NewAPI/Documents/gfx-api

From Allegro Wiki
Jump to: navigation, search

Bob's GFX API proposal

The original is from here: http://alleg.sourceforge.net/future/gfx-api.txt

date: 2003 - 12 - 30

Graphics API. Details of a user's view to Allegro 5.

Changelog:

  • 2003/12/30
    • Cleared up the role of the alpha channel on al_blit()
    • Various formatting changes
    • Display bitmap update mode was make into a recommendation.
    • Added 16-bit per component display formats
    • Added some 3-component display formats
    • Generatlized RLE bitmaps to Compressed bitmaps.
    • Removed the useless 'int x' parameter to al_map_yuv422()
    • Removed al_get_bitmap_component_ordering(), replaced by al_get_bitmap_component_positions()


  • 2003/04/19
    • Renamed AL_NOT_MASK_SOURCE to AL_MASK_INV_SOURCE and AL_NOT_DEST_MASK to AL_MASK_INV_DEST.
    • Removed sub-pixel precision and linear interpolation hints. Replaced them with a generic AL_FILTER, which can be controlled by al_set_bitmap_filter().
    • Added al_get_bitmap_region_info()
    • Added al_set_bitmap_filter()
    • Changed clip behavior of al_blit_region_3()


  • History (as of 10-Jan-2003):
    • Added missing flip flags to the other blit functions, as pointed out by Lennart Steinke
    • Fixed up the behavior of al_list_bitmap_clip() as suggested by Peter Hull.
    • Removed text/font functions from this proposal. They are better left for a separate one.
    • Documented bitmap acquire/release functions
    • Removed XOR mode. This mode can be merged with the blenders
    • Documented primitive drawing functions.
    • Renamed AL_PRIMITIVE_LINE to AL_OUTLINE, as per Lennart Steinke's suggestion and to reduce typing.
    • Renamed AL_TRANS_BLIT to AL_BLEND, as suggested by Nick Davis, and AL_LIT_BLIT to AL_LIT to potentially reuse it for the primitive functions.
    • Removed the circle drawing function and generalized the ellipse one to draw a shape enclosed by a rectangle as suggested by Chris Barry and 'Rash'
    • Updated some of the config variables.
    • Added an 8+8 interleaved format (AL_8_8_I) to support YUV422.
    • Renamed blit_clip to blit_region
    • Renamed blit_scale to blit_scaled and rotate_scale_bitmap to rotate_scaled_bitmap
    • Renamed AL_8 and family to AL_COLOR_*, after overwhelming support for more verbose names.
    • Added wording about alpha channels
    • Documented the al_map_* family of routines.
    • Dropped the 'x' parameter in the yuv mapping functions. It isn't necessairy and will complicate the implementation.
    • Changed return type of al_is_bitmap_of_type() to bool.
    • Started writting a prototype header file.
    • Documented low-level bitmap access.
    • Added an example for the low-level bitmap access routines.
    • Renamed al_blit_3_clip() to al_blit_region_3().
    • Added interpolation hints to the rotate and stretch functions.


<highlightSyntax language="c"> /* Insert intro paragraph on graphics and bitmaps, as they relate to Allegro */


/**** Blitting ****/


/* void al_blit(int flag, AL_BITMAP *source, AL_BITMAP *dest,

               int dest_x, int dest_y);
*/

/* Copies a rectangular area of the source bitmap to the destination bitmap.

* The dest_x and dest_y are the coordinates of the top-left corner in the
* destination bitmap where the source bitmap will be drawn. This routine
* respects the source and destination clipping rectangles.
*
* If the flags parameter is zero, you can blit between any parts of any two
* bitmaps, even if the two memory areas overlap (ie. source and dest are the
* same, or one is sub-bitmap of the other). You should be aware, however,
* that a lot of SVGA cards don't provide separate read and write banks,
* which means that blitting from one part of the screen to another requires
* the use of a temporary bitmap in memory, and is therefore extremely slow.
* As a general rule you should avoid blitting from the screen onto itself in
* SVGA modes. 
*
* If the flags parameter is not zero, then performing blits in between
* overlapping regions has an undefined result.
*
* If the gfx/current/hw_vram_blit flag is set, and the flags parameter is 0,
* the current driver supports hardware accelerated blits from one part of
* the current display or associated video bitmaps onto another (in the same
* display). This is extremely fast, so when this flag is set it may be worth
* storing some of your more frequently used graphics in an offscreen portion
* of the video memory by using video bitmaps.
*
* Similarly, if the gfx/current/hw_vram_masked_blit flag is set and the flags
* parameter is set to AL_MASK_SOURCE, then source-masked blitting is supported
* in between the current display, or an associated video bitmap, and another
* video bitmap or another part of the same display.
*
* Unlike most of the graphics routines, al_blit() allows the source and
* destination bitmaps to be of different color depths, so it can be used
* to convert images from one pixel format to another. Note however that
* color conversion is only available if the flags parameter is set to 0.
* Color conversion can be performed in between any type of bitmap supported
* by Allegro. The color converters will use the direct bitmap access routines.
*
* Additionally, you may not blit from a video, system, display, or sub-bitmaps
* thereof that inherit from one display bitmap to video, system, display or
* sub-bitmaps thereof that inherit from some other display bitmap.
* That is, video and system bitmaps are linked to the display bitmap they
* inherit from, and cannot be directly blitted to some other display bitmap
* or associated video and system bitmaps. If you really need to cross-blit
* in between display bitmap 'families', then use a temporary memory bitmap.
*
* The flag parameter can be almost any binary OR (|) combination of:
*  - AL_MASK_SOURCE - Don't copy source pixels that are of the mask color
*  - AL_MASK_DEST   - Don't copy source pixels if the corresponding
*                     destination pixel is of the mask color
*  - AL_MASK_INV_SOURCE - Don't copy source pixels that are not of the mask
*                         color
*  - AL_MASK_INV_DEST   - Don't copy source pixels if the corresponding
*                         destination pixel is not of the mask color.
*  - AL_BLEND       - Draws pixels tranlucently. See al_set_blender()
*                     for details. This flag cannot be used in conjunction
*                     with AL_LIT.
*  - AL_LIT         - Lits the source pixels with the current blend color
*                     before writting them to the destination.
*                     This flag cannot be used with AL_BLEND.
*  - AL_HORIZONTAL_FLIP - Flips the source bitmap along the x axis. The top
*                         row of pixels ends up at the bottom and vice versa
*  - AL_VERTICAL_FLIP   - Flips the source bitmap along the y axis. The left
*                         column of pixels ends up at the right and vice versa
*  (desribe the flags in more details)
*
*  Additional flags can be added via add-ons. (How??)
*  
* The alpha channel, if present, does not affect pixel processing for any but
* the AL_BLEND and AL_LIT drawing modes.
*
* Comments:
*  - The flag parameter can be used to add more functionality
*  - Reduction in the API from Allegro 4
*  - However, more code will included in static builds.
*  - Only flag parameter of 0 will perform color conversion.
*/

void al_blit(int flag, AL_BITMAP *source, AL_BITMAP *dest,

            int dest_x, int dest_y);


/* void al_blit_region(int flag, AL_BITMAP *source, int source_x, int source_y,

                      AL_BITMAP* dest, int dest_x, int dest_y,
                      int width, int height)
*/

/* Similarly to al_blit(), al_blit_region() copies a rectangular region of

* the source bitmap to the destination bitmap. The source bitmap
* rectangle is user-specified. The source_x and source_y parameters
* are the coordinates of the top-left corder of the source bitmap
* area to be draw. The dest_x and dest_y are the coordinates of the
* top-left corner in the destination bitmap where the source bitmap area
* will be drawn. The width and height parameters indicate the size
* of the rectangle area to be copied. This routine respects the source
* and destination clipping rectangles.
*
* All the restrictions and freedoms provided by al_blit() are also provided
* by al_blit_region(), including color conversion, blending and hardware
* acceleration.
*
* al_blit(flags, source, dest, dest_x, dest_y) is strictly equivalent to
* al_blit_region(flags, source, 0, 0, dest, dest_x, dest_y, source->w, source->h);
*/

void al_blit_region(int flag, AL_BITMAP *source, int source_x, int source_y,

                   AL_BITMAP* dest, int dest_x, int dest_y,
                   int width, int height);


/* void al_blit_scaled(int flag, AL_BITMAP *source, int source_x, int source_y,

                      int source_w, int source_h, AL_BITMAP *dest,
                      int dest_x, int dest_y, int dest_w, int dest_h)
*/

/* Scales a rectangular area of the source bitmap and draws it into the

* destination bitmap. The source bitmap rectangle is user-specified.
* The source_x and source_y parameters are the coordinates of the top-left
* corder of the source bitmap area to be be stretched. The source_w and
* source_h parameters designate the source rectangle's dimenions in pixels.
* The dest_x and dest_y are the coordinates of the top-left corner in the
* destination bitmap where the source bitmap area will be drawn. The dest_w
* and dest_h parameters indicate the size of the final stretched rectangle
* area to be copied. This routine respects the source and destination
* clipping rectangles.
* 
* Source width/height and destination width/height must be strictly positive
* numbers. If not, the call to al_blit_scaled() is ignored.
*
* The source and destination sizes can be arbitrary. This function can both
* stretch and shrink rectangular areas.
*
* Stretching from overlapping regions results in implementation-defined
* behavior.
*
* The flags parameter is more constrained however. The valid values described
* below can be combined in any way by using a binary OR (|):
*  - AL_MASK_SOURCE - Don't copy source pixels that are of the mask color
*  - AL_MASK_DEST   - Don't copy source pixels if the corresponding
*                     destination pixel is of the mask color
*  - AL_MASK_INV_SOURCE - Don't copy source pixels that are not of the mask
*                         color
*  - AL_MASK_INV_DEST   - Don't copy source pixels if the corresponding
*                         destination pixel is not of the mask color.
*  - AL_HORIZONTAL_FLIP - Flips the source bitmap along the x axis. The top
*                         row of pixels ends up at the bottom and vice versa
*  - AL_VERTICAL_FLIP   - Flips the source bitmap along the y axis. The left
*                         column of pixels ends up at the right and vice versa
*  - AL_FILTER
*
* The alpha channel, if present, is also scaled accordingly.
*/
void al_blit_scaled(int flag, AL_BITMAP *source, int source_x, int source_y,
                    int source_w, int source_h, AL_BITMAP *dest,
                    int dest_x, int dest_y, int dest_w, int dest_h)


