Unit al5primitives

Returns the (compiled) version of the addon, in the same format as al_get_allegro_version.

Initializes the primitives addon.

Returns

True on success, False on failure.

See also

al_shutdown_primitives_addon

Shut down the primitives addon.

al_is_primitives_addon_initialized

Returns True if the primitives addon is is initialized, otherwise returns false.

Returns True if the primitives addon is is initialized, otherwise returns false.

See also

al_init_primitives_addon

Initializes the primitives addon.

al_shutdown_primitives_addon

Shut down the primitives addon.

Shut down the primitives addon. This is done automatically at program exit, but can be called any time the user wishes as well.

See also

al_init_primitives_addon

Initializes the primitives addon.

al_is_primitives_addon_initialized

Returns True if the primitives addon is is initialized, otherwise returns false.

Draws a subset of the passed vertex array.

For example to draw a textured triangle you could use:

VAR
  v: ARRAY [0..2] OF ALLEGRO_VERTEX = (
    (x: 128, y: 0,   z: 0, color: white, u: 128, v: 0),
    (x: 0,   y: 256, z: 0, color: white, u: 0,   v: 256),
    (x: 256, y: 256, z: 0, color: white, u: 256, v: 256)
  );
BEGIN
  al_draw_prim (v, Texture, 0, 3, ALLEGRO_PRIM_TRIANGLE_LIST)
END;

Parameters

vtxs

Pointer to an array of vertices.

texture

Texture to use, pass Nil to use only color shaded primitves.

start

Start index of the subset of the vertex array to draw.

end

One past the last index of the subset of the vertex array to draw.

Returns

Number of primitives drawn.

See also

al_draw_prim_ex

Extended version of al_draw_prim that allows to define your own vertex type.

ALLEGRO_VERTEX

Defines the generic vertex type, with a 3D position, color and texture coordinates for a single texture.

ALLEGRO_PRIM_TYPE

Enumerates the types of primitives this addon can draw.

ALLEGRO_VERTEX_DECLptr

A vertex declaration.

al_draw_indexed_prim

Draws a subset of the passed vertex array.

Extended version of al_draw_prim that allows to define your own vertex type.

Parameters

vtxs

Pointer to an array of vertices.

decl

Pointer to a vertex declaration. If set to Nil, the vtx are assumed to be of the ALLEGRO_VERTEX type.

texture

Texture to use, pass Nil to use only color shaded primitves.

start

Start index of the subset of the vertex array to draw.

end

One past the last index of the subset of the vertex array to draw.

atype

A member of the ALLEGRO_PRIM_TYPE enumeration, specifying what kind of primitive to draw.

Returns

Number of primitives drawn.

See also

al_draw_prim_ex

Extended version of al_draw_prim that allows to define your own vertex type.

ALLEGRO_VERTEX

Defines the generic vertex type, with a 3D position, color and texture coordinates for a single texture.

ALLEGRO_PRIM_TYPE

Enumerates the types of primitives this addon can draw.

ALLEGRO_VERTEX_DECLptr

A vertex declaration.

al_draw_indexed_prim

Draws a subset of the passed vertex array.

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

Parameters

vtxs

Pointer to an array of vertices.

texture

Texture to use, pass Nil to use only color shaded primitves.

indices

An array of indices into the vertex array.

num_vtx

Number of indices from the indices array you want to draw.

atype

A member of the ALLEGRO_PRIM_TYPE enumeration, specifying what kind of primitive to draw.

Returns

Number of primitives drawn.

See also

al_draw_indexed_prim_ex

Extended version of al_draw_indexed_prim that allows to define your own vertex type.

ALLEGRO_VERTEX

Defines the generic vertex type, with a 3D position, color and texture coordinates for a single texture.

ALLEGRO_PRIM_TYPE

Enumerates the types of primitives this addon can draw.

ALLEGRO_VERTEX_DECLptr

A vertex declaration.

al_draw_prim

Draws a subset of the passed vertex array.

Extended version of al_draw_indexed_prim that allows to define your own vertex type.

Parameters

vtxs

Pointer to an array of vertices.

decl

Pointer to a vertex declaration. If set to Nil, the vtxs are assumed to be of the ALLEGRO_VERTEX type.

texture

Texture to use, pass Nil to use only color shaded primitves.

indices

An array of indices into the vertex array.

num_vtx

Number of indices from the indices array you want to draw.

atype

A member of the ALLEGRO_PRIM_TYPE enumeration, specifying what kind of primitive to draw.

Returns

Number of primitives drawn.

See also

al_draw_indexed_prim

Draws a subset of the passed vertex array.

ALLEGRO_VERTEX

Defines the generic vertex type, with a 3D position, color and texture coordinates for a single texture.

ALLEGRO_PRIM_TYPE

Enumerates the types of primitives this addon can draw.

ALLEGRO_VERTEX_DECLptr

A vertex declaration.

al_draw_prim

Draws a subset of the passed vertex array.

Draws a subset of the passed vertex buffer. The vertex buffer must not be locked. Additionally, to draw onto memory bitmaps or with memory bitmap textures the vertex buffer must support reading (i.e. it must be created with the ALLEGRO_PRIM_BUFFER_READWRITE).

Parameters

vertex_buffer

Vertex buffer to draw.

texture

Texture to use, pass Nil to use only color shaded primitves.

start

Start index of the subset of the vertex buffer to draw.

end

One past the last index of the subset of the vertex buffer to draw.

atype

A member of the ALLEGRO_PRIM_TYPE enumeration, specifying what kind of primitive to draw.

Returns

