/usr/share/doc/allegro5-doc/refman/primitives.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <meta http-equiv="Content-Style-Type" content="text/css" />
  <meta name="generator" content="pandoc" />
  <title>Primitives addon</title>
  <style type="text/css">code{white-space: pre;}</style>
  <style type="text/css">
div.sourceCode { overflow-x: auto; }
table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode {
  margin: 0; padding: 0; vertical-align: baseline; border: none; }
table.sourceCode { width: 100%; line-height: 100%; }
td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; }
td.sourceCode { padding-left: 5px; }
code > span.kw { color: #007020; font-weight: bold; } /* Keyword */
code > span.dt { color: #902000; } /* DataType */
code > span.dv { color: #40a070; } /* DecVal */
code > span.bn { color: #40a070; } /* BaseN */
code > span.fl { color: #40a070; } /* Float */
code > span.ch { color: #4070a0; } /* Char */
code > span.st { color: #4070a0; } /* String */
code > span.co { color: #60a0b0; font-style: italic; } /* Comment */
code > span.ot { color: #007020; } /* Other */
code > span.al { color: #ff0000; font-weight: bold; } /* Alert */
code > span.fu { color: #06287e; } /* Function */
code > span.er { color: #ff0000; font-weight: bold; } /* Error */
code > span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
code > span.cn { color: #880000; } /* Constant */
code > span.sc { color: #4070a0; } /* SpecialChar */
code > span.vs { color: #4070a0; } /* VerbatimString */
code > span.ss { color: #bb6688; } /* SpecialString */
code > span.im { } /* Import */
code > span.va { color: #19177c; } /* Variable */
code > span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code > span.op { color: #666666; } /* Operator */
code > span.bu { } /* BuiltIn */
code > span.ex { } /* Extension */
code > span.pp { color: #bc7a00; } /* Preprocessor */
code > span.at { color: #7d9029; } /* Attribute */
code > span.do { color: #ba2121; font-style: italic; } /* Documentation */
code > span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code > span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
  </style>
  <link rel="stylesheet" href="pandoc.css" type="text/css" />
  <script type="text/javascript" src="autosuggest.js"></script>
  <script type="text/javascript" src="search_index.js"></script>
</head>
<body>
<div class="sidebar">
<div>
<ul>
<li><a href="index.html"><strong>Contents</strong></a></li>
<li><a href="config.html">Configuration files</a></li>
<li><a href="display.html">Display</a></li>
<li><a href="events.html">Events</a></li>
<li><a href="file.html">File I/O</a></li>
<li><a href="fshook.html">Filesystem</a></li>
<li><a href="fixed.html">Fixed point math</a></li>
<li><a href="fullscreen_mode.html">Fullscreen modes</a></li>
<li><a href="graphics.html">Graphics</a></li>
<li><a href="haptic.html">Haptic</a></li>
<li><a href="joystick.html">Joystick</a></li>
<li><a href="keyboard.html">Keyboard</a></li>
<li><a href="memory.html">Memory</a></li>
<li><a href="monitor.html">Monitor</a></li>
<li><a href="mouse.html">Mouse</a></li>
<li><a href="path.html">Path</a></li>
<li><a href="shader.html">Shader</a></li>
<li><a href="state.html">State</a></li>
<li><a href="system.html">System</a></li>
<li><a href="threads.html">Threads</a></li>
<li><a href="time.html">Time</a></li>
<li><a href="timer.html">Timer</a></li>
<li><a href="touch.html">Touch input</a></li>
<li><a href="transformations.html">Transformations</a></li>
<li><a href="utf8.html">UTF-8</a></li>
<li><a href="misc.html">Miscellaneous</a></li>
<li><a href="platform.html">Platform-specific</a></li>
<li><a href="direct3d.html">Direct3D</a></li>
<li><a href="opengl.html">OpenGL</a></li>
</ul>
<!-- The preceding blank line forces pandoc to terminate the list -->
</div>
<div>
<ul>
<li><a href="index.html#addons"><strong>Addons</strong></a></li>
<li><a href="audio.html">Audio addon</a></li>
<li><a href="acodec.html">Audio codecs</a></li>
<li><a href="color.html">Color addon</a></li>
<li><a href="font.html">Font addons</a></li>
<li><a href="image.html">Image I/O addon</a></li>
<li><a href="main.html">Main addon</a></li>
<li><a href="memfile.html">Memfile addon</a></li>
<li><a href="native_dialog.html">Native dialogs addon</a></li>
<li><a href="physfs.html">PhysicsFS addon</a></li>
<li><a href="primitives.html">Primitives addon</a></li>
<li><a href="video.html">Video streaming addon</a></li>
</ul>
<!-- The preceding blank line forces pandoc to terminate the list -->
</div>
<div>
<ul>
<li><a href="index_all.html"><strong>Index</strong></a></li>
</ul>
<!-- The preceding blank line forces pandoc to terminate the list -->
</div>
<div class="searchbox">
<script type="text/javascript">
function on_search(index, control) {
    // Note to self: the less-than sign must NOT converted to an entity!
    // SCRIPT elements are special.  The HTML validator gives bad advice.
    for (i = 0; i < search_index.length; i++) {
        if (search_index[i] == control.keywords[index]) {
            break;
        }
    }
    location.href = search_urls[i];
}
</script>
Search<br/> <input type="text" name="q" id="q" size="15" autocomplete="off"/><br/>
<script type="text/javascript"> new autosuggest("q", search_index, null, on_search); </script>
</div>
</div>
<div class="content">
<div id="header">
<h1 class="title">Primitives addon</h1>
</div>
<div id="TOC">
<ul>
<li><a href="#general">General</a><ul>
<li><a href="#al_get_allegro_primitives_version">al_get_allegro_primitives_version</a></li>
<li><a href="#al_init_primitives_addon">al_init_primitives_addon</a></li>
<li><a href="#al_shutdown_primitives_addon">al_shutdown_primitives_addon</a></li>
</ul></li>
<li><a href="#high-level-drawing-routines">High level drawing routines</a><ul>
<li><a href="#pixel-precise-output">Pixel-precise output</a></li>
<li><a href="#al_draw_line">al_draw_line</a></li>
<li><a href="#al_draw_triangle">al_draw_triangle</a></li>
<li><a href="#al_draw_filled_triangle">al_draw_filled_triangle</a></li>
<li><a href="#al_draw_rectangle">al_draw_rectangle</a></li>
<li><a href="#al_draw_filled_rectangle">al_draw_filled_rectangle</a></li>
<li><a href="#al_draw_rounded_rectangle">al_draw_rounded_rectangle</a></li>
<li><a href="#al_draw_filled_rounded_rectangle">al_draw_filled_rounded_rectangle</a></li>
<li><a href="#al_calculate_arc">al_calculate_arc</a></li>
<li><a href="#al_draw_pieslice">al_draw_pieslice</a></li>
<li><a href="#al_draw_filled_pieslice">al_draw_filled_pieslice</a></li>
<li><a href="#al_draw_ellipse">al_draw_ellipse</a></li>
<li><a href="#al_draw_filled_ellipse">al_draw_filled_ellipse</a></li>
<li><a href="#al_draw_circle">al_draw_circle</a></li>
<li><a href="#al_draw_filled_circle">al_draw_filled_circle</a></li>
<li><a href="#al_draw_arc">al_draw_arc</a></li>
<li><a href="#al_draw_elliptical_arc">al_draw_elliptical_arc</a></li>
<li><a href="#al_calculate_spline">al_calculate_spline</a></li>
<li><a href="#al_draw_spline">al_draw_spline</a></li>
<li><a href="#al_calculate_ribbon">al_calculate_ribbon</a></li>
<li><a href="#al_draw_ribbon">al_draw_ribbon</a></li>
</ul></li>
<li><a href="#low-level-drawing-routines">Low level drawing routines</a><ul>
<li><a href="#al_draw_prim">al_draw_prim</a></li>
<li><a href="#al_draw_indexed_prim">al_draw_indexed_prim</a></li>
<li><a href="#al_draw_vertex_buffer">al_draw_vertex_buffer</a></li>
<li><a href="#al_draw_indexed_buffer">al_draw_indexed_buffer</a></li>
<li><a href="#al_draw_soft_triangle">al_draw_soft_triangle</a></li>
<li><a href="#al_draw_soft_line">al_draw_soft_line</a></li>
</ul></li>
<li><a href="#custom-vertex-declaration-routines">Custom vertex declaration routines</a><ul>
<li><a href="#al_create_vertex_decl">al_create_vertex_decl</a></li>
<li><a href="#al_destroy_vertex_decl">al_destroy_vertex_decl</a></li>
</ul></li>
<li><a href="#vertex-buffer-routines">Vertex buffer routines</a><ul>
<li><a href="#al_create_vertex_buffer">al_create_vertex_buffer</a></li>
<li><a href="#al_destroy_vertex_buffer">al_destroy_vertex_buffer</a></li>
<li><a href="#al_lock_vertex_buffer">al_lock_vertex_buffer</a></li>
<li><a href="#al_unlock_vertex_buffer">al_unlock_vertex_buffer</a></li>
<li><a href="#al_get_vertex_buffer_size">al_get_vertex_buffer_size</a></li>
</ul></li>
<li><a href="#index-buffer-routines">Index buffer routines</a><ul>
<li><a href="#al_create_index_buffer">al_create_index_buffer</a></li>
<li><a href="#al_destroy_index_buffer">al_destroy_index_buffer</a></li>
<li><a href="#al_lock_index_buffer">al_lock_index_buffer</a></li>
<li><a href="#al_unlock_index_buffer">al_unlock_index_buffer</a></li>
<li><a href="#al_get_index_buffer_size">al_get_index_buffer_size</a></li>
</ul></li>
<li><a href="#polygon-routines">Polygon routines</a><ul>
<li><a href="#al_draw_polyline">al_draw_polyline</a></li>
<li><a href="#al_draw_polygon">al_draw_polygon</a></li>
<li><a href="#al_draw_filled_polygon">al_draw_filled_polygon</a></li>
<li><a href="#al_draw_filled_polygon_with_holes">al_draw_filled_polygon_with_holes</a></li>
<li><a href="#al_triangulate_polygon">al_triangulate_polygon</a></li>
</ul></li>
<li><a href="#structures-and-types">Structures and types</a><ul>
<li><a href="#allegro_vertex">ALLEGRO_VERTEX</a></li>
<li><a href="#allegro_vertex_decl">ALLEGRO_VERTEX_DECL</a></li>
<li><a href="#allegro_vertex_element">ALLEGRO_VERTEX_ELEMENT</a></li>
<li><a href="#allegro_prim_type">ALLEGRO_PRIM_TYPE</a></li>
<li><a href="#allegro_prim_attr">ALLEGRO_PRIM_ATTR</a></li>
<li><a href="#allegro_prim_storage">ALLEGRO_PRIM_STORAGE</a></li>
<li><a href="#allegro_vertex_cache_size">ALLEGRO_VERTEX_CACHE_SIZE</a></li>
<li><a href="#allegro_prim_quality">ALLEGRO_PRIM_QUALITY</a></li>
<li><a href="#allegro_line_join">ALLEGRO_LINE_JOIN</a></li>
<li><a href="#allegro_line_cap">ALLEGRO_LINE_CAP</a></li>
<li><a href="#allegro_vertex_buffer">ALLEGRO_VERTEX_BUFFER</a></li>
<li><a href="#allegro_index_buffer">ALLEGRO_INDEX_BUFFER</a></li>
<li><a href="#allegro_prim_buffer_flags">ALLEGRO_PRIM_BUFFER_FLAGS</a></li>
</ul></li>
</ul>
</div>
<p>These functions are declared in the following header file. Link with allegro_primitives.</p>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"> <span class="pp">#include </span><span class="im">&lt;allegro5/allegro_primitives.h&gt;</span></code></pre></div>
<h1 id="general">General</h1>
<h2 id="al_get_allegro_primitives_version">al_get_allegro_primitives_version</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">uint32_t</span> al_get_allegro_primitives_version(<span class="dt">void</span>)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/primitives.c#L151">Source Code</a></p>
<p>Returns the (compiled) version of the addon, in the same format as <a href="system.html#al_get_allegro_version">al_get_allegro_version</a>.</p>
<h2 id="al_init_primitives_addon">al_init_primitives_addon</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c">bool al_init_primitives_addon(<span class="dt">void</span>)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/primitives.c#L46">Source Code</a></p>
<p>Initializes the primitives addon.</p>
<p><em>Returns:</em> True on success, false on failure.</p>
<p>See also: <a href="primitives.html#al_shutdown_primitives_addon">al_shutdown_primitives_addon</a></p>
<h2 id="al_shutdown_primitives_addon">al_shutdown_primitives_addon</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_shutdown_primitives_addon(<span class="dt">void</span>)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/primitives.c#L60">Source Code</a></p>
<p>Shut down the primitives addon. This is done automatically at program exit, but can be called any time the user wishes as well.</p>
<p>See also: <a href="primitives.html#al_init_primitives_addon">al_init_primitives_addon</a></p>
<h1 id="high-level-drawing-routines">High level drawing routines</h1>
<p>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.</p>
<h2 id="pixel-precise-output">Pixel-precise output</h2>
<p>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.</p>
<p>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:</p>
<div class="figure">
<img src="images/primitives1.png" alt="Diagram showing a how pixel output is calculated by the GPU given the mathematical description of several shapes." />
<p class="caption"><em>Diagram showing a how pixel output is calculated by the GPU given the mathematical description of several shapes.</em></p>
</div>
<p>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.</p>
<p>Here is a more practical example. The image below shows the output of this code:</p>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="co">/* blue vertical line */</span>
al_draw_line(<span class="fl">0.5</span>, <span class="dv">0</span>, <span class="fl">0.5</span>, <span class="dv">6</span>, color_blue, <span class="dv">1</span>);
<span class="co">/* red horizontal line */</span>
al_draw_line(<span class="dv">2</span>, <span class="dv">1</span>, <span class="dv">6</span>, <span class="dv">1</span>, color_red, <span class="dv">2</span>);
<span class="co">/* green filled rectangle */</span>
al_draw_filled_rectangle(<span class="dv">3</span>, <span class="dv">4</span>, <span class="dv">5</span>, <span class="dv">5</span>, color_green);
<span class="co">/* purple outlined rectangle */</span>
al_draw_rectangle(<span class="fl">2.5</span>, <span class="fl">3.5</span>, <span class="fl">5.5</span>, <span class="fl">5.5</span>, color_purple, <span class="dv">1</span>);</code></pre></div>
<div class="figure">
<img src="images/primitives2.png" alt="Diagram showing a practical example of pixel output resulting from the invocation of several primitives addon functions." />
<p class="caption"><em>Diagram showing a practical example of pixel output resulting from the invocation of several primitives addon functions.</em></p>
</div>
<p>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 <code>al_draw_line</code> had to be offset by 0.5 in the appropriate dimensions.</p>
<p>Filled rectangles are generated by making a rectangle between the endpoints passed to the <code>al_draw_filled_rectangle</code>.</p>
<p>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.</p>
<p>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.</p>
<h2 id="al_draw_line">al_draw_line</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_line(<span class="dt">float</span> x1, <span class="dt">float</span> y1, <span class="dt">float</span> x2, <span class="dt">float</span> y2,
   ALLEGRO_COLOR color, <span class="dt">float</span> thickness)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/high_primitives.c#L77">Source Code</a></p>
<p>Draws a line segment between two points.</p>
<p><em>Parameters:</em></p>
<ul>
<li>x1, y1, x2, y2 - Start and end points of the line</li>
<li>color - Color of the line</li>
<li>thickness - Thickness of the line, pass <code>&lt;= 0</code> to draw hairline lines</li>
</ul>
<p>See also: <a href="primitives.html#al_draw_soft_line">al_draw_soft_line</a></p>
<h2 id="al_draw_triangle">al_draw_triangle</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_triangle(<span class="dt">float</span> x1, <span class="dt">float</span> y1, <span class="dt">float</span> x2, <span class="dt">float</span> y2,
   <span class="dt">float</span> x3, <span class="dt">float</span> y3, ALLEGRO_COLOR color, <span class="dt">float</span> thickness)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/high_primitives.c#L122">Source Code</a></p>
<p>Draws an outlined triangle.</p>
<p><em>Parameters:</em></p>
<ul>
<li>x1, y1, x2, y2, x3, y3 - Three points of the triangle</li>
<li>color - Color of the triangle</li>
<li>thickness - Thickness of the lines, pass <code>&lt;= 0</code> to draw hairline lines</li>
</ul>
<p>See also: <a href="primitives.html#al_draw_filled_triangle">al_draw_filled_triangle</a>, <a href="primitives.html#al_draw_soft_triangle">al_draw_soft_triangle</a></p>
<h2 id="al_draw_filled_triangle">al_draw_filled_triangle</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_filled_triangle(<span class="dt">float</span> x1, <span class="dt">float</span> y1, <span class="dt">float</span> x2, <span class="dt">float</span> y2,
   <span class="dt">float</span> x3, <span class="dt">float</span> y3, ALLEGRO_COLOR color)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/high_primitives.c#L335">Source Code</a></p>
<p>Draws a filled triangle.</p>
<p><em>Parameters:</em></p>
<ul>
<li>x1, y1, x2, y2, x3, y3 - Three points of the triangle</li>
<li>color - Color of the triangle</li>
</ul>
<p>See also: <a href="primitives.html#al_draw_triangle">al_draw_triangle</a></p>
<h2 id="al_draw_rectangle">al_draw_rectangle</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_rectangle(<span class="dt">float</span> x1, <span class="dt">float</span> y1, <span class="dt">float</span> x2, <span class="dt">float</span> y2,
   ALLEGRO_COLOR color, <span class="dt">float</span> thickness)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/high_primitives.c#L357">Source Code</a></p>
<p>Draws an outlined rectangle.</p>
<p><em>Parameters:</em></p>
<ul>
<li>x1, y1, x2, y2 - Upper left and lower right points of the rectangle</li>
<li>color - Color of the rectangle</li>
<li>thickness - Thickness of the lines, pass <code>&lt;= 0</code> to draw hairline lines</li>
</ul>
<p>See also: <a href="primitives.html#al_draw_filled_rectangle">al_draw_filled_rectangle</a>, <a href="primitives.html#al_draw_rounded_rectangle">al_draw_rounded_rectangle</a></p>
<h2 id="al_draw_filled_rectangle">al_draw_filled_rectangle</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_filled_rectangle(<span class="dt">float</span> x1, <span class="dt">float</span> y1, <span class="dt">float</span> x2, <span class="dt">float</span> y2,
   ALLEGRO_COLOR color)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/high_primitives.c#L402">Source Code</a></p>
<p>Draws a filled rectangle.</p>
<p><em>Parameters:</em></p>
<ul>
<li>x1, y1, x2, y2 - Upper left and lower right points of the rectangle</li>
<li>color - Color of the rectangle</li>
</ul>
<p>See also: <a href="primitives.html#al_draw_rectangle">al_draw_rectangle</a>, <a href="primitives.html#al_draw_filled_rounded_rectangle">al_draw_filled_rounded_rectangle</a></p>
<h2 id="al_draw_rounded_rectangle">al_draw_rounded_rectangle</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_rounded_rectangle(<span class="dt">float</span> x1, <span class="dt">float</span> y1, <span class="dt">float</span> x2, <span class="dt">float</span> y2,
   <span class="dt">float</span> rx, <span class="dt">float</span> ry, ALLEGRO_COLOR color, <span class="dt">float</span> thickness)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/high_primitives.c#L851">Source Code</a></p>
<p>Draws an outlined rounded rectangle.</p>
<p><em>Parameters:</em></p>
<ul>
<li>x1, y1, x2, y2 - Upper left and lower right points of the rectangle</li>
<li>color - Color of the rectangle</li>
<li>rx, ry - The radii of the round</li>
<li>thickness - Thickness of the lines, pass <code>&lt;= 0</code> to draw hairline lines</li>
</ul>
<p>See also: <a href="primitives.html#al_draw_filled_rounded_rectangle">al_draw_filled_rounded_rectangle</a>, <a href="primitives.html#al_draw_rectangle">al_draw_rectangle</a></p>
<h2 id="al_draw_filled_rounded_rectangle">al_draw_filled_rounded_rectangle</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_filled_rounded_rectangle(<span class="dt">float</span> x1, <span class="dt">float</span> y1, <span class="dt">float</span> x2, <span class="dt">float</span> y2,
   <span class="dt">float</span> rx, <span class="dt">float</span> ry, ALLEGRO_COLOR color)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/high_primitives.c#L949">Source Code</a></p>
<p>Draws an filled rounded rectangle.</p>
<p><em>Parameters:</em></p>
<ul>
<li>x1, y1, x2, y2 - Upper left and lower right points of the rectangle</li>
<li>color - Color of the rectangle</li>
<li>rx, ry - The radii of the round</li>
</ul>
<p>See also: <a href="primitives.html#al_draw_rounded_rectangle">al_draw_rounded_rectangle</a>, <a href="primitives.html#al_draw_filled_rectangle">al_draw_filled_rectangle</a></p>
<h2 id="al_calculate_arc">al_calculate_arc</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_calculate_arc(<span class="dt">float</span>* dest, <span class="dt">int</span> stride, <span class="dt">float</span> cx, <span class="dt">float</span> cy,
   <span class="dt">float</span> rx, <span class="dt">float</span> ry, <span class="dt">float</span> start_theta, <span class="dt">float</span> delta_theta, <span class="dt">float</span> thickness,
   <span class="dt">int</span> num_points)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/high_primitives.c#L423">Source Code</a></p>
<p>When <code>thickness &lt;= 0</code> this function computes positions of <code>num_points</code> regularly spaced points on an elliptical arc. When <code>thickness &gt; 0</code> this function computes two sets of points, obtained as follows: the first set is obtained by taking the points computed in the <code>thickness &lt;= 0</code> case and shifting them by <code>thickness / 2</code> outward, in a direction perpendicular to the arc curve. The second set is the same, but shifted <code>thickness / 2</code> 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).</p>
<p>The destination buffer <code>dest</code> 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 <code>stride</code>. For example, if you have a tightly packed array of floats with no spaces between pairs, then <code>stride</code> will be exactly <code>2 * sizeof(float)</code>.</p>
<p>Example with <code>thickness &lt;= 0</code>:</p>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">const</span> <span class="dt">int</span> num_points = <span class="dv">4</span>;
<span class="dt">float</span> points[num_points][<span class="dv">2</span>];
al_calculate_arc(&amp;points[<span class="dv">0</span>][<span class="dv">0</span>], <span class="dv">2</span> * <span class="kw">sizeof</span>(<span class="dt">float</span>), <span class="dv">0</span>, <span class="dv">0</span>, <span class="dv">10</span>, <span class="dv">10</span>, <span class="dv">0</span>, ALLEGRO_PI / <span class="dv">2</span>, <span class="dv">0</span>, num_points);

assert((<span class="dt">int</span>)points[<span class="dv">0</span>][<span class="dv">0</span>] == <span class="dv">10</span>);
assert((<span class="dt">int</span>)points[<span class="dv">0</span>][<span class="dv">1</span>] == <span class="dv">0</span>);

assert((<span class="dt">int</span>)points[num_points - <span class="dv">1</span>][<span class="dv">0</span>] == <span class="dv">0</span>);
assert((<span class="dt">int</span>)points[num_points - <span class="dv">1</span>][<span class="dv">1</span>] == <span class="dv">10</span>);</code></pre></div>
<p>Example with <code>thickness &gt; 0</code>:</p>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">const</span> <span class="dt">int</span> num_points = <span class="dv">4</span>;
<span class="dt">float</span> points[num_points * <span class="dv">2</span>][<span class="dv">2</span>];
al_calculate_arc(&amp;points[<span class="dv">0</span>][<span class="dv">0</span>], <span class="dv">2</span> * <span class="kw">sizeof</span>(<span class="dt">float</span>), <span class="dv">0</span>, <span class="dv">0</span>, <span class="dv">10</span>, <span class="dv">10</span>, <span class="dv">0</span>, ALLEGRO_PI / <span class="dv">2</span>, <span class="dv">2</span>, num_points);

assert((<span class="dt">int</span>)points[<span class="dv">0</span>][<span class="dv">0</span>] == <span class="dv">11</span>);
assert((<span class="dt">int</span>)points[<span class="dv">0</span>][<span class="dv">1</span>] == <span class="dv">0</span>);
assert((<span class="dt">int</span>)points[<span class="dv">1</span>][<span class="dv">0</span>] == <span class="dv">9</span>);
assert((<span class="dt">int</span>)points[<span class="dv">1</span>][<span class="dv">1</span>] == <span class="dv">0</span>);

assert((<span class="dt">int</span>)points[(num_points - <span class="dv">1</span>) * <span class="dv">2</span>][<span class="dv">0</span>] == <span class="dv">0</span>);
assert((<span class="dt">int</span>)points[(num_points - <span class="dv">1</span>) * <span class="dv">2</span>][<span class="dv">1</span>] == <span class="dv">11</span>);
assert((<span class="dt">int</span>)points[(num_points - <span class="dv">1</span>) * <span class="dv">2</span> + <span class="dv">1</span>][<span class="dv">0</span>] == <span class="dv">0</span>);
assert((<span class="dt">int</span>)points[(num_points - <span class="dv">1</span>) * <span class="dv">2</span> + <span class="dv">1</span>][<span class="dv">1</span>] == <span class="dv">9</span>);</code></pre></div>
<p><em>Parameters:</em></p>
<ul>
<li>dest - The destination buffer</li>
<li>stride - Distance (in bytes) between starts of successive pairs of points</li>
<li>cx, cy - Center of the arc</li>
<li>rx, ry - Radii of the arc</li>
<li>start_theta - The initial angle from which the arc is calculated in radians</li>
<li>delta_theta - Angular span of the arc in radians (pass a negative number to switch direction)</li>
<li>thickness - Thickness of the arc</li>
<li>num_points - The number of points to calculate</li>
</ul>
<p>See also: <a href="primitives.html#al_draw_arc">al_draw_arc</a>, <a href="primitives.html#al_calculate_spline">al_calculate_spline</a>, <a href="primitives.html#al_calculate_ribbon">al_calculate_ribbon</a></p>
<h2 id="al_draw_pieslice">al_draw_pieslice</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_pieslice(<span class="dt">float</span> cx, <span class="dt">float</span> cy, <span class="dt">float</span> r, <span class="dt">float</span> start_theta,
   <span class="dt">float</span> delta_theta, ALLEGRO_COLOR color, <span class="dt">float</span> thickness)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/high_primitives.c#L504">Source Code</a></p>
<p>Draws a pieslice (outlined circular sector).</p>
<p><em>Parameters:</em></p>
<ul>
<li>cx, cy - Center of the pieslice</li>
<li>r - Radius of the pieslice</li>
<li>color - Color of the pieslice</li>
<li>start_theta - The initial angle from which the pieslice is drawn in radians</li>
<li>delta_theta - Angular span of the pieslice in radians (pass a negative number to switch direction)</li>
<li>thickness - Thickness of the circle, pass <code>&lt;= 0</code> to draw hairline pieslice</li>
</ul>
<p>Since: 5.0.6, 5.1.0</p>
<p>See also: <a href="primitives.html#al_draw_filled_pieslice">al_draw_filled_pieslice</a></p>
<h2 id="al_draw_filled_pieslice">al_draw_filled_pieslice</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_filled_pieslice(<span class="dt">float</span> cx, <span class="dt">float</span> cy, <span class="dt">float</span> r, <span class="dt">float</span> start_theta,
   <span class="dt">float</span> delta_theta, ALLEGRO_COLOR color)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/high_primitives.c#L660">Source Code</a></p>
<p>Draws a filled pieslice (filled circular sector).</p>
<p><em>Parameters:</em></p>
<ul>
<li>cx, cy - Center of the pieslice</li>
<li>r - Radius of the pieslice</li>
<li>color - Color of the pieslice</li>
<li>start_theta - The initial angle from which the pieslice is drawn in radians</li>
<li>delta_theta - Angular span of the pieslice in radians (pass a negative number to switch direction)</li>
</ul>
<p>Since: 5.0.6, 5.1.0</p>
<p>See also: <a href="primitives.html#al_draw_pieslice">al_draw_pieslice</a></p>
<h2 id="al_draw_ellipse">al_draw_ellipse</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_ellipse(<span class="dt">float</span> cx, <span class="dt">float</span> cy, <span class="dt">float</span> rx, <span class="dt">float</span> ry,
   ALLEGRO_COLOR color, <span class="dt">float</span> thickness)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/high_primitives.c#L691">Source Code</a></p>
<p>Draws an outlined ellipse.</p>
<p><em>Parameters:</em></p>
<ul>
<li>cx, cy - Center of the ellipse</li>
<li>rx, ry - Radii of the ellipse</li>
<li>color - Color of the ellipse</li>
<li>thickness - Thickness of the ellipse, pass <code>&lt;= 0</code> to draw a hairline ellipse</li>
</ul>
<p>See also: <a href="primitives.html#al_draw_filled_ellipse">al_draw_filled_ellipse</a>, <a href="primitives.html#al_draw_circle">al_draw_circle</a></p>
<h2 id="al_draw_filled_ellipse">al_draw_filled_ellipse</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_filled_ellipse(<span class="dt">float</span> cx, <span class="dt">float</span> cy, <span class="dt">float</span> rx, <span class="dt">float</span> ry,
   ALLEGRO_COLOR color)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/high_primitives.c#L743">Source Code</a></p>
<p>Draws a filled ellipse.</p>
<p><em>Parameters:</em></p>
<ul>
<li>cx, cy - Center of the ellipse</li>
<li>rx, ry - Radii of the ellipse</li>
<li>color - Color of the ellipse</li>
</ul>
<p>See also: <a href="primitives.html#al_draw_ellipse">al_draw_ellipse</a>, <a href="primitives.html#al_draw_filled_circle">al_draw_filled_circle</a></p>
<h2 id="al_draw_circle">al_draw_circle</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_circle(<span class="dt">float</span> cx, <span class="dt">float</span> cy, <span class="dt">float</span> r, ALLEGRO_COLOR color,
   <span class="dt">float</span> thickness)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/high_primitives.c#L778">Source Code</a></p>
<p>Draws an outlined circle.</p>
<p><em>Parameters:</em></p>
<ul>
<li>cx, cy - Center of the circle</li>
<li>r - Radius of the circle</li>
<li>color - Color of the circle</li>
<li>thickness - Thickness of the circle, pass <code>&lt;= 0</code> to draw a hairline circle</li>
</ul>
<p>See also: <a href="primitives.html#al_draw_filled_circle">al_draw_filled_circle</a>, <a href="primitives.html#al_draw_ellipse">al_draw_ellipse</a></p>
<h2 id="al_draw_filled_circle">al_draw_filled_circle</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_filled_circle(<span class="dt">float</span> cx, <span class="dt">float</span> cy, <span class="dt">float</span> r, ALLEGRO_COLOR color)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/high_primitives.c#L786">Source Code</a></p>
<p>Draws a filled circle.</p>
<p><em>Parameters:</em></p>
<ul>
<li>cx, cy - Center of the circle</li>
<li>r - Radius of the circle</li>
<li>color - Color of the circle</li>
</ul>
<p>See also: <a href="primitives.html#al_draw_circle">al_draw_circle</a>, <a href="primitives.html#al_draw_filled_ellipse">al_draw_filled_ellipse</a></p>
<h2 id="al_draw_arc">al_draw_arc</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_arc(<span class="dt">float</span> cx, <span class="dt">float</span> cy, <span class="dt">float</span> r, <span class="dt">float</span> start_theta,
   <span class="dt">float</span> delta_theta, ALLEGRO_COLOR color, <span class="dt">float</span> thickness)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/high_primitives.c#L843">Source Code</a></p>
<p>Draws an arc.</p>
<p><em>Parameters:</em></p>
<ul>
<li>cx, cy - Center of the arc</li>
<li>r - Radius of the arc</li>
<li>color - Color of the arc</li>
<li>start_theta - The initial angle from which the arc is calculated in radians</li>
<li>delta_theta - Angular span of the arc in radians (pass a negative number to switch direction)</li>
<li>thickness - Thickness of the arc, pass <code>&lt;= 0</code> to draw hairline arc</li>
</ul>
<p>See also: <a href="primitives.html#al_calculate_arc">al_calculate_arc</a>, <a href="primitives.html#al_draw_elliptical_arc">al_draw_elliptical_arc</a></p>
<h2 id="al_draw_elliptical_arc">al_draw_elliptical_arc</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_elliptical_arc(<span class="dt">float</span> cx, <span class="dt">float</span> cy, <span class="dt">float</span> rx, <span class="dt">float</span> ry, <span class="dt">float</span> start_theta,
   <span class="dt">float</span> delta_theta, ALLEGRO_COLOR color, <span class="dt">float</span> thickness)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/high_primitives.c#L793">Source Code</a></p>
<p>Draws an elliptical arc.</p>
<p><em>Parameters:</em></p>
<ul>
<li>cx, cy - Center of the arc</li>
<li>rx, ry - Radii of the arc</li>
<li>color - Color of the arc</li>
<li>start_theta - The initial angle from which the arc is calculated in radians</li>
<li>delta_theta - Angular span of the arc in radians (pass a negative number to switch direction)</li>
<li>thickness - Thickness of the arc, pass <code>&lt;= 0</code> to draw hairline arc</li>
</ul>
<p>Since: 5.0.6, 5.1.0</p>
<p>See also: <a href="primitives.html#al_calculate_arc">al_calculate_arc</a>, <a href="primitives.html#al_draw_arc">al_draw_arc</a></p>
<h2 id="al_calculate_spline">al_calculate_spline</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_calculate_spline(<span class="dt">float</span>* dest, <span class="dt">int</span> stride, <span class="dt">float</span> points[<span class="dv">8</span>],
   <span class="dt">float</span> thickness, <span class="dt">int</span> num_segments)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/high_primitives.c#L1000">Source Code</a></p>
<p>Calculates a Bézier spline given 4 control points. If <code>thickness &lt;= 0</code>, then <code>num_segments</code> 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.</p>
<p><em>Parameters:</em></p>
<ul>
<li>dest - The destination buffer</li>
<li>stride - Distance (in bytes) between starts of successive pairs of coordinates</li>
<li>points - An array of 4 pairs of coordinates of the 4 control points</li>
<li>thickness - Thickness of the spline ribbon</li>
<li>num_segments - The number of points to calculate</li>
</ul>
<p>See also: <a href="primitives.html#al_draw_spline">al_draw_spline</a>, <a href="primitives.html#al_calculate_arc">al_calculate_arc</a>, <a href="primitives.html#al_calculate_ribbon">al_calculate_ribbon</a></p>
<h2 id="al_draw_spline">al_draw_spline</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_spline(<span class="dt">float</span> points[<span class="dv">8</span>], ALLEGRO_COLOR color, <span class="dt">float</span> thickness)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/high_primitives.c#L1079">Source Code</a></p>
<p>Draws a Bézier spline given 4 control points.</p>
<p><em>Parameters:</em></p>
<ul>
<li>points - An array of 4 pairs of coordinates of the 4 control points</li>
<li>color - Color of the spline</li>
<li>thickness - Thickness of the spline, pass <code>&lt;= 0</code> to draw a hairline spline</li>
</ul>
<p>See also: <a href="primitives.html#al_calculate_spline">al_calculate_spline</a></p>
<h2 id="al_calculate_ribbon">al_calculate_ribbon</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_calculate_ribbon(<span class="dt">float</span>* dest, <span class="dt">int</span> dest_stride, <span class="dt">const</span> <span class="dt">float</span> *points,
   <span class="dt">int</span> points_stride, <span class="dt">float</span> thickness, <span class="dt">int</span> num_segments)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/high_primitives.c#L1123">Source Code</a></p>
<p>Calculates a ribbon given an array of points. The ribbon will go through all of the passed points. If <code>thickness &lt;= 0</code>, then <code>num_segments</code> 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.</p>
<p><em>Parameters:</em></p>
<ul>
<li>dest - Pointer to the destination buffer</li>
<li>dest_stride - Distance (in bytes) between starts of successive pairs of coordinates in the destination buffer</li>
<li>points - An array of pairs of coordinates for each point</li>
<li>points_stride - Distance (in bytes) between starts of successive pairs of coordinates in the points buffer</li>
<li>thickness - Thickness of the spline ribbon</li>
<li>num_segments - The number of points to calculate</li>
</ul>
<p>See also: <a href="primitives.html#al_draw_ribbon">al_draw_ribbon</a>, <a href="primitives.html#al_calculate_arc">al_calculate_arc</a>, <a href="primitives.html#al_calculate_spline">al_calculate_spline</a></p>
<h2 id="al_draw_ribbon">al_draw_ribbon</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_ribbon(<span class="dt">const</span> <span class="dt">float</span> *points, <span class="dt">int</span> points_stride, ALLEGRO_COLOR color,
   <span class="dt">float</span> thickness, <span class="dt">int</span> num_segments)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/high_primitives.c#L1245">Source Code</a></p>
<p>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.</p>
<p><em>Parameters:</em></p>
<ul>
<li>points - An array of coordinate pairs (x and y) for each point</li>
<li>points_stride - Distance (in bytes) between starts of successive pairs of coordinates in the points buffer</li>
<li>color - Color of the spline</li>
<li>thickness - Thickness of the spline, pass <code>&lt;= 0</code> to draw hairline spline</li>
<li>num_segments - The number of segments</li>
</ul>
<p>See also: <a href="primitives.html#al_calculate_ribbon">al_calculate_ribbon</a></p>
<h1 id="low-level-drawing-routines">Low level drawing routines</h1>
<p>Low level drawing routines allow for more advanced usage of the addon, allowing you to pass arbitrary sequences of vertices to draw to the screen. These routines also support using textures on the primitives with the following restrictions:</p>
<p>For maximum portability, you should only use textures that have dimensions that are a power of two, as not every videocard supports textures of different sizes completely. This warning is relaxed, however, if the texture coordinates never exit the boundaries of a single bitmap (i.e. you are not having the texture repeat/tile). As long as that is the case, any texture can be used safely. Sub-bitmaps work as textures, but cannot be tiled.</p>
<p>Some platforms also dictate a minimum texture size, which means that textures smaller than that size will not tile properly. The minimum size that will work on all platforms is 32 by 32.</p>
<p>A note about pixel coordinates. In OpenGL the texture coordinate (0, 0) refers to the top left corner of the pixel. This confuses some drivers, because due to rounding errors the actual pixel sampled might be the pixel to the top and/or left of the (0, 0) pixel. To make this error less likely it is advisable to offset the texture coordinates you pass to the al_draw_prim by (0.5, 0.5) if you need precise pixel control. E.g. to refer to pixel (5, 10) you'd set the u and v to 5.5 and 10.5 respectively.</p>
<p>See also: <a href="primitives.html#pixel-precise-output">Pixel-precise output</a></p>
<h2 id="al_draw_prim">al_draw_prim</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">int</span> al_draw_prim(<span class="dt">const</span> <span class="dt">void</span>* vtxs, <span class="dt">const</span> ALLEGRO_VERTEX_DECL* decl,
   ALLEGRO_BITMAP* texture, <span class="dt">int</span> start, <span class="dt">int</span> end, <span class="dt">int</span> type)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/primitives.c#L68">Source Code</a></p>
<p>Draws a subset of the passed vertex array.</p>
<p><em>Parameters:</em></p>
<ul>
<li>texture - Texture to use, pass NULL to use only color shaded primitves</li>
<li>vtxs - Pointer to an array of vertices</li>
<li>decl - Pointer to a <a href="primitives.html#al_create_vertex_decl">vertex declaration</a>. If set to NULL, the vertices are assumed to be of the <a href="primitives.html#allegro_vertex">ALLEGRO_VERTEX</a> type</li>
<li>start - Start index of the subset of the vertex array to draw</li>
<li>end - One past the last index of the subset of the vertex array to draw</li>
<li>type - A member of the <a href="primitives.html#allegro_prim_type">ALLEGRO_PRIM_TYPE</a> enumeration, specifying what kind of primitive to draw</li>
</ul>
<p><em>Returns:</em> Number of primitives drawn</p>
<p>For example to draw a textured triangle you could use:</p>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c">ALLEGRO_COLOR white = al_map_rgb_f(<span class="dv">1</span>, <span class="dv">1</span>, <span class="dv">1</span>);
ALLEGRO_VERTEX v[] = {
   {.x = <span class="dv">128</span>, .y = <span class="dv">0</span>, .z = <span class="dv">0</span>, .color = white, .u = <span class="dv">128</span>, .v = <span class="dv">0</span>},
   {.x = <span class="dv">0</span>, .y = <span class="dv">256</span>, .z = <span class="dv">0</span>, .color = white, .u = <span class="dv">0</span>, .v = <span class="dv">256</span>},
   {.x = <span class="dv">256</span>, .y = <span class="dv">256</span>, .z = <span class="dv">0</span>, .color = white, .u = <span class="dv">256</span>, .v = <span class="dv">256</span>}};
al_draw_prim(v, NULL, texture, <span class="dv">0</span>, <span class="dv">3</span>, ALLEGRO_PRIM_TRIANGLE_LIST);</code></pre></div>
<p>See also: <a href="primitives.html#allegro_vertex">ALLEGRO_VERTEX</a>, <a href="primitives.html#allegro_prim_type">ALLEGRO_PRIM_TYPE</a>, <a href="primitives.html#allegro_vertex_decl">ALLEGRO_VERTEX_DECL</a>, <a href="primitives.html#al_draw_indexed_prim">al_draw_indexed_prim</a></p>
<h2 id="al_draw_indexed_prim">al_draw_indexed_prim</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">int</span> al_draw_indexed_prim(<span class="dt">const</span> <span class="dt">void</span>* vtxs, <span class="dt">const</span> ALLEGRO_VERTEX_DECL* decl,
   ALLEGRO_BITMAP* texture, <span class="dt">const</span> <span class="dt">int</span>* indices, <span class="dt">int</span> num_vtx, <span class="dt">int</span> type)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/primitives.c#L104">Source Code</a></p>
<p>Draws a subset of the passed vertex array. This function uses an index array to specify which vertices to use.</p>
<p><em>Parameters:</em></p>
<ul>
<li>texture - Texture to use, pass NULL to use only color shaded primitves</li>
<li>vtxs - Pointer to an array of vertices</li>
<li>decl - Pointer to a vertex declaration. If set to NULL, the vtxs are assumed to be of the ALLEGRO_VERTEX type</li>
<li>indices - An array of indices into the vertex array</li>
<li>num_vtx - Number of indices from the indices array you want to draw</li>
<li>type - A member of the <a href="primitives.html#allegro_prim_type">ALLEGRO_PRIM_TYPE</a> enumeration, specifying what kind of primitive to draw</li>
</ul>
<p><em>Returns:</em> Number of primitives drawn</p>
<p>See also: <a href="primitives.html#allegro_vertex">ALLEGRO_VERTEX</a>, <a href="primitives.html#allegro_prim_type">ALLEGRO_PRIM_TYPE</a>, <a href="primitives.html#allegro_vertex_decl">ALLEGRO_VERTEX_DECL</a>, <a href="primitives.html#al_draw_prim">al_draw_prim</a></p>
<h2 id="al_draw_vertex_buffer">al_draw_vertex_buffer</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">int</span> al_draw_vertex_buffer(ALLEGRO_VERTEX_BUFFER* vertex_buffer,
   ALLEGRO_BITMAP* texture, <span class="dt">int</span> start, <span class="dt">int</span> end, <span class="dt">int</span> type)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/primitives.c#L501">Source Code</a></p>
<p>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 <code>ALLEGRO_PRIM_BUFFER_READWRITE</code>).</p>
<p><em>Parameters:</em></p>
<ul>
<li>vertex_buffer - Vertex buffer to draw</li>
<li>texture - Texture to use, pass NULL to use only color shaded primitves</li>
<li>start - Start index of the subset of the vertex buffer to draw</li>
<li>end - One past the last index of the subset of the vertex buffer to draw</li>
<li>type - A member of the <a href="primitives.html#allegro_prim_type">ALLEGRO_PRIM_TYPE</a> enumeration, specifying what kind of primitive to draw</li>
</ul>
<p><em>Returns:</em> Number of primitives drawn</p>
<p>Since: 5.1.3</p>
<p>See also: <a href="primitives.html#allegro_vertex_buffer">ALLEGRO_VERTEX_BUFFER</a>, <a href="primitives.html#allegro_prim_type">ALLEGRO_PRIM_TYPE</a></p>
<h2 id="al_draw_indexed_buffer">al_draw_indexed_buffer</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">int</span> al_draw_indexed_buffer(ALLEGRO_VERTEX_BUFFER* vertex_buffer,
   ALLEGRO_BITMAP* texture, ALLEGRO_INDEX_BUFFER* index_buffer,
   <span class="dt">int</span> start, <span class="dt">int</span> end, <span class="dt">int</span> type)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/primitives.c#L536">Source Code</a></p>
<p>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 <code>ALLEGRO_PRIM_BUFFER_READWRITE</code>).</p>
<p><em>Parameters:</em></p>
<ul>
<li>vertex_buffer - Vertex buffer to draw</li>
<li>texture - Texture to use, pass NULL to use only color shaded primitves</li>
<li>index_buffer - Index buffer to use</li>
<li>start - Start index of the subset of the vertex buffer to draw</li>
<li>end - One past the last index of the subset of the vertex buffer to draw</li>
<li>type - A member of the <a href="primitives.html#allegro_prim_type">ALLEGRO_PRIM_TYPE</a> enumeration, specifying what kind of primitive to draw. Note that ALLEGRO_PRIM_LINE_LOOP and ALLEGRO_PRIM_POINT_LIST are not supported.</li>
</ul>
<p><em>Returns:</em> Number of primitives drawn</p>
<p>Since: 5.1.8</p>
<p>See also: <a href="primitives.html#allegro_vertex_buffer">ALLEGRO_VERTEX_BUFFER</a>, <a href="primitives.html#allegro_index_buffer">ALLEGRO_INDEX_BUFFER</a>, <a href="primitives.html#allegro_prim_type">ALLEGRO_PRIM_TYPE</a></p>
<h2 id="al_draw_soft_triangle">al_draw_soft_triangle</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_soft_triangle(
   ALLEGRO_VERTEX* v1, ALLEGRO_VERTEX* v2, ALLEGRO_VERTEX* v3, <span class="dt">uintptr_t</span> state,
   <span class="dt">void</span> (*init)(<span class="dt">uintptr_t</span>, ALLEGRO_VERTEX*, ALLEGRO_VERTEX*, ALLEGRO_VERTEX*),
   <span class="dt">void</span> (*first)(<span class="dt">uintptr_t</span>, <span class="dt">int</span>, <span class="dt">int</span>, <span class="dt">int</span>, <span class="dt">int</span>),
   <span class="dt">void</span> (*step)(<span class="dt">uintptr_t</span>, <span class="dt">int</span>),
   <span class="dt">void</span> (*draw)(<span class="dt">uintptr_t</span>, <span class="dt">int</span>, <span class="dt">int</span>, <span class="dt">int</span>))</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/prim_soft.c#L522">Source Code</a></p>
<p>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.</p>
<p><em>Parameters:</em></p>
<ul>
<li>v1, v2, v3 - The three vertices of the triangle</li>
<li>state - A pointer to a user supplied struct, this struct will be passed to all the pixel functions</li>
<li>init - Called once per call before any drawing is done. The three points passed to it may be altered by clipping.</li>
<li>first - Called twice per call, once per triangle segment. 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.</li>
<li>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.</li>
<li>draw - Called once per scanline. The function is expected to draw the scanline starting with a point specified by the first two parameters (corresponding to x and y values) going to the right until it reaches the value of the third parameter (the x value of the end point). All coordinates are inclusive.</li>
</ul>
<p>See also: <a href="primitives.html#al_draw_triangle">al_draw_triangle</a></p>
<h2 id="al_draw_soft_line">al_draw_soft_line</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_soft_line(ALLEGRO_VERTEX* v1, ALLEGRO_VERTEX* v2, <span class="dt">uintptr_t</span> state,
   <span class="dt">void</span> (*first)(<span class="dt">uintptr_t</span>, <span class="dt">int</span>, <span class="dt">int</span>, ALLEGRO_VERTEX*, ALLEGRO_VERTEX*),
   <span class="dt">void</span> (*step)(<span class="dt">uintptr_t</span>, <span class="dt">int</span>),
   <span class="dt">void</span> (*draw)(<span class="dt">uintptr_t</span>, <span class="dt">int</span>, <span class="dt">int</span>))</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/line_soft.c#L572">Source Code</a></p>
<p>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.</p>
<p><em>Parameters:</em></p>
<ul>
<li>v1, v2 - The two vertices of the line</li>
<li>state - A pointer to a user supplied struct, this struct will be passed to all the pixel functions</li>
<li>first - Called before drawing the first pixel of the 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.</li>
<li>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.</li>
<li>draw - Called once per pixel. The function is expected to draw the pixel at the coordinates passed to it.</li>
</ul>
<p>See also: <a href="primitives.html#al_draw_line">al_draw_line</a></p>
<h1 id="custom-vertex-declaration-routines">Custom vertex declaration routines</h1>
<h2 id="al_create_vertex_decl">al_create_vertex_decl</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c">ALLEGRO_VERTEX_DECL* al_create_vertex_decl(<span class="dt">const</span> ALLEGRO_VERTEX_ELEMENT* elements, <span class="dt">int</span> stride)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/primitives.c#L158">Source Code</a></p>
<p>Creates a vertex declaration, which describes a custom vertex format.</p>
<p><em>Parameters:</em></p>
<ul>
<li>elements - An array of <a href="primitives.html#allegro_vertex_element">ALLEGRO_VERTEX_ELEMENT</a> structures.</li>
<li>stride - Size of the custom vertex structure</li>
</ul>
<p><em>Returns:</em> Newly created vertex declaration.</p>
<p>See also: <a href="primitives.html#allegro_vertex_element">ALLEGRO_VERTEX_ELEMENT</a>, <a href="primitives.html#allegro_vertex_decl">ALLEGRO_VERTEX_DECL</a>, <a href="primitives.html#al_destroy_vertex_decl">al_destroy_vertex_decl</a></p>
<h2 id="al_destroy_vertex_decl">al_destroy_vertex_decl</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_destroy_vertex_decl(ALLEGRO_VERTEX_DECL* decl)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/primitives.c#L218">Source Code</a></p>
<p>Destroys a vertex declaration.</p>
<p><em>Parameters:</em></p>
<ul>
<li>decl - Vertex declaration to destroy</li>
</ul>
<p>See also: <a href="primitives.html#allegro_vertex_element">ALLEGRO_VERTEX_ELEMENT</a>, <a href="primitives.html#allegro_vertex_decl">ALLEGRO_VERTEX_DECL</a>, <a href="primitives.html#al_create_vertex_decl">al_create_vertex_decl</a></p>
<h1 id="vertex-buffer-routines">Vertex buffer routines</h1>
<h2 id="al_create_vertex_buffer">al_create_vertex_buffer</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c">ALLEGRO_VERTEX_BUFFER* al_create_vertex_buffer(ALLEGRO_VERTEX_DECL* decl,
   <span class="dt">const</span> <span class="dt">void</span>* initial_data, <span class="dt">int</span> num_vertices, <span class="dt">int</span> flags)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/primitives.c#L229">Source Code</a></p>
<p>Creates a vertex buffer. Can return NULL if the buffer could not be created (e.g. the system only supports write-only buffers).</p>
<blockquote>
<p><em>Note:</em></p>
<p>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.</p>
</blockquote>
<p><em>Parameters:</em></p>
<ul>
<li>decl - Vertex type that this buffer will hold. NULL implies that this buffer will hold <a href="primitives.html#allegro_vertex">ALLEGRO_VERTEX</a> vertices</li>
<li>initial_data - Memory buffer to copy from to initialize the vertex buffer. Can be <code>NULL</code>, in which case the buffer is uninitialized.</li>
<li>num_vertices - Number of vertices the buffer will hold</li>
<li>flags - A combination of the <a href="primitives.html#allegro_prim_buffer_flags">ALLEGRO_PRIM_BUFFER_FLAGS</a> flags specifying how this buffer will be created. Passing 0 is the same as passing <code>ALLEGRO_PRIM_BUFFER_STATIC</code>.</li>
</ul>
<p>Since: 5.1.3</p>
<p>See also: <a href="primitives.html#allegro_vertex_buffer">ALLEGRO_VERTEX_BUFFER</a>, <a href="primitives.html#al_destroy_vertex_buffer">al_destroy_vertex_buffer</a></p>
<h2 id="al_destroy_vertex_buffer">al_destroy_vertex_buffer</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_destroy_vertex_buffer(ALLEGRO_VERTEX_BUFFER* buffer)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/primitives.c#L303">Source Code</a></p>
<p>Destroys a vertex buffer. Does nothing if passed NULL.</p>
<p>Since: 5.1.3</p>
<p>See also: <a href="primitives.html#allegro_vertex_buffer">ALLEGRO_VERTEX_BUFFER</a>, <a href="primitives.html#al_create_vertex_buffer">al_create_vertex_buffer</a></p>
<h2 id="al_lock_vertex_buffer">al_lock_vertex_buffer</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span>* al_lock_vertex_buffer(ALLEGRO_VERTEX_BUFFER* buffer, <span class="dt">int</span> offset,
   <span class="dt">int</span> length, <span class="dt">int</span> flags)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/primitives.c#L360">Source Code</a></p>
<p>Locks a vertex buffer so you can access its data. Will return NULL if the parameters are invalid, if reading is requested from a write only buffer, or if the buffer is already locked.</p>
<p><em>Parameters:</em></p>
<ul>
<li>buffer - Vertex buffer to lock</li>
<li>offset - Vertex index of the start of the locked range</li>
<li>length - How many vertices to lock</li>
<li>flags - ALLEGRO_LOCK_READONLY, ALLEGRO_LOCK_WRITEONLY or ALLEGRO_LOCK_READWRITE</li>
</ul>
<p>Since: 5.1.3</p>
<p>See also: <a href="primitives.html#allegro_vertex_buffer">ALLEGRO_VERTEX_BUFFER</a>, <a href="primitives.html#al_unlock_vertex_buffer">al_unlock_vertex_buffer</a></p>
<h2 id="al_unlock_vertex_buffer">al_unlock_vertex_buffer</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_unlock_vertex_buffer(ALLEGRO_VERTEX_BUFFER* buffer)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/primitives.c#L415">Source Code</a></p>
<p>Unlocks a previously locked vertex buffer.</p>
<p>Since: 5.1.3</p>
<p>See also: <a href="primitives.html#allegro_vertex_buffer">ALLEGRO_VERTEX_BUFFER</a>, <a href="primitives.html#al_lock_vertex_buffer">al_lock_vertex_buffer</a></p>
<h2 id="al_get_vertex_buffer_size">al_get_vertex_buffer_size</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">int</span> al_get_vertex_buffer_size(ALLEGRO_VERTEX_BUFFER* buffer)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/primitives.c#L574">Source Code</a></p>
<p>Returns the size of the vertex buffer</p>
<p>Since: 5.1.8</p>
<p>See also: <a href="primitives.html#allegro_vertex_buffer">ALLEGRO_VERTEX_BUFFER</a></p>
<h1 id="index-buffer-routines">Index buffer routines</h1>
<h2 id="al_create_index_buffer">al_create_index_buffer</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c">ALLEGRO_INDEX_BUFFER* al_create_index_buffer(<span class="dt">int</span> index_size,
    <span class="dt">const</span> <span class="dt">void</span>* initial_data, <span class="dt">int</span> num_indices, <span class="dt">int</span> flags)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/primitives.c#L263">Source Code</a></p>
<p>Creates a index buffer. Can return NULL if the buffer could not be created (e.g. the system only supports write-only buffers).</p>
<blockquote>
<p><em>Note:</em></p>
<p>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.</p>
</blockquote>
<p><em>Parameters:</em></p>
<ul>
<li>index_size - Size of the index in bytes. Supported sizes are 2 for short integers and 4 for integers</li>
<li>initial_data - Memory buffer to copy from to initialize the index buffer. Can be <code>NULL</code>, in which case the buffer is uninitialized.</li>
<li>num_indices - Number of indices the buffer will hold</li>
<li>flags - A combination of the <a href="primitives.html#allegro_prim_buffer_flags">ALLEGRO_PRIM_BUFFER_FLAGS</a> flags specifying how this buffer will be created. Passing 0 is the same as passing <code>ALLEGRO_PRIM_BUFFER_STATIC</code>.</li>
</ul>
<p>Since: 5.1.8</p>
<p>See also: <a href="primitives.html#allegro_index_buffer">ALLEGRO_INDEX_BUFFER</a>, <a href="primitives.html#al_destroy_index_buffer">al_destroy_index_buffer</a></p>
<h2 id="al_destroy_index_buffer">al_destroy_index_buffer</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_destroy_index_buffer(ALLEGRO_INDEX_BUFFER* buffer)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/primitives.c#L325">Source Code</a></p>
<p>Destroys a index buffer. Does nothing if passed NULL.</p>
<p>Since: 5.1.8</p>
<p>See also: <a href="primitives.html#allegro_index_buffer">ALLEGRO_INDEX_BUFFER</a>, <a href="primitives.html#al_create_index_buffer">al_create_index_buffer</a></p>
<h2 id="al_lock_index_buffer">al_lock_index_buffer</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span>* al_lock_index_buffer(ALLEGRO_INDEX_BUFFER* buffer, <span class="dt">int</span> offset,
    <span class="dt">int</span> length, <span class="dt">int</span> flags)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/primitives.c#L389">Source Code</a></p>
<p>Locks a index buffer so you can access its data. Will return NULL if the parameters are invalid, if reading is requested from a write only buffer and if the buffer is already locked.</p>
<p><em>Parameters:</em></p>
<ul>
<li>buffer - Index buffer to lock</li>
<li>offset - Element index of the start of the locked range</li>
<li>length - How many indices to lock</li>
<li>flags - ALLEGRO_LOCK_READONLY, ALLEGRO_LOCK_WRITEONLY or ALLEGRO_LOCK_READWRITE</li>
</ul>
<p>Since: 5.1.8</p>
<p>See also: <a href="primitives.html#allegro_index_buffer">ALLEGRO_INDEX_BUFFER</a>, <a href="primitives.html#al_unlock_index_buffer">al_unlock_index_buffer</a></p>
<h2 id="al_unlock_index_buffer">al_unlock_index_buffer</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_unlock_index_buffer(ALLEGRO_INDEX_BUFFER* buffer)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/primitives.c#L436">Source Code</a></p>
<p>Unlocks a previously locked index buffer.</p>
<p>Since: 5.1.8</p>
<p>See also: <a href="primitives.html#allegro_index_buffer">ALLEGRO_INDEX_BUFFER</a>, <a href="primitives.html#al_lock_index_buffer">al_lock_index_buffer</a></p>
<h2 id="al_get_index_buffer_size">al_get_index_buffer_size</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">int</span> al_get_index_buffer_size(ALLEGRO_INDEX_BUFFER* buffer)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/primitives.c#L582">Source Code</a></p>
<p>Returns the size of the index buffer</p>
<p>Since: 5.1.8</p>
<p>See also: <a href="primitives.html#allegro_index_buffer">ALLEGRO_INDEX_BUFFER</a></p>
<h1 id="polygon-routines">Polygon routines</h1>
<h2 id="al_draw_polyline">al_draw_polyline</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_polyline(<span class="dt">const</span> <span class="dt">float</span>* vertices, <span class="dt">int</span> vertex_stride,
   <span class="dt">int</span> vertex_count, <span class="dt">int</span> join_style, <span class="dt">int</span> cap_style,
   ALLEGRO_COLOR color, <span class="dt">float</span> thickness, <span class="dt">float</span> miter_limit)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/polyline.c#L537">Source Code</a></p>
<p>Draw a series of line segments.</p>
<ul>
<li>vertices - Interleaved array of (x, y) vertex coordinates</li>
<li>vertex_stride - the number of bytes between pairs of vertices (the stride)</li>
<li>vertex_count - Number of vertices in the array</li>
<li>join_style - Member of <a href="primitives.html#allegro_line_join">ALLEGRO_LINE_JOIN</a> specifying how to render the joins between line segments</li>
<li>cap_style - Member of <a href="primitives.html#allegro_line_cap">ALLEGRO_LINE_CAP</a> specifying how to render the end caps</li>
<li>color - Color of the line</li>
<li>thickness - Thickness of the line, pass <code>&lt;= 0</code> to draw hairline lines</li>
<li>miter_limit - Parameter for miter join style</li>
</ul>
<p>The stride is normally <code>2 * sizeof(float)</code> but may be more if the vertex coordinates are in an array of some structure type, e.g.</p>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="kw">struct</span> VertexInfo {
   <span class="dt">float</span> x;
   <span class="dt">float</span> y;
   <span class="dt">int</span> id;
};

<span class="dt">void</span> my_draw(<span class="kw">struct</span> VertexInfo verts[], <span class="dt">int</span> vertex_count, ALLEGRO_COLOR c)
{
   al_draw_polyline((<span class="dt">float</span> *)verts, <span class="kw">sizeof</span>(VertexInfo), vertex_count,
      ALLEGRO_LINE_JOIN_NONE, ALLEGRO_LINE_CAP_NONE, c, <span class="fl">1.0</span>, <span class="fl">1.0</span>);
}</code></pre></div>
<p>The stride may also be negative if the vertices are stored in reverse order.</p>
<p>Since: 5.1.0</p>
<p>See also: <a href="primitives.html#al_draw_polygon">al_draw_polygon</a>, <a href="primitives.html#allegro_line_join">ALLEGRO_LINE_JOIN</a>, <a href="primitives.html#allegro_line_cap">ALLEGRO_LINE_CAP</a></p>
<h2 id="al_draw_polygon">al_draw_polygon</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_polygon(<span class="dt">const</span> <span class="dt">float</span> *vertices, <span class="dt">int</span> vertex_count,
   <span class="dt">int</span> join_style, ALLEGRO_COLOR color, <span class="dt">float</span> thickness, <span class="dt">float</span> miter_limit)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/polygon.c#L44">Source Code</a></p>
<p>Draw an unfilled polygon. This is the same as passing <code>ALLEGRO_LINE_CAP_CLOSED</code> to <a href="primitives.html#al_draw_polyline">al_draw_polyline</a>.</p>
<ul>
<li>vertex - Interleaved array of (x, y) vertex coordinates</li>
<li>vertex_count - Number of vertices in the array</li>
<li>join_style - Member of <a href="primitives.html#allegro_line_join">ALLEGRO_LINE_JOIN</a> specifying how to render the joins between line segments</li>
<li>color - Color of the line</li>
<li>thickness - Thickness of the line, pass <code>&lt;= 0</code> to draw hairline lines</li>
<li>miter_limit - Parameter for miter join style</li>
</ul>
<p>Since: 5.1.0</p>
<p>See also: <a href="primitives.html#al_draw_filled_polygon">al_draw_filled_polygon</a>, <a href="primitives.html#al_draw_polyline">al_draw_polyline</a>, <a href="primitives.html#allegro_line_join">ALLEGRO_LINE_JOIN</a></p>
<h2 id="al_draw_filled_polygon">al_draw_filled_polygon</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_filled_polygon(<span class="dt">const</span> <span class="dt">float</span> *vertices, <span class="dt">int</span> vertex_count,
   ALLEGRO_COLOR color)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/polygon.c#L53">Source Code</a></p>
<p>Draw a filled, simple polygon. Simple means it does not have to be convex but must not be self-overlapping.</p>
<ul>
<li>vertices - Interleaved array of (x, y) vertex coordinates</li>
<li>vertex_count - Number of vertices in the array</li>
<li>color - Color of the filled polygon</li>
</ul>
<p>When the y-axis is facing downwards (the usual), the coordinates must be ordered anti-clockwise.</p>
<p>Since: 5.1.0</p>
<p>See also: <a href="primitives.html#al_draw_polygon">al_draw_polygon</a>, <a href="primitives.html#al_draw_filled_polygon_with_holes">al_draw_filled_polygon_with_holes</a></p>
<h2 id="al_draw_filled_polygon_with_holes">al_draw_filled_polygon_with_holes</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">void</span> al_draw_filled_polygon_with_holes(<span class="dt">const</span> <span class="dt">float</span> *vertices,
   <span class="dt">const</span> <span class="dt">int</span> *vertex_counts, ALLEGRO_COLOR color)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/polygon.c#L71">Source Code</a></p>
<p>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.</p>
<ul>
<li>vertices - Interleaved array of (x, y) vertex coordinates for each of the polygons, including holes.</li>
<li>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.</li>
<li>color - Color of the filled polygon</li>
</ul>
<p>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.</p>
<p>For example:</p>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="dt">float</span> vertices[] = {
      <span class="dv">0</span>,   <span class="dv">0</span>, <span class="co">// filled polygon, upper left corner</span>
      <span class="dv">0</span>, <span class="dv">100</span>, <span class="co">// filled polygon, lower left corner</span>
    <span class="dv">100</span>, <span class="dv">100</span>, <span class="co">// filled polygon, lower right corner</span>
    <span class="dv">100</span>,   <span class="dv">0</span>, <span class="co">// filled polygon, upper right corner</span>
     <span class="dv">10</span>,  <span class="dv">10</span>, <span class="co">// hole, upper left</span>
     <span class="dv">90</span>,  <span class="dv">10</span>, <span class="co">// hole, upper right</span>
     <span class="dv">90</span>,  <span class="dv">90</span>  <span class="co">// hole, lower right</span>
};
<span class="dt">int</span> vertex_counts[] = {
   <span class="dv">4</span>, <span class="co">// number of vertices for filled polygon</span>
   <span class="dv">3</span>, <span class="co">// number of vertices for hole</span>
   <span class="dv">0</span>  <span class="co">// terminator</span>
};</code></pre></div>
<p>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).</p>
<p>Since: 5.1.0</p>
<p>See also: <a href="primitives.html#al_draw_filled_polygon">al_draw_filled_polygon</a>, <a href="primitives.html#al_draw_filled_polygon_with_holes">al_draw_filled_polygon_with_holes</a>, <a href="primitives.html#al_triangulate_polygon">al_triangulate_polygon</a></p>
<h2 id="al_triangulate_polygon">al_triangulate_polygon</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c">bool al_triangulate_polygon(
   <span class="dt">const</span> <span class="dt">float</span>* vertices, <span class="dt">size_t</span> vertex_stride, <span class="dt">const</span> <span class="dt">int</span>* vertex_counts,
   <span class="dt">void</span> (*emit_triangle)(<span class="dt">int</span>, <span class="dt">int</span>, <span class="dt">int</span>, <span class="dt">void</span>*), <span class="dt">void</span>* userdata)</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/triangulator.c#L814">Source Code</a></p>
<p>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.</p>
<p><em>Parameters:</em></p>
<ul>
<li>vertices - Interleaved array of (x, y) vertex coordinates for each of the polygons, including holes.</li>
<li>vertex_stride - distance (in bytes) between successive pairs of vertices in the array.</li>
<li>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.</li>
<li>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 <code>vertices</code> and <code>userdata</code>.</li>
<li>userdata - arbitrary data to be passed to emit_triangle.</li>
</ul>
<p>Since: 5.1.0</p>
<p>See also: <a href="primitives.html#al_draw_filled_polygon_with_holes">al_draw_filled_polygon_with_holes</a></p>
<h1 id="structures-and-types">Structures and types</h1>
<h2 id="allegro_vertex">ALLEGRO_VERTEX</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="kw">typedef</span> <span class="kw">struct</span> ALLEGRO_VERTEX ALLEGRO_VERTEX;</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/allegro5/allegro_primitives.h#L145">Source Code</a></p>
<p>Defines the generic vertex type, with a 3D position, color and texture coordinates for a single texture. Note that at this time, the software driver for this addon cannot render 3D primitives. If you want a 2D only primitive, set z to 0. Note that you must initialize all members of this struct when you're using it. One exception to this rule are the u and v variables which can be left uninitialized when you are not using textures.</p>
<p><em>Fields:</em></p>
<ul>
<li>x, y, z - Position of the vertex (float)</li>
<li>u, v - Texture coordinates measured in pixels (float)</li>
<li>color - <a href="graphics.html#allegro_color">ALLEGRO_COLOR</a> structure, storing the color of the vertex</li>
</ul>
<p>See also: <a href="primitives.html#allegro_prim_attr">ALLEGRO_PRIM_ATTR</a></p>
<h2 id="allegro_vertex_decl">ALLEGRO_VERTEX_DECL</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="kw">typedef</span> <span class="kw">struct</span> ALLEGRO_VERTEX_DECL ALLEGRO_VERTEX_DECL;</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/allegro5/allegro_primitives.h#L137">Source Code</a></p>
<p>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.</p>
<p>See also: <a href="primitives.html#al_create_vertex_decl">al_create_vertex_decl</a>, <a href="primitives.html#al_destroy_vertex_decl">al_destroy_vertex_decl</a>, <a href="primitives.html#allegro_vertex_element">ALLEGRO_VERTEX_ELEMENT</a></p>
<h2 id="allegro_vertex_element">ALLEGRO_VERTEX_ELEMENT</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="kw">typedef</span> <span class="kw">struct</span> ALLEGRO_VERTEX_ELEMENT ALLEGRO_VERTEX_ELEMENT;</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/allegro5/allegro_primitives.h#L127">Source Code</a></p>
<p>A small structure describing a certain element of a vertex. E.g. the position of the vertex, or its color. These structures are used by the <a href="primitives.html#al_create_vertex_decl">al_create_vertex_decl</a> function to create the vertex declaration. For that they generally occur in an array. The last element of such an array should have the attribute field equal to 0, to signify that it is the end of the array. Here is an example code that would create a declaration describing the <a href="primitives.html#allegro_vertex">ALLEGRO_VERTEX</a> structure (passing this as vertex declaration to al_draw_prim would be identical to passing NULL):</p>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="co">/* On compilers without the offsetof keyword you need to obtain the</span>
<span class="co"> * offset with sizeof and make sure to account for packing.</span>
<span class="co"> */</span>
ALLEGRO_VERTEX_ELEMENT elems[] = {
   {ALLEGRO_PRIM_POSITION, ALLEGRO_PRIM_FLOAT_3, offsetof(ALLEGRO_VERTEX, x)},
   {ALLEGRO_PRIM_TEX_COORD_PIXEL, ALLEGRO_PRIM_FLOAT_2, offsetof(ALLEGRO_VERTEX, u)},
   {ALLEGRO_PRIM_COLOR_ATTR, <span class="dv">0</span>, offsetof(ALLEGRO_VERTEX, color)},
   {<span class="dv">0</span>, <span class="dv">0</span>, <span class="dv">0</span>}
};
ALLEGRO_VERTEX_DECL* decl = al_create_vertex_decl(elems, <span class="kw">sizeof</span>(ALLEGRO_VERTEX));</code></pre></div>
<p><em>Fields:</em></p>
<ul>
<li>attribute - A member of the <a href="primitives.html#allegro_prim_attr">ALLEGRO_PRIM_ATTR</a> enumeration, specifying what this attribute signifies</li>
<li>storage - A member of the <a href="primitives.html#allegro_prim_storage">ALLEGRO_PRIM_STORAGE</a> enumeration, specifying how this attribute is stored</li>
<li>offset - Offset in bytes from the beginning of the custom vertex structure. The C function offsetof is very useful here.</li>
</ul>
<p>See also: <a href="primitives.html#al_create_vertex_decl">al_create_vertex_decl</a>, <a href="primitives.html#allegro_vertex_decl">ALLEGRO_VERTEX_DECL</a>, <a href="primitives.html#allegro_prim_attr">ALLEGRO_PRIM_ATTR</a>, <a href="primitives.html#allegro_prim_storage">ALLEGRO_PRIM_STORAGE</a></p>
<h2 id="allegro_prim_type">ALLEGRO_PRIM_TYPE</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="kw">typedef</span> <span class="kw">enum</span> ALLEGRO_PRIM_TYPE</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/allegro5/allegro_primitives.h#L36">Source Code</a></p>
<p>Enumerates the types of primitives this addon can draw.</p>
<ul>
<li><p>ALLEGRO_PRIM_POINT_LIST - A list of points, each vertex defines a point</p></li>
<li><p>ALLEGRO_PRIM_LINE_LIST - A list of lines, sequential pairs of vertices define disjointed lines</p></li>
<li><p>ALLEGRO_PRIM_LINE_STRIP - A strip of lines, sequential vertices define a strip of lines</p></li>
<li><p>ALLEGRO_PRIM_LINE_LOOP - Like a line strip, except at the end the first and the last vertices are also connected by a line</p></li>
<li><p>ALLEGRO_PRIM_TRIANGLE_LIST - A list of triangles, sequential triplets of vertices define disjointed triangles</p></li>
<li><p>ALLEGRO_PRIM_TRIANGLE_STRIP - A strip of triangles, sequential vertices define a strip of triangles</p></li>
<li><p>ALLEGRO_PRIM_TRIANGLE_FAN - A fan of triangles, all triangles share the first vertex</p></li>
</ul>
<h2 id="allegro_prim_attr">ALLEGRO_PRIM_ATTR</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="kw">typedef</span> <span class="kw">enum</span> ALLEGRO_PRIM_ATTR</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/allegro5/allegro_primitives.h#L55">Source Code</a></p>
<p>Enumerates the types of vertex attributes that a custom vertex may have.</p>
<ul>
<li><p>ALLEGRO_PRIM_POSITION - Position information, can be stored only in ALLEGRO_PRIM_SHORT_2, ALLEGRO_PRIM_FLOAT_2 and ALLEGRO_PRIM_FLOAT_3.</p></li>
<li><p>ALLEGRO_PRIM_COLOR_ATTR - Color information, stored in an <a href="graphics.html#allegro_color">ALLEGRO_COLOR</a>. The storage field of ALLEGRO_VERTEX_ELEMENT is ignored</p></li>
<li><p>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).</p></li>
<li><p>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.</p></li>
<li><p>ALLEGRO_PRIM_USER_ATTR - A user specified attribute. You can use any storage for this attribute. You may have at most ALLEGRO_PRIM_MAX_USER_ATTR (currently 10) of these that you can specify by adding an index to the value of ALLEGRO_PRIM_USER_ATTR, e.g. the first user attribute is <code>ALLEGRO_PRIM_USER_ATTR + 0</code>, the second is <code>ALLEGRO_PRIM_USER_ATTR + 1</code> and so on.</p>
<p>To access these custom attributes from GLSL shaders you need to declare attributes that follow this nomenclature: <code>user_attr_#</code> where # is the index of the attribute.</p>
<p>To access these custom attributes from HLSL you need to declare a parameter with the following semantics: <code>TEXCOORD{# + 2}</code> where # is the index of the attribute. E.g. the first attribute can be accessed via <code>TEXCOORD2</code>, second via <code>TEXCOORD3</code> and so on.</p>
<p>Since: 5.1.6</p></li>
</ul>
<p>See also: <a href="primitives.html#allegro_vertex_decl">ALLEGRO_VERTEX_DECL</a>, <a href="primitives.html#allegro_prim_storage">ALLEGRO_PRIM_STORAGE</a></p>
<h2 id="allegro_prim_storage">ALLEGRO_PRIM_STORAGE</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="kw">typedef</span> <span class="kw">enum</span> ALLEGRO_PRIM_STORAGE</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/allegro5/allegro_primitives.h#L67">Source Code</a></p>
<p>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.</p>
<ul>
<li><p>ALLEGRO_PRIM_FLOAT_1 - A single float</p>
Since: 5.1.6</li>
<li><p>ALLEGRO_PRIM_FLOAT_2 - A doublet of floats</p></li>
<li><p>ALLEGRO_PRIM_FLOAT_3 - A triplet of floats</p></li>
<li><p>ALLEGRO_PRIM_FLOAT_4 - A quad of floats</p>
Since: 5.1.6</li>
<li><p>ALLEGRO_PRIM_SHORT_2 - A doublet of shorts</p></li>
<li><p>ALLEGRO_PRIM_SHORT_4 - A quad of shorts</p>
Since: 5.1.6</li>
<li><p>ALLEGRO_PRIM_UBYTE_4 - A quad of unsigned bytes</p>
Since: 5.1.6</li>
<li><p>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</p>
Since: 5.1.6</li>
<li><p>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</p>
Since: 5.1.6</li>
<li><p>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</p>
Since: 5.1.6</li>
<li><p>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</p>
Since: 5.1.6</li>
<li><p>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</p>
Since: 5.1.6</li>
<li><p>ALLEGRO_PRIM_HALF_FLOAT_2 - A doublet of half-precision floats. Note that this storage format is not supported on all platforms. <a href="primitives.html#al_create_vertex_decl">al_create_vertex_decl</a> will return NULL if you use it on those platforms</p>
Since: 5.1.6</li>
<li><p>ALLEGRO_PRIM_HALF_FLOAT_4 - A quad of half-precision floats. Note that this storage format is not supported on all platforms. <a href="primitives.html#al_create_vertex_decl">al_create_vertex_decl</a> will return NULL if you use it on those platforms.</p>
<p>Since: 5.1.6</p></li>
</ul>
<p>See also: <a href="primitives.html#allegro_prim_attr">ALLEGRO_PRIM_ATTR</a></p>
<h2 id="allegro_vertex_cache_size">ALLEGRO_VERTEX_CACHE_SIZE</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="pp">#define ALLEGRO_VERTEX_CACHE_SIZE 256</span></code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/allegro5/allegro_primitives.h#L119">Source Code</a></p>
<p>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.</p>
<h2 id="allegro_prim_quality">ALLEGRO_PRIM_QUALITY</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="pp">#define ALLEGRO_PRIM_QUALITY 10</span></code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/allegro5/allegro_primitives.h#L123">Source Code</a></p>
<p>Controls the quality of the approximation of curved primitives (e.g. circles). Curved primitives are drawn by approximating them with a sequence of line segments. By default, this roughly corresponds to error of less than half of a pixel.</p>
<h2 id="allegro_line_join">ALLEGRO_LINE_JOIN</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="kw">typedef</span> <span class="kw">enum</span> ALLEGRO_LINE_JOIN</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/allegro5/allegro_primitives.h#L87">Source Code</a></p>
<ul>
<li>ALLEGRO_LINE_JOIN_NONE</li>
<li>ALLEGRO_LINE_JOIN_BEVEL</li>
<li>ALLEGRO_LINE_JOIN_ROUND</li>
<li>ALLEGRO_LINE_JOIN_MITER</li>
</ul>
<div class="figure">
<img src="images/LINE_JOIN.png" alt="ALLEGRO_LINE_JOIN styles" />
<p class="caption"><em>ALLEGRO_LINE_JOIN styles</em></p>
</div>
<p>See the picture for the difference.</p>
<p>The maximum miter length (relative to the line width) can be specified as parameter to the polygon functions.</p>
<p>Since: 5.1.0</p>
<p>See also: <a href="primitives.html#al_draw_polygon">al_draw_polygon</a></p>
<h2 id="allegro_line_cap">ALLEGRO_LINE_CAP</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="kw">typedef</span> <span class="kw">enum</span> ALLEGRO_LINE_CAP</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/allegro5/allegro_primitives.h#L98">Source Code</a></p>
<ul>
<li>ALLEGRO_LINE_CAP_NONE</li>
<li>ALLEGRO_LINE_CAP_SQUARE</li>
<li>ALLEGRO_LINE_CAP_ROUND</li>
<li>ALLEGRO_LINE_CAP_TRIANGLE</li>
<li>ALLEGRO_LINE_CAP_CLOSED</li>
</ul>
<div class="figure">
<img src="images/LINE_CAP.png" alt="ALLEGRO_LINE_CAP styles" />
<p class="caption"><em>ALLEGRO_LINE_CAP styles</em></p>
</div>
<p>See the picture for the difference.</p>
<p>ALLEGRO_LINE_CAP_CLOSED is different from the others - it causes the polygon to have no caps. (And the <a href="primitives.html#allegro_line_join">ALLEGRO_LINE_JOIN</a> style will determine how the vertex looks.)</p>
<p>Since: 5.1.0</p>
<p>See also: <a href="primitives.html#al_draw_polygon">al_draw_polygon</a></p>
<h2 id="allegro_vertex_buffer">ALLEGRO_VERTEX_BUFFER</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="kw">typedef</span> <span class="kw">struct</span> ALLEGRO_VERTEX_BUFFER ALLEGRO_VERTEX_BUFFER;</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/allegro5/allegro_primitives.h#L156">Source Code</a></p>
<p>A GPU vertex buffer that you can use to store vertices on the GPU instead of uploading them afresh during every drawing operation.</p>
<p>Since: 5.1.3</p>
<p>See also: <a href="primitives.html#al_create_vertex_buffer">al_create_vertex_buffer</a>, <a href="primitives.html#al_destroy_vertex_buffer">al_destroy_vertex_buffer</a></p>
<h2 id="allegro_index_buffer">ALLEGRO_INDEX_BUFFER</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="kw">typedef</span> <span class="kw">struct</span> ALLEGRO_INDEX_BUFFER ALLEGRO_INDEX_BUFFER;</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/allegro5/allegro_primitives.h#L160">Source Code</a></p>
<p>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.</p>
<p>Since: 5.1.8</p>
<p>See also: <a href="primitives.html#al_create_index_buffer">al_create_index_buffer</a>, <a href="primitives.html#al_destroy_index_buffer">al_destroy_index_buffer</a></p>
<h2 id="allegro_prim_buffer_flags">ALLEGRO_PRIM_BUFFER_FLAGS</h2>
<div class="sourceCode"><pre class="sourceCode c"><code class="sourceCode c"><span class="kw">typedef</span> <span class="kw">enum</span> ALLEGRO_PRIM_BUFFER_FLAGS</code></pre></div>
<p><a href="https://github.com/liballeg/allegro5/blob/master/addons/primitives/allegro5/allegro_primitives.h#L109">Source Code</a></p>
<p>Flags to specify how to create a vertex or an index buffer.</p>
<ul>
<li><p>ALLEGRO_PRIM_BUFFER_STREAM - Hints to the driver that the buffer is written to often, but used only a few times per frame</p></li>
<li><p>ALLEGRO_PRIM_BUFFER_STATIC - Hints to the driver that the buffer is written to once and is used often</p></li>
<li><p>ALLEGRO_PRIM_BUFFER_DYNAMIC - Hints to the driver that the buffer is written to often and is used often</p></li>
<li><p>ALLEGRO_PRIM_BUFFER_READWRITE - 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 <code>al_create_vertex_buffer</code> or <code>al_create_index_buffer</code> the call will fail.</p></li>
</ul>
<p>Since: 5.1.3</p>
<p>See also: <a href="primitives.html#al_create_vertex_buffer">al_create_vertex_buffer</a>, <a href="primitives.html#al_create_index_buffer">al_create_index_buffer</a></p>
<p class="timestamp">
Allegro version 5.2.2
 - Last updated: 2017-01-02 15:17:41 UTC
</p>
</div>
</body>
</html>
allegro5-doc 2:5.2.2-1 / usr / share / doc / allegro5-doc / refman / primitives.html
