font.h

Go to the documentation of this file.

/**
 * @file font.h
 * @brief Shared font support.
 */
#pragma once
#include <3ds/types.h>
 
///@name Data types
///@{
 
/// Character width information structure.
typedef struct
{
    s8 left;       ///< Horizontal offset to draw the glyph with.
    u8 glyphWidth; ///< Width of the glyph.
    u8 charWidth;  ///< Width of the character, that is, horizontal distance to advance.
} charWidthInfo_s;
 
/// Font texture sheet information.
typedef struct
{
    u8 cellWidth;    ///< Width of a glyph cell.
    u8 cellHeight;   ///< Height of a glyph cell.
    u8 baselinePos;  ///< Vertical position of the baseline.
    u8 maxCharWidth; ///< Maximum character width.
 
    u32 sheetSize; ///< Size in bytes of a texture sheet.
    u16 nSheets;   ///< Number of texture sheets.
    u16 sheetFmt;  ///< GPU texture format (GPU_TEXCOLOR).
 
    u16 nRows;  ///< Number of glyphs per row per sheet.
    u16 nLines; ///< Number of glyph rows per sheet.
 
    u16 sheetWidth;  ///< Texture sheet width.
    u16 sheetHeight; ///< Texture sheet height.
    u8* sheetData;   ///< Pointer to texture sheet data.
} TGLP_s;
 
/// Font character width information block type.
typedef struct tag_CWDH_s CWDH_s;
 
/// Font character width information block structure.
struct tag_CWDH_s
{
    u16 startIndex; ///< First Unicode codepoint the block applies to.
    u16 endIndex;   ///< Last Unicode codepoint the block applies to.
    CWDH_s* next;   ///< Pointer to the next block.
 
    charWidthInfo_s widths[0]; ///< Table of character width information structures.
};
 
/// Font character map methods.
enum
{
    CMAP_TYPE_DIRECT = 0, ///< Identity mapping.
    CMAP_TYPE_TABLE = 1,  ///< Mapping using a table.
    CMAP_TYPE_SCAN = 2,   ///< Mapping using a list of mapped characters.
};
 
/// Font character map type.
typedef struct tag_CMAP_s CMAP_s;
 
/// Font character map structure.
struct tag_CMAP_s
{
    u16 codeBegin;     ///< First Unicode codepoint the block applies to.
    u16 codeEnd;       ///< Last Unicode codepoint the block applies to.
    u16 mappingMethod; ///< Mapping method.
    u16 reserved;
    CMAP_s* next;      ///< Pointer to the next map.
 
    union
    {
        u16 indexOffset;   ///< For CMAP_TYPE_DIRECT: index of the first glyph.
        u16 indexTable[0]; ///< For CMAP_TYPE_TABLE: table of glyph indices.
        /// For CMAP_TYPE_SCAN: Mapping data.
        struct
        {
            u16 nScanEntries; ///< Number of pairs.
            /// Mapping pairs.
            struct
            {
                u16 code;       ///< Unicode codepoint.
                u16 glyphIndex; ///< Mapped glyph index.
            } scanEntries[0];
        };
    };
};
 
/// Font information structure.
typedef struct
{
    u32 signature;   ///< Signature (FINF).
    u32 sectionSize; ///< Section size.
 
    u8 fontType;                  ///< Font type
    u8 lineFeed;                  ///< Line feed vertical distance.
    u16 alterCharIndex;           ///< Glyph index of the replacement character.
    charWidthInfo_s defaultWidth; ///< Default character width information.
    u8 encoding;                  ///< Font encoding (?)
 
    TGLP_s* tglp; ///< Pointer to texture sheet information.
    CWDH_s* cwdh; ///< Pointer to the first character width information block.
    CMAP_s* cmap; ///< Pointer to the first character map.
 
    u8 height;  ///< Font height.
    u8 width;   ///< Font width.
    u8 ascent;  ///< Font ascent.
    u8 padding;
} FINF_s;
 
/// Font structure.
typedef struct
{
    u32 signature;  ///< Signature (CFNU).
    u16 endianness; ///< Endianness constant (0xFEFF).
    u16 headerSize; ///< Header size.
    u32 version;    ///< Format version.
    u32 fileSize;   ///< File size.
    u32 nBlocks;    ///< Number of blocks.
 
    FINF_s finf; ///< Font information.
} CFNT_s;
 
