diff options
Diffstat (limited to 'nuttx/graphics/README.txt')
| -rw-r--r-- | nuttx/graphics/README.txt | 401 |
1 files changed, 401 insertions, 0 deletions
diff --git a/nuttx/graphics/README.txt b/nuttx/graphics/README.txt new file mode 100644 index 000000000..18aebadbd --- /dev/null +++ b/nuttx/graphics/README.txt @@ -0,0 +1,401 @@ +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 present (bitmap) font images. + NX - The tiny NuttX windowing system. This includes both a small-footprint, + single user implementaton (NXSU as described below) 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 more-or-less interchangable. 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. + NxConsole - NxConsole 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. + NxConsole is only available when the multi-user NX implementation is + selected (CONFIG_NX_MULTIUSERs). + + +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 +^^^^^^^^^^^ + +graphics/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 can be used with either of + two front-ends to complete a windowing system (see nxmu and nxsu below). It + contains most of the important window management logic: clipping, window controls, + window drawing, etc. + +graphics/nxsu + This is the NX single user "front end". When combined with the generic "back-end" + (nxbe), it implements a single thread, single user windowing system. The files + in this directory present the window APIs described in include/nuttx/nx/nx.h. The + single user front-end is selected when CONFIG_NX_MULTIUSER is not defined in the + NuttX configuration file. + +graphics/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 a 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 when CONFIG_NX_MULTIUSER is defined in the NuttX configuration file. + +graphics/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 + +graphics/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). + +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_MULTIUSER + Configures NX in multi-user mode +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_MOUSE + Build in support for mouse input. +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. + +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). + +NxConsole Configuration Settings +-------------------------------- + +CONFIG_NXCONSOLE + Enables building of the NxConsole driver. + +NxConsole output text/graphics options: + +CONFIG_NXCONSOLE_BPP + Currently, NxConsole 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_NXCONSOLE_CURSORCHAR + The bitmap code to use as the cursor. Default '_' +CONFIG_NXCONSOLE_MXCHARS + NxConsole 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_NXCONSOLE_CACHESIZE + NxConsole 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_NXCONSOLE_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 NxConsole 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_NXCONSOLE_CACHESIZE + is something that you should try. Alternatively, you can reduce the size of + CONFIG_MQ_MAXMSGSIZE which will force NxConsole task to pace the server task. + CONFIG_NXCONSOLE_CACHESIZE should be larger than ONFIG_MQ_MAXMSGSIZE in any event. +CONFIG_NXCONSOLE_LINESEPARATION + This the space (in rows) between each row of test. Default: 0 +CONFIG_NXCONSOLE_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. + +NxConsole Input options + +CONFIG_NXCONSOLE_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 nxcon_kdbin() is enabled. That interface may be driven + by window callback functions so that keyboard input *only* goes to the + top window. +CONFIG__NXCONSOLE_KBDBUFSIZE + If CONFIG_NXCONSOLE_NXKBDIN is enabled, then this value may be used to + define the size of the per-window keyboard input buffer. Default: 16 +CONFIG_NXCONSOLE_NPOLLWAITERS + The number of threads that can be waiting for read data available. + Default: 4 + +NX Multi-user only 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). + + |