Number of primitives drawn.

See also

ALLEGRO_VERTEX_BUFFERptr

A GPU vertex buffer that you can use to store vertices on the GPU instead of uploading them afresh during every drawing operation.

ALLEGRO_PRIM_TYPE

Enumerates the types of primitives this addon can draw.

Draws a subset of the passed vertex buffer. This function uses an index buffer to specify which vertices to use. Both buffers must not be locked. Additionally, to draw onto memory bitmaps or with memory bitmap textures both buffers must support reading (i.e. they must be created with the ALLEGRO_PRIM_BUFFER_READWRITE).

Parameters

vertex_buffer

Vertex buffer to draw.

texture

Texture to use, pass Nil to use only color shaded primitves.

index_buffer

Index buffer to use.

start

Start index of the subset of the vertex buffer to draw.

end

One past the last index of the subset of the vertex buffer to draw.

type

A member of the ALLEGRO_PRIM_TYPE enumeration, specifying what kind of primitive to draw. Note that ALLEGRO_PRIM_LINE_LOOP and ALLEGRO_PRIM_POINT_LIST are not supported.

Returns

Number of primitives drawn.

See also

ALLEGRO_VERTEX_BUFFERptr

A GPU vertex buffer that you can use to store vertices on the GPU instead of uploading them afresh during every drawing operation.

ALLEGRO_INDEX_BUFFERptr

A GPU index buffer that you can use to store indices of vertices in a vertex buffer on the GPU instead of uploading them afresh during every drawing operation.

ALLEGRO_PRIM_TYPE

Enumerates the types of primitives this addon can draw.

Creates a vertex declaration, which describes a custom vertex format.

Parameters

elements

An array of ALLEGRO_VERTEX_ELEMENT structures.

stride

Size of the custom vertex structure.

Returns

Newly created vertex declaration.

See also

ALLEGRO_VERTEX_ELEMENT

A small structure describing a certain element of a vertex.

ALLEGRO_VERTEX_DECLptr

A vertex declaration.

al_destroy_vertex_decl

Destroys a vertex declaration.

Destroys a vertex declaration.

Parameters

decl

Vertex declaration to destroy.

See also

ALLEGRO_VERTEX_ELEMENT

A small structure describing a certain element of a vertex.

ALLEGRO_VERTEX_DECLptr

A vertex declaration.

al_create_vertex_decl

Creates a vertex declaration, which describes a custom vertex format.

Creates a vertex buffer. Can return Nil if the buffer could not be created (e.g. the system only supports write-only buffers).

Note

This is an advanced feature, often unsupported on lower-end video cards. Be extra mindful of this function failing and make arrangements for fallback drawing functionality or a nice error message for users with such lower-end cards.

Parameters

initial_data

Memory buffer to copy from to initialize the vertex buffer.

flags

A combination of the ALLEGRO_PRIM_BUFFER_FLAGS flags specifying how this buffer will be created.

See also

al_create_vertex_buffer_ex

Extended version of al_create_vertex_buffer that allows to define your own vertex type.

ALLEGRO_VERTEX_BUFFERptr

A GPU vertex buffer that you can use to store vertices on the GPU instead of uploading them afresh during every drawing operation.

al_destroy_vertex_buffer

Destroys a vertex buffer.

Extended version of al_create_vertex_buffer that allows to define your own vertex type.

Parameters

decl

Vertex type that this buffer will hold. Nil implies that this buffer will hold ALLEGRO_VERTEX vertices.

initial_data

Memory buffer to copy from to initialize the vertex buffer. Can be Nil, in which case the buffer is uninitialized.

num_vertices

Number of vertices the buffer will hold.

flags

A combination of the ALLEGRO_PRIM_BUFFER_FLAGS flags specifying how this buffer will be created.

See also

al_create_vertex_buffer

Creates a vertex buffer.

ALLEGRO_VERTEX_BUFFERptr

A GPU vertex buffer that you can use to store vertices on the GPU instead of uploading them afresh during every drawing operation.

al_destroy_vertex_buffer

Destroys a vertex buffer.

Destroys a vertex buffer. Does nothing if passed Nil.

See also

ALLEGRO_VERTEX_BUFFERptr

A GPU vertex buffer that you can use to store vertices on the GPU instead of uploading them afresh during every drawing operation.

al_create_vertex_buffer

Creates a vertex buffer.

Locks a vertex buffer so you can access its data. Will return Nil if the parameters are invalid, if reading is requested from a write only buffer, or if the buffer is already locked.

Parameters

buffer

Vertex buffer to lock.

offset

Vertex index of the start of the locked range.

length

How many vertices to lock.

flags

ALLEGRO_LOCK_READONLY, ALLEGRO_LOCK_WRITEONLY or ALLEGRO_LOCK_READWRITE.

See also

ALLEGRO_VERTEX_BUFFERptr

A GPU vertex buffer that you can use to store vertices on the GPU instead of uploading them afresh during every drawing operation.

al_unlock_vertex_buffer

Unlocks a previously locked vertex buffer.

Unlocks a previously locked vertex buffer.

See also

ALLEGRO_VERTEX_BUFFERptr

A GPU vertex buffer that you can use to store vertices on the GPU instead of uploading them afresh during every drawing operation.

al_lock_vertex_buffer

Locks a vertex buffer so you can access its data.

Returns the size of the vertex buffer.

See also

ALLEGRO_VERTEX_BUFFERptr

A GPU vertex buffer that you can use to store vertices on the GPU instead of uploading them afresh during every drawing operation.

Creates an index buffer. Can return Nil if the buffer could not be created (e.g. the system only supports write-only buffers).

