Drawing primitives

Except for _putpixel(), all these routines are affected by the current drawing mode and the clipping rectangle of the destination bitmap. Unless specified otherwise, all coordinates for drawing operations are inclusive, and they, as well as lengths, are specified in pixel units.


void clear_bitmap(BITMAP *bitmap);

Clears the bitmap to color 0.
See also: clear_to_color.
Examples using this: Available Allegro examples.
void clear_to_color(BITMAP *bitmap, int color);

Clears the bitmap to the specified color. Example: 
      /* Clear the screen to red. */
      clear_to_color(bmp, makecol(255, 0, 0));
See also: clear_bitmap, makecol.
Examples using this: Available Allegro examples.
void putpixel(BITMAP *bmp, int x, int y, int color);

Writes a pixel to the specified position in the bitmap, using the current drawing mode and the bitmap's clipping rectangle. Example: 
      putpixel(screen, 10, 30, some_color);
See also: getpixel, _putpixel, drawing_mode, makecol.
Examples using this: ex12bit, exalpha, exflame, exjoy, exstars, exswitch.
void _putpixel(BITMAP *bmp, int x, int y, int color);

void _putpixel15(BITMAP *bmp, int x, int y, int color);

void _putpixel16(BITMAP *bmp, int x, int y, int color);

void _putpixel24(BITMAP *bmp, int x, int y, int color);

void _putpixel32(BITMAP *bmp, int x, int y, int color);

Like the regular putpixel(), but much faster because they are implemented as an inline assembler functions for specific color depths. These won't work in mode-X graphics modes, don't perform any clipping (they will crash if you try to draw outside the bitmap!), and ignore the drawing mode.
See also: putpixel, makecol.
int getpixel(BITMAP *bmp, int x, int y);

Reads a pixel from point (x, y) in the bitmap.

Return value: Returns -1 if the point lies outside the bitmap (ignoring the clipping rectangle), otherwise the value of the pixel in the color format of the bitmap.

Warning: -1 is also a valid value for pixels contained in 32-bit bitmaps with alpha channel (when R,G,B,A are all equal to 255) so you can't use the test against -1 as a predicate for such bitmaps. In this cases, the only reliable predicate is is_inside_bitmap().

To extract the individual color components, use the getr() / getg() / getb() / geta() family of functions.

See also: putpixel, _getpixel, is_inside_bitmap, getr, getg, getb, geta, Truecolor pixel formats, Palette routines.
Examples using this: ex12bit, exalpha, exflame, exlights.
int _getpixel(BITMAP *bmp, int x, int y);

int _getpixel15(BITMAP *bmp, int x, int y);

int _getpixel16(BITMAP *bmp, int x, int y);

int _getpixel24(BITMAP *bmp, int x, int y);

int _getpixel32(BITMAP *bmp, int x, int y);

Faster inline versions of getpixel() for specific color depths. These won't work in mode-X, and don't do any clipping, so you must make sure the point lies inside the bitmap.

Return value: Returns the value of the pixel in the color format you specified.

See also: getpixel.
void vline(BITMAP *bmp, int x, int y1, int y2, int color);

Draws a vertical line onto the bitmap, from point (x, y1) to (x, y2).

Note: vline() is implemented as an alias to another function. See ALLEGRO_NO_VHLINE_ALIAS in the `Differences between platforms' section for details.

See also: hline, line, drawing_mode, makecol, Differences between platforms.
Examples using this: exrgbhsv, exscroll, extruec.
void hline(BITMAP *bmp, int x1, int y, int x2, int color);

Draws a horizontal line onto the bitmap, from point (x1, y) to (x2, y).

Note: hline() is implemented as an alias to another function. See ALLEGRO_NO_VHLINE_ALIAS in the `Differences between platforms' section for details.

See also: vline, line, drawing_mode, makecol, Differences between platforms.
Examples using this: exsprite.
void do_line(BITMAP *bmp, int x1, y1, x2, y2, int d, void (*proc)(BITMAP *bmp, int x, int y, int d));

