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