/* void al_rotate_bitmap(int flag, AL_BITMAP *source,

                        int source_center_x, int source_center_y,
                        AL_BITMAP *dest, int dest_x, int dest_y, float angle)
*/

/* Rotates the bitmap counter-clockwise by the specified angle. The angle

* is expressed in radians. The center of the rotation is defined by the
* source_center_x and source_center_y parameters relative to the top-left
* corner of the source bitmap, in pixels. The rotated bitmap is drawn into
* the destination bitmap at the location specified by the dest_x and dest_y
* parameters. The destination coordinate is where the rotation center
* of the source bitmap will be drawn.
*
* The flags parameter can be any combination of the following, using
* binary OR (|):
*  - AL_MASK_SOURCE - Don't copy source pixels that are of the mask color
*  - AL_MASK_DEST   - Don't copy source pixels if the corresponding
*                     destination pixel is of the mask color
*  - AL_MASK_INV_SOURCE - Don't copy source pixels that are not of the mask
*                         color
*  - AL_MASK_INV_DEST   - Don't copy source pixels if the corresponding
*                         destination pixel is not of the mask color.
*  - AL_HORIZONTAL_FLIP - Flips the source bitmap along the x axis. The top
*                         row of pixels ends up at the bottom and vice versa
*  - AL_VERTICAL_FLIP   - Flips the source bitmap along the y axis. The left
*                         column of pixels ends up at the right and vice versa
*  - AL_FILTER      - Performs interpolation or filtering on the pixel
*                     data. See al_set_bitmap_filtering() for details.
*
* The alpha channel, if present, is rotated accordingly.
*
* al_rotate_bitmap(flag, source, center_x, center_y, dest, dest_x, dest_y, 
*                  angle)
* is strictly equivalent to 
* al_rotate_scale_bitmap(flag, source, center_x, center_y,
*                        dest, dest_x, dest_y, angle, 1.0, 1.0)
*
* This function respects the source and destination clip rectangles.
*/

void al_rotate_bitmap(int flag, AL_BITMAP *source,

                     int source_center_x, int source_center_y,
                     AL_BITMAP *dest, int dest_x, int dest_y, float angle)


/* void al_rotate_scaled_bitmap(int flag,

                 AL_BITMAP *source, int source_center_x, int source_center_y,
                 AL_BITMAP *dest, int dest_x, int dest_y,
                 float angle, float xscale, float yscale) */

/* Like al_rotate_bitmap() but scales the source bitmap before rotating it.

* The xscale and yscale parameters specify the scaling factor. 1.0 is no
* scaling, 0.5 will half the size of the bitmap while 2.0 will enlarge it.
* The scaling factor can be any floating point value.
*
* The same flags as al_rotate_bitmap() apply to this function.
*
* This function respects the source and destination clip rectangles.
*/

void al_rotate_scaled_bitmap(int flag,

                 AL_BITMAP *source, int source_center_x, int source_center_y,
                 AL_BITMAP *dest, int dest_x, int dest_y,
                 float angle, float xscale, float yscale)


/* void al_blit_region_3(int flag,

                        AL_BITMAP *source1, int source1_x, int source1_y,
                        AL_BITMAP *source2, int source2_x, int source2_y,
                        AL_BITMAP *dest, int dest_x, int dest_y,
                        int dest_w, int dest_h)
*/

/* Some of the blitting modes require reading the destination pixels, such as

* blending or destination masking. However, reading from video memory can be
* quite slow, so it is very much discouraged. Instead, al_blit_3_clip() allows
* the use of a second source bitmap from which the pixels are read. This way,
* the destination bitmap is only written to, never read. This allows for
* very high-speed blending operations on video or display bitmaps. It can
* also be used for cross-fading two images in one pass.
*
* The source image (corresponding to the one in al_blit_clip()) is specified in
* source1. The second source image is specified in source2. The second source
* must either be a memory or system bitmap, or a video bitmap associated to
* the destination bitmap. The second source format and destination format must
* always match. The first source depth may be different from the other two but
* only in the case of alpha-blending 32-bit RGBA sprites into a bitmap of some
* other color depth. In all other cases, the color format of all three bitmaps
* need to match.
*
* The flags parameter is identical to the one in al_blit().
*
* The second source is ignored when flags does not contain AL_BLEND.
*
* The destination and the first source's clip rectangles are respected.
* The second source's clip rectangles are ignored.
*/

void al_blit_region_3(int flag,

                     AL_BITMAP *source1, int source1_x, int source1_y,
                     AL_BITMAP *source2, int source2_x, int source2_y,
                     AL_BITMAP *dest, int dest_x, int dest_y,
                     int dest_w, int dest_h)


/**** Bitmap creation ****/

typedef AL_BITMAP AL_DISPLAY; /* Until we settle on what is what */


/* AL_DISPLAY *al_create_display_bitmap(al_id_t card, int width, int height,

                                       al_id_t format, al_id_t update_method)
*/

/* Creates a display bitmap. A display bitmap is a bitmap that can be shown

* on screen. It represents a bitmap that is directly visible to the user
* (ie: what they see on their monitors).
*
* Display bitmaps differ from regular bitmaps in that they have a user-visible
* and optionally, one or more user-invisible portions. When reading or
* writing to the display bitmap, the invisble portion of the bitmap
* (if present) is read from an writen to. The visible portion of the
* bitmap can only be updated via calls to al_show_display_bitmap().
* Using an invisible backbuffer helps reduce flickering and may
* even speed up some operations.
* Refer to the documentation of al_show_display_bitmap() for details.
*
* Creating a display bitmap may or may not change the monitor's
* resolution. You may or may not have the ability to have more than one
* display bitmap at a time.
*
* Display bitmaps are similar Allegro 4.0's 'screen'.
*
* The 'card' parameter can be one of:
*  - AL_GFX_FULL_SCREEN - Selects a full-screen display bitmap. The screen's
*                         resolution may be changed to accomodate the
*                         required display bitmap settings. Not all platforms
*                         support full screen display bitmaps.
*                         Typically, you can only have one display bitmap
*                         if you are using a full-screen mode. However,
*                         if the platform supports multiple monitors
*                         then multiple full-screen display bitmaps may be
*                         created, each on a different monitor.
*  - AL_GFX_WINDOWED    - Selects a windowed display bitmap. Not all platforms
*                         support windowed display bitmaps. For platforms that
*                         do support windowed bitmaps however, you can create
*                         multiple display bitmaps and Allegro will create and
*                         manage multiple windows.
*  - AL_GFX_SAFE        - Selects a display bitmap that is guaranteed to be
*                         creatable on the current platform. Color space and
*                         depth settings are ignored. You may get virtually any
*                         color depth and color space settings so your
*                         application should be able to work with all possible
*                         combinations.
*                         You may or may not get a full-screen mode. You can
*                         only create a single safe display bitmap; no other
*                         display bitmap can co-exist with a safe display
*                         bitmap.
*  - AL_GFX_AUTODETECT  - Allegro will autodetect whether the current platform
*                         supports windowed or full-screen modes, and will
*                         pick the mode that best matches the gfx configuration
*                         settings.
*
* For example, DOS will only support one full-screen display bitmap.
* Windows95 will support either multiple windowed display bitmaps or a single
* full-screen. Windows98, 2000 and XP can also support multiple full-screen
* display bitmaps if the system has multiple monitors. Under X, you may
* not be able to set a full-screen mode at all.
*
* The width and height parameters specify the size, in pixels, of the display
* bitmap to create.
*
* The update_method parameter is used to specify which method Allegro will use
* to update the visible portion of the display bitmap.
*
* The update_method parameter must be one of the following:
*   - AL_GFX_UPDATE_AUTO == 0
*   - AL_GFX_UPDATE_DIRECT
*   - AL_GFX_UPDATE_DOUBLE_BUFFERING
*   - AL_GFX_UPDATE_DIRTY_RECTANGLES
*   - AL_GFX_UPDATE_DOUBLE_VIDEO_BUFFERING
*   - AL_GFX_UPDATE_PAGE_FLIPPING
*   - AL_GFX_UPDATE_TRIPLE_BUFFERING
*
* Note that the update mode is only a suggestion. Individual drivers are free
* to pick the best matching mode they can get.
*
* See the documentation for al_show_display_bitmap() for the details
* on the display update methods.
*
* (Enumerate config settings)
* (Talk about pixels and screen coordinates?)
*
* Allegro supports several color spaces. The color space is
* specified by the following flags in the format parameter:
*   - AL_RGBA
*   - AL_RGB
*   - AL_PALETTE
*   - AL_YUV
*   - AL_LUMINANCE
*
* These flags select the color space but not the color depth. The depth
* is selected via one of the following flags, which are combined with 
* a binary OR (|) with the previous ones:
*   - AL_COLOR_8
*   - AL_COLOR_8_8_I
*   - AL_COLOR_5_5_5       (==  AL_COLOR_15?)
*   - AL_COLOR_5_6_5       (==  AL_COLOR_16?)
*   - AL_COLOR_8_8_8       (==  AL_COLOR_24?)
*   - AL_COLOR_8_8_8_8     (==  AL_COLOR_32?)
*   - AL_COLOR_10_10_10
*   - AL_COLOR_10_10_10_2
*   - AL_COLOR_16_16_16
*   - AL_COLOR_16_16_16_16
*   - AL_COLOR_32_32_32
*   - AL_COLOR_32_32_32_32 (== AL_COLOR_128?)
*
* The color depth specification can be augmented by the following flags, which
* are combined with a binray OR (|) with the previous ones:
*   - AL_COLOR_INTEGER
*   - AL_COLOR_FLOAT
*
* Note that not all combinations of formats and depths are valie.
*
* If you don't specify the color space, then Allegro will default to
* AL_RGB if there are 3 components, AL_RGBA if there are 4 components
* and AL_PALETTE if there is only one component. If you don't specify
* the color depth, then Allegro will select the desktop color depth
* (if applicable) or some other sensible default depending on the platform.
*
* For example, setting an RGB 5.6.5 16-bpp mode, you'd use:
* 
* AL_BITMAP *screen = al_create_display_bitmap(AL_GFX_AUTO, w, h,
*                     AL_COLOR_5_6_5, AL_GFX_UPDATE_AUTO);
* 
*
* Notice that we don't specify the color space so Allegro will select
* AL_RGB, since AL_COLOR_5_6_5 has 3 components.
*
* A call to al_destroy_bitmap() with a display bitmap as parameter will
* destroy the bitmap. If the display bitmap set a full-screen mode on creation
* then the resolution is restored on destruction.
*
* If Allegro is unable to create the desired display bitmap, or if the
* specified display bitmap is unsupported on the current platform, then
* NULL is returned.
*/

