NX Graphics Subsystem

Last Updated: December 1, 2011



Table of Contents

1.0 Introduction

2.0 NX User APIs

2.4 NX Tool Kit (NXTK)

2.5 NX Fonts Support (NXFONTS)

2.6 Sample Code

Appendix A graphics/ Directory Structure
Appendix B NX Configuration Options

Appendix C Installing New Fonts

Appendix D NX Test Coverage

1.0 Introduction

1.1 Overview

This document describes the tiny graphics support included in NuttX. It includes an overview description of that graphics support, detailed descriptions of the NuttX graphics APIs, and discussion of code organization, and OS configuration options.

Figure 1. This scren shot shows the final frame for the NuttX example at apps/examples/nx running on the simulated, Linux x86 platform with simulated framebuffer output to an X window. This picture shows to framed windows with (blank) toolbars. Each window has displayed text as received from the NX keyboard interface The second window has just been raised to the top of the display.

1.2 Objectives

The objective of this development was to provide a tiny windowing system in the spirit of X, but greatly scaled down and appropriate for most resource-limited embedded environments. The current NX implementation supports the general following, high-level features:

1.3 Organization

NX is organized into 6 (and perhaps someday 7 or 8) logical modules. These logical modules also correspond to the directory organization. That NuttX directory organization is discussed in Appendix B of this document. The logic modules are discussed in the following sub-paragraphs.

1.3.1 NX Graphics Library (NXGL)

NXGLIB is a standalone library that contains low-level graphics utilities and direct framebuffer or LCD rendering logic. NX is built on top NXGLIB.

1.3.2 NX (NXSU and NXMU)

NX is the tiny NuttX windowing system for raw windows (i.e., simple regions of graphics memory). NX includes both a small-footprint, single user implementaton (NXSU) and a somewhat larger multi-user implentation (NXMU as described below). Both conform to the same APIs as defined in include/nuttx/nx/nx.h and, hence, are interchangable1. NX can be used without NXWIDGETS and without NXTOOLKIT for raw window displays.

1NXMU and NXSU are interchangeable other than (1) certain start-up and intialization APIs (as described below), and (2) timing. With NXSU, NX APIs execute immediately; with NXMU, NX APIs defer and serialize the operations and, hence, introduce different timing and potential race conditions that you would not experience with NXSU.

NXNULL? At one time, I also envisoned a NULL front-end that did not support windowing at all but, rather, simply provided the entire framebuffer or LCD memory as one dumb window. This has the advantage that the same NX APIs can be used on the one dumb window as for the other NX windows. This would be in the NuttX spirit of scalability.

However, the same end result can be obtained by using the nx_requestbkgd() API. It still may be possible to reduce the footprint in this usage case by developing and even thinner NXNULL front-end. That is a possible future development.

1.3.3 NX Tool Kit (NXTK)

NXTK is a s set of C graphics tools that provide higher-level window drawing operations. This is the module where the framed windows and toolbar logic is implemented. NXTK is built on top of NX and does not depend on NXWIDGETS.

1.3.4 NX Fonts Support (NXFONTS)

A set of C graphics tools for present (bitmap) font images. The font implementation is at a very low level or graphics operation, comparable to the logic in NXGLIB. NXFONTS does not depend on any NX module other than some utilities and types from NXGLIB.

1.3.5 NX Widgets (NXWIDGETS)

I had originally planned a high level, C++, object-oriented library for object-oriented access to graphics widgets. However, C++ compilers are not available for some of the targets supported by NuttX. So I have decided to implement the entire solution in C. That decision makes the solution somewhat more difficult to work with, but supports all platforms.

At this point, the amount of C in the implementation would make conversion to C++ a more difficult job. I leave the C++ widget interface to any contributor who may have an interest in such things.

2.0 NX User APIs

2.1 NX Header Files

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

2.2.1 NXGL Types

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.

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_size_s. Describes the size of a rectangular region.

struct nxgl_rect_s. Describes a positioned rectangle on the display.

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

2.2.1 nxgl_rgb2yuv()

Function Prototype:

Description: Convert 8-bit RGB triplet to 8-bit YUV triplet.

