* 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:
*
* 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
*/
Configuration system howto:
- Enumerate all Allegro display drivers:
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");
}
- Create a YUV 422 overlay
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
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);
- Display current resolutions of all monitors on the system
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"));
}
- Moves a display bitmap window
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);