AL_DISPLAY *al_create_display_bitmap(al_id_t card, int width, int height,

                                    al_id_t format, al_id_t update_method)


/* AL_BITMAP *al_create_bitmap(int flags, AL_DISPLAY *inherit_from,

                              int width, int height)
*/

/* Creates a bitmap of size width by height, and returns a pointer to it.

* The bitmap will have clipping turned on, and the clipping rectangle set
* to the full size of the new bitmap. The image memory will not be cleared, so
* it will probably contain garbage: you should initialize the bitmap data
* before using it.
*
* The bitmap's color depth, color component ordering and color space are
* inherited from the bitmap specified in the 'inherit_from' parameter.
* If NULL is used Allegro will use the global color space and depth settings
* instead. (??)
*
* You can select whether to create a memory, a video or a system bitmap
* by specifying the bitmap type in the flags parameter.
*
* Note that system and video bitmaps must always inherit from a display
* bitmap. Video and system bitmaps can only be blitted to memory bitmaps
* or video, system or display bitmaps (and sub-bitmaps thereof) that
* inherit from the same parent display bitmap. That is, you cannot blit
* blit from a video bitmap in display_1 to display_2.
*
* The inherit_from parameter is required for creating video or system bitmaps.
*
* Flags can be only one of:
*  - AL_BITMAP_TYPE_MEMORY == 0
*  - AL_BITMAP_TYPE_VIDEO
*  - AL_BITMAP_TYPE_SYSTEM
*
* This specifies the bitmap type to create.
*
* Additionally, you can OR the flags parameter with:
*  - AL_KEEP_MEMORY_COPY - For video bitmaps onle, specifies that a memory copy
*                          should be kept for high-speed reading. This switch 
*                          also allows the bitmap to be automatically restored
*                          after destructive context switches under Windows.
*                          Note that writes to that bitmap are performed at
*                          half speed, since two bitmaps need to be updated.
*/

AL_BITMAP *al_create_bitmap(int flags, AL_DISPLAY *inherit_from,

                           int width, int height);


/* AL_BITMAP *al_create_bitmap_2(int flags, AL_DISPLAY *inherit_from,

                                int width, int height, al_id_t format)
*/

/* Like al_create_bitmap() except that you can specify the color depth

* and color space for the bitmap. On some platform, video
* and system bitmaps may need to have their color space and depth match the
* display bitmap they are associated to. In that case, if those parameters
* do not match, NULL is returned.
*
* If the format is 0, then the same color depth and format as the
* parent is used.
*
* The format can be any one of the color space formats supported by Allegro.
* See the documentation for al_create_display_bitmap() for details.
*
* Additionally, the following color spaces are supported:
*  - AL_MONOCHROME
*
* The following depths are also supported:
*  - AL_COLOR_1
*/

AL_BITMAP *al_create_bitmap_2(int flags, AL_DISPLAY *inherit_from,

                             int width, int height, al_id_t format);


/* AL_BITMAP *al_compress_bitmap(AL_BITMAP *bmp) */ /* Creates a compressed version of the specified bitmap. Compressed bitmaps

* have additional restrictions over regular bitmaps. You cannot draw
* into a compressed bitmaps.
*
* Compressed bitmaps typically have performence advantages over non-compressed
* bitmaps. Note that compression might be lossy - that is, the compressed
* bitmap may not be pixel-identical to the original bitmap.
*
* The parent bitmap's clipping rectangles are ignored.
*
* The source bitmap data is copied, so you no longer need to have the
* original bitmap around. Destroying the original bitmap will not
* affect operations on the compressed bitmap.
*
* You should destroy the compressed bitmap via a call to al_destroy_bitmap()
* when you are done using it.
*
* The bitmap specified by the 'bmp' parameter is not modified.
*
* If the bitmap is not compressible, NULL is returned.
*
* XXX What else can we say?
*/

AL_BITMAP *al_compress_bitmap(AL_BITMAP *bmp);


/* AL_BITMAP *al_create_sub_bitmap(AL_BITMAP *parent, int x, int y,

                                  int w, int h)
*/

/* Creates a sub-bitmap of the parent, at the specified coordinates and of the

* specified size. A sub-bitmap is a bitmap that shares drawing memory with a
* pre-existing (parent) bitmap, but possibly with a different size and clipping
* settings.
*
* When creating a sub-bitmap of a mode-X display bitmap, the x position must be
* a multiple of four (should we remove this limitation?)
*
* If the sub-bitmap does not lie completely inside the parent bitmap, then
* it is automatically clipped so that it does.
*
* The parent bitmap's clipping rectangles are ignored.
*
* If a sub-bitmap was not or cannot be created then NULL is returned.
*
* Note that destroying parents of sub-bitmaps will not destroy the
* sub-bitmaps; instead the sub-bitmaps become invalid and should no
* longer be used.
*/

AL_BITMAP *al_create_sub_bitmap(AL_BITMAP *parent, int x, int y, int w, int h);


/**** Clipping ****/


/* void al_set_bitmap_clip(AL_BITMAP *bitmap, int id, int x, int y, int w, int h) */ /* Each bitmap has a associated clipping rectangles, which are the areas of

* the image that are allowed to be read and written by Allegro. Nothing
* will be drawn to pixels outside this space.
*
* As Allegro supports multiple clip rectangles, you must specify the id
* number of the clip rectangle you'd like to set up. The id number is
* arbitrary - you can use any number and there is no speed or memory
* penalty for chosing one set of numbers over an other.
*
* By default, the clip rectangle of id 0 is enabled and clips
* the bitmap to its dimensions.
*
* Specify the top-left corner of the clip rectangle by the x and y
* parameters (in pixels), and the size of the rectangle in pixels
* by the width and height parameters.
*
* Width and Height must be non-negative, but can be zero.
*
* Invalid clip rectangles are ignored.
*
* If a clip rectangle is outsize the bitmap, then it itself is clipped
* to the bitmap dimensions.
*
* If there are no enabled clip rectangles, then clipping is disabled, which
* may speed up some drawing operations by a small amount but will result
* in your program dying a horrible death if you try to read or write beyond
* the edges of the bitmap.
*
* The clip rectangles can overlap. Allegro will automatically (and internally)
* adjust the rectangles so that they do not.
*
* If you use an unused id number for the bitmap clip rectangle, then a new clip
* rectangle is created for this bitmap, and is enabled by default.
*/

void al_set_bitmap_clip(AL_BITMAP *bitmap, int id, int x, int y, int w, int h);


/* void al_get_bitmap_clip(AL_BITMAP *bitmap, int id, int *x, int *y, int *w, int *h) */ /* Returns the position and dimension of some clip rectangle for the specified

* bitmap. The position and dimentions are returned by reference from the
* x, y, w and h parameters.
*
* If the clip rectangle associated with the id number specified does not exist
* then 0 is returned in all parameters.
*
* If NULL as passed as one of the references to the position or dimension of
* the clip rectangle, then that parameter is ignored for the purpose of this
* function.
*
* This function will return the user-defined clip rectangle information and
* not the internal information used by Allegro.
*/

void al_get_bitmap_clip(AL_BITMAP *bitmap, int id, int *x, int *y, int *w, int *h);


/* void al_enable_bitmap_clip(AL_BITMAP *bitmap, int id, bool enable) */ /* Enables or disales a clip rectangle. By default, all clip rectangles are enabled.

* If the clip rectangle associted with the id number specified does not exist
* then this function returns immediately and no changes to the bitmap is made.
*/

void al_enable_bitmap_clip(AL_BITMAP *bitmap, int id, bool enable);


/* bool al_is_enabled_bitmap_clip(AL_BITMAP *bitmap, int id) */ /* Querries whether the specified clip rectangle is enabled or not.

*
* If the clip rectangle associted with the id number specified does not exist
* then this function returns FALSE.
*/

bool al_is_enabled_bitmap_clip(AL_BITMAP *bitmap, int id);


