gdi.h

这是ARM嵌入式系统的实验教程中的MINIGUI的实验源代码！

 * \param color_key the color_key of the memory DC.
 * \return TRUE on success, otherwise FALSE.
 *
 * \note Only defined for _USE_NEWGAL.
 *
 * \sa SetMemDCAlpha
 */
MG_EXPORT 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
 */
MG_EXPORT void GUIAPI DeleteMemDC (HDC mem_dc);

/**
 * \def CreateCompatibleDC(hdc)
 * \brief Creates a memory DC which is compatible with a given DC.
 *
 * This function creates a memory DC fully compatible with the reference 
 *        DC \a hdc, including pixel format and geomatry.
 *
 * \param hdc The reference DC.
 * \return The handle to the memory DC, HDC_INVALID indicates an error.
 *
 * \note Only defined as macro calling \a CreateCompatibleDCEx for _USE_NEWGAL. 
 *       If _USE_NEWGAL is not defined, \a CreateCompatibleDC is defined as 
 *       a function, and have the same semantics as this macro.
 *
 * \sa CreateCompatibleDCEx, DeleteMemDC
 */
#define CreateCompatibleDC(hdc) CreateCompatibleDCEx(hdc, 0, 0);

/**
 * \def DeleteCompatibleDC(hdc)
 * \brief Deletes a memory DC.
 *
 * This function deletes a memory DC created by \a CreateCompatibleDC.
 *
 * \param hdc The device context to be deleted.
 *
 * \note Only defined as macro calling \a DeleteMemDC for _USE_NEWGAL. 
 *       If _USE_NEWGAL is not defined, \a DeleteCompatibleDC is defined 
 *       as a function, and have the same semantics as this macro.
 *
 * \sa CreateCompatibleDC, DeleteMemDC
 */
#define DeleteCompatibleDC(hdc) DeleteMemDC(hdc)

/**
 * \fn Uint8* GUIAPI LockDC (HDC hdc, const RECT* rw_rc, int* width, int* height, int* pitch)
 * \brief Locks a dc to get direct access to pixels in the DC.
 *
 * Calling this function will try to lock the DC \a hdc to directly access the pixels
 * of the DC. You should tell this function the rectangle to be accessed, and the function
 * will return the effective \a width, \a height and \a pitch of the DC. The access 
 * beyond effective width and height will be invalid. 
 *
 * Locking a DC which uses screen surface will lock some global objects, such as mouse
 * cursor, and so on. All GDI calls of other threads (in MiniGUI-Threads) or other process 
 * (in MiniGUI-Lite) will be blocked as well. So you should call \a UnlockDC to unlock 
 * the DC as soon as possible, and should not call any system function in the duration of 
 * locking the DC.
 *
 * \param hdc The handle to the device context.
 * \param rw_rc The rectangle in device coordinate system to be accessed in the DC.
 * \param width The width of the effective rectangle can access will be returned through 
 *        this pointer.
 * \param height The height of the effective rectangle can access will be returned through 
 *        this pointer.
 * \param pitch The pitch of the scan line of the DC will be returned through this pointer.
 *        Pitch means the length of the scan line in bytes.
 * \return The bits pointer to the upper-left corner of the effective rectangle, NULL on error.
 *
 * \note Only defined for _USE_NEWGAL.
 *
 * \sa UnlockDC
 *
 * Example:
 *
 * \include lockdc.c
 */
MG_EXPORT Uint8* GUIAPI LockDC (HDC hdc, const RECT* rw_rc, int* width, int* height, int* pitch);

/**
 * \fn void GUIAPI UnlockDC (HDC hdc)
 * \brief Unlocks a locked DC.
 *
 * \param hdc The locked DC.
 *
 * \note Only defined for _USE_NEWGAL.
 *
 * \sa LockDC
 */
MG_EXPORT void GUIAPI UnlockDC (HDC hdc);

   /**
    * \defgroup yuv_fns YUV overlay operations
    *
    * For an explanation of common video overlay formats, see:
    *
    * http://www.webartz.com/fourcc/indexyuv.htm
    *
    * For information on the relationship between color spaces, see:
    *
    * http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
    *
    * @{
    */

#define GAL_YV12_OVERLAY  0x32315659    /* Planar mode: Y + V + U  (3 planes) */
#define GAL_IYUV_OVERLAY  0x56555949    /* Planar mode: Y + U + V  (3 planes) */
#define GAL_YUY2_OVERLAY  0x32595559    /* Packed mode: Y0+U0+Y1+V0 (1 plane) */
#define GAL_UYVY_OVERLAY  0x59565955    /* Packed mode: U0+Y0+V0+Y1 (1 plane) */
#define GAL_YVYU_OVERLAY  0x55595659    /* Packed mode: Y0+V0+Y1+U0 (1 plane) */

/**
 * The YUV hardware video overlay
 */
