gdi.h

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

/**
 * \file gdi.h
 * \author Wei Yongming <[e-mail]>
 * \date 2002/01/06
 * 
 * This file includes graphics device interfaces of MiniGUI.
 *
 \verbatim
    Copyright (C) 2002-2005 Feynman Software.
    Copyright (C) 1998-2002 Wei Yongming.

    This file is part of MiniGUI, a compact cross-platform Graphics 
    User Interface (GUI) support system for real-time embedded systems.

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

    If you are using MiniGUI for developing commercial, proprietary, or other
    software not covered by the GPL terms, you must have a commercial license
    for MiniGUI. Please see http://www.minigui.com/product/index.html for 
    how to obtain this. If you are interested in the commercial MiniGUI 
    licensing, please write to [e-mail]. 

 \endverbatim
 */

/*
 * $Id: gdi.h,v 1.205.2.1 2005/03/09 09:26:19 weiym Exp $
 *
 *             MiniGUI for Linux/uClinux, eCos, uC/OS-II, VxWorks, 
 *                     and ThreadX version 1.6.x
 *             Copyright (C) 2002-2005 Feynman Software.
 *             Copyright (C) 1998-2002 Wei Yongming.
 */

#ifndef _MGUI_GDI_H
    #define _MGUI_GDI_H

/* include necessary headers */
#ifndef _LITE_VERSION
#include <pthread.h>
#endif /* !LITE_VERSION */
 
