Primitives Addon

High Level Drawing Routines

al_draw_line

void al_draw_line(float x1, float y1, float x2, float y2,
   ALLEGRO_COLOR color, float thickness)

Draws a line segment between two points.

Parameters:

  • x1, y1, x2, y2 - Start and end points of the line
  • color - Color of the line
  • thickness - Thickness of the line, pass <= 0 to draw hairline lines

al_draw_triangle

void al_draw_triangle(float x1, float y1, float x2, float y2,
   float x3, float y3, ALLEGRO_COLOR color, float thickness)

Draws an outlined triangle.

Parameters:

  • x1, y1, x2, y2, x3, y3 - Three points of the triangle
  • color - Color of the triangle
  • thickness - Thickness of the lines, pass <= 0 to draw hairline lines

al_draw_filled_triangle

void al_draw_filled_triangle(float x1, float y1, float x2, float y2,
   float x3, float y3, ALLEGRO_COLOR color)

Draws a filled triangle.

Parameters:

  • x1, y1, x2, y2, x3, y3 - Three points of the triangle
  • color - Color of the triangle

al_draw_rectangle

void al_draw_rectangle(float x1, float y1, float x2, float y2,
   ALLEGRO_COLOR color, float thickness)

Draws an outlined rectangle.

Parameters:

  • x1, y1, x2, y2 - Upper left and lower right points of a triangle
  • color - Color of the rectangle
  • thickness - Thickness of the lines, pass <= 0 to draw hairline lines

al_draw_filled_rectangle

void al_draw_filled_rectangle(float x1, float y1, float x2, float y2,
   ALLEGRO_COLOR color)

Draws a filled rectangle.

Parameters:

  • x1, y1, x2, y2 - Upper left and lower right points of a triangle
  • color - Color of the rectangle

al_calculate_arc

void al_calculate_arc(ALLEGRO_VBUFFER* vbuff, float cx, float cy,
   float rx, float ry, float start_theta, float delta_theta, float thickness,
   int start, int num_segments)

Calculates an elliptical arc, and sets the vertices in a buffer to the calculated positions. If thickness <= 0, then num_points of points are required in the vbuff, otherwise twice as many are needed.

Parameters:

  • vbuff - Vertex buffer to fill out
  • cx, cy - Center of the arc
  • rx, ry - Radii of the arc
  • start_theta - The initial angle from which the arc is calculated
  • delta_theta - Angular span of the arc (pass a negative number to switch direction)
  • thickness - Thickness of the arc
  • start - The index of the first calculated point in the vertex buffer
  • num_points - The number of points to calculate

al_draw_ellipse

void al_draw_ellipse(float cx, float cy, float rx, float ry,
   ALLEGRO_COLOR color, float thickness)

Draws an outlined ellipse.

Parameters:

  • cx, cy - Center of the ellipse
  • rx, ry - Radii of the ellipse
  • color - Color of the ellipse
  • thickness - Thickness of the ellipse, pass <= 0 to draw hairline ellipse

al_draw_filled_ellipse

void al_draw_filled_ellipse(float cx, float cy, float rx, float ry,
   ALLEGRO_COLOR color)

Draws a filled ellipse.

Parameters:

  • cx, cy - Center of the ellipse
  • rx, ry - Radii of the ellipse
  • color - Color of the ellipse

al_draw_circle

void al_draw_circle(float cx, float cy, float r, ALLEGRO_COLOR color,
   float thickness)

Draws an outlined circle.

Parameters:

  • cx, cy - Center of the circle
  • r - Radius of the circle
  • color - Color of the circle
  • thickness - Thickness of the circle, pass <= 0 to draw hairline circle

al_draw_filled_circle

void al_draw_filled_circle(float cx, float cy, float r, ALLEGRO_COLOR color)

Draws a filled circle.

Parameters:

  • cx, cy - Center of the circle
  • r - Radius of the circle
  • color - Color of the circle

al_draw_arc

void al_draw_arc(float cx, float cy, float r, float start_theta,
   float delta_theta, ALLEGRO_COLOR color, float thickness)

Draws an arc.

Parameters:

  • cx, cy - Center of the arc
  • r - Radius of the arc
  • color - Color of the arc
  • start_theta - The initial angle from which the arc is calculated
  • delta_theta - Angular span of the arc (pass a negative number to switch direction)
  • thickness - Thickness of the circle, pass <= 0 to draw hairline circle

al_calculate_spline

void al_calculate_spline(ALLEGRO_VBUFFER* vbuff, float points[8],
   float thickness, int start, int num_segments)

