newgal.h

libminigui-1.3.0.tar.gz。 miniGUI的库函数源代码！

 * available.  The default is to emulate the requested pixel format if it
 * is not natively available.
 *
 * If GAL_HWSURFACE is set in 'flags', the video surface will be placed in
 * video memory, if possible, and you may have to call GAL_LockSurface()
 * in order to access the raw framebuffer.  Otherwise, the video surface
 * will be created in system memory.
 *
 * If GAL_ASYNCBLIT is set in 'flags', GAL will try to perform rectangle
 * updates asynchronously, but you must always lock before accessing pixels.
 * GAL will wait for updates to complete before returning from the lock.
 *
 * If GAL_HWPALETTE is set in 'flags', the GAL library will guarantee
 * that the colors set by GAL_SetColors() will be the colors you get.
 * Otherwise, in 8-bit mode, GAL_SetColors() may not be able to set all
 * of the colors exactly the way they are requested, and you should look
 * at the video surface structure to determine the actual palette.
 * If GAL cannot guarantee that the colors you request can be set, 
 * i.e. if the colormap is shared, then the video surface may be created
 * under emulation in system memory, overriding the GAL_HWSURFACE flag.
 *
 * If GAL_FULLSCREEN is set in 'flags', the GAL library will try to set
 * a fullscreen video mode.  The default is to create a windowed mode
 * if the current graphics system has a window manager.
 * If the GAL library is able to set a fullscreen video mode, this flag 
 * will be set in the surface that is returned.
 *
 * If GAL_DOUBLEBUF is set in 'flags', the GAL library will try to set up
 * two surfaces in video memory and swap between them when you call 
 * GAL_Flip().  This is usually slower than the normal single-buffering
 * scheme, but prevents "tearing" artifacts caused by modifying video 
 * memory while the monitor is refreshing.  It should only be used by 
 * applications that redraw the entire screen on every update.
 *
 * If GAL_RESIZABLE is set in 'flags', the GAL library will allow the
 * window manager, if any, to resize the window at runtime.  When this
 * occurs, GAL will send a GAL_VIDEORESIZE event to you application,
 * and you must respond to the event by re-calling GAL_SetVideoMode()
 * with the requested size (or another size that suits the application).
 *
 * If GAL_NOFRAME is set in 'flags', the GAL library will create a window
 * without any title bar or frame decoration.  Fullscreen video modes have
 * this flag set automatically.
 *
 * This function returns the video framebuffer surface, or NULL if it fails.
 *
 * If you rely on functionality provided by certain video flags, check the
 * flags of the returned surface to make sure that functionality is available.
 * GAL will fall back to reduced functionality if the exact flags you wanted
 * are not available.
 */
extern GAL_Surface *GAL_SetVideoMode
                        (int width, int height, int bpp, Uint32 flags);

/*
 * Makes sure the given list of rectangles is updated on the given screen.
 * If 'x', 'y', 'w' and 'h' are all 0, GAL_UpdateRect will update the entire
 * screen.
 * These functions should not be called while 'screen' is locked.
 */
extern void GAL_UpdateRects
                (GAL_Surface *screen, int numrects, GAL_Rect *rects);
extern void GAL_UpdateRect
                (GAL_Surface *screen, Sint32 x, Sint32 y, Uint32 w, Uint32 h);

#if 0
/*
 * On hardware that supports double-buffering, this function sets up a flip
 * and returns.  The hardware will wait for vertical retrace, and then swap
 * video buffers before the next video surface blit or lock will return.
 * On hardware that doesn not support double-buffering, this is equivalent
 * to calling GAL_UpdateRect(screen, 0, 0, 0, 0);
 * The GAL_DOUBLEBUF flag must have been passed to GAL_SetVideoMode() when
 * setting the video mode for this function to perform hardware flipping.
 * This function returns 0 if successful, or -1 if there was an error.
 */
extern int GAL_Flip (GAL_Surface *screen);
#endif

#if 0
/*
 * Set 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.  If successful, this
 * function returns 0, otherwise it returns -1.
 */
extern int GAL_SetGamma (float red, float green, float blue);

/*
 * Set 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.
 * 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.
 */
extern int GAL_SetGammaRamp (Uint16 *red, Uint16 *green, Uint16 *blue);

/*
 * Retrieve the current values of the gamma translation 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.
 * 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.
 */
extern int GAL_GetGammaRamp (Uint16 *red, Uint16 *green, Uint16 *blue);
#endif

/*
 * Sets a portion of the colormap for the given 8-bit surface.  If 'surface'
 * is not a palettized surface, this function does nothing, returning 0.
 * If all of the colors were set as passed to GAL_SetColors(), it will
 * return 1.  If not all the color entries were set exactly as given,
 * it will return 0, and you should look at the surface palette to
 * determine the actual color palette.
 *
 * When 'surface' is the surface associated with the current display, the
 * display colormap will be updated with the requested colors.  If 
 * GAL_HWPALETTE was set in GAL_SetVideoMode() flags, GAL_SetColors()
 * will always return 1, and the palette is guaranteed to be set the way
 * you desire, even if the window colormap has to be warped or run under
 * emulation.
 */
extern int GAL_SetColors (GAL_Surface *surface, 
                        GAL_Color *colors, int firstcolor, int ncolors);

