Debian Codegraph @

Documentation/Overview/opengl_overview.xml

raw
1 <xml>
2 <head>
3 <title>Using OpenGL with ClanLib</title>
4 </head>
5 <body>
6
7 <p>ClanLib's primary render target is OpenGL. It is handled by the module
8 clanGL, a target for clanDisplay.</p>
9
10 <p>ClanDisplay is an abstraction, working to allow ClanLib applications to
11 do stuff in a general matter that can be applied to any display target
12 supported by ClanLib. In order to use clanDisplay, one or more display
13 targets must also be setup. For example, a GL-based ClanLib app must call
14 both CL_SetupDisplay::init() and CL_SetupGL::init() when starting.</p>
15
16 <p>Because clanDisplay is an abstraction, its API in itself will not
17 directly offer you access to the objects the implementation is using.
18 Instead, each of the display targets offer their own set of subclasses for
19 clanDisplay. An example of this the CL_OpenGLSurface class. This is the
20 OpenGL version of CL_Surface - you can use it anywhere in ClanLib where it
21 takes a CL_Surface object, and you can cast between the two types of
22 objects:</p>
23
24 <code>
25 CL_Surface some_surface("fish.png");
26 CL_OpenGLSurface gl_version = some_surface;
27 gl_version.bind();
28 </code>
29
30 <p>The display target specific versions of the clanDisplay classes offer
31 ways to integrate directly with target specific code. The bind() function on
32 CL_OpenGLSurface binds the texture used by the surface, for apps wanting to
33 do 3D OpenGL stuff, but use ClanLib to load the textures. Sometimes it's also
34 possible to get the internal handles used by the target.</p>
35
36 <h3>OpenGL states</h3>
37
38 <p>OpenGL as a library is very hardware oriented. It uses a state model that
39 reflect how hardware is, more than how things are ideally from a software
40 developers point of view. This is both the strength and weakness of the
41 OpenGL API. It makes OpenGL very simple and fast, but also makes it hard to
42 write component oriented rendering.</p>
43
44 <p>If a state is set in OpenGL (ie glEnable(GL_TEXTURE_2D) or
45 glBindTexture(textureid)), it remains in this state until its changed. This
46 makes it problematic for different rendering code to share the same OpenGL
47 context. If the first piece of render code (ie ClanLib) enables
48 GL_TEXTURE_2D, and the next render code expects it to be disabled, then the
49 output produced may be wrong. To make things even worse, for each graphic
50 context in ClanLib, there is a new OpenGL context. Each of those OpenGL
51 contexts maintain their own set of states.</p>
52
53 <p>To address these issues, clanGL introduces a concept called OpenGL state,
54 maintained by the class <codelink>CL_OpenGLState</codelink>. CL_OpenGLState
55 acts like there is a seperate OpenGL context (state setup) for each
56 CL_OpenGLState object contstructed. It setups and keeps OpenGL states in a
57 known configuration for the user of CL_OpenGLState.</p>
58
59 <p>Currently it tracks the following states:</p>
60
61 <ul>
62 <li>glEnable/glDisable GL_TEXTURE_2D</li>
63 <li>glBindTexture GL_TEXTURE_2D</li>
64 <li>glEnable/glDisable GL_BLEND</li>
65 <li>glEnable/glDisable GL_FOG</li>
66 <li>glEnable/glDisable GL_DEPTH_TEST</li>
67 <li>glEnable/glDisable GL_SCISSOR_TEST</li>
68 <li>glEnable/glDisable GL_ALPHA_TEST</li>
69 <li>glEnable/glDisable GL_STENCIL_TEST</li>
70 <li>glViewport</li>
71 <li>glScissor</li>
72 <li>glClearColor</li>
73 <li>glBlendFunc</li>
74 <li>glColor</li>
75 <li>glVertexPointer</li>
76 <li>glColorPointer</li>
77 <li>glTexCoordPointer</li>
78 <li>glEnableClientState GL_VERTEX_ARRAY</li>
79 <li>glEnableClientState GL_COLOR_ARRAY</li>
80 <li>glEnableClientState GL_TEXTURE_COORD_ARRAY</li>
81 <li>glMatrixMode</li>
82 <li>matrix GL_TEXTURE</li>
83 <li>matrix GL_PROJECTION</li>
84 <li>matrix GL_MODELVIEW</li>
85 <li>glTexEnvf GL_TEXTURE_ENV GL_TEXTURE_ENV_MODE</li>
86 <li>glPolygonMode</li>
87 <li>glAlphaFunc</li>
88 <li>glStencilFunc</li>
89 <li>glStencilOp</li>
90 </ul>
91
92 <p>Only one CL_OpenGLState is active in clanlib at a time. When its made
93 active, it will setup OpenGL to the state that the instance had last time it
94 was active.</p>
95
96 <p>To illustrate with an example, look at the following code:</p>
97
98 <code>
99 CL_OpenGLState state_a(window1.get_gc());
100 CL_OpenGLState state_b(window1.get_gc());
101 CL_OpenGLState state_c(window2.get_gc());
102
103 state_a.set_active();
104 glColor3d(1.0,0.0,0.0);
105
106 state_b.set_active();
107 glEnable(GL_TEXTURE_2D);
108 glBindTexture(texture_handle);
109
110 state_c.set_active();
111 glColor3d(0.0,0.0,1.0);
112
113 state_a.set_active();
114 glBegin(GL_QUADS);
115 glVertex3d(...); glVertex3d(...); glVertex3d(...); glVertex3d(...);
116 glEnd();
117
118 state_b.set_active();
119 glBegin(GL_QUADS);
120 glVertex3d(...); glVertex3d(...); glVertex3d(...); glVertex3d(...);
121 glEnd();
122 </code>
123
124 <p>In the above example, the first quad drawn will be rendered with
125 GL_TEXTURE_2D disabled, but with color red color (1.0, 0.0, 0.0). The second
126 quad will be with GL_TEXTURE_2D enabled, texture bound to texture_handle and
127 with white color (OpenGL default color).</p>
128
129 <h3>Doing custom OpenGL with ClanLib</h3>
130
131 <p>If you want to do your own OpenGL (or use external OpenGL specific
132 libraries) with clanGL, you need to create your own CL_OpenGLState object.
133 Internally ClanLib works with a set of CL_OpenGLState objects, one for each
134 of the following steps, but also other places. This is just to describe the
135 general idea.</p>
136
137 <ul>
138 <li>Texture uploads and downloads (CL_Surface)</li>
139 <li>ClanDisplay 2D Batch Rendering (lines, fills, surface rendering)</li>
140 <li>Copying from back buffer to front (CL_DisplayWindow::update())</li>
141 <li>Flipping front and back buffers (CL_DisplayWindow::flip())</li>
142 <li>Copying texture to pbuffer (CL_Surface::get_gc())</li>
143 <li>Copying from pbuffer to texture (CL_Surface::draw())</li>
144 </ul>
145
146 <p>Each of those commands act as stand alone components that do not know
147 terrible much about each other. They each have their own CL_OpenGLState
148 object that keep OpenGL's states like they set them up. If you call
149 CL_DisplayWindow::flip(), then ClanLib makes a CL_OpenGLState::set_active()
150 call, causing the current active OpenGL state to be saved, and the new one
151 loaded.</p>
152
153 <p>This can happen in any clanDisplay/clanGL call you might make, except
154 those specifically not designed to do so, like CL_OpenGLSurface::bind().
155 Common error is when loading surfaces/textures - make sure to reactivate
156 your state after doing this.</p>
157
158 <p>By creating one (or more) CL_OpenGLState objects yourself, ClanLib is
159 able to store your OpenGL setup and restore it when you need to do OpenGL
160 calls next time. Simply call set_active() before every time you are going to
161 do OpenGL. If the state object is already active, no actions will be
162 performed.</p>
163
164 <code>
165 CL_DisplayWindow window("Hello OpenGL!", 640, 480);
166 CL_GraphicContext *gc = window.get_gc();
167 CL_OpenGLSurface surface("hello.png");
168
169 // Setup my OpenGL state:
170 CL_OpenGLState my_opengl(gc);
171 my_opengl.set_active();
172 glEnable(GL_TEXTURE_2D);
173 surface.bind();
174 glMatrixMode(GL_PROJECTION);
175 glProject(...);
176 glMatrixMode(GL_MODELVIEW);
177 gluLookAt(...);
178
179 while (CL_Keyboard::get_keycode(CL_KEY_ESCAPE) == false)
180 {
181 // draw my opengl world:
182 my_opengl.set_active();
183 glBegin(GL_TRIANGLES);
184 glVertex4d(...);
185 glVertex4d(...);
186 glVertex4d(...);
187 glVertex4d(...);
188 glEnd();
189
190 // draw HUD (with clanlib 2D stuff):
191 gc->draw_line(...);
192
193 // Make things visible for user:
194 window.flip();
195 CL_System::keep_alive();
196 }
197 </code>
198
199 <h3>Accessing OpenGL 2.0</h3>
200
201 <p>One of the problems you will face when using OpenGL is that nobody really
202 got the OpenGL 2.0 API (at least at the time this was written). If you use
203 the standard OpenGL headers and libraries delivered by your operating
204 system, you will get:</p>
205
206 <table>
207 <tr>
208 <th>Operating System</th>
209 <th>OpenGL version</th>
210 <th>Extensions</th>
211 </tr>
212 <tr>
213 <td>Microsoft Windows</td>
214 <td>OpenGL 1.2</td>
215 <td>No extensions in glext.h added since 1995 when Microsoft
216 abandoned OpenGL.</td>
217 </tr>
218 <tr>
219 <td>Linux</td>
220 <td>OpenGL 1.2</td>
221 <td>Each vendor got their own set of OpenGL headers. Nvidia got theirs, ATI
222 got theirs, DRI too. Depending on the age of the headers, they can be
223 anywhere between OpenGL 1.3's extensions to OpenGL 1.5.</td>
224 </tr>
225 <tr>
226 <td>Apple Mac OS X</td>
227 <td>OpenGL 1.4 (for Jaguar, OS X 10.3.5)</td>
228 <td>Extensions? Apple didnt even bother make an aglGetProcAddress
229 function to at least get you started!</td>
230 </tr>
231 </table>
232
233 <p>ClanLib offers the complete OpenGL 2.0 API via its own set of macros. All
234 you need to do is to include ClanLib/GL/opengl_wrap.h, and then change the
235 gl prefix to cl. It's that simple.</p>
236
237 <code>
238 // Setup my OpenGL state:
239 CL_OpenGLState my_opengl(gc);
240 my_opengl.set_active();
241
242 // Do some OpenGL 2.0 specific stuff:
243 CLInt shader_handle = clCreateShader(CL_FRAGMENT_SHADER);
244 clShaderSource(shader_handle, ..);
245 clCompileShader(shader_handle);
246
247 CLInt program_handle = clCreateProgram();
248 clAttachShader(program_handle);
249 clLinkProgram(program_handle);
250
251 clUseProgram(program_handle);
252 </code>
253
254 <h3>Custom OpenGL 2D</h3>
255
256 <p>If you intend to do 2D OpenGL rendering, you can get ClanLib to manage
257 your projection matrix, view matrix and clipping (glScissor). To enable
258 that, simply call CL_OpenGLState::setup_2d() when setting up your OpenGL
259 state. Changes to the CL_GraphicContext's view matrix or clipping will be
260 applied automatically.</p>
261
262 <code>
263 // Setup my OpenGL state:
264 CL_OpenGLState my_opengl(gc);
265 my_opengl.set_active();
266
267 // We want to work in 2d, doing our own fancy OpenGL effects:
268 my_opengl.setup_2d();
269
270 // Ok so our fancy effect is just a boring triangle here :)
271 clBegin(CL_TRIANGLES);
272 clVertex2i(x, y);
273 clVertex2i(x + 10, y);
274 clVertex2i(x, y + 10);
275 clEnd();
276 </code>
277
278 </body>
279 </xml>