glcIntro(3G) OpenGL Character Renderer glcIntro(3G)NAMEglcIntro - Introduction to the OpenGL Character Renderer
DOCUMENTATION
The most authoritative documentation on GLC is the GLC specification
document, which is included in this release in PostScript form. If you
install the software product gl_dev.sw.samples, the GLC specification
will be installed as /usr/share/src/OpenGL/teach/glc/glcspec.ps.
OVERVIEW
The OpenGL Character Renderer (GLC) is a subroutine library that provides
OpenGL programs with character rendering services.
A GLC context is an instantiation of the GLC state machine. A GLC client
is a program that uses both OpenGL (henceforth, "GL") and GLC. When a
client thread issues a GLC command, the thread's current GLC context
executes the command.
To render a character, a GLC client issues the command
glcRenderChar(GLint inCode);
GLC then goes through these steps:
1. GLC finds a font that maps inCode to a character such as LATIN
CAPITAL LETTER A.
2. GLC uses one or more glyphs from the font to create a graphical
layout that represents the character.
3. GLC issues a sequence of GL commands to draw the layout.
A font is a stylistically consistent set of glyphs that can be used to
render some set of characters. Each font has a family name (e.g.
Palatino) and a state variable that selects one of the faces (e.g.
Regular, Bold, Italic, Bold Italic) that the font contains. A typeface is
the combination of a family and a face (e.g. Palatino Bold).
A font is an instantiation of a master. A master is a representation of
the font that is stored outside of GLC in a standard format such as Type
1.
A catalog is a file containing a list of master file names. A list of
catalog names (GLC_CATALOG_LIST) defines the list of masters that can be
instantiated in a GLC context. When a GLC context is created,
GLC_CATALOG_LIST initially contains one name:
("/usr/lib/X11/fonts/Type1").
By default, GLC interprets all character codes as elements of the
Page 1
glcIntro(3G) OpenGL Character Renderer glcIntro(3G)
Universal Coded Set (UCS) defined by ISO 10646-1:1993.
The interpretation of arrays of character codes of type GLCchar in the
GLC API is determined by the value of the GLC context state variable
GLC_STRING_TYPE. The values GLC_UCS1, GLC_UCS2, and GLC_UCS4 specify that
each array element is a UCS code of type GLubyte, GLushort, or GLint,
respectively. The initial value of GLC_STRING_TYPE is GLC_UCS1.
Before issuing a GLC rendering command, a client must issue GL commands
directly to establish a GL state such that the GL commands issued by GLC
produce the desired result. For example, before issuing a glcRenderChar
command, a client may issue glColor and glRasterPos commands to establish
the color and origin of the resulting layout.
Before issuing any GLC commands, the client must create a GL context and
make it current.
Layout
Glyph coordinates are defined in em units and are transformed during
rendering to produce the desired mapping of the glyph shape into the GL
window coordinate system.
In addition to commands for rendering, the GLC API includes measurement
commands that return certain metrics (currently the bounding box and the
baseline) for the layout.
Since the focus of GLC is on rendering and not modeling, the GLC API does
not provide access to glyph shape data.
EXAMPLES
The following ISO C code fragment uses GL and GLC to render the character
LATIN CAPITAL LETTER A in red at (100, 100) using a default typeface at a
scale of 24 pixels per em. In this example, GLC issues a glBitmap command
to draw the layout.
glcContext(glcGenContext());
glcScale(24.f, 24.f);
glColor3f(1.f, 0.f, 0.f);
glRasterPos2f(100.f, 100.f);
glcRenderChar(`A');
In the following example, GLC renders the string "Hello, world!" in red
24 pixel Palatino Bold at a rotation of 30 degrees, starting at (100,
100).
glcContext(glcGenContext());
glcFont (glcNewFontFromFamily(1, "palatino"));
glcFontFace(1, "bold");
glcScale(24.f, 24.f);
glcRotate(30.f);
Page 2
glcIntro(3G) OpenGL Character Renderer glcIntro(3G)
glColor3f(1.f, 0.f, 0.f);
glRasterPos2f(100.f, 100.f);
glcRenderString("Hello, world!");
NOTES
- The current implementation of GLC implements only a subset of the
GLC specification.
- The implementation specific constants for the current
implementation are as follows: GLC_EXTENSIONS="",
GLC_RELEASE="IRIX 6.2", GLC_VENDOR="SGI".
- The only language bindings that are currently available for GLC
are C and C++.
- The GLC API is designed to handle 10646-1 codepoints larger than
255, but support for these codepoints is not implemented in the
current release.
- The GLC API is designed to support a variety of master formats,
but the current implementation supports only masters in PostScript
Type 1 text format (.pfa files).
- In the current implementation, a catalog file must be in the
format generated by the X Window System utility program
mkfontdir(1). Future releases may use a different catalog file
format.
- The current implementation maps the Type 1 .pfa files in
/usr/lib/X11/fonts/Type1 into master objects that are visible
through the GLC API. A group of .pfa files from a single typeface
family will be mapped into a single GLC master object that has
multiple faces. For example, the files AvantGarde-Book.pfa,
AvantGarde-BookOblique.pfa, AvantGarde-Demi.pfa, and
AvantGarde-DemiOblique.pfa are visible through the GLC API as a
single master with GLC_VENDOR="Adobe", GLC_FAMILY="ITC Avant Garde
Gothic", GLC_MASTER_FORMAT="Type 1", GLC_FACE_COUNT=4, and
GLC_FACE_LIST=("Book", "Book Oblique", "Demi", Demi Oblique").
- Future releases may provide mechanisms to control the ordering of
masters in a catalog and the ordering of each master's face list.
Future releases may also change the default orderings of masters
and faces. Therefore, GLC clients should not depend on any
particular ordering of masters or faces.
- The GLC specification requires that a master's character map (and
hence a font's initial character map) must be strictly based on
10646-1. A GLC client that wants to use a different character
mapping must issue a sequence of glcFontMap commands to obtain the
required mapping. Subroutines that issue glcFontMap command
sequences to set up the most popular mappings are available in
Page 3
glcIntro(3G) OpenGL Character Renderer glcIntro(3G)
source code form (see below).
The argument inCharName to glcFontMap is the 10646-1 name of the
character to be mapped, e.g. "LATIN CAPITAL LETTER A". These
names are documented in the Unicode 2.0 standard.
The non 10646-1 character mappings that are used most commonly
with Type 1 masters are Adobe Standard, Adobe Symbol, and Adobe
Zapf Dingbats. The information needed to set up these mappings
via glcFontMap commands can be found in the Unicode 2.0 standard.
For example, the Adobe Zapf Dingbats encoding maps the code 0xD5
to U+2192. The Unicode 2.0 name of this character is RIGHTWARDS
ARROW. To set up the Adobe encoding for this character, issue the
command
glcFontMap(f, 0xD5, "RIGHTWARDS ARROW");
In general, GLC uses 10646-1 character names, not Adobe glyph
names. If, however, a master supports characters that are not
contained in 10646-1, GLC uses the Adobe glyph names for these
characters. For example, the ligature glyphs "fi" and "fl" are
not contained in 10646-1 and hence are never mapped in a master's
character map, but they may be contained in a master's
GLC_CHAR_LIST and can be mapped via glcFontMap.
If your application uses Adobe character mappings, install the
software product gl_dev.sw.samples and use the subroutines in
/usr/share/src/OpenGL/tools/glc/fontmap.c to issue the sequence of
glcFontMap commands that is necessary to establish the desired
mappings.
BUGS
The following is a list of known GLC bugs in the current release.
Application developers should take care to not write code that depends on
the presence of these bugs, which will be removed in a future release.
- The current implementation has been tested with the Type 1 master
files that SGI ships, but may not work properly with third party
Type 1 master files.
- The current implementation does not work properly with the
following SGI-shipped typefaces: Adobe Carta, Adobe Copal
Decorated. Using these typefaces in GLC may lead to program
termination.
- In the current implementation, the following commands raise
GLC_STATE_ERROR and return zero: glcGetFontMasterArray,
glcNewFontFromMasterArray.
- In the current implementation, the following command raises
Page 4
glcIntro(3G) OpenGL Character Renderer glcIntro(3G)
GLC_PARAMETER_ERROR: glcRenderStyle(GLC_TEXTURE)
- In the current implementation, the following state variables can
be set and retrieved, but they have no effect: GLC_MIPMAP,
GLC_RESOLUTION.
- The current implementation ignores the state variable
GLC_RESOLUTION and computes all metrics at 1000 pixels per em.
When rendering with GLC_RENDER_STYLE == GLC_BITMAP at lower
resolutions, returned metrics may not match the rendered layout.
- In the current implementation, the state variable
GLC_TEXTURE_OBJECT_LIST always contains zero elements.
- In the current implementation, the master/font attribute
GLC_VERSION) is always the empty string ("").
- In the current implementation, the character maps of masters
contain no entries larger than 255, and the following commands
raise GLC_PARAMETER_ERROR if inCode is greater than 255:
glcFontMap, glcGetFontMap, glcGetMasterMap.
As a result, most of the characters supported by the masters
Symbol and ITC Zapf Dingbats, which have 10646-1 codepoints that
are larger than 255, are not mapped. To use these characters,
issue a sequence of glcFontMap commands to map codes smaller than
256 to these characters. Subroutines that do this for you are
available in source code form (see above).
- In the current implementation, the following commands truncate all
incoming character codes to the low order 8 bits (the specified
behavior is to truncate to the low order 31 bits):
glcAppendCatalog, glcPrependCatalog, glcFontFace, glcFontMap,
glcNewFontFromFamily.
- The current implementation does not conform to the specified
behavior of rendering a character in the form \<hexcode> if a
font that maps the character cannot be found.
- In the current implementation, the GLC current-context state
variable is per-process, not per-thread.
- In the current implementation, the GLC current-error variable is
stored in the current GLC context, not in thread-local storage.
- The current implementation does not conform to the specified
behavior of issuing the commands glGetString(GL_VERSION) and
glGetString(GL_EXTENSIONS) when the command glcContext is
executed.
- The current implementation ignores the following environment
variables: GLC_CATALOG_LIST, GLC_LIST_SEPARATOR.
Page 5
glcIntro(3G) OpenGL Character Renderer glcIntro(3G)FILES
/usr/include/GL/glc.h
/usr/lib/libGLC.so
/usr/lib32/libGLC.so
/usr/lib64/libGLC.so
/usr/lib/X11/fonts/Type1/fonts.dir
/usr/lib/X11/fonts/Type1/*.pfa
/usr/share/src/OpenGL/teach/glc/fontmap.c
/usr/share/src/OpenGL/teach/glc/glcspec.ps
SEE ALSO
glcRenderChar, glintro
Page 6