Calculates a spline given 4 control points. If thickness <= 0, then num_segments of points are required in the vbuff, otherwise twice as many are needed.

Parameters:

  • vbuff - Vertex buffer to fill out
  • points - An array of 4 pairs of coordinates of the 4 control points
  • start - The index of the first calculated point in the vertex buffer
  • thickness - Thickness of the spline ribbon
  • num_segments - The number of points to calculate

al_draw_spline

void al_draw_spline(float points[8], ALLEGRO_COLOR color, float thickness)

Draws a spline given 4 control points.

Parameters:

  • points - An array of 4 pairs of coordinates of the 4 control points
  • color - Color of the spline
  • thickness - Thickness of the spline, pass <= 0 to draw hairline spline

al_calculate_ribbon

void al_calculate_ribbon(ALLEGRO_VBUFFER* vbuff, const float *points,
   float thickness, int start, int num_segments)

Calculates a ribbon given an array of points. The ribbon will go through all of the passed points. If thickness <= 0, then num_segments of points are required in the vbuff, otherwise twice as many are needed.

Parameters:

  • vbuff - Vertex buffer to fill out
  • points - An array of pairs of coordinates for each point
  • start - The index of the first calculated point in the vertex buffer
  • thickness - Thickness of the spline ribbon
  • num_segments - The number of points to calculate

al_draw_ribbon

void al_draw_ribbon(const float *points, ALLEGRO_COLOR color, float thickness,
   int num_segments)

Draws a ribbon given given an array of points. The ribbon will go through all of the passed points.

Parameters:

  • points - An array of pairs of coordinates for each point
  • color - Color of the spline
  • thickness - Thickness of the spline, pass <= 0 to draw hairline spline

Low Level Drawing Routines

al_draw_prim

int al_draw_prim(ALLEGRO_VBUFFER* vbuff, ALLEGRO_BITMAP* texture,
   int start, int end, int type)

Draws a subset of the passed vertex buffer.

Parameters:

  • texture - Texture to use, pass 0 to use only shaded primitves
  • vbuff - Vertex buffer to use
  • start, end - Start and end of the subset of the vertex buffer to draw
  • type - Primitive type to draw

Returns: Number of primitives drawn

See Also: ALLEGRO_VBUFFER, ALLEGRO_PRIM_TYPE, al_draw_indexed_prim

al_draw_indexed_prim

int al_draw_indexed_prim(ALLEGRO_VBUFFER* vbuff, ALLEGRO_BITMAP* texture,
   const int* indices, int num_vtx, int type)

Draws a subset of the passed vertex buffer. This function uses an index array to specify which vertices to use.

Parameters:

  • texture - Texture to use, pass 0 to use only shaded primitves
  • vbuff - Vertex buffer to use
  • indices - An array of indices into the vertex buffer
  • num_vtx - Number of indices from the indices array you want to draw
  • type - Primitive type to draw

Returns: Number of primitives drawn

See Also: ALLEGRO_VBUFFER, ALLEGRO_PRIM_TYPE, al_draw_prim

Vertex Buffer Locking

al_lock_vbuff_range

int al_lock_vbuff_range(ALLEGRO_VBUFFER* vbuff, int start, int end)

Locks a range of the vertex buffer.

Parameters:

  • vbuff - Vertex buffer to lock
  • start, end - Range to lock

Returns: 1 if locking was successful, 0 otherwise

See Also: ALLEGRO_VBUFFER

al_lock_vbuff

int al_lock_vbuff(ALLEGRO_VBUFFER* vbuff)

Locks a the whole vertex buffer.

Parameters:

  • vbuff - Vertex buffer to lock

Returns: 1 if locking was successful, 0 otherwise

See Also: ALLEGRO_VBUFFER

al_unlock_vbuff

void al_unlock_vbuff(ALLEGRO_VBUFFER* vbuff)

Unlocks a the whole vertex buffer.

Parameters:

  • vbuff - Vertex buffer to unlock

See Also: ALLEGRO_VBUFFER

al_vbuff_is_locked

int al_vbuff_is_locked(ALLEGRO_VBUFFER* vbuff)

Checks to see if the vertex buffer is locked or not.

Parameters:

  • vbuff - Vertex buffer to check

Returns: 1 if it is locked, 0 otherwise

See Also: ALLEGRO_VBUFFER

al_vbuff_range_is_locked

int al_vbuff_range_is_locked(ALLEGRO_VBUFFER* vbuff, int start, int end)

Checks to see if a range in the vertex buffer is locked or not.

Parameters:

  • vbuff - Vertex buffer to check
  • start, end - Range to check

