NX Graphics Subsystem

Last Updated: August 8, 2019



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 NX Cursor Support (NXCURSOR)

2.7 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 a small-footprint, multi-user implentation (NXMU as described below). 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 initialization 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 envisioned 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)

NxWidgets is a higher level, C++, object-oriented library for object-oriented access to graphical "widgets." NxWidgets is provided as a separate library in the apps/ repository NxWidgets is built on top of the core NuttX graphics subsystem, but is part of the application space rather than part of the core OS graphics subsystems.

1.3.6 NX Terminal Driver (NxTerm)

NxTerm is a write-only character device (not shown) that is built on top of an NX window. This character device can be used to provide stdout and stderr and, hence, can provide the output side of NuttX console. ).

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 YUV triplet to 8-bit RGB 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 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.

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(). These callbacks will be invoked as part of the processing performed by nx_eventhandler().

2.3.3 Starting the NX Server

The NX Server is a kernel daemon that receives and serializes graphic commands. Before you can use the NX graphics system, you must first start this daemon. There are two ways that this can be done:

  1. The NX server may be started in your board startup logic by simply calling the function nxmu_start(). The board startup logic usually resides the the boards/arch/chip/board/src directory. The board startup logic can run automatically during the early system if CONFIG_BOARD_LATE_INITIALIZE is defined in the configuration. Or, the board startup logic can execute under control of the application by calling the boardctl(BOARDIOC_INIT, arg) OS interface.

    The board initialization logic will run in either case and the simple call to nxmu_start() will start the NX server.

  2. The NX server may also be started later by the application via the boardctl(BOARDIOC_NX_START, arg)

2.3.3.1 nxmu_start()

Function Prototype:

Description: nxmu_start() provides a wrapper function to simplify and standardize the starting of the NX server.

Input Parameters:

Returned Value: Zero (OK) is returned on success. This indicates that the NX server has been successfully started, is running, and waiting to accept connections from NX clients.

A negated errno value is returned on failure. The errno value indicates the nature of the failure.

2.3.3.1 boardctl()

Function Prototype:

Description: boardctl() is a generic NuttX interface that among many of it functions, may also be used to start the NX server.

In a small embedded system, there will typically be a much greater interaction between application and low-level board features. The canonically correct to implement such interactions is by implementing a character driver and performing the interactions via low level ioctl() calls. This, however, may not be practical in many cases and will lead to "correct" but awkward implementations.

boardctl() is non-standard OS interface to alleviate the problem. It basically circumvents the normal device driver ioctl interlace and allows the application to perform direction IOCTL-like calls to the board-specific logic. In it is especially useful for setting up board operational and test configurations.

When called with the cmd of BOARDIOC_NX_START, then the boardctl() will call nxmu_start indirectly on behalf of the appication. In this case the arg parameter is ignored.

Input Parameters:

Returned Value: On success zero (OKERROR) is returned on failure with the errno variable set to indicate the nature of the failure.

2.3.4 NX Server Callbacks

2.3.4.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.4.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.4.3 mousein()

Callback Function Prototype:

Description: New mouse data is available for the window

Input Parameters:

Returned Value: None

2.3.4.4 kbdin()

Callback Function Prototype:

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

Input Parameters:

Returned Value: None

2.3.4.5 event()

2.3.4.5 event()

Callback Function Prototype:

Description: This callback is used to communicate server events to the window listener.

NXEVENT_BLOCKED - Window messages are blocked.
This callback is the response from nx_block(), nxtk_block(). Those blocking interfaces are used to assure that no further messages are directed to the window. Receipt of the blocked callback signifies that (1) there are no further pending callbacks and (2) that the window is now defunct and will receive no further callbacks. This callback supports coordinated destruction of a window. In the multi-user mode, the client window logic must stay intact until all of the queued callbacks are processed. Then the window may be safely closed. Closing the window prior with pending callbacks can lead to bad behavior when the callback is executed.
NXEVENT_SYNCHED - Synchronization handshake
This completes the handshake started by nx_synch(), or nxtk_synch(). Those interfaces send a synchronization messages to the NX server which responds with this event. The sleeping client is awakened and continues graphics processing, completing the handshake. Due to the highly asynchronous nature of client-server communications, synchronization is sometimes necessary to assure that the client and server are working together properly.

