glcIntro(3G)
glcIntro - Introduction to the OpenGL Character Renderer
As shipped in IRIX 6.5.15. Last changed in IRIX 6.5.15.
NAME glcIntro - 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 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); 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 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 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. 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/tools/glc/fontmap.c /usr/share/src/OpenGL/tools/glc/glcspec.ps SEE ALSO glcRenderChar, glintro