2.2.2 nxgl_yuv2rgb()

Function Prototype:

Description: Convert 8-bit RGB triplet to 8-bit YUV triplet.

2.2.3 nxgl_rectcopy()

Function Prototype:

Description: This is essentially memcpy()for rectangles. We don't do structure assignments because some compilers are not good at that.

2.2.4 nxgl_rectoffset()

Function Prototype:

Description: Offset the rectangle position by the specified dx, dy values.

2.2.5 nxgl_vectoradd()

Function Prototype:

Description: Add two 2x1 vectors and save the result to a third.

2.2.6 nxgl_vectorsubtract()

Function Prototype:

Description: Add subtract vector v2 from vector v1 and return the result in vector dest.

2.2.7 nxgl_rectintersect()

Function Prototype:

Description: Return the rectangle representing the intersection of the two rectangles.

2.2.8 nxgl_rectunion()

Function Prototype:

Description: Given two rectanges, src1 and src2, return the larger rectangle that contains both, dest.

2.2.9 nxgl_nonintersecting()

Function Prototype:

Description: 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()).

2.2.10 nxgl_rectoverlap()

Function Prototype:

Description: Return true if the two rectangles overlap.

2.2.11 nxgl_rectinside()

Function Prototype:

Description: Return true if the point pt lies within rect.

2.2.12 nxgl_rectsize()

Function Prototype:

Description: Return the size of the specified rectangle.

2.2.13 nxgl_nullrect()

Function Prototype:

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

2.2.14 nxgl_runoffset()

Function Prototype:

Description: Offset the run position by the specified dx, dy values.

2.2.15 nxgl_runcopy()

Function Prototype:

Description: This is essentially memcpy()for runs. We don't do structure assignments because some compilers are not good at that.

2.2.16 nxgl_trapoffset()

Function Prototype:

Description: Offset the trapezoid position by the specified dx, dy values.

2.2.17 nxgl_trapcopy()

Function Prototype:

Description: This is essentially memcpy()for trapezoids. We don't do structure assignments because some compilers are not good at that.

2.2.18 nxgl_colorcopy

Function Prototype:

Description: 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.

2.2.19 nxgl_splitline

Function Prototype:

