Unit al5primitives

Description

Primitive drawing.

Warning: Some parts of this add-on don't work correctly. See the examples to know what primitives work and what ones don't. Note also that use of the primitives that doesn't work may result in memory corruption and kill your program (and may be your operating system too!). Of course, this unit will work perfectly in the next stable version.

High level drawing routines

High level drawing routines encompass the most common usage of this addon: to draw geometric primitives, both smooth (variations on the circle theme) and piecewise linear. Outlined primitives support the concept of thickness with two distinct modes of output: hairline lines and thick lines. Hairline lines are specifically designed to be exactly a pixel wide, and are commonly used for drawing outlined figures that need to be a pixel wide. Hairline thickness is designated as thickness less than or equal to 0. Unfortunately, the exact rasterization rules for drawing these hairline lines vary from one video card to another, and sometimes leave gaps where the lines meet. If that matters to you, then you should use thick lines. In many cases, having a thickness of 1 will produce 1 pixel wide lines that look better than hairline lines. Obviously, hairline lines cannot replicate thicknesses greater than 1. Thick lines grow symmetrically around the generating shape as thickness is increased.

Pixel-precise output

While normally you should not be too concerned with which pixels are displayed when the high level primitives are drawn, it is nevertheless possible to control that precisely by carefully picking the coordinates at which you draw those primitives.

To be able to do that, however, it is critical to understand how GPU cards convert shapes to pixels. Pixels are not the smallest unit that can be addressed by the GPU. Because the GPU deals with floating point coordinates, it can in fact assign different coordinates to different parts of a single pixel. To a GPU, thus, a screen is composed of a grid of squares that have width and length of 1. The top left corner of the top left pixel is located at (0, 0). Therefore, the center of that pixel is at (0.5, 0.5). The basic rule that determines which pixels are associated with which shape is then as follows: a pixel is treated to belong to a shape if the pixel's center is located in that shape. The figure below illustrates the above concepts:

[Diagram showing a how pixel output is calculated by the GPU given the mathematical description of several shapes.]

This figure depicts three shapes drawn at the top left of the screen: an orange and green rectangles and a purple circle. On the left are the mathematical descriptions of pixels on the screen and the shapes to be drawn. On the right is the screen output. Only a single pixel has its center inside the circle, and therefore only a single pixel is drawn on the screen. Similarly, two pixels are drawn for the orange rectangle. Since there are no pixels that have their centers inside the green rectangle, the output image has no green pixels.

Here is a more practical example. The image below shows the output of this code:

/* blue vertical line */
al_draw_line(0.5, 0, 0.5, 6, color_blue, 1);
/* red horizontal line */
al_draw_line(2, 1, 6, 1, color_red, 2);
/* green filled rectangle */
al_draw_filled_rectangle(3, 4, 5, 5, color_green);
/* purple outlined rectangle */
al_draw_rectangle(2.5, 3.5, 5.5, 5.5, color_purple, 1);

[Diagram showing a practical example of pixel output resulting from the invocation of several primitives addon functions.]

It can be seen that lines are generated by making a rectangle based on the dashed line between the two endpoints. The thickness causes the rectangle to grow symmetrically about that generating line, as can be seen by comparing the red and blue lines. Note that to get proper pixel coverage, the coordinates passed to the al_draw_line had to be offset by 0.5 in the appropriate dimensions.

Filled rectangles are generated by making a rectangle between the endpoints passed to the al_draw_filled_rectangle.

Outlined rectangles are generated by symmetrically expanding an outline of a rectangle. With a thickness of 1, as depicted in the diagram, this means that an offset of 0.5 is needed for both sets of endpoint coordinates to exactly line up with the pixels of the display raster.

The above rules only apply when multisampling is turned off. When multisampling is turned on, the area of a pixel that is covered by a shape is taken into account when choosing what color to draw there. This also means that shapes no longer have to contain the pixel's center to affect its color. For example, the green rectangle in the first diagram may in fact be drawn as two (or one) semi-transparent pixels. The advantages of multisampling is that slanted shapes will look smoother because they will not have jagged edges. A disadvantage of multisampling is that it may make vertical and horizontal edges blurry. While the exact rules for multisampling are unspecified, and may vary from GPU to GPU, it is usually safe to assume that as long as a pixel is either completely covered by a shape or completely not covered, then the shape edges will be sharp. The offsets used in the second diagram were chosen so that this is the case: if you use those offsets, your shapes (if they are oriented the same way as they are on the diagram) should look the same whether multisampling is turned on or off.

