Add JP's BDF font conversion program

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

2 files changed, 146 insertions, 6 deletions

diff --git a/nuttx/graphics/README.txt b/nuttx/graphics/README.txt
index c99a72809..378f71a9d 100644
--- a/nuttx/graphics/README.txt
+++ b/nuttx/graphics/README.txt
@@ -4,6 +4,14 @@ README
 This directory contains tiny graphics support for NuttX.  The contents of this directory
 are only build if CONFIG_NX is defined in the NuttX configuration file.
 
+Contents
+^^^^^^^^
+  Roadmap
+  Related Header Files
+  Directories
+  Installing New Fonts
+  Configuration Settings
+
 Roadmap
 ^^^^^^^
 
@@ -37,8 +45,8 @@ include/nutt/nxtk.h       -- Describe the NXTOOLKIT C interfaces
 include/nutt/nxfont.h     -- Describe sthe NXFONT C interfaces
 include/nuttx/nxwidgets.h -- Will describe the NXWIDGETS classes (no longer planned)
 
-Directories:
-^^^^^^^^^^^^
+Directories
+^^^^^^^^^^^
 
 graphics/nxglib
   The NuttX tiny graphics library.  The directory contains generic utilities
@@ -80,6 +88,142 @@ graphics/nxtk
 graphics/nxwidgets
   At one time, I planned to put NXWIDGETS implementation here, but not anymore.
 