/// Font glyph position structure.
typedef struct
{
    int sheetIndex; ///< Texture sheet index to use to render the glyph.
    float xOffset;  ///< Horizontal offset to draw the glyph width.
    float xAdvance; ///< Horizontal distance to advance after drawing the glyph.
    float width;    ///< Glyph width.
    /// Texture coordinates to use to render the glyph.
    struct
    {
        float left, top, right, bottom;
    } texcoord;
    /// Vertex coordinates to use to render the glyph.
    struct
    {
        float left, top, right, bottom;
    } vtxcoord;
} fontGlyphPos_s;
 
/// Flags for use with fontCalcGlyphPos.
enum
{
    GLYPH_POS_CALC_VTXCOORD = BIT(0), ///< Calculates vertex coordinates in addition to texture coordinates.
    GLYPH_POS_AT_BASELINE   = BIT(1), ///< Position the glyph at the baseline instead of at the top-left corner.
    GLYPH_POS_Y_POINTS_UP   = BIT(2), ///< Indicates that the Y axis points up instead of down.
};
 
///@}
 
///@name Initialization and basic operations
///@{
 
/// Ensures the shared system font is mapped.
Result fontEnsureMapped(void);
 
/**
 * @brief Fixes the pointers internal to a just-loaded font
 * @param font Font to fix
 * @remark Should never be run on the system font, and only once on any other font.
 */
void fontFixPointers(CFNT_s* font);
 
/// Gets the currently loaded system font
static inline CFNT_s* fontGetSystemFont(void)
{
    extern CFNT_s* g_sharedFont;
    if (!g_sharedFont)
        fontEnsureMapped();
    return g_sharedFont;
}
 
/**
 * @brief Retrieves the font information structure of a font.
 * @param font Pointer to font structure. If NULL, the shared system font is used.
 */
static inline FINF_s* fontGetInfo(CFNT_s* font)
{
    if (!font)
        font = fontGetSystemFont();
    return &font->finf;
}
 
/**
 * @brief Retrieves the texture sheet information of a font.
 * @param font Pointer to font structure. If NULL, the shared system font is used.
 */
static inline TGLP_s* fontGetGlyphInfo(CFNT_s* font)
{
    if (!font)
        font = fontGetSystemFont();
    return fontGetInfo(font)->tglp;
}
 
/**
 * @brief Retrieves the pointer to texture data for the specified texture sheet.
 * @param font Pointer to font structure. If NULL, the shared system font is used.
 * @param sheetIndex Index of the texture sheet.
 */
static inline void* fontGetGlyphSheetTex(CFNT_s* font, int sheetIndex)
{
    if (!font)
        font = fontGetSystemFont();
    TGLP_s* tglp = fontGetGlyphInfo(font);
    return &tglp->sheetData[sheetIndex*tglp->sheetSize];
}
 
/**
 * @brief Retrieves the glyph index of the specified Unicode codepoint.
 * @param font Pointer to font structure. If NULL, the shared system font is used.
 * @param codePoint Unicode codepoint.
 */
int fontGlyphIndexFromCodePoint(CFNT_s* font, u32 codePoint);
 
/**
 * @brief Retrieves character width information of the specified glyph.
 * @param font Pointer to font structure. If NULL, the shared system font is used.
 * @param glyphIndex Index of the glyph.
 */
charWidthInfo_s* fontGetCharWidthInfo(CFNT_s* font, int glyphIndex);
 
/**
 * @brief Calculates position information for the specified glyph.
 * @param out Output structure in which to write the information.
 * @param font Pointer to font structure. If NULL, the shared system font is used.
 * @param glyphIndex Index of the glyph.
 * @param flags Calculation flags (see GLYPH_POS_* flags).
 * @param scaleX Scale factor to apply horizontally.
 * @param scaleY Scale factor to apply vertically.
 */
void fontCalcGlyphPos(fontGlyphPos_s* out, CFNT_s* font, int glyphIndex, u32 flags, float scaleX, float scaleY);
 
///@}