Returns: 0 if it not locked at all, or the range does not match, 1 otherwise

See Also: ALLEGRO_VBUFFER

Vertex Buffer Access

al_set_vbuff_pos

void al_set_vbuff_pos(ALLEGRO_VBUFFER* vbuff, int idx,
   float x, float y, float z)

Sets the position variables of a vertex in a vertex buffer.

Parameters:

  • vbuff - Vertex buffer to modify
  • idx - Index of the vertex to modify
  • x, y, z - New position

al_set_vbuff_uv

void al_set_vbuff_uv(ALLEGRO_VBUFFER* vbuff, int idx, float u, float v)

Sets the uv coordinates of a vertex in a vertex buffer.

Parameters:

  • vbuff - Vertex buffer to modify
  • idx - Index of the vertex to modify
  • u,v - New texture coordinates

al_set_vbuff_vertex

void al_set_vbuff_vertex(ALLEGRO_VBUFFER* vbuff, int idx,
   const ALLEGRO_VERTEX *vtx)

Sets a vertex in a vertex buffer.

Parameters:

  • vbuff - Vertex buffer to modify
  • idx - Index of the vertex to modify
  • vtx - New vertex definition

al_set_vbuff_color

void al_set_vbuff_color(ALLEGRO_VBUFFER* vbuff, int idx,
   const ALLEGRO_COLOR col)

Sets the colour of a vertex in a vertex buffer.

Parameters:

  • vbuff - Vertex buffer to modify
  • idx - Index of the vertex to modify
  • col - New colour

al_get_vbuff_vertex

void al_get_vbuff_vertex(ALLEGRO_VBUFFER* vbuff, int idx, ALLEGRO_VERTEX *vtx)

Gets a vertex from the vertex buffer.

Parameters:

  • vbuff - Vertex buffer to modify
  • idx - Index of the vertex to modify
  • vtx - Vertex structure to fill out definition

al_get_vbuff_flags

int al_get_vbuff_flags(ALLEGRO_VBUFFER* vbuff)

Return the flags of a vertex buffer

Parameters:

  • vbuff - Vertex buffer to get flags from

Returns: The flags of the buffer

See Also: ALLEGRO_VBUFFER_FLAGS

al_get_vbuff_len

int al_get_vbuff_len(ALLEGRO_VBUFFER* vbuff)

Return the length of a vertex buffer

Parameters:

  • vbuff - Vertex buffer to get length of

Returns: The length of the buffer

al_get_vbuff_lock_range

void al_get_vbuff_lock_range(ALLEGRO_VBUFFER* vbuff, int* start, int* end)

Queries the start and the end of the locked range of a vertex buffer

Parameters:

  • vbuff - Vertex buffer to examine
  • start, end - Will hold the start/end pointers after the call is done

Vertex Buffer Creation/Destruction

al_create_vbuff

ALLEGRO_VBUFFER* al_create_vbuff(int len, int type)

Creates a vertex buffer.

Parameters:

  • len - Number of vertices to put in this buffer
  • type -Type of the vertex buffer to create

Returns: A newly created vertex buffer, 0 on failure.

See Also: ALLEGRO_VBUFFER_FLAGS

al_destroy_vbuff

void al_destroy_vbuff(ALLEGRO_VBUFFER* vbuff)

Destroys a vertex buffer.

Parameters:

  • vbuff - Vertex buffer to destroy. 0 is ignored.

Transformations

al_copy_transform

void al_copy_transform(ALLEGRO_TRANSFORM* src, ALLEGRO_TRANSFORM* dest)

Makes a copy of a transformation.

Parameters:

  • src - Source transformation
  • dest - Destination transformation

al_use_transform

void al_use_transform(ALLEGRO_TRANSFORM* trans)

Sets the transformation to be used for the primitive drawing operations. Every drawing operation after this call will be transformed using this transformation.

Parameters:

  • trans - Transformation to use

al_identity_transform

void al_identity_transform(ALLEGRO_TRANSFORM* trans)

Sets the transformation to be the identity transformation.

Parameters:

  • trans - Transformation to alter

al_build_transform

void al_build_transform(ALLEGRO_TRANSFORM* trans, float x, float y,
   float sx, float sy, float theta)

Builds a transformation given some parameters. This call is equivalent to calling the transformations in this order: make identity, scale, rotate, translate. This method is faster, however.

Parameters:

  • trans - Transformation to alter
  • x, y - Translation
  • sx, sy - Scale
  • theta - Rotation angle

al_translate_transform

void al_translate_transform(ALLEGRO_TRANSFORM* trans, float x, float y)

