| 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> |