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
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- Created by texi2html 1.64 -->
<!--
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>
Send bugs and suggestions to <texi2html@mathematik.uni-kl.de>
-->
<HTML>
<HEAD>
<TITLE>Crystal Space: Rendering Loop</TITLE>
<META NAME="description" CONTENT="Crystal Space: Rendering Loop">
<META NAME="keywords" CONTENT="Crystal Space: Rendering Loop">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META NAME="Generator" CONTENT="texi2html 1.64">
</HEAD>
<BODY LANG="" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
<A NAME="SEC405"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_189.html#SEC403"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_191.html#SEC409"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_181.html#SEC390"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_168.html#SEC359"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_196.html#SEC414"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="index.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_285.html#SEC711">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<HR SIZE=1>
<H3> 7.6.8 Rendering Loop </H3>
<!--docid::SEC405::-->
<P>
<EM>Written by Jorrit Tyberghein,
<A HREF="mailto:jorrit.tyberghein@uz.kuleuven.ac.be">jorrit.tyberghein@uz.kuleuven.ac.be</A>.</EM>
</P><P>
<STRONG>Warning</STRONG>: About half of the information in this document is out of
date and no longer accurately reflects the state of the rendering engine in
Crystal Space.
</P><P>
Here is a run-through of the main rendering loop. This document is not an
explanation of portal technology. It just explains how the main rendering
loop in Crystal Space works so that you can have a quick idea of where you
have to go to see a particular part of the algorithm work. This is a rather
technical document and not intended for people who are only interested in
using Crystal Space in their own projects. It is intended for people who want
to know how Crystal Space works internally.
</P><P>
To understand this you should know how portals are used in Crystal Space. You
should also read the tutorial (see section <A HREF="cs_73.html#SEC171">5.2 Simple Tutorial 1</A>) as this explains the
basics for using Crystal Space. This document is baseed upon the
`<TT>simple</TT>' application (`<TT>CS/apps/simple/</TT>') because this discussion
looks a lot like a tutorial.
</P><P>
First we start in `<TT>apps/simple/simple.cpp</TT>'. In the <CODE>main()</CODE>
function we initialize our engine. This is an instance of the class
`<SAMP>csEngine</SAMP>' which actually represents the engine. I will not explain how
all the initialization works. This is explained in the tutorial. But I will
go straight to <CODE>csEngine::Draw()</CODE> which is called indirectly from within
<CODE>Simple::NextFrame()</CODE>. It is called indirectly because first we call
<CODE>csView::Draw()</CODE> which then calls <CODE>csEngine::Draw()</CODE>.
</P><P>
<A NAME="SEC406"></A>
<H4> World Rendering (<CODE>csEngine::Draw()</CODE>) </H4>
<!--docid::SEC406::-->
<P>
The method <CODE>csEngine::Draw()</CODE> is located in the file
`<TT>CS/libs/csengine/engine.cpp</TT>'.
</P><P>
<CODE>csEngine::Draw()</CODE> first sets up the initial `<SAMP>csRenderView</SAMP>'
structure. This structure is defined in `<TT>CS/include/csengine/rview.h</TT>'
and is the main structure which is used throughout the entire rendering
process. It collects all data that is required for rendering the recursive
portal structure.
</P><P>
Basically it contains the following information:
</P><P>
<DL COMPACT>
<DT><CODE>view</CODE>
<DD>This is the current clipper. A clipper is a 2D polygon which defines what is
visible. Every object is clipped to the view first. Every time we go through
a portal the view is modified.
<P>
<DT><CODE>g3d</CODE>
<DD><DT><CODE>g2d</CODE>
<DD>These are pointers to our 3D and 2D graphics subsystems.
<P>
<DT><CODE>clip_plane</CODE>
<DD>This is a special plane. If `<SAMP>do_clip_plane</SAMP>' is used then we clip all
geometry in 3D to `<SAMP>clip_plane</SAMP>'. This is normally not used except in
special cases where we have portals that arrive in the middle of a sector. In
that case the portal will be used as an extra clipping plane because we don't
want to render everything that is behind the arrival plane of the portal.
<P>
<DT><CODE>callback</CODE>
<DD><DT><CODE>callback_data</CODE>
<DD>These are used for special purposes which are not relevant to this discussion.
</DL>
<P>
Another important thing is that `<SAMP>csRenderView</SAMP>' is actually a subclass of
`<SAMP>csCamera</SAMP>' (`<TT>CS/include/csengine/camera.h</TT>') so all camera
functionality is present as well.
</P><P>
To set up the initial `<SAMP>csRenderView</SAMP>' structure <CODE>csEngine::Draw()</CODE>
creates a new instance based upon the given camera.
</P><P>
After this <CODE>csEngine::Draw()</CODE> gets the current sector from the camera and
calls <CODE>csSector::Draw()</CODE> (`<TT>CS/libs/csengine/sector.cpp</TT>'). This will
essentially draw the whole screen as discussed below.
</P><P>
After doing this (now that the screen is fully updated) we optionally draw
halos. Halos are drawn on top of everything else since they are an effect in
the eyes.
</P><P>
<A NAME="SEC407"></A>
<H4> Sector Rendering (<CODE>csSector::Draw()</CODE>) </H4>
<!--docid::SEC407::-->
<P>
This method <CODE>csSector::Draw()</CODE> is located in
`<TT>CS/libs/csengine/sector.cpp</TT>'.
</P><P>
<CODE>csSector::Draw()</CODE> is responsible for rendering everything in the current
sector. It will do this by first rendering the walls of the sector (using
Z-fill only). It is possible that there is a BSP tree attached to the
sector. In that case <CODE>csSector::Draw()</CODE> will use that BSP tree to
sort the wall polygons back to front.
</P><P>
Before actually starting to render, it will first transform the sector to the
camera position so that (0,0,0) is the camera point, (1,0,0) is one unit right
of the camera, (0,1,0) is one unit above the camera, and (0,0,1) is one unit
above the camera. This is done in <CODE>csPolygonSet::NewTransformation()</CODE>
and <CODE>csPolygonSet::TransformWorld2Cam()</CODE> (see
`<TT>CS/libs/csengine/basic/polyset.cpp</TT>'). The call to
<CODE>NewTransformation()</CODE> is needed because it is possible that we render the
same sector multiple times in the same recursion tree. Because of this we
don't actually want to loose the transformation that occured the previous time
so <CODE>NewTransformation()</CODE> takes care of potentially storing the old
transformation and setting a new one (mirrors and other space warping portals
make this feature essential).
</P><P>
After that actual drawing of the transformed polygons is performed by the
method <CODE>csSector::DrawPolygons()</CODE>, which in turn calls
<CODE>csPolygonSet::DrawPolygonArray()</CODE>. The `<SAMP>csPolygonSet</SAMP>' class is
implemented in `<TT>CS/libs/csengine/basic/polyset.cpp</TT>'), and
<CODE>DrawPolygonArray()</CODE> is discussed further in the next section.
</P><P>
While drawing the polygons of the sector (which are the sector's walls) some
of them may be portals. In that case <CODE>csPolygonSet::DrawPolygonArray()</CODE>
will immediatelly perform recursion to the destination sector of the portal.
This means creating a new `<SAMP>csRenderView</SAMP>' with the new view and then
recursing into <CODE>csSector::Draw()</CODE> of the new sector. It is important to
note that <CODE>DrawPolygonArray()</CODE> may already enter recursion for a new
sector even though the first sector has not finished drawing yet.
</P><P>
So it is important to note that after drawing all sector walls we have in fact
drawn the entire world visible from this sector (including things and sprites
in other sectors). But we have not drawn things and sprites in this sector
yet.
</P><P>
<CODE>csSector::Draw()</CODE> will then continue to draw all things in the current
sector. There are some special cases here. It is possible that all
non-moving things have been collected into one thing which has an attached
BSP tree. This is the `<SAMP>static_thing</SAMP>'. If that exists we first
render that `<SAMP>static_thing</SAMP>' by using back to front ordering and using
Z-fill instead of Z-buffer. Note that all non-moving things which were
collected into the static thing are still in the list of things for the
sector. But you can recognize them because they <CODE>IsMerged()</CODE> returns
true.
</P><P>
Now there are two important cases depending on wether or not there was a
static thing in the previous case. If there was a static thing or if the
sector itself had a BSP tree, then all remaining things have to be drawn
using the Z-buffer (ignoring foggy things for the moment). In this case we
can't use Z-fill anymore because there was a BSP tree used to render the
previous sector or static thing.
</P><P>
If there was no static thing and there was no BSP tree for the sector
then we can still use Z-fill to render all convex things provided we render
them back to front. This part of the algorithm does not work correctly yet
and that's the reason that it has been disabled.
</P><P>
In any case all foggy things are collected and then Z-sorted. This is also
not correct but currently the only way. Here we need a better way to do
Z-sorting.
</P><P>
Now we can proceed to drawing all sprites. <STRONG>Warning</STRONG>: <EM>The
remainder of this paragraph is no longer true.</EM> Currently this algorithm is
somewhat simple. It assumes that a sprite always lives in one sector. This
is of course not always right and the sprite structure (`<SAMP>csSprite3D</SAMP>' in
`<TT>CS/libs/csengine/objects/cssprite.h</TT>') already has provisions for the
fact that a single sprite can live in several sectors at the same time. What
we want to do here is to only draw a sprite if one of the below conditions is
true:
</P><P>
<OL>
<LI>
The current sector is being rendered through an alpha mapping portal.
<P>
<LI>
The sector we came from before entering the portal (in the render process) is
also a sector where the sprite lives.
</OL>
<P>
In the first case we have to clip the sprite to the portal and render only the
side on this portal. When returning from the recursion we will have to render
the other side of the sprite.
</P><P>
In the second case we don't render the sprite but it will be rendered when we
return from our recursion because the sprite is also part of the previous
sector.
</P><P>
The next step in <CODE>csSector::Draw()</CODE> is to queue all halos that were
encountered in this sector so that they can be drawn later. A Z-buffer
visibility test will be used later to make sure that the halo only appears
when the center is visible.
</P><P>
Finally we conclude by optionally fogging the current sector if this is
needed. There are currently two ways of fogging:
</P><P>
<UL>
<LI>
Using the Z-buffer (`<SAMP>G3DFOGMETHOD_ZBUFFER</SAMP>').
<P>
<LI>
Using planed fog (`<SAMP>G3DFOGMETHOD_PLANES</SAMP>').
</UL>
<P>
<EM>Fixme</EM>: Is the next paragraph even accurate anymore?
</P><P>
The last method does not work correctly at this time. The first method is
only implemented by the software renderer.
</P><P>
The method <CODE>csSector::Draw()</CODE> ends by restoring the transformation by
calling <CODE>csPolygonSet::RestoreTransformation()</CODE>.
</P><P>
<A NAME="SEC408"></A>
<H4> Polygon Array Rendering (<CODE>csPolygonSet::DrawPolygonArray()</CODE>) </H4>
<!--docid::SEC408::-->
<P>
The implementation of <CODE>csPolygonSet::DrawPolygonArray()</CODE> can be found in
the file `<TT>CS/libs/csengine/basic/polyset.cpp</TT>'.
</P><P>
Both `<SAMP>csSector</SAMP>' and `<SAMP>csThing</SAMP>' inherit from `<SAMP>csPolygonSet</SAMP>' so
they both basically use the same way of rendering polygons.
<CODE>DrawPolygonArray()</CODE> is responsible for that. <CODE>DrawPolygonArray()</CODE>
is typically called on either the complete list of polygons for the
`<SAMP>csThing</SAMP>' or `<SAMP>csSector</SAMP>' or else a subset which was computed from a
BSP tree.
</P><P>
<CODE>DrawPolygonArray()</CODE> will process every polygon in the array in turn. It
will basically call the following three functions for every polygon:
</P><P>
<OL>
<LI>
<CODE>csPolygon3D::ClipToPlane()</CODE> (`<TT>CS/libs/csengine/polygon/polygon.cpp</TT>')
<P>
<LI>
<CODE>csPolygon3D::DoPerspective()</CODE>
<P>
<LI>
<CODE>csPolygon2D::ClipAgainst()</CODE>
</OL>
<P>
<CODE>ClipToPlane()</CODE> will do a quick test to see if all vertices of the
polygon are in front of the Z-plane. That will at least exclude polygons
quickly which are behind the viewer. Then it will perform backface culling.
Finally it will process the special `<SAMP>clip_plane</SAMP>' field in
`<SAMP>csRenderView</SAMP>' which was mentioned in the beginning of this document. In
other words, it will clip the polygon in 3D to that plane. This is rarely
needed.
</P><P>
If <CODE>ClipToPlane()</CODE> fails then the polygon is not visible and we don't
need to continue with the other steps.
</P><P>
<CODE>DoPerspective()</CODE> does perspective correction on the polygon and thus
transforms the polygon from 3D to 2D. The 2D polygon will be placed in a
special static variable of type `<SAMP>csPolygon2D</SAMP>' (called `<SAMP>clipped</SAMP>').
Finally it will also transform the plane of the polygon to camera space.
</P><P>
<CODE>DoPerspective()</CODE> can also fail in which case the polygon is not visible
and processing can stop here.
</P><P>
Finally we do <CODE>ClipAgainst()</CODE>. This will clip the polygon to the current
view. The clipping happens in place. The result will be in `<SAMP>clipper</SAMP>'.
</P><P>
If <CODE>ClipAgainst()</CODE> fails the polygon was completely clipped away and we
don't need to show anything.
</P><P>
When all three steps above succeed we have a visible (part) of a polygon which
has been perspective corrected. We can now render that polygon.
</P><P>
If the polygon is a portal then we initiate a recursive process by calling the
method <CODE>csPortal::Draw()</CODE> (`<TT>CS/libs/csengine/polygon/portal.cpp</TT>')
which will in turn call <CODE>csSector::Draw()</CODE> for the destination sector.
<CODE>csPortal::Draw()</CODE> also takes care of possible space warping and also
creation of the `<SAMP>clip_plane</SAMP>' in `<SAMP>csRenderView</SAMP>' if this should be
needed.
</P><P>
If a portal has an alpha transparent texture superimposed then we will draw
that texture on top of the portal when <CODE>csPortal::Draw()</CODE> returned.
However since `<SAMP>clipped</SAMP>' is a static variable we need to copy it locally
to be able to draw it again later. This happens in `<SAMP>keep_clipped</SAMP>' and
`<SAMP>keep_plane</SAMP>'.
</P><P>
If the polygon was not a portal then we just render it. This happens in
<CODE>csPolygon2D::DrawFilled()</CODE> (from the file
`<TT>CS/libs/csengine/polygon/polygon.cpp</TT>') which is further explained in the
next section.
</P><P>
That's basically it for this function.
<A NAME="3D Sprites"></A>
<HR SIZE=1>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_189.html#SEC403"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_191.html#SEC409"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_181.html#SEC390"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_168.html#SEC359"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_196.html#SEC414"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="index.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_285.html#SEC711">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<BR>
<FONT SIZE="-1">
This document was generated
using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
"><I>texi2html</I></A>
</BODY>
</HTML>
|