Apply a translation to a transformation.

Parameters:

  • trans - Transformation to alter
  • x, y - Translation

al_rotate_transform

void al_rotate_transform(ALLEGRO_TRANSFORM* trans, float theta)

Apply a rotation to a transformation.

Parameters:

  • trans - Transformation to alter
  • theta - Rotation angle

al_scale_transform

void al_scale_transform(ALLEGRO_TRANSFORM* trans, float sx, float sy)

Apply a scale to a transformation.

Parameters:

  • trans - Transformation to alter
  • sx, sy - Scale

al_transform_vertex

void al_transform_vertex(ALLEGRO_TRANSFORM* trans, ALLEGRO_VERTEX* vtx)

Transform a vertex.

Parameters:

  • trans - Transformation to use
  • vtx - Vertex to transform

al_transform_transform

void al_transform_transform(ALLEGRO_TRANSFORM* trans, ALLEGRO_TRANSFORM* trans2)

Transform a transformation.

Parameters:

  • trans - Transformation to use
  • trans2 - Transformation to transform

Structures and Types

ALLEGRO_VERTEX

typedef struct {

Defines the generic vertex type, with a 3D position, 4 component colour and texture coordinates for a single texture. If the vertex is within the ALLEGRO_VBUFFER You should use the al_set_vbuff_* functions to manipulate the values within this struct.

  • x, y, z - Position of the vertex. Use z = 0 if you are only dealing with 2D primitives
  • r, g, b, a - Color components
  • u, v - Texture coordinates

ALLEGRO_TRANSFORM

typedef float ALLEGRO_TRANSFORM[4][4];

Defines the generic transformation type, a 4x4 matrix. 2D transforms use only a small subsection of this matrix, namely the top left 2x2 matrix, and the right most 2x1 matrix, for a total of 6 values.

ALLEGRO_VBUFFER

typedef struct ALLEGRO_VBUFFER ALLEGRO_VBUFFER;

Defines the generic vertex buffer type. They hold vertices in an arrangement that is conducive to rapid drawing. Vertex buffers have to be locked to read/write data from them, and have to be unlocked before drawing. Use the various access routines to operate on them, never touching the internal data if possible.

Constants

ALLEGRO_PRIM_TYPE

enum ALLEGRO_PRIM_TYPE {

Enumerates the types of primitves this addon can draw.

  • ALLEGRO_PRIM_LINE_LIST - A list of lines, sequential pairs of vertices define disjointed lines
  • ALLEGRO_PRIM_LINE_STRIP - A strip of lines, sequential vertices define a strip of lines
  • ALLEGRO_PRIM_LINE_LOOP - Like a line strip, except at the end the first and the last vertices are also connected by a line
  • ALLEGRO_PRIM_TRIANGLE_LIST - A list of triangles, sequential triplets of vertices define disjointed triangles
  • ALLEGRO_PRIM_TRIANGLE_STRIP - A strip of triangles, sequential vertices define a strip of triangles
  • ALLEGRO_PRIM_TRIANGLE_FAN - A fan of triangles, all triangles share the first vertex

ALLEGRO_VBUFFER_FLAGS

enum ALLEGRO_VBUFFER_FLAGS {

Enumerates the flags that describe vertex buffers, and access to them. When no flags are set, the vertex buffer is assumed to be an unlocked software 2D vertex buffer.

  • ALLEGRO_VBUFFER_VIDEO - A video buffer, can be drawn by the software backend, and the hardware accelerated backend that created it
  • ALLEGRO_VBUFFER_LOCKED - Signifies that the vertex buffer is locked, meaning you can access its values. A buffer has to be unlocked before it can be drawn
  • ALLEGRO_VBUFFER_3D - Signifies that when drawing this buffer the z coordinate should be taken into account

ALLEGRO_VERTEX_CACHE_SIZE

#define ALLEGRO_VERTEX_CACHE_SIZE 256

Defines the size of the transformation vertex cache for the software renderer. If you pass less than this many vertices to the primitve rendering functions you will get a speed boost.

ALLEGRO_VBUFF_CACHE_SIZE

#define ALLEGRO_VBUFF_CACHE_SIZE 256

Defines the size of the cache vertex buffer, used for the high-level primitives. This corresponds to the maximum number of line segments that will be used to form them.

ALLEGRO_PRIM_QUALITY

#define ALLEGRO_PRIM_QUALITY 10

Defines the quality of the quadratic primitives. At 10, this roughly corresponds to error < 0.5 pixel.

Last updated: 2009-05-04 10:18:46 UTC