Note

This is an advanced feature, often unsupported on lower-end video cards. Be extra mindful of this function failing and make arrangements for fallback drawing functionality or a nice error message for users with such lower-end cards.

Parameters

index_size

Size of the index in bytes. Supported sizes are 2 for short integers and 4 for integers.

initial_data

Memory buffer to copy from to initialize the index buffer. Can be Nil, in which case the buffer is uninitialized.

num_indices

Number of indices the buffer will hold.

flags

A combination of the ALLEGRO_PRIM_BUFFER_FLAGS flags specifying how this buffer will be created.

See also

ALLEGRO_INDEX_BUFFERptr

A GPU index buffer that you can use to store indices of vertices in a vertex buffer on the GPU instead of uploading them afresh during every drawing operation.

al_destroy_index_buffer

Destroys an index buffer.

Destroys an index buffer. Does nothing if passed Nil.

See also

ALLEGRO_INDEX_BUFFERptr

A GPU index buffer that you can use to store indices of vertices in a vertex buffer on the GPU instead of uploading them afresh during every drawing operation.

al_create_index_buffer

Creates an index buffer.

Locks an index buffer so you can access its data. Will return Nil if the parameters are invalid, if reading is requested from a write only buffer and if the buffer is already locked.

Parameters

buffer

Index buffer to lock.

offset

Element index of the start of the locked range.

length

How many indices to lock.

flags

ALLEGRO_LOCK_READONLY, ALLEGRO_LOCK_WRITEONLY or ALLEGRO_LOCK_READWRITE.

See also

ALLEGRO_INDEX_BUFFERptr

A GPU index buffer that you can use to store indices of vertices in a vertex buffer on the GPU instead of uploading them afresh during every drawing operation.

al_unlock_index_buffer

Unlocks a previously locked index buffer.

Unlocks a previously locked index buffer.

See also

ALLEGRO_INDEX_BUFFERptr

A GPU index buffer that you can use to store indices of vertices in a vertex buffer on the GPU instead of uploading them afresh during every drawing operation.

al_lock_index_buffer

Locks an index buffer so you can access its data.

Returns the size of the index buffer

See also

ALLEGRO_INDEX_BUFFERptr

A GPU index buffer that you can use to store indices of vertices in a vertex buffer on the GPU instead of uploading them afresh during every drawing operation.

Divides a simple polygon into triangles, with zero or more other simple polygons subtracted from it - the holes. The holes cannot touch or intersect with the outline of the main polygon. Simple means the polygon does not have to be convex but must not be self-overlapping.

Parameters

vertices

Interleaved array of (x, y) vertex coordinates for each of the polygons, including holes.

vertex_stride

Distance (in bytes) between successive pairs of vertices in the array.

vertex_counts

Number of vertices for each polygon. The number of vertices in the main polygon is given by vertex_counts[0] and must be at least three. Subsequent elements indicate the number of vertices in each hole. The array must be terminated with an element with value zero.

emit_triangle

A function to be called for every set of three points that form a triangle. The function is passed the indices of the points in vertices and userdata.

userdata

Arbitrary data to be passed to emit_triangle.

See also

ALLEGRO_EMIT_TRIANGLE_PROC

Callback function used by al_triangulate_polygon.

al_draw_filled_polygon_with_holes

Draws a filled simple polygon with zero or more other simple polygons subtracted from it - the holes.

Draws a triangle using the software rasterizer and user supplied pixel functions. For help in understanding what these functions do, see the implementation of the various shading routines in addons/primitives/tri_soft.c. The triangle is drawn in two segments, from top to bottom. The segments are deliniated by the vertically middle vertex of the triangle. One of the two segments may be absent if two vertices are horizontally collinear.

Parámetros sin terminar de describir. Alguna explicación habrá que ponerla en la descripción del tipo de parámetro.

Parameters

v1

The first vertex of the triangle.

v2

The second vertex of the triangle.

v3

The third vertex of the triangle.

state

A pointer to a user supplied struct, this struct will be passed to all the pixel functions.

init

Called once per call before any drawing is done. The three points passed to it may be altered by clipping.

first

Called twice per call, once per triangle segment.

step

Called once per scanline. The last parameter is set to 1 if the step is a minor step, and 0 if it is a major step.

draw

Called once per scanline.

See also

al_draw_triangle

Draws a line using the software rasterizer and user supplied pixel functions. For help in understanding what these functions do, see the implementation of the various shading routines in addons/primitives/line_soft.c. The line is drawn top to bottom.

Parameters

v1

Initial vertex of the line.

v2

Final vertex of the line.

state

A pointer to a user supplied struct, this struct will be passed to all the pixel functions.

first

Called before drawing the first pixel of the line.

step

Called once per pixel. The second parameter is set to 1 if the step is a minor step, and 0 if this step is a major step. Minor steps are taken only either in x or y directions. Major steps are taken in both directions diagonally. In all cases, the absolute value of the change in coordinate is at most 1 in either direction.

draw

Called once per pixel.

See also

al_draw_line

Draws a line segment between two points.

Draws a line segment between two points.

Parameters

x1

X start point of the line.

y1

Y start point of the line.

x2

X end point of the line.

y2

Y end point of the line.

color

Color of the line.

thickness

Thickness of the line, pass <= 0 to draw hairline lines.

See also

al_draw_soft_line

Draws a line using the software rasterizer and user supplied pixel functions.

Parameters

x1

X coordinate of the first vertex.

y1

Y coordinate of the first vertex.

x2

X coordinate of the second vertex.

y2