/* int al_list_bitmap_clip(AL_BITMAP *bitmap, int *ids, int max_num_id) */ /* This function can be used to list the ids of all existing clip rectangles

* for some bitmap.
*
* If ids is NULL then the number of clip rectangles is returned. In this case,
* the max_num_id parameter is ignored.
*
* If ids is not NULL, then the id numbers of all existing clip rectangles
* are written to the int array pointed by ids. The size of that array
* is specified by the max_num_id parameter. al_list_bitmap_clip() will
* never write more than 'max_num_id' integers in the array pointer by
* 'ids'. The return value is the number of clip rectangle ids written in
* the array.
*
* Here are two examples of the use of this function:
*
* 
* int num_ids = al_list_bitmap_clip(bmp, NULL, 0);
*
* int *id = malloc(sizeof(int) * num_ids);
*
* if (!id) {
*   //handle error
* }
*
* al_list_bitmap_clip(bmp, id, num_ids);
*
* for (i = 0; i < num_ids; i++) {
*    int x, y, w, h;
*    al_get_bitmap_clip(bmp, id[i], &x, &y, &w, &h);
*    printf("Clip rectangle %i at (%i,%i) of size %ix%i\n",
*            id[i], x, y, w, h);
* }
*
* free(id);
* 
*
* 
* int id[10];  // Reserve a safe number
* int num_ids = al_list_bitmap_clip(bmp, id, 10);
*/

int al_list_bitmap_clip(AL_BITMAP *bitmap, int *ids, int num_ids);


/* void al_show_display_bitmap(AL_DISPLAY *display) */ /* The display bitmap is not entirely visible to the user. Depending on the

* update mode selected on creation, there may be invisible buffers associated
* with the display bitmap. Allegro will first draw into those buffers, and
* al_show_display_bitmap() will copy or update those buffers so that what
* has been drawn in them becomes visible on screen. The different update
* methods have various advantages and disadvantages, as listed below.

* Depending on the update method chosen when creating the display bitmap
* al_show_display_bitmap() will perform different actions. The following
* list describes each update method, what al_show_display_bitmap() does
* and why you'd want to use it (or not).
*
* * AL_GFX_UPDATE_AUTO:
*   Allegro will automatically pick the best mode it can find.
*
* * AL_GFX_UPDATE_DIRECT:
*   The display bitmap is directly visible by the user. Any changes can be
*   immediately viewed by the user. This is the method used by Allegro 4.
*   Calls to al_show_display_bitmap() will be silently ignored.
*
* * AL_GFX_UPDATE_DOUBLE_BUFFERING:
*   Double-buffer the display bitmap using a memory bitmap. Drawing into the
*   display bitmap will draw into a memory buffer first. Then, when
*   al_show_display_bitmap() is called, that memory buffer is copied to the
*   video card. Since the contents of the display bitmap are available in
*   system RAM, then reading from that display bitmap is very fast. This
*   implies that al_blit() with operations that require reading the
*   destination bitmap will also run very quickly. However, transfering
*   the contents of the memory buffer to video RAM so it can be displayed
*   is a rather slow process, limiting the achievable frame rate.
*   The contents of the previous frame remains in the memory buffer.
*
* * AL_GFX_UPDATE_DIRTY_RECTANGLES:  (note: Need to change the name - refers to a particular implementation)
*   Much like AL_GFX_UPDATE_DOUBLE_BUFFERING, a secondary memory bitmap is
*   used. This memory bitmap is drawn into by Allegro. When
*   al_show_display_bitmap() is called, only the parts of the display bitmap
*   that have changed are drawn on the visible portion of the screen.
*   This method speeds up the screen updating when the display bitmap's
*   content does not change much in between frames. However, this method
*   may prove to be slower if the entire display bitmap changes since the
*   last call to al_show_display_bitmap().
*   The contents of the previous frame remains in the memory buffer.
*
* * AL_GFX_UPDATE_DOUBLE_VIDEO_BUFFERING:
*   Double-buffer the display bitmap using a video bitmap. This method is
*   similar to AL_GFX_UPDATE_DOUBLE_BUFFERING except that the secondary
*   buffer lives in video memory. This means that reading from the display
*   bitmap is really slow, which will render blending operations nearly
*   useless. It does make updating the visible oprtion of the display
*   bitmap much faster if hardware acceleration is availble (as it is
*   on most video cards these days). Also, drawing into this bitmap
*   from video bitmaps will also be very fast.
*   The contents of the previous frame remains in the video buffer.
*
* * AL_GFX_UPDATE_PAGE_FLIPPING:
*   Uses page flipping with a video bitmap. Instead of copying the contents
*   of the secondary buffer to the visible portion of the display bitmap,
*   the video card is instructed to display that secondary buffer instead,
*   and sets the buffer that was previously visible to be invisible.
*   In other words, the visible and invisible buffers are swapped.
*   This update method can be significantly faster than double buffering.
*   However, Allegro will wait for the vertical retrace signal before updating
*   the display, which means that the framerate is dependent on the monitor
*   refresh rate. On the other hand, waiting for the vertical retrace signal
*   means that the image will not tear. See al_wait_for_vsync() for details.
*   The contents of the previous frame is undefined.
*
* * AL_GFX_UPDATE_TRIPLE_BUFFERING:
*   Like page flipping but uses three buffers instead of just two. This allows
*   the Operating System to perform a swap assynchronously so that no waiting
*   is required.
*   The contents of the previous frame is undefined.
*
* Note that unless the update method is GFX_UPDATE_DIRECT then
* al_show_display_bitmap() must be called to show any update on the
* display.
*/

void al_show_display_bitmap(AL_DISPLAY *display);


/* void al_wait_for_vsync(AL_DISPLAY *display) */ /* Waits for the vertical retrace signal on the specified display bitmap.

* The retrace happens when the electron beam in your monitor has reached
* the bottom of the screen and is moving back to the top ready for another
* scan. During this short period the graphics card isn't sending any data
* to the monitor, so you can do things to it that aren't possible at other
* times, such as altering the palette without causing flickering (snow).
*
* Not every video card support waiting for the vertical refresh signal
* (the Voodoo 3 for example), and some display devices have no concept
* of vertical refresh (such as LCDs), so there may be no wait at all.
*/

void al_wait_for_vsync(AL_DISPLAY *display);


/* void al_destroy_bitmap(AL_BITMAP* bitmap) */ /* Destroys a bitmap. The memory and resources associated with the bitmap

* are released. If the bitmap was a display bitmap in full-screen mode
* then the resolution of the monitor is reset.
* Destroying parents of sub-bitmaps will not destroy the sub-bitmaps;
* instead the sub-bitmaps become invalid and should no longer
* be used.
*
* Note: Perhaps the debug build can keep track of a parent's sub-bitmap
* and flag an error in allegro.log when trying to use a sub-bitmap
* of a destroyed parent.
*/

void al_destroy_bitmap(AL_BITMAP* bitmap); void al_destroy_display_bitmap(AL_DISPLAY *display); /* Only if AL_DISPLAY != AL_BITMAP */



/**** Bitmap locking ****/

/* void al_acquire_bitmap(AL_BITMAP *bitmap) */ /* Acquires the specified video or display bitmap for drawing from or to it.

* This does not apply to memory bitmaps, and only affects some platforms (for
* example, Windows needs it, DOS does not). These calls are not strictly
* required because the drawing routines will automatically acquire the
* bitmap before accessing it. However, acquiring a DirectDraw surface is very
* slow, so you will get much better performance if you acquire the video 
* or display bitmap just once at the start of your main redraw function,
* and only release it when the drawing is completely finished.
*
* Multiple acquire calls may be nested, and the bitmap will only be truly
* released when the lock count returns to zero.
*
* You must release all acquired bitmaps prior to calling
* al_show_display_bitmap().
*
* Be warned that DirectX programs activate a mutex lock whenever a surface
* is locked, which prevents them from getting any input messages, so you
* must be sure to release all your bitmaps before using any timer, keyboard,
* or other non-graphics routines! 
*/

void al_acquire_bitmap(AL_BITMAP *bitmap);


/* void al_release_bitmap(AL_BITMAP *bitmap) */ /* Releases a bitmap that was previously acquired by calling

* al_acquire_bitmap(). If the bitmap was acquired multiple times, you must
* release it the same number of times before it will truly be unlocked. 
*
* You must release all acquired bitmaps prior to calling
* al_show_display_bitmap().
*/

void al_release_bitmap(AL_BITMAP *bitmap);


/**** Primitive functions ****/

/* Most primitive functions take a flags parameter that will determine

* the operation they will perform. Those flags, which are described here,
* can be combined together via a binary OR (|). Not all combinations
* are valid.
*
*  - AL_OUTLINE  == 0
*    The default mode. Primitives drawn with this mode will only have
*    their outlines rendered. For example, drawing a rectangle will
*    only draw the rectangle border. This flag has no meaning for
*    unidimentional primitives such as lines and points.
*    This flag cannot be used in conjunction with AL_FILLED.
*
*  - AL_FILLED
*    Primitives drawn with this mode will have their area filled by
*    their color. For example, drawing a rectangle will fill the 
*    surface enclosed by it with the specified color. This flag
*    has no meaning for unidimentional primitives such as lines and
*    points.
*    This flag cannot be used in conjunction with AL_OUTLINE.
*
*  - AL_PATTERNED
*    Draws the primitive using the pre-set pattern. With the patterned
*    mode, you provide a pattern bitmap which is tiled across the surface
*    of the shape.
*
*  - AL_MASK_DEST
*    Specifies that the destination pixels are not written to if they
*    are of the mask color. This allows you to use the masked area
*    of a bitmap as a drawing mask. You can combine this flag with
*    any of the other primitive flags.
*
*  - AL_MASK_INV_DEST
*    Specifies that the destination pixels are not written to if they
*    are not of the mask color. This allows you to use the masked area
*    of a bitmap as a drawing surface, with the non-masked area left
*    untouched. You can combine this flag with any of the other primitive
*    flags.
*
*  - AL_MASK_SOURCE
*    Specifies that the source pixels are not written to if they
*    are of the mask color. This flag only has meaning when the
*    AL_PATTERNED flag is also used. It is otherwise ignored.
*
*  - AL_MASK_INV_SOURCE
*    Specifies that the source pixels are not written to if they
*    are not of the mask color. This flag only has meaning when the
*    AL_PATTERNED flag is also used. It is otherwise ignored.
*
*  - AL_BLEND
*    The primitive is drawn translucently, using the currently set blender
*    function. See al_set_blender() for details.
*/


