dibapi.txt

讲mfc的书

DIBError
Syntax    void DIBError(ErrNo)
          
          This function displays a MessageBox with an error
          message corresponding to the specified error number.
          
          Parameter      Type/Description
          ErrNo          int    Specifies the error message to
                                display.
          
          The error message must be one of the following:
          
          Value          Meaning
          ERR_NOT_DIB  Tried to load a non-DIB file.
          
          ERR_MEMORY   Not enough memory.
          
          ERR_READ     Error reading a file.
          
          ERR_LOCK     Error on a GlobalLock.
          
          ERR_OPEN     Error opening a file.
          
          ERR_CREATEPAL       Error creating a palette.
          
          ERR_GETDC    Error getting a DC.
          
          ERR_CREATEDDB       Error creating a bitmap.
          
          ERR_STRETCHBLT      StretchBlt failed.
          
          ERR_STRETCHDIBITS   StretchDIBits failed.
          
          ERR_SETDIBITSTODEVICE    SetDIBitsToDevice failed.
          
          ERR_STARTDOC Error calling StartDoc.
          
          ERR_NOGDIMODULE     GDI module was not in memory.
                                
          ERR_SETABORTPROC    Error calling SetAbortProc.
          
          ERR_STARTPAGE       Error calling StartPage.
          
          ERR_NEWFRAME Error calling NEWFRAME escape.
          
          ERR_ENDPAGE  Error calling EndPage.
          
          ERR_ENDDOC   Error calling EndDoc.
          
          ERR_SETDIBITS       Error calling SetDIBits.
          
          ERR_FILENOTFOUND    Error opening file in
                                LoadDIBLoadDIB.
          
          ERR_INVALIDHANDLE   Invalid handle.
          
          ERR_DIBFUNCTION     Error on call to DIB function.
          
Return Value   None.


DIBHeight
Syntax    DWORD DIBHeight(lpDIB)
          
          This function gets the height of the specified DIB.
          
          Parameter      Type/Description
          lpDIB          LPSTR  Specifies the DIB.
          
Return Value   The value returned specifies the height of the
          DIB.

Comments  This function requires a pointer to a DIB rather than
          an HDIB.  In order to use this function with an HDIB,
          you must first call the Windows GlobalLock function
          on the HDIB, and pass the resulting pointer to this
          function.


DIBNumColors
Syntax    WORD DIBNumColors(lpDIB)
          
          This function calculates the number of colors in
          color table of the specified DIB specification.
          
          Parameter      Type/Description
          lpDIB          LPSTR  Pointer to a DIB specification.
          
Return Value   The value returned specifies the number of
          colors in the color table.

Comments  This function requires a pointer to a DIB rather than
          an HDIB.  In order to use this function with an HDIB,
          you must first call the Windows GlobalLock function
          on the HDIB, and pass the resulting pointer to this
          function.


DIBToBitmap
Syntax    HBITMAP DIBToBitmap(hDIB, hPal)
          
          This function creates a device-dependent bitmap from
          the specified DIB and palette.
          
          Parameter      Type/Description
          hDIB           HDIB   Specifies the DIB.
          
          hPal           HPALETTE    Specifies the handle to
                                the palette.
          
Return Value   The value returned identifies the device-
          dependent bitmap. 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.

          The bitmap returned from this function is always a
          bitmap compatible with the screen (e.g. same
          bits/pixel and color planes) rather than a bitmap
          with the same attributes as the DIB.  This behavior
          is by design, and occurs because this function calls
          the Windows CreateDIBitmap function to do its work,
          and CreateDIBitmap always creates a bitmap compatible
          with the hDC parameter passed in (because it in turn
          calls the Windows CreateCompatibleBitmap function).
          
          So for instance, if your DIB is a monochrome DIB and
          you call this function, you will not get back a
          monochrome HBITMAP -- you will get an HBITMAP
          compatible with the screen DC, but with only 2 colors
          used in the bitmap.  If your application requires a
          monochrome HBITMAP returned for a monochrome DIB, use
          the Windows function SetDIBits instead.


