Use a handle instead of an ID in each font lookup; this saves doing the font set lookup each time

git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@3802 42af7a65-404d-4744-a932-0658087f49c3

ChangeLog

@@ -1928,3 +1928,8 @@
 	  not being coordinated correctly.
 	* configs/stm3210e-eval/nsh2: Enable FAT long file name support
 	* sched/sem_timedwait.c: Add the standard sem_timedwait() interface.
+	* graphics/nxfonts/nxfonts_getfont.c, nxfonts_bitmap.c,
+	  Makefile.source, and include/nuttx/nxfonts.h: Support for multiple
+	  fonts included.  A new interface, nxf_getfonthandle() takes a font
+	  ID and returns a handle that is now used at all other font interfaces
+	  to specify which of the multiple fonts to use.

Documentation/NXGraphicsSubsystem.html

@@ -153,9 +153,10 @@
    <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.2 <a href="#nxfgetfonthandle"><code>nxf_getfonthandle()</code></a></i><br>
-        <i>2.5.3 <a href="#nxfgetbitmap"><code>nxf_getbitmap()</code></a></i><br>
+        <i>2.5.3 <a href="#nxfgetfontset"><code>nxf_getfontset()</code></a></i><br>
-        <i>2.5.4 <a href="#nxfconvertbpp"><code>nxf_convert_*bpp()</code></a></i>
+        <i>2.5.4 <a href="#nxfgetbitmap"><code>nxf_getbitmap()</code></a></i><br>
+        <i>2.5.5 <a href="#nxfconvertbpp"><code>nxf_convert_*bpp()</code></a></i>
      </ul>
    </p>
    <p>
@@ -2396,13 +2397,36 @@ struct nx_font_s
 };
 </pre></ul>
 
-<h3>2.5.2 <a name="nxfgetfontset"><code>nxf_getfontset()</code></a></h3>
+<h3>2.5.2 <a name="nxfgetfonthandle"><code>nxf_getfonthandle()</code></a></h3>
+<p><b>Function Prototype:</b></p>
+<ul><pre>
+#include &lt;nuttx/nxfonts.h&gt;
+
+NXHANDLE nxf_getfonthandle(enum nx_fontid_e fontid);
+</pre></ul>
+<p>
+  <b>Description:</b>
+  Given a numeric font ID, return a handle that may be subsequently be used to access the font data sets.
+</p>
+<p>
+  <b>Input Parameters:</b>
+  <ul><dl>
+    <dt><code>fontid</code>
+    <dd>Identifies the font set to use
+  </dl></ul>
+</p>
+<p>
+  <b>Returned Value:</b>
+  A handle that may be subsequently be used to access the font data sets.
+</p>
+
+<h3>2.5.3 <a name="nxfgetfontset"><code>nxf_getfontset()</code></a></h3>
 <p><b>Function Prototype:</b></p>
 <ul><pre>
 #include &lt;nuttx/nxglib.h&gt;
 #include &lt;nuttx/nxfonts.h&gt;
 
-FAR const struct nx_font_s *nxf_getfontset(enum nx_fontid_e fontid);
+FAR const struct nx_font_s *nxf_getfontset(NXHANDLE handle);
 </pre></ul>
 <p>
   <b>Description:</b>
@@ -2411,8 +2435,8 @@ FAR const struct nx_font_s *nxf_getfontset(enum nx_fontid_e fontid);
 <p>
   <b>Input Parameters:</b>
   <ul><dl>
-    <dt><code>fontid</code>
+    <dt><code>handle</code>
-    <dd>Identifies the font set to get
+    <dd>A font handle previously returned by <code>nxf_getfonthandle()</code>.
   </dl></ul>
 </p>
 <p>
@@ -2420,13 +2444,13 @@ FAR const struct nx_font_s *nxf_getfontset(enum nx_fontid_e fontid);
   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>
+<h3>2.5.4 <a name="nxfgetbitmap"><code>nxf_getbitmap()</code></a></h3>
 <p><b>Function Prototype:</b></p>
 <ul><pre>
 #include &lt;nuttx/nxglib.h&gt;
 #include &lt;nuttx/nxfonts.h&gt;
 
