28de00a90a
Squashed commit of the following:
libnx: Need to duplicate some Kconfig setting for NXFONTs if it can be configured and built independently of NX. Also includes some build-related fixes.
configs/sim: Disable NX graphics support in the fb configuration.
libnx: Basic configuration and build changes to support building font support independend of the NX server.
409 lines
17 KiB
Plaintext
409 lines
17 KiB
Plaintext
README
|
|
^^^^^^
|
|
|
|
This directory contains tiny graphics support for NuttX. The contents of this directory
|
|
are only build if CONFIG_NX is defined in the NuttX configuration file.
|
|
|
|
Contents
|
|
^^^^^^^^
|
|
Roadmap
|
|
Related Header Files
|
|
Directories
|
|
Installing New Fonts
|
|
Configuration Settings
|
|
|
|
Roadmap
|
|
^^^^^^^
|
|
|
|
This directory holds NuttX graphic packages. Not all of these packages are implemented
|
|
at the present, but here is the longer term roadmap:
|
|
|
|
NxWidgets - NxWidgets is a higher level, C++, object-oriented library for object-
|
|
oriented access to graphics "widgets." NxWidgets is provided as a separate
|
|
package. NxWidgets is built on top of the core NuttX graphics subsystem,
|
|
but is not a part of the core graphics subystems.
|
|
NXTOOLKIT - A set of C graphics tools that provide higher-level window drawing
|
|
operations. The toolkit can be used for window-oriented graphics
|
|
without NxWidgets and is built on top of NX.
|
|
NXFONTS - A set of C graphics tools for presenting (bitmap) font images.
|
|
NX - The tiny NuttX windowing system. This includes the small-footprint
|
|
multi-user implentation (NXMU as described below). NX can be used
|
|
without NxWidgets and without NXTOOLKIT for raw access to window memory.
|
|
NXGLIB - Low level graphics utilities and direct framebuffer rendering logic.
|
|
NX is built on top of NXGLIB.
|
|
NxTerm - NxTerm is a write-only character device 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.
|
|
|
|
|
|
Related Header Files
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
include/nuttx/nx/nxglib.h -- Describes the NXGLIB C interfaces
|
|
include/nuttx/nx/nx.h -- Describes the NX C interfaces
|
|
include/nuttx/nx/nxtk.h -- Describe the NXTOOLKIT C interfaces
|
|
include/nuttx/nx/nxfont.h -- Describe sthe NXFONT C interfaces
|
|
|
|
Directories
|
|
^^^^^^^^^^^
|
|
|
|
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. This directory, nuttx/graphics,
|
|
contains only those components that are internal to the RTOS.
|
|
|
|
User callable functions must, instead, be part of a library that can be
|
|
linked against user applications. This user callable interfaces are
|
|
provided in sub-directories under nuttx/libnx.
|
|
|
|
libnx/nx
|
|
Client application callable interfaces.
|
|
|
|
graphics/nxglib
|
|
libnx/nxglib
|
|
The NuttX tiny graphics library. The directory contains generic utilities
|
|
support operations on primitive graphics objects and logic to rasterize directly
|
|
into a framebuffer. It has no concept of windows (other than the one, framebuffer
|
|
window).
|
|
|
|
graphics/nxbe
|
|
This is the "back-end" of a tiny windowing system. It contains most
|
|
of the important window management logic: clipping, window controls,
|
|
window drawing, etc. Currently, the NXserver is the only "front-end"
|
|
|
|
graphics/nxmu
|
|
libnx/nxmu
|
|
This is the NX multi user "front end". When combined with the generic
|
|
"back-end" (nxbe), it implements a multi-threaded, multi-user windowing
|
|
system. The files in this directory present the window APIs described in
|
|
include/nuttx/nx/nx.h. The multi-user front end includes the NX graphics
|
|
server that executes on its own thread; multiple graphics clients then
|
|
communicate with the server via a POSIX message queue to serialize window
|
|
operations from many threads. The multi-user front-end is selected
|
|
automatically.
|
|
|
|
libnx/nxfonts
|
|
This is where the NXFONTS implementation resides. This is a relatively low-
|
|
level set of charset set/glyph management APIs. See include/nuttx/nx/nxfonts.h
|
|
|
|
libnx/nxtk
|
|
This is where the NXTOOLKIT implementation resides. This toolkit is built on
|
|
top of NX and works with either the single-user or multi-user NX version. See
|
|
include/nuttx/nx/nxtk.h
|
|
|
|
nuttx/../NxWidgets
|
|
The NxWidgets code is provided as a separate package located outside of the
|
|
NuttX source tree (probably at this location).
|
|
|
|
graphics/vnc
|
|
The future home of the VNC Remote Frame Buffer (RFB) server and client
|
|
implementations.
|
|
|
|
Installing New Fonts
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
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.
|
|
|
|
Below are general instructions for creating and installing a new font
|
|
in the NX graphic system:
|
|
|
|
1. Locate a font in BDF format,
|
|
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.
|
|
|
|
Create a new NuttX configuration variable. For example, suppose
|
|
you define the following variable: CONFIG_NXFONT_MYFONT. Then
|
|
you would need to:
|
|
|
|
3. Define CONFIG_NXFONT_MYFONT=y in your NuttX configuration file.
|
|
|
|
A font ID number has to be assigned for each new font. The font ID
|
|
is 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 your
|
|
new font in a similar fashion:
|
|
|
|
4. include/nuttx/nx/nxfonts.h. Add you new font as a possible system
|
|
default font:
|
|
|
|
#if defined(CONFIG_NXFONT_SANS23X27)
|
|
# define NXFONT_DEFAULT FONTID_SANS23X27
|
|
#elif defined(CONFIG_NXFONT_MYFONT)
|
|
# define NXFONT_DEFAULT FONTID_MYFONT
|
|
#endif
|
|
|
|
Then define the actual font ID. Make sure that the font ID value
|
|
is unique:
|
|
|
|
enum nx_fontid_e
|
|
{
|
|
FONTID_DEFAULT = 0 /* The default font */
|
|
#ifdef CONFIG_NXFONT_SANS23X27
|
|
, FONTID_SANS23X27 = 1 /* The 23x27 sans serif font */
|
|
#endif
|
|
#ifdef CONFIG_NXFONT_MYFONT
|
|
, FONTID_MYFONT = 2 /* My shiny, new font */
|
|
#endif
|
|
...
|
|
|
|
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:
|
|
|
|
5. 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.
|
|
|
|
genfontsources:
|
|
ifeq ($(CONFIG_NXFONT_SANS23X27),y)
|
|
@$(MAKE) -C nxfonts -f Makefile.sources TOPDIR=$(TOPDIR) NXFONTS_FONTID=1 EXTRADEFINES=$(EXTRADEFINES)
|
|
endif
|
|
ifeq ($(CONFIG_NXFONT_MYFONT),y)
|
|
@$(MAKE) -C nxfonts -f Makefile.sources TOPDIR=$(TOPDIR) NXFONTS_FONTID=2 EXTRADEFINES=$(EXTRADEFINES)
|
|
endif
|
|
|
|
6. 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:
|
|
|
|
ifeq ($(CONFIG_NXFONT_SANS23X27),y)
|
|
NXFSET_CSRCS += nxfonts_bitmaps_sans23x27.c
|
|
endif
|
|
ifeq ($(CONFIG_NXFONT_MYFONT),y)
|
|
NXFSET_CSRCS += nxfonts_bitmaps_myfont.c
|
|
endif
|
|
|
|
7. 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):
|
|
|
|
ifeq ($(NXFONTS_FONTID),1)
|
|
NXFONTS_PREFIX := g_sans23x27_
|
|
GEN_CSRC = nxfonts_bitmaps_sans23x27.c
|
|
endif
|
|
ifeq ($(NXFONTS_FONTID),2)
|
|
NXFONTS_PREFIX := g_myfont_
|
|
GEN_CSRC = nxfonts_bitmaps_myfont.c
|
|
endif
|
|
|
|
8. graphics/nxfonts/nxfonts_bitmaps.c. This is the file that contains
|
|
the generic font structures. It is used as a "template" file by
|
|
nuttx/graphics/nxfonts/Makefile.sources to create your customized
|
|
font data set.
|
|
|
|
#if NXFONTS_FONTID == 1
|
|
# include "nxfonts_sans23x27.h"
|
|
#elif NXFONTS_FONTID == 2
|
|
# include "nxfonts_myfont.h"
|
|
#else
|
|
# error "No font ID specified"
|
|
#endif
|
|
|
|
Where nxfonts_myfont.h is the NuttX font file that we generated in
|
|
step 2 using the bdf-converter tool.
|
|
|
|
9. 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).
|
|
The new font information needs to be added to data structures used by
|
|
that function:
|
|
|
|
#ifdef CONFIG_NXFONT_SANS23X27
|
|
extern const struct nx_fontpackage_s g_sans23x27_package;
|
|
#endif
|
|
#ifdef CONFIG_NXFONT_MYFONT
|
|
extern const struct nx_fontpackage_s g_myfont_package;
|
|
#endif
|
|
|
|
static FAR const struct nx_fontpackage_s *g_fontpackages[] =
|
|
{
|
|
#ifdef CONFIG_NXFONT_SANS23X27
|
|
&g_sans23x27_package,
|
|
#endif
|
|
#ifdef CONFIG_NXFONT_MYFONT
|
|
&g_myfont_package,
|
|
#endif
|
|
NULL
|
|
};
|
|
|
|
Configuration Settings
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
General NX Settings
|
|
-------------------
|
|
|
|
CONFIG_NX
|
|
Enables overall support for graphics library and NX
|
|
CONFIG_NX_NPLANES
|
|
Some YUV color formats requires support for multiple planes, one for each
|
|
color component. Unless you have such special hardware, this value should be
|
|
undefined or set to 1.
|
|
CONFIG_NX_WRITEONLY
|
|
Define if the underlying graphics device does not support read operations.
|
|
Automatically defined if CONFIG_NX_LCDDRIVER and CONFIG_LCD_NOGETRUN are
|
|
defined.
|
|
CONFIG_NX_DISABLE_1BPP, CONFIG_NX_DISABLE_2BPP,
|
|
CONFIG_NX_DISABLE_4BPP, CONFIG_NX_DISABLE_8BPP,
|
|
CONFIG_NX_DISABLE_16BPP, CONFIG_NX_DISABLE_24BPP, and
|
|
CONFIG_NX_DISABLE_32BPP
|
|
NX supports a variety of pixel depths. You can save some memory by disabling
|
|
support for unused color depths.
|
|
CONFIG_NX_PACKEDMSFIRST
|
|
If a pixel depth of less than 8-bits is used, then NX needs to know if the
|
|
pixels pack from the MS to LS or from LS to MS
|
|
CONFIG_NX_XYINPUT
|
|
Build in support for a X/Y positional input device such as a mouse or a
|
|
touchscreen.
|
|
CONFIG_NX_KBD
|
|
Build in support of keypad/keyboard input.
|
|
CONFIG_NXTK_BORDERWIDTH
|
|
Specifies with with of the border (in pixels) used with framed windows.
|
|
The default is 4.
|
|
CONFIG_NXTK_BORDERCOLOR1, CONFIG_NXTK_BORDERCOLOR2, CONFIG_NXTK_BORDERCOLOR3
|
|
Specify the colors of the border used with framed windows.
|
|
CONFIG_NXTK_BORDERCOLOR2 is the shadow side color and so is normally darker.
|
|
CONFIG_NXTK_BORDERCOLOR3 is the shiny side color and so is normally brighter.
|
|
The default is mediumdark grey, and light grey, respectively
|
|
CONFIG_NXTK_AUTORAISE
|
|
If set, a window will be raised to the top if the mouse position is over a
|
|
visible portion of the window. Default: A mouse button must be clicked over
|
|
a visible portion of the window.
|
|
CONFIG_NXFONTS_CHARBITS
|
|
The number of bits in the character set. Current options are only 7 and 8.
|
|
The default is 7.
|
|
CONFIG_VNCSERVER and CONFIG_VNCCLIENT
|
|
Enable the VNC RFB server and client, respecitively.
|
|
|
|
Font Selections
|
|
---------------
|
|
|
|
CONFIG_NXFONT_SANS17X22
|
|
This option enables support for a tiny, 17x22 san serif font
|
|
(font ID FONTID_SANS17X22 == 14).
|
|
CONFIG_NXFONT_SANS20X26
|
|
This option enables support for a tiny, 20x26 san serif font
|
|
(font ID FONTID_SANS20X26 == 15).
|
|
CONFIG_NXFONT_SANS23X27
|
|
This option enables support for a tiny, 23x27 san serif font
|
|
(font ID FONTID_SANS23X27 == 1).
|
|
CONFIG_NXFONT_SANS22X29
|
|
This option enables support for a small, 22x29 san serif font
|
|
(font ID FONTID_SANS22X29 == 2).
|
|
CONFIG_NXFONT_SANS28X37
|
|
This option enables support for a medium, 28x37 san serif font
|
|
(font ID FONTID_SANS28X37 == 3).
|
|
CONFIG_NXFONT_SANS39X48
|
|
This option enables support for a large, 39x48 san serif font
|
|
(font ID FONTID_SANS39X48 == 4).
|
|
CONFIG_NXFONT_SANS17X23B
|
|
This option enables support for a tiny, 17x23 san serif bold font
|
|
(font ID FONTID_SANS17X23B == 16).
|
|
CONFIG_NXFONT_SANS20X27B
|
|
This option enables support for a tiny, 20x27 san serif bold font
|
|
(font ID FONTID_SANS20X27B == 17).
|
|
CONFIG_NXFONT_SANS22X29B
|
|
This option enables support for a small, 22x29 san serif bold font
|
|
(font ID FONTID_SANS22X29B == 5).
|
|
CONFIG_NXFONT_SANS28X37B
|
|
This option enables support for a medium, 28x37 san serif bold font
|
|
(font ID FONTID_SANS28X37B == 6).
|
|
CONFIG_NXFONT_SANS40X49B
|
|
This option enables support for a large, 40x49 san serif bold font
|
|
(font ID FONTID_SANS40X49B == 7).
|
|
CONFIG_NXFONT_SERIF22X29
|
|
This option enables support for a small, 22x29 font (with serifs)
|
|
(font ID FONTID_SERIF22X29 == 8).
|
|
CONFIG_NXFONT_SERIF29X37
|
|
This option enables support for a medium, 29x37 font (with serifs)
|
|
(font ID FONTID_SERIF29X37 == 9).
|
|
CONFIG_NXFONT_SERIF38X48
|
|
This option enables support for a large, 38x48 font (with serifs)
|
|
(font ID FONTID_SERIF38X48 == 10).
|
|
CONFIG_NXFONT_SERIF22X28B
|
|
This option enables support for a small, 27x38 bold font (with serifs)
|
|
(font ID FONTID_SERIF22X28B == 11).
|
|
CONFIG_NXFONT_SERIF27X38B
|
|
This option enables support for a medium, 27x38 bold font (with serifs)
|
|
(font ID FONTID_SERIF27X38B == 12).
|
|
CONFIG_NXFONT_SERIF38X49B
|
|
This option enables support for a large, 38x49 bold font (with serifs)
|
|
(font ID FONTID_SERIF38X49B == 13).
|
|
|
|
NxTerm Configuration Settings
|
|
--------------------------------
|
|
|
|
CONFIG_NXTERM
|
|
Enables building of the NxTerm driver.
|
|
|
|
NxTerm output text/graphics options:
|
|
|
|
CONFIG_NXTERM_BPP
|
|
Currently, NxTerm supports only a single pixel depth. This
|
|
configuration setting must be provided to support that single pixel depth.
|
|
Default: The smallest enabled pixel depth. (see CONFIG_NX_DISABLE_*BPP)
|
|
CONFIG_NXTERM_CURSORCHAR
|
|
The bitmap code to use as the cursor. Default '_'
|
|
CONFIG_NXTERM_MXCHARS
|
|
NxTerm needs to remember every character written to the console so
|
|
that it can redraw the window. This setting determines the size of some
|
|
internal memory allocations used to hold the character data. Default: 128.
|
|
CONFIG_NXTERM_CACHESIZE
|
|
NxTerm supports caching of rendered fonts. This font caching is required
|
|
for two reasons: (1) First, it improves text performance, but more
|
|
importantly (2) it preserves the font memory. Since the NX server runs on
|
|
a separate server thread, it requires that the rendered font memory persist
|
|
until the server has a chance to render the font. Unfortunately, the font
|
|
cache would be quite large if all fonts were saved. The CONFIG_NXTERM_CACHESIZE
|
|
setting will control the size of the font cache (in number of glyphs). Only that
|
|
number of the most recently used glyphs will be retained. Default: 16.
|
|
NOTE: There can still be a race condition between the NxTerm driver and the
|
|
NX task. If you every see character corruption (especially when printing
|
|
a lot of data or scrolling), then increasing the value of CONFIG_NXTERM_CACHESIZE
|
|
is something that you should try. Alternatively, you can reduce the size of
|
|
CONFIG_MQ_MAXMSGSIZE which will force NxTerm task to pace the server task.
|
|
CONFIG_NXTERM_CACHESIZE should be larger than CONFIG_MQ_MAXMSGSIZE in any event.
|
|
CONFIG_NXTERM_LINESEPARATION
|
|
This the space (in rows) between each row of test. Default: 0
|
|
CONFIG_NXTERM_NOWRAP
|
|
By default, lines will wrap when the test reaches the right hand side
|
|
of the window. This setting can be defining to change this behavior so
|
|
that the text is simply truncated until a new line is encountered.
|
|
|
|
NxTerm Input options
|
|
|
|
CONFIG_NXTERM_NXKBDIN
|
|
Take input from the NX keyboard input callback. By default, keyboard
|
|
input is taken from stdin (/dev/console). If this option is set, then
|
|
the interface nxterm_kdbin() is enabled. That interface may be driven
|
|
by window callback functions so that keyboard input *only* goes to the
|
|
top window.
|
|
CONFIG_NXTERM_KBDBUFSIZE
|
|
If CONFIG_NXTERM_NXKBDIN is enabled, then this value may be used to
|
|
define the size of the per-window keyboard input buffer. Default: 16
|
|
CONFIG_NXTERM_NPOLLWAITERS
|
|
The number of threads that can be waiting for read data available.
|
|
Default: 4
|
|
|
|
NX Multi-user options
|
|
---------------------
|
|
|
|
CONFIG_NX_BLOCKING
|
|
Open the client message queues in blocking mode. In this case,
|
|
nx_eventhandler() will not return until a message is received and processed.
|
|
CONFIG_NX_MXSERVERMSGS and CONFIG_NX_MXCLIENTMSGS
|
|
Specifies the maximum number of messages that can fit in the message queues.
|
|
No additional resources are allocated, but this can be set to prevent
|
|
flooding of the client or server with too many messages (CONFIG_PREALLOC_MQ_MSGS
|
|
controls how many messages are pre-allocated).
|
|
|