dibapi.txt

讲mfc的书

         DIB Screen Capture/Printing API Specification
                By Pat Schreiber and Mark Bader
                 Version dated March 27, 1992

The following document contains descriptions of the functions
defined in the DIBAPI dynamic-linked library.  This DLL
demonstrates using the Windows Device-Independent Bitmap (DIB)
functions to capture the screen, print bitmaps, convert between
bitmap formats, and to display DIBs.

The DIBAPI DLL is a component of the WINCAP sample program,
available in the Microsoft Software Library as WINCAP.ZIP.
This sample program demonstrates using these APIs.

To use these APIs in your own program, first compile the
DIBAPI.DLL using the DIBAPI.MAK make file.  Then, in your
program, simply include the DIBAPI.H header file, and link with
the DIBAPI.LIB import library (and make sure DIBAPI.DLL is in
your path).

-Mark & Pat

===============================================================
BitmapToDIB
Syntax    HDIB BitmapToDIB(hBitmap, hPal)
          
          This function creates a device-independent bitmap
          (DIB) from a device-dependent bitmap using the
          specified palette.  The DIB format is the same as the
          hBitmap parameter.
          
          Parameter      Type/Description
          hBitmap        HBITMAPSpecifies the handle to the
                                bitmap to convert.
          
          hPal           HPALETTE    Specifies the handle to
                                the palette associated with
                                the bitmap.
          
Return Value   The value returned identifies the device-
          independent bitmap if the function is successful.
          Otherwise, it is NULL.

Comments  The bitmap and palette remain intact after calling
          this function. They should be deleted using the
          Windows DeleteObject function once they are no longer
          needed.


ChangeBitmapFormat
Syntax    HDIB ChangeBitmapFormat(hBitmap, wBitCount,
                    dwCompression, hPal)
          
          This function converts a bitmap to a DIB of the
          specified bits per pixel and compression format using
          the specified palette.
          
          Parameter      Type/Description
          hBitmap        HBITMAPSpecifies the handle to the
                                bitmap.
          
          wBitCount      WORD   Specifies the desired bits per
                                pixel.
          
          dwCompression  DWORD  Specifies the desired
                                compression format. Must be
                                one of the following:
                                BI_RGB, BI_RLE4, or BI_RLE8.
          
          hPal           HPALETTE    Specifies the handle to
                                the palette associated with
                                the bitmap.
          
Return Value   The value returned identifies the device-
          dependent bitmap if the function is successful.
          Otherwise, it is NULL.

Comments  The bitmap and palette remain intact after calling
          this function. They should be deleted using the
          Windows DeleteObject function once they are no longer
          needed.


ChangeDIBFormat
Syntax    HDIB ChangeDIBFormat(hDIB, wBitCount, dwCompression)
          
          This function changes the bits per pixel and
          compression format of the given DIB to those
          specified by the wBitCount and dwCompression.
          
          Parameter      Type/Description
          hBitmap        HBITMAPSpecifies the handle to the
                                bitmap.
          
          wBitCount      WORD   Specifies the desired bits per
                                pixel.
          
          dwCompression  DWORD  Specifies the desired
                                compression format. Must be
                                one of the following:
                                BI_RGB, BI_RLE4, or BI_RLE8.
          
          hPal           HPALETTE    Specifies the handle to
                                the palette associated with
                                the bitmap.
          
Return Value   The value returned identifies the device-
          dependent bitmap if the function is successful.
          Otherwise, it is NULL.

Comments  The original DIB is left intact after calling this
          function. It should be deleted using
          DestroyDIBDestroyDIB once it is no longer needed.


CopyScreenToBitmap
Syntax    HBITMAP CopyScreenToBitmap(lpRect)
          
          This function copies the specified part of the screen
          to a device-dependent bitmap.
          
          Parameter      Type/Description
          lpRect         LPRECT Pointer to a RECT data
                                structure that contains the
                                rectangle to be copied.
          
Return Value   The value returned identifies the deice-
          dependent bitmap if the function is successful.
          Otherwise, it is NULL.

Comments  The bitmap should be deleted using the Windows
          DeleteObject function once it is no longer needed.