/* AL_COLOR *al_get_pixel(AL_BITMAP *bmp, int x, int y, AL_COLOR *color) */ /* Reads a pixel from point (x,y) in the bitmap.

* You need to pass a valid pointer to an AL_COLOR structure as the 'color'
* parameter. This structure will be filled in by al_get_pixel(). This
* procedure is necessary to support bitmaps of arbitrary color depth.
*
* If the point specified by (x,y) lies outside the bitmap's clip
* region, then the color returned is equivalent to pure black
* (red, green and blue are all 0).
*
* The return value is the value passed as the 'color' parameter.
*
* Here's an example use:
* <code>
* AL_COLOR color;
* al_put_pixel(0, bmp2, x, y, al_get_pixel(bmp1, x, y, &color));
* 
*/

AL_COLOR *al_get_pixel(AL_BITMAP *bmp, int x, int y, AL_COLOR *color);


/* void al_put_pixel (int flag, AL_BITMAP *bitmap, int x, int y,

                     AL_COLOR *color)
*/

/* Writes a pixel to the specified position in the bitmap. The primitive flags

* are respected (see above). The bitmap's clipping rectangles are also
* respected.
*
* If NULL is passed as the 'color' parameter, or the pixel coordinates lie
* outside the bitmap, then nothing is done; the function silently fails.
*/

void al_put_pixel(int flag, AL_BITMAP *bitmap, int x, int y, AL_COLOR *color);


/* void al_draw_line (int flag, AL_BITMAP *bitmap, int x1, int y1,

                     int x2, int y2, AL_COLOR *color)
*/

/* Draws a line from point (x1,y1) to point (x2,y2) using the color specified

* by the 'color' parameter. The start and end coordinates are inclusive.
* If the color parameter is NULL then this function silently fails.
*
* The bitmap's clipping rectangles are respected.
*/

void al_draw_line (int flag, AL_BITMAP *bitmap, int x1, int y1, int x2, int y2,

                  AL_COLOR *color);


/* void al_draw_hline(int flag, AL_BITMAP *bitmap, int x, int y, int width,

                     AL_COLOR *color) */

/* Draws a horizontal line from point (x,y) to point (x + width - 1, y). If

* the width is zero or negative, or the color parameter is NULL, then this
* function silently fails.
*
* This function respects the bitmap's clip rectangles.
*
* al_draw_hline(flag, bitmap, x, y, width, color) is equivalent to
* al_draw_line(flag, bitmap, x, y, x + width - 1, y, color) only when
* the width parameter is greater than zero.
*
* If the gfx/current/hw_vram_hline flag is set, and the flag parameter
* is set to AL_OUTLINE or AL_FILLED, then this function is accelerated
* when drawing into video or display bitmaps.
*/

void al_draw_hline(int flag, AL_BITMAP *bitmap, int x, int y, int width,

                  AL_COLOR *color);


/* void al_draw_vline(int flag, AL_BITMAP *bitmap, int x, int y, int height,

                     AL_COLOR *color) */

/* Draws a vertical line from point (x,y) to point (x, y + height - 1). If

* the height is zero or negative, or the color parameter is NULL, then this
* function silently fails.
*
* This function respects the bitmap's clip rectangles.
*
* al_draw_vline(flag, bitmap, x, y, height, color) is equivalent to
* al_draw_line(flag, bitmap, x, y, x, y + height - 1, color) only when
* the height parameter is greater than zero.
*
* If the gfx/current/hw_vram_vline flag is set, and the flag parameter
* is set to AL_OUTLINE or AL_FILLED, then this function is accelerated
* when drawing into video or display bitmaps.
*/

void al_draw_vline(int flag, AL_BITMAP *bitmap, int x, int y, int height,

                  AL_COLOR *color);


/* void al_draw_triangle(int flag, AL_BITMAP *bitmap, int x1, int y1,

                        int x2, int y2, int x3, int y3, AL_COLOR *color)
*/

/* Draws a triangle with the corners at (x1,y1), (x2,y2) and (x3,y2), with the

* specified color. If the color parameter is NULL then this function silently
* fails.
*
* The bitmap's clip rectangles are respected.
*
* Comment: What about the degenerate case?
*
* If the gfx/current/hw_vram_triangle flag is set, and the flag parameter
* is set to AL_OUTLINE or AL_FILLED, then this function is accelerated
* when drawing into video or display bitmaps.
*/

void al_draw_triangle(int flag, AL_BITMAP *bitmap, int x1, int y1,

                     int x2, int y2, int x3, int y3, AL_COLOR *color);


/* void al_draw_polygon(int flag, AL_BITMAP *bitmap, int points[], int num_points, AL_COLOR *color) */ /* Draws an arbitrary polygon on the specified bitmap, using the specified

* color. The polygon can be convex or concave.
*
* The coordinates of the corners are specified by the points array, which
* is an interleaved array of x and y coordinate pairs. That is, the n-th
* point has its x coordiante in points[n * 2] and its y coordinate in
* points[n * 2 + 1]. The number of points in this polygon is specified by the
* num_points parameter. Thus the points[] array much have 2 * num_points
* entries.
*
* The bitmap's clip rectangles are respected.
*
* Comment: What about the degenerate case?
*/

void al_draw_polygon(int flag, AL_BITMAP *bitmap, int points[], int num_points,

                    AL_COLOR *color);


/* void al_draw_ellipse(int flag, AL_BITMAP *bitmap, int x, int y,

                       int width, int height, AL_COLOR *color)
*/

/* Draws an ellipse enclosed in the rectangle specified by the coordinate of

* its top-left corner (x,y) and its size (width,height), with the specified
* color.
*
* If you need to draw a circle of radius r, then simply call:
* 
* al_draw_ellipse(flag, bitmap, x - r, y - r, 2 * r, 2 * r, color);
* 
*
* The bitmap's clip rectangles are respected.
*/

void al_draw_ellipse(int flag, AL_BITMAP *bitmap, int x, int y,

                    int width, int height, AL_COLOR *color);


/* void al_draw_circle(int flag, AL_BITMAP *bitmap, int x, int y, int r,

                      AL_COLOR *color)
*/

/* Draws a circle. Equivalent to:

*
* 
* al_draw_ellipse(flag, bitmap, x - r, y - r, 2 * r, 2 * r, color);
* 
*/

void al_draw_circle(int flag, AL_BITMAP *bitmap, int x, int y, int r,

                   AL_COLOR *color);


/* void al_draw_rect(int flag, AL_BITMAP *bitmap, int x, int y,

                    int width, int height, AL_COLOR *color)
*/

/* Draws a rectangle with the upper-left corner at (x,y), and of size

* (width,height), in pixels. The specified color is used for the drawing.
*
* The bitmap's clip rectangles are respected.
*/  

void al_draw_rect(int flag, AL_BITMAP *bitmap, int x, int y,

                 int width, int height, AL_COLOR *color);


/* void al_floodfill(int flag, AL_BITMAP *bitmap, int x, int y, AL_COLOR *color) */ /* Floodfills an enclosed area, starting at point (x,y), with the specified

* color.
*
* The bitmap's clip rectangles are respected.
*
* Note that this function cannot be hardware accelerated, and that it requires
* reading from the destination bitmap. It is not recommened to use it in
* conjuction with video or display bitmaps.
*/

void al_floodfill(int flag, AL_BITMAP *bitmap, int x, int y, AL_COLOR *color);


/* void al_clear_bitmap(AL_BITMAP *bmp, AL_COLOR *color) */ /* Clears the bitmap using the specified color.

* 
* The bitmap's clip rectangles are NOT respected. If you need to respect
* the clip rectangles, then use al_draw_rect(AL_FILLED,...) instead.
*
* If the gfx/current/hw_vram_clear flag is set then this function is
* accelerated when drawing into video or display bitmaps.
*/

void al_clear_bitmap (AL_BITMAP *bmp, AL_COLOR *color);


/**** Pattern drawing ****/


/* void al_set_pattern(AL_BITMAP *bmp, int mode, AL_BITMAP *pattern,

                      int anchor_x, int anchor_y)
*/

/* Sets the current pattern for pattern drawing.

*
* With the patterned modes, you provide a pattern bitmap which is tiled
* across the surface of the shape. Allegro stores a pointer to this bitmap
* rather than copying it, so you must not destroy the bitmap while it is
* still selected as the pattern. The width and height of the pattern must
* be powers of two, but they can be different, eg. a 64x16 pattern is fine,
* but a 17x3 one is not. The pattern is tiled in a grid starting at point
* (x_anchor, y_anchor). Normally you should just pass zero for these values,
* which lets you draw several adjacent shapes and have the patterns meet up
* exactly along the shared edges. Zero alignment may look peculiar if you
* are moving a patterned shape around the screen, however, because the
* shape will move but the pattern alignment will not, so in some situations
* you may wish to alter the anchor position. 
*
* The set pattern mode only applies to when drawing into the bitmap specified
* by the 'bmp' parameter.
*
* Pattern drawing is enabled by setting the AL_PATTERNED flag on the 'flags'
* parameter of the primitive functions.
*/

void al_set_pattern(AL_BITMAP *bmp, int mode, AL_BITMAP *pattern,

                   int anchor_x, int anchor_y);


/* void al_get_pattern(AL_BITMAP *bmp, int *mode, AL_BITMAP **pattern,

                      int *anchor_x, int *anchor_y)
*/

