<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>Machine definition</title>
<link href="quesoglc.css" rel="stylesheet" type="text/css">
</head><body>
<table>
<tr valign="top">
<td width="190" align="center">
<table class="qmenu" cellspacing="0">
<tr>
<td class="qglobal">
<ul class="qmenu">
<li class="mainmenu"><a href="index.html" >Main</a></li>
</ul>
</td>
</tr>
<tr>
<td class="qtitle">Tutorials</td>
</tr>
<tr>
<td class="qglobal">
<ul class="qmenu">
<li class="mainmenu"><a href="tutorial.html">First Steps</a></li>
<li class="mainmenu"><a href="tutorial2.html">Measurement</a></li>
</ul>
</td>
</tr>
<tr>
<td class="qtitle">Documentation</td>
</tr>
<tr>
<td class="qglobal">
<ul class="qmenu">
<li class="mainmenu"><a href="overview.html">Overview</a></li>
<li class="mainmenu"><a href="glyph.html">Glyph conventions</a></li>
<li class="mainmenu"><a href="machinedef.html">Machine definition</a></li>
<li class="mainmenu"><a href="group__context.html">Context State</a></li>
<li class="mainmenu"><a href="group__font.html">Fonts</a></li>
<li class="mainmenu"><a href="group__global.html">Global</a></li>
<li class="mainmenu"><a href="group__master.html">Master</a></li>
<li class="mainmenu"><a href="group__transform.html">Transformation</a></li>
<li class="mainmenu"><a href="group__render.html">Render</a></li>
<li class="mainmenu"><a href="group__measure.html">Measurement</a></li>
</ul>
</td>
</tr>
</table>
</td>
<td>
<table>
<tr>
<td class="main">
<!-- Generated by Doxygen 1.8.3 -->
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Machine definition </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="datatypes"></a>
Data types</h1>
<p>GLC uses GL data types and defines additional types, which are listed in the table below :</p>
<center> <table class="doxtable">
<caption align="bottom">GLC data types</caption>
<tr>
<td>Type </td><td>Definition </td></tr>
<tr>
<td><b>GLCchar</b> </td><td>Character code array element </td></tr>
<tr>
<td><b>GLCenum</b> </td><td>32 bits enumerant </td></tr>
<tr>
<td><b>GLCfunc</b> </td><td>Callback function pointer </td></tr>
</table>
</center><h1><a class="anchor" id="errors"></a>
Errors</h1>
<p>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 <a class="el" href="group__global.html#gae5b9cdedd0a8e8d7a565090c400cd396" title="Retrieves the value of the issuing thread's GLC error code variable, assigns the value GLC_NONE to th...">glcGetError()</a> is used to obtain error information.</p>
<p>Each client thread has a private GLC error code variable of type <b>GLCenum</b>. The initial value of this variable is <b>GLC_NONE</b>. If a GLC command raises an error, and the value of this variable is <b>GLC_NONE</b>, the command stores the error's code in the variable. Hence, after an error has been detected, no new error code is recorded until <a class="el" href="group__global.html#gae5b9cdedd0a8e8d7a565090c400cd396" title="Retrieves the value of the issuing thread's GLC error code variable, assigns the value GLC_NONE to th...">glcGetError()</a> is called.</p>
<p>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.</p>
<p>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.</p>
<p>Every GLC command execution begins with a test to determine if the command parameters are valid. If this test fails, the command raises <b>GLC_PARAMETER_ERROR</b>. Otherwise, GLC performs a test to determine if its state is such that the command is valid. If this test fails, the command raises <b>GLC_STATE_ERROR</b>. Otherwise, command execution proceeds. If at any point during command execution a needed resource (e.g. memory) is unavailable, the command raises <b>GLC_RESOURCE_ERROR</b>.</p>
<p>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.</p>
<h1><a class="anchor" id="contexts"></a>
Contexts</h1>
<p>A GLC <em>context</em> is an instantiation of GLC. When a client thread issues a GLC command, the thread's <em>current</em> GLC context executes the command.</p>
<p>Each GLC context has a nonzero ID of type <b>GLint</b>. 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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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 <b>GLC_STATE_ERROR</b> if the issuing thread has no current GLC context.</p>
<p>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.</p>
<p>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 </p>
<div class="fragment"><div class="line">glGetString(GL_VERSION);</div>
<div class="line">glGetString(GL_EXTENSIONS);</div>
</div><!-- fragment --><p>and stores the returned strings.</p>
<h1><a class="anchor" id="charcodes"></a>
Character codes</h1>
<p>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+<em>hexcode</em>, where <em>hexcode</em> 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.</p>
<h1><a class="anchor" id="strings"></a>
Strings</h1>
<p>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 <b>GLCchar</b>, but the actual type of these values is determined dynamically by the value of the variable <b>GLC_STRING_TYPE</b>. The values <b>GLC_UCS1</b>, <b>GLC_UCS2</b>, <b>GLC_UCS4</b> and <b>GLC_UTF8</b> specify how GLC should interpret the character codes and that each value is of type <b>GLubyte</b>, <b>GLushort</b>, <b>GLuint</b>, or <b>GLushort</b>, respectively. The initial value of <b>GLC_STRING_TYPE</b> is <b>GLC_UCS1</b>.</p>
<p>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.</p>
<p>The value of a character code in a returned string may exceed the range of the character encoding selected by <b>GLC_STRING_TYPE</b>. In this case, the returned character is converted to a character sequence <em>\<hexcode></em>, 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 <em>hexcode</em> 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.</p>
<h1><a class="anchor" id="constants"></a>
Constants</h1>
<p>GLC defines a set of implementation specific constants. The integer constants <b>GLC_VERSION_MAJOR</b> and <b>GLC_VERSION_MINOR</b> identify the version of GLC that the implementation supports. These constants correspond to a version <em>A.B</em> of the GLC specification. If a new version breaks compatibility, the major version number <em>A</em> will be incremented by one. Otherwise, the minor version number <em>B</em> will be incremented by one.</p>
<p>The string constant <b>GLC_VENDOR</b> identifies the vendor of the implementation.</p>
<p>The string constant <b>GLC_EXTENSIONS</b> 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".</p>
<p>The string constant <b>GLC_RELEASE</b> identifies the vendor specific software release that contains the implementation. </p>
</div></div><!-- contents -->
</td>
</tr>
<tr>
<td align="center" class="main">
<hr>
<small>
<font color="#cccccc">Generated on Sun Jan 13 2013 22:53:23 for QuesoGLC by <a href="http://www.doxygen.org/index.html"><img src="doxygen.png" alt="doxygen" align="middle" border=0></a> 1.8.3 written by Dimitri van Heesch © 1997-2005</font>
</small>
</td>
</tr>
</table>
</td>
</tr>
</table>
</body>
</html>