Y coordinate of the second vertex.

x3

X coordinate of the third vertex.

y3

Y coordinate of the third vertex.

color

Color of the triangle.

thickness

Thickness of the lines, pass <= 0 to draw hairline lines.

See also

al_draw_filled_triangle

Draws a filled triangle.

al_draw_soft_triangle

Draws a triangle using the software rasterizer and user supplied pixel functions.

Draws an outlined rectangle.

Parameters

x1

Left side of the rectangle.

y1

Top side of the rectangle.

x2

Right side of the rectangle.

y2

Bottom side of the rectangle.

color

Color of the rectangle.

thickness

Thickness of the lines, pass <= 0 to draw hairline lines.

See also

al_draw_filled_rectangle

Draws a filled rectangle.

al_draw_rounded_rectangle

Draws an outlined rounded rectangle.

Draws an outlined rounded rectangle.

Parameters

x1

Left side of the rectangle.

y1

Top side of the rectangle.

x2

Right side of the rectangle.

y2

Bottom side of the rectangle.

rx

Horizontal radius of the round.

ry

Vertical radius of the round.

color

Color of the rectangle.

thickness

Thickness of the lines, pass <= 0 to draw hairline lines.

See also

al_draw_filled_rounded_rectangle

Draws a filled rounded rectangle.

al_draw_rectangle

Draws an outlined rectangle.

When thickness <= 0 this function computes positions of num_points regularly spaced points on an elliptical arc. When thickness > 0 this function computes two sets of points, obtained as follows: the first set is obtained by taking the points computed in the thickness <= 0 case and shifting them by thickness / 2 outward, in a direction perpendicular to the arc curve. The second set is the same, but shifted thickness / 2 inward relative to the arc. The two sets of points are interleaved in the destination buffer (i.e. the first pair of points will be collinear with the arc center, the first point of the pair will be farther from the center than the second point; the next pair will also be collinear, but at a different angle and so on).

The destination buffer dest is interpreted as a set of regularly spaced pairs of floats, each pair holding the coordinates of the corresponding point on the arc. The two floats in the pair are adjacent, and the distance (in bytes) between the addresses of the first float in two successive pairs is stride. For example, if you have a tightly packed array of floats with no spaces between pairs, then stride will be exactly 2 * sizeof (float).

Example with thickness <= 0:

CONST
  NumPoints = 4;
VAR
  Points: ARRAY [0..NumPoints-1, 0..1] OF AL_FLOAT;
BEGIN
  al_calculate_arc (
    Points,
    0, 0,			{ Center }
    10, 10,			{ Radii  }
    0, ALLEGRO_PI / 2,		{ Angles }
    0
  );
END;

Example with thickness > 0:

CONST
  NumPoints = 4;
VAR
  Points: ARRAY [0..(NumPoints * 2)-1, 0..1] OF AL_FLOAT;
BEGIN
  al_calculate_arc (
    Points,
    0, 0,			{ Center }
    10, 10,			{ Radii  }
    0, ALLEGRO_PI / 2,		{ Angles }
    2
  );
END;

Parameters

dest

The destination buffer.

cx

X coordinate of the center of the arc.

cy

Y coordinate of the center of the arc.

rx

Horizontal radius of the arc.

ry

Vertical radius of the arc.

start_theta

The initial angle from which the arc is calculated in radians.

delta_theta

Angular span of the arc in radians (pass a negative number to switch direction).

thickness

Thickness of the arc.

See also

al_calculate_arc_ex

Same than al_calculate_arc but using a pointer instead of an array.

al_draw_arc

Draws an arc.

al_calculate_spline

Calculates a Bézier spline given 4 control points.

al_calculate_ribbon

Calculates a ribbon given an array of points.

Same than al_calculate_arc but using a pointer instead of an array.

Example with thickness <= 0:

CONST
  NumPoints = 4;
VAR
  Points: ARRAY [0..NumPoints-1, 0..1] OF AL_FLOAT;
BEGIN
  al_calculate_arc_ex (
    @points[0, 0],
    2 * sizeof (AL_FLOAT),
    0, 0,			{ Center }
    10, 10,			{ Radii  }
    0, ALLEGRO_PI / 2,		{ Angles }
    0,
    NumPoints
  );
END;

Example with thickness > 0:

CONST
  NumPoints = 4;
VAR
  Points: ARRAY [0..(NumPoints * 2)-1, 0..1] OF AL_FLOAT;
BEGIN
  al_calculate_arc_ex (
    @points[0, 0],
    2 * sizeof (AL_FLOAT),
    0, 0,			{ Center }
    10, 10,			{ Radii  }
    0, ALLEGRO_PI / 2,		{ Angles }
    2,
    NumPoints
  );
END;

Parameters

dest

The destination buffer.

stride

Distance (in bytes) between starts of successive pairs of points.

cx

X coordinate of the center of the arc.

cy

Y coordinate of the center of the arc.

rx

Horizontal radius of the arc.

ry

Vertical radius of the arc.

start_theta

The initial angle from which the arc is calculated in radians.

delta_theta

Angular span of the arc in radians (pass a negative number to switch direction).

thickness

Thickness of the arc.

num_points

The number of points to calculate.

See also

al_calculate_arc

When thickness <= 0 this function computes positions of num_points regularly spaced points on an elliptical arc.

al_draw_arc

Draws an arc.

al_calculate_spline

Calculates a Bézier spline given 4 control points.

al_calculate_ribbon

Calculates a ribbon given an array of points.

Draws an outlined circle.

Parameters

cx

X coordinate of the center of the circle.

cy

