Blitz3D+ Command Reference

SetFontSheetSpacing font,spacing

Parameters

font - a font handle returned by LoadFontSheet

spacing - pixels to add between adjacent characters; may be negative

Description

Changes the letter spacing of a font sheet.

Positive values push characters apart, negative values pull them together or even overlap them, and 0 - the value a freshly loaded sheet starts with - leaves the artwork's own metrics alone. It is the quick way to make a title font feel airy, to tighten a cramped HUD font so a long score still fits, or to fix a sheet that was authored with too much padding.

The spacing is added between adjacent characters after any kerning the sheet defines, and nothing is added after the last character, so a string does not gain a trailing gap. It is measured in output pixels, which means it looks the same size whatever the atlas's native line height and whatever height you passed to LoadFontSheet.

The change takes effect immediately for Text, Print and Write, including centred text, and StringWidth measures with it - so your layout maths stays correct. FontWidth and the width of a single character are unaffected, since spacing only exists between characters.

The setting belongs to the one font handle you name. Passing an ordinary system font handle from LoadFont is an error.

Requires Extended mode.

See also: LoadFontSheet, FontSheetError, StringWidth, SetFont, Text.

Example

; SetFontSheetSpacing Example
; ---------------------------
; Requires Extended mode.

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

; Load a bitmap font sheet (the .fnt descriptor names its PNG atlas)
sheet=LoadFontSheet("../../../samples/font-sheets/assets/glossy_cyan_techno_font_atlas_game.fnt",36)
If sheet=0 Then RuntimeError FontSheetError()

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

spacing=0

While Not KeyDown(1)

    ; [ / ] tighten or spread the letter spacing
    If KeyHit(27) And spacing<16 Then spacing=spacing+2
    If KeyHit(26) And spacing>-8 Then spacing=spacing-2

    ; SetFontSheetSpacing adds signed output pixels between characters:
    ; negative values tighten, positive values spread
    SetFontSheetSpacing sheet,spacing

    Cls

    SetFont sheet
    ; StringWidth reflects the new spacing immediately
    w=StringWidth("abc xyz 09")
    Color 255,255,255
    Text 320,140,"SPACING",True
    Color 180,255,255
    Text 320,230,"abc xyz 09",True

    SetFont info_font
    Color 255,255,255
    Text 0,0,"[ / ] change letter spacing   Esc: exit"
    Text 0,20,"SetFontSheetSpacing sheet,"+spacing
    Text 0,40,"StringWidth(abc xyz 09) = "+w+" pixels"

    Flip

Wend

FreeFont sheet

End

Index