DrawTextString

Draws a text string into a bitmap.

Synopsis

void DrawTextString (FontDescriptor *fDesc, GrafCon *gcon,Item bitmapItem, char *text,...)

Description

Draws a text string directly into a bitmap, using the colors and x/y coordinates specified in the GrafCon. The text string can be a simple string of characters or a printf-style format string followed by additional arguments. If you use printf-style formatting, the resulting formatted string cannot exceed 1024 characters. A maximum of ten printf-style % formatting directives can appear in the string.

The GrafCon's pen coordinates are interpreted as integer (not Frac16) values. After the call, the GrafCon's gc_PenX and gc_PenY fields have been updated to reflect the space the character pixels occupy within the bitmap. A newline character moves the gc_PenY value down by the font's height + leading value, and sets gc_PenX to its entry-time value. The net effect is that when there are multiple lines of text, each line begins in the column specified by the initial value of gc_PenX.

The foreground and background colors follow the usual rules for cels: a color of 000 results in transparent output, for opaque black use 001.

If you use typical double-buffering screen logic, it is more efficient to use a TextCel to hold your text string and redraw it on each frame with DrawScreenCels() than to rerender the string directly into the screen bitmap on each frame update.

Arguments

fDesc
Pointer to a FontDescriptor structure.
gcon
Pointer to a GrafCon structure containing the foreground and background colors and pen x/y coordinates to use in rendering the character.
bitmapItem
Bitmap into which the character is rendered.
text
String of characters to be rendered, optionally including printf-style % formatting commands.
...
Optional arguments for printf-style formatting.

Associated Files

lib3do.lib, textlib.h

See Also

DrawTextChar