Y coordinate of the center of the circle.

r

Radius of the circle.

color

Color of the circle.

thickness

Thickness of the circle, pass <= 0 to draw a hairline circle.

See also

al_draw_filled_circle

Draws a filled circle.

al_draw_ellipse

Draws an outlined ellipse.

Draws an outlined ellipse.

Parameters

cx

X coordinate of the center of the ellipse.

cy

Y coordinate of the center of the ellipse.

rx

Horizontal radius of the ellipse.

ry

Vertical radius of the ellipse.

color

Color of the ellipse.

thickness

Thickness of the ellipse, pass <= 0 to draw a hairline circle.

See also

al_draw_filled_ellipse

Draws a filled ellipse.

al_draw_circle

Draws an outlined circle.

Draws an arc.

Parameters

cx

X coordinate of the center of the arc.

cy

Y coordinate of the center of the arc.

r

Radius of the arc.

start_theta

The initial angle from which the arc is calculated in radians.

delta_theta

Angular span of the arc in radians (pass a negative number to switch direction).

color

Color of the arc.

thickness

Thickness of the circle, pass <= 0 to draw a hairline circle.

See also

al_calculate_arc

When thickness <= 0 this function computes positions of num_points regularly spaced points on an elliptical arc.

al_draw_elliptical_arc

Draws an elliptical arc.

Draws an elliptical arc.

Parameters

cx

X coordinate of the center of the arc.

cy

Y coordinate of the center of the arc.

rx

Horizontal radius of the arc.

ry

Vertical radius of the arc.

start_theta

The initial angle from which the arc is calculated in radians.

delta_theta

Angular span of the arc in radians (pass a negative number to switch direction).

color

Color of the arc.

thickness

Thickness of the arc, pass <= 0 to draw a hairline circle.

See also

al_calculate_arc

When thickness <= 0 this function computes positions of num_points regularly spaced points on an elliptical arc.

al_draw_arc

Draws an arc.

Draws a pieslice (outlined circular sector).

Parameters

cx

X coordinate of the center of the pieslice.

cy

Y coordinate of the center of the pieslice.

r

Radius of the pieslice.

start_theta

The initial angle from which the arc is calculated in radians.

delta_theta

Angular span of the arc in radians (pass a negative number to switch direction).

color

Color of the pieslice.

thickness

Thickness of the pieslice, pass <= 0 to draw a hairline circle.

See also

al_draw_filled_pieslice

Draws a filled pieslice (filled circular sector).

Calculates a Bézier spline given 4 control points. If thickness <= 0, then num_segments of points are required in the destination, otherwise twice as many are needed. The destination buffer should consist of regularly spaced (by distance of stride bytes) doublets of floats, corresponding to x and y coordinates of the vertices.

Parameters

dest

The destination buffer.

stride

Distance (in bytes) between starts of successive pairs of coordinates.

points

An array of 4 pairs of coordinates of the 4 control points.

thickness

Thickness of the spline ribbon.

num_segments

The number of points to calculate.

See also

al_draw_spline

Draws a Bézier spline given 4 control points.

al_calculate_arc

When thickness <= 0 this function computes positions of num_points regularly spaced points on an elliptical arc.

al_calculate_ribbon

Calculates a ribbon given an array of points.

al_draw_spline

Draws a Bézier spline given 4 control points.

Draws a Bézier 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 a hairline spline.

See also

al_calculate_spline

Calculates a Bézier spline given 4 control points.

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 destination buffer, otherwise twice as many are needed. The destination and the points buffer should consist of regularly spaced doublets of floats, corresponding to x and y coordinates of the vertices.

Parameters

dest

Pointer to the destination buffer.

dest_stride

Distance (in bytes) between starts of successive pairs of coordinates in the destination buffer.

points

An array of pairs of coordinates for each point.

points_stride

Distance (in bytes) between starts of successive pairs of coordinates in the points buffer.

thickness

Thickness of the spline ribbon.

num_segments

The number of points to calculate.

See also

al_draw_ribbon

Draws a ribbon given an array of points.

al_calculate_arc

When thickness <= 0 this function computes positions of num_points regularly spaced points on an elliptical arc.

al_calculate_spline

Calculates a Bézier spline given 4 control points.

al_draw_ribbon

Draws a ribbon given an array of points.

Draws a ribbon given an array of points. The ribbon will go through all of the passed points. The points buffer should consist of regularly spaced doublets of floats, corresponding to x and y coordinates of the vertices.

Parameters

points

An array of coordinate pairs (x and y) for each point.

points_stride

Distance (in bytes) between starts of successive pairs of coordinates in the points buffer.

color

Color of the spline.

thickness

Thickness of the spline, pass <= 0 to draw hairline spline.

num_segments

The number of segments.

See also

al_calculate_ribbon

Calculates a ribbon given an array of points.

Draws a filled triangle.

Parameters

x1

X coordinate of the first vertex.

y1

Y coordinate of the first vertex.

x2

X coordinate of the second vertex.

y2

Y coordinate of the second vertex.

x3

X coordinate of the third vertex.

y3

Y coordinate of the third vertex.

color

Color of the triangle.

See also

al_draw_triangle

Draws a filled rectangle.

Parameters

x1

Left side of the rectangle.

y1

Top side of the rectangle.

x2

Right side of the rectangle.

y2

Bottom side of the rectangle.

color

Color of the rectangle.

See also

al_draw_rectangle

Draws an outlined rectangle.

al_draw_filled_rounded_rectangle

Draws a filled rounded rectangle.

Draws a filled ellipse.

Parameters

cx