+Installing New Fonts
+^^^^^^^^^^^^^^^^^^^^
+
+  There is a tool called bdf-converter in the directory tools/.  The bdf-converter
+  program be used to convert fonts in Bitmap Distribution Format (BDF)
+  into fonts that can be used in the NX graphics system.
+
+  Below are general instructions for creating and installing a new font
+  in the NX graphic system:
+
+    1. Locate a font in BDF format,
+    2. Use the bdf-converter program to convert the BDF font to the NuttX
+       font format.  This will result in a C header file containing
+       defintions.  That header file should be installed at, for example,
+       graphics/nxfonts/nxfonts_myfont.h.
+
+  Create a new NuttX configuration variable.  For example, suppose
+  you define the following variable:  CONFIG_NXFONT_MYFONT.  Then
+  you would need to:
+  
+    3. Define CONFIG_NXFONT_MYFONT=y in your NuttX configuration file.
+
+  A font ID number has to be assigned for each new font.  The font ID
+  is defined in the file include/nuttx/nxfonts.h.  Those definitions
+  have to be extended to support your new font.  Look at how the font ID
+  enabled by CONFIG_NXFONT_SANS23X27 is defined and add an ID for your
+  new font in a similar fashion:
+
+    4. include/nuttx/nxfonts.h. Add you new font as a possible system
+       default font:
+ 
+       #if defined(CONFIG_NXFONT_SANS23X27)
+       # define NXFONT_DEFAULT FONTID_SANS23X27
+       #elif defined(CONFIG_NXFONT_MYFONT)
+       # define NXFONT_DEFAULT FONTID_MYFONT
+       #endif
+
+       Then define the actual font ID.  Make sure that the font ID value
+       is unique:
+ 
+       enum nx_fontid_e
+       {
+         FONTID_DEFAULT     = 0      /* The default font */
+       #ifdef CONFIG_NXFONT_SANS23X27
+         , FONTID_SANS23X27 = 1      /* The 23x27 sans serif font */
+       #endif
+       #ifdef CONFIG_NXFONT_MYFONT
+         , FONTID_MYFONT    = 2      /* My shiny, new font */
+       #endif
+       ...
+ 
+  New Add the font to the NX build system.  There are several files that
+  you have to modify to to this.  Look how the build system uses the
+  font CONFIG_NXFONT_SANS23X27 for examaples:
+
+    5. nuttx/graphics/Makefile.  This file needs logic to auto-generate
+       a C source file from the header file that you generated with the
+       the bdf-converter program.  Notice NXFONTS_FONTID=2; this must be
+       set to the same font ID value that you defined in the
+       include/nuttx/nxfonts.h file.
+
+       genfontsources:
+         ifeq ($(CONFIG_NXFONT_SANS23X27),y)
+	      @$(MAKE) -C nxfonts -f Makefile.sources TOPDIR=$(TOPDIR) NXFONTS_FONTID=1 EXTRADEFINES=$(EXTRADEFINES)
+        endif
+         ifeq ($(CONFIG_NXFONT_MYFONT),y)
+	      @$(MAKE) -C nxfonts -f Makefile.sources TOPDIR=$(TOPDIR) NXFONTS_FONTID=2 EXTRADEFINES=$(EXTRADEFINES)
+        endif
+
+    6. nuttx/graphics/nxfonts/Make.defs.  Set the make variable NXFSET_CSRCS.
+       NXFSET_CSRCS determines the name of the font C file to build when
+       NXFONTS_FONTID=2:
+
+       ifeq ($(CONFIG_NXFONT_SANS23X27),y)
+       NXFSET_CSRCS	+= nxfonts_bitmaps_sans23x27.c
+       endif
+       ifeq ($(CONFIG_NXFONT_MYFONT),y)
+       NXFSET_CSRCS	+= nxfonts_bitmaps_myfont.c
+       endif
+
+    7. nuttx/graphics/nxfonts/Makefile.sources.  This is the Makefile used
+       in step 5 that will actually generate the font C file.  So, given
+       your NXFONTS_FONTID=2, it needs to determine a prefix to use for
+       auto-generated variable and function names and (again) the name of
+       the autogenerated file to create (this must be the same name that
+       was used in nuttx/graphics/nxfonts/Make.defs):
+
+       ifeq ($(NXFONTS_FONTID),1)
+       NXFONTS_PREFIX	:= g_sans23x27_
+       GEN_CSRC	= nxfonts_bitmaps_sans23x27.c
+       endif
+       ifeq ($(NXFONTS_FONTID),2)
+       NXFONTS_PREFIX	:= g_myfont_
+       GEN_CSRC	= nxfonts_bitmaps_myfont.c
+       endif
+
+    8. graphics/nxfonts/nxfonts_bitmaps.c.  This is the file that contains
+       the generic font structures.  It is used as a "template" file by
+       nuttx/graphics/nxfonts/Makefile.sources to create your customized
+       font data set.
+
+       #if NXFONTS_FONTID == 1
+       #  include "nxfonts_sans23x27.h"
+       #elif NXFONTS_FONTID == 2
+       #  include "nxfonts_myfont.h"
+       #else
+       #  error "No font ID specified"
+       #endif
+
+       Where nxfonts_myfont.h is the NuttX font file that we generated in
+       step 2 using the bdf-converter tool.
+
+    9. Finally, we need to extend the logic that does the run-time font
+       lookups so that can find our new font.  The lookup function is
+       NXHANDLE nxf_getfonthandle(enum nx_fontid_e fontid).  The new
+       font information needs to be added to data structures used by
+       that function:
+ 
+       #ifdef CONFIG_NXFONT_SANS23X27
+       extern const struct nx_fontpackage_s g_sans23x27_package;
+       #endif
+       #ifdef CONFIG_NXFONT_MYFONT
+       extern const struct nx_fontpackage_s g_myfont_package;
+       #endif
+
+       static FAR const struct nx_fontpackage_s *g_fontpackages[] =
+       {
+       #ifdef CONFIG_NXFONT_SANS23X27
+       &g_sans23x27_package,
+       #endif
+       #ifdef CONFIG_NXFONT_MYFONT
+       &g_myfont_package,
+       #endif
+       NULL
+       };
+
 Configuration Settings
 ^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/nuttx/graphics/nxfonts/nxfonts_internal.h b/nuttx/graphics/nxfonts/nxfonts_internal.h
index 54c574fdc..889d573b1 100644
--- a/nuttx/graphics/nxfonts/nxfonts_internal.h
+++ b/nuttx/graphics/nxfonts/nxfonts_internal.h
@@ -54,10 +54,6 @@
 #  define CONFIG_NXFONTS_CHARBITS 7
 #endif
 
-/* Only font supported for now */
-
-#define CONFIG_NXFONT_SANS23X27 1
-
 /****************************************************************************
  * Public Types
  ****************************************************************************/