Debian Codegraph @

Documentation/Overview/display-1.xml

raw
1 <xml>
2 <head>
3 <title>ClanLib Display</title>
4 <eyecolor>yellow</eyecolor>
5 </head>
6 <body>
7
8 <p>To do graphics with ClanLib, you need to use clanDisplay. This module
9 acts as an abstraction for any graphics target available via ClanLib -
10 currently the OpenGL and SDL targets. ClanDisplay allows you to do stuff in
11 the following categories:</p>
12
13 <ul>
14 <li>Top level windows</li>
15 <li>Handling input (see <a href="input.html">Input overview</a>)</li>
16 <li>Drawing simple graphics</li>
17 <li>Loading images from common formats</li>
18 <li>Animating images easily</li>
19 <li>Font and text rendering</li>
20 <li>Working with image data</li>
21 </ul>
22
23 <p>ClanDisplay is an abstraction, working to allow ClanLib applications to
24 do stuff in a general matter that can be applied to any display target
25 supported by ClanLib. In order to use clanDisplay, one or more display
26 targets must also be setup. For example, a GL-based ClanLib app must
27 call both CL_SetupDisplay::init() and
28 CL_SetupGL::init() when starting.</p>
29
30 <p>The SDL target does not support every feature currently offered by
31 clanDisplay, and it most likely never will. The main point of the
32 SDL target in ClanLib is to support older cards that come with no 3D
33 accelerator. ClanDisplay has been written to try take advantage of as much
34 of modern OpenGL hardware acceleration as possible - for example, all the
35 blending functions offered by glBlendFunc. Implementing a software target for
36 all this is would take forever, and most likely would end up being as slow as using
37 OpenGL software targets such as Mesa. Instead, the clanSDL target aims at only
38 supporting the things that SDL API itself supports; it's better for it
39 to get some things fast, instead of everything slow.</p>
40
41 <p>Because clanDisplay is an abstraction, its API in itself will not
42 directly offer you access to the objects the implementation is using.
43 Instead, each of the display targets offer their own set of subclasses for
44 clanDisplay. For more information about this, see the
45 <a href="opengl_overview.html">OpenGL overview</a>.</p>
46
47 <p>In general, if you are just doing normal 2D graphics, you will not need to
48 use the target specific interfaces.</p>
49
50 <h3>Top level windows</h3>
51 <p>Main classes: <codelink>CL_DisplayWindow</codelink>,
52 <codelink>CL_DisplayWindowDescription</codelink>.</p>
53
54 <p>Before you can do any graphics with ClanLib, you need to create a window
55 for your application. CL_DisplayWindow creates such a top level window.
56 There are two ways to create it; either use one of the convenience
57 constructors on CL_DisplayWindow:</p>
58
59 <code>
60 CL_DisplayWindow window("My ClanLib Window", 640, 480);
61 </code>
62
63 <p>Or you can create it by setting up a CL_DisplayWindowDescription, and
64 pass that to CL_DisplayWindow:</p>
65
66 <code>
67 CL_DisplayWindowDescription desc;
68 desc.set_title("My ClanLib Window");
69 desc.set_size(CL_Size(640, 480));
70 CL_DisplayWindow window(desc);
71 </code>
72
73 <p>If you need to set target specific parameters, you can create a
74 CL_OpenGLWindowDescription or CL_SDLWindowDescription object instead.</p>
75
76 <p>The CL_DisplayWindow object mainly gives you access to four things: a
77 graphic context (for rendering to the screen), an input context (for getting input from the user),
78 pixel buffers for back and front buffers (for accessing the frame buffer) and top level
79 window management (for setting window position, resizing the window, going fullscreen, etc):</p>
80
81 <code>
82 CL_GraphicContext *gc = window.get_gc();
83 CL_InputContext *ic = window.get_ic();
84 CL_PixelBuffer buffer = window.get_back_buffer();
85 window.set_fullscreen();
86 </code>
87
88
89
90 <h3>Drawing simple graphics</h3>
91 <p>Main classes: <codelink>CL_GraphicContext</codelink>,
92 <codelink>CL_Surface</codelink></p>
93
94 <p>After setting up a display window and learning how to deal with input
95 from it, the next logical step is to draw something in the window. All
96 drawing in ClanLib is done on a graphic context, which CL_GraphicContext
97 abstracts. Just like with the input context, CL_DisplayWindow also has a
98 function get_gc() that returns the graphic context.</p>
99
100 <p>The graphic context itself has a set of functions that allow you to draw
101 some common primitives (lines, boxes, gradients, etc.). These functions
102 are fairly straightforward:</p>
103
104 <code>
105 CL_DisplayWindow window("My ClanLib Window", 640, 480);
106 CL_GraphicContext *gc = window.get_gc();
107 gc->clear(CL_Color::black);
108 gc->draw_line(100, 100, 400, 400, CL_Color::red);
109 gc->draw_rect(CL_Rect(101,101,399,399), CL_Color::blue);
110 </code>
111
112 <p>Sometimes it's practical to limit the drawing of items to a specific area
113 of the screen. ClanLib always uses the screen boundary as a clipping
114 rectangle, so you never have to worry about showing objects outside the
115 screen - just call the draw-function and they are trivially rejected by the
116 clipper.</p>
117
118 <p>Like many other clipping systems, the ClanLib clipping system uses a
119 stack principle. It's not possible to create polygonal clipping areas this
120 way. Instead, if you push a new clipping rectangle upon the clipping stack,
121 the single clipping rectangle used to clip further graphics is defined as
122 the area shared by the previous clipping rectangle and the newly pushed one
123 (the intersection).</p>
124
125 <p>The previous clipping rectangle is stored and brought back to use when
126 the clipping rectangle in action is popped off the clipping stack. However,
127 it's also possible to set the clipping rectangle in absolute terms,
128 disregarding any previous clipping rectangles.</p>
129
130 <p>Example of use:</p>
131
132 <code>
133 gc->push_cliprect(CL_Rect(10,10,100,100));
134 gc->clear(CL_Color::black);
135 gc->fill_rect(CL_Rect(0, 0, 400, 400), CL_Color::white);
136 gc->pop_cliprect();
137 </code>
138
139 <p>In this example, the clear() and fill_rect() calls are clipped to the
140 10,10,100,100 rectangle.</p>
141
142 <p>A translation stack is also available.</p>
143
144 <p>To draw images on a graphic context, we need to use the surface class.
145 <codelink>CL_Surface</codelink> is the interface that stores images in a texture and perform
146 drawing commands to render it. Using CL_Surface is rather simple and
147 straightforward. Create the surface by specifying a source for the image to
148 be loaded from, then call draw() to render it:</p>
149
150 <code>
151 CL_Surface image("cow.png");
152 image.draw(10, 10, gc);
153 </code>
154
155 <p><i>Note:</i> It is important you create your surface objects <i>after</i>
156 you have created the display window. Otherwise, mysterious crashes will result.
157 This is a known bug, and might be fixed in a future version of ClanLib.</p>
158
159 <p>All the operations done by CL_GraphicContext are implemented by making
160 calls to OpenGL (or SDL, if that's the display target). OpenGL uses a state
161 machine model where states affect the result of primitive drawing commands -
162 for example, the OpenGL command glBlendMode affects how textures with
163 glBegin(GL_TRIANGLES) blend to the framebuffer. If an application needs to
164 do its own lower level drawing using direct OpenGL calls, there has to be
165 some kind of cooperation between ClanLib and the application about OpenGL
166 states.</p>
167
168 <p>In other words, it is possible for a ClanLib application to interact directly
169 with OpenGL, but you must warn ClanLib before and after doing so.</p>
170
171 <p>An application tells ClanLib it wants to do OpenGL operations by calling
172 the begin_3d() method on the graphic context. This causes ClanLib to flush any pending
173 drawing commands it has queued for rendering, restore the view matrix, and
174 set other OpenGL states to their defaults. When the application is done
175 doing its own drawing, it should restore the states to OpenGL defaults, then
176 call end_3d() to tell ClanLib it can setup the OpenGL states for its own use
177 again.</p>
178
179 <code>
180 gc->begin_3d();
181 glMatrixMode(GL_PROJ_MATRIX);
182 glPushMatrix();
183 glProject(...);
184 glMatrixMode(GL_VIEW_MATRIX);
185 glPushMatrix();
186 gluLookAt(...);
187 glBegin(GL_POLYGONS);
188 glColor3f(1.0f, 1.0f, 0.0f);
189 for (int i=0; i<100; i++) glVertex3f(x[i],y[i],z[i]);
190 glEnd(GL_POLYGONS);
191 glPopMatrix();
192 glMatrixMode(GL_PROJ_MATRIX);
193 glPopMatrix();
194 gc->end_3d();
195 </code>
196
197 <p>We are currently working on a system to control states in a more
198 intelligent way in ClanLib. When this system is done, the begin_3d/end_3d
199 system may be modified, but it should be fairly straightforward to port
200 any code using the current model.</p>
201
202 <h3>Loading images from common formats</h3>
203 <p>Main classes:
204 <codelink>CL_JPEGProvider</codelink>, <codelink>CL_PNGProvider</codelink>,
205 <codelink>CL_PCXProvider</codelink>,
206 <codelink>CL_TargaProvider</codelink>.</p>
207
208 <p>As mentioned in the previous section, <codelink>CL_Surface</codelink> needs a source for its
209 image data. Image data is offered through the <codelink>CL_PixelBuffer</codelink> interface. A
210 pixel buffer is an image format description, plus the image data itself. You
211 can feed CL_Surface with any image made available via a pixel buffer, but in
212 most cases the built-in image providers will do. Currently those are the
213 JPEG (.jpg), PNG (.png), PCX (.pcx) and Targa (.tga) providers.</p>
214
215 <p>The constructor on CL_Surface that take a filename uses the interface
216 <codelink>CL_ProviderFactory</codelink> to find a suitable surface provider
217 (pixel buffer) that can load the image. If you write your own image loader,
218 and want ClanLib to be able to recognize images of the new type based on
219 the filename extension, you must add a <codelink>CL_ProviderType</codelink> object to
220 CL_ProviderFactory::types.</p>
221
222 <p>It is not possible to directly examine the image contained in a surface.
223 CL_Surface does not keep a local copy of the image it uploads to the texture.
224 CL_Surface offers a function called get_pixeldata() that can download the
225 image from the texture, but this can result in a loss of quality depending
226 on the graphics card. The original picture may be in 32 bit with 8 bits per
227 channel for red, green, blue and alpha - but when stored on the card it may
228 been stored in 16 bit, with 4 bits per channel.</p>
229
230 <p>If it is needed to examine the image used by a surface, the best way to
231 do it is to first load image into a pixel buffer, analyze the image, and
232 then pass on the pixel buffer to CL_Surface:</p>
233
234 <code>
235 CL_PixelBuffer *image = new CL_PNGProvider("dog.png");
236 image->lock();
237 examine_image(
238 image->get_format(),
239 image->get_width(),
240 image->get_height(),
241 image->get_pitch(),
242 image->get_data());
243 image->unlock();
244 CL_Surface surface(image, true);
245 </code>
246
247 <p><i>Note:</i> The built-in surface providers in ClanLib will not return
248 the correct values for get_width(), get_height(), get_pitch() and
249 get_format() until lock() have been called the first time. This will be
250 fixed in a future version of ClanLib.</p>
251
252 <h3>Animating images easily</h3>
253 <p>Main classes: <codelink>CL_Sprite</codelink>,
254 <codelink>CL_SpriteDescription</codelink>,
255 <codelink>CL_SpritePacker</codelink>.</p>
256
257 <p>As most people probably know, a sprite is a collection of 2D images
258 (called frames), shown in sequence with a delay between each frame. Sprites
259 are used for a lot of game objects, i.e. moving people, spaceships, chairs,
260 powerups, missiles, animated mouse cursors, etc.</p>
261
262 <p><codelink>CL_Sprite</codelink> does all this for you in a very easy, yet
263 flexible way. The simplest sprites are just a collection of frames, all
264 shown after each other, drawn on the screen somewhere.</p>
265
266 <p>You can also rotate sprites and make them translucent, you can tweak the
267 animation speed for individual frames, set frame offsets, set drawing and
268 rotation alignment, play frames in a backward looping pattern, a ping-pong loop,
269 forward just-once, etc. Basically, CL_Sprite can do most things you'll ever need for basic 2d
270 sprites.</p>
271
272 <p>ClanLib's sprites are rather advanced. Because of this it got its own
273 overview. You can <a href="sprites_overview.html">read it here</a>.</p>
274
275 <h3>Font and text rendering</h3>
276 <p>Main classes: <codelink>CL_Font</codelink>,
277 <codelink>CL_TextStyler</codelink>,
278 <codelink>CL_GlyphBuffer</codelink>.</p>
279
280 <p>Drawing text in ClanLib is simple, but creating a font is slightly more
281 complex. There is support for drawing both system fonts and bitmap fonts,
282 but the system font support should be considered experimental at this time.
283 Creating a bitmap font requires some basic knowledge about sprites - CL_Font
284 collects its bitmap glyphs from a sprite.</p>
285
286 <p>The easiest way to construct your first font is to take a look at one of
287 the font image files from ClanLib's examples, and then <a
288 href="font_overview-1.html">read the font overview</a>.</p>
289
290 <h3>Working with image data</h3>
291 <p>Main classes: <codelink>CL_PixelBuffer</codelink>,
292 <codelink>CL_PixelFormat</codelink>, <codelink>CL_Palette</codelink>.</p>
293
294 <!--
295
296 <p>Displaying 2D graphics, setting the video mode and drawing on
297 the screen are very basic features of any game. The ClanLib
298 2D api provides support for this and several other things,
299 including:</p>
300
301 <ul>
302 <li>Setting a videomode</li>
303 <li>Clearing the screen</li>
304 <li>Drawing sprites</li>
305 <li>Drawing lines/rectangles</li>
306 <li>Clipping</li>
307 <li>Printing text</li>
308 </ul>
309
310 <h3>ClanDisplay class overview</h3>
311
312 <p>ClanDisplay is divided into several classes.</p>
313
314 <p>Note that input is part of the display component in ClanLib, there
315 is no separate ClanInput. The input API and its classes are explained
316 in a separate documentation overview.</p>
317
318 <p>Here is a short overview over the most important display classes:</p>
319
320 <ul>
321 <li><codelink>CL_Display</codelink>
322 <p>The display class provides a static function interface to
323 CL_DisplayWindow and other display classes. It uses a selected
324 display window (by default the first created window) to call the
325 equivalent functions in CL_DisplayWindow, CL_GraphicContext and such.</p>
326 <p>The entire point of this is to allow applications with only one
327 window to not pass around a pointer to the display window.</p></li>
328
329 <li><codelink>CL_DisplayWindow</codelink>
330 <p>CL_DisplayWindow represents a window in your windowing system
331 (Windows, X11). You need to create at least one display window in order
332 to draw graphics in ClanLib.</p></li>
333
334 <li><codelink>CL_GraphicContext</codelink>
335 <p>A graphic context is something that ClanLib can render onto, for
336 examples a CL_DisplayWindow, CL_Canvas or CL_PixelBuffer.</p>
337
338 <li><codelink>CL_InputContext</codelink>
339 <p>An input context is a collection of inputdevices available in
340 a displaywindow.</p>
341
342 <li><codelink>CL_PixelBuffer</codelink>
343 <p>Pixel data access.</p>
344
345 <li><codelink>CL_PixelFormat</codelink>
346 <p>Pixel data format description.</p>
347
348 <li><codelink>CL_Surface</codelink>
349 <p>A surface is an image you can draw to the display, having
350 support for scaling, rotation, alignment and more.</p>
351
352 <li><codelink>CL_Canvas</codelink>
353 <p>The Canvas class is a special surface that is optimized for rapid
354 changes in its pixel data. This is opposite to CL_Surface, which is optimized
355 for no changes in its pixel data.</p>
356
357 <li><codelink>CL_Texture</codelink>
358 <p>A texture is just a simple texture, nice for use in 3D application.</p>
359
360 <li><codelink>CL_Font</codelink>
361 <p>Font makes it possible to write text to a displaywindow, with support for
362 scaling, rotation, alignment, and more.</p>
363
364 <li><codelink>CL_Sprite</codelink>
365 <p>Animated sprites with CL_Sprite is both easy, and very powerful.</p>
366
367 </ul>
368
369 <p><a href="display-2.html">Move on to part two</a>.</p>
370
371 -->
372
373 </body>
374 </xml>