X coordinate of the center of the ellipse.

cy

Y coordinate of the center of the ellipse.

rx

Horizontal radius of the ellipse.

ry

Vertical radius of the ellipse.

color

Color of the ellipse.

See also

al_draw_ellipse

Draws an outlined ellipse.

al_draw_filled_circle

Draws a filled circle.

Draws a filled circle.

Parameters

cx

X coordinate of the center of the circle.

cy

Y coordinate of the center of the circle.

r

Radius of the circle.

color

Color of the circle.

See also

al_draw_circle

Draws an outlined circle.

al_draw_filled_ellipse

Draws a filled ellipse.

Draws a filled pieslice (filled circular sector).

Parameters

cx

X coordinate of the center of the pieslice.

cy

Y coordinate of the center of the pieslice.

r

Radius of the pieslice.

start_theta

The initial angle from which the arc is calculated in radians.

delta_theta

Angular span of the arc in radians (pass a negative number to switch direction).

color

Color of the pieslice.

See also

al_draw_pieslice

Draws a pieslice (outlined circular sector).

Draws a filled rounded rectangle.

Parameters

x1

Left side of the rectangle.

y1

Top side of the rectangle.

x2

Right side of the rectangle.

y2

Bottom side of the rectangle.

rx

Horizontal radius of the round.

ry

Vertical radius of the round.

color

Color of the rectangle.

See also

al_draw_rounded_rectangle

Draws an outlined rounded rectangle.

al_draw_filled_rectangle

Draws a filled rectangle.

Draws a series of line segments.

Parameters

vertices

Interleaved array of (x, y) vertex coordinates.

join_style

Member of ALLEGRO_LINE_JOIN specifying how to render the joins between line segments.

cap_style

Member of ALLEGRO_LINE_CAP specifying how to render the end caps.

color

Color of the line.

thickness

Thickness of the line, pass <= 0 to draw hairline lines.

miter_limit

Parameter for miter join style.

See also

al_draw_polygon

Draws an unfilled polygon.

ALLEGRO_LINE_JOIN

See the picture for the difference.

ALLEGRO_LINE_CAP

See the picture for the difference.

An extended version of al_draw_polyline.

The stride is normally 2 * sizeof (float) but may be more if the vertex coordinates are in an array of some structure type, e.g.

TYPE
  VertexInfo = RECORD
    x, y: AL_FLOAT;
    id: INTEGER;
  END;

PROCEDURE MyDraw (Verts: ARRAY OF VertexInfo; Clr: ALLEGRO_COLOR);
BEGIN
  al_draw_polyline_ex (
    POINTER (@Verts[0]),
    SIZEOF (VertexInfo),
    Length (Verts),
    ALLEGRO_LINE_JOIN_NONE,
    ALLEGRO_LINE_CAP_NONE,
    Clr,
    1, 1
  )
END;

The stride may also be negative if the vertices are stored in reverse order.

Parameters

vertices

Interleaved array of (x, y) vertex coordinates.

vertex_stride

the number of bytes between pairs of vertices (the stride).

vertex_count

Number of vertices in the array.

join_style

Member of ALLEGRO_LINE_JOIN specifying how to render the joins between line segments.

cap_style

Member of ALLEGRO_LINE_CAP specifying how to render the end caps.

color

Color of the line.

thickness

Thickness of the line, pass <= 0 to draw hairline lines.

miter_limit

Parameter for miter join style.

See also

al_draw_polygon

Draws an unfilled polygon.

ALLEGRO_LINE_JOIN

See the picture for the difference.

ALLEGRO_LINE_CAP

See the picture for the difference.

Draws an unfilled polygon. This is the same as passing ALLEGRO_LINE_CAP to al_draw_polyline.

Parameters

vertex

Interleaved array of (x, y) vertex coordinates.

join_style

Member of ALLEGRO_LINE_JOIN specifying how to render the joins between line segments.

color

Color of the line.

thickness

Thickness of the line, pass <= 0 to draw hairline lines.

miter_limit

Parameter for miter join style.

See also

al_draw_filled_polygon

Draw a filled, simple polygon.

al_draw_polyline

Draws a series of line segments.

ALLEGRO_LINE_JOIN

See the picture for the difference.

Draw a filled, simple polygon. Simple means it does not have to be convex but must not be self-overlapping.

When the y-axis is facing downwards (the usual), the coordinates must be ordered anti-clockwise.

Parameters

vertices

Interleaved array of (x, y) vertex coordinates.

color

Color of the filled polygon.

See also

al_draw_polygon

Draws an unfilled polygon.

al_draw_filled_polygon_with_holes

Draws a filled simple polygon with zero or more other simple polygons subtracted from it - the holes.

Draws a filled simple polygon with zero or more other simple polygons subtracted from it - the holes. The holes cannot touch or intersect with the outline of the filled polygon.

All hole vertices must use the opposite order (clockwise with y down) of the polygon vertices. All hole vertices must be inside the main polygon and no hole may overlap the main polygon.

For example:

VAR
  Vertices: ARRAY [0..13] OF AL_FLOAT = (
      0,   0, { Filled polygon, upper left corner. }
      0, 100, { Filled polygon, lower left corner. }
    100, 100, { Filled polygon, lower right corner. }
    100,   0, { Filled polygon, upper right corner. }
     10,  10, { Hole, upper left. }
     90,  10, { Hole, upper right. }
     90,  90  { Hole, lower right. }
  );
  VertexCounts: ARRAY [0..2] OF AL_INT = (
    4, { number of vertices for filled polygon. }
    3, { number of vertices for hole. }
    0  { terminator. }
  );

