Primitives Addon

# 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