The Allegro Wiki is migrating to github at https://github.com/liballeg/allegro_wiki/wiki

NewAPI/AlternativeGraphics

From Allegro Wiki
Jump to: navigation, search

Structures

ALLEGRO_GRAPHICS

An ALLEGRO_GRAPHICS structure is the backbone of the Allegro graphics API in this proposal. Everything related to drawing to a buffer (on or off screen) happens through an ALLEGRO_GRAPHICS object. Every ALLEGRO_WINDOW and ALLEGRO_BITMAP has it's own ALLEGRO_GRAPHICS object.

ALLEGRO_LOCKED_REGION

Users who wish to manually edit or read from a bitmap are required to lock it first. The ALLEGRO_LOCKED_REGION structure represents the locked region of the bitmap.

<highlightSyntax language="c"> typedef struct ALLEGRO__LOCKED_REGION {

       void *data;
       int format;
       int pitch;

} </highlightSyntax> data points to the actual bitmap data. The format of the data depends on the format of the graphics object that was locked. pitch defines the number of bytes in a single row of bitmap data. The pitch may be greater than pixel_size*width.

ALLEGRO_COLOR

An ALLEGRO_COLOR structure describes a color in a particular pixel format. A color that appears the same in one format may be internally very different in another format. Notably, color->raw[0] does not always represent the same color component (red, green, blue, alpha) and will not always be in the same scale or even data type. Users will not normally have to access the internals of this structure directly. The map_* and unmap_* functions should do the work for them.

<highlightSyntax language="c"> typedef struct ALLEGRO_COLOR {

  uint64_t raw[4];

} </highlightSyntax>


Targets

Every thread has it's own current ALLEGRO_GRAPHICS object. This object is implied with all functions operating on a graphics object.

al_set_current_graphics

Sets the current graphics object for the current thread. <highlightSyntax language="c"> void al_set_current_graphics(ALLEGRO_GRAPHICS *graphics); </highlightSyntax>

al_get_current_graphics

Returns the current graphics object of the current thread. <highlightSyntax language="c"> ALLEGRO_GRAPHICS *al_get_current_graphics(void); </highlightSyntax>


Locking methods

al_lock_graphics

Lock the entire current graphics object for reading or writing. If the graphics object is a display bitmap it will be updated from system memory after the bitmap is unlocked. locked_region must point to an already allocated ALLEGRO_LOCKED_REGION structure. Returns false if the bitmap cannot be locked, e.g. the bitmap was locked previously and not unlocked. Valid flags are:

  • ALLEGRO_LOCK_READONLY - The locked region will not be written to. This can be faster if the bitmap is a video texture, as it can be discarded after the lock instead of uploaded back to the card.

<highlightSyntax language="c"> ALLEGRO_LOCKED_REGION *al_lock_graphics(ALLEGRO_LOCKED_REGION *locked_region, int flags); </highlightSyntax>

al_lock_graphics_rectangle

Like al_lock_graphics but only locks the specified area. If you only need a subsection of a bitmap, this will usually be faster. <highlightSyntax language="c"> ALLEGRO_LOCKED_REGION *al_lock_graphics_rectangle(int x, int y, int width, int height, ALLEGRO_LOCKED_REGION *locked_region, int flags); </highlightSyntax>

al_unlock_graphics

Unlocks a previously locked graphics object, whether the whole bitmap or a rectangle was locked. <highlightSyntax language="c"> void al_unlock_graphics(void); </highlightSyntax>


Color mapping

al_map_rgb

<highlightSyntax language="c"> ALLEGRO_COLOR* al_map_rgb(unsigned char r, unsigned char g, unsigned char b, ALLEGRO_COLOR *p); /* Converts colors from a Red-Green-Blue hardware-independent format to the

* pixel format required by the current graphics object. In the 'p' parameter, pass
* a pointer to an already made ALLEGRO_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 'p' is NULL, then this function silently fails.
* In this case, the value of '*p' is not touched.
*
* If the target graphics object 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:
*
 *   ALLEGRO_COLOR color;
 *   al_put_pixel(x, y, al_map_rgb(&color, 45, 63, 97));
 * 
*/

</highlightSyntax>

al_map_rgba

<highlightSyntax language="c"> ALLEGRO_COLOR* al_map_rgba(unsigned char r, unsigned char g, unsigned char b, unsigned char a, ALLEGRO_COLOR *p); /* 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.
*/

</highlightSyntax>

al_map_rgb_f

<highlightSyntax language="c"> ALLEGRO_COLOR* al_map_rgb_f(float r, float g, float b, ALLEGRO_COLOR *p); /* 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 graphics object 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.
*/

</highlightSyntax>

map_rgba_f

<highlightSyntax language="c"> ALLEGRO_COLOR* al_map_rgba_f(float r, float g, float b, float a, ALLEGRO_COLOR *p); /* 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.
*/

</highlightSyntax>

al_map_rgb_i