Input Parameters:

Returned Value: None

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

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

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

Input Parameters:

Returned Value: None.

2.3.8 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 available.

Input Parameters:

Returned Value:

2.3.9 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.10 nx_block()

Function Prototype:

Description: The response to this function call is two things: (1) any queued callback messages to the window are 'blocked' and then (2) also subsequent window messaging is blocked.

The event callback with the NXEVENT_BLOCKED event is the response from nx_block(). This blocking interface is used to assure that no further messages are are directed to the window. Receipt of the NXEVENT_BLOCKED event signifies that (1) there are no further pending callbacks and (2) that the window is now defunct and will receive no further callbacks.

This callback supports coordinated destruction of a window. The client window logic must stay intact until all of the queued callbacks are processed. Then the window may be safely closed. Closing the window prior with pending callbacks can lead to bad behavior when the callback is executed.

Input Parameters:

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

2.3.11 nx_synch()

Function Prototype:

Description: This interface can be used to synchronize the window client with the NX server. It really just implements an echo: A synch message is sent from the window client to the server which then responds immediately by sending the NXEVENT_SYNCHED back to the windows client.

Due to the highly asynchronous nature of client-server communications, nx_synch() is sometimes necessary to assure that the client and server are fully synchronized in time.

Usage by the window client might be something like this:

When the window listener thread receives the NXEVENT_SYNCHED event, it would set g_synched to true and post g_synch_sem, waking up the above loop.

Input Parameters:

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

2.3.12 nx_openwindow()

Function Prototype:

Description: Create a new window.

Input Parameters:

Returned Value:

2.3.13 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.14 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.15 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.16 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.17 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.18 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.19 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.20 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.21 nx_modal()

Function Prototype:

Description: May be used to either (1) raise a window to the top of the display and select modal behavior, or (2) disable modal behavior.

Input Parameters:

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

2.3.22 nx_setvisibility()

Function Prototype:

Description: Select if the window is visible or hidden. A hidden window is still present and will update normally, but will not be visible on the display until it is unhidden.

Input Parameters:

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

2.3.23 nx_ishidden()

Function Prototype:

Description: Return true if the window is hidden.

NOTE: There will be a delay between the time that the visibility of the window is changed via nx_setvisibily() before that new setting is reported by nx_ishidden(). nx_synch() may be used if temporal synchronization is required.

Input Parameters:

Returned Value: True: the window is hidden, false: the window is visible

2.3.24 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.25 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.26 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.27 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.28 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.29 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.30 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.31 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.32 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.33 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.34 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_block()

Function Prototype:

Description: The response to this function call is two things: (1) any queued callback messages to the window are 'blocked' and then (2) also subsequent window messaging is blocked.

The event callback with the NXEVENT_BLOCKED event is the response from nxtk_block(). This blocking interface is used to assure that no further messages are are directed to the window. Receipt of the NXEVENT_BLOCKED event signifies that (1) there are no further pending callbacks and (2) that the window is now defunct and will receive no further callbacks.

This callback supports coordinated destruction of a window. The client window logic must stay intact until all of the queued callbacks are processed. Then the window may be safely closed. Closing the window prior with pending callbacks can lead to bad behavior when the callback is executed.

Input Parameters:

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

2.4.3 nxtk_synch()

Function Prototype:

Description: This interface can be used to synchronize the window client with the NX server. It really just implements an echo: A synch message is sent from the window client to the server which then responds immediately by sending the NXEVENT_SYNCHED back to the windows client.

