3. Font Management

This chapter describes the management of fonts. The rendering of characters by applications is described in subsequent chapters.

The Font library provides the Font class as a base class, the ResFont class for manipulating font resources loaded into memory, the ArchiveFont class and PackedFont class for manipulating archived font resources, and the PairFont class for handling two fonts as a single font. Note that we recommend using UTF16-LE as the encoding for font resources, because this is the encoding used by other CTR-SDK libraries to handle strings.

The following figure illustrates the hierarchy of the Font library classes (with derived classes on the right). In your application, select from among the classes along the right edge of the figure and create instances of these classes as necessary depending on how you use font resources.

Figure 3-1. Hierarchy of Classes (for Font Management)

Font ResFontBase ResFont ArchiveFontBase ArchiveFont PackedFont PairFont

 

3.1. Font Class

This is the base class for handling font resources, but this class itself is never instantiated. When the Font library classes are used to render characters, textures (sheets upon which glyph images are drawn) are loaded by directly referencing main memory, so the application must prepare a buffer in device memory for the font (the images). The restrictions placed on the location of this memory are described in the individual classes that inherit from this class.

Table 3-1 is a list of the member functions defined in the Font class. Note that as a general rule, when these functions get parameters they return values in pixels.

Table 3-1. List of Member Functions of the Font Class
Category Function Description
Get font information







GetWidth Returns the font width. Used to determine the tab width and perform similar tasks.
GetHeight Returns the font height.
GetAscent Returns the ascent. Used to align the upper edges of characters.
GetDescent Returns the descent. Used to align the lower edges of characters.
GetMaxCharWidth Returns the maximum character width of all of the characters contained in the font.
GetType Returns the font type.
GetTextureFormat Returns the format of the sheet (the texture).
GetLineFeed Returns the linefeed width.
GetDefaultCharWidths Returns the default character width information. Used as the character width for characters not contained in the font and for other anomalous widths.
Set font information

SetLineFeed Resets the linefeed width.
SetDefaultCharWidths Resets the default character width information.
SetAlternateChar Sets alternate characters.
Get character information


GetCharWidth Returns the character width of a character.
GetCharWidths Returns the character width information of a character.
GetGlyph Glyph information. Returns the glyph of an alternate character if the glyph of the specified character is not contained in the font.
HasGlyph Returns whether the glyph of the specified character is contained in the font.

String

Encoding

GetCharacterCode Returns the character encoding.
GetCharStrmReader The CharWriter class is used when drawing characters with the Font library.
Gets sheet information.

GetBaselinePos Returns the baseline position.
GetCellHeight Returns the cell height.
GetCellWidth Returns the cell width.
Texture interpolation


EnableLinearFilter When rendering characters with the Font library, sets whether to use linear interpolation when scaling characters.
IsLinearFilterEnableAtSmall When rendering characters with the Font library, returns whether linear interpolation is used when scaling down characters.
IsLinearFilterEnableAtLarge When rendering characters with the Font library, returns whether linear interpolation is used when scaling up characters.
GetTextureWrapFilterValue When rendering characters with the Font library, returns the wrapping mode and filter settings.

3.2. ResFont Class

This is a class for manipulating font resources. It is not compatible with grouping, so when using this class all sheets are loaded in memory. For this reason, the entire font resource must be loaded in memory.

Font resources (BCFNT files) loaded in memory are bound to the ResFont class by the SetResource() function. When the Font library classes are used to render characters, the glGenTextures() function is used to create one texture object for each sheet contained in the font resource. These created texture objects are configured so that the GPU directly accesses their texture images. Accordingly, the font resource must be loaded into device memory using 128-byte alignment (defined by nn::font::GlyphDataAlignment). Unbind the resource using the RemoveResource() function. Do not release the buffer into which the font resource was loaded until the resource is unbound.

When the Font library classes are used to render characters, a render buffer having the size returned by the GetDrawBufferSize() function must be set using the SetDrawBuffer() function, but there is no need to allocate the render buffer in device memory. The render buffer must be aligned using the nn::font::ResFont::BUFFER_ALIGNMENT (4 byte) value.

3.2.1. System Fonts

With 3DS, font resources called system fonts are stored in system memory. The application can use the PL library to use these system fonts as shared font resources.