-FAR const struct nx_fontbitmap_s *nxf_getbitmap(uint16_t ch, enum nx_fontid_e fontid);
+FAR const struct nx_fontbitmap_s *nxf_getbitmap(NXHANDLE handle, uint16_t ch);
 </pre></ul>
 <p>
   <b>Description:</b>
@@ -2436,9 +2460,9 @@ FAR const struct nx_fontbitmap_s *nxf_getbitmap(uint16_t ch, enum nx_fontid_e fo
   <b>Input Parameters:</b>
   <ul><dl>
     <dt><code>ch</code>
-    <dd>
+    <dd>The char code for the requested bitmap.
-    <dt><code>fontid</code>
+    <dt><code>handle</code>
-    <dd>Identifies the font set to use
+    <dd>A font handle previously returned by <code>nxf_getfonthandle()</code>.
   </dl></ul>
 </p>
 <p>
@@ -2446,7 +2470,7 @@ FAR const struct nx_fontbitmap_s *nxf_getbitmap(uint16_t ch, enum nx_fontid_e fo
   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>
+<h3>2.5.5 <a name="nxfconvertbpp"><code>nxf_convert_*bpp()</code></a></h3>
 <p><b>Function Prototype:</b></p>
 <ul><pre>
 #include &lt;nuttx/nxglib.h&gt;
@@ -2505,13 +2529,27 @@ int nxf_convert_32bpp(FAR uint32_t *dest, uint16_t height,
 
 <h2>2.6 <a name="samplecode">Sample Code</a></h2>
 
-<p><b><code>apps/examples/nx</code></b>.
+<p><b><code>apps/examples/nx*</code></b>.
   No sample code is provided in this document.
-  However, an example can be found in the NuttX source tree at <code>apps/examples/nx</code>.
+  However, examples can be found in the NuttX source tree at the follow locations:
-  That code is intended to test NX.
+  That example code is intended to test NX.
-  Since it is test code, it is designed to exercise functionality and does not necessarily
+  Since it is test code, it is designed to exercise functionality and does not necessarily represent best NX coding practices.
-  represent best NX coding practices.
 </p>
+<ul>
+  <li><code>apps/examples/nx</code>.
+    This is a test of windows, optionally with toolbars.
+    Two windows are created, re-sized, moved, raise lowered.
+    Simulated mouse and keyboard input is provided.
+  </li>
+  <li><code>apps/examples/nxhello</code>.
+    This is intended to be simplest NX test:
+    It simply displays the words &quot;Hello, World!&quot; centered on the display.
+  </li>
+  <li><code>apps/examples/nxtext</code>.
+    This illustrates how fonts may be managed to provide scrolling text windows.
+    Pop-up windows are included to verify the clipping and re-drawing of the text display.
+  </li>
+</ul>
 
 <p>
   In its current form, the NX graphics system provides a low level of graphics and window
@@ -2963,13 +3001,17 @@ make
 </tr>
 <tr>
   <td align="left" valign="top"><a href="#nxrequestbkgd"><code>nx_requestbkgd()</code></a></td>
-  <td><br></td>
+  <td>
-  <td align="center" bgcolor="lightgrey">NO</td>
+    Verified by <code>apps/examples/nxtext</code> and <code>apps/examples/nxhello</code>.
+  </td>
+  <td align="center" bgcolor="skyblue">YES</td>
 </tr>
 <tr>
   <td align="left" valign="top"><a href="#nxreleasebkgd"><code>nx_releasebkgd()</code></a></td>
-  <td><br></td>
+  <td>
-  <td align="center" bgcolor="lightgrey">NO</td>
+    Verified by <code>apps/examples/nxtext</code> and <code>apps/examples/nxhello</code>.
+  </td>
+  <td align="center" bgcolor="skyblue">YES</td>
 </tr>
 <tr>
   <td align="left" valign="top"><a href="#nxgetposition"><code>nx_getposition()</code></a></td>
@@ -3142,6 +3184,11 @@ make
   <th width="60%">Special Setup/Notes</th>
   <th width="5%">Verified</th></tr>
 </tr>
+<tr>
+  <td align="left" valign="top"><a href="#nxfgetfonthandle"><code>nxf_getfonthandle()</code></a></td>
+  <td><br></td>
+  <td align="center" bgcolor="skyblue">YES</td>
+</tr>
 <tr>
   <td align="left" valign="top"><a href="#nxfgetfontset"><code>nxf_getfontset()</code></a></td>
   <td><br></td>
@@ -3170,7 +3217,7 @@ make
 <tr>
   <td align="left" valign="top"><a href="#nxfconvertbpp"><code>nxf_convert_16bpp()</code></a></td>
   <td><br></td>
-  <td align="center" bgcolor="lightgrey">NO</td>
+  <td align="center" bgcolor="skyblue">YES</td>
 </tr>
 <tr>
   <td align="left" valign="top"><a href="#nxfconvertbpp"><code>nxf_convert_24bpp()</code></a></td>

graphics/nxfonts/nxfonts_bitmaps.c

@@ -1620,30 +1620,6 @@ NXFONT_DEFMETRIC(255),
 };
 #endif
 
-static const struct nx_fontset_s NXF_SYMNAME(NXFONTS_PREFIX,7bitfonts) =
-{
-  NXFONT_MIN7BIT,                      /* First glyph code */
-  NXFONT_N7BITFONTS,                   /* Number of bitmap glyphs */
-  NXF_SYMNAME(NXFONTS_PREFIX,7bitmaps) /* List of glyphs */
-};
-
-#if CONFIG_NXFONTS_CHARBITS >= 8
-static const struct nx_fontset_s NXF_SYMNAME(NXFONTS_PREFIX,8bitfonts) =
-{
-  NXFONT_MIN8BIT,                      /* First glyph code */
-  NXFONT_N8BITFONTS,                   /* Number of bitmap glyphs */
-  NXF_SYMNAME(NXFONTS_PREFIX,8bitmaps) /* List of glyphs */
-};
-#endif
-
-static const struct nx_font_s NXF_SYMNAME(NXFONTS_PREFIX,fonts) =
-{
-  NXFONT_MAXHEIGHT,                    /* Max. height of a glyph in rows */
-  NXFONT_MAXWIDTH,                     /* Max. width of a glyph in pixels */
-  CONFIG_NXFONTS_CHARBITS,             /* Max number of bits per character code */
-  NXFONT_SPACEWIDTH,                   /* The width of a space in pixels */
-};
-
 /****************************************************************************
  * Public Data
  ****************************************************************************/
@@ -1651,10 +1627,23 @@ static const struct nx_font_s NXF_SYMNAME(NXFONTS_PREFIX,fonts) =
 const struct nx_fontpackage_s NXF_SYMNAME(NXFONTS_PREFIX,package) =
 {
   NXFONT_ID,                             /* The font ID */
-  &NXF_SYMNAME(NXFONTS_PREFIX,fonts),      /* Font set metrics */
+  {                                      /*  Font set metrics: */
-  &NXF_SYMNAME(NXFONTS_PREFIX,7bitfonts)   /* Fonts for 7-bit encoding */
+    NXFONT_MAXHEIGHT,                    /*   Max. height of a glyph in rows */
+    NXFONT_MAXWIDTH,                     /*   Max. width of a glyph in pixels */
+    CONFIG_NXFONTS_CHARBITS,             /*   Max number of bits per character code */
+    NXFONT_SPACEWIDTH,                   /*   The width of a space in pixels */
+  },
+  {                                      /* Fonts for 7-bit encoding */
+    NXFONT_MIN7BIT,                      /* First glyph code */
+    NXFONT_N7BITFONTS,                   /* Number of bitmap glyphs */
+    NXF_SYMNAME(NXFONTS_PREFIX,7bitmaps) /* List of glyphs */
+  }
 #if CONFIG_NXFONTS_CHARBITS >= 8
-  , &NXF_SYMNAME(NXFONTS_PREFIX,8bitfonts) /* Fonts for 8-bit encoding */
+, {                                      /* Fonts for 8-bit encoding */
+    NXFONT_MIN8BIT,                      /* First glyph code */
+    NXFONT_N8BITFONTS,                   /* Number of bitmap glyphs */
+    NXF_SYMNAME(NXFONTS_PREFIX,8bitmaps) /* List of glyphs */
+  }
 #endif
 };
 

graphics/nxfonts/nxfonts_getfont.c

@@ -43,6 +43,7 @@
 #include <stddef.h>
 #include <debug.h>
 
+#include <nuttx/nx.h>
 #include <nuttx/nxfonts.h>
 
 #include "nxfonts_internal.h"
@@ -79,43 +80,6 @@ static FAR const struct nx_fontpackage_s *g_fontpackages[] =
  * Private Functions
  ****************************************************************************/
 
-/****************************************************************************
- * Name: nxf_findpackage
- *
- * Description:
- *   Find the font package associated with the provided font ID.
- *
- * Input Parameters:
- *   fontid:  Identifies the font set to get
- *
- ****************************************************************************/
-
-static FAR const struct nx_fontpackage_s *nxf_findpackage(enum nx_fontid_e fontid)
-{
-  FAR const struct nx_fontpackage_s **pkglist;
-  FAR const struct nx_fontpackage_s *package;
-
-  /* Handle the default font package */
-
-  if (fontid == FONTID_DEFAULT)
-   {
-     fontid = NXFONT_DEFAULT;
-   }
-
-  /* Then search for the font package with this ID */
-
-  for (pkglist = g_fontpackages; *pkglist; pkglist++)
-    {
-      package = *pkglist;
-      if (package->id == fontid)
-        {
-          return package;
-        }
-    }
-
-  return NULL;
-}
-
 /****************************************************************************
  * Name: nxf_getglyphset
  *
@@ -140,14 +104,14 @@ static inline FAR const struct nx_fontset_s *
     {
       /* Select the 7-bit font set */
 
-      fontset = package->font7;
+      fontset = &package->font7;
     }
   else if (ch < 256)
     {
 #if CONFIG_NXFONTS_CHARBITS >= 8
       /* Select the 8-bit font set */
 
-      fontset = package->font8;
+      fontset = &package->font8;
 #else
       gdbg("8-bit font support disabled: %d\n", ch);
       return NULL;
@@ -177,26 +141,66 @@ static inline FAR const struct nx_fontset_s *
  ****************************************************************************/
 
 /****************************************************************************
- * Name: nxf_getfontset
+ * Name: nxf_getfonthandle
  *
  * Description:
- *   Return information about the current font set
+ *   Given a numeric font ID, return a handle that may be subsequently be
+ *   used to access the font data sets.
  *
  * Input Parameters:
  *   fontid:  Identifies the font set to get
  *
  ****************************************************************************/
 
-FAR const struct nx_font_s *nxf_getfontset(enum nx_fontid_e fontid)
+NXHANDLE nxf_getfonthandle(enum nx_fontid_e fontid)
 {
+  FAR const struct nx_fontpackage_s **pkglist;
+  FAR const struct nx_fontpackage_s *package;
+
+  /* Handle the default font package */
+
+  if (fontid == FONTID_DEFAULT)
+   {
+     fontid = NXFONT_DEFAULT;
+   }
+
+  /* Then search for the font package with this ID */
+
+  for (pkglist = g_fontpackages; *pkglist; pkglist++)
+    {
+      package = *pkglist;
+      if (package->id == fontid)
+        {
+          return (NXHANDLE)package;
+        }
+    }
+
+  return (NXHANDLE)NULL;
+}
+
+/****************************************************************************
+ * Name: nxf_getfontset
+ *
+ * Description:
+ *   Return information about the current font set
+ *
+ * Input Parameters:
+ *   handle:  A font handle previously returned by nxf_getfonthandle
+ *
+ ****************************************************************************/
+
+FAR const struct nx_font_s *nxf_getfontset(NXHANDLE handle)
+{
+  FAR const struct nx_fontpackage_s *package =
+    (FAR const struct nx_fontpackage_s *)handle;
+
   /* Find the font package associated with this font ID */
 
-  FAR const struct nx_fontpackage_s *package = nxf_findpackage(fontid);
   if (package)
     {
       /* Found... return the font set metrics for this font package */
 
-      return package->metrics;
+      return &package->metrics;
     }
 
   return NULL;
@@ -209,23 +213,23 @@ FAR const struct nx_font_s *nxf_getfontset(enum nx_fontid_e fontid)
  *   Return font bitmap information for the selected character encoding.
  *
  * Input Parameters:
- *   ch:      Character code
+ *   handle:  A font handle previously returned by nxf_getfonthandle
- *   fontid:  Identifies the font set to use
+ *   ch:      Character code whose bitmap is requested
+ *
+ * Returned Value:
+ *   An instance of struct nx_fontbitmap_s describing the glyph.
  *
  ****************************************************************************/
 
-FAR const struct nx_fontbitmap_s *nxf_getbitmap(uint16_t ch,
+FAR const struct nx_fontbitmap_s *nxf_getbitmap(NXHANDLE handle, uint16_t ch)
-                                                enum nx_fontid_e fontid)
 {
-  /* Find the font package associated with this font ID */
+  FAR const struct nx_fontpackage_s *package =
-
+    (FAR const struct nx_fontpackage_s *)handle;
-  FAR const struct nx_fontpackage_s *package;
   FAR const struct nx_fontset_s     *fontset;
   FAR const struct nx_fontbitmap_s  *bm  = NULL;
 
-  /* Get the font package associated with the font ID */
+  /* Verify that the handle is a font package */
 
-  package = nxf_findpackage(fontid);
   if (package)
     {
       /* Now get the fontset from the package */

include/nuttx/nxfonts.h

@@ -43,6 +43,8 @@
 #include <nuttx/config.h>
 
 #include <stdint.h>
+
+#include <nuttx/nx.h>
 #include <nuttx/nxglib.h>
 
 /****************************************************************************
@@ -117,10 +119,10 @@ struct nx_font_s
 struct nx_fontpackage_s
 {
   uint8_t id;                            /* The font ID */
-  FAR const struct nx_font_s    *metrics; /* Font set metrics */
+  FAR const struct nx_font_s    metrics; /* Font set metrics */
-  FAR const struct nx_fontset_s *font7;   /* Fonts for 7-bit encoding */
+  FAR const struct nx_fontset_s font7;   /* Fonts for 7-bit encoding */
 #if CONFIG_NXFONTS_CHARBITS >= 8
-  FAR const struct nx_fontset_s *font8;   /* Fonts for 8-bit encoding */
+  FAR const struct nx_fontset_s font8;   /* Fonts for 8-bit encoding */
 #endif
 };
 
@@ -141,17 +143,31 @@ extern "C" {
  ****************************************************************************/
 
 /****************************************************************************
- * Name: nxf_getfontset
+ * Name: nxf_getfonthandle
  *
  * Description:
- *   Return information about the current font set
+ *   Given a numeric font ID, return a handle that may be subsequently be
+ *   used to access the font data sets.
  *
  * Input Parameters:
  *   fontid:  Identifies the font set to get
  *
  ****************************************************************************/
 
-EXTERN FAR const struct nx_font_s *nxf_getfontset(enum nx_fontid_e fontid);
+EXTERN NXHANDLE nxf_getfonthandle(enum nx_fontid_e fontid);
+
+/****************************************************************************
+ * Name: nxf_getfontset
+ *
+ * Description:
+ *   Return information about the current font set
+ *
+ * Input Parameters:
+ *   handle:  A font handle previously returned by nxf_getfonthandle()
+ *
+ ****************************************************************************/
+
+EXTERN FAR const struct nx_font_s *nxf_getfontset(NXHANDLE handle);
 
 /****************************************************************************
  * Name: nxf_getbitmap
@@ -160,8 +176,8 @@ EXTERN FAR const struct nx_font_s *nxf_getfontset(enum nx_fontid_e fontid);
  *   Return font bitmap information for the selected character encoding.
  *
  * Input Parameters:
- *   ch:      Character code
+ *   handle:  A font handle previously returned by nxf_getfonthandle()
- *   fontid:  Identifies the font set to use
+ *   ch:      Character code whose bitmap is requested
  *
  * Returned Value:
  *   An instance of struct nx_fontbitmap_s describing the glyph.
@@ -169,7 +185,7 @@ EXTERN FAR const struct nx_font_s *nxf_getfontset(enum nx_fontid_e fontid);
  ****************************************************************************/
 
 EXTERN FAR const struct nx_fontbitmap_s *
-  nxf_getbitmap(uint16_t ch, enum nx_fontid_e fontid);
+  nxf_getbitmap(NXHANDLE handle, uint16_t ch);
 
 /****************************************************************************
  * Name: nxf_convert_*bpp