Due to the highly asynchronous nature of client-server communications, nx_synch() is sometimes necessary to assure that the client and server are fully synchronized in time.

Usage by the window client might be something like this:

When the window listener thread receives the NXEVENT_SYNCHED event, it would set g_synched to true and post g_synch_sem, waking up the above loop.

Input Parameters:

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

2.4.4 nxtk_openwindow()

Function Prototype:

Description: Create a new, framed window.

Input Parameters:

handle
The handle returned by nx_connect().
flags
Optional flags. These include:
cb
Callbacks used to process window events
arg
User provided argument (see nx_openwindow())

Returned Value:

2.4.5 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.6 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.7 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.8 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.9 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.10 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.11 nxtk_modal()

Function Prototype:

Description: May be used to either (1) raise a window to the top of the display and select modal behavior, or (2) disable modal behavior.

Input Parameters:

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

2.4.12 nxtk_setvisibility()

Function Prototype:

Description: Select if the window is visible or hidden. A hidden window is still present and will update normally, but will not be visible on the display until it is unhidden.

Input Parameters:

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

2.4.13 nxtk_ishidden()

Function Prototype:

Description: Return true if the window is hidden.

NOTE: There will be a delay between the time that the visibility of the window is changed via nxtk_setvisibily() before that new setting is reported by nxtk_ishidden(). nxtk_synch() may be used if temporal synchronization is required.

Input Parameters:

Returned Value: True: the window is hidden, false: the window is visible

2.4.14 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.15 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, of the dest memory

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

2.4.16 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.17 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.18 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.19 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.20 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.21 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.22 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.23 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.24 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.25 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, of the dest memory.

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

2.4.26 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.27 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.28 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.29 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.30 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.31 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

2.6 NX Cursor Support (NXCURSOR)

2.6.1 nxcursor_enable()

Function Prototype:

Description: Enable/disable presentation of the cursor. The disabled cursor still exits and still may be controlled, but is not visible on the display.

Input Parameters:

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

2.6.2 nxcursor_setimage()

Function Prototype:

Description: Set the cursor image.

The image is provided a a 2-bits-per-pixel image. The two bit incoding is as followings:

NOTE: The NX logic will reference the user image buffer repeatedly. That image buffer must persist for as long as the NX server connection persists.

Input Parameters:

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

2.6.3 nxcursor_setposition()

Function Prototype:

Description: Move the cursor to the specified position.

Input Parameters:

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

2.7 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

The graphics capability consist both of components internal to the RTOS and of user-callable interfaces. In the NuttX kernel mode build there are some components of the graphics subsystem are callable in user mode and other components that are internal to the RTOS. The directory nuttx/graphics contains only those components that are internal to the RTOS. User callable functions must be part of a library that can be linked against user applications. This user callable interfaces are provided in sub-directories under nuttx/libnx.

Appendix B NX Configuration Options

B.1 General Configuration Settings

B.2 NXGL Configuration Settings

B.3 NX Configuration Settings

B.4 NX Server Configuration Settings

B.5 NXTK Configuration Settings

B.6 NXFONTS Configuration Settings

B.7 NxTerm Configuration Settings

General NxTerm settings.

NxTerm output text/graphics options:

NxTerm input options:

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 definitions. 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 do 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 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 boards/sim/sim/sim/configs/nx and boards/sim/sim/sim/configs/nx11. There are two alternative configurations for building the simulation:

  1. The configuration using the configuration file at boards/sim/sim/sim/configs/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 boards/sim/sim/sim/configs/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()
YES
nx_connectinstance()
YES
nx_disconnect()
YES
nx_eventhandler()
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_modal()   NO
nx_setvisibility() Exercized using Twm4Nx YES, Informally
nx_ishidden() Exercized using Twm4Nx YES, Informally
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_modal()
NO
nxtk_setvisibility() Exercized using Twm4Nx YES, informally
nxtk_ishidden() Exercized using Twm4Nx YES, informally
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