Calculates all the points along a line from point (x1, y1) to (x2, y2), calling the supplied function for each one. This will be passed a copy of the bmp parameter, the x and y position, and a copy of the d parameter, so it is suitable for use with putpixel(). Example: 
      void draw_dust_particle(BITMAP *bmp, int x, int y, int d)
      {
         ...
      }
      
         do_line(screen, 0, 0, SCREEN_W-1, SCREEN_H-2,
                 dust_strength, draw_dust_particle);
See also: do_circle, do_ellipse, do_arc, line.
void line(BITMAP *bmp, int x1, int y1, int x2, int y2, int color);

Draws a line onto the bitmap, from point (x1, y1) to (x2, y2).
See also: fastline, hline, vline, do_line, drawing_mode, makecol.
Examples using this: Available Allegro examples.
void fastline(BITMAP *bmp, int x1, int y1, int x2, int y2, int color);

Faster version of the previous function. Note that pixel correctness is not guaranteed for this function.
See also: line, hline, vline, do_line, drawing_mode, makecol.
Examples using this: Available Allegro examples.
void triangle(BITMAP *bmp, int x1, y1, x2, y2, x3, y3, int color);

Draws a filled triangle between the three points.
See also: polygon, triangle3d, drawing_mode, makecol.
Examples using this: ex3buf, exstars, exupdate.
void polygon(BITMAP *bmp, int vertices, const int *points, int color);

Draws a filled polygon with an arbitrary number of corners. Pass the number of vertices and an array containing a series of x, y points (a total of vertices*2 values). Example: 
      int points[12] = { 50, 50,   100, 100,  100, 150,
                         50, 200,  0,   150,  0,   100 };
      ...
      clear_to_color(screen, makecol(255, 255, 255));
      polygon(screen, 6, points, makecol(0, 0, 0));
See also: triangle, polygon3d, drawing_mode, makecol.
Examples using this: excamera.
void rect(BITMAP *bmp, int x1, int y1, int x2, int y2, int color);

Draws an outline rectangle with the two points as its opposite corners.
See also: rectfill, drawing_mode, makecol.
Examples using this: ex3d, excamera.
void rectfill(BITMAP *bmp, int x1, int y1, int x2, int y2, int color);

Draws a solid, filled rectangle with the two points as its opposite corners.
See also: rect, clear_bitmap, drawing_mode, makecol.
Examples using this: exalpha, excolmap, exkeys, exmidi, expat, exscroll, exsprite, exstars, exswitch, extrans.
void do_circle(BITMAP *bmp, int x, int y, int radius, int d, void (*proc)(BITMAP *bmp, int x, int y, int d));

Calculates all the points in a circle around point (x, y) with radius r, calling the supplied function for each one. This will be passed a copy of the bmp parameter, the x and y position, and a copy of the d parameter, so it is suitable for use with putpixel(). Example: 
      void draw_explosion_ring(BITMAP *bmp, int x, int y, int d)
      {
         ...
      }
      
         do_circle(screen, SCREEN_W/2, SCREEN_H/2,
                   SCREEN_H/16, flame_color,
                   draw_explosion_ring);
See also: do_ellipse, do_arc, do_line, circle, circlefill.
void circle(BITMAP *bmp, int x, int y, int radius, int color);

Draws a circle with the specified centre and radius.
See also: ellipse, arc, circlefill, do_circle, drawing_mode, makecol.
Examples using this: ex12bit, exblend, excustom, exjoy, exmem, exmouse, exquat, exsprite.
void circlefill(BITMAP *bmp, int x, int y, int radius, int color);

Draws a filled circle with the specified centre and radius.
See also: ellipsefill, circle, do_circle, drawing_mode, makecol.
Examples using this: excolmap, excustom, exdbuf, exflip, exlights, expal, exspline, extrans.
void do_ellipse(BITMAP *bmp, int x, int y, int rx, ry, int d, void (*proc)(BITMAP *bmp, int x, int y, int d));

