diff options
| -rw-r--r-- | nuttx/Documentation/NXGraphicsSubsystem.html | 2620 | ||||
| -rw-r--r-- | nuttx/Documentation/NXOrganization.gif | bin | 0 -> 34880 bytes | |||
| -rw-r--r-- | nuttx/Documentation/NuttX.html | 14 | ||||
| -rw-r--r-- | nuttx/Documentation/NuttxPortingGuide.html | 286 | ||||
| -rw-r--r-- | nuttx/graphics/README.txt | 2 | ||||
| -rw-r--r-- | nuttx/include/nuttx/arch.h | 2 | ||||
| -rw-r--r-- | nuttx/include/nuttx/nx.h | 18 | ||||
| -rw-r--r-- | nuttx/include/nuttx/nxfonts.h | 7 | ||||
| -rw-r--r-- | nuttx/include/nuttx/nxglib.h | 8 | ||||
| -rw-r--r-- | nuttx/include/nuttx/nxtk.h | 14 |
10 files changed, 2848 insertions, 123 deletions
diff --git a/nuttx/Documentation/NXGraphicsSubsystem.html b/nuttx/Documentation/NXGraphicsSubsystem.html new file mode 100644 index 000000000..cfe66daae --- /dev/null +++ b/nuttx/Documentation/NXGraphicsSubsystem.html @@ -0,0 +1,2620 @@ +<html> +<head> +<title>NX Graphics Subsystem</title> +<meta name="author" content="Gregory Nutt"> +</head> + +<body background="backgd.gif"> +<hr><hr> +<table width ="100%"> + <tr align="center" bgcolor="#e4e4e4"> + <td> + <h1><big><font color="#3c34ec"> + <i>NX Graphics Subsystem</i> + </font></big></h1> + <p>Last Updated: December 5, 2008</p> + </td> + </tr> +</table> +<hr><hr> + +<table width ="100%"> + <tr bgcolor="#e4e4e4"> + <td> + <h1>Table of Contents</h1> + </td> + </tr> +</table> + +<table width="100%"> +<tr> + <td align="left" valign="top"> + <p> + <big><b>1.0</b> <a href="#Introduction">Introduction</a></big> + </p> + <ul> + <p> + <i><b>1.1</b> <a href="#Overview">Overview</a><br></i> + <i><b>1.2</b> <a href="#Objectives">Objectives</a></i><br> + <i><b>1.3</b> <a href="#Organization">Organization</a></i> + </p> + <p> + <ul> + <i>1.3.1 <a href="#nxgl1">NX Graphics Library (<code>NXGL</code>)</a></i><br> + <i>1.3.2 <a href="#nx1">NX (NXSU and NXMU)</a></i><br> + <i>1.3.3 <a href="#nxtk1">NX Tool Kit (<code>NXTK</code>)</a></i><br> + <i>1.3.4 <a href="#nxfonts1">NX Fonts Support (<code>NXFONTS</code>)</a></i><br> + <i>1.3.5 <a href="#nxwidgets1">NX Widgets (<code>NXWIDGETS</code>)</a></i> + </ul> + </p> + </ul> + <p> + <big><b>2.0</b> <a href="#nxapis">NX User APIs</a></big> + </p> + <ul> + <p> + <i><b>2.1</b> <a href="#nxheaders">NX Header Files</a></i><br> + <i><b>2.2</b> <a href="#nxgl2">NX Graphics Library (<code>NXGL</code>)</a></i> + </p> + <p> + <ul> + <i>2.2.1 <a href="#nxgltypes">NXGL Types</a></i><br> + <i>2.2.1 <a href="#nxglrgb2yuv"><code>nxgl_rgb2yuv()</code></a></i><br> + <i>2.2.2 <a href="#nxglyuv2rgb"><code>nxgl_yuv2rgb()</code></a></i><br> + <i>2.2.3 <a href="#nxglrectcopy"><code>nxgl_rectcopy()</code></a></i><br> + <i>2.2.4 <a href="#nxglrectoffset"><code>nxgl_rectoffset()</code></a></i><br> + <i>2.2.5 <a href="#nxglvectoradd"><code>nxgl_vectoradd()</code></a></i><br> + <i>2.2.6 <a href="#nxglvectorsubtract"><code>nxgl_vectorsubtract()</code></a></i><br> + <i>2.2.7 <a href="#nxglrectintersect"><code>nxgl_rectintersect()</code></a></i><br> + <i>2.2.8 <a href="#nxglrectunion"><code>nxgl_rectunion()</code></a></i><br> + <i>2.2.9 <a href="#nxglnonintersecting"><code>nxgl_nonintersecting()</code></a></i><br> + <i>2.2.10 <a href="#nxglrectoverlap"><code>nxgl_rectoverlap()</code></a></i><br> + <i>2.2.11 <a href="#nxglrectinside"><code>nxgl_rectinside()</code></a></i><br> + <i>2.2.12 <a href="#nxglrectsize"><code>nxgl_rectsize()</code></a></i><br> + <i>2.2.13 <a href="#nxglnullrect"><code>nxgl_nullrect()</code></a></i><br> + <i>2.2.14 <a href="#nxglrunoffset"><code>nxgl_runoffset()</code></a></i><br> + <i>2.2.15 <a href="#nxglruncopy"><code>nxgl_runcopy()</code></a></i><br> + <i>2.2.16 <a href="#nxgltrapoffset"><code>nxgl_trapoffset()</code></a></i><br> + <i>2.2.17 <a href="#nxgltrapcopy"><code>nxgl_trapcopy()</code></a></i><br> + <i>2.2.18 <a href="#nxglcolorcopy"><code>nxgl_colorcopy</code></a></i> + </ul> + </p> + <p> + <i><b>2.3</b> <a href="#nx2">NX</a></i> + </p> + <p> + <ul> + <i>2.3.1 <a href="#nxppdefs">Pre-Processor Definitions</a></i><br> + <i>2.3.2 <a href="#nxtypes">NX Types</a></i><br> + <i>2.3.3 <a href="#nxtypes">NX Server Callbacks</a></i> + <p> + <ul> + <i>2.3.3.1 <a href="#nxcbredraw"><code>redraw()</code></a></i><br> + <i>2.3.3.2 <a href="#nxcbposition"><code>position()</code></a></i><br> + <i>2.3.3.3 <a href="#nxcbmousein"><code>mousein()</code></a></i><br> + <i>2.3.3.4 <a href="#nxcbkbdin"><code>kbdin()</code></a></i> + </ul> + <p> + <i>2.3.4 <a href="#nxruninstance"><code>nx_runinstance()</code> (and <code>nx_run()<code> macro)</a></i><br> + <i>2.3.5 <a href="#nxconnectinstance"><code>nx_connectinstance()</code> (and <code>nx_connect()</code> macro)</a></i><br> + <i>2.3.6 <a href="#nxopen"><code>nx_open()</code></a></i><br> + <i>2.3.7 <a href="#nxdisconnect"><code>nx_disconnect()</code></a></i><br> + <i>2.3.8 <a href="#nxclose"><code>nx_close()</code></a></i><br> + <i>2.3.9 <a href="#nxeventhandler"><code>nx_eventhandler()</code></a></i><br> + <i>2.3.10 <a href="#nxeventnotify"><code>nx_eventnotify()</code></a></i><br> + <i>2.3.11 <a href="#nxopenwindow"><code>nx_openwindow()</code></a></i><br> + <i>2.3.12 <a href="#nxclosewindow"><code>nx_closewindow()</code></a></i><br> + <i>2.3.13 <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a></i><br> + <i>2.3.14 <a href="#nxreleasebkgd"><code>nx_releasebkgd()</code></a></i><br> + <i>2.3.15 <a href="#nxgetposition"><code>nx_getposition()</code></a></i><br> + <i>2.3.16 <a href="#nxsetposition"><code>nx_setposition()</code></a></i><br> + <i>2.3.17 <a href="#nxsetsize"><code>nx_setsize()</code></a></i><br> + <i>2.3.18 <a href="#nxraise"><code>nx_raise()</code></a></i><br> + <i>2.3.19 <a href="#nxlower"><code>nx_lower()</code></a></i><br> + <i>2.3.20 <a href="#nxfill"><code>nx_fill()</code></a></i><br> + <i>2.3.21 <a href="#nxfilltrapezoid"><code>nx_filltrapezoid()</code></a></i><br> + <i>2.3.22 <a href="#nxglrgb2yuv"><code>nx_setbgcolor()</code></a></i><br> + <i>2.3.23 <a href="#nxmove"><code>nx_move()</code></a></i><br> + <i>2.3.24 <a href="#nxbitmap"><code>nx_bitmap()</code></a></i><br> + <i>2.3.25 <a href="#nxkbdin"><code>nx_kbdin()</code></a></i><br> + <i>2.3.26 <a href="#nxmousein"><code>nx_mousein()</code></a></i><br> + </ul> + </p> + </td> + <td align="left" valign="top"> + <p> + <i><b>2.4</b> <a href="#nxtk2">NX Tool Kit (<code>NXTK</code>)</a></i> + </p> + <p> + <ul> + <i>2.4.1 <a href="#nxtktypes"><code>NXTK Types()</code></a></i><br> + <i>2.4.2 <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a></i><br> + <i>2.4.3 <a href="#nxtkclosewindow"><code>nxtk_closewindow()</code></a></i><br> + <i>2.4.4 <a href="#nxtkgetposition"><code>nxtk_getposition()</code></a></i><br> + <i>2.4.5 <a href="#nxtksetposition"><code>nxtk_setposition()</code></a></i><br> + <i>2.4.6 <a href="#nxtksetsize"><code>nxtk_setsize()</code></a></i><br> + <i>2.4.7 <a href="#nxtkraise"><code>nxtk_raise()</code></a></i><br> + <i>2.4.8 <a href="#nxtklower"><code>nxtk_lower()</code></a></i><br> + <i>2.4.9 <a href="#nxtkfillwindow"><code>nxtk_fillwindow()</code></a></i><br> + <i>2.4.10 <a href="#nxtkfilltrapwindow"><code>nxtk_filltrapwindow()</code></a></i><br> + <i>2.4.11 <a href="#nxtkmovewindow"><code>nxtk_movewindow()</code></a></i><br> + <i>2.4.12 <a href="#nxtkbitmapwindow"><code>nxtk_bitmapwindow()</code></a></i><br> + <i>2.4.13 <a href="#nxtkopentoolbar"><code>nxtk_opentoolbar()</code></a></i><br> + <i>2.4.14 <a href="#nxtkclosetoolbar"><code>nxtk_closetoolbar()</code></a></i><br> + <i>2.4.15 <a href="#nxtkfilltoolbar"><code>nxtk_filltoolbar()</code></a></i><br> + <i>2.4.16 <a href="#nxtkfilltraptoolbar"><code>nxtk_filltraptoolbar()</code></a></i><br> + <i>2.4.17 <a href="#nxtkmovetoolbar"><code>nxtk_movetoolbar()</code></a></i><br> + <i>2.4.18 <a href="#nxtkbitmaptoolbar"><code>nxtk_bitmaptoolbar()</code></a></i> + </ul> + </p> + <p> + <i><b>2.5</b> <a href="#nxfonts2">NX Fonts Support (<code>NXFONTS</code>)</a></i><br> + </p> + <p> + <ul> + <i>2.5.1 <a href="#nxfontstypes"><code>NXFONTS Types()</code></a></i><br> + <i>2.5.2 <a href="#nxfgetfontset"><code>nxf_getfontset()</code></a></i><br> + <i>2.5.3 <a href="#nxfgetbitmap"><code>nxf_getbitmap()</code></a></i><br> + <i>2.5.4 <a href="#nxfconvertbpp"><code>nxf_convert_*bpp()</code></a></i> + </ul> + </p> + </ul> + <p> + <big><b>Appendix A</b> <a href="#grapicsdirs"><code>graphics/</code> Directory Structure</a></big><br> + <big><b>Appendix B</b> <a href="#nxconfigs">NX Configuration Options</a></big> + </p> + <p> + <ul> + <i><b>B.1</b> <a href="#nxgenconfig">General Configuration Settings</a></i><br> + <i><b>B.2</b> <a href="#nxglconfig">NXGL Configuration Settings</a></i><br> + <i><b>B.3</b> <a href="#nxconfig">NX Configuration Settings</a></i><br> + <i><b>B.4</b> <a href="#nxmuconfig">NX Multi-User (Only) Configuration Settings</a></i><br> + <i><b>B.5</b> <a href="#nxtkconfig">NXTK Configuration Settings</a></i><br> + <i><b>B.6</b> <a href="#nxfpmtsconfig">NXFONTS Configuration Settings</a></i> + </ul> + </p> + <p> + <big><b>Appendix C</b> <a href="#testcoverage">NX Test Coverage</a></big> + </p> + </td> + </tr> +</table> + +<table width ="100%"> + <tr bgcolor="#e4e4e4"> + <td> + <h1>1.0 <a name="Introduction">Introduction</a></h1> + </td> + </tr> +</table> + +<h2>1.1 <a name="Overview">Overview</a></h2> +<p> + 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. +</p> + +<center><table width="480"> + <tr> + <td><a name="screenshot"><img src="NuttXScreenShot.jpg"></a></td> + </tr> + <tr> + <td><small>Figure 1. + This sceen shot shows the final frame for the NuttX example at <code>examples/nx</code> + 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. + </small> + </tr> +</table></center> + + +<h2>1.2 <a name="Objectives">Objectives</a></h2> + +<p> + 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: +</p> +<ul> + <li><b>Virtual Vertical Graphics Space</b>. + Windows that reside in a virtual, <i>vertical</i> space so that it makes + sense to talk about one window being on top of another and obcuring the + window below it. + </li> + <li><b>Client/Server Model</b>. + A standard client server/model was adopted. NX may be considered a server + and other logic that presents the windows are NX clients. + </li> + <li><b>Single- and Multi-User Support</b>. + NX includes <i>front-end</i> logic to either a simple single-thread/single-user + architecture or a separate NX server thread that can serve multiple NX client threads. + In the single-user case, the NX <i>server</i> is simply a set of library + calls; in the multi-user case, NX is a server thread/daemon the serializes + graphics operations from multiple clients. + Other some unique start-up/connection logic, the APIs supported by the single-user + and multi-user front-ends are identical. + Providing both front-ends is consistent with the NuttX commitment to scalability. + </li> + <li><b>Minimal Graphics Toolset</b>. + The actual implementation of the graphics operations is performed by common, + <i>back-end</i> logic. This back-end supports only a primitive set of graphic + and rendering operations. + </li> + <li><b>Framebuffer Device Interface</b>. + NX supports any graphics device using the NuttX framebuffer <i>driver</i> + interface. + (However, the dependency of NX on framebuffer drivers is minimal and the + logic could be extended to other interfaces -- such as a serial LCD -- with + some minimal effort). + <li><b>Transparent to NX Client</b>. + The window client on "sees" the sub-window that is operates in + and does not need to be concerned with the virtual, vertical space (other + that to respond to <i>redraw</i> requests from NX when needed). + </li> + <li><b>Framed Windows and Toolbars</b>. + NX also adds the capability to support windows with frames and toolbars on + top of the basic windowing support. + These are windows such as those shown in the + <a href="#screenshot">screenshot</a> above. + These framed windows sub-divide one one window into three relatively independent + subwindows: A frame, the contained window and an (optional) toolbar window. + </li> + <li><b>Mouse Support</b>. + NX provides support for a mouse or other X/Y pointing devices. + APIs are provided to allow external devices to give X/Y position information + and mouse button presses to NX. + NX will then provide the mouse input to the relevant window clients via callbacks. + Client windows only receive the mouse input callback if the mouse is positioned over a visible + portion of the client window; X/Y position is provided to the client in the relative + coordinate system of the client window. + </li> + <li><b>Keyboard input</b>. + NX also supports keyboard/keypad devices. + APIs are provided to allow external devices to give keypad information to NX. + NX will then provide the mouse input to the top window on the display (the window + that has the <i>focus</i>) via a callback function. + </li> +</ul> + +<h2>1.3 <a name="Organization">Organization</a></h2> + +<p> + 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 + <a href="#grapicsdirs">Appendix B</a> of this document. + The logic modules are discussed in the following sub-paragraphs. +</p> + +<p> + <center><img src="NXOrganization.gif" width="60%"></center> +</p> + +<h3>1.3.1 <a name="nxgl1">NX Graphics Library (<code>NXGL</code>)</a></h3> + +<p> + NXGLIB is a standalone library that contains low-level graphics utilities and + direct framebuffer rendering logic. NX is built on top NXGLIB. +</p> + +<h3>1.3.2 <a name="nx1">NX (<code>NXSU</code> and <code>NXMU</code>)</a></h3> + +<p> + 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 <code>include/nuttx/nx.h</code> and, hence, + are interchangable<sup>1</sup>. + NX can be used without NXWIDGETS and without NXTOOLKIT for raw window displays. +</p> + +<p> + <sup>1</sup><small>NXMU 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.</small> +</p> + +<p><b>NXNULL?</b> + At one time, I also envisoned a <i>NULL</i> front-end that did not support windowing + at all but, rather, simply provided the entire framebuffer 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. +</p> +<p> + However, the same end result can be obtained by using the + <a href="nxrequestbkgd"><code>nx_requestbkgd()</code></a> 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. +</p> + +<h3>1.3.3 <a name="nxtk1">NX Tool Kit (<code>NXTK</code>)</a></h3> + +<p> + 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. +</p> + +<h3>1.3.4 <a name="nxfonts1">NX Fonts Support (<code>NXFONTS</code>)</a></h3> + +<p> + 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. +</p> + +<h3>1.3.5 <a name="nxwidgets1">NX Widgets (<code>NXWIDGETS</code>)</a></h3> + +<p> + I had originally planned a high level, C++, object-oriented library for + object-oriented access to graphics <i>widgets</i>. + 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. +</p> +<p> + 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. +</p> + +<table width ="100%"> + <tr bgcolor="#e4e4e4"> + <td> + <h1>2.0 <a name="nxapis">NX User APIs</a></h1> + </td> + </tr> +</table> + +<h2>2.1 <a name="nxheaders">NX Header Files</a></h2> + +<ul><dl> + <dt><code>include/nuttx/nxglib.h + <dd>Describes the NXGLIB C interfaces + <dt><code>include/nuttx/nx.h + <dd>Describes the NX C interfaces + <dt><code>include/nutt/nxtk.h + <dd>Describe the NXTOOLKIT C interfaces + <dt><code>include/nutt/nxfont.h + <dd>Describe sthe NXFONT C interfaces + <dt><code>include/nuttx/nxwidgets.h + <dd>Will describe the NXWIDGETS classes (no longer planned) +</dl></ul> + +<h2>2.2 <a name="nxgl2">NX Graphics Library (<code>NXGL</code>)</a></h2> + +<p> + 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 <code>include/nuttx/nxglib.h</code> for the full set of APIs; + those APIs might be of interest if you are rendering directly into + framebuffer memory. +</p> + +<h3>2.2.1 <a name="nxgltypes">NXGL Types</a></h3> + +<p> + <code>nxgl_mxpixel_t</code>. + Holds one device pixel. + NXGLIB will select the smallest size for the <code>nxgl_mxpixel_t</code> + that just contains the pixel: <code>byte</code> if 16, 24, and 32 resolution + support is disabled, <code>uint16</code> if 24, and 32 resolution + support is disabled, or <code>uint32</code>. +</p> + +<p> + <code>nxgl_coord_t</b> + 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: +</p> +<ul><pre> +typedef sint16 nxgl_coord_t; +</pre></ul> + +<p> + <code>struct nxgl_point_s</code>. Describes a point on the display: +</p> +<ul><pre> +struct nxgl_point_s +{ + nxgl_coord_t x; /* X position, range: 0 to screen width - 1 */ + nxgl_coord_t y; /* Y position, range: 0 to screen height - 1 */ +}; +</pre></ul> + +<p> + <code>struct nxgl_size_s</code>. Describes the size of a rectangular region. +</p> +<ul><pre> +struct nxgl_size_s +{ + nxgl_coord_t w; /* Width in pixels */ + nxgl_coord_t h; /* Height in rows */ +}; +</pre></ul> + +<p> + <code>struct nxgl_rect_s</code>. Describes a positioned rectangle on the display. +</p> +<ul><pre> +struct nxgl_rect_s +{ + struct nxgl_point_s pt1; /* Upper, left-hand corner */ + struct nxgl_point_s pt2; /* Lower, right-hand corner */ +}; +</pre></ul> + +<p> + <code>struct nxgl_run_s</code>. + 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 +</p> +<ul><pre> +struct nxgl_run_s +{ + b16_t x1; /* Left X position, range: 0 to x2 */ + b16_t x2; /* Right X position, range: x1 to screen width - 1 */ + nxgl_coord_t y; /* Top Y position, range: 0 to screen height - 1 */ +}; +</pre></ul> + +<p> + <code>struct nxgl_trapezoid_s</code>. + Describes a horizontal trapezoid on the display in terms the run at the + top of the trapezoid and the run at the bottom +</p> +<ul><pre> +struct nxgl_trapezoid_s +{ + struct nxgl_run_s top; /* Top run */ + struct nxgl_run_s bot; /* bottom run */ +}; +</pre></ul> + +<h3>2.2.1 <a name="nxglrgb2yuv"><code>nxgl_rgb2yuv()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +void nxgl_rgb2yuv(ubyte r, ubyte g, ubyte b, ubyte *y, ubyte *u, ubyte *v); +</pre></ul> +<p> + <b>Description:</b> + Convert 8-bit RGB triplet to 8-bit YUV triplet. +</p> + +<h3>2.2.2 <a name="nxglyuv2rgb"><code>nxgl_yuv2rgb()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +void nxgl_yuv2rgb(ubyte y, ubyte u, ubyte v, ubyte *r, ubyte *g, ubyte *b); +</pre></ul> +<p> + <b>Description:</b> + Convert 8-bit RGB triplet to 8-bit YUV triplet. +</p> + +<h3>2.2.3 <a name="nxglrectcopy"><code>nxgl_rectcopy()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +void nxgl_rectcopy(FAR struct nxgl_rect_s *dest, + FAR const struct nxgl_rect_s *src); +</pre></ul> +<p> + <b>Description:</b> + This is essentially <code>memcpy()</code>for rectangles. We don't do structure + assignments because some compilers are not good at that. +</p> + +<h3>2.2.4 <a name="nxglrectoffset"><code>nxgl_rectoffset()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +void nxgl_rectoffset(FAR struct nxgl_rect_s *dest, + FAR const struct nxgl_rect_s *src, + nxgl_coord_t dx, nxgl_coord_t dy); +</pre></ul> +<p> + <b>Description:</b> + Offset the rectangle position by the specified dx, dy values. +</p> + +<h3>2.2.5 <a name="nxglvectoradd"><code>nxgl_vectoradd()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +void nxgl_vectoradd(FAR struct nxgl_point_s *dest, + FAR const struct nxgl_point_s *v1, + FAR const struct nxgl_point_s *v2); +</pre></ul> +<p> + <b>Description:</b> + Add two 2x1 vectors and save the result to a third. +</p> + +<h3>2.2.6 <a name="nxglvectorsubtract"><code>nxgl_vectorsubtract()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +void nxgl_vectsubtract(FAR struct nxgl_point_s *dest, + FAR const struct nxgl_point_s *v1, + FAR const struct nxgl_point_s *v2); +</pre></ul> +<p> + <b>Description:</b> + Add subtract vector <code>v2</code> from vector <code>v1</code> and return the result in vector dest. +</p> + +<h3>2.2.7 <a name="nxglrectintersect"><code>nxgl_rectintersect()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +void nxgl_rectintersect(FAR struct nxgl_rect_s *dest, + FAR const struct nxgl_rect_s *src1, + FAR const struct nxgl_rect_s *src2); +</pre></ul> +<p> + <b>Description:</b> + Return the rectangle representing the intersection of the two rectangles. +</p> + +<h3>2.2.8 <a name="nxglrectunion"><code>nxgl_rectunion()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +void nxgl_rectunion(FAR struct nxgl_rect_s *dest, + FAR const struct nxgl_rect_s *src1, + FAR const struct nxgl_rect_s *src2); +</pre></ul> +<p> + <b>Description:</b> + Given two rectanges, <code>src1</code> and <code>src2</code>, return the larger rectangle that + contains both, <code>dest</code>. +</p> + +<h3>2.2.9 <a name="nxglnonintersecting"><code>nxgl_nonintersecting()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +nxgl_nonintersecting(FAR struct nxgl_rect_s result[4], + FAR const struct nxgl_rect_s *rect1, + FAR const struct nxgl_rect_s *rect2); +</pre></ul> +<p> + <b>Description:</b> + Return the regions of rectangle <code>rect1</code> that do not intersect with + <code>rect2</code>. This will four rectangles, some of which may be + degenerate (and can be picked off with <a href="#nxglnullrect"><code>nxgl_nullrect()<code></a>). +</p> + +<h3>2.2.10 <a name="nxglrectoverlap"><code>nxgl_rectoverlap()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +boolean nxgl_rectoverlap(FAR struct nxgl_rect_s *rect1, + FAR struct nxgl_rect_s *rect2); +</pre></ul> +<p> + <b>Description:</b> + Return TRUE if the two rectangles overlap. +</p> + +<h3>2.2.11 <a name="nxglrectinside"><code>nxgl_rectinside()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +boolean nxgl_rectinside(FAR const struct nxgl_rect_s *rect, + FAR const struct nxgl_point_s *pt); +</pre></ul> +<p> + <b>Description:</b> + Return TRUE if the point <code>pt</code> lies within <code>rect</code>. +</p> + +<h3>2.2.12 <a name="nxglrectsize"><code>nxgl_rectsize()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +void nxgl_rectsize(FAR struct nxgl_size_s *size, + FAR const struct nxgl_rect_s *rect); +</pre></ul> +<p> + <b>Description:</b> + Return the size of the specified rectangle. +</p> + +<h3>2.2.13 <a name="nxglnullrect"><code>nxgl_nullrect()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +boolean nxgl_nullrect(FAR const struct nxgl_rect_s *rect); +</pre></ul> +<p> + <b>Description:</b> + Return TRUE if the area of the retangle is <= 0. +</p> + +<h3>2.2.14 <a name="nxglrunoffset"><code>nxgl_runoffset()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +void nxgl_runoffset(FAR struct nxgl_run_s *dest, + FAR const struct nxgl_run_s *src, + nxgl_coord_t dx, nxgl_coord_t dy); +</pre></ul> +<p> + <b>Description:</b> + Offset the run position by the specified <code>dx</code>, <code>dy</code> values. +</p> + +<h3>2.2.15 <a name="nxglruncopy"><code>nxgl_runcopy()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +void nxgl_runcopy(FAR struct nxgl_run_s *dest, + FAR const struct nxgl_run_s *src); +</pre></ul> +<p> + <b>Description:</b> + This is essentially <code>memcpy()</code>for runs. We don't do structure assignments + because some compilers are not good at that. +</p> + +<h3>2.2.16 <a name="nxgltrapoffset"><code>nxgl_trapoffset()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +void nxgl_trapoffset(FAR struct nxgl_trapezoid_s *dest, + FAR const struct nxgl_trapezoid_s *src, + nxgl_coord_t dx, nxgl_coord_t dy); +</pre></ul> +<p> + <b>Description:</b> + Offset the trapezoid position by the specified <code>dx</code>, <code>dy</code> values. +</p> + +<h3>2.2.1 <a name="nxgltrapcopy"><code>nxgl_trapcopy()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +void nxgl_trapcopy(FAR struct nxgl_trapezoid_s *dest, + FAR const struct nxgl_trapezoid_s *src); +</pre></ul> +<p> + <b>Description:</b> + This is essentially <code>memcpy()</code>for trapezoids. We don't do structure + assignments because some compilers are not good at that. +</p> + +<h3>2.2.1 <a name="nxglcolorcopy"><code>nxgl_colorcopy</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +nxgl_colorcopy(nxgl_mxpixel_t dest[CONFIG_NX_NPLANES], + const nxgl_mxpixel_t src[CONFIG_NX_NPLANES]); +</pre></ul> +<p> + <b>Description:</b> + This is essentially <code>memcpy()</code>for colors. This does very little for us + other than hide all of the conditional compilation for planar colors + in one place. +</p> + +<h2>2.3 <a name="nx2">NX</a></h2> + +<h3>2.3.1 <a name="nxppdefs">Pre-Processor Definitions</a></h3> + +<p> + The default server message queue name used by the + <a href="#nxruninstance"><code>nx_run()</code></a> macro: +</p> +<ul><pre> +#define NX_DEFAULT_SERVER_MQNAME "/dev/nxs" +</pre></ul> + +<p> + Mouse button bits: +</p> +<ul><pre> +#define NX_MOUSE_NOBUTTONS 0x00 +#define NX_MOUSE_LEFTBUTTON 0x01 +#define NX_MOUSE_CENTERBUTTON 0x02 +#define NX_MOUSE_RIGHTBUTTON 0x04 +</pre></ul> + +<h3>2.3.2 <a name="nxtypes">NX Types</a></h3> + +<p> + The interface to the NX server is managed using a opaque handle: +</p> +<ul><pre> +typedef FAR void *NXHANDLE; +</pre></ul> + +<p> + The interface to a specific window is managed using an opaque handle: +</p> +<ul><pre> +typedef FAR void *NXWINDOW; +</pre></ul> + +<p> + These define callbacks that must be provided to + <a href="#nxopenwindow"><code>nx_openwindow()</code></a>. + In the multi-user model, these callbacks will be invoked as part of the + processing performed by + <a href="#nxeventhandler"><code>nx_eventhandler()</code></a>. +</p> +<ul><pre> +struct nx_callback_s +{ + void (*redraw)(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect, + boolean more, FAR void *arg); + void (*position)(NXWINDOW hwnd, FAR const struct nxgl_size_s *size, + FAR const struct nxgl_point_s *pos, + FAR const struct nxgl_rect_s *bounds, + FAR void *arg); +#ifdef CONFIG_NX_MOUSE + void (*mousein)(NXWINDOW hwnd, FAR const struct nxgl_point_s *pos, + ubyte buttons, FAR void *arg); +#endif +#ifdef CONFIG_NX_KBD + void (*kbdin)(NXWINDOW hwnd, ubyte nch, FAR const ubyte *ch, FAR void *arg); +#endif +}; +</pre></ul> + +<h3>2.3.3 <a name="nxtypes">NX Server Callbacks</a></h3> + +<h4>2.3.3.1 <a name="nxcbredraw"><code>redraw()</code></a></h4> +<p><b>Callback Function Prototype:</b></p> +<ul><pre> +void redraw(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect, + boolean more, FAR void *arg); +</pre></ul> +<p> + <b>Description:</b> + NX requests that the client re-draw the portion of the window within + with rectangle. +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>hwnd</code> + <dd>The handle created by <a href="#nxopenwindow"><code>nx_openwindow()</code></a> + or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a> + <dt><code>rect</code> + <dd>The rectangle that needs to be re-drawn (in window relative coordinates) + <dt><code>more</code> + <dd>TRUE: More re-draw requests will follow + <dt><code>arg</code> + <dd>User provided argument (see <a href="#nxopenwindow"><code>nx_openwindow()</code></a>) + </dl></ul> +</p> +<p> + <b>Returned Value:</b> None +</p> + +<h4>2.3.3.2 <a name="nxcbposition"><code>position()</code></a></h4> +<p><b>Callback Function Prototype:</b></p> +<ul><pre> +void position(NXWINDOW hwnd, FAR const struct nxgl_size_s *size, + FAR const struct nxgl_point_s *pos, + FAR const struct nxgl_rect_s *bounds, + FAR void *arg); +</pre></ul> +<p> + <b>Description:</b> + The size or position of the window has changed (or the window was + just created with zero size. +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>hwnd</code> + <dd>The handle created by <a href="#nxopenwindow"><code>nx_openwindow()</code></a> + or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a> + <dt><code>size</code> + <dd>The size of the window + <dt><code>pos</code> + <dd>The position of the upper left hand corner of the window on + the overall display + <dt><code>bounds</code> + <dd>The bounding rectangle that the describes the entire display + <dt><code>arg</code> + <dd>User provided argument (see <a href="#nxopenwindow"><code>nx_openwindow()</code></a>) + </dl></ul> +</p> +<p> + <b>Returned Value:</b> None +</p> + +<h4>2.3.3.3 <a name="nxcbmousein"><code>mousein()</code></a></h4> +<p><b>Callback Function Prototype:</b></p> +<ul><pre> +#ifdef CONFIG_NX_MOUSE +void mousein(NXWINDOW hwnd, FAR const struct nxgl_point_s *pos, + ubyte buttons, FAR void *arg); +#endif +</pre></ul> +<p> + <b>Description:</b> + New mouse data is available for the window +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>hwnd</code> + <dd>The handle created by <a href="#nxopenwindow"><code>nx_openwindow()</code></a> + or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a> + <dt><code>pos</code> + <dd>The (x,y) position of the mouse + <dt><code>buttons</code> + <dd>See <code>NX_MOUSE_*</code> definitions + <dt><code>arg</code> + <dd>User provided argument (see <a href="#nxopenwindow"><code>nx_openwindow()</code></a>) + </dl></ul> +</p> +<p> + <b>Returned Value:</b> None +</p> + +<h4>2.3.3.4 <a name="nxcbkbdin"><code>kbdin()</code></a></h4> +<p><b>Callback Function Prototype:</b></p> +<ul><pre> +#ifdef CONFIG_NX_KBD +void (*kbdin)(NXWINDOW hwnd, ubyte nch, FAR const ubyte *ch, FAR void *arg); +#endif +</pre></ul> +<p> + <b>Description:</b> + New keyboard/keypad data is available for the window. +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>hwnd</code> + <dd>The handle created by <a href="#nxopenwindow"><code>nx_openwindow()</code></a> + or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a> + <dt><code>nch</code> + <dd>The number of characters that are available in ch[] + <dt><code>ch</code> + <dd>The array of characters + <dt><code>arg</code> + <dd>User provided argument (see <a href="#nxopenwindow"><code>nx_openwindow()</code></a>) + </dl></ul> +</p> +<p> + <b>Returned Value:</b> NOne +</p> + +<h3>2.3.4 <a name="nxruninstance"><code>nx_runinstance()</code> (and <code>nx_run()<code> macro)</a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +#ifdef CONFIG_NX_MULTIUSER +int nx_runinstance(FAR const char *mqname, FAR struct fb_vtable_s *fb); +#define nx_run(fb) nx_runinstance(NX_DEFAULT_SERVER_MQNAME, fb) +#endif +</pre></ul> +<p> + <b>Description:</b> + This is the server entry point. It does not return; the calling thread + is dedicated to supporting NX server. +</p> +<p> + NOTE that multiple instances of the NX server may run at the same time, + with different callback and message queue names. <code>nx_run()</code> is simply + a macro that can be used when only one server instance is required. In + that case, a default server name is used. +</p> +<p> + Multiple user mode only! +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>mqname</code> + <dd> + - The name for the server incoming message queue + <dt><code>fb</code> + <dd>Vtable "object" of the framebuffer "driver" to use + </dl></ul> +</p> +<p> + <b>Returned Value:</b> + This function usually does not return. If it does return, it will + return <code>ERROR</code> and <code>errno</code> will be set appropriately. +</p> + +<h3>2.3.5 <a name="nxconnectinstance"><code>nx_connectinstance()</code> (and <code>nx_connect()</code> macro)</a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +#ifdef CONFIG_NX_MULTIUSER +NXHANDLE nx_connectinstance(FAR const char *svrmqname); +#define nx_connect(cb) nx_connectinstance(NX_DEFAULT_SERVER_MQNAME) +#endif +</pre></ul> +<p> + <b>Description:</b> + 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. +</p> +<p> + NOTES: +</p> +<ul> + <li> + This function returns before the connection is fully instantiated. + it is necessary to wait for the connection event before using the + returned handle. + </li> + <li> + Multiple instances of the NX server may run at the same time, + each with different message queue names. + </li> + <li> + <code>nx_connect()</code> is simply a macro that can be used when only one + server instance is required. In that case, a default server name + is used. + </li> +</ul> +<p> + Multiple user mode only! +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>svrmqname</code> + <dd>The name for the server incoming message queue + </dl></ul> +</p> +<p> + <b>Returned Value:</b> +</p> +<ul> + Success: A non-NULL handle used with subsequent NX accesses<br> + Failure: NULL is returned and <code>errno</code> is set appropriately. +</ul> + +<h3>2.3.6 <a name="nxopen"><code>nx_open()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +#ifndef CONFIG_NX_MULTIUSER +NXHANDLE nx_open(FAR struct fb_vtable_s *fb); +#endif +</pre></ul> +<p> + <b>Description:</b> + Create, initialize and return an NX handle for use in subsequent + NX API calls. <code>nx_open()</code> is the single user equivalent of + <a href="#nxconnectinstance"><code>nx_connect()</code></a> plus + <a href="#nxruninstance"><code>nx_run()</code></a>. +</p> +<p> + Single user mode only! +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>fb</code> + <dd>Vtable "object" of the framebuffer "driver" to use + <dt><code>cb</code> + <dd>Callbacks used to process received NX server messages + </dl></ul> +</p> +<p> + <b>Returned Value:</b> +</p> +<ul> + Success: A non-NULL handle used with subsequent NX accesses<br> + Failure: NULL is returned and <code>errno</code> is set appropriately. +</ul> + +<h3>2.3.7 <a name="nxdisconnect"><code>nx_disconnect()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +#ifdef CONFIG_NX_MULTIUSER +void nx_disconnect(NXHANDLE handle); +#endif +</pre></ul> +<p> + <b>Description:</b> + Disconnect a client from the NX server and/or free resources reserved + by <a href="#nxconnectinstance"><code>nx_connect()</code>/<code>nx_connectinstance()</code></a>. + <code>nx_disconnect()</code> is muliti-user equivalent of + <a href="#nxclose"><code>nx_close()</code></a>. +</p> +<p> + Multiple user mode only! +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>handle</code> + <dd>The handle returned by <a href="#nxconnectinstance"><code>nx_connect()</code></a>. + </dl></ul> +</p> +<p> + <b>Returned Value:</b> None. +</p> + +<h3>2.3.8 <a name="nxclose"><code>nx_close()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +#ifndef CONFIG_NX_MULTIUSER +void nx_close(NXHANDLE handle); +#endif +</pre></ul> +<p> + <b>Description:</b> + Close the single user NX interface. nx_close is single-user equivalent + of <a href="#nxdisconnect"><code>nx_disconnect()</code></a>. +</p> +<p> + Single user mode only! +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>handle</code> + <dd>The handle returned by <a href="#nxopen"><code>nx_open()</code></a>. + </dl></ul> +</p> +<p> + <b>Returned Value:</b> None +</p> + +<h3>2.3.9 <a name="nxeventhandler"><code>nx_eventhandler()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +#ifdef CONFIG_NX_MULTIUSER +int nx_eventhandler(NXHANDLE handle); +#else +# define nx_eventhandler(handle) (OK) +#endif +</pre></ul> +<p> + <b>Description:</b> + The client code must call this function periodically to process + incoming messages from the server. If <code>CONFIG_NX_BLOCKING</code> is defined, + then this function not return until a server message is received. +</p> +<p> + When <code>CONFIG_NX_BLOCKING</code> 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. + <a href="#nxeventnotify"><code>nx_eventnotify()</code></a> + may be called to get a signal event whenever a new incoming server + event is avaiable. +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>handle</code> + <dd>The handle returned by <a href="#nxconnectinstance"><code>nx_connect()</code></a>. + </dl></ul> +</p> +<p> + <b>Returned Value:</b> +</p> +<ul> + <li> + <code>OK</code>: No errors occurred. If <code>CONFIG_NX_BLOCKING</code> is defined, + then one or more server messages were processed. + </li> + <li> + <code>ERROR</code>: An error occurred and <code>errno</code> has been set appropriately. + Of particular interest, it will return <code>errno == EHOSTDOWN</code> when the + server is disconnected. After that event, the handle can no longer be used. + </li> +</ul> + +<h3>2.3.10 <a name="nxeventnotify"><code>nx_eventnotify()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +#if defined(CONFIG_NX_MULTIUSER) && !defined(CONFIG_DISABLE_SIGNALS) +int nx_eventnotify(NXHANDLE handle, int signo); +#else +# define nx_eventnotify(handle, signo) (OK) +#endif +</pre></ul> +<p> + <b>Description:</b> + Rather than calling <a href="#nxeventhandler"><code>nx_eventhandler()</code></a> periodically, + the client may register to receive a signal when a server event is available. + The client can then call <a href="#nxeventhandler"><code>nv_eventhandler()</code></a> only when + incoming events are available. +</p> +<p> + The underlying implementation used <code>mq_notifiy()</code> and, as a result, + the client must observe the rules for using <code>mq_notifiy()</code>: + <ul> + <li> + Only one event is signaled. Upon receipt of the signal, if the client + wishes further notifications, it must call <code>nx_eventnotify()</code> again. + </li> + <li> + The signal will only be issued when the message queue transitions from empty to + not empty. + </li> + </ul> +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>handle</code> + <dd>The handle returned by <a href="#nxconnectinstance"><code>nx_connect()</code></a>. + </dl></ul> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.3.11 <a name="nxopenwindow"><code>nx_openwindow()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +NXWINDOW nx_openwindow(NXHANDLE handle, + FAR const struct nx_callback_s *cb, + FAR void *arg); +</pre></ul> +<p> + <b>Description:</b> Create a new window. +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>handle</code> + <dd>The handle returned by <a href="#nxconnectinstance"><code>nx_connect()</code></a> + or <a href="#nxopen"><code>nx_open()</code></a>. + <dt><code>cb</code> + <dd>Callbacks used to process window events + <dt><code>arg</code> + <dd>User provided value that will be returned with NX callbacks. + </dl></ul> +</p> +<p> + <b>Returned Value:</b> +</p> +<ul> + Success: A non-NULL handle used with subsequent NX accesses<br> + Failure: NULL is returned and <code>errno</code> is set appropriately. +</ul> + +<h3>2.3.12 <a name="nxclosewindow"><code>nx_closewindow()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +int nx_closewindow(NXWINDOW hwnd); +</pre></ul> +<p> + <b>Description:</b> + Destroy a window created by <a href="#nxopenwindow"><code>nx_openwindow()</code></a> window. +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>hwnd</code> + <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a> + that identifies the window to be destroyed. + This handle must not have been one returned by + <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>. + </dl></ul> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.3.13 <a name="nxrequestbkgd"><code>nx_requestbkgd()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +int nx_requestbkgd(NXHANDLE handle, + FAR const struct nx_callback_s *cb, + FAR void *arg); +</pre></ul> +<p> + <b>Description:</b> + 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: +</p> +<ul> + <li> + If you want to implement a windowless solution. The single screen + can be used to creat a truly simple graphic environment. In this + case, you should probably also de-select <code>CONFIG_NX_MULTIUSER</code> as well. + </li> + <li> + When you want more on the background than a solid color. For + example, if you want an image in the background, or animations in the + background, or live video, etc. + </li> +</ul> +<p> + This API only requests the handle of the background window. That + handle will be returned asynchronously in a subsequent position and + redraw callbacks. +</p> +<p> + Cautions: +</p> +<ul> + <li> + The following should never be called using the background window. + They are guaranteed to cause severe crashes: + <a href="#nxsetposition"><code>nx_setposition()</code></a>, + <a href="#nxsetsize"><code>nx_setsize()</code></a>, + <a href="#nxraise"><code>nx_raise()</code></a>, or + <a href="#nxlower"><code>nx_lower()</code></a>. + </li> + <li> + Neither <code>nx_requestbkgd()</code> nor + <a href="#nxreleasebkgd"><code>nx_releasebkgd ()</code></a> should be called more than once. + Multiple instances of the background window are not supported. + </li> +</ul> +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>handle</code> + <dd>The handle returned by <a href="#nxconnectinstance"><code>nx_connect()</code></a> + or <a href="#nxopen"><code>nx_open()</code></a>. + <dt><code>cb</code> + <dd>Callbacks to use for processing background window events + <dt><code>arg</code> + <dd>User provided argument (see <a href="#nxopenwindow"><code>nx_openwindow()</code></a>) + </dl></ul> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.3.14 <a name="nxreleasebkgd"><code>nx_releasebkgd()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +int nx_releasebkgd(NXWINDOW hwnd); +</pre></ul> +<p> + <b>Description:</b> + Release the background window previously acquired using + <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a> + and return control of the background to NX. +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>handle</code> + <dd>The handle returned indirectly by + <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>. + This handle must not have been one created by + <a href="#nxopenwindow"><code>nx_openwindow()</code></a>. + </dl></ul> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.3.15 <a name="nxgetposition"><code>nx_getposition()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +int nx_getposition(NXWINDOW hwnd); +</pre></ul> +<p> + <b>Description:</b> + Request the position and size information for the selected window. The + values will be return asynchronously through the client callback function + pointer. +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>hwnd</code> + <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a> or + <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>. + </dl></ul> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.3.16 <a name="nxsetposition"><code>nx_setposition()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +int nx_setposition(NXWINDOW hwnd, FAR struct nxgl_point_s *pos); +</pre></ul> +<p> + <b>Description:</b> + Set the position and size for the selected window. +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>hwnd</code> + <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>. + This handle must not have been created by + <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>. + <dt><code>pos</code> + <dd>The new position of the window + </dl></ul> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.3.17 <a name="nxsetsize"><code>nx_setsize()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +int nx_setsize(NXWINDOW hwnd, FAR struct nxgl_size_s *size); +</pre></ul> +<p> + <b>Description:</b> Set the size of the selected window. +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>hwnd</code> + <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>. + This handle must not have been created by + <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>. + <dt><code>size</code> + <dd>The new size of the window (in pixels). + </dl></ul> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.3.18 <a name="nxraise"><code>nx_raise()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +int nx_raise(NXWINDOW hwnd); +</pre></ul> +<p> + <b>Description:</b> Bring the specified window to the top of the display. +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>hwnd</code> + <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>. + This handle must not have been created by + <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>. + <dt><code></code> + <dd> + </dl></ul> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.3.19 <a name="nxlower"><code>nx_lower()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +int nx_lower(NXWINDOW hwnd); +</pre></ul> +<p> + <b>Description:</b> Lower the specified window to the bottom of the display. +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>hwnd</code> + <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a>. + This handle must not have been created by + <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a>. + <dt><code></code> + <dd> + </dl></ul> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.3.20 <a name="nxfill"><code>nx_fill()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +int nx_fill(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect, + nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); +</pre></ul> +<p> + <b>Description:</b> + Fill the specified rectangle in the window with the specified color. +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>hwnd</code> + <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a> + or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a> + <dt><code>rect</code> + <dd>The location to be filled + <dt><code>color</code> + <dd>The color to use in the fill + </dl></ul> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.3.21 <a name="nxfilltrapezoid"><code>nx_filltrapezoid()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +int nx_filltrapezoid(NXWINDOW hwnd, FAR const struct nxgl_rect_s *clip, + FAR const struct nxgl_trapezoid_s *trap, + nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); +</pre></ul> +<p> + <b>Description:</b> + Fill the specified trapezoidal region in the window with the specified color. +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>hwnd</code> + <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a> + or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a> + <dt><code>clip</code> + <dd>Clipping rectangle relative to window (may be null) + <dt><code>trap</code> + <dd>The trapezoidal region to be filled + <dt><code>color</code> + <dd>The color to use in the fill + </dl></ul> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.3.22 <a name="nxglrgb2yuv"><code>nx_setbgcolor()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +int nx_setbgcolor(NXHANDLE handle, + nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); +</pre></ul> +<p> + <b>Description:</b> Set the color of the background. +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>handle</code> + <dd>The handle created by <a href="#nxopenwindow"><code>nx_openwindow()</code></a> + or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a> + <dt><code>color</code> + <dd>The color to use in the background + </dl></ul> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.3.23 <a name="nxmove"><code>nx_move()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +int nx_move(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect, + FAR const struct nxgl_point_s *offset); +</pre></ul> +<p> + <b>Description:</b> Move a rectangular region within the window. +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>hwnd</code> + <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a> + or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a> that specifies + the window within which the move is to be done + <dt><code>rect</code> + <dd>Describes the (source) rectangular region to move + <dt><code>offset</code> + <dd>The offset to move the region + </dl></ul> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.3.24 <a name="nxbitmap"><code>nx_bitmap()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +int nx_bitmap(NXWINDOW hwnd, FAR const struct nxgl_rect_s *dest, + FAR const void *src[CONFIG_NX_NPLANES], + FAR const struct nxgl_point_s *origin, + unsigned int stride); +</pre></ul> +<p> + <b>Description:</b> + Copy a rectangular region of a larger image into the rectangle in the + specified window. +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>hwnd</code> + <dd>The handle returned by <a href="#nxopenwindow"><code>nx_openwindow()</code></a> + or <a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a> that specifies the + window that will receive the bitmap image. + <dt><code>dest</code> + <dd> Describes the rectangular on the display that will receive the the bit map. + <dt><code>src</code> + <dd>The start of the source image. This is an array source images of size + <code>CONFIG_NX_NPLANES</code> (probably 1). + <dt><code>origin</code> + <dd>The origin of the upper, left-most corner of the full bitmap. + Both dest and origin are in window coordinates, however, the origin + may lie outside of the display. + <dt><code>stride</code> + <dd>The width of the full source image in bytes. + </dl></ul> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.3.25 <a name="nxkbdin"><code>nx_kbdin()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +#ifdef CONFIG_NX_KBD +int nx_kbdchin(NXHANDLE handle, ubyte ch); +int nx_kbdin(NXHANDLE handle, ubyte nch, FAR const ubyte *ch); +#endif +</pre></ul> +<p> + <b>Description:</b> + 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. +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.3.26 <a name="nxmousein"><code>nx_mousein()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> + +#ifdef CONFIG_NX_MOUSE +int nx_mousein(NXHANDLE handle, nxgl_coord_t x, nxgl_coord_t y, ubyte buttons); +#endif +</pre></ul> +<p> + <b>Description:</b> + 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. +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code></code> + <dd> + </dl></ul> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h2>2.4 <a name="nxtk2">NX Tool Kit (<code>NXTK</code>)</a></h2> + +<h3>2.4.1 <a name="nxtktypes"><code>NXTK Types()</code></a></h3> + +<p> + This is the handle that can be used to access the window data region. +</p> +<ul><pre> +typedef FAR void *NXTKWINDOW; +</pre></ul> + +<h3>2.4.2 <a name="nxtkopenwindow"><code>nxtk_openwindow()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> +#include <nuttx/nxtk.h> + +NXTKWINDOW nxtk_openwindow(NXHANDLE handle, + FAR const struct nx_callback_s *cb, + FAR void *arg); +</pre></ul> +<p> + <b>Description:</b> Create a new, framed window. +</p> +<p> + <b>Input Parameters:</b> + <dl> + <dt><code>handle</code> + <dd>The handle returned by <a href="#nxconnectinstance"><code>nx_connect()</code></a> + or <a href="#nxopen"><code>nx_open()</code></a>. + <dt><code>cb</code> + <dd>Callbacks used to process window events + <dt><code>arg</code> + <dd>User provided argument (see <a href="#nxopenwindow"><code>nx_openwindow()</code></a>) + </dl> +</p> +<p> + <b>Returned Value:</b> +</p> +<ul> + Success: A non-NULL handle used with subsequent NXTK window accesses<br> + Failure: NULL is returned and <code>errno</code> is set appropriately. +</ul> + +<h3>2.4.3 <a name="nxtkclosewindow"><code>nxtk_closewindow()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> +#include <nuttx/nxtk.h> + +int nxtk_closewindow(NXTKWINDOW hfwnd); +</pre></ul> +<p> + <b>Description:</b> + Close the window opened by <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>. +</p> +<p> + <b>Input Parameters:</b> + <dl> + <dt><code>hfwnd</code> + <dd>A handle previously returned by + <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>. + </dl> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.4.4 <a name="nxtkgetposition"><code>nxtk_getposition()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> +#include <nuttx/nxtk.h> + +int nxtk_getposition(NXTKWINDOW hfwnd); +</pre></ul> +<p> + <b>Description:</b> + 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. +</p> +<p> + <b>Input Parameters:</b> + <dl> + <dt><code>hfwnd</code> + <dd>A handle previously returned by + <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>. + </dl> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.4.5 <a name="nxtksetposition"><code>nxtk_setposition()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> +#include <nuttx/nxtk.h> + +int nxtk_setposition(NXTKWINDOW hfwnd, FAR struct nxgl_point_s *pos); +</pre></ul> +<p> + <b>Description:</b> + 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. +</p> +<p> + <b>Input Parameters:</b> + <dl> + <dt><code>hfwnd</code> + <dd>A handle previously returned by + <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>. + <dt><code>pos</code> + <dd>The new position of the client sub-window + </dl> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.4.6 <a name="nxtksetsize"><code>nxtk_setsize()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> +#include <nuttx/nxtk.h> + +int nxtk_setsize(NXTKWINDOW hfwnd, FAR struct nxgl_size_s *size); +</pre></ul> +<p> + <b>Description:</b> + 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. +</p> +<p> + <b>Input Parameters:</b> + <dl> + <dt><code>hfwnd</code> + <dd>A handle previously returned by + <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>. + <dt><code>size</code> + <dd>The new size of the client sub-window. + </dl> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.4.7 <a name="nxtkraise"><code>nxtk_raise()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> +#include <nuttx/nxtk.h> + +int nxtk_raise(NXTKWINDOW hfwnd); +</pre></ul> +<p> + <b>Description:</b> + Bring the window containing the specified client sub-window to the top + of the display. +</p> +<p> + <b>Input Parameters:</b> + <dl> + <dt><code>hfwnd</code> + <dd>A handle previously returned by + <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a> + specifying the window to be raised. + <dt><code></code> + <dd> + </dl> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.4.8 <a name="nxtklower"><code>nxtk_lower()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> +#include <nuttx/nxtk.h> + +int nxtk_lower(NXTKWINDOW hfwnd); +</pre></ul> +<p> + <b>Description:</b> + Lower the window containing the specified client sub-window to the + bottom of the display. +</p> +<p> + <b>Input Parameters:</b> + <dl> + <dt><code>hfwnd</code> + <dd>A handle previously returned by + <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a> + specifying the window to be lowered. + <dt><code></code> + <dd> + </dl> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.4.9 <a name="nxtkfillwindow"><code>nxtk_fillwindow()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> +#include <nuttx/nxtk.h> + +int nxtk_fillwindow(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, + nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); +</pre></ul> +<p> + <b>Description:</b> + Fill the specified rectangle in the client window with the specified color. +</p> +<p> + <b>Input Parameters:</b> + <dl> + <dt><code>hfwnd</code> + <dd>A handle previously returned by + <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>. + <dt><code>rect</code> + <dd>The location within the client window to be filled + <dt><code>color</code> + <dd>The color to use in the fill + </dl> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.4.10 <a name="nxtkfilltrapwindow"><code>nxtk_filltrapwindow()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> +#include <nuttx/nxtk.h> + +int nxtk_filltrapwindow(NXTKWINDOW hfwnd, + FAR const struct nxgl_trapezoid_s *trap, + nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); +</pre></ul> +<p> + <b>Description:</b> + Fill the specified trapezoid in the client window with the specified color +</p> +<p> + <b>Input Parameters:</b> + <dl> + <dt><code>hfwnd</code> + <dd>A handle previously returned by + <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>. + <dt><code>trap</code> + <dd>The trapezoidal region to be filled. + <dt><code>color</code> + <dd>The color to use in the fill. + </dl> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.4.11 <a name="nxtkmovewindow"><code>nxtk_movewindow()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> +#include <nuttx/nxtk.h> + +int nxtk_movewindow(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, + FAR const struct nxgl_point_s *offset); +</pre></ul> +<p> + <b>Description:</b> + Move a rectangular region within the client sub-window of a framed window. +</p> +<p> + <b>Input Parameters:</b> + <dl> + <dt><code>hfwnd</code> + <dd>A handle previously returned by + <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a> + specifying the client sub-window within which the move is to be done. + <dt><code>rect</code> + <dd>Describes the rectangular region relative to the client sub-window to move. + <dt><code>offset</code> + <dd>The offset to move the region + </dl> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.4.12 <a name="nxtkbitmapwindow"><code>nxtk_bitmapwindow()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> +#include <nuttx/nxtk.h> + +int nxtk_bitmapwindow(NXTKWINDOW hfwnd, + FAR const struct nxgl_rect_s *dest, + FAR const void *src[CONFIG_NX_NPLANES], + FAR const struct nxgl_point_s *origin, + unsigned int stride); +</pre></ul> +<p> + <b>Description:</b> + Copy a rectangular region of a larger image into the rectangle in the + specified client sub-window. +</p> +<p> + <b>Input Parameters:</b> + <dl> + <dt><code>hfwnd</code> + <dd>A handle previously returned by + <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a> + specifying the client sub-window that will receive the bitmap. + <dt><code>dest</code> + <dd>Describes the rectangular region on in the client sub-window + will receive the bit map. + <dt><code>src</code> + <dd>The start of the source image(s). This is an array source + images of size <code>CONFIG_NX_NPLANES</code> (probably 1). + <dt><code>origin</code> + <dd>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. + <dt><code>stride</code> + <dd>The width of the full source image in pixels. + </dl> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.4.13 <a name="nxtkopentoolbar"><code>nxtk_opentoolbar()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> +#include <nuttx/nxtk.h> + +int nxtk_opentoolbar(NXTKWINDOW hfwnd, nxgl_coord_t height, + FAR const struct nx_callback_s *cb, + FAR void *arg); +</pre></ul> +<p> + <b>Description:</b> + Create a tool bar at the top of the specified framed window. +</p> +<p> + <b>Input Parameters:</b> + <dl> + <dt><code>hfwnd</code> + <dd>A handle previously returned by + <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>. + <dt><code>height</code> + <dd>The requested height of the toolbar in pixels. + <dt><code></code> + <dd>Callbacks used to process toolbar events. + <dt><code></code> + <dd>User provided value that will be returned with toolbar callbacks. + </dl> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.4.14 <a name="nxtkclosetoolbar"><code>nxtk_closetoolbar()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> +#include <nuttx/nxtk.h> + +int nxtk_closetoolbar(NXTKWINDOW hfwnd); +</pre></ul> +<p> + <b>Description:</b> + Remove the tool bar at the top of the specified framed window. +</p> +<p> + <b>Input Parameters:</b> + <dl> + <dt><code>hfwnd</code> + <dd>A handle previously returned by + <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>. + <dt><code></code> + <dd> + </dl> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.4.15 <a name="nxtkfilltoolbar"><code>nxtk_filltoolbar()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> +#include <nuttx/nxtk.h> + +int nxtk_filltoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, + nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); +</pre></ul> +<p> + <b>Description:</b> + Fill the specified rectangle in the toolbar sub-window with the specified color. +</p> +<p> + <b>Input Parameters:</b> + <dl> + <dt><code>hfwnd</code> + <dd>A handle previously returned by + <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>. + <dt><code>rect</code> + <dd>The location within the toolbar window to be filled. + <dt><code>color</code> + <dd>The color to use in the fill. + </dl> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.4.16 <a name="nxtkfilltraptoolbar"><code>nxtk_filltraptoolbar()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> +#include <nuttx/nxtk.h> + +int nxtk_filltraptoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_trapezoid_s *trap, + nxgl_mxpixel_t color[CONFIG_NX_NPLANES]); +</pre></ul> +<p> + <b>Description:</b> + Fill the specified trapezoid in the toolbar sub-window with the specified color. +</p> +<p> + <b>Input Parameters:</b> + <dl> + <dt><code>hfwnd</code> + <dd>A handle previously returned by + <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>. + <dt><code>trap</code> + <dd>The trapezoidal region to be filled + <dt><code>color</code> + <dd>The color to use in the fill + </dl> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.4.17 <a name="nxtkmovetoolbar"><code>nxtk_movetoolbar()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> +#include <nuttx/nxtk.h> + +int nxtk_movetoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, + FAR const struct nxgl_point_s *offset); +</pre></ul> +<p> + <b>Description:</b> + Move a rectangular region within the toolbar sub-window of a framed window. +</p> +<p> + <b>Input Parameters:</b> + <dl> + <dt><code>hfwnd</code> + <dd>A handle identifying sub-window containing the toolbar within which the move is + to be done. + This handle must have previously been returned by + <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>. + <dt><code>rect</code> + <dd>Describes the rectangular region relative to the toolbar sub-window to move. + <dt><code>offset</code> + <dd>The offset to move the region + </dl> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h3>2.4.18 <a name="nxtkbitmaptoolbar"><code>nxtk_bitmaptoolbar()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nx.h> +#include <nuttx/nxtk.h> + +int nxtk_bitmaptoolbar(NXTKWINDOW hfwnd, + FAR const struct nxgl_rect_s *dest, + FAR const void *src[CONFIG_NX_NPLANES], + FAR const struct nxgl_point_s *origin, + unsigned int stride); +</pre></ul> +<p> + <b>Description:</b> + Copy a rectangular region of a larger image into the rectangle in the + specified toolbar sub-window. +</p> +<p> + <b>Input Parameters:</b> + <dl> + <dt><code>hfwnd</code> + <dd>A handle previously returned by + <a href="#nxtkopenwindow"><code>nxtk_openwindow()</code></a>. + <dt><code>dest</code> + <dd>Describes the rectangular region on in the toolbar sub-window + will receive the bit map. + <dt><code>src</code> + <dd>The start of the source image. + <dt><code>origin</code> + <dd>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. + <dt><code>stride</code> + <dd>The width of the full source image in bytes. + </dl> +</p> +<p> + <b>Returned Value:</b> + <code>OK</code> on success; + <code>ERROR</code> on failure with <code>errno</code> set appropriately +</p> + +<h2>2.5 <a name="nxfonts2">NX Fonts Support (<code>NXFONTS</code>)</a></h2> + +<h3>2.5.1 <a name="nxfontstypes"><code>NXFONTS Types()</code></a></h3> +<p> + This structures provides the metrics for one glyph: +</p> +<ul><pre> +struct nx_fontmetic_s +{ + uint32 stride : 2; /* Width of one font row in bytes */ + uint32 width : 6; /* Width of the font in bits */ + uint32 height : 6; /* Height of the font in rows */ + uint32 xoffset : 6; /* Top, left-hand corner X-offset in pixels */ + uint32 yoffset : 6; /* Top, left-hand corner y-offset in pixels */ + uint32 unused : 6; +}; +</pre></ul> + +<p> + This structure binds the glyph metrics to the glyph bitmap: +</p> +<ul><pre> +struct nx_fontbitmap_s +{ + struct nx_fontmetic_s metric; /* Character metrics */ + FAR const ubyte *bitmap; /* Pointer to the character bitmap */ +}; +</pre></ul> + +<p> + This structure describes one contiguous grouping of glyphs that + can be described by an array starting with encoding <code>first</code> and + extending through (<code>first</code> + <code>nchars</code> - 1). +</p> +<ul><pre> +struct nx_fontset_s +{ + ubyte first; /* First bitmap character code */ + ubyte nchars; /* Number of bitmap character codes */ + FAR const struct nx_fontbitmap_s *bitmap; +}; +</pre></ul> + +<p> + This structure describes the overall fontset: +</p> +<ul><pre> +struct nx_font_s +{ + ubyte mxheight; /* Max height of one glyph in rows */ + ubyte mxwidth; /* Max width of any glyph in pixels */ + ubyte mxbits; /* Max number of bits per character code */ + ubyte spwidth; /* The width of a space in pixels */ +}; +</pre></ul> + +<h3>2.5.2 <a name="nxfgetfontset"><code>nxf_getfontset()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nxfonts.h> + +FAR const struct nx_font_s *nxf_getfontset(void); +</pre></ul> +<p> + <b>Description:</b> + Return information about the current font set. +</p> +<p> + <b>Input Parameters:</b> None +</p> +<p> + <b>Returned Value:</b> + An instance of <code>struct nx_font_s</code> describing the font set. +</p> + +<h3>2.5.3 <a name="nxfgetbitmap"><code>nxf_getbitmap()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nxfonts.h> + +FAR const struct nx_fontbitmap_s *nxf_getbitmap(uint16 ch); +</pre></ul> +<p> + <b>Description:</b> + Return font bitmap information for the selected character encoding. +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code></code> + <dd> + </dl></ul> +</p> +<p> + <b>Returned Value:</b> + An instance of <code>struct nx_fontbitmap_s</code> describing the glyph. +</p> + +<h3>2.5.4 <a name="nxfconvertbpp"><code>nxf_convert_*bpp()</code></a></h3> +<p><b>Function Prototype:</b></p> +<ul><pre> +#include <nuttx/nxglib.h> +#include <nuttx/nxfonts.h> + +int nxf_convert_2bpp(FAR ubyte *dest, uint16 height, + uint16 width, uint16 stride, uint16 ch, + nxgl_mxpixel_t color); +int nxf_convert_4bpp(FAR ubyte *dest, uint16 height, + uint16 width, uint16 stride, uint16 ch, + nxgl_mxpixel_t color); +int nxf_convert_8bpp(FAR ubyte *dest, uint16 height, + uint16 width, uint16 stride, uint16 ch, + nxgl_mxpixel_t color); +int nxf_convert_16bpp(FAR uint16 *dest, uint16 height, + uint16 width, uint16 stride, uint16 ch, + nxgl_mxpixel_t color); +int nxf_convert_24bpp(FAR uint32 *dest, uint16 height, + uint16 width, uint16 stride, uint16 ch, + nxgl_mxpixel_t color); +int nxf_convert_32bpp(FAR uint32 *dest, uint16 height, + uint16 width, uint16 stride, uint16 ch, + nxgl_mxpixel_t color); +</pre></ul> +<p> + <b>Description:</b> Convert the 1BPP font to a new pixel depth. +</p> +<p> + <b>Input Parameters:</b> + <ul><dl> + <dt><code>dest</code> + <dd>The destination buffer provided by the caller. + <dt><code>height</code> + <dd>The max height of the returned char in rows. + <dt><code>width</code> + <dd>The max width of the returned char in pixels. + <dt><code>stride</code> + <dd>The width of the destination buffer in bytes. + <dt><code>ch</code> + <dd>The character code to convert. + <dt><code>color</code> + <dd>The color to use for '1' bits in the font bitmap (0 bits are transparent). + </dl></ul> +</p> +<p> + <b>Returned Value:</b> + On Success, these functions returns the actual width of the font in bytes. + on failed, a negated <code>errno</code> is retured. +</p> + +<table width ="100%"> + <tr bgcolor="#e4e4e4"> + <td> + <h1>Appendix A <a name="grapicsdirs"><code>graphics/</code> Directory Structure</a></h1> + </td> + </tr> +</table> + +<ul> + <dl> + <dt><code>graphics/nxglib</code> + <dd>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). + + <dt><code>graphics/nxbe</code> + <dd>This is the <i>back-end</i> of a tiny windowing system. + It can be used with either of two front-ends to complete a windowing system (see + <code>nxmu</code> and <code>nxsu/<code> below). + It contains most of the important window management logic: clipping, window controls, + window drawing, etc. + + <dt><code>graphics/nxsu</code> + <dd>This is the NX single user <i>front end</i>. + When combined with the generic <i>back-end</i> (<code>nxbe</code>), it implements a + single threaded, single user windowing system. + The files in this directory present the window APIs described in + <code>include/nuttx/nx.h</code>. + The single user front-end is selected when <code>CONFIG_NX_MULTIUSER</code> is not + defined in the NuttX configuration file. + + <dt><code>graphics/nxsu</code> + <dd>This is the NX multi user <i>front end</i>. + When combined with the generic <i>back-end</i> (<code>nxbe</code>), it implements a + multi-threaded, multi-user windowing system. + The files in this directory present the window APIs described in + <code>include/nuttx/nx.h</code>. + 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 <code>CONFIG_NX_MULTIUSER</code> is defined + in the NuttX configuration file. + + <dt><code>graphics/nxfonts</code> + <dd>This is where the NXFONTS implementation resides. + This is a relatively low-level set of charset set/glyph management APIs. + See <code>include/nuttx/nxfonts.h</code>. + + <dt><code>graphics/nxtk</code> + <dd>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 <code>include/nuttx/nxtk.h</code>. + + <dt><code>graphics/nxwidgets</code> + <dd>At one time, I planned to put NXWIDGETS implementation here, but not anymore. + </dl> +</ul> + +<table width ="100%"> + <tr bgcolor="#e4e4e4"> + <td> + <h1>Appendix B <a name="nxconfigs">NX Configuration Options</a></h1> + </td> + </tr> +</table> + +<h2>B.1 <a name="nxgenconfig">General Configuration Settings</a></h2> + +<ul> + <dl> + <dt><code>CONFIG_NX</code> + Enables overall support for graphics library and NX + </dl> +</ul> + +<h2>B.2 <a name="nxglconfig">NXGL Configuration Settings</a></h2> + +<ul> + <dl> + <dt><code>CONFIG_NX_NPLANES</code>: + <dd>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. + <dt><code>CONFIG_NX_DISABLE_1BPP</code>, <code>CONFIG_NX_DISABLE_2BPP</code>, + <code>CONFIG_NX_DISABLE_4BPP</code>, <code>CONFIG_NX_DISABLE_8BPP</code> + <code>CONFIG_NX_DISABLE_16BPP</code>, <code>CONFIG_NX_DISABLE_24BPP</code>, and + <code>CONFIG_NX_DISABLE_32BPP</code>: + <dd>NX supports a variety of pixel depths. You can save some + memory by disabling support for unused color depths. + <dt><code>CONFIG_NX_PACKEDMSFIRST</code>: + <dd>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 + </dl> +</ul> + +<h2>B.3 <a name="nxconfig">NX Configuration Settings</a></h2> + +<ul> + <dl> + <dt><code>CONFIG_NX_MOUSE</code>: + <dd>Build in support for mouse input. + <dt><code>CONFIG_NX_KBD</code>: + <dd>Build in support of keypad/keyboard input. + </dl> +</ul> + +<h2>B.4 <a name="nxmuconfig">NX Multi-User (Only) Configuration Settings</a></h2> + +<ul> + <dl> + <dt><code>CONFIG_NX_MULTIUSER</code>: + <dd>Configures NX in multi-user mode. + <dt><code>CONFIG_NX_BLOCKING</code> + <dd>Open the client message queues in blocking mode. In this case, + <dt><code>nx_eventhandler()</code> will not return until a message is received and processed. + <dt><code>CONFIG_NX_MXSERVERMSGS</code> and <code>CONFIG_NX_MXCLIENTMSGS</code> + <dd>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 (<code>CONFIG_PREALLOC_MQ_MSGS</code> controls how many + messages are pre-allocated). + </dl> +</ul> + +<h2>B.5 <a name="nxtkconfig">NXTK Configuration Settings</a></h2> + +<ul> + <dl> + <dt><code>CONFIG_NXTK_BORDERWIDTH</code>: + <dd>Specifies with with of the border (in pixels) used with + framed windows. The default is 4. + <dt><code>CONFIG_NXTK_BORDERCOLOR1</code> and <code>CONFIG_NXTK_BORDERCOLOR2</code>: + <dd>Specify the colors of the border used with framed windows. + <dt><code>CONFIG_NXTK_BORDERCOLOR2</code> is the shadow side color and so + <dd>is normally darker. The default is medium and dark grey, + respectively + <dt><code>CONFIG_NXTK_AUTORAISE</code>: + <dd>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. + </dl> +</ul> + +<h2>B.6 <a name="nxfpmtsconfig">NXFONTS Configuration Settings</a></h2> + +<ul> + <dl> + <dt><code>CONFIG_NXFONTS_CHARBITS</code>: + <dd>The number of bits in the character set. Current options are + only 7 and 8. The default is 7. + <dt><code>CONFIG_NXFONT_SANS</code>: + <dd>At present, there is only one font. But if there were were more, + then this option would select the sans serif font. + </dl> +</ul> + +<table width ="100%"> + <tr bgcolor="#e4e4e4"> + <td> + <h1>Appendix C <a name="testcoverage">NX Test Coverage</a></h1> + </td> + </tr> +</table> + +<p> + The primary test tool for debugging NX resides at <code>examples/nx</code>. + At present, that test only exercises a subset of NX; the remainder is essentially + untested. + The following table describes the testing performed on each NX API: +</p> + +<center><h1>Table C.1: NX Test Coverage</h1></center> + +<center><table border="1" width="50%"> + <tr><th><i>To be provided</i></th></tr> +</table></center> + +</body> +</html> + diff --git a/nuttx/Documentation/NXOrganization.gif b/nuttx/Documentation/NXOrganization.gif Binary files differnew file mode 100644 index 000000000..6bae8e552 --- /dev/null +++ b/nuttx/Documentation/NXOrganization.gif diff --git a/nuttx/Documentation/NuttX.html b/nuttx/Documentation/NuttX.html index e333675e9..4481149fa 100644 --- a/nuttx/Documentation/NuttX.html +++ b/nuttx/Documentation/NuttX.html @@ -497,7 +497,11 @@ <td><br></td> <td> <p> - <li>Graphics library and tiny windowing system under development.</li> + <li> + NX: A graphics library, tiny windowing system and tiny font support. + Documented in the <a href="NXGraphicsSubsystem.html">NX Graphics Subsystem</a> + manual. + </li> </p> </tr> </table></center> @@ -574,8 +578,8 @@ Using a variety of technologies, NuttX can scale from the very tiny to the moderate-size system. I have executed NuttX with some simple applications in as little as 32Kb <i>total</i> memory (code and data). - On the other hand, I often run richly featured NuttX builds that require - memory up to 100Kb. + On the other hand, typical, richly featured NuttX builds require more like 64Kb + (and if all of the features are used, this can push 100Kb). </p> </td> </tr> @@ -1375,6 +1379,10 @@ buildroot-0.1.3 2008-xx-xx <spudmonkey@racsa.co.cr> </tr> <tr> <td valign="top" width="22"><img height="20" width="20" src="favicon.ico"></td> + <td><a href="NXGraphicsSubsystem.html">NX Graphics Subsystem</a></td> +</tr> +<tr> + <td valign="top" width="22"><img height="20" width="20" src="favicon.ico"></td> <td><a href="ChangeLog.txt">Change Log</a></td> </tr> <tr> diff --git a/nuttx/Documentation/NuttxPortingGuide.html b/nuttx/Documentation/NuttxPortingGuide.html index e40a8d4e2..b47cd99de 100644 --- a/nuttx/Documentation/NuttxPortingGuide.html +++ b/nuttx/Documentation/NuttxPortingGuide.html @@ -1,99 +1,114 @@ <html> - <head> -<title>NuttX Porting Manual</title> +<title>NuttX Porting Guide</title> <meta name="author" content="Gregory Nutt"> </head> <body background="backgd.gif"> <hr><hr> -<center><h1><i>Under Construction</i></h1></center> +<table width ="100%"> + <tr align="center" bgcolor="#e4e4e4"> + <td> + <h1><big><font color="#3c34ec"> + <i>NuttX RTOS Porting Guide</i> + </font></big></h1> + <p>Last Updated: December 5, 2008</p> + </td> + </tr> +</table> <hr><hr> -<center> - <h1><big><b> - <p>NuttX Operating System</br> - Porting Guide</p> - </b></big></h1> - <p><small>by</small></p> - <p>Gregory Nutt</p> - <p><small>Last Update: December 5, 2008</small></p> -</center> - -<center><h1>Table of Contents</h1></center> -<li><a href="#Introduction">1.0 Introduction</a></li> -<li><a href="#DirectoryStructure">2.0 Directory Structure</a></li> + +<table width ="100%"> + <tr bgcolor="#e4e4e4"> + <td> + <h1>Table of Contents</h1> + </td> + </tr> +</table> + <ul> - <li><a href="#DirStructDocumentation">2.1 Documentation</a></li> - <l1><a href="#DirStructArch">2.2 arch/</a></li> - <ul> - <li><a href="#archdirectorystructure">2.2.1 Subdirectory Structure</a></li> - <li><a href="#summaryofarchfiles">2.2.2 Summary of Files</a></li> - <li><a href="#supportedarchitectures">2.2.3 Supported Architectures</a></li> - </ul> - <li><a href="#DirStructConfigs">2.3 configs/</a></li> + <a href="#Introduction">1.0 Introduction</a><br> + <a href="#DirectoryStructure">2.0 Directory Structure</a> <ul> - <li><a href="#configsdirectorystructure">2.3.1 Subdirectory Structure</a></li> - <li><a href="#summaryofconfigfiles">2.3.2 Summary of Files</a></li> + <a href="#DirStructDocumentation">2.1 Documentation</a></br> + <a href="#DirStructArch">2.2 arch/</a> <ul> - <li><a href="#boardlogic">2.3.2.1 Board Specific Logic</a></li> - <li><a href="#boardconfigsubdirs">2.3.2.2 Board Specific Configuration Sub-Directories</a></li> + <a href="#archdirectorystructure">2.2.1 Subdirectory Structure</a><br> + <a href="#summaryofarchfiles">2.2.2 Summary of Files</a><br> + <a href="#supportedarchitectures">2.2.3 Supported Architectures</a> </ul> - <li><a href="#supportedboards">2.3.3 Supported Boards</a></li> + <a href="#DirStructConfigs">2.3 configs/</a> + <ul> + <a href="#configsdirectorystructure">2.3.1 Subdirectory Structure</a><br> + <a href="#summaryofconfigfiles">2.3.2 Summary of Files</a> + <ul> + <a href="#boardlogic">2.3.2.1 Board Specific Logic</a><br> + <a href="#boardconfigsubdirs">2.3.2.2 Board Specific Configuration Sub-Directories</a> + </ul> + <a href="#supportedboards">2.3.3 Supported Boards</a> + </ul> + <a href="#DirStructDrivers">2.4 drivers/</a><br> + <a href="#DirStructExamples">2.5 examples/</a><br> + <a href="#DirStructFs">2.6 fs/</a><br> + <a href="#DirStructGraphics">2.7 graphics/</a><br> + <a href="#DirStructInclude">2.8 include/</a><br> + <a href="#DirStructLib">2.9 lib/</a><br> + <a href="#DirStructMm">2.10 mm/</a><br> + <a href="#DirStructNet">2.11 net</a><br> + <a href="#DirStructNetUtils">2.12 netutils</a><br> + <a href="#DirStructSched">2.13 sched/</a><br> + <a href="#DirStructTools">2.14 tools/</a><br> + <a href="#topmakefile">2.15 Makefile</a> </ul> - <li><a href="#DirStructDrivers">2.4 drivers/</a></li> - <li><a href="#DirStructExamples">2.5 examples/</a></li> - <li><a href="#DirStructFs">2.6 fs/</a></li> - <li><a href="#DirStructGraphics">2.7 graphics/</a></li> - <li><a href="#DirStructInclude">2.8 include/</a></li> - <li><a href="#DirStructLib">2.9 lib/</a></li> - <li><a href="#DirStructMm">2.10 mm/</a></li> - <li><a href="#DirStructNet">2.11 net</a></li> - <li><a href="#DirStructNetUtils">2.12 netutils</a></li> - <li><a href="#DirStructSched">2.13 sched/</a></li> - <li><a href="#DirStructTools">2.14 tools/</a></li> - <li><a href="#topmakefile">2.15 Makefile</a></li> -</ul> -<li><a href="#configandbuild">3.0 Configuring and Building</a></li> -<ul> - <li><a href="#configuringnuttx">3.1 Configuring NuttX</a></li> - <li><a href="#buildingnuttx">3.2 Building NuttX</a></li> -</ul> -<li><a href="#ArchAPIs">4.0 Architecture APIs</a></li> -<ul> - <li><a href="#imports">4.1 APIs Exported by Architecture-Specific Logic to NuttX</a></li> + <a href="#configandbuild">3.0 Configuring and Building</a> <ul> - <li><a href="#upinitialize">4.1.1 <code>up_initialize()</code></a></li> - <li><a href="#upidle">4.1.2 <code>up_idle()</code></a></li> - <li><a href="#upinitialstate">4.1.3 <code>up_initial_state()</code></a></li> - <li><a href="#upcreatestack">4.1.4 <code>up_create_stack()</code></a></li> - <li><a href="#upusestack">4.1.5 <code>up_use_stack()</code></a></li> - <li><a href="#upreleasestack">4.1.6 <code>up_release_stack()</code></a></li> - <li><a href="#upunblocktask">4.1.7 <code>up_unblock_task()</code></a></li> - <li><a href="#upblocktask">4.1.8 <code>up_block_task()</code></a></li> - <li><a href="#upreleasepending">4.1.9 <code>up_release_pending()</code></a></li> - <li><a href="#upreprioritizertr">4.1.10 <code>up_reprioritize_rtr()</code></a></li> - <li><a href="#_exit">4.1.11 <code>_exit()</code></a></li> - <li><a href="#upassert">4.1.12 <code>up_assert()</code></a></li> - <li><a href="#upschedulesigaction">4.1.13 <code>up_schedule_sigaction()</code></a></li> - <li><a href="#upallocateheap">4.1.14 <code>up_allocate_heap()</code></a></li> - <li><a href="#upinterruptcontext">4.1.15 <code>up_interrupt_context()</code></a></li> - <li><a href="#updisableirq">4.1.16 <code>up_disable_irq()</code></a></li> - <li><a href="#upenableirq">4.1.17 <code>up_enable_irq()</code></a></li> - <li><a href="#upputc">4.1.18 <code>up_putc()</code></a></li> + <a href="#configuringnuttx">3.1 Configuring NuttX</a><br> + <a href="#buildingnuttx">3.2 Building NuttX</a> </ul> - <li><a href="#exports">4.2 APIs Exported by NuttX to Architecture-Specific Logic</a></li> + <a href="#ArchAPIs">4.0 Architecture APIs</a> <ul> - <li><a href="#osstart">4.2.1 <code>os_start()</code></a></li> - <li><a href="#listmgmt">4.2.2 OS List Management APIs</a></li></li> - <li><a href="#schedprocesstimer">4.2.3 <code>sched_process_timer()</code></a></li> - <li><a href="#irqdispatch">4.2.4 <code>irq_dispatch()</code></a></li> + <a href="#imports">4.1 APIs Exported by Architecture-Specific Logic to NuttX</a> + <ul> + <a href="#upinitialize">4.1.1 <code>up_initialize()</code></a><br> + <a href="#upidle">4.1.2 <code>up_idle()</code></a><br> + <a href="#upinitialstate">4.1.3 <code>up_initial_state()</code></a><br> + <a href="#upcreatestack">4.1.4 <code>up_create_stack()</code></a><br> + <a href="#upusestack">4.1.5 <code>up_use_stack()</code></a><br> + <a href="#upreleasestack">4.1.6 <code>up_release_stack()</code></a><br> + <a href="#upunblocktask">4.1.7 <code>up_unblock_task()</code></a><br> + <a href="#upblocktask">4.1.8 <code>up_block_task()</code></a><br> + <a href="#upreleasepending">4.1.9 <code>up_release_pending()</code></a><br> + <a href="#upreprioritizertr">4.1.10 <code>up_reprioritize_rtr()</code></a><br> + <a href="#_exit">4.1.11 <code>_exit()</code></a><br> + <a href="#upassert">4.1.12 <code>up_assert()</code></a><br> + <a href="#upschedulesigaction">4.1.13 <code>up_schedule_sigaction()</code></a><br> + <a href="#upallocateheap">4.1.14 <code>up_allocate_heap()</code></a><br> + <a href="#upinterruptcontext">4.1.15 <code>up_interrupt_context()</code></a><br> + <a href="#updisableirq">4.1.16 <code>up_disable_irq()</code></a><br> + <a href="#upenableirq">4.1.17 <code>up_enable_irq()</code></a><br> + <a href="#upprioritizeirq">4.1.18 <code>up_prioritize_irq()</code></a></br> + <a href="#upputc">4.1.19 <code>up_putc()</code></a> + </ul> + <a href="#exports">4.2 APIs Exported by NuttX to Architecture-Specific Logic</a> + <ul> + <a href="#osstart">4.2.1 <code>os_start()</code></a><br> + <a href="#listmgmt">4.2.2 OS List Management APIs</a><br><br> + <a href="#schedprocesstimer">4.2.3 <code>sched_process_timer()</code></a><br> + <a href="#irqdispatch">4.2.4 <code>irq_dispatch()</code></a> + </ul> </ul> + <a href="#NxFileSystem">5.0 NuttX File System</a><br> + <a href="#apndxconfigs">Appendix A: NuttX Configuration Settings</a><br> + <a href="#apndxtrademarks">Appendix B: Trademarks</a> </ul> -<li><a href="#NxFileSystem">5.0 NuttX File System</a></li> -<li><a href="#apndxconfigs">Appendix A: NuttX Configuration Settings</a></li> -<li><a href="#apndxtrademarks">Appendix B: Trademarks</a></li> -<hr> -<h1>1.0 <a name="Introduction">Introduction</a></h1> + +<table width ="100%"> + <tr bgcolor="#e4e4e4"> + <td> + <h1>1.0 <a name="Introduction">Introduction</a></h1> + </td> + </tr> +</table> <p><b>Overview</b> This document provides and overview of the NuttX build and configuration @@ -104,10 +119,13 @@ See also <code>arch/README.txt</code> and <code>configs/README.txt</code>. </p> -<p><b>General Philosophy</b>. - -<hr> -<h1>2.0 <a name="DirectoryStructure">Directory Structure</a></h1> +<table width ="100%"> + <tr bgcolor="#e4e4e4"> + <td> + <h1>2.0 <a name="DirectoryStructure">Directory Structure</a></h1> + </td> + </tr> +</table> <p> <b>Directory Structure</b>. @@ -868,8 +886,14 @@ tools/ Use of this <code>Makefile</code> to build NuttX is described <a href="#buildingnuttx">below</a>. </p> -<hr> -<h1>3.0 <a name="configandbuild">Configuring and Building</a></h1> +<table width ="100%"> + <tr bgcolor="#e4e4e4"> + <td> + <h1>3.0 <a name="configandbuild">Configuring and Building</a></h1> + </td> + </tr> +</table> + <h2><a name="configuringnuttx">3.1 Configuring NuttX</a></h2> <p> <b>Manual Configuration</b>. @@ -948,7 +972,13 @@ The system can be re-made subsequently by just typing <code>make</code>. <li>Creating make dependencies. </ul> -<h1>4.0 <a name="ArchAPIs">Architecture APIs</a></h1> +<table width ="100%"> + <tr bgcolor="#e4e4e4"> + <td> + <h1>4.0 <a name="ArchAPIs">Architecture APIs</a></h1> + </td> + </tr> +</table> <p> The file <code>include/nuttx/arch.h</code> identifies by prototype all of the APIs that must @@ -1285,28 +1315,76 @@ The system can be re-made subsequently by just typing <code>make</code>. </p> <h3><a name="updisableirq">4.1.16 <code>up_disable_irq()</code></a></h3> -<p><b>Prototype</b>: <code>void up_disable_irq(int irq);</code></p> +<p><b>Prototype</b>:</p> +<ul><pre> +#ifndef CONFIG_ARCH_NOINTC + void up_disable_irq(int irq); +#endf +</pre></ul> <p><b>Description</b>. Disable the IRQ specified by 'irq' + On many architectures, there are three levels of interrupt enabling: (1) + at the global level, (2) at the level of the interrupt controller, + and (3) at the device level. In order to receive interrupts, they + must be enabled at all three levels. +</p> +<p> + This function implements enabling of the device specified by 'irq' + at the interrupt controller level if supported by the architecture + (irqsave() supports the global level, the device level is hardware + specific). +<p> + If the architecture does not support <code>up_disable_irq</code>, + <code>CONFIG_ARCH_NOINTC</code> should be defined in the NuttX configuration file. + Since this API cannot be supported on all architectures, it should be + avoided in common implementations where possible. </p> <h3><a name="upenableirq">4.1.17 <code>up_enable_irq()</code></a></h3> -<p><b>Prototype</b>: <code>void up_enable_irq(int irq);</code></p> +<p><b>Prototype</b>:</p> +<ul><pre> +#ifndef CONFIG_ARCH_NOINTC + void up_enable_irq(int irq); +#endf +</pre></ul> + +<p><b>Description</b>. + This function implements disabling of the device specified by 'irq' + at the interrupt controller level if supported by the architecture + (irqrestore() supports the global level, the device level is hardware + specific). +</p> +<p> + If the architecture does not support <code>up_disable_irq</code>, + <code>CONFIG_ARCH_NOINTC</code> should be defined in the NuttX configuration file. + Since this API cannot be supported on all architectures, it should be + avoided in common implementations where possible. +</p> +<h3><a name="upprioritizeirq">4.1.18 <code>up_prioritize_irq()</code></a></h3> +<p><b>Prototype</b>:</p> +<ul><pre> +#ifdef CONFIG_ARCH_IRQPRIO + void up_enable_irq(int irq); +#endf +</pre></ul> <p><b>Description</b>. - Enable the IRQ specified by 'irq' + Set the priority of an IRQ. +</p> +<p> + If the architecture supports <code>up_enable_irq</code>, + <code>CONFIG_ARCH_IRQPRIO</code> should be defined in the NuttX configuration file. + Since this API cannot be supported on all architectures, it should be + avoided in common implementations where possible. </p> -<h3><a name="upputc">4.1.18 <code>up_putc()</code></a></h3> +<h3><a name="upputc">4.1.19 <code>up_putc()</code></a></h3> <p><b>Prototype</b>: <code>int up_putc(int ch);</code></p> <p><b>Description</b>. This is a debug interface exported by the architecture-specific logic. Output one character on the console -<p> - This API is <i>NOT</i> required if <code>CONFIG_HEAP_BASE</code> - is defined. </p> <h2><a name="exports">4.2 APIs Exported by NuttX to Architecture-Specific Logic</a></h2> @@ -1345,7 +1423,13 @@ The system can be re-made subsequently by just typing <code>make</code>. the appropriate, registered handling logic. </p> -<h1><a name="NxFileSystem">5.0 NuttX File System</a></h1> +<table width ="100%"> + <tr bgcolor="#e4e4e4"> + <td> + <h1><a name="NxFileSystem">5.0 NuttX File System</a></h1> + </td> + </tr> +</table> <p><b>Overview</b>. NuttX includes an optional, scalable file system. @@ -1395,7 +1479,13 @@ The system can be re-made subsequently by just typing <code>make</code>. from the very tiny platform to the moderate platform. </p> -<h1><a name="apndxconfigs">Appendix A: NuttX Configuration Settings</a></h1> +<table width ="100%"> + <tr bgcolor="#e4e4e4"> + <td> + <h1><a name="apndxconfigs">Appendix A: NuttX Configuration Settings</a></h1> + </td> + </tr> +</table> <p> The following variables are recognized by the build (you may @@ -1977,7 +2067,13 @@ The system can be re-made subsequently by just typing <code>make</code>. </li> </ul> -<h1><a name="apndxtrademarks">Appendix B: Trademarks</a></h1> +<table width ="100%"> + <tr bgcolor="#e4e4e4"> + <td> + <h1><a name="apndxtrademarks">Appendix B: Trademarks</a></h1> + </td> + </tr> +</table> <li>ARM, ARM7 ARM7TDMI, ARM9, ARM926EJS are trademarks of Advanced RISC Machines, Limited.</li> <li>Cygwin is a trademark of Red Hat, Incorporated.</li> diff --git a/nuttx/graphics/README.txt b/nuttx/graphics/README.txt index ded6f531c..44127a53c 100644 --- a/nuttx/graphics/README.txt +++ b/nuttx/graphics/README.txt @@ -26,7 +26,7 @@ at the present, but here is the longer term roadmap: 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 build on NXGLIB. + NX is built on top of NXGLIB. Related Header Files ^^^^^^^^^^^^^^^^^^^^ diff --git a/nuttx/include/nuttx/arch.h b/nuttx/include/nuttx/arch.h index b5e33d739..b4e17f658 100644 --- a/nuttx/include/nuttx/arch.h +++ b/nuttx/include/nuttx/arch.h @@ -386,7 +386,7 @@ EXTERN boolean up_interrupt_context(void); * * This function implements enabling of the device specified by 'irq' * at the interrupt controller level if supported by the architecture - * (irqsave() supports the global level, the device level is hardware + * (irqrestore() supports the global level, the device level is hardware * specific). * * Since this API is not supported on all architectures, it should be diff --git a/nuttx/include/nuttx/nx.h b/nuttx/include/nuttx/nx.h index 13866f2f5..cb5ac07e3 100644 --- a/nuttx/include/nuttx/nx.h +++ b/nuttx/include/nuttx/nx.h @@ -99,7 +99,7 @@ struct nx_callback_s * Input Parameters: * hwnd - Window handle * rect - The rectangle that needs to be re-drawn (in window relative - * coordinates + * coordinates) * more - TRUE: More re-draw requests will follow * arg - User provided argument (see nx_openwindow, nx_constructwindow) * @@ -122,7 +122,7 @@ struct nx_callback_s * hwnd - Window handle * size - The size of the window * pos - The position of the upper left hand corner of the window on - * the overalll display + * the overall display * bounds - The bounding rectangle that the describes the entire * display * arg - User provided argument (see nx_openwindow, nx_constructwindow) @@ -141,7 +141,7 @@ struct nx_callback_s * Name: mousein * * Descripton: - * New mouse data is available for the window + * New mouse data is available for the window. * * Input Parameters: * hwnd - Window handle @@ -346,7 +346,7 @@ EXTERN void nx_close(NXHANDLE handle); * * Return: * OK: No errors occurred. If CONFIG_NX_BLOCKING is defined, then - * one or more server message was processed. + * one or more server messages were processed. * ERROR: An error occurred and errno has been set appropriately. Of * particular interest, it will return errno == EHOSTDOWN when the * server is disconnected. After that event, the handle can no @@ -376,9 +376,7 @@ EXTERN int nx_eventhandler(NXHANDLE handle); * handle - the handle returned by nx_connect * * Return: - * OK: No errors occurred. If CONFIG_NX_BLOCKING is defined, then - * one or more server message was processed. - * ERROR: An error occurred and errno has been set appropriately + * OK on success; ERROR on failure with errno set appropriately * ****************************************************************************/ @@ -452,7 +450,7 @@ EXTERN int nx_closewindow(NXWINDOW hwnd); * * nx_setposition, nx_setsize, nx_raise, nx_lower. * - * - Neither nx_opengbwindow or nx_closebgwindow should be called more than + * - Neither nx_requestbkgd or nx_releasebkgd should be called more than * once. Multiple instances of the background window are not supported. * * Input Parameters: @@ -555,7 +553,7 @@ EXTERN int nx_setsize(NXWINDOW hwnd, FAR struct nxgl_size_s *size); EXTERN int nx_raise(NXWINDOW hwnd); /**************************************************************************** - * Name: nx_raise + * Name: nx_lower * * Description: * Lower the specified window to the bottom of the display. @@ -664,7 +662,7 @@ EXTERN int nx_move(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect, * origin - The origin of the upper, left-most corner of the full bitmap. * Both dest and origin are in window coordinates, however, origin * may lie outside of the display. - * stride - The width of the full source image in pixels. + * stride - The width of the full source image in bytes. * * Return: * OK on success; ERROR on failure with errno set appropriately diff --git a/nuttx/include/nuttx/nxfonts.h b/nuttx/include/nuttx/nxfonts.h index 25e7e0b12..4b9a0e3ed 100644 --- a/nuttx/include/nuttx/nxfonts.h +++ b/nuttx/include/nuttx/nxfonts.h @@ -64,7 +64,7 @@ struct nx_fontmetic_s uint32 unused : 6; }; -/* This structure bings the glyph metrics to the glyph bitmap */ +/* This structure binds the glyph metrics to the glyph bitmap */ struct nx_fontbitmap_s { @@ -117,7 +117,7 @@ extern "C" { * Return information about the current font set * * Input Parameters: - * None + * An instance of struct nx_font_s describing the font set. * ****************************************************************************/ @@ -132,6 +132,9 @@ EXTERN FAR const struct nx_font_s *nxf_getfontset(void); * Input Parameters: * ch - character code * + * Returned Value: + * An instance of struct nx_fontbitmap_s describing the glyph. + * ****************************************************************************/ EXTERN FAR const struct nx_fontbitmap_s *nxf_getbitmap(uint16 ch); diff --git a/nuttx/include/nuttx/nxglib.h b/nuttx/include/nuttx/nxglib.h index 56739592e..89585cf50 100644 --- a/nuttx/include/nuttx/nxglib.h +++ b/nuttx/include/nuttx/nxglib.h @@ -101,7 +101,7 @@ struct nxgl_point_s nxgl_coord_t y; /* Y position, range: 0 to screen height - 1 */ }; -/* Describes the size of a rectangulare region */ +/* Describes the size of a rectangular region */ struct nxgl_size_s { @@ -109,7 +109,7 @@ struct nxgl_size_s nxgl_coord_t h; /* Height in rows */ }; -/* Describes a rectangle on the display */ +/* Describes a positioned rectangle on the display */ struct nxgl_rect_s { @@ -329,7 +329,7 @@ EXTERN void nxgl_copyrectangle_32bpp(FAR struct fb_planeinfo_s *pinfo, * * Description: * This is essentially memcpy for rectangles. We don't do structure - * assignements because some compilers are not good at that. + * assignments because some compilers are not good at that. * ****************************************************************************/ @@ -402,7 +402,7 @@ EXTERN void nxgl_rectunion(FAR struct nxgl_rect_s *dest, * * Description: * Return the regions of rectangle rect 1 that do not intersect with - * rect2. This may be up to founr rectangles some of which may be + * rect2. This will be four rectangles ,some of which may be * degenerate (and can be picked off with nxgl_nullrect) * ****************************************************************************/ diff --git a/nuttx/include/nuttx/nxtk.h b/nuttx/include/nuttx/nxtk.h index d9466b9dc..8d2f08c6a 100644 --- a/nuttx/include/nuttx/nxtk.h +++ b/nuttx/include/nuttx/nxtk.h @@ -225,7 +225,7 @@ EXTERN int nxtk_fillwindow(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect, * Name: nxtk_filltrapwindow * * Description: - * Fill the specified rectangle in the client window with the specified color + * Fill the specified trapezoid in the client window with the specified color * * Input Parameters: * hfwnd - The window handle returned by nxtk_openwindow @@ -298,8 +298,8 @@ EXTERN int nxtk_bitmapwindow(NXTKWINDOW hfwnd, * Create a tool bar at the top of the specified framed window * * Input Parameters: - * hfwnd - The handle returned by nxtk_openwindow - * height - The request height of the toolbar in pixels + * hfwnd - The handle 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. * @@ -316,7 +316,7 @@ EXTERN int nxtk_opentoolbar(NXTKWINDOW hfwnd, nxgl_coord_t height, * Name: nxtk_closetoolbar * * Description: - * Create a tool bar at the top of the specified framed window + * Remove the tool bar at the top of the specified framed window * * Input Parameters: * hfwnd - The handle returned by nxtk_openwindow @@ -332,7 +332,7 @@ EXTERN int nxtk_closetoolbar(NXTKWINDOW hfwnd); * Name: nxtk_filltoolbar * * Description: - * Fill the specified rectangle in the client window with the specified color + * Fill the specified rectangle in the toolbar sub-window with the specified color * * Input Parameters: * hfwnd - The handle returned by nxtk_openwindow @@ -351,7 +351,7 @@ EXTERN int nxtk_filltoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect * Name: nxtk_filltraptoolbar * * Description: - * Fill the specified rectangle in the toolbar with the specified color + * Fill the specified trapezoid in the toolbar sub-window with the specified color * * Input Parameters: * hfwnd - The handle returned by nxtk_openwindow @@ -403,7 +403,7 @@ EXTERN int nxtk_movetoolbar(NXTKWINDOW hfwnd, FAR const struct nxgl_rect_s *rect * 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. + * stride - The width of the full source image in bytes. * * Return: * OK on success; ERROR on failure with errno set appropriately |