There are 7 vertices: four for an outer square from (0, 0) to (100, 100) in anti-clockwise order, and three more for an inner triangle in clockwise order. The outer main polygon uses vertices 0 to 3 (inclusive) and the hole uses vertices 4 to 6 (inclusive).

Parameters

vertices

Interleaved array of (x, y) vertex coordinates for each of the polygons, including holes.

vertex_counts

Number of vertices for each polygon. The number of vertices in the filled polygon is given by vertex_counts[0] and must be at least three. Subsequent elements indicate the number of vertices in each hole. The array must be terminated with an element with value zero.

color

Color of the filled polygon.

See also

al_draw_filled_polygon

Draw a filled, simple polygon.

al_draw_filled_polygon_with_holes

Draws a filled simple polygon with zero or more other simple polygons subtracted from it - the holes.

al_triangulate_polygon

Divides a simple polygon into triangles, with zero or more other simple polygons subtracted from it - the holes.

Enumerates the types of primitives this addon can draw.

Values

• 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_PRIM_POINT_LIST: A list of points, each vertex defines a point.
• ALLEGRO_PRIM_NUM_TYPES

Enumerates the types of vertex attributes that a custom vertex may have.

See also

ALLEGRO_VERTEX_DECLptr

A vertex declaration.

ALLEGRO_PRIM_STORAGE

Enumerates the types of storage an attribute of a custom vertex may be stored in.

Values

