home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / dive1.zip / DIVE.H < prev    next >
C/C++ Source or Header  |  1996-07-15  |  18KB  |  379 lines
  1. /***************************************************************************\
  2. *
  3. * Module Name: DIVE.H
  4. *
  5. * OS/2 2.1 Multimedia Extensions Display Engine API data structures
  6. *
  7. * Copyright (c) International Business Machines Corporation 1993, 1994
  8. *                         All Rights Reserved
  9. *
  10. *
  11. \****************************************************************************/
  12. #ifdef __cplusplus
  13.    extern "C" {
  14. #endif
  15.  
  16. #ifndef _DIVE_H_
  17. #define _DIVE_H_
  18.  
  19. #define MAX_DIVE_INSTANCES    64
  20.  
  21. #define FOURCC ULONG
  22. #define HDIVE ULONG
  23.  
  24. #define DIVE_SUCCESS                                     0x00000000
  25. #define DIVE_ERR_INVALID_INSTANCE                        0x00001000
  26. #define DIVE_ERR_SOURCE_FORMAT                           0x00001001
  27. #define DIVE_ERR_DESTINATION_FORMAT                      0x00001002
  28. #define DIVE_ERR_BLITTER_NOT_SETUP                       0x00001003
  29. #define DIVE_ERR_INSUFFICIENT_LENGTH                     0x00001004
  30. #define DIVE_ERR_TOO_MANY_INSTANCES                      0x00001005
  31. #define DIVE_ERR_NO_DIRECT_ACCESS                        0x00001006
  32. #define DIVE_ERR_NOT_BANK_SWITCHED                       0x00001007
  33. #define DIVE_ERR_INVALID_BANK_NUMBER                     0x00001008
  34. #define DIVE_ERR_FB_NOT_ACQUIRED                         0x00001009
  35. #define DIVE_ERR_FB_ALREADY_ACQUIRED                     0x0000100a
  36. #define DIVE_ERR_ACQUIRE_FAILED                          0x0000100b
  37. #define DIVE_ERR_BANK_SWITCH_FAILED                      0x0000100c
  38. #define DIVE_ERR_DEACQUIRE_FAILED                        0x0000100d
  39. #define DIVE_ERR_INVALID_PALETTE                         0x0000100e
  40. #define DIVE_ERR_INVALID_DESTINATION_RECTL               0x0000100f
  41. #define DIVE_ERR_INVALID_BUFFER_NUMBER                   0x00001010
  42. #define DIVE_ERR_SSMDD_NOT_INSTALLED                     0x00001011
  43. #define DIVE_ERR_BUFFER_ALREADY_ACCESSED                 0x00001012
  44. #define DIVE_ERR_BUFFER_NOT_ACCESSED                     0x00001013
  45. #define DIVE_ERR_TOO_MANY_BUFFERS                        0x00001014
  46. #define DIVE_ERR_ALLOCATION_ERROR                        0x00001015
  47. #define DIVE_ERR_INVALID_LINESIZE                        0x00001016
  48. #define DIVE_ERR_FATAL_EXCEPTION                         0x00001017
  49. #define DIVE_ERR_INVALID_CONVERSION                      0x00001018
  50. #define DIVE_ERR_VSD_ERROR                               0x00001019
  51. #define DIVE_ERR_COLOR_SUPPORT                           0x0000101a
  52. #define DIVE_ERR_OUT_OF_RANGE                            0x0000101b
  53. #define DIVE_WARN_NO_SIZE                                0x00001100
  54.  
  55. #define DIVE_BUFFER_SCREEN                               0x00000000
  56. #define DIVE_BUFFER_GRAPHICS_PLANE                       0x00000001
  57. #define DIVE_BUFFER_ALTERNATE_PLANE                      0x00000002
  58.  
  59. #define DIVE_FULLY_VISIBLE                               0xffffffff
  60.  
  61.  
  62. /* Notes:
  63.       Associated/Allocated memory buffers start at:      0x00000010
  64.  
  65.       Specifing DIVE_BUFFER_GRAPHICS_PLANE results in the image being
  66.             transferred to the graphics plane.
  67.       Specifing DIVE_BUFFER_ALTERNATE_PLANE results in the image being
  68.             transferred to the alternate (e.g. overlay) plane.  If your
  69.             hardware doesn't support such a plane, this is an error.
  70.       Specifing DIVE_BUFFER_SCREEN will result in the image being
  71.             transferred to either the graphics plane buffer or the alternate
  72.             plane buffer based on if an alternate buffer exists and based on
  73.             the suitability the overlay plane to accelerate the scaling of
  74.             the image.  If DIVE chooses to use the alternate buffer, it
  75.             will also paint the overlay "key" color on the graphics plane.
  76.             This automatic painting does not occur if the alternate plane
  77.             is explicitly specified.
  78. */
  79.  
  80.  
  81.  
  82. typedef struct _DIVE_CAPS {
  83.  
  84.    ULONG  ulStructLen;            /* Set equal to sizeof(DIVE_CAPS)          */
  85.    ULONG  ulPlaneCount;           /* Number of defined planes.               */
  86.  
  87.    /* Info returned in the following fields pertains to ulPlaneID.           */
  88.    BOOL   fScreenDirect;          /* TRUE if can get addressability to vram. */
  89.    BOOL   fBankSwitched;          /* TRUE if vram is bank-switched.          */
  90.    ULONG  ulDepth;                /* Number of bits per pixel.               */
  91.    ULONG  ulHorizontalResolution; /* Screen width in pixels.                 */
  92.    ULONG  ulVerticalResolution;   /* Screen height in pixels.                */
  93.    ULONG  ulScanLineBytes;        /* Screen scan line size in bytes.         */
  94.    FOURCC fccColorEncoding;       /* Colorspace encoding of the screen.      */
  95.    ULONG  ulApertureSize;         /* Size of vram aperture in bytes.         */
  96.  
  97.    ULONG  ulInputFormats;         /* Number of input color formats.          */
  98.    ULONG  ulOutputFormats;        /* Number of output color formats.         */
  99.    ULONG  ulFormatLength;         /* Length of format buffer.                */
  100.    PVOID  pFormatData;            /* Pointer to color format buffer FOURCC's.*/
  101.  
  102.    } DIVE_CAPS;
  103. typedef DIVE_CAPS *PDIVE_CAPS;
  104.  
  105.  
  106.  
  107.  
  108. typedef struct _SETUP_BLITTER {
  109.  
  110.      /* Set the ulStructLen field equal to the amount of the structure used. */
  111.      /* allowable: blank lines below mark sizes of 8, 28, 32, 52, 60, or 68. */
  112.    ULONG  ulStructLen;
  113.      /* Set the ulInvert flags based on the following:                       */
  114.      /* b0001 = d01 = h01 = flip the image in the horizontal direction.      */
  115.      /* b0010 = d02 = h02 = flip the image in the vertical direction.        */
  116.    ULONG  fInvert;
  117.  
  118.      /* This is the color format of the source data.  See "FOURCC.H"         */
  119.    FOURCC fccSrcColorFormat;
  120.      /* This is the width of the source image in pixels.                     */
  121.    ULONG  ulSrcWidth;
  122.      /* This is the height of the source image in pixels.                    */
  123.    ULONG  ulSrcHeight;
  124.      /* This is the horizontal offset from which to start displaying for     */
  125.      /* use in displaying a sub-portion of the source image.                 */
  126.    ULONG  ulSrcPosX;
  127.      /* This is the vertical offset from which to start displaying.          */
  128.    ULONG  ulSrcPosY;
  129.  
  130.      /* This is the dither type to use.  0 defines no dither and 1           */
  131.      /* defines 2x2 dither (all others ignored).  Note: dithering is only    */
  132.      /* supported in direct color to LUT8 conversions.                       */
  133.    ULONG  ulDitherType;
  134.  
  135.      /* This is the color format of the destinaion data.  See "FOURCC.H"     */
  136.    FOURCC fccDstColorFormat;
  137.      /* This is the width of the destination image in pixels.                */
  138.    ULONG  ulDstWidth;
  139.      /* This is the height of the destination image in pixels.               */
  140.    ULONG  ulDstHeight;
  141.      /* This is the horizontal offset from which to start displaying for     */
  142.      /* use in displaying to sub-portion of the destination image.           */
  143.    LONG   lDstPosX;
  144.      /* This is the vertical offset from which to start displaying.          */
  145.    LONG   lDstPosY;
  146.  
  147.      /* This is the world screen horizontal position, where 0 is left.       */
  148.      /* These are ignored if the destination is not the screen.              */
  149.    LONG   lScreenPosX;
  150.      /* This is the world screen vertical position, where 0 is bottom.       */
  151.    LONG   lScreenPosY;
  152.  
  153.      /* This is the number of visible rectangular regions being passed in.   */
  154.      /* These are ignored if the destination is not the screen.              */
  155.      /* Also, if you application *KNOWS* that the region is fully visible    */
  156.      /* (like not going to the screen), the you can use DIVE_FULLY_VISIBLE   */
  157.      /* instead of making up a bogus visible region structure.               */
  158.    ULONG  ulNumDstRects;
  159.      /* This points to an array of visible regions which defines what        */
  160.      /* portions of the source image are to be displayed.                    */
  161.    PRECTL pVisDstRects;           /* Pointer to array of visible rectangles. */
  162.  
  163.    } SETUP_BLITTER;
  164. typedef SETUP_BLITTER *PSETUP_BLITTER;
  165.  
  166.  
  167.  
  168. ULONG APIENTRY DiveQueryCaps ( PDIVE_CAPS pDiveCaps,
  169.                                ULONG      ulPlaneBufNum );
  170.  
  171. ULONG APIENTRY DiveOpen ( HDIVE *phDiveInst,
  172.                           BOOL   fNonScreenInstance,
  173.                           PVOID  ppFrameBuffer );
  174.  
  175. ULONG APIENTRY DiveSetupBlitter ( HDIVE          hDiveInst,
  176.                                   PSETUP_BLITTER pSetupBlitter );
  177.  
  178. ULONG APIENTRY DiveBlitImage ( HDIVE hDiveInst,
  179.                                ULONG ulSrcBufNumber,
  180.                                ULONG ulDstBufNumber );
  181.  
  182. /* Same as DiveBlitImage, except pbLineMask points to one byte per line      */
  183. /* in source image buffer such that 0: unchanged, 0xFF: changed              */
  184. ULONG APIENTRY DiveBlitImageLines ( HDIVE hDiveInst,
  185.                                     ULONG ulSrcBufNumber,
  186.                                     ULONG ulDstBufNumber,
  187.                                     PBYTE pbLineMask );
  188.  
  189. ULONG APIENTRY DiveClose ( HDIVE hDiveInst );
  190.  
  191. ULONG APIENTRY DiveAcquireFrameBuffer ( HDIVE   hDiveInst,
  192.                                         PRECTL  prectlDst );
  193.  
  194. ULONG APIENTRY DiveSwitchBank ( HDIVE hDiveInst,
  195.                                 ULONG ulBankNumber );
  196.  
  197. ULONG APIENTRY DiveDeacquireFrameBuffer ( HDIVE hDiveInst );
  198.  
  199. ULONG APIENTRY DiveCalcFrameBufferAddress ( HDIVE  hDiveInst,
  200.                                             PRECTL prectlDest,
  201.                                             PBYTE *ppDestinationAddress,
  202.                                             PULONG pulBankNumber,
  203.                                             PULONG pulRemLinesInBank );
  204.  
  205. /* Notes on DiveAllocImageBuffer:
  206.       If pbImageBuffer is not NULL, the buffer is associated rather than
  207.       allocated.  If pbImageBuffer is not NULL and the buffer number
  208.       pointed to by pulBufferNumber is non-zero, a new buffer pointer is
  209.       associated with the buffer number.  Even though no memory is
  210.       allocated by DiveAllocImageBuffer when user-allocated buffers are
  211.       associated, DiveFreeImageBuffer should be called to release the
  212.       buffer association to avoid using up available buffer indexes.
  213.       The specified line size will be used if a buffer is allocated in
  214.       system memory, or if a user buffer is associated.  If the
  215.       specified line size is zero, the allocated line size is rounded up
  216.       to the nearest DWORD boundry.
  217. */
  218.  
  219. ULONG APIENTRY DiveAllocImageBuffer ( HDIVE  hDiveInst,
  220.                                       PULONG pulBufferNumber,
  221.                                       FOURCC fccColorSpace,
  222.                                       ULONG  ulWidth,
  223.                                       ULONG  ulHeight,
  224.                                       ULONG  ulLineSizeBytes,
  225.                                       PBYTE  pbImageBuffer );
  226.  
  227. ULONG APIENTRY DiveFreeImageBuffer ( HDIVE hDiveInst,
  228.                                      ULONG ulBufferNumber );
  229.  
  230. ULONG APIENTRY DiveBeginImageBufferAccess ( HDIVE  hDiveInst,
  231.                                             ULONG  ulBufferNumber,
  232.                                             PBYTE *ppbImageBuffer,
  233.                                             PULONG pulBufferScanLineBytes,
  234.                                             PULONG pulBufferScanLines );
  235.  
  236. ULONG APIENTRY DiveEndImageBufferAccess ( HDIVE hDiveInst,
  237.                                           ULONG ulBufferNumber );
  238.  
  239.  
  240.  
  241. /* Notes on palettes:
  242.       Neither DiveSetSourcePalette nor DiveSetDestinationPalette API's will set
  243.       the physical palette.  If your application MUST set the PHYSICAL palette,
  244.       try using no more than 236 entries (the middle 236: 10-245, thus leaving
  245.       the top and bottom 10 entries for the Workplace Shell).  If your
  246.       application MUST use ALL 256 entries, it must do so as a full-screen
  247.       (i.e. maximized) application.  Remember, No WM_REALIZEPALETTE message
  248.       will be sent to other running applications, meaning they will not redraw
  249.       and their colors will be all wrong.  It is not recommended that a
  250.       developer use these commands:
  251.  
  252.    To set physical palette, do the following:
  253.             hps = WinGetPS ( HWND_DESKTOP );
  254.             hdc = GpiQueryDevice ( hps );
  255.             GpiCreateLogColorTable ( hps, LCOL_PURECOLOR | LCOL_REALIZABLE,
  256.                            LCOLF_CONSECRGB, 0, 256, (PLONG)plRGB2Entries );
  257.             Gre32EntrY3 ( hdc, 0L, 0x000060C6L );
  258.             WinInvalidateRect ( HWND_DESKTOP, (PRECTL)NULL, TRUE );
  259.             WinReleasePS ( hps );
  260.  
  261.    To reset physical palette, do the following:
  262.             hps = WinGetPS ( HWND_DESKTOP );
  263.             hdc = GpiQueryDevice ( hps );
  264.             Gre32EntrY3 ( hdc, 0L, 0x000060C7L );
  265.             WinInvalidateRect ( HWND_DESKTOP, (PRECTL)NULL, TRUE );
  266.             WinReleasePS ( hps );
  267. */
  268.  
  269.  
  270. /* Use either of the two defines as the pRGB2Entries pointer to have DIVE    */
  271. /* query and set the physical or default palette as source or destination.   */
  272.  
  273. #define DIVE_PALETTE_PHYSICAL                     (PBYTE)0x00000000
  274. #define DIVE_PALETTE_DEFAULT                      (PBYTE)0xffffffff
  275.  
  276. ULONG APIENTRY DiveSetDestinationPalette ( HDIVE hDiveInst,
  277.                                            ULONG ulStartIndex,
  278.                                            ULONG ulNumEntries,
  279.                                            PBYTE pbRGB2Entries );
  280.  
  281. ULONG APIENTRY DiveSetSourcePalette ( HDIVE hDiveInst,
  282.                                       ULONG ulStartIndex,
  283.                                       ULONG ulNumEntries,
  284.                                       PBYTE pbRGB2Entries );
  285.  
  286. ULONG APIENTRY DiveSetTransparentBlitMode ( HDIVE hDiveInst,
  287.                                             ULONG ulTransBlitMode,
  288.                                             ULONG ulValue1,
  289.                                             ULONG ulValue2 );
  290.  
  291. /* The following transparent blitting modes are supported:                   */
  292.  
  293. #define DIVE_TBM_NONE                              0x0
  294. /* No transparency, i.e. all pixels are transferred (default)                */
  295.  
  296. #define DIVE_TBM_EXCLUDE_SOURCE_VALUE              0x01
  297. /* Source pixels with values that exactly match the value specified in       */
  298. /* ulValue1 are not transferred.                                             */
  299.  
  300. #define DIVE_TBM_EXCLUDE_SOURCE_RGB_RANGE          0x02
  301. /* Source pixels with values that lie within the range specified in RGB      */
  302. /* color space specified by ulValue1 (minimum) and ulValue2 (maximum)        */
  303. /* are not transferred by DiveBlitImage.                                     */
  304.  
  305. #define DIVE_TBM_INCLUDE_SOURCE_RGB_RANGE          0x03
  306. /* Source pixels with values that lie outside the range specified in RGB     */
  307. /* color space specified by ulValue1 (minimum) and ulValue2 (maximum)        */
  308. /* are not transferred by DiveBlitImage.                                     */
  309.  
  310. #define DIVE_TBM_EXCLUDE_SOURCE_YUV_RANGE          0x04
  311. /* Source pixels with values that lie within the range specified in RGB      */
  312. /* color space specified by ulValue1 (minimum) and ulValue2 (maximum)        */
  313. /* are not transferred by DiveBlitImage.                                     */
  314.  
  315. #define DIVE_TBM_INCLUDE_SOURCE_YUV_RANGE          0x05
  316. /* Source pixels with values that lie outside the range specified in RGB     */
  317. /* color space specified by ulValue1 (minimum) and ulValue2 (maximum)        */
  318. /* are not transferred by DiveBlitImage.                                     */
  319.  
  320. /* Notes on transparent blitting:
  321.    Supported transparent blitting functions are all based on source pixel
  322.    values.  A pixel in the destination image buffer is not modified if the
  323.    corresponding pixel in the source buffer is "transparent".  The color
  324.    values or color value ranges specified in ulValue1 and ulValue2 are
  325.    dependent on the source image color format (fccSrcColorFormat) and the
  326.    color space in which the range comparison is taking place.
  327.  
  328.    FOURCC_LUT8:
  329.       The color value is specified in the low 8 bits of parameter
  330.  
  331.    FOURCC_Y888, FOURCC_Y2X2, FOURCC_Y4X4, FOURCC_YUV9, FOURCC_Y644, FOURCC_Y422:
  332.       23:8 - Y, 15:8 - U, 7:8 - V  (bits 31:8 ignored)
  333.  
  334.    FOURCC_R565, FOURCC_R555, FOURCC_R664, FOURCC_RGB3, FOURCC_BGR3, FOURCC_RGB4,
  335.    FOURCC_BGR4:
  336.       23:8 - R, 15:8 - G, 7:8 - B  (bits 31:8 ignored)
  337.       R, G, and B components are specified with 8 bit significance, regardless
  338.       of significance in the source data.
  339.  
  340.    Transparent blitting of other source image formats is not supported.
  341.  
  342.    For range comparisons in RGB or YUV, the three components are compared
  343.    independently against the minimum and maximum values specified by the
  344.    ulValue1 and ulValue2 parameters respectively.  A value is considered to
  345.    within the specified range if all three components satisfy:
  346.    min <= value <= max.
  347.  
  348.    For EXCLUDE_SOURCE_VALUE tranparent blitting, the specified value in
  349.    ulValue1 is assumed to be in the source color space as described above.
  350.    For range comparisons, the values specified in ulValue1 and ulValue2 are
  351.    assumed to be in the color space in which the range comparison is to be
  352.    performed, either YUV or RGB.
  353.  
  354.    - For range comparisons in YUV where the source data format is a YUV
  355.      form, the values in ulValue1 and ulValue2 are in the source YUV
  356.      format.
  357.  
  358.    - For range comparisons in YUV where the source data format is RGB,
  359.      conversion of source data format from RGB to YUV using standard
  360.      CCIR601 equations is assumed (refer to fourcc.h).
  361.  
  362.    - For range comparisons in RGB where the source data format is an RGB
  363.      form, the values in ulValue1 and ulValue2 specify the RGB range with
  364.      5 bits significance in R, 6 bits in G, and 5 bits in B.
  365.  
  366.    - For range comparisons in RGB where the source data format is YUV,
  367.      conversion of source data format from YUV to RGB using standard
  368.      CCIR601 equations is assumed (refer to fourcc.h).
  369.  
  370.  
  371.  
  372. */
  373.  
  374. #endif
  375. #ifdef __cplusplus
  376. }
  377. #endif
  378.  
  379.