258 lines
9.4 KiB
ReStructuredText
258 lines
9.4 KiB
ReStructuredText
.. _nx-graphics-library-nxgl-1:
|
|
|
|
==============================
|
|
NX Graphics Library (``NXGL``)
|
|
==============================
|
|
|
|
NXGL provides many APIs, some available for use internally by NX and
|
|
others for use by applications as well. Only those APIs intended for
|
|
application usage are documented here See ``include/nuttx/nx/nxglib.h``
|
|
for the full set of APIs; those APIs might be of interest if you are
|
|
rendering directly into framebuffer or LCD memory.
|
|
|
|
NXGL Types
|
|
----------
|
|
|
|
.. c:type:: nxgl_mxpixel_t
|
|
|
|
Holds one device pixel. NXGLIB will select the
|
|
smallest size for the ``nxgl_mxpixel_t`` that just contains the pixel:
|
|
``byte`` if 16, 24, and 32 resolution support is disabled, ``uint16_t``
|
|
if 24, and 32 resolution support is disabled, or ``uint32_t``.
|
|
|
|
.. c:type:: nxgl_coord_t
|
|
|
|
A given coordinate is limited to the screen height an
|
|
width. If either of those values exceed 32,767 pixels, then the
|
|
following will have to need to change:
|
|
|
|
.. c:struct:: nxgl_point_s
|
|
|
|
Describes a point on the display:
|
|
|
|
.. code-block:: c
|
|
|
|
struct nxgl_point_s
|
|
{
|
|
nxgl_coord_t x; /* X position, range: 0 to screen width - 1 */
|
|
nxgl_coord_t y; /* Y position, range: 0 to screen height - 1 */
|
|
};
|
|
|
|
.. c:struct:: nxgl_size_s
|
|
|
|
Describes the size of a rectangular region.
|
|
|
|
.. code-block:: c
|
|
|
|
struct nxgl_size_s
|
|
{
|
|
nxgl_coord_t w; /* Width in pixels */
|
|
nxgl_coord_t h; /* Height in rows */
|
|
};
|
|
|
|
.. c:struct:: nxgl_rect_s
|
|
|
|
Describes a positioned rectangle on the display.
|
|
|
|
.. code-block:: c
|
|
|
|
struct nxgl_rect_s
|
|
{
|
|
struct nxgl_point_s pt1; /* Upper, left-hand corner */
|
|
struct nxgl_point_s pt2; /* Lower, right-hand corner */
|
|
};
|
|
|
|
.. c:struct:: nxgl_run_s
|
|
|
|
Describes a run, i.e., a horizontal line. Note
|
|
that the start/end positions have fractional precision. This is
|
|
necessary for good joining of trapezoids when a more complex shape is
|
|
decomposed into trapezoids.
|
|
|
|
.. code-block:: c
|
|
|
|
struct nxgl_run_s
|
|
{
|
|
b16_t x1; /* Left X position, range: 0 to x2 */
|
|
b16_t x2; /* Right X position, range: x1 to screen width - 1 */
|
|
nxgl_coord_t y; /* Top Y position, range: 0 to screen height - 1 */
|
|
};
|
|
|
|
.. c:struct:: nxgl_trapezoid_s
|
|
|
|
Describes a horizontal trapezoid on the
|
|
display in terms the run at the top of the trapezoid and the run at the
|
|
bottom.
|
|
|
|
.. code-block:: c
|
|
|
|
struct nxgl_trapezoid_s
|
|
{
|
|
struct nxgl_run_s top; /* Top run */
|
|
struct nxgl_run_s bot; /* bottom run */
|
|
};
|
|
|
|
.. c:function:: void nxgl_rgb2yuv(uint8_t r, uint8_t g, uint8_t b, uint8_t *y, uint8_t *u, uint8_t *v)
|
|
|
|
Convert 8-bit RGB triplet to 8-bit YUV triplet.
|
|
|
|
.. c:function:: void nxgl_yuv2rgb(uint8_t y, uint8_t u, uint8_t v, uint8_t *r, uint8_t *g, uint8_t *b);
|
|
|
|
Convert 8-bit YUV triplet to 8-bit RGB triplet.
|
|
|
|
.. c:function:: void nxgl_rectcopy(FAR struct nxgl_rect_s *dest, FAR const struct nxgl_rect_s *src)
|
|
|
|
This is essentially ``memcpy()``\ for rectangles. We
|
|
don't do structure assignments because some compilers are not good at
|
|
that.
|
|
|
|
.. c:function:: void nxgl_rectoffset(FAR struct nxgl_rect_s *dest, \
|
|
FAR const struct nxgl_rect_s *src, \
|
|
nxgl_coord_t dx, nxgl_coord_t dy);
|
|
|
|
Offset the rectangle position by the specified dx, dy
|
|
values.
|
|
|
|
.. c:function:: void nxgl_vectoradd(FAR struct nxgl_point_s *dest, \
|
|
FAR const struct nxgl_point_s *v1, \
|
|
FAR const struct nxgl_point_s *v2);
|
|
|
|
Add two 2x1 vectors and save the result to a third.
|
|
|
|
.. c:function:: void nxgl_vectsubtract(FAR struct nxgl_point_s *dest, \
|
|
FAR const struct nxgl_point_s *v1, \
|
|
FAR const struct nxgl_point_s *v2);
|
|
|
|
Add subtract vector ``v2`` from vector ``v1`` and
|
|
return the result in vector dest.
|
|
|
|
.. c:function:: void nxgl_rectintersect(FAR struct nxgl_rect_s *dest, \
|
|
FAR const struct nxgl_rect_s *src1, \
|
|
FAR const struct nxgl_rect_s *src2);
|
|
|
|
Return the rectangle representing the intersection of
|
|
the two rectangles.
|
|
|
|
.. c:function:: void nxgl_rectunion(FAR struct nxgl_rect_s *dest, \
|
|
FAR const struct nxgl_rect_s *src1, \
|
|
FAR const struct nxgl_rect_s *src2);
|
|
|
|
Given two rectangles, ``src1`` and ``src2``, return the
|
|
larger rectangle that contains both, ``dest``.
|
|
|
|
.. c:function:: void nxgl_nonintersecting(FAR struct nxgl_rect_s result[4], \
|
|
FAR const struct nxgl_rect_s *rect1, \
|
|
FAR const struct nxgl_rect_s *rect2);
|
|
|
|
Return the regions of rectangle ``rect1`` that do not
|
|
intersect with ``rect2``. This will four rectangles, some of which may
|
|
be degenerate (and can be picked off with :c:func:`nxgl_nullrect`).
|
|
|
|
.. c:function:: bool nxgl_rectoverlap(FAR struct nxgl_rect_s *rect1, \
|
|
FAR struct nxgl_rect_s *rect2);
|
|
|
|
Return true if the two rectangles overlap.
|
|
|
|
.. c:function:: bool nxgl_rectinside(FAR const struct nxgl_rect_s *rect, \
|
|
FAR const struct nxgl_point_s *pt);
|
|
|
|
Return true if the point ``pt`` lies within ``rect``.
|
|
|
|
.. c:function:: void nxgl_rectsize(FAR struct nxgl_size_s *size, \
|
|
FAR const struct nxgl_rect_s *rect);
|
|
|
|
Return the size of the specified rectangle.
|
|
|
|
.. c:function:: bool nxgl_nullrect(FAR const struct nxgl_rect_s *rect);
|
|
|
|
Return true if the area of the retangle is <= 0.
|
|
|
|
.. c:function:: void nxgl_runoffset(FAR struct nxgl_run_s *dest, \
|
|
FAR const struct nxgl_run_s *src, \
|
|
nxgl_coord_t dx, nxgl_coord_t dy);
|
|
|
|
Offset the run position by the specified ``dx``, ``dy``
|
|
values.
|
|
|
|
.. c:function:: void nxgl_runcopy(FAR struct nxgl_run_s *dest, \
|
|
FAR const struct nxgl_run_s *src);
|
|
|
|
This is essentially ``memcpy()``\ for runs. We don't do
|
|
structure assignments because some compilers are not good at that.
|
|
|
|
.. c:function:: void nxgl_trapoffset(FAR struct nxgl_trapezoid_s *dest, \
|
|
FAR const struct nxgl_trapezoid_s *src, \
|
|
nxgl_coord_t dx, nxgl_coord_t dy);
|
|
|
|
Offset the trapezoid position by the specified ``dx``,
|
|
``dy`` values.
|
|
|
|
.. c:function:: void nxgl_trapcopy(FAR struct nxgl_trapezoid_s *dest, \
|
|
FAR const struct nxgl_trapezoid_s *src);
|
|
|
|
This is essentially ``memcpy()``\ for trapezoids. We
|
|
don't do structure assignments because some compilers are not good at
|
|
that.
|
|
|
|
.. c:function:: void nxgl_colorcopy(nxgl_mxpixel_t dest[CONFIG_NX_NPLANES], \
|
|
const nxgl_mxpixel_t src[CONFIG_NX_NPLANES]);
|
|
|
|
This is essentially ``memcpy()``\ for colors. This does
|
|
very little for us other than hide all of the conditional compilation
|
|
for planar colors in one place.
|
|
|
|
.. c:function:: int nxgl_splitline(FAR struct nxgl_vector_s *vector, FAR struct nxgl_trapezoid_s *traps, \
|
|
FAR struct nxgl_rect_s *rect, nxgl_coord_t linewidth);
|
|
|
|
In the general case, a line with width can be
|
|
represented as a parallelogram with a triangle at the top and bottom.
|
|
Triangles and parallelograms are both degenerate versions of a
|
|
trapezoid. This function breaks a wide line into triangles and
|
|
trapezoids. This function also detects other degenerate cases:
|
|
|
|
#. If ``y1 == y2`` then the line is horizontal and is better represented
|
|
as a rectangle.
|
|
#. If ``x1 == x2`` then the line is vertical and also better represented
|
|
as a rectangle.
|
|
#. If the width of the line is 1, then there are no triangles at the top
|
|
and bottom (this may also be the case if the width is narrow and the
|
|
line is near vertical).
|
|
#. If the line is oriented is certain angles, it may consist only of the
|
|
upper and lower triangles with no trapezoid in between. In this case,
|
|
3 trapezoids will be returned, but traps[1] will be degenerate.
|
|
|
|
:param vector: A pointer to the vector described the line to be drawn.
|
|
:param traps: A pointer to a array of trapezoids (size 3).
|
|
:param rect: A pointer to a rectangle.
|
|
|
|
:return:
|
|
- 0: Line successfully broken up into three trapezoids. Values in traps[0], traps[1], and traps[2] are valid.
|
|
- 1: Line successfully represented by one trapezoid. Value in traps[1] is valid.
|
|
- 2: Line successfully represented by one rectangle. Value in rect is valid
|
|
- <0: On errors, a negated errno value is returned.
|
|
|
|
.. c:function:: void nxgl_circlepts(FAR const struct nxgl_point_s *center, nxgl_coord_t radius, \
|
|
FAR struct nxgl_point_s *circle);
|
|
|
|
Given a description of a circle, return a set of 16
|
|
points on the circumference of the circle. These points may then be used
|
|
by :c:func:`nx_drawcircle` or related APIs to draw a
|
|
circle outline.
|
|
|
|
:param center: A pointer to the point that is the center of the circle.
|
|
:param radius: The radius of the circle in pixels.
|
|
:param circle: A pointer the first entry in an array of 16 points where the circle points will be returned.
|
|
|
|
.. c:function:: void nxgl_circletraps(FAR const struct nxgl_point_s *center, nxgl_coord_t radius, \
|
|
FAR struct nxgl_trapezoid_s *circle);
|
|
|
|
Given a description of a a circle, return 8 trapezoids
|
|
that can be used to fill the circle by
|
|
:c:func:`nx_fillcircle` and other interfaces.
|
|
|
|
:param center: A pointer to the point that is the center of the circle.
|
|
:param radius: The radius of the circle in pixels.
|
|
:param circle: A pointer the first entry in an array of 8 trapezoids where the
|
|
circle description will be returned.
|
|
|