CHGfx_gfxfont.h

Go to the documentation of this file.

/**
 * @file CHGfx_gfxfont.h
 * @brief The bitmap font container, GFXfont, byte-for-byte Adafruit_GFX's.
 *
 * This is deliberately, byte-for-byte, Adafruit_GFX's gfxfont.h layout,
 * down to the include guard. Two consequences, both wanted:
 *
 *   1. Every font header ever generated by Adafruit's fontconvert - the
 *      whole Fonts/ directory of Adafruit_GFX, and the hundreds of
 *      converted fonts floating around - drops straight into
 *      gfx_setFont() with no translation.
 *   2. Fonts shipped with CHGfx work unchanged under Adafruit_GFX's own
 *      setFont(), including through CHGfx_AdafruitGFX.h.
 *
 * The shared `_GFXFONT_H_` guard means whichever header is included first
 * defines the types and the other one steps aside. That only works
 * because the definitions match, so do not "improve" the field order.
 *
 * CHGfx.h includes it; a sketch never needs to. The bundled fonts are
 * listed under @ref chgfx_fonts.
 */
#ifndef _GFXFONT_H_
#define _GFXFONT_H_
 
#include <stdint.h>
 
/**
 * @brief One glyph's record in a GFXfont: where its bitmap is, its size,
 * and where it sits relative to the pen.
 * @ingroup chgfx_fonts
 *
 * A glyph is drawn relative to the pen position (x, y), where y is the
 * BASELINE, not the top:
 *
 * - upper-left corner = (x + xOffset, y + yOffset) (yOffset is negative)
 * - next pen position = (x + xAdvance, y)
 * - next line         = y + GFXfont::yAdvance
 */
typedef struct {
    uint16_t bitmapOffset;  /**< byte offset of this glyph's first row     */
    uint8_t  width;         /**< bitmap width in pixels                    */
    uint8_t  height;        /**< bitmap height in pixels                   */
    uint8_t  xAdvance;      /**< pen movement after drawing                */
    int8_t   xOffset;       /**< pen x -> bitmap left edge                 */
    int8_t   yOffset;       /**< baseline -> bitmap top edge (negative up) */
} GFXglyph;
 
/**
 * @brief A whole bitmap font, for gfx_setFont(): glyph bitmaps, glyph
 * records, the character range and the line spacing.
 * @ingroup chgfx_fonts
 *
 * `first`..`last` is a contiguous character range; glyph[] has
 * last-first+1 entries. The two pointers are non-const to match
 * Adafruit's struct, which is why every font header casts on init.
 *
 * bitmap is one flat MSB-first bitstream with all glyphs concatenated.
 * A glyph occupies exactly width*height bits starting at bitmapOffset;
 * rows are NOT padded to byte boundaries, so glyph row r begins at bit
 * bitmapOffset*8 + r*width.
 *
 * Fonts are made with `extras/fontconvert.py` (or Adafruit's own
 * fontconvert); see @ref chgfx_fonts.
 */
typedef struct {
    uint8_t  *bitmap;       /**< concatenated glyph bitstreams             */
    GFXglyph *glyph;        /**< glyph records, one per character          */
    uint16_t  first;        /**< first character code present             */
    uint16_t  last;         /**< last character code present               */
    uint8_t   yAdvance;     /**< baseline-to-baseline line spacing         */
} GFXfont;
 
#endif /* _GFXFONT_H_ */