DIBWidth
Syntax    DWORD DIBWidth(lpDIB)
          
          This function gets the width of the specified DIB.
          
          Parameter      Type/Description
          lpDIB          LPSTR  Specifies the DIB.
          
Return Value   The value returned specifies the width of the
          DIB.

Comments  This function requires a pointer to a DIB rather than
          an HDIB.  In order to use this function with an HDIB,
          you must first call the Windows GlobalLock function
          on the HDIB, and pass the resulting pointer to this
          function.


FindDIBBits
Syntax    LPSTR FindDIBBits(lpDIB)
          
          This function finds and returns a pointer to the
          specified DIB's bits.
          
          Parameter      Type/Description
          lpDIB          LPSTR  Pointer to the DIB
                                specification.
          
Return Value   The value returned is a pointer to the DIB's
          bits.

Comments  This function requires a pointer to a DIB rather than
          an HDIB.  In order to use this function with an HDIB,
          you must first call the Windows GlobalLock function
          on the HDIB, and pass the resulting pointer to this
          function.


GetSystemPalette
Syntax    HPALETTE GetSystemPalette(void)
          
          This function returns a logical palette that
          represents the current system palette.
          
Return Value   The value returned identifies the logical
          palette representing the current system palette.

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


LoadDIB
Syntax    HDIB LoadDIB(lpFileName)
          
          This function loads a DIB from the specified file,
          allocates memory for the DIB, and returns a handle to
          the DIB.
          
          Parameter      Type/Description
          lpFileName     LPSTR  Specifies the complete path
                                name of the DOS filename of
                                the DIB to load.  This
                                function will load files with
                                any extension, but the
                                convention is to name DIB
                                files with a .BMP extension.
          
Return Value   The value returned identifies the deice-
          dependent bitmap if the function is successful.
          Otherwise, it is NULL.

Comments  This function is similar to the Windows LoadBitmap
          function, but there are a few major differences:

          1. The filename passed into this function is the name
          of a Disk-based file rather than a resource in the
          executable.  You can specify a full path name for the
          filename if required.
          
          2. This function will preserve the bitmap's color
          format when it loads the DIB.  For instance, if you
          load a 256-color DIB with this function, the DIB is
          stored in memory as a 256-color DIB.  The Windows
          LoadBitmap function always reduces a DIBs color
          format to the reserved system colors (e.g. for a 256-
          color bitmap on a 256-color display, the LoadBitmap
          function will color-reduce the bitmap to 20 colors).
          
          3. This function returns a HDIB rather than an
          HBITMAP.
          
          The DIB should be deleted using the
          DestroyDIBDestroyDIB function once it is no longer
          needed.


PaintBitmap
Syntax    BOOL PaintBitmap(hDC, lpDCRect, hDDB, lpDDBRect,
                    hPalette)
          
          This function draws the specified bitmap in the given
          DC. The bitmap is output to the DC at the coordinates
          given by lpDCRect. The area of the bitmap to be
          output is given by the lpDDBRect parameter.
          
          Parameter      Type/Description
          hDC            HDC    Specifies the output DC. The
                                bitmap specified by hDDB must
                                be compatible with this DC.
          
          lpDCRect       LPRECT Specifies the destination
                                coordinates of the bitmap
                                being drawn.
          
          hDDB           HBITMAPSpecifies the bitmap.
          
          lpDDBRect      LPRECT Specifies the area of the
                                bitmap to be drawn.
          
          hPalette       HPALETTE    Specifies the palette to
                                be used in drawing the bitmap.
          
Return Value   The value returned is non-zero if successful.
          Otherwise, it is zero.

Comments  Note that the palette is selected and realized as a
          background palette. If a foreground palette is
          needed, it must be selected as foreground and
          realized before calling this function.


PaintDIB
Syntax    BOOL PaintDIB(hDC, lpDCRect, hDIB, lpDIBRect, hPal)
          
          This function draws the specified DIB in the given
          DC. The DIB is output to the DC at the coordinates
          given by lpDCRect. The area of the DIB to be output
          is given by the lpDIBRect parameter.
          
          Parameter      Type/Description
          hDC            HDC    Specifies the output DC. The
                                bitmap specified by hDDB must
                                be compatible with this DC.