Calling the nn::pl::InitializeSharedFont() function starts the loading of the system fonts corresponding to the 3DS system region, and the loading is complete when the nn::pl::GetSharedFontLoadState() function returns nn::pl::SHARED_FONT_LOAD_STATE_LOADED. Font resources loaded by this procedure are loaded to fixed addresses (physical addresses outside of application jurisdiction), so they do not consume any application memory.

The nn::pl::GetSharedFontType() function gets the type of the system fonts, which are loaded based on the 3DS system’s region. To use a system font of a type not returned by this function, you must use the nn::pl::MountSharedFont() function to mount the system font archive and then have the application load the font resource file. The files are compressed in LZ77 format, so they must be uncompressed using the CX Library. Also note that each type of system font must be mounted separately, and that the uncompressed font resources must be placed in device memory to render characters with the Font library. When the loading of font resources is complete, unmount the archive with the nn::pl::UnmountSharedFont() function.

Note:

For more information about loading system fonts, see the 3DS Programming Manual: System.

3.3. ArchiveFont Class

This is a class for manipulating archived fonts. The glyphs within the font files are organized into groups, so you can uncompress and load into memory sheets containing just the specified groups. (Multiple groups can be specified.) To specify groups, either use LOAD_GLYPH_ALL, which loads all glyphs, or use a string containing the names of the groups to load delimited by commas (",").

There are two ways to construct fonts: (1) you can construct fonts from archived font data that is already loaded in memory, or (2) you can load the data into memory as a stream to reduce the amount of memory required for loading. Use the Construct() function for the former method and the InitStreamingConstruct and StreamingConstruct() functions for the latter. Font data is compressed, but the font images are decompressed and loaded into memory. Use the GetRequireBufferSize() function to get the size of the buffer required to construct the font. (The data is decompressed into this buffer.) When the Font library classes are used to render characters, the buffer must be allocated in device memory using 128-byte alignment.

After the font is constructed, the memory used to load archived fonts can be released, but the buffer used to construct the font cannot be released until the font is destroyed. Destroy the font using the Destroy() function. When this function destroys a font, it returns a pointer to the buffer for you to then release.

3.4. PackedFont Class

Like the ArchiveFont class, the PackedFont class is a class for manipulating archived fonts. However, by using this class, you can maintain font resources in memory in compressed form and decompress and use them as needed. Although decompressing the sheet corresponding to a particular character entails a processing load, this class implements a cache so that the load is reduced somewhat. By managing the proportion of data left in the cache and locking the sheets, you can prevent cache misses.

The PackedFont class uses the same font construction methods as the ArchiveFont class. When calculating the size of the buffer, specify the number or proportion of the sheets to be left in the cache. The following functions are provided for managing the cache: GetNumCache which gets the number of cacheable sheets, PreloadSheet which preloads the cache with sheets, LockSheet which locks sheets, UnlockSheet which unlocks individual sheets and UnlockSheetAll which unlocks all sheets.

After the font is constructed, the memory used to load archived fonts can be released, but the buffer used to construct the font cannot be released until the font is destroyed. Destroy the font using the Destroy() function. When this function destroys a font, it returns a pointer to the buffer for you to then release.

3.5. PairFont Class

This class inherits the Font class and enables you to use two fonts that have the same character encoding and same texture format as a single font. Note that problems with the display positions of characters might occur when combining fonts that have different baseline positions.

When an instance of the PairFont class is constructed, the font specified first is called the primary font and the font specified next is the secondary font. When you get parameters using this class, the class returns parameters for either the primary font or secondary font in accordance with the conditions in the following table.

Table 3-2. Parameters of the PairFont Class
Parameter Parameter Returned
Font width Greatest value among the two fonts.
Font height
Maximum character width
Ascent

The value for the font that has the largest font height.

If both fonts have the same height, the value for the primary font is returned.

Descent
Baseline
Cell height
Line feed width
Cell width

The value for the font that has the largest font width.

If both fonts have the same width, the value for the primary font is returned.

Default character width
Getting glyphs

The primary font takes priority.

The glyph from the secondary font is returned if the specified character is not present in the primary font. The alternate character from the primary font is returned if the specified character is not in either font. However, if an alternate character is set after the instance was constructed, and that alternate character is not present in the primary font but is present in the secondary font, the alternate character from the secondary font is returned.

Alternate character

The primary font takes priority.

However, if an alternate character is set after the instance was constructed, and that alternate character is not present in the primary font but is present in the secondary font, the alternate character from the secondary font is returned.


CONFIDENTIAL