#ifdef __cplusplus
extern "C" {
#endif  /* __cplusplus */

    /**
     * \addtogroup global_vars Global variables
     * @{
     */

    /**
     * \defgroup color_vars System colors and pixel values.
     * @{
     */

/**
 * \var gal_pixel SysPixelIndex []
 * \brief The pre-defined system pixel values.
 *
 * MiniGUI defines some system pixel values when initializing 
 * graphics sub-system. You can access the arrary to get the
 * system pixel values, or just use the following macros:
 *
 *  - PIXEL_black\n
 *    black
 *  - PIXEL_darkred\n
 *    dark red
 *  - PIXEL_darkgreen\n
 *    dark green
 *  - PIXEL_darkyellow\n
 *    dark yellow
 *  - PIXEL_darkblue\n
 *    dark blue
 *  - PIXEL_darkmagenta\n
 *    dark magenta
 *  - PIXEL_darkcyan\n
 *    dark cyan
 *  - PIXEL_lightgray\n
 *    light gray
 *  - PIXEL_darkgray\n
 *    dark gray
 *  - PIXEL_red\n
 *    red
 *  - PIXEL_green\n
 *    green
 *  - PIXEL_yellow\n
 *    yellow
 *  - PIXEL_blue\n
 *    blue
 *  - PIXEL_magenta\n
 *    magenta
 *  - PIXEL_cyan\n
 *    cyan
 *  - PIXEL_lightwhite\n
 *    light white
 */
#ifdef WIN32
#ifdef __MINIGUI_LIB__
MG_EXPORT  gal_pixel SysPixelIndex [];
#else
MG_IMPORT  gal_pixel SysPixelIndex [];
#endif
#else
extern gal_pixel SysPixelIndex [];
#endif

/**
 * \var RGB SysPixelColor []
 * \brief The pre-defined system RGB colors.
 *
 * The elements in this array are system colors in RGB triples.
 */
extern const RGB SysPixelColor [];

#define PIXEL_invalid       0
#define PIXEL_transparent   SysPixelIndex[0]
#define PIXEL_darkblue      SysPixelIndex[1]
#define PIXEL_darkgreen     SysPixelIndex[2]
#define PIXEL_darkcyan      SysPixelIndex[3]
#define PIXEL_darkred       SysPixelIndex[4] 
#define PIXEL_darkmagenta   SysPixelIndex[5]
#define PIXEL_darkyellow    SysPixelIndex[6] 
#define PIXEL_darkgray      SysPixelIndex[7] 
#define PIXEL_lightgray     SysPixelIndex[8]
#define PIXEL_blue          SysPixelIndex[9]
#define PIXEL_green         SysPixelIndex[10]
#define PIXEL_cyan          SysPixelIndex[11]
#define PIXEL_red           SysPixelIndex[12]
#define PIXEL_magenta       SysPixelIndex[13]
#define PIXEL_yellow        SysPixelIndex[14]
#define PIXEL_lightwhite    SysPixelIndex[15]
#define PIXEL_black         SysPixelIndex[16]

/* Compatiblity definitions */
#define COLOR_invalid       PIXEL_invalid
#define COLOR_transparent   PIXEL_transparent
#define COLOR_darkred       PIXEL_darkred
#define COLOR_darkgreen     PIXEL_darkgreen
#define COLOR_darkyellow    PIXEL_darkyellow
#define COLOR_darkblue      PIXEL_darkblue
#define COLOR_darkmagenta   PIXEL_darkmagenta
#define COLOR_darkcyan      PIXEL_darkcyan
#define COLOR_lightgray     PIXEL_lightgray
#define COLOR_darkgray      PIXEL_darkgray
#define COLOR_red           PIXEL_red
#define COLOR_green         PIXEL_green
#define COLOR_yellow        PIXEL_yellow
#define COLOR_blue          PIXEL_blue
#define COLOR_magenta       PIXEL_magenta
#define COLOR_cyan          PIXEL_cyan
#define COLOR_lightwhite    PIXEL_lightwhite
#define COLOR_black         PIXEL_black

#define SysColorIndex       SysPixelIndex

    /** @} end of color_vars */

    /** @} end of global_vars */

    /**
     * \addtogroup fns Functions
     * @{
     */

    /**
     * \addtogroup global_fns Global/general functions
     * @{
     */

    /**
     * \defgroup block_heap_fns Block data heap operations
     *
     * MiniGUI maintains some private block data heaps to allocate
     * data blocks which have fixed size, such as the clipping rectangles
     * in a region. By using the private heap, we can avoiding calling
     * \a malloc and \a free function frequently, so will have a slight 
     * performance enhancement.
     *
     * @{
     */

/**
 * MiniGUI's private block data heap.
 *
 * \sa InitBlockDataHeap, DestroyBlockDataHeap
 */
typedef struct _BLOCKHEAP
{
#ifndef _LITE_VERSION
    pthread_mutex_t lock;
#endif
    /**
     * size of one block element.
     */
    size_t          bd_size;
    /**
     * size of the heap in blocks.
     */
    size_t          heap_size;
    /**
     * the first free element in the heap.
     */
    int             free;
    /**
     * pointer to the pre-allocated heap.
     */
    void*           heap;
} BLOCKHEAP;

/**
 * \var typedef BLOCKHEAP* PBLOCKHEAP
 * \brief Data type of the pointer to a BLOCKHEAP.
 *
 * \sa BLOCKHEAP
 */
typedef BLOCKHEAP* PBLOCKHEAP;

/**
 * \fn void InitBlockDataHeap (PBLOCKHEAP heap, size_t bd_size, size_t heap_size)
 * \brief Initializes a private block data heap.
 *
 * This function initializes a block data heap pointed to by \a heap.
 * It will allocate the buffer used by the heap from system heap by using \a malloc(3).
 * Initially, the heap has \a heap_size blocks free, and each is \a bd_size bytes long.
 *
 * \param heap The pointer to the heap structure.
 * \param bd_size The size of one block in bytes.
 * \param heap_size The size of the heap in blocks.
 * \return \a heap->heap will contains a valid pointer on success, NULL on error.
 *
 * \note This function does not return anything. You should check the \a heap
 * field of the \a heap structure.
 *
 * \sa BLOCKHEAP
 */
MG_EXPORT   extern void  InitBlockDataHeap (PBLOCKHEAP heap, size_t bd_size, size_t heap_size);

/**
 * \fn void* BlockDataAlloc (PBLOCKHEAP heap)
 * \brief Allocates a data block from private heap.
 *
 * This function allocates a data block from an initialized 
 * block data heap. The allocated block will have the size of \a heap->bd_size.
 * If there is no free block in the heap, this function will try to allocate
 * the block from the system heap by using \a malloc(3) function.
 *
 * \param heap The pointer to the initialized heap.
 * \return Pointer to the allocated data block, NULL on error.
 *
 * \sa InitBlockDataHeap, BlockDataFree
 */

MG_EXPORT  extern  void*   BlockDataAlloc (PBLOCKHEAP heap);

/**
 * \fn void BlockDataFree (PBLOCKHEAP heap, void* data)
 * \brief Frees an allocated data block.
 *
 * This function frees the specified data block pointed to by \a data to the heap \a heap.
 * If the block was allocated by using \a malloc function, this function will
 * free the element by using \a free(3) function. 
 *
 * \param heap The pointer to the heap.
 * \param data The pointer to the element to be freed.
 *
 * \sa InitBlockDataHeap, BlockDataAlloc
 */
MG_EXPORT extern  void BlockDataFree (PBLOCKHEAP heap, void* data);

/**
 * \fn void DestroyBlockDataHeap (PBLOCKHEAP heap)
 * \brief Destroies a private block data heap.
 *
 * \param heap The pointer to the heap to be destroied.
 *
 * \sa InitBlockDataHeap, BLOCKHEAP
 */
MG_EXPORT  extern void DestroyBlockDataHeap (PBLOCKHEAP heap);

    /** @} end of block_heap_fns */

    /** @} end of global_fns */

    /**
     * \defgroup gdi_fns GDI functions
     * @{
     */

struct _BITMAP;
typedef struct _BITMAP BITMAP;
typedef BITMAP* PBITMAP;

struct _MYBITMAP;
typedef struct _MYBITMAP MYBITMAP;
typedef struct _MYBITMAP* PMYBITMAP;

   /**
    * \defgroup region_fns Region operations
    *
    * A Region is simply an area, as the name implies, and is implemented as 
    * a "y-x-banded" array of rectangles. To explain: Each Region is made up 
    * of a certain number of rectangles sorted by y coordinate first, 
    * and then by x coordinate.
    *
    * Furthermore, the rectangles are banded such that every rectangle with a
    * given upper-left y coordinate (y1) will have the same lower-right y
    * coordinate (y2) and vice versa. If a rectangle has scanlines in a band, it
    * will span the entire vertical distance of the band. This means that some
    * areas that could be merged into a taller rectangle will be represented as
    * several shorter rectangles to account for shorter rectangles to its left
    * or right but within its "vertical scope".
    *
    * An added constraint on the rectangles is that they must cover as much
    * horizontal area as possible. E.g. no two rectangles in a band are allowed
    * to touch.
    *
    * Whenever possible, bands will be merged together to cover a greater vertical
    * distance (and thus reduce the number of rectangles). Two bands can be merged
    * only if the bottom of one touches the top of the other and they have
    * rectangles in the same places (of the same width, of course). This maintains
    * the y-x-banding that's so nice to have...
    *
    * Example:
    *
    * \include region.c
    *
    * @{
    */

/**
 * Clipping rectangle structure.
 */
typedef struct _CLIPRECT
{
    /**
     * the clipping rectangle itself.
     */
    RECT rc;
    /**
     * the next clipping rectangle.
     */
    struct _CLIPRECT* next;
#ifdef _USE_NEWGAL
    /**
     * the previous clipping rectangle.
     * \note only defined for _USE_NEWGAL.
     */
    struct _CLIPRECT* prev;
#endif
} CLIPRECT;
typedef CLIPRECT* PCLIPRECT;

/* Clipping Region */
#ifdef _USE_NEWGAL
#define NULLREGION      0x00
#define SIMPLEREGION    0x01
#define COMPLEXREGION   0x02
#endif

/**
 * Clipping region structure, alos used for general regions.
 */
typedef struct _CLIPRGN
{
#ifdef _USE_NEWGAL
   /**
    * type of the region, can be one of the following:
    *   - NULLREGION\n
    *     a null region.
    *   - SIMPLEREGION\n
    *     a simple region.
    *   - COMPLEXREGION
    *     a complex region.
    *
    * \note only defined for _USE_NEWGAL.
    */
    BYTE            type;        /* type of region */
   /**
    * reserved for alignment.
    *
    * \note only defined for _USE_NEWGAL.