• ALLEGRO_PRIM_ATTR_NONE = 0
• ALLEGRO_PRIM_POSITION = 1: Position information, can be stored only in ALLEGRO_PRIM_SHORT_2, ALLEGRO_PRIM_FLOAT_2 and ALLEGRO_PRIM_FLOAT_3.
• ALLEGRO_PRIM_COLOR_ATTR: Color information, stored in an ALLEGRO_COLOR. The storage field of ALLEGRO_VERTEX_ELEMENT is ignored.
• ALLEGRO_PRIM_TEX_COORD: Texture coordinate information, can be stored only in ALLEGRO_PRIM_FLOAT_2 and ALLEGRO_PRIM_SHORT_2. These coordinates are normalized by the width and height of the texture, meaning that the bottom-right corner has texture coordinates of (1, 1).
• ALLEGRO_PRIM_TEX_COORD_PIXEL: Texture coordinate information, can be stored only in ALLEGRO_PRIM_FLOAT_2 and ALLEGRO_PRIM_SHORT_2. These coordinates are measured in pixels.
• ALLEGRO_PRIM_USER_ATTR: A user specified attribute. You can use any storage for this attribute. You may have at most 10 of these that you can specify by adding an index to the identifier, e.g. the first user attribute is ALLEGRO_PRIM_USER_ATTR, the second is ALLEGRO_PRIM_USER_ATTR2 and so on.

  To access these custom attributes from GLSL shaders you need to declare attributes that follow this nomenclature: user_attr_# where # is the index of the attribute.

  To access these custom attributes from HLSL you need to declare a parameter with the following semantics: TEXCOORD{# + 2} where # is the index of the attribute. E.g. the first attribute can be accessed via TEXCOORD2, second via TEXCOORD3 and so on.

• ALLEGRO_PRIM_USER_ATTR2
• ALLEGRO_PRIM_USER_ATTR3
• ALLEGRO_PRIM_USER_ATTR4
• ALLEGRO_PRIM_USER_ATTR5
• ALLEGRO_PRIM_USER_ATTR6
• ALLEGRO_PRIM_USER_ATTR7
• ALLEGRO_PRIM_USER_ATTR8
• ALLEGRO_PRIM_USER_ATTR9
• ALLEGRO_PRIM_USER_ATTR10
• ALLEGRO_PRIM_ATTR_NUM

Enumerates the types of storage an attribute of a custom vertex may be stored in. Many of these can only be used for ALLEGRO_PRIM_USER_ATTR attributes and can only be accessed via shaders. Usually no matter what the storage is specified the attribute gets converted to single precision floating point when the shader is run. Despite that, it may be advantageous to use more dense storage formats (e.g. ALLEGRO_PRIM_NORMALIZED_UBYTE_4 instead of ALLEGRO_PRIM_FLOAT_4) when bandwidth (amount of memory sent to the GPU) is an issue but precision is not.

See also

ALLEGRO_PRIM_STORAGE_NONE

Default storage value.

ALLEGRO_PRIM_ATTR

Enumerates the types of vertex attributes that a custom vertex may have.

Values

• ALLEGRO_PRIM_FLOAT_2: A doublet of floats.
• ALLEGRO_PRIM_FLOAT_3: A triplet of floats.
• ALLEGRO_PRIM_SHORT_2: A doublet of shorts.
• ALLEGRO_PRIM_FLOAT_1: A single float.
• ALLEGRO_PRIM_FLOAT_4: A quad of floats.
• ALLEGRO_PRIM_UBYTE_4: A quad of unsigned bytes.
• ALLEGRO_PRIM_SHORT_4: A quad of shorts.
• ALLEGRO_PRIM_NORMALIZED_UBYTE_4: A quad of unsigned bytes. Before being sent to the shader, each component is divided by 255. Each component of the resultant float quad ranges between 0.0 and 1.0.
• ALLEGRO_PRIM_NORMALIZED_SHORT_2: A doublet of shorts. Before being sent to the shader, each component is divided by 32767. Each component of the resultant float doublet ranges between -1.0 and 1.0.
• ALLEGRO_PRIM_NORMALIZED_SHORT_4: A quad of shorts. Before being sent to the shader, each component is divided by 32767. Each component of the resultant float quad ranges between -1.0 and 1.0.
• ALLEGRO_PRIM_NORMALIZED_USHORT_2: A doublet of unsigned shorts. Before being sent to the shader, each component is divided by 65535. Each component of the resultant float doublet ranges between 0.0 and 1.0.
• ALLEGRO_PRIM_NORMALIZED_USHORT_4: A quad of unsigned shorts. Before being sent to the shader, each component is divided by 65535. Each component of the resultant float quad ranges between 0.0 and 1.0.
• ALLEGRO_PRIM_HALF_FLOAT_2: A doublet of half-precision floats. Note that this storage format is not supported on all platforms. al_create_vertex_decl will return Nil if you use it on those platforms.
• ALLEGRO_PRIM_HALF_FLOAT_4: A quad of half-precision floats. Note that this storage format is not supported on all platforms. al_create_vertex_decl will return Nil if you use it on those platforms.

See the picture for the difference.

See also

al_draw_polygon

Draws an unfilled polygon.

ALLEGRO_LINE_JOIN_MITRE

Alternative name for ALLEGRO_LINE_JOIN_MITER.

Values

• ALLEGRO_LINE_JOIN_NONE
• ALLEGRO_LINE_JOIN_BEVEL
• ALLEGRO_LINE_JOIN_ROUND
• ALLEGRO_LINE_JOIN_MITER

See the picture for the difference.

See also

al_draw_polygon

Draws an unfilled polygon.

Values

• ALLEGRO_LINE_CAP_NONE
• ALLEGRO_LINE_CAP_SQUARE
• ALLEGRO_LINE_CAP_ROUND
• ALLEGRO_LINE_CAP_TRIANGLE
• ALLEGRO_LINE_CAP_CLOSED

Flags to specify how to create a vertex or an index buffer.

See also

al_create_vertex_buffer

Creates a vertex buffer.

al_create_index_buffer

Creates an index buffer.

Values

• ALLEGRO_PRIM_BUFFER_NONE = 0
• ALLEGRO_PRIM_BUFFER_STREAM = $01: Hints to the driver that the buffer is written to often, but used only a few times per frame.
• ALLEGRO_PRIM_BUFFER_STATIC = $02: Hints to the driver that the buffer is written to once and is used often.
• ALLEGRO_PRIM_BUFFER_DYNAMIC = $04: Hints to the driver that the buffer is written to often and is used often.
• ALLEGRO_PRIM_BUFFER_READWRITE = $08: Specifies that you want to be able read from this buffer. By default this is disabled for performance. Some platforms (like OpenGL ES) do not support reading from vertex buffers, so if you pass this flag to al_create_vertex_buffer or al_create_index_buffer the call will fail.

Pointer to ALLEGRO_VERTEX_ELEMENT.

A vertex declaration. This opaque structure is responsible for describing the format and layout of a user defined custom vertex. It is created and destroyed by specialized functions.

See also

al_create_vertex_decl

Creates a vertex declaration, which describes a custom vertex format.

al_destroy_vertex_decl

Destroys a vertex declaration.

ALLEGRO_VERTEX_ELEMENT

A small structure describing a certain element of a vertex.

Pointer to ALLEGRO_VERTEX.

A GPU vertex buffer that you can use to store vertices on the GPU instead of uploading them afresh during every drawing operation.

See also

al_create_vertex_buffer

Creates a vertex buffer.

al_destroy_vertex_buffer

Destroys a vertex buffer.

A GPU index buffer that you can use to store indices of vertices in a vertex buffer on the GPU instead of uploading them afresh during every drawing operation.

See also

al_create_index_buffer

Creates an index buffer.

al_destroy_index_buffer

Destroys an index buffer.

Callback function used by al_triangulate_polygon.

Parameters

a

Index of the first triangle vertex.

b

Index of the first triangle vertex.

c

Index of the first triangle vertex.

p

Pointer to user data.

Callback function used by al_draw_soft_triangle.

Parameters

state

Pointer to a user suplied struct.

v1

First vertex of the triangle.

v2

Second vertex of the triangle.

v3

third vertex of the triangle.

Callback function used by al_draw_soft_triangle.

It is passed 4 parameters, the first two are the coordinates of the initial pixel drawn in the segment. The second two are the left minor and the left major steps, respectively. They represent the sizes of two steps taken by the rasterizer as it walks on the left side of the triangle. From then on, each step will either be classified as a minor or a major step, corresponding to the above values.

Callback function used by al_draw_soft_triangle.

The function is expected to draw the scanline starting with a point specified by the first two parameters (x1, y) going to the right until it reaches the value of the third parameter (x2). All coordinates are inclusive.

Callback function used by al_draw_soft_line.

It is passed the coordinates of this pixel, as well as the two vertices above. The passed vertices may have been altered by clipping.

Callback function used by al_draw_soft_line.

The function is expected to draw the pixel at the coordinates passed to it.

Callback function used to track the steps on some drawing functions.

An array that defines 4 pair of coordinates for spline lines.

See also

al_calculate_spline

Calculates a Bézier spline given 4 control points.

al_draw_spline

Draws a Bézier spline given 4 control points.

Default storage value.

See also

ALLEGRO_PRIM_STORAGE

Enumerates the types of storage an attribute of a custom vertex may be stored in.

Alternative name for ALLEGRO_LINE_JOIN_MITER.

Defines the size of the transformation vertex cache for the software renderer. If you pass less than this many vertices to the primitive rendering functions you will get a speed boost. This also 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.