<!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>First Steps</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.8 -->
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">First Steps </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="general"></a>
General description</h1>
<p>GLC is a library that provides font services for OpenGL applications. When using GLC, there is no need for you to look for font directories, manage the font files, load and interpret glyphs data, tesselate polygons, antialias characters and issue GL commands to render text, since GLC takes care of that for you.</p>
<p>Although GLC is very easy to use, there are a few steps to follow in order to be ready to render text in your OpenGL application. This tutorial will guide you through the basic commands of GLC and will expose you a few concepts that GLC relies on.</p>
<dl class="section warning"><dt>Warning</dt><dd>Since GLC uses OpenGL, a GL context must be bound to the current thread before any GLC command can be issued. This task must be done by the GLC client (i.e. the application that uses GLC). GLC does not verify if this has been done. If you try to issue GLC commands while no GL context is current, the result of the commands is undefined.</dd></dl>
<h1><a class="anchor" id="setupcontext"></a>
Setting up a GLC context</h1>
<p>Just like OpenGL, GLC relies on the concept of context. A context is an entity that stores the state machine of GLC, that is, an entity that stores the font that is currently used, the type of rendering, the string encoding and so on.</p>
<h2><a class="anchor" id="ctxcreation"></a>
Context creation</h2>
<p>Unlike OpenGL, the GLC context commands are machine independant. The commands to create, manage and bind a context to the current thread are the same for every platform that supports GLC.</p>
<p>The first step to use GLC is to create a context which is simply done by the code below :</p>
<div class="fragment"><div class="line">GLint ctx;</div>
<div class="line"></div>
<div class="line">ctx = <a class="code" href="group__global.html#ga65c4f22e1a75bca7edafe35fe6b185ee">glcGenContext</a>();</div>
</div><!-- fragment --><p>When <a class="el" href="group__global.html#ga65c4f22e1a75bca7edafe35fe6b185ee" title="Generates a new GLC context and returns its ID. ">glcGenContext()</a> is executed, the variable <code>ctx</code> contains the ID of the context that has been created. This ID is unique and must be used each time a GLC command needs to identify a context.</p>
<h2><a class="anchor" id="ctxbind"></a>
Context binding</h2>
<p>You can create just as many contexts as you want, but one and only one context can be used at a given time. Therefore, you must tell GLC which context you plan to use, even if you have created only one context. This operation is said to "make a context current" or to "bind a context to the current thread". This is achieved by calling <a class="el" href="group__global.html#gaaa17c69ee70f9e8a900dc9c6830f3f09" title="Assigns the value inContext to the issuing thread's current GLC context ID variable. ">glcContext()</a> :</p>
<div class="fragment"><div class="line"><a class="code" href="group__global.html#gaaa17c69ee70f9e8a900dc9c6830f3f09">glcContext</a>(ctx);</div>
</div><!-- fragment --><p>At this stage, whenever a GLC command is issued, the context <code>ctx</code> will execute the command.</p>
<p>You can change the current GLC context at any time by re-issuing a <a class="el" href="group__global.html#gaaa17c69ee70f9e8a900dc9c6830f3f09" title="Assigns the value inContext to the issuing thread's current GLC context ID variable. ">glcContext()</a> command with a new context ID and if you want to release the current context without making a new context current, you just need to call <code>glcContext(0)</code>; </p><dl class="section note"><dt>Note</dt><dd>If your application is multi-threaded, you can bind a different context to each thread. However a context can only be bound to one thread at a time.</dd></dl>
<h1><a class="anchor" id="fontdir"></a>
Adding font directories</h1>
<p>GLC grabs font files from directories that are called "catalogs" in the GLC specifications. Depending on the implementation, a GLC context may or may not have default directories where to look for font files and may or may not provide some default fonts.</p>
<p>QuesoGLC uses the Fontconfig library to automagically find the fonts that are available on your system. Moreover, the environment variable <code>GLC_PATH</code> can be used to set up some more default fonts. You may however want GLC to search for fonts in additional directories, especially if your application comes with its own fonts. This can be achieved with the command <a class="el" href="group__master.html#gab0b37f7b9f9459aef7ec645a66bac4a7" title="This command appends the string inCatalog to the list GLC_CATALOG_LIST. ">glcAppendCatalog()</a> :</p>
<div class="fragment"><div class="line"><span class="comment">// For many Unixes (included Linux), /usr/lib/X11/fonts/Type1/ is a standard</span></div>
<div class="line"><span class="comment">// directory where X windows stores fonts in Adobe's Type1 format.</span></div>
<div class="line"></div>
<div class="line"><a class="code" href="group__master.html#gab0b37f7b9f9459aef7ec645a66bac4a7">glcAppendCatalog</a>(<span class="stringliteral">"/usr/lib/X11/fonts/Type1/"</span>);</div>
</div><!-- fragment --><p>You can call <a class="el" href="group__master.html#gab0b37f7b9f9459aef7ec645a66bac4a7" title="This command appends the string inCatalog to the list GLC_CATALOG_LIST. ">glcAppendCatalog()</a> as much as needed, to add several directories to the catalog list of GLC.</p>
<dl class="section note"><dt>Note</dt><dd>GLC internally manages a list of catalogs (that is, of directories) where it will look for directories that contains the font files. You can inspect this list with the command <a class="el" href="group__context.html#gaff9f0d258360614e3d2ffbdaeade1ecc" title="This command returns the string at offset inIndex from the first element in the string list identifie...">glcGetListc()</a> as in the following code :</dd></dl>
<div class="fragment"><div class="line">GLint count, i;</div>
<div class="line"></div>
<div class="line"><span class="comment">// Get the number of entries in the catalog list</span></div>
<div class="line">count = <a class="code" href="group__context.html#gad9d771a80cebb0d5e346066d2636bca0">glcGeti</a>(GLC_CATALOG_COUNT);</div>
<div class="line"></div>
<div class="line"><span class="comment">// Print the path to the catalogs</span></div>
<div class="line"><span class="keywordflow">for</span> (i = 0; i \< count; i++)</div>
<div class="line"> printf(<span class="stringliteral">"%s\n"</span>, <a class="code" href="group__context.html#gaff9f0d258360614e3d2ffbdaeade1ecc">glcGetListc</a>(GLC_CATALOG_LIST, i));</div>
</div><!-- fragment --><h1><a class="anchor" id="choosefont"></a>
Choosing a font</h1>
<p>Now, you may want to choose the font that will be used to render your text. In GLC, fonts are managed in a very similar way than contexts are : fonts are identified by a unique integer ID, and they need to be made current to the context before they are used. Hence, we need first to get an identifier which is not used by another font :</p>
<div class="fragment"><div class="line">GLint myFont;</div>
<div class="line"></div>
<div class="line">myFont = <a class="code" href="group__font.html#ga658c40ba0437274cf2849bc3dac4dd20">glcGenFontID</a>();</div>
</div><!-- fragment --><p>The font ID <code>myFont</code> is unique and will be used thereafter to designate our font.</p>
<p>Each font has a <em>family</em> name (e.g. Palatino, Courier, Helvetica, ...) and a state variable that select one of the <em>faces</em> (e.g. Regular, Italic, Bold, Bold Italic, ...) that the font contains.</p>
<p>In our example, we want to use "Palatino Bold" to render the text. This is done with the following code :</p>
<div class="fragment"><div class="line"><a class="code" href="group__font.html#gacc8675929261b5f04882d375cb54a530">glcNewFontFromFamily</a>(myFont, <span class="stringliteral">"Palatino"</span>); <span class="comment">// Select the family of my font</span></div>
<div class="line"><a class="code" href="group__font.html#gab9800f5153d46bd293b62dc7bfcd364f">glcFontFace</a>(myFont, <span class="stringliteral">"Bold"</span>); <span class="comment">// Select the face of my font</span></div>
</div><!-- fragment --><p>At this stage, a new font "Palatino Bold" which is identified by <code>myFont</code> has been created in the current GLC context. We now want GLC to use <code>myFont</code> to render the text :</p>
<div class="fragment"><div class="line"><a class="code" href="group__font.html#gaab2c8a01997c3827b10aebedd8e78501">glcFont</a>(myFont);</div>
</div><!-- fragment --><h1><a class="anchor" id="rendertext"></a>
Rendering the text</h1>
<p>We have now reached the final step : we are now able to render some text. First, we need to tell OpenGL (yes, OpenGL not GLC !!!) where the characters will be rendered. Indeed, when the <a class="el" href="group__render.html#ga93708ef20c96fd01019fcd9eb18f0b03" title="This command is identical to the command glcRenderCountedString(), except that inString is zero termi...">glcRenderString()</a> command will be executed, GLC will issue some GL commands but nothing will be displayed if we do not tell OpenGL where to render the string.</p>
<p>By default, QuesoGLC renders fonts at a size of 1 point. If we want our text to be readable, we must scale it :</p>
<div class="fragment"><div class="line"><span class="comment">// Render the text at a size of 100 points</span></div>
<div class="line"><a class="code" href="group__transform.html#ga71a9a779d35bc8c4631de7cbda21cea6">glcScale</a>(100.f, 100.f);</div>
</div><!-- fragment --><p>If we decide to render text in bitmap mode (which is the default render style of GLC), we need to give the raster position and (why not ?) the color of the text to OpenGL :</p>
<div class="fragment"><div class="line">glColor3f(1.f, 0.f, 0.f);</div>
<div class="line">glRasterPos2f(50.f, 50.f);</div>
</div><!-- fragment --><p>Now, our text will be rendered at coordinates (50, 50) in red color.</p>
<p>It is time now to render the famous <em>"Hello world!"</em> string :</p>
<div class="fragment"><div class="line"><a class="code" href="group__render.html#ga93708ef20c96fd01019fcd9eb18f0b03">glcRenderString</a>(<span class="stringliteral">"Hello world!"</span>);</div>
</div><!-- fragment --><p>That's it ! With a few lines of code, GLC allows to render some text in an OpenGL window.</p>
<div class="image">
<img src="tutorial.png" alt="tutorial.png"/>
</div>
<p><br />
As a reminder, the complete code is given below :</p>
<div class="fragment"><div class="line">GLint ctx, myFont;</div>
<div class="line"></div>
<div class="line"><span class="comment">// Set up and initialize GLC</span></div>
<div class="line">ctx = <a class="code" href="group__global.html#ga65c4f22e1a75bca7edafe35fe6b185ee">glcGenContext</a>();</div>
<div class="line"><a class="code" href="group__global.html#gaaa17c69ee70f9e8a900dc9c6830f3f09">glcContext</a>(ctx);</div>
<div class="line"><a class="code" href="group__master.html#gab0b37f7b9f9459aef7ec645a66bac4a7">glcAppendCatalog</a>(<span class="stringliteral">"/usr/lib/X11/fonts/Type1/"</span>);</div>
<div class="line"></div>
<div class="line"><span class="comment">// Create a font "Palatino Bold"</span></div>
<div class="line">myFont = <a class="code" href="group__font.html#ga658c40ba0437274cf2849bc3dac4dd20">glcGenFontID</a>();</div>
<div class="line"><a class="code" href="group__font.html#gacc8675929261b5f04882d375cb54a530">glcNewFontFromFamily</a>(myFont, <span class="stringliteral">"Palatino"</span>);</div>
<div class="line"><a class="code" href="group__font.html#gab9800f5153d46bd293b62dc7bfcd364f">glcFontFace</a>(myFont, <span class="stringliteral">"Bold"</span>);</div>
<div class="line"><a class="code" href="group__font.html#gaab2c8a01997c3827b10aebedd8e78501">glcFont</a>(myFont);</div>
<div class="line"></div>
<div class="line"><span class="comment">// Render the text at a size of 100 points</span></div>
<div class="line"><a class="code" href="group__transform.html#ga71a9a779d35bc8c4631de7cbda21cea6">glcScale</a>(100.f, 100.f);</div>
<div class="line"></div>
<div class="line"><span class="comment">// Render "Hello world!"</span></div>
<div class="line">glColor3f(1.f, 0.f, 0.f);</div>
<div class="line">glRasterPos2f(50.f, 50.f);</div>
<div class="line"><a class="code" href="group__render.html#ga93708ef20c96fd01019fcd9eb18f0b03">glcRenderString</a>(<span class="stringliteral">"Hello world!"</span>);</div>
</div><!-- fragment --><p>Most of the code above is executed once in a program : the GLC setup and the font creation are done at the beginning of the program, only the rendering part of the code (that is 3 lines !) may be located in the main loop of the application. </p><dl class="section note"><dt>Note</dt><dd>If the rendering style of the text is not <b>GLC_BITMAP</b>, then you should use <code>glTranslate()</code> and <code>glScale()</code> instead of <code>glRasterPos()</code> and <a class="el" href="group__transform.html#ga71a9a779d35bc8c4631de7cbda21cea6" title="This command produces a general scaling along the x and y axes, that is, it assigns the value [a b c ...">glcScale()</a>.</dd></dl>
<h1><a class="anchor" id="whatmore"></a>
What more ?</h1>
<p>This is a basic tutorial which has shown you the basic steps to render some text with GLC. However, for the sake of clarity, no error has been checked in the example above. In GLC some functions returns a value and this value must be checked in order to verify that no error has occured. Nevertheless, the prefered way in GLC to check errors is to use <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>.</p>
<p>If you want to change the code above in order to fit it to your needs, the first place to look at is the <a href="overview.html">reference documentation </a> which is provided with QuesoGLC.</p>
<p>GLC also provides a nice set of functions (all of them beginning with <code>glcGet*</code> ) to introspect a context and see, for instance, which fonts are available.</p>
<p>The <a class="el" href="group__measure.html">Measurement commands</a> have not been used in the example above but you may use them to get some basic metrics of a string in order to precisely locate it on the screen (see the <a class="el" href="tutorial2.html">Measurement tutorial</a> for instance).</p>
<p>The <a class="el" href="group__transform.html">Transformation commands</a> can be used with <b>GLC_BITMAP</b> rendering to obtain fancy effects (rotation and scaling) which are not available in GLX.</p>
<p>Finally, you can have a look at the tests and examples of QuesoGLC to learn how to use some GLC commands and which are their effect. </p>
</div></div><!-- contents -->
</td>
</tr>
<tr>
<td align="center" class="main">
<hr>
<small>
<font color="#cccccc">Generated on Fri Oct 17 2014 04:12:42 for QuesoGLC by <a href="http://www.doxygen.org/index.html"><img src="doxygen.png" alt="doxygen" align="middle" border=0></a> 1.8.8 written by Dimitri van Heesch © 1997-2005</font>
</small>
</td>
</tr>
</table>
</td>
</tr>
</table>
</body>
</html>
distrib
>
Mageia
>
5
>
i586
>
media
>
core-release
>
by-pkgid
>
1ef284ce2eda462d5c7f167d61fd17d0
>
files
>
96
