LoadFontSheet ( datafile$[,height] )

Parameters

datafile$ - path to a bitmap font descriptor, in JSON or BMFont text (.fnt) format

height (optional) - line height in output pixels; 0 uses the descriptor's own line height (default)

Description

Loads a bitmap font sheet and returns an ordinary font handle.

A font sheet is artwork rather than a system typeface: one RGBA image holding every character, plus a descriptor file saying where each one lives. That gets you a font that looks identical on every machine, needs nothing installed, and can be as decorative as you like - a chunky arcade face, a hand-drawn fantasy script, an icon set you print like text.

What comes back is a normal font handle, so it works with SetFont, Text, Print, Write, FontWidth, FontHeight, StringWidth and FreeFont exactly like one from LoadFont. The current Color multiplies the sheet's RGB while leaving its alpha alone, so a white sheet can be tinted to any colour at draw time. Use SetFontSheetSpacing to tighten or loosen the gap between characters.

The descriptor's image path is resolved relative to the descriptor file itself, so keep the two together. Pass a height to scale the whole font to that many output pixels per line; leave it at 0 to draw at the atlas's native size.

The command returns 0 when the descriptor or its image is missing or invalid, rather than stopping your program with a dialog - call FontSheetError for the reason. Version 1 JSON descriptors and unpacked text BMFont .fnt files are supported; binary, XML, packed and multi-page BMFont data are not.

Requires Extended mode.

See also: SetFontSheetSpacing, FontSheetError, SetFont, FreeFont, LoadFont, Text.

Example

; LoadFontSheet Example
; ---------------------
; Requires Extended mode.

Graphics 640,480,0,2
SetBuffer BackBuffer()

; The .fnt descriptor names the PNG atlas stored beside it
sheet_file$="../../../samples/font-sheets/assets/glossy_cyan_techno_font_atlas_game.fnt"

; LoadFontSheet(datafile$[,height]) returns an ordinary font handle;
; height sets the output line height in pixels
height=36
sheet=LoadFontSheet(sheet_file$,height)
If sheet=0 Then RuntimeError FontSheetError()

; A small system font for the info overlay
info_font=LoadFont("Arial",14)

While Not KeyDown(1)

    ; Keys 1-3 reload the sheet at a different output line height
    new_height=0
    If KeyHit(2) Then new_height=24
    If KeyHit(3) Then new_height=36
    If KeyHit(4) Then new_height=48
    If new_height<>0 And new_height<>height Then
        FreeFont sheet
        height=new_height
        sheet=LoadFontSheet(sheet_file$,height)
        If sheet=0 Then RuntimeError FontSheetError()
    End If

    Cls

    ; The bitmap font works with the normal Text command
    SetFont sheet
    Color 255,255,255
    Text 320,150,"LEVEL UP!",True

    ; The current Color tints the atlas image
    pulse=155+Sin(MilliSecs()/4.0)*100
    Color pulse,255,255
    Text 320,240,"abc xyz 09",True

    SetFont info_font
    Color 255,255,255
    Text 0,0,"1-3: line height 24/36/48   Esc: exit"
    Text 0,20,"LoadFontSheet(sheet_file$,"+height+") handle: "+sheet

    Flip

Wend

FreeFont sheet

End

Index

Blitz3D+ Command Reference

LoadFontSheet ( datafile$[,height] )

Parameters

Description

Example