sergiotarxz/nuttx
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
c67502d9b4
nuttx/Documentation/components/libs/libnx/nxfonts.rst
raiden00pl d98ae9d3e4 Documentation: cosmetics changes 
- various style fixes
- limit the line length to about 80 characters to improve readability in terminal-based IDEs
2023-10-26 20:01:21 +08:00

272 lines
8.6 KiB
ReStructuredText
Raw Blame History

======
nxfont
======
This directory contains font support for NuttX. The contents of this directory
are only build if CONFIG_NXFONTS is defined in the NuttX configuration file.
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:
#. Locate a font in BDF format,
#. Use the bdf-converter program to convert the BDF font to the NuttX
font format. This will result in a C header file containing
definitions. 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:
#. Define ``CONFIG_NXFONT_MYFONT=y`` in your NuttX configuration file.
A font ID number has to be assigned for each new font. The font ID
is defined in the file ``include/nuttx/nx/nxfonts.h``. Those definitions
have to be extended to support your new font. Look at how the font ID
enabled by ``CONFIG_NXFONT_SANS23X27`` is defined and add an ID for your
new font in a similar fashion:
3. ``include/nuttx/nx/nxfonts.h`` Add you new font as a possible system
default font:
.. code-block:: C
#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 do this. Look how the build system uses the
font CONFIG_NXFONT_SANS23X27 for examaples:
#. ``nuttx/graphics/Makefile`` This file needs logic to auto-generate
a C source file from the header file that you generated with the
the bdf-converter program. Notice NXFONTS_FONTID=2; this must be
set to the same font ID value that you defined in the
``include/nuttx/nx/nxfonts.h`` file.
.. code-block:: make
genfontsources:
ifeq ($(CONFIG_NXFONT_SANS23X27),y)
@$(MAKE) -C nxfonts -f Makefile.sources NXFONTS_FONTID=1 EXTRAFLAGS=$(EXTRAFLAGS)
endif
ifeq ($(CONFIG_NXFONT_MYFONT),y)
@$(MAKE) -C nxfonts -f Makefile.sources NXFONTS_FONTID=2 EXTRAFLAGS=$(EXTRAFLAGS)
endif
#. ``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:
.. code-block:: make
ifeq ($(CONFIG_NXFONT_SANS23X27),y)
NXFSET_CSRCS += nxfonts_bitmaps_sans23x27.c
endif
ifeq ($(CONFIG_NXFONT_MYFONT),y)
NXFSET_CSRCS += nxfonts_bitmaps_myfont.c
endif
#. ``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):
.. code-block:: C
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
#. ``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.
.. code-block:: C
#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.
#. ``graphics/nxfonts/nxfonts_getfont.c``. Finally, we need to extend the
logic that does the run-time font lookups so that can find our new
font. The lookup function is NXHANDLE nxf_getfonthandle(enum nx_fontid_e fontid).
The new font information needs to be added to data structures used by
that function
.. code-block:: C
#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
======================
NxFonts
-------
* ``CONFIG_NXFONTS``
Enables font support
* ``CONFIG_NXFONTS_CHARBITS``
The number of bits in the character set. Current options are only 7 and 8.
The default is 7.
* ``CONFIG_NXFONTS_DISABLE_1BPP``, ``CONFIG_NXFONTS_DISABLE_2BPP``,
``CONFIG_NXFONTS_DISABLE_4BPP``, ``CONFIG_NXFONTS_DISABLE_8BPP``,
``CONFIG_NXFONTS_DISABLE_16BPP``, ``CONFIG_NXFONTS_DISABLE_24BPP``, and
``CONFIG_NXFONTS_DISABLE_32BPP``
NX supports a variety of pixel depths. You can save some memory by disabling
support for unused color depths.
* ``CONFIG_NXFONTS_PACKEDMSFIRST``
If a pixel depth of less than 8-bits is used, then NX needs to know if the
pixels pack from the MS to LS or from LS to MS
Font Selections
---------------
* ``CONFIG_NXFONT_SANS17X22``
This option enables support for a tiny, 17x22 san serif font
(font ID FONTID_SANS17X22 == 14).
* ``CONFIG_NXFONT_SANS20X26``
This option enables support for a tiny, 20x26 san serif font
(font ID FONTID_SANS20X26 == 15).
* ``CONFIG_NXFONT_SANS23X27``
This option enables support for a tiny, 23x27 san serif font
(font ID FONTID_SANS23X27 == 1).
* ``CONFIG_NXFONT_SANS22X29``
This option enables support for a small, 22x29 san serif font
(font ID FONTID_SANS22X29 == 2).
* ``CONFIG_NXFONT_SANS28X37``
This option enables support for a medium, 28x37 san serif font
(font ID FONTID_SANS28X37 == 3).
* ``CONFIG_NXFONT_SANS39X48``
This option enables support for a large, 39x48 san serif font
(font ID FONTID_SANS39X48 == 4).
* ``CONFIG_NXFONT_SANS17X23B``
This option enables support for a tiny, 17x23 san serif bold font
(font ID FONTID_SANS17X23B == 16).
* ``CONFIG_NXFONT_SANS20X27B``
This option enables support for a tiny, 20x27 san serif bold font
(font ID FONTID_SANS20X27B == 17).
* ``CONFIG_NXFONT_SANS22X29B``
This option enables support for a small, 22x29 san serif bold font
(font ID FONTID_SANS22X29B == 5).
* ``CONFIG_NXFONT_SANS28X37B``
This option enables support for a medium, 28x37 san serif bold font
(font ID FONTID_SANS28X37B == 6).
* ``CONFIG_NXFONT_SANS40X49B``
This option enables support for a large, 40x49 san serif bold font
(font ID FONTID_SANS40X49B == 7).
* ``CONFIG_NXFONT_SERIF22X29``
This option enables support for a small, 22x29 font (with serifs)
(font ID FONTID_SERIF22X29 == 8).
* ``CONFIG_NXFONT_SERIF29X37``
This option enables support for a medium, 29x37 font (with serifs)
(font ID FONTID_SERIF29X37 == 9).
* ``CONFIG_NXFONT_SERIF38X48``
This option enables support for a large, 38x48 font (with serifs)
(font ID FONTID_SERIF38X48 == 10).
* ``CONFIG_NXFONT_SERIF22X28B``
This option enables support for a small, 27x38 bold font (with serifs)
(font ID FONTID_SERIF22X28B == 11).
* ``CONFIG_NXFONT_SERIF27X38B``
This option enables support for a medium, 27x38 bold font (with serifs)
(font ID FONTID_SERIF27X38B == 12).
p
* ``CONFIG_NXFONT_SERIF38X49B``
This option enables support for a large, 38x49 bold font (with serifs)
(font ID FONTID_SERIF38X49B == 13).
[REVISIT... this list is not complete]
Reference in New Issue View Git Blame Copy Permalink