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 figure below 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.
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 below 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.
Category | Function | Description |
---|---|---|
Get font information |
|
Returns the font width. Used to determine the tab width and perform similar tasks. |
|
Returns the font height. | |
|
Returns the ascent. Used to align the upper edges of characters. | |
|
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
function. When the Font library classes are used to render characters, the SetResource
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 (requiring 4-byte alignment) 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.
3.2.1. System Fonts
With 3DS, font resources called internal fonts are stored in system memory. The application can use the PL library to use these internal fonts as shared font resources.
Calling the nn::pl::InitializeSharedFont
function starts the loading of the internal 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 internal fonts, which are loaded based on the 3DS system’s region. To use an internal font of a type not returned by this function, you must use the nn::pl::MountSharedFont
function to mount the internal 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 internal 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.
For more information about loading internal 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, using this class font resources can be maintained in memory in compressed form and decompressed and used 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 is derived from the Font
class and is a class for using 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.
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. |