CopyScreenToDIB
Syntax    HDIB CopyScreenToDIB(lpRect)
          
          This function copies the specified part of the screen
          to a device-independent bitmap.
          
          Parameter      Type/Description
          lpRect         LPRECT Pointer to a RECT data
                                structure that contains the
                                rectangle to be copied.
          
Return Value   The value returned identifies the device-
          independent bitmap if the function is successful.
          Otherwise, it is NULL.

Comments  The DIB should be deleted using the
          DestroyDIBDestroyDIB function once it is no longer
          needed.


CopyWindowToBitmap
Syntax    HBITMAP CopyWindowToBitmap(hWnd, fPrintArea)
          
          This function copies the specified part of  the
          window to a device-dependent bitmap.
          
          Parameter      Type/Description
          hWnd           HWND   Specifies the window.
          
          fPrintArea     WORD   Specifies the window area(s) to
                                copy into the device-
                                independent bitmap.
          
          The fPrintArea parameter must be one of the
                                following:
          
          Value          Meaning
          PW_WINDOW      Copy the entire window.
          
          PW_CLIENT      Copy only the client area of the given
                                window.
          
Return Value   The value returned identifies the device-
          dependent bitmap if the function is successful.
          Otherwise, it is NULL.

Comments  The bitmap should be deleted using the Windows
          DeleteObject function once it is no longer needed.


CopyWindowToDIB
Syntax    HDIB CopyWindowToDIB(hWnd, fPrintArea)
          
          This function copies the specified part of the window
          to a device-independent bitmap.
          
          Parameter      Type/Description
          hWnd           HWND   Specifies the window.
          
          fPrintArea     WORD   Specifies the window area(s) to
                                copy into the device-
                                independent bitmap.
          
          The fPrintArea parameter must be one of the
                                following:
          
          Value          Meaning
          PW_WINDOW      Copy the entire window.
          
          PW_CLIENT      Copy only the client area of the given
                                window.
          
          
Return Value   The value returned identifies the device-
          independent bitmap if the function is successful.
          Otherwise, it is NULL.

Comments  The DIB should be deleted using the
          DestroyDIBDestroyDIB function once it is no longer
          needed.


CreateDIBPalette
Syntax    HPALETTE CreateDIBPalette(hDIB)
          
          This function creates a logical palette from the
          color table of the specified DIB.
          
          Parameter      Type/Description
          hDIB           HDIB   Specifies the handle to the
                                DIB.
          
Return Value   The value returned identifies the logical
          palette corresponding to the DIB's color table.
          Otherwise, it is NULL.

Comments  The palette should be deleted using the Windows
          DeleteObject function once it is no longer needed.


CreateDIB
Syntax    HDIB CreateDIB(dwWidth, dwHeight, wBitCount)
          
          This function allocates memory for and initializes a
          new DIB by filling in the BITMAPINFOHEADER,
          allocating memory for the color table, and allocating
          memory for the bitmap bits. The color table and
          bitmap bits are all set to zeros.  As with all HDIBs,
          the header, color table, and bits are all in one
          contiguous memory block. This function is similar to
          the Windows CreateBitmap function.
          
          Parameter      Type/Description
          dwWidth        DWORD  Specifies the width of the new
                                DIB in pixels.
          
          dwHeight       DWORD  Specifies the height of the new
                                DIB in pixels.
          
          wBitCount      WORD   Specifies the bits per pixel of
                                the new DIB. This must be one
                                of the following: 1, 4, 8, or
                                24.
          
Return Value   The value returned identifies the new DIB.
          Otherwise, it is NULL.

Comments  The DIB should be deleted using the
          DestroyDIBDestroyDIB function once it is no longer
          needed.


DestroyDIB
Syntax    WORD DestroyDIB(hDib)
          
          This function destroys the specified DIB, deleting
          any memory associated with the DIB.  The handle to
          the DIB is invalid after calling this function.
          
          Parameter      Type/Description
          hDib           HDIB   Specifies the handle to the DIB
                                to destroy.
          
Return Value   The value returned is zero for success.