typedef struct GAL_Overlay {
    /** The overlay format, read-only */
    Uint32 format;
    /** The width of the overlay, read-only */
    int w;
    /** The height of the overlay, read-only */
    int h;
    /** The number of the planes of the overlay, read-only */
    int planes;
    /** The pitches of planes, read-only */
    Uint16 *pitches;
    /** The YUV pixels of planse, read-write */
    Uint8 **pixels;

    /* Hardware-specific surface info */
    struct private_yuvhwfuncs *hwfuncs;
    struct private_yuvhwdata *hwdata;

    /** Does This overlay hardware accelerated? */
    Uint32 hw_overlay :1;
    Uint32 UnusedBits :31;
} GAL_Overlay;

/**
 * \fn GAL_Overlay* GUIAPI CreateYUVOverlay (int width, int height, Uint32 format, HDC hdc)
 * \brief Creates a video output overlay on a DC.
 *
 * This function creates a video output overlay on the given DC \a hdc.
 * Calling the returned surface an \a overlay is something of a misnomer because
 * the contents of the display DC \a hdc underneath the area where the overlay
 * is shown is undefined - it may be overwritten with the converted YUV data.
 *
 * \param width The expected width of the video overlay.
 * \param height The expected height of the video overlay.
 * \param format The expected video overlay format, can be one of the following values:
 *
 *      - GAL_YV12_OVERLAY\n
 *        Planar mode: Y + V + U  (3 planes)
 *      - GAL_IYUV_OVERLAY\n
 *        Planar mode: Y + U + V  (3 planes)
 *      - GAL_YUY2_OVERLAY\n
 *        Packed mode: Y0+U0+Y1+V0 (1 plane)
 *      - GAL_UYVY_OVERLAY\n
 *        Packed mode: U0+Y0+V0+Y1 (1 plane)
 *      - GAL_YVYU_OVERLAY\n
 *        Packed mode: Y0+V0+Y1+U0 (1 plane)
 *
 * \param hdc The device context.
 * \return A GAL_Overlay object on success, NULL on error.
 *
 * \note Only defined for _USE_NEWGAL.
 *
 * \sa GAL_LockYUVOverlay, GAL_FreeYUVOverlay, http://www.webartz.com/fourcc/indexyuv.htm
 */
MG_EXPORT GAL_Overlay* GUIAPI CreateYUVOverlay (int width, int height,
                Uint32 format, HDC hdc);

/**
 * \fn int GAL_LockYUVOverlay (GAL_Overlay *overlay)
 * \brief Locks an overlay for direct access.
 *
 * \note Only defined for _USE_NEWGAL.
 *
 * \sa GAL_UnlockYUVOverlay
 */
int GAL_LockYUVOverlay (GAL_Overlay *overlay);

/**
 * \fn void GAL_UnlockYUVOverlay (GAL_Overlay *overlay)
 * \brief Unlocks a locked overlay when you are done
 *
 * \note Only defined for _USE_NEWGAL.
 *
 * \sa GAL_LockYUVOverlay
 */
void GAL_UnlockYUVOverlay (GAL_Overlay *overlay);

/**
 * \def LockYUVOverlay
 * \brief Is an alias of \a GAL_LockYUVOverlay
 * \sa GAL_LockYUVOverlay
 */
#define LockYUVOverlay GAL_LockYUVOverlay

/**
 * \def UnlockYUVOverlay
 * \brief Is an alias of \a GAL_UnlockYUVOverlay
 * \sa GAL_UnlockYUVOverlay
 */
#define UnlockYUVOverlay GAL_UnlockYUVOverlay

/**
 * \fn void GAL_FreeYUVOverlay (GAL_Overlay *overlay)
 * \brief Frees a YUV overlay.
 *
 * This function frees a YUV overlay created by \a GAL_CreateYUVOverlay.
 *
 * \param overlay The video overlay to be freed.
 *
 * \note Only defined for _USE_NEWGAL.
 *
 * \sa GAL_CreateYUVOverlay
 */
void GAL_FreeYUVOverlay (GAL_Overlay *overlay);

/**
 * \def FreeYUVOverlay
 * \brief Is an alias of \a GAL_FreeYUVOverlay
 * \sa GAL_FreeYUVOverlay
 */
#define FreeYUVOverlay GAL_FreeYUVOverlay

/**
 * \fn void GUIAPI DisplayYUVOverlay (GAL_Overlay* overlay, const RECT* dstrect)
 * \brief Blits a video overlay to the screen.
 *
 * Calling this function will blit the video overly \a overlay to the screen. 
 * The contents of the video surface underneath the blit destination are
 * not defined. The width and height of the destination rectangle may be 
 * different from that of the overlay, but currently only 2x scaling is supported.
 * And note that the \a dstrect is in screen coordinate system.
 *
 * \param overlay The video overlay to be displayed.
 * \param dstrect The destination rectangle. It may be different from that of 
 *        the overlay, but currently only 2x scaling is supported
 *
 * \note Only defined for _USE_NEWGAL.
 *
 * \sa GAL_CreateYUVOverlay, GAL_LockYUVOverlay
 */