/* Retreives the current pattern settings of the bitmap specified by the 'bmp'.

* The pattern settings are returned by reference in the following parameters.
* Pass NULL to those parameters to not retrieve them.
*
* If the 'bmp' parameter is NULL, then this function will not write to any
* other parameter.
*/

void al_get_pattern(AL_BITMAP *bmp, int *mode, AL_BITMAP **pattern,

                   int *anchor_x, int *anchor_y);


/* void al_set_bitmap_filter(AL_BITMAP *bmp, int filter) */ /* Sets the bitmap filtering mode. Filtering is enabled whenever AL_FILTERED

* is specified as a parameter to the relevent functions. Filtering only
* affects the source bitmap pixels, before they are drawn into the destination
* bitmap.
*
* Filtering is a hint, so drivers may or may not decide to respect it.
*
* The filter parameter can be any of:
*  - AL_BITMAP_FILTER_NONE
*  - AL_BITMAP_FILTER_BILINEAR
*/

void al_set_bitmap_filter(AL_BITMAP *bmp, int filter);



/**** Color mapping ****/


/* AL_COLOR* al_map_rgb(AL_BITMAP *bmp, AL_COLOR *p,

                       unsigned char r, unsigned char g, unsigned char b)
*/

/* Converts colors from a Red-Green-Blue hardware-independent format to the

* pixel format required by a bitmap. The specific bitmap to convert the
* color to is specified in the 'bmp' parameter. In the 'p' parameter, pass
* a pointer to an already made AL_COLOR object. The 'r', 'g' and 'b'
* parameters specify the intensity of each Red, Green and Blue components,
* respectivally. The range of the color components is from 0 to 255
* included.
*
* If an alpha channel is required, then 255 is automatically used for alpha.
*
* The return value is identical to the 'p' parameter, allowing you
* to chain calls to primitive functions.
*
* If either the 'p' or the 'bmp' parameters are NULL, then this function
* silently fails. In this case, the value of '*p' is not touched.
*
* If the target bitmap uses floating-point components, then the integer
* values in the range 0-255 are first mapped to 0.0-1.0. Only then is the
* final color value computed.
*
* Example use:
*
 *   AL_COLOR color;
 *   al_put_pixel(bmp, x, y, al_map_rgb(bmp, &color, 45, 63, 97));
 * 
*/

AL_COLOR* al_map_rgb(AL_BITMAP *bmp, AL_COLOR *p,

                    unsigned char r, unsigned char g, unsigned char b);


/* AL_COLOR* al_map_rgba(AL_BITMAP *bmp, AL_COLOR *p,

           unsigned char r, unsigned char g, unsigned char b, unsigned char a)
*/

/* Similar to al_map_rgb(), but also includes an alpha component. The alpha

* component should be in the range 0 to 255 included. The alpha component
* is ignored if the bitmap does not support an alpha channel.
*/

AL_COLOR* al_map_rgba(AL_BITMAP *bmp, AL_COLOR *p,

           unsigned char r, unsigned char g, unsigned char b, unsigned char a);


/* AL_COLOR* al_map_rgb_f(AL_BITMAP *bmp, AL_COLOR *p,

                         float r, float g, float b)
*/

/* Similar to al_map_rgb(), but accepts color components as single-precision

* floating-point numbers. The values of 'r', 'g' and 'b' should be in the range
* 0.0 to 1.0 included.
*
* An alpha of 1.0 is automatically inserted if the target bitmap supports an
* alpha channel.
*
* If the target bitmap uses integer components instead of floating-point
* ones, then the floating point components are scaled to the apropreate
* range and converted to integers before the final color value is computed.
*/

AL_COLOR* al_map_rgb_f (AL_BITMAP *bmp, AL_COLOR *p, float r, float g, float b);


/* AL_COLOR* al_map_rgba_f(AL_BITMAP *bmp, AL_COLOR *p,

                          float r, float g, float b, float a)
*/

/* Similar to al_map_rgb_f(), but also includes an alpha component. The alpha

* component should be in the range 0.0 to 1.0 included. The alpha component
* is ignored if the bitmap does not support an alpha channel.
*/

AL_COLOR* al_map_rgba_f(AL_BITMAP *bmp, AL_COLOR *p,

                       float r, float g, float b, float a);


/* AL_COLOR* al_map_rgb_i(AL_BITMAP *bmp, AL_COLOR *p, int r, int g, int b) */ /* Similar to al_map_rgb(), but accepts color components in half the integer

* range. If the target bitmap uses integer components, then the color
* components in the range 0 to INT_MAX are scaled down to the apropreate
* range before the final color value is computed. However, if the target
* bitmap uses floating-point components, then the color components are
* first mapped to the range 0.0 to 1.0 before computing the final color
* value.
*
* An alpha of INT_MAX is assumed for target bitmaps requiring an alpha
* channel.
*/

AL_COLOR* al_map_rgb_i(AL_BITMAP *bmp, AL_COLOR *p, int r, int g, int b);


/* AL_COLOR* al_map_rgba_i(AL_BITMAP *bmp, AL_COLOR *p,

                          int r, int g, int b, int a)
*/

/* Similar to al_map_rgb_i(), but also includes an alpha component. The alpha

* component should be in the range 0 to INT_MAX included. The alpha component
* is ignored if the target bitmap does not support an alpha channel.
*/

AL_COLOR* al_map_rgba_i(AL_BITMAP *bmp, AL_COLOR *p,

                       int r, int g, int b, int a);


/* AL_COLOR* al_map_yuv422(AL_BITMAP *bmp, AL_COLOR *p,

                      unsigned char y, unsigned char u, unsigned char v)

/* Converts colors from a Luma-Chrominance1-Chrominance2 hardware-independent

* format (YCrCb) to the pixel format required by a bitmap. The specific
* bitmap to convert the color to is specified in the 'bmp' parameter. In the
* 'p' parameter, pass a pointer to an already made AL_COLOR object. The
* 'y', 'u' and 'v' parameters specify the value of each Luma, Chrominance1 and
* Chrominance2 components, respectivally. The range of the color components
* is from 0 to 255 included.
*
* If an alpha channel is required, then 255 is automatically used for alpha.
*
* The return value is identical to the 'p' parameter, allowing you
* to chain calls to primitive functions.
*
* If either the 'p' or the 'bmp' parameters are NULL, then this function
* silently fails. In this case, the value of '*p' is not touched.
*
* If the target bitmap uses floating-point components, then the integer
* values in the range 0-255 are first mapped to 0.0-1.0. Only then is the
* final color value computed.
*
* Example use:
*
 *   AL_COLOR color;
 *   al_put_pixel(bmp, x, y, al_map_yuv(bmp, &color, 45, 63, 97));
 * 
*/

AL_COLOR* al_map_yuv422(AL_BITMAP *bmp, AL_COLOR *p,

                       unsigned char y, unsigned char u, unsigned char v);


/* void al_unmap_rgb(AL_BITMAP *bmp, AL_COLOR *p,

                    unsigned char *r, unsigned char *g, unsigned char *b)
*/

/* Performs the opposite operation from al_map_rgb(). The raw color value

* extracted from the specified bitmap is decomposed into its basic
* hardware-independent Red-Green-Blue components.
*
* The extracted color components are in the range 0 to 255 included.
*
* The 'p' parameter points to the raw pixel color that was extracted from the
* bitmap specified in 'bmp' (or sub-bitmap thereof). The 'r', 'g' and 'b'
* parameters will be filled with the extracted color components.
*
* If any of the color component pointers is NULL, then that component
* is not extracted from the raw pixel color.
*
* Example code:
*
 *  unsigned char r, g, b;
 *  AL_COLOR color;
 *  al_unmap_rgb(bmp, al_get_pixel(bmp, &color, x, y), &r, &g, &b);
 *  printf("Red: %u, Green: %u, Blue: %u\n", r, g, b);
 * 
*/

void al_unmap_rgb(AL_BITMAP *bmp, AL_COLOR *p,

                 unsigned char *r, unsigned char *g, unsigned char *b);


/* void al_unmap_rgba(AL_BITMAP *bmp, AL_COLOR *p,

        unsigned char *r, unsigned char *g, unsigned char *b, unsigned char *a)
*/

/* Similar to al_unmap_rgb, but also extracts an alpha component. If the bitmap

* has no alpha channel, then the value 255 is returned through the 'a'
* parameter.
*/

void al_unmap_rgba(AL_BITMAP *bmp, AL_COLOR *p,

       unsigned char *r, unsigned char *g, unsigned char *b, unsigned char *a);


/* void al_unmap_rgb_f(AL_BITMAP *bmp, AL_COLOR *p,

                      float *r, float *g, float *b)
*/

/* Similar to al_unmap_rgb(), but extracts the color components as

* single-precision floating-point numbers, in the range 0.0 to 1.0.
*/

void al_unmap_rgb_f (AL_BITMAP *bmp, AL_COLOR *p, float *r, float *g, float *b);


/* void al_unmap_rgba_f(AL_BITMAP *bmp, AL_COLOR *p,

                       float *r, float *g, float *b, float *a)
*/

/* Similar to al_unmap_rgb_f(), but also extracts an alpha component. If the

* bitmap has no alpha channel, then the value 1.0 is returned through the 'a'
* parameter.
*/

void al_unmap_rgba_f(AL_BITMAP *bmp, AL_COLOR *p,

                    float *r, float *g, float *b, float *a);


/* void al_unmap_rgb_i (AL_BITMAP *bmp, AL_COLOR *p, int *r, int *g, int *b) */ /* Similar to al_unmap_rgb(), but extracts the color components as

* integers in the range 0 to INT_MAX.
*/

void al_unmap_rgb_i (AL_BITMAP *bmp, AL_COLOR *p, int *r, int *g, int *b);