Overview

Classes, Interfaces, Objects and Records

Name Description
Record ALLEGRO_VERTEX_ELEMENT  
Record ALLEGRO_VERTEX  

Functions and Procedures

FUNCTION al_get_allegro_primitives_version: AL_UINT32; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
FUNCTION al_init_primitives_addon: AL_BOOL; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_shutdown_primitives_addon; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
FUNCTION al_draw_prim (VAR vtxs: ARRAY OF ALLEGRO_VERTEX; CONST decl: ALLEGRO_VERTEX_DECLptr; texture: ALLEGRO_BITMAPptr; start, finish: AL_INT; _type: ALLEGRO_PRIM_TYPE): AL_INT; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
FUNCTION al_draw_prim_ex (vtxs: AL_VOIDptr; CONST decl: ALLEGRO_VERTEX_DECLptr; texture: ALLEGRO_BITMAPptr; start, finish: AL_INT; _type: ALLEGRO_PRIM_TYPE): AL_INT; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME NAME 'al_draw_prim';
FUNCTION al_draw_indexed_prim (VAR vtxs: ARRAY OF ALLEGRO_VERTEX; CONST decl: ALLEGRO_VERTEX_DECLptr; texture: ALLEGRO_BITMAPptr; VAR indices: ARRAY OF AL_INT; num_vtx: AL_INT; _type: ALLEGRO_PRIM_TYPE): AL_INT; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
FUNCTION al_draw_vertex_buffer (vertex_buffer: ALLEGRO_VERTEX_BUFFERptr; texture: ALLEGRO_BITMAPptr; start, finish: AL_INT; _type: ALLEGRO_PRIM_TYPE): AL_INT; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
FUNCTION al_draw_indexed_buffer (vertex_buffer: ALLEGRO_VERTEX_BUFFERptr; texture: ALLEGRO_BITMAPptr; index_buffer: ALLEGRO_INDEX_BUFFERptr; start, finish: AL_INT; _type: ALLEGRO_PRIM_TYPE): AL_INT; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
FUNCTION al_create_vertex_decl (VAR elements: ARRAY OF ALLEGRO_VERTEX_ELEMENT; stride: AL_INT): ALLEGRO_VERTEX_DECLptr; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_destroy_vertex_decl (decl: ALLEGRO_VERTEX_DECLptr); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
FUNCTION al_create_vertex_buffer (decl: ALLEGRO_VERTEX_DECLptr; VAR initial_data: ARRAY OF ALLEGRO_VERTEX; num_vertices: AL_INT; flags: ALLEGRO_PRIM_BUFFER_FLAGS): ALLEGRO_VERTEX_BUFFERptr; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
FUNCTION al_create_vertex_buffer_ex (decl: ALLEGRO_VERTEX_DECLptr; CONST initial_data: AL_VOIDptr; num_vertices: AL_INT; flags: ALLEGRO_PRIM_BUFFER_FLAGS): ALLEGRO_VERTEX_BUFFERptr; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME NAME 'al_create_vertex_buffer';
PROCEDURE al_destroy_vertex_buffer (buffer: ALLEGRO_VERTEX_BUFFERptr); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
FUNCTION al_lock_vertex_buffer (buffer: ALLEGRO_VERTEX_BUFFERptr; offset, length, flags: AL_INT): AL_VOIDptr; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_unlock_vertex_buffer (buffer: ALLEGRO_VERTEX_BUFFERptr); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
FUNCTION al_get_vertex_buffer_size (buffer: ALLEGRO_VERTEX_BUFFERptr): AL_INT; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
FUNCTION al_create_index_buffer (index_size: AL_INT; const initial_data: AL_VOIDptr; num_indices: AL_INT; flags: ALLEGRO_PRIM_BUFFER_FLAGS): ALLEGRO_INDEX_BUFFERptr; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_destroy_index_buffer (buffer: ALLEGRO_INDEX_BUFFERptr); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
FUNCTION al_lock_index_buffer (buffer: ALLEGRO_INDEX_BUFFERptr; offset, length, flags: AL_INT): AL_VOIDptr; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_unlock_index_buffer (buffer: ALLEGRO_INDEX_BUFFERptr); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
FUNCTION al_get_index_buffer_size (buffer: ALLEGRO_INDEX_BUFFERptr): AL_INT; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
FUNCTION al_triangulate_polygon (CONST vertices: AL_FLOATptr; svertex_stride: AL_SIZE_T; CONST vertex_counts: AL_INTptr; emit_triangle: ALLEGRO_EMIT_TRIANGLE_PROC; userdata: AL_VOIDptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_soft_triangle (v1, v2, v3: ALLEGRO_VERTEXptr; state: AL_UINTPTR_T; init: ALLEGRO_INIT_TRIANGLE_PROC; first: ALLEGRO_FIRST_TRIANGLE_PROC; step: ALLEGRO_STEP_PROC; draw: ALLEGRO_DRAW_TRIANGLE_PROC); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_soft_line (v1, v2: ALLEGRO_VERTEXptr; state: AL_UINTPTR_T; first: ALLEGRO_FIRST_LINE_PROC; step: ALLEGRO_STEP_PROC; draw: ALLEGRO_DRAW_LINE_PROC); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_line (x1, y1, x2, y2: AL_FLOAT; color: ALLEGRO_COLOR; thickness: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_triangle (x1, y1, x2, y2, x3, y3: AL_FLOAT; color: ALLEGRO_COLOR; thickness: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_rectangle (x1, y1, x2, y2: AL_FLOAT; color: ALLEGRO_COLOR; thickness: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_rounded_rectangle (x1, y1, x2, y2, rx, ry: AL_FLOAT; color: ALLEGRO_COLOR; thickness: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_calculate_arc (dest: AL_FLOATptr; stride: AL_INT; cx, cy, rx, ry, start_theta, delta_theta, thickness: AL_FLOAT; num_segments: AL_INT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_circle (cx, cy, r: AL_FLOAT; color: ALLEGRO_COLOR; thickness: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_ellipse (cx, cy, rx, ry: AL_FLOAT; color: ALLEGRO_COLOR; thickness: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_arc (cx, cy, r, start_theta, delta_theta: AL_FLOAT; color: ALLEGRO_COLOR; thickness: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_elliptical_arc (cx, cy, rx, ry, start_theta, delta_theta: AL_FLOAT; color: ALLEGRO_COLOR; thickness: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_pieslice (cx, cy, r, start_theta, fdelta_theta: AL_FLOAT; color: ALLEGRO_COLOR; thickness: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_calculate_spline (dest: AL_FLOATptr; stride: AL_INT; VAR points: ALLEGRO_SPLINE_CONTROL_POINTS; thickness: AL_FLOAT; num_segments: AL_INT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_spline (VAR points: ALLEGRO_SPLINE_CONTROL_POINTS; color: ALLEGRO_COLOR; thickness: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_calculate_ribbon (dest: AL_FLOATptr; dest_stride: AL_INT; VAR points: ARRAY OF AL_FLOAT; points_stride: AL_INT; thickness: AL_FLOAT; num_segments: AL_INT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_ribbon (VAR points: ARRAY OF AL_FLOAT; points_stride: AL_INT; color: ALLEGRO_COLOR; thickness: AL_FLOAT; num_segments: AL_INT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_filled_triangle (x1, y1, x2, y2, x3, y3: AL_FLOAT; color: ALLEGRO_COLOR); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_filled_rectangle (x1, y1, x2, y2: AL_FLOAT; color: ALLEGRO_COLOR); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_filled_ellipse (cx, cy, rx, ry: AL_FLOAT; color: ALLEGRO_COLOR); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_filled_circle (cx, cy, r: AL_FLOAT; color: ALLEGRO_COLOR); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_filled_pieslice (cx, cy, r, start_theta, fdelta_theta: AL_FLOAT; color: ALLEGRO_COLOR); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_filled_rounded_rectangle (x1, y1, x2, y2, rx, ry: AL_FLOAT; color: ALLEGRO_COLOR); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_polyline (CONST vertices: AL_FLOATptr; vertex_stride, vertex_count, join_style, cap_style: AL_INT; color: ALLEGRO_COLOR; thickness, miter_limit: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_polygon (CONST vertices: AL_FLOATptr; vertex_count, join_style: AL_INT; color: ALLEGRO_COLOR; thickness, miter_limit: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_filled_polygon (CONST vertices: AL_FLOATptr; vertex_count: AL_INT; color: ALLEGRO_COLOR); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
PROCEDURE al_draw_filled_polygon_with_holes (CONST vertices: AL_FLOATptr; CONST vertex_counts: AL_INTptr; color: ALLEGRO_COLOR); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;

Types

ALLEGRO_PRIM_TYPE = (...);
ALLEGRO_PRIM_ATTR = (...);
ALLEGRO_PRIM_STORAGE = (...);
ALLEGRO_LINE_JOIN = (...);
ALLEGRO_LINE_CAP = (...);
ALLEGRO_PRIM_BUFFER_FLAGS = (...);
ALLEGRO_VERTEX_ELEMENTptr = ˆALLEGRO_VERTEX_ELEMENT;
ALLEGRO_VERTEX_DECLptr = AL_POINTER;
ALLEGRO_VERTEXptr = ˆALLEGRO_VERTEX;
ALLEGRO_VERTEX_BUFFERptr = AL_POINTER;
ALLEGRO_INDEX_BUFFERptr = AL_POINTER;
ALLEGRO_EMIT_TRIANGLE_PROC = PROCEDURE (a, b, c: AL_INT; p: AL_VOIDptr);
ALLEGRO_INIT_TRIANGLE_PROC = PROCEDURE (state: AL_UINTPTR_T; v1, v2, v3: ALLEGRO_VERTEXptr); CDECL;
ALLEGRO_FIRST_TRIANGLE_PROC = PROCEDURE (state: AL_UINTPTR_T; x, y, l1, l2: AL_INT); CDECL;
ALLEGRO_DRAW_TRIANGLE_PROC = PROCEDURE (state: AL_UINTPTR_T; x1, y, x2: AL_INT); CDECL;
ALLEGRO_FIRST_LINE_PROC = PROCEDURE (state: AL_UINTPTR_T; px, py: AL_INT; v1, v2: ALLEGRO_VERTEXptr); CDECL;
ALLEGRO_DRAW_LINE_PROC = PROCEDURE (state: AL_UINTPTR_T; x, y: AL_INT); CDECL;
ALLEGRO_STEP_PROC = PROCEDURE (state: AL_UINTPTR_T; _type: AL_INT); CDECL;
ALLEGRO_SPLINE_CONTROL_POINTS = ARRAY [0..7] OF AL_FLOAT;

Constants

ALLEGRO_PRIM_STORAGE_NONE = ALLEGRO_PRIM_FLOAT_2;
ALLEGRO_LINE_JOIN_MITRE = ALLEGRO_LINE_JOIN_MITER;
ALLEGRO_VERTEX_CACHE_SIZE = 256;
ALLEGRO_PRIM_QUALITY = 10;

Description

Functions and Procedures

FUNCTION al_get_allegro_primitives_version: AL_UINT32; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;

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

FUNCTION al_init_primitives_addon: AL_BOOL; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;

Initializes the primitives addon.

Returns

True on success, False on failure.

See also
al_shutdown_primitives_addon
Shut down the primitives addon.
PROCEDURE al_shutdown_primitives_addon; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;

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.
FUNCTION al_draw_prim (VAR vtxs: ARRAY OF ALLEGRO_VERTEX; CONST decl: ALLEGRO_VERTEX_DECLptr; texture: ALLEGRO_BITMAPptr; start, finish: AL_INT; _type: ALLEGRO_PRIM_TYPE): AL_INT; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;

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, NIL, 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.
decl
Pointer to a vertex declaration. If set to Nil, the vertices are assumed to be of the ALLEGRO_VERTEX type.
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.
_type
A member of the ALLEGRO_PRIM_TYPE enumeration, specifying what kind of primitive to draw.
Returns

Number of primitives drawn.

See also
ALLEGRO_VERTEX
ALLEGRO_PRIM_TYPE
ALLEGRO_VERTEX_DECLptr
A vertex declaration.
al_draw_indexed_prim
FUNCTION al_draw_prim_ex (vtxs: AL_VOIDptr; CONST decl: ALLEGRO_VERTEX_DECLptr; texture: ALLEGRO_BITMAPptr; start, finish: AL_INT; _type: ALLEGRO_PRIM_TYPE): AL_INT; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME NAME 'al_draw_prim';
 
FUNCTION al_draw_indexed_prim (VAR vtxs: ARRAY OF ALLEGRO_VERTEX; CONST decl: ALLEGRO_VERTEX_DECLptr; texture: ALLEGRO_BITMAPptr; VAR indices: ARRAY OF AL_INT; num_vtx: AL_INT; _type: ALLEGRO_PRIM_TYPE): AL_INT; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
FUNCTION al_draw_vertex_buffer (vertex_buffer: ALLEGRO_VERTEX_BUFFERptr; texture: ALLEGRO_BITMAPptr; start, finish: AL_INT; _type: ALLEGRO_PRIM_TYPE): AL_INT; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
FUNCTION al_draw_indexed_buffer (vertex_buffer: ALLEGRO_VERTEX_BUFFERptr; texture: ALLEGRO_BITMAPptr; index_buffer: ALLEGRO_INDEX_BUFFERptr; start, finish: AL_INT; _type: ALLEGRO_PRIM_TYPE): AL_INT; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
FUNCTION al_create_vertex_decl (VAR elements: ARRAY OF ALLEGRO_VERTEX_ELEMENT; stride: AL_INT): ALLEGRO_VERTEX_DECLptr; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;

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
ALLEGRO_VERTEX_DECLptr
A vertex declaration.
al_destroy_vertex_decl
Destroys a vertex declaration.
PROCEDURE al_destroy_vertex_decl (decl: ALLEGRO_VERTEX_DECLptr); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;

Destroys a vertex declaration.

See also
ALLEGRO_VERTEX_ELEMENT
ALLEGRO_VERTEX_DECLptr
A vertex declaration.
al_create_vertex_decl
Creates a vertex declaration, which describes a custom vertex format.
FUNCTION al_create_vertex_buffer (decl: ALLEGRO_VERTEX_DECLptr; VAR initial_data: ARRAY OF ALLEGRO_VERTEX; num_vertices: AL_INT; flags: ALLEGRO_PRIM_BUFFER_FLAGS): ALLEGRO_VERTEX_BUFFERptr; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
FUNCTION al_create_vertex_buffer_ex (decl: ALLEGRO_VERTEX_DECLptr; CONST initial_data: AL_VOIDptr; num_vertices: AL_INT; flags: ALLEGRO_PRIM_BUFFER_FLAGS): ALLEGRO_VERTEX_BUFFERptr; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME NAME 'al_create_vertex_buffer';
 
PROCEDURE al_destroy_vertex_buffer (buffer: ALLEGRO_VERTEX_BUFFERptr); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
FUNCTION al_lock_vertex_buffer (buffer: ALLEGRO_VERTEX_BUFFERptr; offset, length, flags: AL_INT): AL_VOIDptr; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
PROCEDURE al_unlock_vertex_buffer (buffer: ALLEGRO_VERTEX_BUFFERptr); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
FUNCTION al_get_vertex_buffer_size (buffer: ALLEGRO_VERTEX_BUFFERptr): AL_INT; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
FUNCTION al_create_index_buffer (index_size: AL_INT; const initial_data: AL_VOIDptr; num_indices: AL_INT; flags: ALLEGRO_PRIM_BUFFER_FLAGS): ALLEGRO_INDEX_BUFFERptr; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
PROCEDURE al_destroy_index_buffer (buffer: ALLEGRO_INDEX_BUFFERptr); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
FUNCTION al_lock_index_buffer (buffer: ALLEGRO_INDEX_BUFFERptr; offset, length, flags: AL_INT): AL_VOIDptr; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
PROCEDURE al_unlock_index_buffer (buffer: ALLEGRO_INDEX_BUFFERptr); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
FUNCTION al_get_index_buffer_size (buffer: ALLEGRO_INDEX_BUFFERptr): AL_INT; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
FUNCTION al_triangulate_polygon (CONST vertices: AL_FLOATptr; svertex_stride: AL_SIZE_T; CONST vertex_counts: AL_INTptr; emit_triangle: ALLEGRO_EMIT_TRIANGLE_PROC; userdata: AL_VOIDptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
PROCEDURE al_draw_soft_triangle (v1, v2, v3: ALLEGRO_VERTEXptr; state: AL_UINTPTR_T; init: ALLEGRO_INIT_TRIANGLE_PROC; first: ALLEGRO_FIRST_TRIANGLE_PROC; step: ALLEGRO_STEP_PROC; draw: ALLEGRO_DRAW_TRIANGLE_PROC); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;

Custom primitives

PROCEDURE al_draw_soft_line (v1, v2: ALLEGRO_VERTEXptr; state: AL_UINTPTR_T; first: ALLEGRO_FIRST_LINE_PROC; step: ALLEGRO_STEP_PROC; draw: ALLEGRO_DRAW_LINE_PROC); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
PROCEDURE al_draw_line (x1, y1, x2, y2: AL_FLOAT; color: ALLEGRO_COLOR; thickness: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;

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
PROCEDURE al_draw_triangle (x1, y1, x2, y2, x3, y3: AL_FLOAT; color: ALLEGRO_COLOR; thickness: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;

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.
See also
al_draw_filled_triangle
Draws a filled triangle.
al_draw_soft_triangle
Custom primitives
PROCEDURE al_draw_rectangle (x1, y1, x2, y2: AL_FLOAT; color: ALLEGRO_COLOR; thickness: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;

Draws an outlined rectangle.

Parameters
x1
left of the rectangle.
y1
top of the rectangle.
x2
right of the rectangle.
y2
bottom 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
al_draw_rounded_rectangle
PROCEDURE al_draw_rounded_rectangle (x1, y1, x2, y2, rx, ry: AL_FLOAT; color: ALLEGRO_COLOR; thickness: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
PROCEDURE al_calculate_arc (dest: AL_FLOATptr; stride: AL_INT; cx, cy, rx, ry, start_theta, delta_theta, thickness: AL_FLOAT; num_segments: AL_INT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;

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 (AL_FLOAT).

Parameters
dest
The destination buffer.
stride
Distance (in bytes) between starts of successive pairs of points.
cx,
cy Center of the arc.
rx,
ry Radii 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.
al_calculate_spline
al_calculate_ribbon
See also
al_draw_arc
PROCEDURE al_draw_circle (cx, cy, r: AL_FLOAT; color: ALLEGRO_COLOR; thickness: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;

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
al_draw_ellipse
PROCEDURE al_draw_ellipse (cx, cy, rx, ry: AL_FLOAT; color: ALLEGRO_COLOR; thickness: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
PROCEDURE al_draw_arc (cx, cy, r, start_theta, delta_theta: AL_FLOAT; color: ALLEGRO_COLOR; thickness: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
PROCEDURE al_draw_elliptical_arc (cx, cy, rx, ry, start_theta, delta_theta: AL_FLOAT; color: ALLEGRO_COLOR; thickness: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
PROCEDURE al_draw_pieslice (cx, cy, r, start_theta, fdelta_theta: AL_FLOAT; color: ALLEGRO_COLOR; thickness: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
PROCEDURE al_calculate_spline (dest: AL_FLOATptr; stride: AL_INT; VAR points: ALLEGRO_SPLINE_CONTROL_POINTS; thickness: AL_FLOAT; num_segments: AL_INT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
PROCEDURE al_draw_spline (VAR points: ALLEGRO_SPLINE_CONTROL_POINTS; color: ALLEGRO_COLOR; thickness: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
PROCEDURE al_calculate_ribbon (dest: AL_FLOATptr; dest_stride: AL_INT; VAR points: ARRAY OF AL_FLOAT; points_stride: AL_INT; thickness: AL_FLOAT; num_segments: AL_INT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
PROCEDURE al_draw_ribbon (VAR points: ARRAY OF AL_FLOAT; points_stride: AL_INT; color: ALLEGRO_COLOR; thickness: AL_FLOAT; num_segments: AL_INT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
PROCEDURE al_draw_filled_triangle (x1, y1, x2, y2, x3, y3: AL_FLOAT; color: ALLEGRO_COLOR); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;

Draws a filled triangle.

Parameters
x1,
y1, x2, y2, x3, y3 Three points of the triangle.
color
Color of the triangle.
See also
al_draw_triangle
Draws an outlined triangle.
PROCEDURE al_draw_filled_rectangle (x1, y1, x2, y2: AL_FLOAT; color: ALLEGRO_COLOR); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
PROCEDURE al_draw_filled_ellipse (cx, cy, rx, ry: AL_FLOAT; color: ALLEGRO_COLOR); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
PROCEDURE al_draw_filled_circle (cx, cy, r: AL_FLOAT; color: ALLEGRO_COLOR); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
PROCEDURE al_draw_filled_pieslice (cx, cy, r, start_theta, fdelta_theta: AL_FLOAT; color: ALLEGRO_COLOR); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
PROCEDURE al_draw_filled_rounded_rectangle (x1, y1, x2, y2, rx, ry: AL_FLOAT; color: ALLEGRO_COLOR); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
PROCEDURE al_draw_polyline (CONST vertices: AL_FLOATptr; vertex_stride, vertex_count, join_style, cap_style: AL_INT; color: ALLEGRO_COLOR; thickness, miter_limit: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
PROCEDURE al_draw_polygon (CONST vertices: AL_FLOATptr; vertex_count, join_style: AL_INT; color: ALLEGRO_COLOR; thickness, miter_limit: AL_FLOAT); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
PROCEDURE al_draw_filled_polygon (CONST vertices: AL_FLOATptr; vertex_count: AL_INT; color: ALLEGRO_COLOR); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 
PROCEDURE al_draw_filled_polygon_with_holes (CONST vertices: AL_FLOATptr; CONST vertex_counts: AL_INTptr; color: ALLEGRO_COLOR); CDECL; EXTERNAL ALLEGRO_PRIMITIVES_LIB_NAME;
 

Types

ALLEGRO_PRIM_TYPE = (...);
 
Values
  • ALLEGRO_PRIM_LINE_LIST
  • ALLEGRO_PRIM_LINE_STRIP
  • ALLEGRO_PRIM_LINE_LOOP
  • ALLEGRO_PRIM_TRIANGLE_LIST
  • ALLEGRO_PRIM_TRIANGLE_STRIP
  • ALLEGRO_PRIM_TRIANGLE_FAN
  • ALLEGRO_PRIM_POINT_LIST
  • ALLEGRO_PRIM_NUM_TYPES
ALLEGRO_PRIM_ATTR = (...);
 
Values
  • ALLEGRO_PRIM_ATTR_NONE = 0
  • ALLEGRO_PRIM_POSITION = 1
  • ALLEGRO_PRIM_COLOR_ATTR
  • ALLEGRO_PRIM_TEX_COORD
  • ALLEGRO_PRIM_TEX_COORD_PIXEL
  • ALLEGRO_PRIM_USER_ATTR
  • ALLEGRO_PRIM_ATTR_NUM
ALLEGRO_PRIM_STORAGE = (...);

TODO: Undefined!

Values
  • ALLEGRO_PRIM_FLOAT_2
  • ALLEGRO_PRIM_FLOAT_3
  • ALLEGRO_PRIM_SHORT_2
  • ALLEGRO_PRIM_FLOAT_1
  • ALLEGRO_PRIM_FLOAT_4
  • ALLEGRO_PRIM_UBYTE_4
  • ALLEGRO_PRIM_SHORT_4
  • ALLEGRO_PRIM_NORMALIZED_UBYTE_4
  • ALLEGRO_PRIM_NORMALIZED_SHORT_2
  • ALLEGRO_PRIM_NORMALIZED_SHORT_4
  • ALLEGRO_PRIM_NORMALIZED_USHORT_2
  • ALLEGRO_PRIM_NORMALIZED_USHORT_4
  • ALLEGRO_PRIM_HALF_FLOAT_2
  • ALLEGRO_PRIM_HALF_FLOAT_4
ALLEGRO_LINE_JOIN = (...);
 
Values
  • ALLEGRO_LINE_JOIN_NONE
  • ALLEGRO_LINE_JOIN_BEVEL
  • ALLEGRO_LINE_JOIN_ROUND
  • ALLEGRO_LINE_JOIN_MITER
ALLEGRO_LINE_CAP = (...);
 
Values
  • ALLEGRO_LINE_CAP_NONE
  • ALLEGRO_LINE_CAP_SQUARE
  • ALLEGRO_LINE_CAP_ROUND
  • ALLEGRO_LINE_CAP_TRIANGLE
  • ALLEGRO_LINE_CAP_CLOSED
ALLEGRO_PRIM_BUFFER_FLAGS = (...);
 
Values
  • ALLEGRO_PRIM_BUFFER_NONE = 0
  • ALLEGRO_PRIM_BUFFER_STREAM = $01
  • ALLEGRO_PRIM_BUFFER_STATIC = $02
  • ALLEGRO_PRIM_BUFFER_DYNAMIC = $04
  • ALLEGRO_PRIM_BUFFER_READWRITE = $08
ALLEGRO_VERTEX_ELEMENTptr = ˆALLEGRO_VERTEX_ELEMENT;
 
ALLEGRO_VERTEX_DECLptr = AL_POINTER;

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
ALLEGRO_VERTEXptr = ˆALLEGRO_VERTEX;
 
ALLEGRO_VERTEX_BUFFERptr = AL_POINTER;

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
al_destroy_vertex_buffer
ALLEGRO_INDEX_BUFFERptr = AL_POINTER;

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
al_destroy_index_buffer
ALLEGRO_EMIT_TRIANGLE_PROC = PROCEDURE (a, b, c: AL_INT; p: AL_VOIDptr);
 
ALLEGRO_INIT_TRIANGLE_PROC = PROCEDURE (state: AL_UINTPTR_T; v1, v2, v3: ALLEGRO_VERTEXptr); CDECL;
 
ALLEGRO_FIRST_TRIANGLE_PROC = PROCEDURE (state: AL_UINTPTR_T; x, y, l1, l2: AL_INT); CDECL;
 
ALLEGRO_DRAW_TRIANGLE_PROC = PROCEDURE (state: AL_UINTPTR_T; x1, y, x2: AL_INT); CDECL;
 
ALLEGRO_FIRST_LINE_PROC = PROCEDURE (state: AL_UINTPTR_T; px, py: AL_INT; v1, v2: ALLEGRO_VERTEXptr); CDECL;
 
ALLEGRO_DRAW_LINE_PROC = PROCEDURE (state: AL_UINTPTR_T; x, y: AL_INT); CDECL;
 
ALLEGRO_STEP_PROC = PROCEDURE (state: AL_UINTPTR_T; _type: AL_INT); CDECL;
 
ALLEGRO_SPLINE_CONTROL_POINTS = ARRAY [0..7] OF AL_FLOAT;
 

Constants

ALLEGRO_PRIM_STORAGE_NONE = ALLEGRO_PRIM_FLOAT_2;
 
ALLEGRO_LINE_JOIN_MITRE = ALLEGRO_LINE_JOIN_MITER;
 
ALLEGRO_VERTEX_CACHE_SIZE = 256;
 
ALLEGRO_PRIM_QUALITY = 10;
 

Generated by PasDoc 0.14.0. Generated on 2017-01-03 13:25:50.