<highlightSyntax language="c"> ALLEGRO_COLOR* al_map_rgb_i(int r, int g, int b, ALLEGRO_COLOR *p); /* 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.
*/

</highlightSyntax>

al_map_rgba_i

<highlightSyntax language="c"> ALLEGRO_COLOR* al_map_rgba_i(int r, int g, int b, int a, ALLEGRO_COLOR *p); /* 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.
*/

</highlightSyntax>


Clipping

al_set_graphics_clip

Set the region of the current graphics object that pixels get clipped to. The default is to clip pixels to the entire bitmap. <highlightSyntax language="c"> void al_set_graphics_clip(int x, int y, int width, int height); </highlightSyntax>

al_get_graphics_clip

Gets the current clipping rectangle of the current graphics object. <highlightSyntax language="c"> void al_get_graphics_clip(int *x, int *y, int *width, int *height); </highlightSyntax>

al_enable_graphics_clip

Turn clipping on or off for the current graphics object. <highlightSyntax language="c"> void al_enable_graphics_clip(bool enable); </highlightSyntax>

al_is_graphics_clip_enabled

Check if the current graphics object has clipping enabled. <highlightSyntax> bool al_is_graphics_clip_enabled(void); </highlightSyntax>


Drawing

al_put_pixel

Draw a single pixel onto the current graphics object. <highlightSyntax language="c"> void al_put_pixel(int x, int y, ALLEGRO_COLOR *color); </highlightSyntax>

al_get_pixel

Read a single pixel from the current graphics object. <highlightSyntax language="c"> ALLEGRO_COLOR *al_get_pixel(int x, int y, ALLEGRO_COLOR *color); </highlightSyntax>

al_draw_bitmap

Draws a bitmap onto the current graphics object.

  • For details, see Bob's al_blit. The allowed flags are:
    • ALLEGRO_HORIZONTAL_FLIP
    • ALLEGRO_VERTICAL_FLIP
    • ALLEGRO_MASK_SOURCE - Do not draw pixels of the source bitmap that match the current mask color

<highlightSyntax language="c"> void al_draw_bitmap(ALLEGRO_BITMAP *bitmap, int dx, int dy, int flags) </highlightSyntax>

al_draw_bitmap_region

<highlightSyntax language="c"> void al_draw_bitmap_region(ALLEGRO_BITMAP *bitmap, int sx, int sy, int sw, int sh, int dx, int dy, int flags); /*

* al_draw_bitmap_region(bitmap, 0, 0, w, h, dx, dy, flags)
* is identical to
* al_draw_bitmap(dx, dy, flags)
*/

</highlightSyntax>

al_draw_scaled_bitmap

<highlightSyntax language="c"> al_draw_scaled_bitmap(ALLEGRO_BITMAP *bitmap, int sx, int sy, int swidth, int sheight,

                     int dx, int dy, int dwidth, int dheight, int flags)

/*

* al_draw_scaled_bitmap(bitmap, 0, 0, w, h, dx, dy, w, h, flags)
* is identical to
* al_draw_bitmap(bitmap, dx, dy, flags)
*/

</highlightSyntax>

al_draw_rotated_bitmap

Draws a bitmap rotated counter-clockwise by angle, which is measured in radians. The point center_x, center_y will be drawn at dx, dy with the bitmap rotated around that point. <highlightSyntax language="c"> al_draw_rotated_bitmap(ALLEGRO_BITMAP *bitmap, int center_x, int center_y,

                      int dx, int dy, float angle, int flags)

/*

* al_draw_rotated_bitmap(bitmap, 0, 0, dx, dy, 0, flags)
* is identical to
* al_draw_bitmap(bitmap, dx, dy, flags)
*/

</highlightSyntax>

al_draw_rotated_scaled_bitmap

Like al_draw_rotated_bitmap, but can also scale the bitmap. center_x and center_y are in source bitmap coordinates. <highlightSyntax language="c"> al_draw_rotated_scaled_bitmap(ALLEGRO_BITMAP *bitmap, int center_x, int center_y,

                             int dx, int dy, float x_scale, float y_scale, float angle, int flags)

/*

* al_draw_rotated_scaled_bitmap(bitmap, 0, 0, dx, dy, 1, 1, 0, flags)
* is identical to
* al_draw_bitmap(bitmap, dx, dy, flags)
*/

</highlightSyntax>


Primitives

al_draw_line

Draws a line to the current graphics object. <highlightSyntax language="c"> void al_draw_line(int x1, int y1, int x2, int y2, ALLEGRO_COLOR *color); </highlightSyntax>

al_draw_filled_rectangle

Draws a filled rectangle to the current target. <highlightSyntax language="c"> void al_draw_filled_rectangle(int x1, int y1, int x2, int y2, ALLEGRO_COLOR *color); </highlightSyntax>


Other

al_wait_for_vsync

Waits for the monitor to enter a vertical retrace state. Returns false if not possible, true if successful. <highlightSyntax language="c"> bool al_wait_for_vsync(void); </highlightSyntax>