Drawing primitives
------------------

Drawing primitives implements algorithms to draw basic geometric shapes such
as lines, circles, etc.

You may want to see the link:coordinate_system.html[coordinate system] first.

See also RGB tripplet to pixel link:convert.html[conversions].

Rotation Flags
~~~~~~~~~~~~~~

Drawing orientation is affected by the link:pixmap.html[pixmap rotation
flags]. The parameters passed to the functions are transformed accordingly to
the flags before the drawing, which allows for fast and transparent rotated or
mirrored rendering.


Getting and Putting Pixels
~~~~~~~~~~~~~~~~~~~~~~~~~~

link:get_put_pixel.html[getpixel() and putpixel()] are implemented in the
library core.

Fill
~~~~

[source,c]
--------------------------------------------------------------------------------
void gp_fill(gp_pixmap *pixmap, gp_pixel pixel);
--------------------------------------------------------------------------------

Fills the whole pixmap bitmap with the specified pixel value.

NOTE: gp_fill() is implemented in the library Core rather than in GFX so that
      it's available to all library parts.

Lines
~~~~~

[source,c]
--------------------------------------------------------------------------------
void gp_hline_xxy(gp_pixmap *pixmap, gp_coord x0, gp_coord x1, gp_coord y, gp_pixel pixel);

void gp_hline(gp_pixmap *pixmap, gp_coord x0, gp_coord x1, gp_coord y, gp_pixel pixel);
--------------------------------------------------------------------------------

Draws a horizontal line from (x0, y) to (x1, y), inclusive. The coordinates
x0, x1 can be specified in any order.

'gp_hline()' is an alias for 'gp_hline_xxy()'.

[source,c]
--------------------------------------------------------------------------------
void gp_hline_xyw(gp_pixmap *pixmap, gp_coord x, gp_coord y, gp_size w, gp_pixel pixel);
--------------------------------------------------------------------------------

Draws a horizontal line from (x, y) to (x+w-1, y), inclusive.


[source,c]
--------------------------------------------------------------------------------
void gp_vline_xyy(gp_pixmap *pixmap, gp_coord x, gp_coord y0, gp_coord y1,
                  gp_pixel pixel);

void gp_vline(gp_pixmap *pixmap, gp_coord x, gp_coord y0, gp_coord y1,
              gp_pixel pixel);
--------------------------------------------------------------------------------

Draws a vertical line from (x, y0) to (x, y1), inclusive. The coordinates
y0, y1 can be specified in any order.

'gp_vline()' is an alias for 'gp_vline_xyy()'.

[source,c]
--------------------------------------------------------------------------------
void gp_vline_xyh(gp_pixmap *pixmap, gp_coord x, gp_coord y, gp_size h,
                  gp_pixel pixel);

--------------------------------------------------------------------------------

Draws a vertical line from (x, y) to (x, y+h-1), inclusive.

[source,c]
--------------------------------------------------------------------------------
void gp_line(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
             gp_coord x1, gp_coord y1, gp_pixel pixel);
--------------------------------------------------------------------------------

Draws a line from (x0, y0) to (x1, y1), inclusive. The starting and ending
point can be specified in any order (the implementation guarantees that
exactly the same set of pixels will be drawn in both cases).

Circles
~~~~~~~

[source,c]
--------------------------------------------------------------------------------
void gp_circle(gp_pixmap *pixmap, gp_coord xcenter, gp_coord ycenter,
               gp_size r, gp_pixel pixel);
--------------------------------------------------------------------------------

Draws a circle centered at (xcenter, ycenter) with radius 'r' (in pixels).

The circle is drawn so that all affected pixels will fit into a square
specified by points (xcenter-r, ycenter-r, xcenter+r, ycenter+r), inclusive.

[source,c]
--------------------------------------------------------------------------------
void gp_fill_circle(gp_pixmap *pixmap, gp_coord xcenter, gp_coord ycenter,
                    gp_size r, gp_pixel pixel);
--------------------------------------------------------------------------------

Draws a filled circle.

The set of pixels affected by 'gp_fill_circle()' is exactly the same as if
drawing the circle boundary using 'gp_circle()' and then filling all pixels
within the boundary with the same color.

Rings
~~~~~
[source,c]
--------------------------------------------------------------------------------
void gp_ring(gp_pixmap *pixmap, gp_coord xcenter, gp_coord ycenter,
             gp_size r1, gp_size r2, gp_pixel pixel);
--------------------------------------------------------------------------------

Draws a ring (two circles centered at (xcenter, ycenter) with radii 'r1' and 'r2').

The result is exactly the same as calling 'gp_circle()' with the same center
and appropriate radii.

