Draws a text string into a bitmap.

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

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.

• 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.

lib3do.lib, textlib.h

''%%DrawTextChar%%''