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

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.

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:

struct nxgl_point_s

Describes a point on the display:

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 */
};
struct nxgl_size_s

Describes the size of a rectangular region.

struct nxgl_size_s
{
  nxgl_coord_t w;        /* Width in pixels */
  nxgl_coord_t h;        /* Height in rows */
};
struct nxgl_rect_s

Describes a positioned rectangle on the display.

struct nxgl_rect_s
{
  struct nxgl_point_s pt1; /* Upper, left-hand corner */
  struct nxgl_point_s pt2; /* Lower, right-hand corner */
};
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.

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 */
};
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.

struct nxgl_trapezoid_s
{
  struct nxgl_run_s top;  /* Top run */
  struct nxgl_run_s bot;  /* bottom run */
};
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.

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.

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.

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.

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.

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.

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.

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.

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 nxgl_nullrect()).

bool nxgl_rectoverlap(FAR struct nxgl_rect_s *rect1, FAR struct nxgl_rect_s *rect2);

Return true if the two rectangles overlap.

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.

void nxgl_rectsize(FAR struct nxgl_size_s *size, FAR const struct nxgl_rect_s *rect);

Return the size of the specified rectangle.

bool nxgl_nullrect(FAR const struct nxgl_rect_s *rect);

Return true if the area of the retangle is <= 0.

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.

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.

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.

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.

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.

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:

  1. If y1 == y2 then the line is horizontal and is better represented as a rectangle.

  2. If x1 == x2 then the line is vertical and also better represented as a rectangle.

  3. 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).

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

Parameters

  • vector – A pointer to the vector described the line to be drawn.

  • traps – A pointer to a array of trapezoids (size 3).

  • rect – A pointer to a rectangle.

Returns

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

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 nx_drawcircle() or related APIs to draw a circle outline.

Parameters

  • center – A pointer to the point that is the center of the circle.

  • radius – The radius of the circle in pixels.

  • circle – A pointer the first entry in an array of 16 points where the circle points will be returned.

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 nx_fillcircle() and other interfaces.

Parameters

  • center – A pointer to the point that is the center of the circle.

  • radius – The radius of the circle in pixels.

  • circle – A pointer the first entry in an array of 8 trapezoids where the circle description will be returned.