charstr Subroutine

Purpose

Draws a string of raster characters on the screen.

Libraries

Graphics Library

C (libgl.a)

FORTRAN (libfgl.a)

C Syntax

void charstr(Char8 *string)

FORTRAN Syntax

SUBROUTINE CHARST(string, length)
CHARACTER*(*) string
INTEGER*4 length

Description

The charstr subroutine draws a string of text, using the current raster font. After each character is drawn, the character width is added to the current character position. The text string is drawn in the current raster font and color, using the current writemask.

Characters that are not defined in the current raster font are treated as having zero size and are therefore ignored.

The charstr subroutine supports both single- and double-byte raster character renderings.

If the current font is a double-byte font, this subroutine expects the first two bytes to represent the first character, the second two bytes to represent the next character, and so on. Double-byte fonts are useful in languages with extremely large character sets such as Japanese and Chinese.

If the current font is a single-byte font, each byte represents one character. The ASCII code set is an example of a single-byte font.

It is the user's responsibility to determine if the currently bound font is a single- or double-byte font and to pass the appropriate string. To determine the font type, use the getfonttype subroutine.

Character Clipping

The beginning of the string is positioned at the current character position. The string is drawn from left to right, parallel to the surface of the screen. The string is fine clipped to the rectangular area defined with the scrnmask subroutine. The current color and writemask are used. Characters not defined in the current raster font are assumed to have zero width and are not drawn.

Strings drawn by the charstr subroutine are subject to clipping and z-buffering. The algorithmic details of this process are as follows:

1. Trivial accept/trivial reject test. If the start point of the test string (after transformation by all matrices) is not within the NDC unit cube (-w<x,y,z<+w< x,y,z < +1.0) then the entire string is trivially rejected (not drawn).
2. If the preceding test passes, then z-buffering proceeds on a pixel-by-pixel basis. At the start point, the string is mapped to window-relative pixel coordinates. The z-value of the reference point is used as the z-value of the entire string. Then, for every pixel of every letter in the string:
   1. If that pixel is outside of the screenmask, the pixel is not drawn.
   2. If the pixel is inside the screenmask, then use z-compare. If the z-test passes, then update the frame buffer, and update the z-buffer (for that pixel only).

Glyph Lookup for SBCS and DBCS Strings

Each character of the string should be thought of as a glyph index. That is, each byte (for an SBCS font) or each pair of bytes (for a DBCS font) serves as an index into a table of raster glyphs. The table of glyphs is the table that was loaded with the defrasterfont subroutine or the loadXfont subroutine. The mapping of glyph indices to glyphs is a constant, and is locale-independent. There is no processing or translation that is applied to the glyph index before the raster is looked up. The raw value is used unmodified. A single null byte is sufficient to indicate end-of-string for ordinary (single-byte) fonts; a null short integer (two consecutive null bytes) is required to terminate a DBCS string.

Because the charstr routine does not perform any translation and conversion, it is left up to the application to make sure that appropriate fonts are loaded, and that multibyte text strings are converted into sequences of glyph indices. Some tools for performing such conversions are provided by the base operating system.

Note: The default font (font index 0) is locale-dependent; during initialization, a different default font is loaded, depending on the locale. The default font is always chosen from the iso8859 family of fonts.

Parameters

Example

The example C language programs curved.c and font3.c use the charstr subroutine to draw a character string in the current raster font.

Implementation Specifics

This subroutine is part of GL in the AIXwindows Environment/6000 Version 1, Release 2 with AIXwindows/3D Feature.

Files

Related Information

Determining the font format with the getfonttype subroutine.

Determining the font name with the getfontencoding subroutine.

Moving the current character position with the cmov subroutine.

Defining bitmaps for a raster font with the defrasterfont subroutine.

Selecting a raster font with the font subroutine.

Returning the width of the specified text string with the strwidth subroutine.

National Language Support Overview for Programming in AIX General Programming Concepts: Writing and Debugging Programs.

Creating Text Characters.