Machine definition

Data types

GLC uses GL data types and defines additional types, which are listed in the table below :

GLC data types
Type	Definition
GLCchar	Character code array element
GLCenum	32 bits enumerant
GLCfunc	Callback function pointer

Like OpenGL, GLC detects only a subset of those conditions that could be considered errors. This is because in many cases error checking would adversely impact the performance of an error-free program. The command glcGetError() is used to obtain error information.

Each client thread has a private GLC error code variable of type GLCenum. The initial value of this variable is GLC_NONE. If a GLC command raises an error, and the value of this variable is GLC_NONE, the command stores the error's code in the variable. Hence, after an error has been detected, no new error code is recorded until glcGetError() is called.

If a GLC command raises an error, the command will have no effect except the possible storing of the error's code. If the generating command returns a value, it returns zero. If the generating command modifies values through a pointer argument, no change is made to these values.

GLC error semantics apply only to GLC errors and not to GL errors or system errors (e.g. memory access errors) that occur during GLC command execution. If GL errors occur during the execution of a GLC command, they are left unchanged to the user. GLC errors and GL errors are orthogonal, that is no GLC error depends on the occurence of a GL error. Especially, the GL_OUT_OF_MEMORY error may occur during the execution of a GLC command while no GLC_RESOURCE_ERROR may be raised.

Every GLC command execution begins with a test to determine if the command parameters are valid. If this test fails, the command raises GLC_PARAMETER_ERROR. Otherwise, GLC performs a test to determine if its state is such that the command is valid. If this test fails, the command raises GLC_STATE_ERROR. Otherwise, command execution proceeds. If at any point during command execution a needed resource (e.g. memory) is unavailable, the command raises GLC_RESOURCE_ERROR.

Finally, if memory is exhausted during the execution of a command, QuesoGLC tries to recover from such a critical error, but the result is undefined.

Contexts

A GLC context is an instantiation of GLC. When a client thread issues a GLC command, the thread's current GLC context executes the command.

Each GLC context has a nonzero ID of type GLint. When a client is linked with a GLC library, the library maintains a list of IDs that contains one entry for each of the client's GLC contexts. This list is initially empty.

Each client thread has a private GLC context ID variable that always contains either the value zero, indicating that the thread has no current GLC context, or the ID of the thread's current GLC context. The initial value of this variable is zero.

When the ID of a GLC context is stored in the GLC context ID variable of a client thread, the context is said to be current to the thread. It is not possible for a GLC context to be current simultaneously to multiple threads.

With the exception of the per-thread GLC error code and context ID variables, all of the GLC state variables that are used during execution of a GLC command are stored in the issuing thread's current GLC context.

Each GLC command belongs to one of the following categories : Global, Context, Master, Font, Transformation, Rendering and Measurement. Global commands do not use GLC context state variables and can therefore be executed successfully if the issuing thread has no current GLC context. All other GLC commands raise GLC_STATE_ERROR if the issuing thread has no current GLC context.

This document identifies explicitly the situations in which GLC may issue GL commands. In some GL implementations, the execution behavior of a GL command is defined only if the GL client has previously created a GL context and made it current to the issuing thread. It is the responsability of the GLC client to set up the underlying GL implementation such that whenever GLC issues a GL command, the execution behavior of that command is defined.

The behavior of GLC depends on the extension set and version of the underlying GL implementation. When a GLC context is made current to a thread, GLC issues the commands

glGetString(GL_VERSION);
glGetString(GL_EXTENSIONS);

and stores the returned strings.

Character codes

Except where otherwise specified, every character code in GLC is an element of the Unicode Character Database (UCD) defined by the standards Unicode 4.0.1 and ISO/IEC 10646:2003. A Unicode code point is denoted as U+hexcode, where hexcode is a sequence of hexadecimal digits. Each Unicode code point corresponds to a character that has a unique name string. For example, the code U+41 corresponds to the character LATIN CAPITAL LETTER A.

Strings

Except where otherwise specified, every character string used in the GLC API is represented as a zero terminated array of Unicode code point values. The type of these values is declared statically as GLCchar, but the actual type of these values is determined dynamically by the value of the variable GLC_STRING_TYPE. The values GLC_UCS1, GLC_UCS2, GLC_UCS4 and GLC_UTF8 specify how GLC should interpret the character codes and that each value is of type GLubyte, GLushort, GLuint, or GLushort, respectively. The initial value of GLC_STRING_TYPE is GLC_UCS1.

Some GLC commands return strings. The return value of these commands is a pointer to a string return buffer in the issuing thread's current GLC context. This pointer is valid until the next GLC command is issued. The pointer may be used as a parameter to the next GLC command. The client must copy the returned string to a client provided buffer if the value of the string will be needed after the next GLC command is issued.

The value of a character code in a returned string may exceed the range of the character encoding selected by GLC_STRING_TYPE. In this case, the returned character is converted to a character sequence \<hexcode>, where \ is the character REVERSE SOLIDUS (U+5C), < is the character LESS-THAN SIGN (U+3C), > is the character GREATER-THAN SIGN (U+3E), and hexcode is the original character code represented as a sequence of hexadecimal digits. The sequence has no leading zeros, and alphabetic digits are in upper case.

Constants

GLC defines a set of implementation specific constants. The integer constants GLC_VERSION_MAJOR and GLC_VERSION_MINOR identify the version of GLC that the implementation supports. These constants correspond to a version A.B of the GLC specification. If a new version breaks compatibility, the major version number A will be incremented by one. Otherwise, the minor version number B will be incremented by one.

The string constant GLC_VENDOR identifies the vendor of the implementation.

The string constant GLC_EXTENSIONS lists in alphabetical order the names of the GLC extensions that are supported by the implementation. One space (U+20) separates each pair of adjacent names. Example: "GLC_EXT_kern GLC_SGI_ligature".

The string constant GLC_RELEASE identifies the vendor specific software release that contains the implementation.

Generated on Sun Sep 3 21:06:34 2006 for QuesoGLC by