/*
 * Sets a portion of the colormap for a given 8-bit surface.
 * 'flags' is one or both of:
 * GAL_LOGPAL  -- set logical palette, which controls how blits are mapped
 *                to/from the surface,
 * GAL_PHYSPAL -- set physical palette, which controls how pixels look on
 *                the screen
 * Only screens have physical palettes. Separate change of physical/logical
 * palettes is only possible if the screen has GAL_HWPALETTE set.
 *
 * The return value is 1 if all colours could be set as requested, and 0
 * otherwise.
 *
 * GAL_SetColors() is equivalent to calling this function with
 *     flags = (GAL_LOGPAL|GAL_PHYSPAL).
 */
extern int GAL_SetPalette (GAL_Surface *surface, int flags,
                                   GAL_Color *colors, int firstcolor,
                                   int ncolors);

extern void GAL_DitherColors(GAL_Color *colors, int bpp);

/*
 * Maps an RGB triple to an opaque pixel value for a given pixel format
 */
extern Uint32 GAL_MapRGB (GAL_PixelFormat *format, Uint8 r, Uint8 g, Uint8 b);

/*
 * Maps an RGBA quadruple to a pixel value for a given pixel format
 */
extern Uint32 GAL_MapRGBA (GAL_PixelFormat *format,
                                   Uint8 r, Uint8 g, Uint8 b, Uint8 a);

/*
 * Maps a pixel value into the RGB components for a given pixel format
 */
extern void GAL_GetRGB (Uint32 pixel, GAL_PixelFormat *fmt,
                                Uint8 *r, Uint8 *g, Uint8 *b);

/*
 * Maps a pixel value into the RGBA components for a given pixel format
 */
extern void GAL_GetRGBA (Uint32 pixel, GAL_PixelFormat *fmt,
                                 Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);

/*
 * Allocate and free an RGB surface (must be called after GAL_SetVideoMode)
 * If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
 * If the depth is greater than 8 bits, the pixel format is set using the
 * flags '[RGB]mask'.
 * If the function runs out of memory, it will return NULL.
 *
 * The 'flags' tell what kind of surface to create.
 * GAL_SWSURFACE means that the surface should be created in system memory.
 * GAL_HWSURFACE means that the surface should be created in video memory,
 * with the same format as the display surface.  This is useful for surfaces
 * that will not change much, to take advantage of hardware acceleration
 * when being blitted to the display surface.
 * GAL_ASYNCBLIT means that GAL will try to perform asynchronous blits with
 * this surface, but you must always lock it before accessing the pixels.
 * GAL will wait for current blits to finish before returning from the lock.
 * GAL_SRCCOLORKEY indicates that the surface will be used for colorkey blits.
 * If the hardware supports acceleration of colorkey blits between
 * two surfaces in video memory, GAL will try to place the surface in
 * video memory. If this isn't possible or if there is no hardware
 * acceleration available, the surface will be placed in system memory.
 * GAL_SRCALPHA means that the surface will be used for alpha blits and 
 * if the hardware supports hardware acceleration of alpha blits between
 * two surfaces in video memory, to place the surface in video memory
 * if possible, otherwise it will be placed in system memory.
 * If the surface is created in video memory, blits will be _much_ faster,
 * but the surface format must be identical to the video surface format,
 * and the only way to access the pixels member of the surface is to use
 * the GAL_LockSurface() and GAL_UnlockSurface() calls.
 * If the requested surface actually resides in video memory, GAL_HWSURFACE
 * will be set in the flags member of the returned surface.  If for some
 * reason the surface could not be placed in video memory, it will not have
 * the GAL_HWSURFACE flag set, and will be created in system memory instead.
 */
#define GAL_AllocSurface    GAL_CreateRGBSurface
extern GAL_Surface *GAL_CreateRGBSurface
                        (Uint32 flags, int width, int height, int depth, 
                        Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
extern GAL_Surface *GAL_CreateRGBSurfaceFrom (void *pixels,
                        int width, int height, int depth, int pitch,
                        Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
extern void GAL_FreeSurface (GAL_Surface *surface);

typedef struct REQ_HWSURFACE {
    /* for allocation */
    Uint32 w;
    Uint32 h;
    Uint32 pitch;

    /* for free */
    Uint32 offset;
    void* bucket;
} REQ_HWSURFACE;

typedef struct REP_HWSURFACE {
    Uint32 offset;
    Uint32 pitch;
    void*  bucket;
} REP_HWSURFACE;

#ifdef _LITE_VERSION
extern void GAL_RequestHWSurface (const REQ_HWSURFACE* request, REP_HWSURFACE* reply);
#endif

/*
 * GAL_LockSurface() sets up a surface for directly accessing the pixels.
 * Between calls to GAL_LockSurface()/GAL_UnlockSurface(), you can write
 * to and read from 'surface->pixels', using the pixel format stored in 
 * 'surface->format'.  Once you are done accessing the surface, you should 
 * use GAL_UnlockSurface() to release it.
 *
 * Not all surfaces require locking.  If GAL_MUSTLOCK(surface) evaluates
 * to 0, then you can read and write to the surface at any time, and the
 * pixel format of the surface will not change.  In particular, if the
 * GAL_HWSURFACE flag is not given when calling GAL_SetVideoMode(), you
 * will not need to lock the display surface before accessing it.
 * 
 * No operating system or library calls should be made between lock/unlock
 * pairs, as critical system locks may be held during this time.
 *
 * GAL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
 */
#if 0
extern int GAL_LockSurface (GAL_Surface *surface);
extern void GAL_UnlockSurface (GAL_Surface *surface);
#endif