MG_EXPORT void GUIAPI DisplayYUVOverlay (GAL_Overlay* overlay, const RECT* dstrect);

    /** @} end of yuv_fns */

    /**
     * \defgroup gamma_fns Gamma correction functions
     * @{
     */

/**
 * \fn int GAL_SetGamma (float red, float green, float blue)
 * \brief Sets the gamma correction for each of the color channels.
 *
 * This function sets the gamma correction for each of the color channels.
 * The gamma values range (approximately) between 0.1 and 10.0.
 * If this function isn't supported directly by the hardware, it will
 * be emulated using gamma ramps, if available. 
 *
 * \param red The gamma correction value of red channel.
 * \param green The gamma correction value of green channel.
 * \param blue The gamma correction value of blue channel.
 * \return If successful, this function returns 0, otherwise it returns -1.
 *
 * \note Only defined for _USE_NEWGAL.
 *
 * \sa GAL_SetGammaRamp
 */
int GAL_SetGamma (float red, float green, float blue);

/**
 * \def SetGamma
 * \brief Is an alias of \a GAL_SetGamma
 * \sa GAL_SetGamma
 */
#define SetGamma GAL_SetGamma

/**
 * \fn int GAL_SetGammaRamp (Uint16 *red, Uint16 *green, Uint16 *blue)
 * \brief Sets the gamma translation table for the red, green, and blue channels of the video hardware.  
 *
 * This function sets the gamma translation table for the red, green, and blue channels of the video hardware.  
 * Each table is an array of 256 16-bit quantities, representing a mapping 
 * between the input and output for that channel. The input is the index into 
 * the array, and the output is the 16-bit gamma value at that index, scaled 
 * to the output color precision.
 * 
 * You may pass NULL for any of the channels to leave it unchanged.
 *
 * \param red The gamma translation table for the red channel.
 * \param green The gamma translation table for the green channel.
 * \param blue The gamma translation table for the blue channel.
 * \return If the call succeeds, it will return 0. If the display driver or hardware does 
 * not support gamma translation, or otherwise fails, this function will return -1.
 *
 * \note Only defined for _USE_NEWGAL.
 *
 * \sa GAL_GetGammaRamp, GAL_SetGamma
 */
int GAL_SetGammaRamp (Uint16 *red, Uint16 *green, Uint16 *blue);

/**
 * \def SetGammaRamp
 * \brief Is an alias of \a GAL_SetGammaRamp
 * \sa GAL_SetGammaRamp
 */
#define SetGammaRamp GAL_SetGammaRamp

/**
 * \fn int GAL_GetGammaRamp (Uint16 *red, Uint16 *green, Uint16 *blue)
 * \brief Retrieves the current values of the gamma translation tables.
 * 
 * This function retrives the current values of the gamma translationn tables.
 * You must pass in valid pointers to arrays of 256 16-bit quantities.
 * Any of the pointers may be NULL to ignore that channel.
 *
 * \param red Pointers to the array of gamma translation tables for the red channel.
 * \param green Pointers to the array of gamma translation tables for the green channel.
 * \param blue Pointers to the array of gamma translation tables for the blue channel.
 * \return If the call succeeds, it will return 0. If the display driver or
 *         hardware does not support gamma translation, or otherwise fails, 
 *         this function will return -1.
 *
 * \note Only defined for _USE_NEWGAL.
 *
 * \sa GAL_SetGammaRamp
 */
int GAL_GetGammaRamp (Uint16 *red, Uint16 *green, Uint16 *blue);

/**
 * \def GetGammaRamp
 * \brief Is an alias of \a GAL_GetGammaRamp
 * \sa GAL_GetGammaRamp
 */
#define GetGammaRamp GAL_GetGammaRamp

    /** @} end of gamma_fns */

#else

MG_EXPORT HDC GUIAPI CreateCompatibleDC (HDC hdc);
MG_EXPORT void GUIAPI DeleteCompatibleDC (HDC hdc);

#endif /* _USE_NEWGAL */

    /** @} end of dc_fns */

    /**
     * \defgroup dc_attrs DC attribute operations
     * @{
     */

#define BM_TRANSPARENT          1
#define BM_OPAQUE               0

#ifdef _USE_NEWGAL

#define DC_ATTR_BK_COLOR        0
#define DC_ATTR_BK_MODE         1
#define DC_ATTR_PEN_COLOR       2
#define DC_ATTR_BRUSH_COLOR     3
#define DC_ATTR_TEXT_COLOR      4
#define DC_ATTR_TAB_STOP        5

#define DC_ATTR_CHAR_EXTRA      6
#define DC_ATTR_ALINE_EXTRA     7
#define DC_ATTR_BLINE_EXTRA     8

#define DC_ATTR_MAP_MODE        9

#ifdef _ADV_2DAPI

#define DC_ATTR_PEN_TYPE        10
#define DC_ATTR_PEN_CAP_STYLE   11
#define DC_ATTR_PEN_JOIN_STYLE  12
#define DC_ATTR_PEN_WIDTH       13