/* void al_unmap_rgba_i(AL_BITMAP *bmp, AL_COLOR *p,

                       int *r, int *g, int *b, int *a);
*/

/* Similar to al_unmap_rgb_i(), but also extracts an alpha component. If the

* bitmap has no alpha channel, then the value INT_MAX is returned through the
* 'a' parameter.
*/

void al_unmap_rgba_i(AL_BITMAP *bmp, AL_COLOR *p,

                    int *r, int *g, int *b, int *a);


/* void al_unmap_yuv422(AL_BITMAP *bmp, AL_COLOR *p,

                       unsigned char *y, unsigned char *u, unsigned char *v)
*/

/* Performs the opposite operation from al_map_yuv(). The raw color value

* extracted from the specified bitmap is decomposed into its basic
* hardware-independent Luma-Chromiance1-Chrominance2 components
* (YCrCb).
*
* The extracted color components are in the range 0 to 255 included.
*
* The 'p' parameter points to the raw pixel color that was extracted from the
* bitmap specified in 'bmp' (or sub-bitmap thereof). The 'y', 'u' and 'v'
* parameters will be filled with the extracted color components.
*
* If any of the color component pointers is NULL, then that component
* is not extracted from the raw pixel color.
  • /

void al_unmap_yuv422(AL_BITMAP *bmp, AL_COLOR *p,

                    unsigned char *y, unsigned char *u, unsigned char *v);



/**** Bitmap properties ****/

/* int al_get_bitmap_color_format(AL_BITMAP *bmp) */ /* Returns the color format of the bitmap specified in the 'bmp' parameter.

*
* The color format is any one of the following:
*   - AL_RGBA
*   - AL_RGB
*   - AL_PALETTE
*   - AL_YUV
*   - AL_LUMINANCE
*   - AL_MONOCHROME
*/

int al_get_bitmap_color_format(AL_BITMAP *bmp);


/* int al_get_bitmap_color_depth(AL_BITMAP *bmp) */ /* Returns the color depth and component arrangement of the bitmap specified

* in the 'bmp' parameter. The color depth and component arrangement is
* specified by one of the following:
*   - AL_COLOR_1
*   - AL_COLOR_8
*   - AL_COLOR_8_8_I
*   - AL_COLOR_5_5_5       (==  AL_COLOR_15?)
*   - AL_COLOR_5_6_5       (==  AL_COLOR_16?)
*   - AL_COLOR_8_8_8       (==  AL_COLOR_24?)
*   - AL_COLOR_8_8_8_8     (==  AL_COLOR_32?)
*   - AL_COLOR_10_10_10
*   - AL_COLOR_10_10_10_2
*   - AL_COLOR_16_16_16
*   - AL_COLOR_16_16_16_16
*   - AL_COLOR_32_32_32
*   - AL_COLOR_32_32_32_32 (== AL_COLOR_128?)
*/

int al_get_bitmap_color_depth(AL_BITMAP *bmp);


/* void al_get_bitmap_component_positions(AL_BITMAP *bmp, int bit[4]) */ /* Returns the color component bit positions.

*
*  bit[]:  RGBA:  YUV:
*   0       R      Y
*   1       G      U
*   2       B      V
*   3       A     N/A
*/

int al_get_bitmap_component_positions(AL_BITMAP *bmp, int bit[4]);


/* AL_COLOR *al_get_bitmap_mask_color(AL_BITMAP *bmp, AL_COLOR *c) */ /* Reads the mask color of the bitmap specified in the 'bmp' parameter

* and stores it in a pre-allocated AL_COLOR structure.
*
* The mask color is typically magic pink for non-paletized bitmaps,
* and 0 for paletized and monochrome bitmaps.
*
* The parameter passed in 'c' is returned.
*
* If either 'bmp' or 'c' are NULL, then this function silently
* fails. Nothing will be written to the color that 'c' points to.
*/

AL_COLOR *al_get_bitmap_mask_color(AL_BITMAP *bmp, AL_COLOR *c);


/* bool al_is_same_bitmap(AL_BITMAP *bmp1, AL_BITMAP *bmp2) */ /* If the bitmaps specified in the 'bmp1' and 'bmp2' parameters describe the

* same drawing surface, ie. the pointers are equal, one is a sub-bitmap of the
* other, or they are both sub-bitmaps of a common parent, then this function
* return TRUE. Otherwise, FALSE is returned.
*
* If either the 'bmp1' or 'bmp2' parameters is NULL, then FALSE is returned.
*/

bool al_is_same_bitmap(AL_BITMAP *bmp1, AL_BITMAP *bmp2);


/* bool al_is_bitmap_of_type(AL_BITMAP *bmp, int type) */ /* Determines whether the bitmap specified in the 'bmp' parameter is of the

* type specified in the 'type' parameter. If it is so, then TRUE is returned.
* otherwise, FALSE is returned.
*
* The 'type' parameter can be any one of the following:
*  - AL_BITMAP_TYPE_MEMORY     - Bitmap is in system RAM
*  - AL_BITMAP_TYPE_RLE        - Bitmap is an RLE-type
*  - AL_BITMAP_TYPE_VIDEO      - Bitmap is in video RAM
*  - AL_BITMAP_TYPE_SYSTEM     - Bitmap is in system RAM but of video format
*  - AL_BITMAP_TYPE_LINEAR     - Bitmap is linear: pixel x+1 is located
*                                immediately after pixel x
*  - AL_BITMAP_TYPE_PLANAR     - Bitmap is planar (see ModeX)
*  - AL_BITMAP_TYPE_SUB_BITMAP - Bitmap is a sub-bitmap
*  - AL_BITMAP_TYPE_DISPLAY    - Bitmap is a display bitmap.
*
* If the 'bmp' parameter is NULL, or the type parameter is not valid, then
* FALSE is returned.
*/

bool al_is_bitmap_of_type(AL_BITMAP *bmp, int type);


/* AL_BITMAP *al_get_bitmap_parent(AL_BITMAP *bmp) */ /* If the bitmap specified in the 'bmp' parameter is a sub-bitmap, then

* a pointer to its parent is returned. Otherwise, NULL is returned.
*/

AL_BITMAP *al_get_bitmap_parent(AL_BITMAP *bmp);



/**** Palettes ****/

/* Palettes

* Notice that palettes are attached to BITMAPS. There are no more global
* palettes.
* Palettes are internal ref-counted objects, which are copied-on-write.
* No calls to vsync() is performed. It's up to the user program to handle that.
*/

void al_set_palette_color(AL_BITMAP *bmp, int index, const AL_COLOR *color); void al_set_palette_range(AL_BITMAP *bmp, int start, int width, const AL_COLOR **palette); AL_COLOR *al_get_palette_color(AL_BITMAP *bmp, int index, AL_COLOR *p); void al_get_palette_range(AL_BITMAP *bmp, int start, int width, AL_COLOR **palette); int al_compute_palette_conversion_table(AL_BITMAP *bmp, AL_RGB_MAP *map); void al_set_palette_conversion_table(AL_BITMAP *bmp, AL_RGB_MAP *map);


/**** File system interaction ****/

/* Allegro supports loading bitmaps from any byte stream. This provides you

* the flexiblity to load bitmaps from custom file systems or even from memory.
*
* Notes:
*  Should the load_bitmap functions take a parent bitmap to inherit properties
*  from? Or should this be a state in al_set_color_conversion()?
*/

AL_BITMAP *al_load_bitmap(const char *filename); AL_BITMAP *al_load_packed_bitmap(PACKFILE *packfile); int al_save_bitmap(AL_BITMAP *bmp, const char *filename); /* Note: bitmap types can be registered via register_driver */


/**** Low-level bitmap access ****/

/* To speed up low-level operations on bitmaps, Allegro provides a way to

* access the bitmap data directly. It is up to you to make sure that you
* write correct information.
*
* Please note that no clipping rectangle affects direct bitmap access,
* and that reading or writing past the end of a line or column may
* crash your program or your computer. You must unselect selected
* regions once you are done with the operation, or risk memory leaks
* or crashes. You must be very careful of what you do when dealing
* directly with bitmaps; Allegro will perform no checking for you.
*
* Once again, when using direct bitmap access, you are on your own.
*
* Allegro supports reading from two source bitmaps simultaniously,
* and writing to one destination bitmap. This allows you to write
* complex blenders or other transforms painlessly while still
* allowing them to run very fast.
*
* Before you can read pixels though, you must first select a read
* region in a bitmap. That bitmap can be any of the bitmaps that
* Allegro supports. Once you have selected a region, you must ask
* for a pointer to a horizontal span. You should only ask for spans
* inside the selected regions. Spans outside or partially outside
* the selected region are left undefined. This means you cannot
* safely access them.
*
* You can query for as many span pointers as you like within the
* selected region. If you need to perform operations on two scan
* lines at a time, for example, you can simply request for two
* pointers inside the selected region.
* 
* Once you have obtained your pointer, you can use any of the
* al_bitmap_read*() or al_bitmap_write*() functions to read/write to the
* selected bitmaps.
*
* Since you can only have one read and write selected region per bitmap
* at a time, setting the selected region to another region inside the same
* bitmap will automatically unselect the previous region.
*
* Once you are done with a bitmap region, you *must* unselect it.
* Failure to do so will leave the system in an undefined state.
*
* Implementation detail: On Windows, you cannot access data in
* Thread-Local Storage while at least one bitmap region is selected.
*
* You can select up to one read and one write region per bitmap at
* a time. You cannot select two read regions on the same bitmap at
* the same time.
*/

/* int al_select_bitmap_read1_region(AL_BITMAP *bitmap, int x, int y, int width, int height) */ /* Selects a region inside the first source bitmap for reading. If a region

* in this bitmap was already selected for reading, then the previous region is
* unselected and the new one selected in its place. Pointers to the old region
* are all invalidated. You will need to query Allegro about new pointers to
* read from this region.
*
* Pass the coordinates of the top-left corner of the bitmap region to select,
* as well as the size of the region to select. If Allegro is unable to select
* that region then this functions returns -1. Otherwise, it returns 0.
*
* Selected a region of height 1 that is entirely inside the bitmap will always
* succeed.
*
* This function is implemented as a macro.
*/