[source,c]
--------------------------------------------------------------------------------
void gp_fill_ring(gp_pixmap *pixmap, gp_coord xcenter, gp_coord ycenter,
                  gp_size r1, gp_size r2, gp_pixel pixel);
--------------------------------------------------------------------------------

Draws a filled ring.

The smaller of r1 and r2 is used for inner radius and bigger one for outer
radius.

Ellipses
~~~~~~~~

[source,c]
--------------------------------------------------------------------------------
void gp_ellipse(gp_pixmap *pixmap, gp_coord xcenter, gp_coord ycenter,
                gp_size a, gp_size b, gp_pixel pixel);
--------------------------------------------------------------------------------

Draws an axis-aligned ellipse.

The ellipse is drawn so that all affected pixels will fit into a rectangle
specified by points (xcenter-a, ycenter-b, xcenter+a, ycenter+b), inclusive.

[source,c]
--------------------------------------------------------------------------------
void gp_fill_ellipse(gp_pixmap *pixmap, gp_coord xcenter, gp_coord ycenter,
                     gp_size a, gp_size b, gp_pixel pixel);
--------------------------------------------------------------------------------

Draws a filled axis-aligned ellipse.

Triangles
~~~~~~~~~

[source,c]
--------------------------------------------------------------------------------
void gp_triangle(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
                 gp_coord x1, gp_coord y1, gp_coord x2, gp_coord y2,
                 gp_pixel pixel);
--------------------------------------------------------------------------------

Draws a triangle.

[source,c]
--------------------------------------------------------------------------------
void gp_fill_triangle(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
                      gp_coord x1, gp_coord y1, gp_coord x2, gp_coord y2,
                      gp_pixel pixel);
--------------------------------------------------------------------------------

Draws a filled triangle.

Rects
~~~~~

[source,c]
--------------------------------------------------------------------------------
void gp_rect_xyxy(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
                  gp_coord x1, gp_coord y1, gp_pixel pixel);

void gp_rect_xywh(gp_pixmap *pixmap, gp_coord x, gp_coord y,
                  gp_size w, gp_size h, gp_pixel pixel);

void gp_rect(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
             gp_coord x1, gp_coord y1, gp_pixel pixel);
--------------------------------------------------------------------------------

Draws a rectangle.

The 'gp_rect_xyxy()' expects two corner points (x0, y0), and (x1, y1).
The 'gp_rect_xywh()' expects a corner point (x0, y0), width and height.
The 'gp_rect()' function is an alias for 'gp_rect_xyxy()'.

[source,c]
--------------------------------------------------------------------------------
void gp_fill_rect_xyxy(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
                       gp_coord x1, gp_coord y1, gp_pixel pixel);

void gp_fill_rect_xywh(gp_pixmap *pixmap, gp_coord x, gp_coord y,
                       gp_size w, gp_size h, gp_pixel pixel);

void gp_fill_rect(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
                  gp_coord x1, gp_coord y1, gp_pixel pixel);
--------------------------------------------------------------------------------

Draws a filled rectangle.

The 'gp_rect_xyxy' fills an area between corner points (x0, y0) and (x1, y1),
inclusive.
The 'gp_rect_xywh' fills an area starting from (x0, y0) with specified width
and height, i.e. from (x0, y0) to (x0 + w, x1 + y), NOT inclusive.
The 'gp_fill_rect()' functions is an alias for 'gp_fill_rect_xyxy()'.

Tetragons
~~~~~~~~~

[source,c]
--------------------------------------------------------------------------------
void gp_tetragon(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
                 gp_coord x1, gp_coord y1, gp_coord x2, gp_coord y2,
                 gp_coord x3, gp_coord y3, gp_pixel pixel);
--------------------------------------------------------------------------------

Draws a tetragon.

[source,c]
--------------------------------------------------------------------------------
void gp_fill_tetragon(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
                     gp_coord x1, gp_coord y1, gp_coord x2, gp_coord y2,
                     gp_coord x3, gp_coord y3, gp_pixel pixel);
--------------------------------------------------------------------------------

Draws a filled tetragon.

Polygons
~~~~~~~~

[source,c]
--------------------------------------------------------------------------------
void gp_polygon(gp_pixmap *pixmap, gp_coord x_off, gp_coord y_off,
                unsigned int vertex_count, const gp_coord *xy, gp_pixel pixel);
--------------------------------------------------------------------------------

Draws a polygon at a defined offset.

[source,c]
--------------------------------------------------------------------------------
void gp_fill_polygon(gp_pixmap *pixmap, gp_coord x_off, gp_coord y_off,
                     unsigned int vertex_count, const gp_coord *xy, gp_pixel pixel);
--------------------------------------------------------------------------------

Draws a filled polygon.

The coordinages are passed in [x0, y0, x1, y1, ...] order, the vertex count
describes a number of nodes, i.e. half of the size of the array.