Description: 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 trapeziod. 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 bottome (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.

Input parameters:

Returned value:

2.2.20 nxgl_circlepts

Description: 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.

Input parameters:

Returned value: None

2.2.21 nxgl_circletraps

Description: Given a description of a a circle, return 8 trapezoids that can be used to fill the circle by nx_fillcircle() and other interfaces.

Input parameters:

Returned value: None

2.3 NX

2.3.1 Pre-Processor Definitions

The default server message queue name used by the nx_run() macro:

Mouse button bits:

2.3.2 NX Types

The interface to the NX server is managed using a opaque handle:

The interface to a specific window is managed using an opaque handle:

These define callbacks that must be provided to nx_openwindow(). In the multi-user model, these callbacks will be invoked as part of the processing performed by nx_eventhandler().

2.3.3 NX Server Callbacks

2.3.3.1 redraw()

Callback Function Prototype:

Description: NX requests that the client re-draw the portion of the window within with rectangle.

Input Parameters:

Returned Value: None

2.3.3.2 position()

Callback Function Prototype:

Description: The size or position of the window has changed (or the window was just created with zero size.

Input Parameters:

Returned Value: None

2.3.3.3 mousein()

Callback Function Prototype:

Description: New mouse data is available for the window

Input Parameters:

Returned Value: None

2.3.3.4 kbdin()

Callback Function Prototype:

Description: New keyboard/keypad data is available for the window.

Input Parameters:

Returned Value: None

2.3.4 nx_runinstance() (and nx_run() macro)

Function Prototype:

Description: This is the server entry point. It does not return; the calling thread is dedicated to supporting NX server.

NOTE that multiple instances of the NX server may run at the same time, with different callback and message queue names. nx_run() is simply a macro that can be used when only one server instance is required. In that case, a default server name is used.

Multiple user mode only!

Input Parameters:

Returned Value: This function usually does not return. If it does return, it will return ERROR and errno will be set appropriately.

2.3.5 nx_connectinstance() (and nx_connect() macro)

Function Prototype:

Description: Open a connection from a client to the NX server. One one client connection is normally needed per thread as each connection can host multiple windows.

NOTES:

Multiple user mode only!

Input Parameters:

Returned Value:

2.3.6 nx_open()

Function Prototype:

Description: Create, initialize and return an NX handle for use in subsequent NX API calls. nx_open() is the single user equivalent of nx_connect() plus nx_run().

Single user mode only!

Input Parameters:

Returned Value:

2.3.7 nx_disconnect()

Function Prototype:

Description: Disconnect a client from the NX server and/or free resources reserved by nx_connect()/nx_connectinstance(). nx_disconnect() is muliti-user equivalent of nx_close().

Multiple user mode only!

Input Parameters:

Returned Value: None.

2.3.8 nx_close()

Function Prototype:

Description: Close the single user NX interface. nx_close is single-user equivalent of nx_disconnect().

Single user mode only!

Input Parameters:

Returned Value: None

2.3.9 nx_eventhandler()

Function Prototype:

Description: The client code must call this function periodically to process incoming messages from the server. If CONFIG_NX_BLOCKING is defined, then this function not return until a server message is received.

When CONFIG_NX_BLOCKING is not defined, the client must exercise caution in the looping to assure that it does not eat up all of the CPU bandwidth calling nx_eventhandler repeatedly. nx_eventnotify() may be called to get a signal event whenever a new incoming server event is avaiable.

Input Parameters:

Returned Value:

2.3.10 nx_eventnotify()

Function Prototype:

Description: Rather than calling nx_eventhandler() periodically, the client may register to receive a signal when a server event is available. The client can then call nv_eventhandler() only when incoming events are available.

The underlying implementation used mq_notifiy() and, as a result, the client must observe the rules for using mq_notifiy():

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.3.11 nx_openwindow()

Function Prototype:

Description: Create a new window.

Input Parameters:

Returned Value:

2.3.12 nx_closewindow()

Function Prototype:

Description: Destroy a window created by nx_openwindow() window.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.3.13 nx_requestbkgd()

Function Prototype:

Description: NX normally controls a separate window called the background window. It repaints the window as necessary using only a solid color fill. The background window always represents the entire screen and is always below other windows. It is useful for an application to control the background window in the following conditions:

This API only requests the handle of the background window. That handle will be returned asynchronously in a subsequent position and redraw callbacks.

Cautions:

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.3.14 nx_releasebkgd()

Function Prototype:

Description: Release the background window previously acquired using nx_requestbkgd() and return control of the background to NX.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.3.15 nx_getposition()

Function Prototype:

Description: Request the position and size information for the selected window. The values will be return asynchronously through the client callback function pointer.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.3.16 nx_setposition()

Function Prototype:

Description: Set the position and size for the selected window.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.3.17 nx_setsize()

Function Prototype:

Description: Set the size of the selected window.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.3.18 nx_raise()

Function Prototype:

Description: Bring the specified window to the top of the display.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.3.19 nx_lower()

Function Prototype:

Description: Lower the specified window to the bottom of the display.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.3.20 nx_fill()

Function Prototype:

Description: Fill the specified rectangle in the window with the specified color.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.3.21 nx_getrectangle()

Function Prototype:

Description: Get the raw contents of graphic memory within a rectangular region. NOTE: Since raw graphic memory is returned, the returned memory content may be the memory of windows above this one and may not necessarily belong to this window unless you assure that this is the top window.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.3.22 nx_filltrapezoid()

Function Prototype:

Description: Fill the specified trapezoidal region in the window with the specified color.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.3.23 nx_drawline()

Function Prototype:

Description: Fill the specified trapezoidal region in the window with the specified color. Fill the specified line in the window with the specified color. This is simply a wrapper that uses nxgl_splitline() to break the line into trapezoids and then calls nx_filltrapezoid() to render the line.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.3.24 nx_drawcircle()

Function Prototype:

Description: Draw a circular outline using the specified line thickness and color.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.3.25 nx_fillcircle()

Function Prototype:

Description: Fill a circular region using the specified color.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.3.26 nx_setbgcolor()

Function Prototype:

Description: Set the color of the background.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.3.27 nx_move()

Function Prototype:

Description: Move a rectangular region within the window.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.3.28 nx_bitmap()

Function Prototype:

Description: Copy a rectangular region of a larger image into the rectangle in the specified window.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.3.29 nx_kbdin()

Function Prototype:

Description: Used by a thread or interrupt handler that manages some kind of keypad hardware to report text information to the NX server. That text data will be routed by the NX server to the appropriate window client.

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.3.30 nx_mousein()

Function Prototype:

Description: Used by a thread or interrupt handler that manages some kind of pointing hardware to report new positional data to the NX server. That positional data will be routed by the NX server to the appropriate window client.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4 NX Tool Kit (NXTK)

NXTK implements where the framed window. NX framed windows consist of three components within one NX window:

  1. The window border,
  2. The main client window area, and
  3. A toolbar area

Each sub-window represents a region within one window. Figure 1 shows some simple NX framed windows. NXTK allows these sub-windows to be managed more-or-less independently:

2.4.1 NXTK Types()

This is the handle that can be used to access the window data region.

2.4.2 nxtk_openwindow()

Function Prototype:

Description: Create a new, framed window.

Input Parameters:

handle
The handle returned by nx_connect() or nx_open().
cb
Callbacks used to process window events
arg
User provided argument (see nx_openwindow())

Returned Value:

2.4.3 nxtk_closewindow()

Function Prototype:

Description: Close the window opened by nxtk_openwindow().

Input Parameters:

hfwnd
A handle previously returned by nxtk_openwindow().

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.4 nxtk_getposition()

Function Prototype:

Description: Request the position and size information for the selected framed window. The size/position for the client window and toolbar will be return asynchronously through the client callback function pointer.

Input Parameters:

hfwnd
A handle previously returned by nxtk_openwindow().

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.5 nxtk_setposition()

Function Prototype:

Description: Set the position for the selected client window. This position does not include the offsets for the borders nor for any toolbar. Those offsets will be added in to set the full window position.

Input Parameters:

hfwnd
A handle previously returned by nxtk_openwindow().
pos
The new position of the client sub-window

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.6 nxtk_setsize()

Function Prototype:

Description: Set the size for the selected client window. This size does not include the sizes of the borders nor for any toolbar. Those sizes will be added in to set the full window size.

Input Parameters:

hfwnd
A handle previously returned by nxtk_openwindow().
size
The new size of the client sub-window.

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.7 nxtk_raise()

Function Prototype:

Description: Bring the window containing the specified client sub-window to the top of the display.

Input Parameters:

hfwnd
A handle previously returned by nxtk_openwindow() specifying the window to be raised.

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.8 nxtk_lower()

Function Prototype:

Description: Lower the window containing the specified client sub-window to the bottom of the display.

Input Parameters:

hfwnd
A handle previously returned by nxtk_openwindow() specifying the window to be lowered.

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.9 nxtk_fillwindow()

Function Prototype:

Description: Fill the specified rectangle in the client window with the specified color.

Input Parameters:

hfwnd
A handle previously returned by nxtk_openwindow().
rect
The location within the client window to be filled
color
The color to use in the fill

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.10 nxtk_getwindow()

Function Prototype:

Description: Get the raw contents of graphic memory within a rectangular region. NOTE: Since raw graphic memory is returned, the returned memory content may be the memory of windows above this one and may not necessarily belong to this window unless you assure that this is the top window.

Input Parameters:

hfwnd
A handle previously returned by nxtk_openwindow().
rect
The location within the client window to be retrieved.
plane
Specifies the color plane to get from.
dest
The location to copy the memory region
deststride
The width, in bytes, the the dest memory

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.11 nxtk_filltrapwindow()

Function Prototype:

Description: Fill the specified trapezoid in the client window with the specified color

Input Parameters:

hfwnd
A handle previously returned by nxtk_openwindow().
trap
The trapezoidal region to be filled.
color
The color to use in the fill.

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.12 nxtk_drawlinewindow()

Function Prototype:

Description: Fill the specified trapezoidal region in the window with the specified color. Fill the specified line in the window with the specified color. This is simply a wrapper that uses nxgl_splitline() to break the line into trapezoids and then calls nxtk_filltrapwindow() to render the line.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.13 nxtk_drawcirclewindow()

Function Prototype:

Description: Draw a circular outline using the specified line thickness and color.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.14 nxtk_fillcirclewindow()

Function Prototype:

Description: Fill a circular region using the specified color.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.15 nxtk_movewindow()

Function Prototype:

Description: Move a rectangular region within the client sub-window of a framed window.

Input Parameters:

hfwnd
A handle previously returned by nxtk_openwindow() specifying the client sub-window within which the move is to be done.
rect
Describes the rectangular region relative to the client sub-window to move.
offset
The offset to move the region

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.16 nxtk_bitmapwindow()

Function Prototype:

Description: Copy a rectangular region of a larger image into the rectangle in the specified client sub-window.

Input Parameters:

hfwnd
A handle previously returned by nxtk_openwindow() specifying the client sub-window that will receive the bitmap.
dest
Describes the rectangular region on in the client sub-window will receive the bit map.
src
The start of the source image(s). This is an array source images of size CONFIG_NX_NPLANES (probably 1).
origin
The origin of the upper, left-most corner of the full bitmap. Both dest and origin are in sub-window coordinates, however, the origin may lie outside of the sub-window display.
stride
The width of the full source image in pixels.

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.17 nxtk_opentoolbar()

Function Prototype:

Description: Create a tool bar at the top of the specified framed window.

Input Parameters:

hfwnd
A handle previously returned by nxtk_openwindow().
height
The requested height of the toolbar in pixels.
cb
Callbacks used to process toolbar events.
arg
User provided value that will be returned with toolbar callbacks.

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.18 nxtk_closetoolbar()

Function Prototype:

Description: Remove the tool bar at the top of the specified framed window.

Input Parameters:

hfwnd
A handle previously returned by nxtk_openwindow().

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.19 nxtk_filltoolbar()

Function Prototype:

Description: Fill the specified rectangle in the toolbar sub-window with the specified color.

Input Parameters:

hfwnd
A handle previously returned by nxtk_openwindow().
rect
The location within the toolbar window to be filled.
color
The color to use in the fill.

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.19 nxtk_gettoolbar()

Function Prototype:

Description: Get the raw contents of graphic memory within a rectangular region. NOTE: Since raw graphic memory is returned, the returned memory content may be the memory of windows above this one and may not necessarily belong to this window unless you assure that this is the top window.

Input Parameters:

hfwnd
A handle previously returned by nxtk_openwindow().
rect
The location within the toolbar window to be retrieved.
plane
TSpecifies the color plane to get from.
dest
TThe location to copy the memory region.
deststride
The width, in bytes, the the dest memory.

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.21 nxtk_filltraptoolbar()

Function Prototype:

Description: Fill the specified trapezoid in the toolbar sub-window with the specified color.

Input Parameters:

hfwnd
A handle previously returned by nxtk_openwindow().
trap
The trapezoidal region to be filled
color
The color to use in the fill

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.22 nxtk_drawlinetoolbar()

Function Prototype:

Description: Fill the specified line in the toolbar sub-window with the specified color. This is simply a wrapper that uses nxgl_splitline() to break the line into trapezoids and then calls nxtk_filltraptoolbar() to render the line.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.23 nxtk_drawcircletoolbar()

Function Prototype:

Description: Draw a circular outline using the specified line thickness and color.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.24 nxtk_fillcircletoolbar()

Function Prototype:

Description: Fill a circular region using the specified color.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.25 nxtk_movetoolbar()

Function Prototype:

Description: Move a rectangular region within the toolbar sub-window of a framed window.

Input Parameters:

hfwnd
A handle identifying sub-window containing the toolbar within which the move is to be done. This handle must have previously been returned by nxtk_openwindow().
rect
Describes the rectangular region relative to the toolbar sub-window to move.
offset
The offset to move the region

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.4.26 nxtk_bitmaptoolbar()

Function Prototype:

Description: Copy a rectangular region of a larger image into the rectangle in the specified toolbar sub-window.

Input Parameters:

hfwnd
A handle previously returned by nxtk_openwindow().
dest
Describes the rectangular region on in the toolbar sub-window will receive the bit map.
src
The start of the source image.
origin
The origin of the upper, left-most corner of the full bitmap. Both dest and origin are in sub-window coordinates, however, the origin may lie outside of the sub-window display.
stride
The width of the full source image in bytes.

Returned Value: OK on success; ERROR on failure with errno set appropriately

2.5 NX Fonts Support (NXFONTS)

2.5.1 NXFONTS Types()

This structures provides the metrics for one glyph:

This structure binds the glyph metrics to the glyph bitmap:

This structure describes one contiguous grouping of glyphs that can be described by an array starting with encoding first and extending through (first + nchars - 1).

This structure describes the overall fontset:

2.5.2 nxf_getfonthandle()

Function Prototype:

Description: Given a numeric font ID, return a handle that may be subsequently be used to access the font data sets.

Input Parameters:

Returned Value: A handle that may be subsequently be used to access the font data sets.

2.5.3 nxf_getfontset()

Function Prototype:

Description: Return information about the current font set.

Input Parameters:

Returned Value: An instance of struct nx_font_s describing the font set.

2.5.4 nxf_getbitmap()

Function Prototype:

Description: Return font bitmap information for the selected character encoding.

Input Parameters:

Returned Value: An instance of struct nx_fontbitmap_s describing the glyph.

2.5.5 nxf_convert_*bpp()

Function Prototype:

Description: Convert the 1BPP font to a new pixel depth.

Input Parameters:

Returned Value: OK on success; ERROR on failure with errno set appropriately.

2.6 Sample Code

apps/examples/nx*. No sample code is provided in this document. However, examples can be found in the NuttX source tree at the follow locations: That example code is intended to test NX. Since it is test code, it is designed to exercise functionality and does not necessarily represent best NX coding practices.

In its current form, the NX graphics system provides a low level of graphics and window support. Most of the complexity of manage redrawing and handling mouse and keyboard events must be implemented by the NX client code.

Building apps/examples/nx. Testing was performed using the Linux/Cygwin-based NuttX simulator. Instructions are provided for building that simulation are provided in Appendix C of this document.

Appendix A graphics/ Directory Structure

Appendix B NX Configuration Options

B.1 General Configuration Settings

B.2 NXGL Configuration Settings

B.3 NX Configuration Settings

B.4 NX Multi-User (Only) Configuration Settings

B.5 NXTK Configuration Settings

B.6 NXFONTS Configuration Settings

Appendix C Installing New Fonts

The BDF Font Converter. There is a tool called bdf-converter in the directory tools/.. The bdf-converter program be used to convert fonts in Bitmap Distribution Format (BDF) into fonts that can be used in the NX graphics system. The BDF format most well known as a font format traditionally used for X-11 bitmap fonts.

A Note about Font Copyrights: My understanding is that the underlying bitmap font data for traditional fonts cannot be copyrighted (the same is not true for scalable fonts). This is because a copyright covers only the form of delivery of the font and not the underlying font content and, at least for the traditional typefaces, the underlying font designs are ancient. There could be issues, however, if you convert from modern, trademarked images. However, remember that I am a programmer not an attorney and that my knowledge of font copyright issues is limited to what I glean by Googling.

Font Installation Steps, Below are general instructions for creating and installing a new font in the NX graphic system. The first two steps only appy if you are using the BDF font converter program.

  1. Locate a font in BDF format. There are many good BDF bitmap fonts bundled with X-11. See this link, as an example,

  2. Use the bdf-converter program to convert the BDF font to the NuttX font format. This will result in a C header file containing defintions. That header file should be installed at, for example, graphics/nxfonts/nxfonts_myfont.h.

The remaining steps apply however you managed to create the NuttX C font header file. After you have your C font header file, the next thing to do is to create a new NuttX configuration variable to select the font. For example, suppose you define the following variable: CONFIG_NXFONT_MYFONT. Then you would need to:

  1. Define CONFIG_NXFONT_MYFONT=y in your NuttX configuration file.

A font ID number has to be assigned for each new font. The font IDs are defined in the file include/nuttx/nx/nxfonts.h. Those definitions have to be extended to support your new font. Look at how the font ID enabled by CONFIG_NXFONT_SANS23X27 is defined and add an ID for yournew font in a similar fashion:

  1. include/nuttx/nx/nxfonts.h. Add you new font as a possible system default font:

    Then define the actual font ID. Make sure that the font ID value is unique:

New Add the font to the NX build system. There are several files that you have to modify to to this. Look how the build system uses the font CONFIG_NXFONT_SANS23X27 for examaples:

  1. nuttx/graphics/Makefile. This file needs logic to auto-generate a C source file from the header file that you generated with the the bdf-converter program. Notice NXFONTS_FONTID=2; this must be set to the same font ID value that you defined in the include/nuttx/nx/nxfonts.h file.

  2. nuttx/graphics/nxfonts/Make.defs. Set the make variable NXFSET_CSRCS. NXFSET_CSRCS determines the name of the font C file to build when NXFONTS_FONTID=2:

  3. nuttx/graphics/nxfonts/Makefile.sources. This is the Makefile used in step 5 that will actually generate the font C file. So, given your NXFONTS_FONTID=2, it needs to determine a prefix to use for auto-generated variable and function names and (again) the name of the autogenerated file to create (this must be the same name that was used in nuttx/graphics/nxfonts/Make.defs):

  4. graphics/nxfonts/nxfonts_bitmaps.c. This is the file that contains the generic font structures. It is used as a "template&qout; file by nuttx/graphics/nxfonts/Makefile.sources to create your customized font data set at build time.

    Where nxfonts_myfont.h is the NuttX font file that we generated in step 2 using the bdf-converter tool.

  5. graphics/nxfonts/nxfonts_getfont.c. Finally, we need to extend the logic that does the run-time font lookups so that can find our new font. The lookup function is NXHANDLE nxf_getfonthandle(enum nx_fontid_e fontid). Note that the lookup is based on the font ID that was defined in step 4. The new font information needs to be added to data structures used by that function:

Appendix D NX Test Coverage

apps/examples/nx. The primary test tool for debugging NX resides at apps/examples/nx.

Building apps/examples/nx. NX testing was performed using apps/examples/nx with the Linux/Cygwin-based NuttX simulator. Configuration files for building this test can be found in configs/sim/nx and configs/sim/nx11. There are two alternative configurations for building the simulation:

  1. The configuration using the configuration file at configs/sim/nx/defconfig. This default configuration exercises the NX logic a 8 BPP but provides no visual feedback. In this configuration, a very simple, simulated framebuffer driver is used that is based upon a simple region of memory posing as video memory. That default configuration can be built as follows:
  2. The preferred configuration is at configs/sim/nx11/defconfig. This configuration extends the test with a simulated framebuffer driver that uses an X window as a framebuffer. This is a superior test configuration because the X window appears at your desktop and you can see the NX output. This preferred configuration can be built as follows:

    Update: The sim target has suffered some bit-rot over the years and so the following caveats need to be added:

Test Coverage. At present, apps/examples/nxt only exercises a subset of NX; the remainder is essentially untested. The following table describes the testing performed on each NX API:

Table D.1: NXGLIB API Test Coverage

Function Special Setup/Notes Verified
nxgl_rgb2yuv()
NO
nxgl_yuv2rgb()
NO
nxgl_rectcopy()
YES
nxgl_rectoffset()
YES
nxgl_vectoradd()
YES
nxgl_vectorsubtract()
YES
nxgl_rectintersect()
YES
nxgl_rectunion()
YES
nxgl_nonintersecting()
YES
nxgl_rectoverlap()
YES
nxgl_rectinside()
YES
nxgl_rectsize()
YES
nxgl_nullrect()
YES
nxgl_runoffset() Verified by apps/examples/nxlines. YES
nxgl_runcopy()
NO
nxgl_trapoffset() Verified by apps/examples/nxlines. YES
nxgl_trapcopy() Verified by apps/examples/nxlines. YES
nxgl_colorcopy
YES
nxgl_splitline Verified using apps/examples/nxlines. Generally works well, but has some accuracy/overflow problems wide lines that are nearly horizontal. There is a "fudge factor" that seems to eliminate the problem, but there could still be issues in some configurations. YES
nxgl_circlepts Verified by apps/examples/nxlines. YES
nxgl_circletraps Verified by apps/examples/nxlines. YES

Table D.2: NX Server Callbacks Test Coverage

Function Special Setup/Notes Verified
redraw()
YES
position()
YES
mousein()
YES
kbdin()
YES

Table D.3: NX API Test Coverage

Function Special Setup/Notes Verified
nx_runinstance() Change to CONFIG_NX_MULTIUSER=y in the <NuttX-Directory>/.config file YES
nx_connectinstance() Change to CONFIG_NX_MULTIUSER=y in the <NuttX-Directory>/.config file YES
nx_open()
YES
nx_disconnect() Change to CONFIG_NX_MULTIUSER=y in the <NuttX-Directory>/.config file YES
nx_close()
YES
nx_eventhandler() Change to CONFIG_NX_MULTIUSER=y in the <NuttX-Directory>/.config file YES
nx_eventnotify() This is not used in the current version of apps/examples/nx, was tested in a previous version) NO
nx_openwindow() Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the <NuttX-Directory>/.config file YES
nx_closewindow() Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the <NuttX-Directory>/.config file YES
nx_requestbkgd() Verified by apps/examples/nxtext and apps/examples/nxhello. YES
nx_releasebkgd() Verified by apps/examples/nxtext and apps/examples/nxhello. YES
nx_getposition()
NO
nx_setposition() Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the <NuttX-Directory>/.config file YES
nx_setsize() Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the <NuttX-Directory>/.config file YES
nx_raise() Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the <NuttX-Directory>/.config file YES
nx_lower() Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the <NuttX-Directory>/.config file YES
nx_fill() Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the <NuttX-Directory>/.config file YES
nx_getrectangle()
YES
nx_filltrapezoid() Verified by apps/examples/nxlines. YES
nx_drawline() Verified by apps/examples/nxlines. YES
nx_drawcircle() Verified by apps/examples/nxlines. YES
nx_fillcircle() Verified by apps/examples/nxlines. YES
nx_setbgcolor()
YES
nx_move() Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the <NuttX-Directory>/.config file YES
nx_bitmap() Change to CONFIG_EXAMPLES_NX_RAWWINDOWS=y in the <NuttX-Directory>/.config file. YES
nx_kbdin()
YES
nx_mousein()
YES

Table D.4: NXTK API Test Coverage

Function Special Setup/Notes Verified
nxtk_openwindow()
YES
nxtk_closewindow()
YES
nxtk_getposition()
NO
nxtk_setposition()
YES
nxtk_setsize()
YES
nxtk_raise()
YES
nxtk_lower()
YES
nxtk_fillwindow()
YES
nxtk_getwindow()
NO
nxtk_filltrapwindow()
NO
nxtk_drawlinewindow()
YES
nxtk_drawcirclewindow()
YES
nxtk_fillcirclewindow()
YES
nxtk_movewindow()
NO
nxtk_bitmapwindow()
YES
nxtk_opentoolbar()
YES
nxtk_closetoolbar()
YES
nxtk_filltoolbar()
YES
nxtk_gettoolbar()
NO
nxtk_filltraptoolbar()
NO
nxtk_drawlinetoolbar()
NO
nxtk_drawcircletoolbar()
NO
nxtk_fillcircletoolbar()
NO
nxtk_movetoolbar()
NO
nxtk_bitmaptoolbar()
NO

Table D.5: NXFONTS API Test Coverage

Function Special Setup/Notes Verified
nxf_getfonthandle()
YES
nxf_getfontset()
YES
nxf_getbitmap()
YES
nxf_convert_2bpp()
NO
nxf_convert_4bpp()
NO
nxf_convert_8bpp() Use defconfig when building. YES
nxf_convert_16bpp()
YES
nxf_convert_24bpp()
NO
nxf_convert_32bpp() YES