int al_select_bitmap_read1_region(AL_BITMAP *bitmap, int x, int y, int width, int height);


/* int al_select_bitmap_read2_region(AL_BITMAP *bitmap, int x, int y, int width, int height) */ /* Behaves identically to al_select_bitmap_read1_region(), but selects a read

* region inside a second source bitmap.
*
* This function is implemented as a macro.
*/

int al_select_bitmap_read2_region(AL_BITMAP *bitmap, int x, int y, int width, int height);


/* int al_select_bitmap_write_region(AL_BITMAP *bitmap, int x, int y, int width, int height) */ /* Behaves identically to al_select_bitmap_read1_region(), but selects a write

* region inside the destination bitmap. This region may overlap with either
* source bitmaps.
*
* This function is implemented as a macro.
*/

int al_select_bitmap_write_region(AL_BITMAP *bitmap, int x, int y, int width, int height);


/* int al_unselect_bitmap_read1_region(AL_BITMAP *bitmap) */ /* Unselects a read region for the first source bitmap. You must call this

* function once you are done with using Direct Bitmap Access on the
* selected bitmap.
*
* This function is implemented as a macro.
*/

int al_unselect_bitmap_read1_region(AL_BITMAP *bitmap);


/* int al_unselect_bitmap_read2_region(AL_BITMAP *bitmap) */ /* Unselects a read region for the second source bitmap. You must call this

* function once you are done with using Direct Bitmap Access on the
* selected bitmap.
*
* This function is implemented as a macro.
*/

int al_unselect_bitmap_read2_region(AL_BITMAP *bitmap);


/* int al_unselect_bitmap_write_region(AL_BITMAP *bitmap) */ /* Unselects a write region for the destination bitmap. You must call this

* function once you are done with using Direct Bitmap Access on the
* selected bitmap.
*
* This function is implemented as a macro.
*/

int al_unselect_bitmap_write_region(AL_BITMAP *bitmap);


/* void *al_map_bitmap_linear_address(AL_BITMAP *bitmap, int x, int y) */ /* Returns a pointer to the memory region occupied by the bitmap at

* position (x,y). The position must be within one of the the selected
* bitmap regions.
*
* The address returns is linear for a particular horizontal span. That is,
* the pixel at x+1 is immediately after the pixel at x. You need to manually
* update the pointer to reach the other pixels in the same span.
*
* This function is implemented as a macro.
*/

void *al_map_bitmap_linear_address(AL_BITMAP *bitmap, int x, int y);


/* void al_get_bitmap_region_info(BITMAP *bitmap, int region, int *line_stride, int *pixel_stride) */ /* Returns low-level information about a specified bitmap region. The 'bitmap'

* parameter should point to a valid bitmap which has had the proper region
* selected. The 'region' parameter should be one of AL_BITMAP_READ1_REGION,
* AL_BITMAP_READ2_REGION or AL_BITMAP_WRITE_REGION, to specify which region
* to get information from. That region must have been selected prior to this
* call.
*
* Pass in 'line_stride' and 'pixel_stride' pointers to integers which will
* be filled up with the number of bytes between each start of scan line and
* the number of bytes between each start of pixel.
*
* If the bitmap is NULL or the specified region has not been selected,
* then 'line_stride' and 'pixel_stride' are both set to 0. If either
* 'line_stride' or 'pixel_stride' are NULL, then the value of the
* stride for that parameter is not returned.
*/

void al_get_bitmap_region_info(BITMAP *bitmap, int region, int *line_stride, int *pixel_stride)


/* Writes the specified number of bits to the address provided.

* The address must lie within one of the selected bitmap regions.
*
* These functions are implemented as macros. 
*/

void al_bitmap_write_8 (void *address, unsigned char value); void al_bitmap_write_16(void *address, unsigned short value); void al_bitmap_write_32(void *address, unsigned int value); void al_bitmap_write_128(void *address, unsigned int value[4]);

/* Reads the specified number of bits from the address provided.

* The address must lie within one of the selected bitmap regions.
*
* These functions are implemented as macros. 
*/

unsigned char al_bitmap_read_8 (void *address); unsigned short al_bitmap_read_16(void *address); unsigned int al_bitmap_read_32(void *address); unsigned int *al_bitmap_read_128(void *address, unsigned int t[4]); /* I don't really like this one... */


/* Here's a complete example for a simple 16-bpp add blender:

*
* void blend_add(BITMAP *source1, BITMAP *source2, BITMAP *dest) {
*    int i, j;
*    unsigned short *s1, *s2, *d;
*
*    if (source1->w != source2->w || source1->w != dest->w
*         || source1->h != source2->h || source1->h != dest->h)
*         return;
*
*    if (al_get_bitmap_color_space() != AL_RGB
*
*    al_acquire_bitmap(source1);
*    al_acquire_bitmap(source2);
*    al_acquire_bitmap(dest);
*
*    for (j = 0; j < source1->h; j++) {
*
*        al_select_bitmap_read1_region(source1, 0, j, source1->w, 1);
*        al_select_bitmap_read2_region(source2, 0, j, source2->w, 1);
*        al_select_bitmap_write_region(dest,    0, j, dest->w,    1);
*        s1 = al_map_bitmap_linear_address(source1, 0, j);
*        s2 = al_map_bitmap_linear_address(source2, 0, j);
*        d  = al_map_bitmap_linear_address(dest,    0, j);
*
*        for (i = 0; j < source1->w; i++) {
*            unsigned short c1, c2;
*            unsigned int r, g, b;
*
*            c1 = al_bitmap_read_16(s1);
*            c2 = al_bitmap_read_16(s2);
*
*            r = (c1 & 0xF800) + (c2 & 0xF800);
*            g = (c1 & 0x07E0) + (c2 & 0x07E0);
*            b = (c1 & 0x001F) + (c2 & 0x001F);
*
*            r = MIN(r, 0xF800);
*            g = MIN(g, 0x07E0);
*            b = MIN(b, 0x001F);
*
*            al_bitmap_write_16(d, r | g | b);
*
*            s1++;
*            s2++;
*            d++;
*        }
*    }
*
*    al_unselect_bitmap_read1_region(source1);
*    al_unselect_bitmap_read2_region(source2);
*    al_unselect_bitmap_dest_region(dest);
*
*    al_release_bitmap(source1);
*    al_release_bitmap(source2);
*    al_release_bitmap(dest);
*
*    return;
* }
*/


typedef struct AL_COLOR { unsigned long raw[4]; /* 128 bit fragments */ } AL_COLOR;


/*

Configuration routines:

gfx

|- system
    |- num_display_devices Number of display devices on the system (multiple monitors)
    |- num_display_drivers Number of display drivers Allegro can use (AL_GFX_*)
|- current
    |- display_device      Current display device for display bitmap creation and for information retreival
    |- display_bitmap      Currently selected bitmap to change parameters
    |- color_format        Color format for this bitmap
    |- window_x            X Position of the window on the desktop (in pixels)
    |- window_y            Y Position of the window on the desktop (in pixels)
    |- window_scale_x      X scaling factor of the window
    |- window_scale_y      Y scaling factor of the window
    |- resizable           Allow for resize
    |- windowed            Display bitmap is a window
    |- refresh_rate        Monitor refresh rate, in Hz
    |- overlay             Request an overlayed mode
    |- hw_vram_blit        Set to true if hardware accelerated VRAM to VRAM
                           blitting is supported.
|- query
    (similar to ../current, but values are read-only)
    |- driver              Selects the current driver for query
    |- valid               Indicates that the druver or display device query is valid
    |- width               Width, in pixels
    |- height              Height, in pixels
    |- name                Name of the current device or driver
    |- refresh_rate        Monitor refresh rate, in Hz
    |- max_refresh_rate    The maxium refresh rate available
  • /

</highlightSyntax>


Configuration system howto

  • Enumerate all Allegro display drivers:

<highlightSyntax language="c"> int num = al_get_int("gfx/system/num_display_drivers"); for (i = 0; i < num; i++) { al_set_int("gfx/query/driver", i); printf("%s", al_get_string("gfx/query/name"); } </highlightSyntax>

  • Create a YUV 422 overlay

<highlightSyntax language="c"> al_set_boolean("gfx/current/overlay", TRUE); al_set_boolean("gfz/current/windowed", TRUE); AL_BITMAP *screen = al_create_display_bitmap(GFX_AUTO, width, height, AL_8_8_I | AL_YUV, GFX_UPDATE_AUTO);

  • Set a full screen 32-bpp display bitmap on the second monitor

<highlightSyntax language="c"> al_set_int("gfx/current/display_device", 1); al_set_int("gfx/current/windowed", FALSE); AL_BITMAP *screen = al_create_display_bitmap(GFX_AUTO, width, height, AL_32, GFX_UPDATE_AUTO); </highlightSyntax>

  • Display current resolutions of all monitors on the system

<highlightSyntax language="c"> int num = al_get_int("gfx/system/num_display_devices"); for (i = 0; i < num; i++) { al_set_int("gfx/query/display_device", i); printf("%i: %i x %i x %i (%s)\n", i al_get_int("gfx/query/width"), al_get_int("gfx/query/height"), al_get_int("gfx/query/color_depth"), al_get_string("gfx/query/color_space")); } </highlightSyntax>

  • Moves a display bitmap window

<highlightSyntax language="c"> al_set_int("gfx/current/display_bitmap", screen->id); al_set_int("gfx/current/window_x", 55); al_set_int("gfx/current/window_y", 107); </highlightSyntax>