Calculates all the points in an ellipse around point (x, y) with radius rx and ry, calling the supplied function for each one. This will be passed a copy of the bmp parameter, the x and y position, and a copy of the d parameter, so it is suitable for use with putpixel(). Example: 
      void draw_explosion_ring(BITMAP *bmp, int x, int y, int d)
      {
         ...
      }
      
         do_ellipse(screen, SCREEN_W/2, SCREEN_H/2,
                   SCREEN_H/16, SCREEN_H/32, flame_color,
                   draw_explosion_ring);
See also: do_circle, do_arc, do_line, ellipse, ellipsefill.
void ellipse(BITMAP *bmp, int x, int y, int rx, int ry, int color);

Draws an ellipse with the specified centre and radius.
See also: circle, arc, ellipsefill, do_ellipse, drawing_mode, makecol.
void ellipsefill(BITMAP *bmp, int x, int y, int rx, int ry, int color);

Draws a filled ellipse with the specified centre and radius.
See also: circlefill, ellipse, do_ellipse, drawing_mode, makecol.
Examples using this: ex12bit.
void do_arc(BITMAP *bmp, int x, int y, fixed a1, fixed a2, int r, int d, void (*proc)(BITMAP *bmp, int x, int y, int d));

Calculates all the points in a circular arc around point (x, y) with radius r, calling the supplied function for each one. This will be passed a copy of the bmp parameter, the x and y position, and a copy of the d parameter, so it is suitable for use with putpixel(). The arc will be plotted in an anticlockwise direction starting from the angle a1 and ending when it reaches a2. These values are specified in 16.16 fixed point format, with 256 equal to a full circle, 64 a right angle, etc. Zero is to the right of the centre point, and larger values rotate anticlockwise from there. Example: 
      void draw_explosion_ring(BITMAP *bmp, int x, int y, int d)
      {
         ...
      }
         do_arc(screen, SCREEN_W/2, SCREEN_H/2,
             itofix(-21), itofix(43), 50, flame_color,
             draw_explosion_ring);
See also: do_circle, do_ellipse, do_line, arc.
void arc(BITMAP *bmp, int x, y, fixed ang1, ang2, int r, int color);

Draws a circular arc with centre x, y and radius r, in an anticlockwise direction starting from the angle a1 and ending when it reaches a2. These values are specified in 16.16 fixed point format, with 256 equal to a full circle, 64 a right angle, etc. Zero is to the right of the centre point, and larger values rotate anticlockwise from there. Example: 
      /* Draw a black arc from 4 to 1 o'clock. */
      arc(screen, SCREEN_W/2, SCREEN_H/2,
          itofix(-21), itofix(43), 50, makecol(0, 0, 0));
See also: circle, ellipse, drawing_mode, makecol.
void calc_spline(const int points[8], int npts, int *x, int *y);

Calculates a series of npts values along a Bezier spline, storing them in the output x and y arrays. The Bezier curve is specified by the four x/y control points in the points array: points[0] and points[1] contain the coordinates of the first control point, points[2] and points[3] are the second point, etc. Control points 0 and 3 are the ends of the spline, and points 1 and 2 are guides. The curve probably won't pass through points 1 and 2, but they affect the shape of the curve between points 0 and 3 (the lines p0-p1 and p2-p3 are tangents to the spline). The easiest way to think of it is that the curve starts at p0, heading in the direction of p1, but curves round so that it arrives at p3 from the direction of p2. In addition to their role as graphics primitives, spline curves can be useful for constructing smooth paths around a series of control points, as in exspline.c.
See also: spline.
Examples using this: exspline.
void spline(BITMAP *bmp, const int points[8], int color);

Draws a Bezier spline using the four control points specified in the points array. Read the description of calc_spline() for information on how to build the points array.
See also: calc_spline, drawing_mode, makecol.
Examples using this: exspline.
void floodfill(BITMAP *bmp, int x, int y, int color);

Floodfills an enclosed area, starting at point (x, y), with the specified color.
See also: drawing_mode, makecol.
Back to contents