1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>Crazy Eddies GUI System: The Beginners Guide to Getting CEGUI Rendering</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.7.4 -->
<script type="text/javascript">
function hasClass(ele,cls) {
return ele.className.match(new RegExp('(\\s|^)'+cls+'(\\s|$)'));
}
function addClass(ele,cls) {
if (!this.hasClass(ele,cls)) ele.className += " "+cls;
}
function removeClass(ele,cls) {
if (hasClass(ele,cls)) {
var reg = new RegExp('(\\s|^)'+cls+'(\\s|$)');
ele.className=ele.className.replace(reg,' ');
}
}
function toggleVisibility(linkObj) {
var base = linkObj.getAttribute('id');
var summary = document.getElementById(base + '-summary');
var content = document.getElementById(base + '-content');
var trigger = document.getElementById(base + '-trigger');
if ( hasClass(linkObj,'closed') ) {
summary.style.display = 'none';
content.style.display = 'block';
trigger.src = 'open.png';
removeClass(linkObj,'closed');
addClass(linkObj,'opened');
} else if ( hasClass(linkObj,'opened') ) {
summary.style.display = 'block';
content.style.display = 'none';
trigger.src = 'closed.png';
removeClass(linkObj,'opened');
addClass(linkObj,'closed');
}
return false;
}
</script>
<div id="top">
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">Crazy Eddies GUI System <span id="projectnumber">0.7.6</span></div>
</td>
</tr>
</tbody>
</table>
</div>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div>
<div class="header">
<div class="headertitle">
<div class="title">The Beginners Guide to Getting <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> Rendering </div> </div>
</div>
<div class="contents">
<div class="textblock"><dl class="author"><dt><b>Author:</b></dt><dd>Paul D Turner</dd></dl>
<h2><a class="anchor" id="rendering_tutorial_intro"></a>
Introduction</h2>
<p>In order to get <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> to render - regardless of your target API or engine - there are basically three steps that need to be performed:</p>
<ul>
<li>Create an instance of a <a class="el" href="classCEGUI_1_1Renderer.html" title="Abstract class defining the basic required interface for Renderer objects.">CEGUI::Renderer</a> based object.</li>
<li>Create the <a class="el" href="classCEGUI_1_1System.html" title="The System class is the CEGUI class that provides access to all other elements in this system...">CEGUI::System</a> object (passing in the renderer created above).</li>
<li>Each frame, call the <a class="el" href="classCEGUI_1_1System.html#a27924df52d352bba7d18a20d9f4639a1" title="Render the GUI.">CEGUI::System::renderGUI</a> function to perform the rendering.</li>
</ul>
<p>Obviously you also need to load some data and perform other basic initialisation, which is covered in <a class="el" href="resprov_tutorial.html">The Beginners Guide to resource loading with ResourceProviders</a> and <a class="el" href="datafile_tutorial.html">The Beginners Guide to Data Files and Defaults Initialisation</a>. You'll also need to get your inputs into the system so that you can interact with the GUI elements, this is covered in <a class="el" href="input_tutorial.html">The Beginners Guide to Injecting Inputs</a>.</p>
<p><br/>
</p>
<h2><a class="anchor" id="rendering_tutorial_bootstrap"></a>
The Easy Way: Renderer 'bootstrapSystem' functions</h2>
<p>This section describes the quickset and easiest way to get <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> up and running, and that is to use the static 'bootstrap' helper functions that are available on the <a class="el" href="classCEGUI_1_1Renderer.html" title="Abstract class defining the basic required interface for Renderer objects.">Renderer</a> class for your chosen API or engine. Unless you're doing something advanced or otherwise unusual, these are the fuctions you'll want to use, since they enable the creation of all the initial <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> objects in a single call.</p>
<p>Note that the Renderers also have destroySystem functions for cleaning up afterwards.</p>
<p>The Ogre3D and Irrlicht engines each have their own intergrated file loading and image parsing functionality which <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> can seamlessly make use of via custom implementations of the <a class="el" href="classCEGUI_1_1ResourceProvider.html" title="Abstract class that defines the required interface for all resource provider sub-classes.">CEGUI::ResourceProvider</a> and <a class="el" href="classCEGUI_1_1ImageCodec.html" title="Abstract ImageLoader class. An image loader encapsulate the loading of a texture.">CEGUI::ImageCodec</a> interfaces. In order to make use of these implementations, the user would typically be required to create instances of these objects and pass them, along with the <a class="el" href="classCEGUI_1_1Renderer.html" title="Abstract class defining the basic required interface for Renderer objects.">CEGUI::Renderer</a>, to the <a class="el" href="classCEGUI_1_1System.html#a1d05da171953f93f9494af68b997ebc0" title="Create the System object and return a reference to it.">System::create</a> function. Since this over-complicates system construction for even the most simplest of uses, the bootstrapSystem functions for those Renderers will creates all these supporting objects automatically.</p>
<p>As stated above, when using the boostrapSystem functions, starting up <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> is as simple as a single function call:</p>
<h3><a class="anchor" id="rendering_tutorial_bootstrap_opengl"></a>
OpenGL</h3>
<div class="fragment"><pre class="fragment"><span class="comment">// Bootstrap CEGUI::System with an OpenGLRenderer object that uses the</span>
<span class="comment">// current GL viewport, the DefaultResourceProvider, and the default</span>
<span class="comment">// ImageCodec.</span>
<a class="code" href="classCEGUI_1_1OpenGLRenderer.html" title="Renderer class to interface with OpenGL.">CEGUI::OpenGLRenderer</a>& myRenderer =
<a class="code" href="classCEGUI_1_1OpenGLRenderer.html#a8c2212c4876f112ea29244fe931b3b20" title="Convenience function that creates the required objects to initialise the CEGUI system.">CEGUI::OpenGLRenderer::bootstrapSystem</a>();
</pre></div><h3><a class="anchor" id="rendering_tutorial_bootstrap_d3d"></a>
Direct3D</h3>
<p>Note that this code shows the D3D9 renderer, but the D3D10 and D3D11 renderers are largely the same. </p>
<div class="fragment"><pre class="fragment"><span class="comment">// Bootstrap CEGUI::System with a Direct3D9Renderer object that uses the</span>
<span class="comment">// DefaultResourceProvider, and the default ImageCodec.</span>
<a class="code" href="classCEGUI_1_1Direct3D9Renderer.html" title="Renderer class to interface with Direct3D 9.">CEGUI::Direct3D9Renderer</a>& myRenderer =
<a class="code" href="classCEGUI_1_1Direct3D9Renderer.html#a005af97e9667611e4d86bd74250c763e" title="Convenience function that creates the required objects to initialise the CEGUI system.">CEGUI::Direct3D9Renderer::bootstrapSystem</a>( myD3D9Device );
</pre></div><h3><a class="anchor" id="rendering_tutorial_bootstrap_ogre"></a>
Ogre3D</h3>
<div class="fragment"><pre class="fragment"><span class="comment">// Bootstrap CEGUI::System with an OgreRenderer object that uses the</span>
<span class="comment">// default Ogre rendering window as the default output surface, an Ogre based</span>
<span class="comment">// ResourceProvider, and an Ogre based ImageCodec.</span>
<a class="code" href="classCEGUI_1_1OgreRenderer.html" title="CEGUI::Renderer implementation for the Ogre engine.">CEGUI::OgreRenderer</a>& myRenderer =
<a class="code" href="classCEGUI_1_1OgreRenderer.html#a3e4a385e76adf91973fb17c767b30177" title="Convenience function that creates all the Ogre specific objects and then initialises the CEGUI system...">CEGUI::OgreRenderer::bootstrapSystem</a>();
</pre></div><h3><a class="anchor" id="rendering_tutorial_bootstrap_irrlicht"></a>
Irrlicht</h3>
<div class="fragment"><pre class="fragment"><span class="comment">// Bootstrap CEGUI::System with an IrrlichtRenderer object, an Irrlicht based</span>
<span class="comment">// ResourceProvider, and an Irrlicht based ImageCodec.</span>
<a class="code" href="classCEGUI_1_1IrrlichtRenderer.html" title="CEGUI::Renderer implementation for the Irrlicht engine.">CEGUI::IrrlichtRenderer</a>& myRenderer =
<a class="code" href="classCEGUI_1_1IrrlichtRenderer.html#a3a7db433f3f82b0824f2a10ac5207e04" title="Convenience function that creates all the Irrlicht specific objects and then initialises the CEGUI sy...">CEGUI::IrrlichtRenderer::bootstrapSystem</a>( myIrrlichtDevice );
</pre></div><p><br/>
</p>
<h2><a class="anchor" id="rendering_tutorial_nonbootstrap"></a>
The Hard Way: Manual object creation.</h2>
<p>If for some reason you don't want to use the bootstrapSystem functions, you can still, of course, create all the required objects manually. The following describes the creation of the <a class="el" href="classCEGUI_1_1Renderer.html" title="Abstract class defining the basic required interface for Renderer objects.">Renderer</a> and <a class="el" href="classCEGUI_1_1System.html" title="The System class is the CEGUI class that provides access to all other elements in this system...">System</a> objects via separate calls. Note that if you have already used the boostrapSystem function, you do not need to perform the following steps, and can instead skip to <a class="el" href="rendering_tutorial.html#rendering_tutorial_draw">Call the function to render the GUI</a></p>
<p><br/>
</p>
<h2><a class="anchor" id="rendering_tutorial_renderer"></a>
Create an instance of a CEGUI::Renderer based object</h2>
<p>This is fairly straight forward and should pose no major obstacles for any of the supported renderers. You must of course remember to include the header file for the renderer that you will be using.</p>
<p>The basic renderer creation code is: </p>
<h3><a class="anchor" id="rendering_tutorial_renderer_d3d9"></a>
Direct3D 9</h3>
<div class="fragment"><pre class="fragment"><a class="code" href="classCEGUI_1_1Direct3D9Renderer.html" title="Renderer class to interface with Direct3D 9.">CEGUI::Direct3D9Renderer</a>& myRenderer =
<a class="code" href="classCEGUI_1_1Direct3D9Renderer.html#a249b304696daa5d476945b20d7da7d72" title="Create an Direct3D9Renderer object.">CEGUI::Direct3D9Renderer::create</a>( myD3D9Device );
</pre></div><h3><a class="anchor" id="rendering_tutorial_renderer_d3d10"></a>
Direct3D 10</h3>
<div class="fragment"><pre class="fragment"><a class="code" href="classCEGUI_1_1Direct3D10Renderer.html" title="Renderer implementation using Direct3D 10.">CEGUI::Direct3D10Renderer</a>& myRenderer =
<a class="code" href="classCEGUI_1_1Direct3D10Renderer.html#a7110576663ab2206a28957d96a138113" title="Create an Direct3D10Renderer object.">CEGUI::Direct3D10Renderer::create</a>( myD3D10Device );
</pre></div><h3><a class="anchor" id="rendering_tutorial_renderer_ogl"></a>
OpenGL</h3>
<div class="fragment"><pre class="fragment"><span class="comment">// Create an OpenGLRenderer object that uses the current GL viewport as</span>
<span class="comment">// the default output surface.</span>
<a class="code" href="classCEGUI_1_1OpenGLRenderer.html" title="Renderer class to interface with OpenGL.">CEGUI::OpenGLRenderer</a>& myRenderer =
<a class="code" href="classCEGUI_1_1OpenGLRenderer.html#a38d5f0f9115e6bdc2b7052719546065b" title="Create an OpenGLRenderer object.">CEGUI::OpenGLRenderer::create</a>();
</pre></div><h3><a class="anchor" id="rendering_tutorial_renderer_ogre"></a>
Ogre3D</h3>
<div class="fragment"><pre class="fragment"><span class="comment">// Create an OgreRenderer object that uses the default Ogre rendering</span>
<span class="comment">// window as the default output surface.</span>
<a class="code" href="classCEGUI_1_1OgreRenderer.html" title="CEGUI::Renderer implementation for the Ogre engine.">CEGUI::OgreRenderer</a>& myRenderer =
<a class="code" href="classCEGUI_1_1OgreRenderer.html#a8ca3cb7094d62e47aa0db20429a82484" title="Create an OgreRenderer object that uses the default Ogre rendering window as the default output surfa...">CEGUI::OgreRenderer::create</a>();
</pre></div><h3><a class="anchor" id="rendering_tutorial_renderer_irrlicht"></a>
Irrlicht Engine</h3>
<div class="fragment"><pre class="fragment"><a class="code" href="classCEGUI_1_1IrrlichtRenderer.html" title="CEGUI::Renderer implementation for the Irrlicht engine.">CEGUI::IrrlichtRenderer</a>& myRenderer =
<a class="code" href="classCEGUI_1_1IrrlichtRenderer.html#a5c498834474a766dfd948904d881ee56" title="Function to create and return IrrlichtRenderer objects.">CEGUI::IrrlichtRenderer::create</a>( myIrrlichtDevice );
</pre></div><h3><a class="anchor" id="rendering_tutorial_renderer_dfb"></a>
DirectFB</h3>
<div class="fragment"><pre class="fragment"><span class="comment">// Create DirectFBRenderer that draws to the given DirectFB surface using</span>
<span class="comment">// the given IDirectFB instance.</span>
<a class="code" href="classCEGUI_1_1DirectFBRenderer.html" title="Implementation of CEGUI::Renderer interface using DirectFB.">CEGUI::DirectFBRenderer</a>& myRenderer =
<a class="code" href="classCEGUI_1_1DirectFBRenderer.html#a84f39250326c9d8cea1d2c3aec6e79ca" title="create a DirectFBRenderer object.">CEGUI::DirectFBRenderer::create</a>( *myDirectFB, *myDirectFBSurface );
</pre></div><p><br/>
</p>
<h2><a class="anchor" id="rendering_tutorial_system"></a>
Create the CEGUI::System object to initialise the system</h2>
<p>Another extremely simple step. Just instantiate the <a class="el" href="classCEGUI_1_1System.html" title="The System class is the CEGUI class that provides access to all other elements in this system...">CEGUI::System</a> object by using the <a class="el" href="classCEGUI_1_1System.html#a1d05da171953f93f9494af68b997ebc0" title="Create the System object and return a reference to it.">System::create</a> function, passing in the reference to the <a class="el" href="classCEGUI_1_1Renderer.html" title="Abstract class defining the basic required interface for Renderer objects.">CEGUI::Renderer</a> that you created in the previous step. This will cause the core <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> system to initialise itself. </p>
<div class="fragment"><pre class="fragment"><a class="code" href="classCEGUI_1_1System.html#a1d05da171953f93f9494af68b997ebc0" title="Create the System object and return a reference to it.">CEGUI::System::create</a>( myRenderer );
</pre></div><p><br/>
</p>
<h2><a class="anchor" id="rendering_tutorial_draw"></a>
Call the function to render the GUI</h2>
<p>This is the only step that, depending upon your target engine, can be done differently. Basically what you need to do call the <a class="el" href="classCEGUI_1_1System.html#a27924df52d352bba7d18a20d9f4639a1" title="Render the GUI.">CEGUI::System::renderGUI</a> function at the end of your rendering loop. For users of the Ogre3D engine, this step is taken care of automatically. For everybody else, some simple example code can be seen below: </p>
<h3><a class="anchor" id="rendering_tutorial_draw_d3d9"></a>
Direct3D 9</h3>
<div class="fragment"><pre class="fragment"><span class="comment">// Start the scene</span>
myD3DDevice->BeginScene();
<span class="comment">// clear display</span>
myD3DDevice->Clear(0, 0, D3DCLEAR_TARGET, D3DCOLOR_XRGB(0, 0, 0), 1.0f, 0);
<span class="comment">// user function to draw 3D scene</span>
draw3DScene();
<span class="comment">// draw GUI</span>
<a class="code" href="classCEGUI_1_1System.html#a8d059b018d621be0e4b98d069421426f" title="Return singleton System object.">CEGUI::System::getSingleton</a>().<a class="code" href="classCEGUI_1_1System.html#a27924df52d352bba7d18a20d9f4639a1" title="Render the GUI.">renderGUI</a>();
<span class="comment">// end the scene</span>
myD3DDevice->EndScene();
<span class="comment">// finally present the frame.</span>
myD3DDevice->Present(0, 0, 0, 0);
</pre></div><h3><a class="anchor" id="rendering_tutorial_draw_d3d10"></a>
Direct3D 10</h3>
<div class="fragment"><pre class="fragment"><span class="comment">// define colour view will be cleared to</span>
<span class="keywordtype">float</span> clear_colour[4] = { 0.0f, 0.0f, 0.0f, 1.0f };
<span class="comment">// clear display</span>
myD3DDevice->ClearRenderTargetView(myRenderTargetView, clear_colour);
<span class="comment">// user function to draw 3D scene</span>
draw3DScene();
<span class="comment">// draw GUI</span>
<a class="code" href="classCEGUI_1_1System.html#a8d059b018d621be0e4b98d069421426f" title="Return singleton System object.">CEGUI::System::getSingleton</a>().<a class="code" href="classCEGUI_1_1System.html#a27924df52d352bba7d18a20d9f4639a1" title="Render the GUI.">renderGUI</a>();
<span class="comment">// present the newly drawn frame.</span>
mySwapChain->Present(0, 0);
</pre></div><h3><a class="anchor" id="rendering_tutorial_draw_ogl"></a>
OpenGL</h3>
<div class="fragment"><pre class="fragment"><span class="comment">// user function to draw 3D scene</span>
draw3DScene();
<span class="comment">// draw GUI (should not be between glBegin/glEnd pair)</span>
<a class="code" href="classCEGUI_1_1System.html#a8d059b018d621be0e4b98d069421426f" title="Return singleton System object.">CEGUI::System::getSingleton</a>().<a class="code" href="classCEGUI_1_1System.html#a27924df52d352bba7d18a20d9f4639a1" title="Render the GUI.">renderGUI</a>();
</pre></div><h3><a class="anchor" id="rendering_tutorial_draw_irrlicht"></a>
Irrlicht</h3>
<div class="fragment"><pre class="fragment"><span class="comment">// start the scene</span>
myIrrlichtDriver->beginScene(<span class="keyword">true</span>, <span class="keyword">true</span>, irr::video::SColor(150,50,50,50));
<span class="comment">// draw main scene</span>
myIrrlichtSceneManager->drawAll();
<span class="comment">// draw gui</span>
<a class="code" href="classCEGUI_1_1System.html#a8d059b018d621be0e4b98d069421426f" title="Return singleton System object.">CEGUI::System::getSingleton</a>().<a class="code" href="classCEGUI_1_1System.html#a27924df52d352bba7d18a20d9f4639a1" title="Render the GUI.">renderGUI</a>();
<span class="comment">// end the scene</span>
myIrrlichtDriver->endScene();
</pre></div><h3><a class="anchor" id="rendering_tutorial_draw_dfb"></a>
DirectFB</h3>
<div class="fragment"><pre class="fragment"><span class="comment">// clear display</span>
myDirectFBSurface->Clear( myDirectFBSurface, 0x0, 0x0, 0x0, 0xFF );
<span class="comment">// TODO: Do other drawing here.</span>
<span class="comment">// draw the GUI</span>
<a class="code" href="classCEGUI_1_1System.html#a8d059b018d621be0e4b98d069421426f" title="Return singleton System object.">CEGUI::System::getSingleton</a>().<a class="code" href="classCEGUI_1_1System.html#a27924df52d352bba7d18a20d9f4639a1" title="Render the GUI.">renderGUI</a>();
<span class="comment">// flip the surface we just rendered</span>
myDirectFBSurface->Flip(myDirectFBSurface, 0, (DFBSurfaceFlipFlags)0);
</pre></div><p><br/>
</p>
<h2><a class="anchor" id="rendering_tutorial_conclusion"></a>
Conclusion</h2>
<p>This is the <em>most basic</em> introduction to setting up <a class="el" href="namespaceCEGUI.html" title="Main namespace for Crazy Eddie's GUI Library.">CEGUI</a> to render. There are things not covered here, such as using different rendering targets in Ogre and advanced options such as user specified resource providers, and so on. </p>
</div></div>
<hr class="footer"/><address class="footer"><small>Generated on Sun Jan 22 2012 16:07:40 for Crazy Eddies GUI System by 
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.4 </small></address>
</body>
</html>
|
