gdi.h

usoc在北京博创兴业有限公司的实验平台s3c2410上运行。 2. 各实验的全部源代码分别存放在各实验目录下面。

     * like \a GetClientDC or \a CreateCompatibleDC to get or create a
     * DC, then call GDI functions to draw objects, e.g. \a MoveTo and \a LineTo.
     * After finishing drawing, you should call \a ReleaseDC or \a DeleteMemDC function
     * to release or destroy the DC.
     *
     * MiniGUI reserved an global DC called \a HDC_SCREEN. You can
     * use this DC directly without getting/creating or releasing/destroying.
     *
     * For main windows or controls, MiniGUI will send a MSG_PAINT message to
     * the window when the whole or part of window area have been invalidated. 
     * You should call \a BegainPaint function to get the DC, then repaint the window, 
     * and call \a EndPaint function to release the DC at the last.
     *
     * Example:
     *
     * \include msg_paint.c
     *
     * @{
     */

/**
 * \def HDC_SCREEN
 * \brief Handle to the device context of the whole screen.
 *
 * This DC is a special one. MiniGUI uses it to draw popup menus and other global
 * objects. You can also use this DC to draw lines or text on the screen 
 * directly, and there is no need to get or release it.
 *
 * If you do not want to create any main window, but you want to draw on
 * the screen, you can use this DC.
 *
 * \note MiniGUI does not do any clipping operation for this DC, so use this DC 
 * may make a mess of other windows. 
 */
#define HDC_SCREEN          0

/**
 * \def HDC_INVALID
 * \brief Indicates an invalid handle to device context.
 */
#define HDC_INVALID         0

#define GDCAP_COLORNUM      0
#define GDCAP_HPIXEL        1
#define GDCAP_VPIXEL        2
#define GDCAP_MAXX          3
#define GDCAP_MAXY          4
#define GDCAP_DEPTH         5
#define GDCAP_BPP           6

/**
 * \fn unsigned int GUIAPI GetGDCapability (HDC hdc, int iItem)
 * \brief Returns a capability of a DC.
 *
 * This function returns the capability of the specified item \a iItem of the DC \a hdc.
 *
 * \param hdc The handle to the DC.
 * \param iItem An integer presents the capablity, can be one of the following values:
 *
 *  - GDCAP_COLORNUM\n
 *    Tell \a GetGDCapability to return the colors number of the DC. Note the for a DC
 *    with 32-bit depth, the function will return 0xFFFFFFFF, not 0x100000000.
 *  - GDCAP_HPIXEL\n
 *    Tell \a GetGCapability to return the horizontal resolution of the DC.
 *  - GDCAP_VPIXEL\n
 *    Tell \a GetGDCapability to return the vertical resolution of the DC.
 *  - GDCAP_MAXX\n
 *    Tell \a GetGDCapability to return the maximal visible x value of the DC.
 *  - GDCAP_MAXY\n
 *    Tell \a GetGDCapability to return the maximal visible y value of the DC.
 *  - GDCAP_DEPTH\n
 *    Tell \a GetGDCapability to return the color depth of the DC. The returned value can be 
 *    1, 4, 8, 15, 16, 24, or 32.
 *  - GDCAP_BPP\n
 *    Tell \a GetGDCapability to return the bytes number for storing a pixle in the DC.
 *
 * \return The capbility.
 */
unsigned int GUIAPI GetGDCapability (HDC hdc, int iItem);

/**
 * \fn HDC GUIAPI GetDC (HWND hwnd)
 * \brief Gets a window DC of a window.
 *
 * This function gets a window DC of the specified \a hwnd, and returns the handle to the DC.
 * MiniGUI will try to return an unused DC from the internal DC pool, rather than
 * allocate a new one from the system heap. Thus, you should release the DC when
 * you finish drawing as soon as possible.
 *
 * \param hwnd The handle to the window.
 * \return The handle to the DC, HDC_INVALID indicates an error.
 *
 * \note You should call \a ReleaseDC to release the DC when you are done.
 *
 * \sa GetClientDC, ReleaseDC
 */
HDC GUIAPI GetDC (HWND hwnd);

/**
 * \fn HDC GUIAPI GetClientDC (HWND hwnd)
 * \brief Gets a client DC of a window.
 *
 * This function gets a client DC of the specified \a hwnd, and returns the handle to the DC.
 * MiniGUI will try to return an unused DC from the internal DC pool, rather than
 * allocate a new one from the system heap. Thus, you should release the DC when
 * you finish drawing as soon as possible.
 *
 * \param hwnd The handle to the window.
 * \return The handle to the DC, HDC_INVALID indicates an error.
 *
 * \note You should call \a ReleaseDC to release the DC when you are done.
 *
 * \sa GetDC, ReleaseDC
 */
HDC GUIAPI GetClientDC (HWND hwnd);

/**
 * \fn void GUIAPI ReleaseDC (HDC hdc)
 * \brief Releases a DC from DC pool.
 *
 * This function releases the DC returned by \a GetDC or \a GetClientDC.
 *
 * \param hdc The handle to the DC.
 *
 * \sa GetDC, GetClientDC 
 */
void GUIAPI ReleaseDC (HDC hdc);

/**
 * \fn HDC GUIAPI CreatePrivateDC (HWND hwnd)
 * \brief Creates a private window DC of a window.
 *
 * This function creates a private window DC of the window \a hwnd and returns the handle to the DC.
 *
 * When you calling \a CreatePrivateDC function to create a private DC, MiniGUI will create 
 * the DC in the system heap, rather than allocate one from the DC pool. Thus, you can 
 * keep up the private DC in the life cycle of the window, and are not needed to release it for 
 * using by other windows.
 *
 * \param hwnd The handle to the window.
 * \return The handle to the DC, HDC_INVALID indicates an error.
 *
 * \sa DeletePrivateDC
 */
HDC GUIAPI CreatePrivateDC (HWND hwnd);

/**
 * \fn HDC GUIAPI CreatePrivateClientDC (HWND hwnd)
 * \brief Creates a private client DC of a window.
 *
 * This function creates a private client DC of the window \a hwnd 
 * and returns the handle to the DC.
 *
 * When you calling \a CreatePrivateClientDC function to create a private client DC, 
 * MiniGUI will create the DC in the system heap, rather than allocate one from the DC pool. 
 * Thus, you can keep up the DC in the life cycle of the window, and are not needed to release 
 * it for using by other windows.
 *
 * \param hwnd The handle to the window.
 * \return The handle to the DC, HDC_INVALID indicates an error.
 *
 * \sa DeletePrivateDC
 */
HDC GUIAPI CreatePrivateClientDC (HWND hwnd);

/**
 * \fn HDC GUIAPI GetPrivateClientDC (HWND hwnd)
 * \brief Returns the private client DC of a window.
 *
 * This function returns the private client DC of the window \a hwnd which 
 * have extended style \a WS_EX_USEPRIVATECDC.
 *
 * When a main window have the extended style \a WS_EX_USEPRIVATECDC, or a
 * control class have the style \a CS_OWNDC, MiniGUI will create a private client DC 
 * for this window in the creation progress of the window, and destroy the DC when you 
 * destroy the window, and use this private client DC in default message handlers. 
 * So there will be some improvments on drawing/repaint performance.
 * You can alos call this function to get the private client DC, and use it to
 * draw anything in your window.
 *
 * \param hwnd The handle to the window.
 * \return The handle to the private client DC, HDC_INVALID indicates an error.
 *
 * \sa CreatePrivateClientDC
 */
HDC GUIAPI GetPrivateClientDC (HWND hwnd);

/**
 * \fn void GUIAPI DeletePrivateDC (HDC hdc)
 * \brief Deletes the DC returned by \a CreatePrivateDC or \a CreatePrivateClientDC.
 *
 * \param hdc The handle to the DC.
 *
 * \sa CreatePrivateDC, CreatePrivateClientDC
 */
void GUIAPI DeletePrivateDC (HDC hdc);

#ifdef _USE_NEWGAL

#define MEMDC_FLAG_NONE         0x00000000          /* None. */
#define MEMDC_FLAG_SWSURFACE    0x00000000          /* DC is in system memory */
#define MEMDC_FLAG_HWSURFACE    0x00000001          /* DC is in video memory */
#define MEMDC_FLAG_SRCCOLORKEY  0x00001000          /* Blit uses a source color key */
#define MEMDC_FLAG_SRCALPHA     0x00010000          /* Blit uses source alpha blending */
#define MEMDC_FLAG_RLEACCEL     0x00004000          /* Surface is RLE encoded */

/**
 * \fn HDC GUIAPI CreateCompatibleDCEx (HDC hdc, int width, int height)
 * \brief Creates a memory DC which is compatible with the specified reference DC.
 *
 * This function creates a memory DC which have the same pixel format
 * as the specified reference DC \a hdc. The same pixel format means that the memory DC will have
 * the same pixel depth, the same RGB composition, or the same palette as the reference DC.
 *
 * \param hdc The handle to the reference DC.
 * \param width The expected width of the result memory DC. If it is zero, the width will
 *        be equal to the width of the reference DC.
 * \param height The expected height of the result memory DC. If it is zero, the height will
 *        be equal to the height of the reference DC.
 * \return The handle to the memory DC, HDC_INVALID indicates an error.
 *
 * \note Only defined for _USE_NEWGAL.
 *
 * \sa CreateCompatibleDC
 */
HDC GUIAPI CreateCompatibleDCEx (HDC hdc, int width, int height);

/**
 * \fn HDC GUIAPI CreateMemDC (int width, int height, int depth, DWORD flags, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)
 * \brief Creates a memory DC.
 *
 * This function creates a memory DC which have the specified flags and pixel format.
 *
 * \param width The expected width of the result memory DC.
 * \param height The expected height of the result memory DC.
 * \param depth The expected color depth of the memory DC.
 * \param flags The memory DC flags, can be or'ed values of the following flags:
 *
 *   - MEMDC_FLAG_SWSURFACE\n
 *     Creates the surface of memory DC in the system memory.
 *   - MEMDC_FLAG_HWSURFACE\n
 *     Creates the surface of memory DC in the video memory.
 *   - MEMDC_FLAG_SRCCOLORKEY\n
 *     The created memory DC will use a source color key to blit to other DC.
 *   - MEMDC_FLAG_SRCALPHA\n
 *     The created memory DC will use a source alpha blending to blit to other DC.
 *   - MEMDC_FLAG_RLEACCEL\n
 *     The memory DC will be RLE encoded
 *
 * \param Rmask The bit-masks of the red components in a pixel value.
 * \param Gmask The bit-masks of the green components in a pixel value.
 * \param Bmask The bit-masks of the blue components in a pixel value.
 * \param Amask The bit-masks of the alpha components in a pixel value.
 * \return The handle to the memory DC, HDC_INVALID indicates an error.
 *
 * \note Only defined for _USE_NEWGAL.
 *
 * \sa CreateMemDCFromBitmap, CreateMemDCFromMyBitmap, CreateCompatibleDCEx
 */
HDC GUIAPI CreateMemDC (int width, int height, int depth, DWORD flags,
                Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);

/**
 * \fn HDC GUIAPI CreateMemDCFromBitmap (HDC hdc, BITMAP* bmp)
 * \brief Creates a memory DC from a reference DC and a BITMAP object.
 *
 * This function creates a memory DC compatible with the 
 * specified DC, and use the bits of the BITMAP object as the surface of 
 * the memory DC. The created memory DC will have the same geometry as the
 * BITMAP object.
 *
 * \param hdc The reference DC.
 * \param bmp The BITMAP object.
 * \return The handle to the memory DC, HDC_INVALID indicates an error.
 *
 * \note Only defined for _USE_NEWGAL.
 *
 * \sa CreateMemDCFromMyBitmap, DeleteMemDC, BITMAP
 */
HDC GUIAPI CreateMemDCFromBitmap (HDC hdc, BITMAP* bmp);

/**
 * \fn HDC GUIAPI CreateMemDCFromMyBitmap (const MYBITMAP* my_bmp, RGB* pal)
 * \brief Creates a memory DC from a device independent MYBITMAP object.
 *
 * This function creates a memory DC which have the same
 * pixel format as the MYBITMAP object \a my_bmp, and use the bits of
 * the MYBITMAP object as the surface of the memory DC. The created memory DC 
 * will have the same geometry as the MYBITMAP object. If the depth of \a my_bmp
 * is 8-bit, the function will use \a pal to initialize the palette of
 * the memory DC.
 *
 * \param my_bmp The device independent MYBITMAP object.
 * \param pal The palette of the MYBITMAP object. If the depth of \a my_bmp
 *        is larger than 8-bit, this argument can be NULL.
 * \return The handle to the memory DC, HDC_INVALID indicates an error.
 *
 * \note Only defined for _USE_NEWGAL.
 *
 * \sa CreateMemDCFromBitmap, DeleteMemDC, MYBITMAP
 */
HDC GUIAPI CreateMemDCFromMyBitmap (const MYBITMAP* my_bmp, RGB* pal);

/**
 * \fn BOOL GUIAPI ConvertMemDC (HDC mem_dc, HDC ref_dc, DWORD flags)
 * \brief Converts a memory DC to have a same format as a reference DC.
 *
 * This function converts a memory DC \a mem_dc in order to
 * let it have the same pixel format as the reference DC \a ref_dc.
 * This function will try to create a new surface for \a mem_dc, 
 * and then copies and maps the surface of \a ref_dc to it so the blit of 
 * the converted memory DC will be as fast as possible. 
 *
 * The \a flags parameter has the same semantics as \a CreateMemDC. 
 * You can also pass MEMDC_FLAG_RLEACCEL in the flags parameter and
 * MiniGUI will try to RLE accelerate colorkey and alpha blits in the 
 * resulting memory DC.
 *
 * \param mem_dc The device context to be converted.
 * \param ref_dc The reference device context.
 * \param flags The memory DC flags, has the same semantics as \a CreateMemDC.
 * \return TRUE on success, otherwise FALSE.
 *
 * \note Only defined for _USE_NEWGAL.
 *
 * \sa CreateMemDC, DeleteMemDC
 */
BOOL GUIAPI ConvertMemDC (HDC mem_dc, HDC ref_dc, DWORD flags);

/**
 * \fn BOOL GUIAPI SetMemDCAlpha (HDC mem_dc, DWORD flags, Uint8 alpha)
 * \brief Sets the alpha value for the entire surface of a DC, as opposed to
 *        using the alpha component of each pixel.
 *
 * This function sets the alpha value for the entire surface of the DC \a mem_dc, 
 * as opposed to using the alpha component of each pixel. This value measures 
 * the range of transparency of the surface, 0 being completely transparent to 255
 * being completely opaque. An \a alpha value of 255 causes blits to be
 * opaque, the source pixels copied to the destination (the default). Note
 * that per-surface alpha can be combined with colorkey transparency.
 * 
 * If \a flags is 0, alpha blending is disabled for the surface.
 * If \a flags is MEMDC_FLAG_SRCALPHA, alpha blending is enabled for the surface.
 * OR'ing the flag with MEMDC_FLAG_RLEACCEL requests RLE acceleration for the
 * surface; if MEMDC_FLAG_RLEACCEL is not specified, the RLE acceleration 
 * will be removed.
 *
 * \param mem_dc The device context.
 * \param flags The alpha value specific memory DC flags.
 * \param alpha the alpha value for the entire surface of the DC \a mem_dc.
 * \return TRUE on success, otherwise FALSE.
 *
 * \note Only defined for _USE_NEWGAL.
 *
 * \sa SetMemDCColorKey
 */ 
BOOL GUIAPI SetMemDCAlpha (HDC mem_dc, DWORD flags, Uint8 alpha);

/**
 * \fn BOOL GUIAPI SetMemDCColorKey (HDC mem_dc, DWORD flags, Uint32 color_key)
 * \brief Sets the color key (transparent pixel) of a memory DC.
 *
 * This function sets the color key (transparent pixel) of the memory DC \a mem_dc.
 * If \a flags is MEMDC_FLAG_SRCCOLORKEY (optionally OR'ed with MEMDC_FLAG_RLEACCEL),
 * \a color_key will be the transparent pixel in the source DC of a blit.
 * MEMDC_FLAG_RLEACCEL requests RLE acceleration for the source of the DC if present,
 * and removes RLE acceleration if absent. If \a flags is 0, this function clears 
 * any current color key.
 *
 * \param mem_dc The device context.
 * \param flags The color key specific memory DC flags.
 * \param color_key the color_key of the memory DC.
 * \return TRUE on success, otherwise FALSE.
 *
 * \note Only defined for _USE_NEWGAL.
 *
 * \sa SetMemDCAlpha
 */
BOOL GUIAPI SetMemDCColorKey (HDC mem_dc, DWORD flags, Uint32 color_key);

/**
 * \fn void GUIAPI DeleteMemDC (HDC mem_dc)
 * \brief Deletes a memory DC.
 *
 * This function deletes the memory DC \a mem_dc, and frees the surface of the DC.
 * For the memory DC created from BITMAP object or MYBITMAP object, the bits used
 * by the surface of the DC will be reserved.
 *
 * \param mem_dc The device context to be deleted.
 *
 * \note Only defined for _USE_NEWGAL.
 *
 * \sa CreateMemDC, CreateMemDCFromBitmap, CreateMemDCFromMyBitmap
 */
void GUIAPI DeleteMemDC (HDC mem_dc);

/**
 * \def CreateCompatibleDC(hdc)