nuttx/Documentation/components/nxgraphics/nxgl.rst

.. _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.