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
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
|
<!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: API Modifications 17</TITLE>
<META NAME="description" CONTENT="Crystal Space: API Modifications 17">
<META NAME="keywords" CONTENT="Crystal Space: API Modifications 17">
<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="SEC701"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_283.html#SEC692"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_285.html#SEC711"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_279.html#SEC650"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_279.html#SEC650"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_285.html#SEC711"> >> </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>
<H2> C.5 API Changes from 0.16 to 0.17 </H2>
<!--docid::SEC701::-->
<P>
This section documents the major changes between versions 0.16 and 0.17 of of
Crystal Space.
</P><P>
<A NAME="SEC702"></A>
<H3> Signature Change: <CODE>NextFrame(elapsed_time/current_time)</CODE> </H3>
<!--docid::SEC702::-->
<P>
<CODE>csSystemDriver::NextFrame()</CODE> no longer accepts `<SAMP>elapsed_time</SAMP>' and
`<SAMP>current_time</SAMP>' arguments, so you have to change the prototype of your own
subclassed version of <CODE>NextFrame()</CODE> and call the following three lines in
the order below (only if you need the elapsed and current time, of course):
</P><P>
<TABLE><tr><td> </td><td class=example><pre>void MySubclass::NextFrame()
{
SysSystemDriver::NextFrame();
cs_time elapsed_time, current_time;
GetElapsedTime(elapsed_time,current_time);
<small>...</small>
</pre></td></tr></table></P><P>
<A NAME="SEC703"></A>
<H3> Signature Change: <CODE>HandleEvent(csEvent)</CODE> </H3>
<!--docid::SEC703::-->
<P>
The argument of <CODE>csSystemDriver::HandleEvent()</CODE> has changed from a
`<SAMP>csEvent*</SAMP>' parameter to an `<SAMP>iEvent*</SAMP>'. Update your subclassed
versions if present.
</P><P>
<A NAME="SEC704"></A>
<H3> Materials Versus Textures </H3>
<!--docid::SEC704::-->
<P>
Crystal Space 0.17 supports <EM>materials</EM> in the sense that the API is
ready for it. There is no real material support though. A material currently
just corresponds with a texture. Here are a few short remarks about the
changes:
</P><P>
<UL>
<LI>
<CODE>csTextureHandle()</CODE> was renamed to <CODE>csTextureWrapper()</CODE>.
<P>
<LI>
New class: <CODE>csMaterialWrapper</CODE>
<P>
<LI>
The methods <CODE>SetTexture()</CODE> and <CODE>GetTexture()</CODE> were renamed to
<CODE>SetMaterial()</CODE> and <CODE>GetMaterial()</CODE>, respectively, in many places.
<P>
<LI>
The methods
<CODE>SetTextureHandle()</CODE> and <CODE>GetTextureHandle()</CODE> were renamed to
<CODE>SetMaterialWrapper()</CODE> and <CODE>GetMaterialWrapper()</CODE>, respectively.
</UL>
<P>
In general, in most places where you used to use <CODE>SetTexture()</CODE> or
<CODE>GetTexture()</CODE> you now need to use the material versions. There are few
places where you deal directly with textures. The material system sits on top
of the texture system and is what you should use in most cases.
</P><P>
`<SAMP>csWorld</SAMP>' now has a <CODE>GetMaterials()</CODE> function which you probably
should use wherever you used <CODE>GetTextures()</CODE> in the past.
</P><P>
In the loader you can find a new function, <CODE>csLoader::FindMaterial()</CODE>,
which will find a material with the given name. If not found it tries to find
a texture with of the same name and, if found, will automatically then create
a material from that texture.
</P><P>
The <CODE>csLoader::LoadTexture()</CODE> method is a bit special. As before, it
loads a texture (and returns a `<SAMP>csTextureWrapper</SAMP>') but it also adds a
material with the same name to the material list. You can then fetch that
material from that list with code similar to the following:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>csLoader::LoadTexture(world,"myTexture","/lib/std/stone4.gif");
csMaterialWrapper* m =
world->GetMaterials()->FindByName("myTexture");
</pre></td></tr></table></P><P>
<A NAME="SEC705"></A>
<H3> Collision Detection Plug-In </H3>
<!--docid::SEC705::-->
<P>
This is a very significant change. The RAPID collision detection system
has been completely removed from the engine and is now available through a
plug-in module. This change will most likely require the most complicated
changes to your code.
</P><P>
The first thing you need to add to your application is code to load the
plugin. You can do this with the following code:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>char const* p = Config->GetStr (
"YourGame",
"COLLDET_PLUGIN",
"crystalspace.colldet.rapid");
collide_system =
LOAD_PLUGIN(this, p, "CollDet", iCollideSystem);
if (!collide_system)
{
Printf(MSG_FATAL_ERROR,
"No Collision Detection plugin found!\n");
return false;
}
</pre></td></tr></table></P><P>
This code loads the rapid collision detection plugin by default (which is the
only one we have now) but it also reads an entry from your config file so that
the user can possibly change it. If you don't want that then you can just
hardcode the `<SAMP>p</SAMP>' pointer with the name of the RAPID plugin.
</P><P>
Note that you need to store the value of `<SAMP>collide_system</SAMP>' some place
where it can be accessed by the routines that need to do the collision
detection.
</P><P>
Then the class `<SAMP>csRAPIDCollider</SAMP>' has been removed from csengine. Instead
there is a new class, `<SAMP>csCollider</SAMP>'. This class encapsulates an
`<SAMP>iCollider</SAMP>' (which is something that is returned from
`<SAMP>collide_system</SAMP>'). This is the easiest way to use the new collision
detection system as it more closely resembles what was possible with
`<SAMP>csRAPIDCollider</SAMP>'. To make a `<SAMP>csCollider</SAMP>' you can use the following
code:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>iPolygonMesh* mesh =
QUERY_INTERFACE(object, iPolygonMesh);
csCollider* collider =
new csCollider(*object, collide_system, mesh);
</pre></td></tr></table></P><P>
`<SAMP>object</SAMP>' can be a sector, sprite, thing, or your own object that supports
the `<SAMP>iPolygonMesh</SAMP>' interface. The new collider will be attached (through
the `<SAMP>csObject</SAMP>' system) to the object. This is similar to what happened
with the old `<SAMP>csRAPIDCollider</SAMP>' class.
</P><P>
To do collision detection you need to find the colliders (or have them stored
somewhere) and then you can do:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>bool rc = collide_system->Collide(
col1->GetCollider(), trans1,
col2->GetCollider(), trans2);
</pre></td></tr></table></P><P>
Or:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>bool rc = col1->Collide(*object2, trans1, trans2);
</pre></td></tr></table></P><P>
With `<SAMP>col1</SAMP>' and `<SAMP>col2</SAMP>' are the colliders (`<SAMP>csCollider</SAMP>') and
`<SAMP>object2</SAMP>' is the second object. `<SAMP>trans1</SAMP>' and `<SAMP>trans2</SAMP>' are the
respective transformations.
</P><P>
Note that before you call this you probably want to initialize the collision
system like this:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>collide_system->ResetCollisionPairs();
collide_system->SetOneHitOnly(<VAR>true</VAR>/<VAR>false</VAR>);
</pre></td></tr></table></P><P>
The argument for the second function depends on wether or not you
are interested in receiving more than one hit.
</P><P>
Note that <CODE>ResetCollisionPairs()</CODE> is important. Every call
to <CODE>Collide()</CODE> will add additional collision pairs to this array.
So you have to reset it if you are no longer interested in that.
</P><P>
Note that <CODE>csRAPIDCollider::Report()</CODE> is gone. If you want that
functionality you have to do it on your own (which is not difficult).
</P><P>
<A NAME="SEC706"></A>
<H3> Texture Mapping Changes </H3>
<!--docid::SEC706::-->
<P>
The way engine defines and uses texturing has changed. There are four polygon
texturing types now:
</P><P>
<DL COMPACT>
<DT><CODE>POLYTXT_NONE</CODE>
<DD>No texturing. Useful when using materials without textures. It defines no
texturing parameters at all thus saves memory.
<P>
<DT><CODE>POLYTXT_FLAT</CODE>
<DD>Flat-shading. Only the angle between light and polygon normal is considered
if `<SAMP>CS_POLY_LIGHTING</SAMP>' flag is set, and entire polygon is painted with one
lighting value. Every vertex has an U/V pair associated.
<P>
<DT><CODE>POLYTXT_GOURAUD</CODE>
<DD>Every polygon vertex has a color and those colors are interpolated across
scanlines.
<P>
<DT><CODE>POLYTXT_LIGHTMAP</CODE>
<DD>A polygon which has an associated lightmap and a texture plane.
</DL>
<P>
Now it is possible to define and use objects which have flat-color but still
receive light with Gouraud as well as without Gouraud interpolation; in
general this open a whole new area for experimenting.
</P><P>
In practice this means that `<SAMP>csGouraudShaded</SAMP>' is gone and has been
replaced with `<SAMP>csPolyTexGouraud</SAMP>'. `<SAMP>csLightMapped</SAMP>' has also gone and
is replaced with `<SAMP>csPolyTexLightMap</SAMP>'.
</P><P>
<A NAME="SEC707"></A>
<H3> Sound Changes </H3>
<!--docid::SEC707::-->
<P>
Merged sound buffers into sound sources. We now have 3D and non-3D sound
sources. Non-3D sources are what were formerly sound buffers. As a parameter
to `<SAMP>Renderer->CreateSource()</SAMP>' you can indicate if you want a 3D or non-3D
source.
</P><P>
The sound loader is now a plugin and must be loaded as such. It uses the
`<SAMP>iSoundLoader</SAMP>' interface. A loaded sound data block is represented by
`<SAMP>iSoundData</SAMP>'.
</P><P>
If you use standard Crystal Space libraries to load sounds, this is all you
need to be aware of. Otherwise you should also know how to load a sound
without `<SAMP>csParser</SAMP>'.
</P><P>
To load a sound the sound loader now needs some information describing the
format of the sound. This information can be queried from the sound renderer.
Also, a sound can be optionally be loaded as <EM>stream</EM>. This is currently
not useful for anything, but will instead affect performance and memory in a
negative way. It is intended as a future option to load background music.
All member functions of `<SAMP>iSoundData</SAMP>' are intended for private use (of
course you may use them, but I don't think they are useful). To load a sound,
perform the following steps.
</P><P>
<OL>
<LI>
Load the file buffer from a VFS path. See section <A HREF="cs_161.html#SEC340">7.2 Virtual File System (VFS)</A>.
<P>
<LI>
Ask the sound renderer for the format descriptor (`<SAMP>csSoundFormat</SAMP>').
<P>
<LI>
Pass both the file data and the format to the sound loader, using `<SAMP>false</SAMP>'
for streaming (the default). After that, you may delete the file data.
</OL>
<P>
<A NAME="SEC708"></A>
<H3> Thing and Sprite Changes (csMovable) </H3>
<!--docid::SEC708::-->
<P>
The movement system of Things and Sprites has been merged into one class
called `<SAMP>csMovable</SAMP>'. Thus, all functions such as <CODE>SetPosition()</CODE>,
<CODE>SetTransform()</CODE>, and so on, have been removed from `<SAMP>csThing</SAMP>' and
`<SAMP>csSprite</SAMP>'. Instead there is a function <CODE>GetMovable()</CODE> (both for
Things and Sprites) which returns the `<SAMP>csMovable</SAMP>' for that object. There
is also a new function called <CODE>csMovable::UpdateMove()</CODE>--which resembles
the original <CODE>csThing::Transform()</CODE> somewhat--which you <EM>must</EM> call
after updating the position and/or transformation of the movable which belongs
to the object.
</P><P>
In addition to the changes related to `<SAMP>csMovable</SAMP>' the linked list of sky
and thing objects in a sector has also been replaced by a `<SAMP>csVector</SAMP>' and
things are now also kept in a global list in the `<SAMP>csWorld</SAMP>', just like
sprites. This means that sprites and things look a lot more like each other
now with regards to movement and placement in sectors. This means that
functions such as <CODE>AddThing()</CODE>, <CODE>GetNumThings()</CODE>,
<CODE>RemoveThing()</CODE> and <CODE>GetFirstThing()</CODE> are now gone, as are the
similar methods for sky objects. Instead, you should work through the new
public `<SAMP>skies</SAMP>' and `<SAMP>things</SAMP>' vectors. In addition to this the
<CODE>GetNext()</CODE> and <CODE>GetParent()</CODE> functions have been removed from
`<SAMP>csPolygonSet</SAMP>'.
</P><P>
Given the old code to operate on things:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>csThing* thing = new csThing(world);
sector->AddThing(thing);
thing->SetPosition(csVector3(0,0,3));
thing->SetTransform(csMatrix3());
thing->Transform();
<small>...</small>
sector->RemoveThing(thing);
delete thing;
</pre></td></tr></table></P><P>
It will need to be converted to the following:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>csThing* thing = new csThing(world);
world->things.Push(thing);
csMovable& move = thing->GetMovable();
move.SetSector(sector);
move.SetPosition(csVector3(0,0,3));
move.SetTransform(csMatrix3());
move.UpdateMove();
<small>...</small>
world->RemoveThing(thing);
</pre></td></tr></table></P><P>
Given the old to operate on sprites:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>csSprite3D* sprite = new csSprite3D(world);
world->sprites.Push(sprite);
sprite->MoveToSector(sector);
sprite->SetPosition(csVector3(0,0,3));
sprite->SetTransform(csMatrix3());
</pre></td></tr></table></P><P>
It will need to be tranformed to:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>csSprite3D* sprite = new csSprite3D(world);
world->sprites.Push(sprite);
csMovable& move = sprite->GetMovable();
move.SetSector(sector);
move.SetPosition(csVector3(0,0,3));
move.SetTransform(csMatrix3());
move.UpdateMove();
</pre></td></tr></table></P><P>
Especially note the new call to <CODE>UpdateMove()</CODE>.
</P><P>
<A NAME="SEC709"></A>
<H3> API Changes: <CODE>csCamera</CODE> </H3>
<!--docid::SEC709::-->
<P>
The function <CODE>SetFOV()</CODE> now needs an extra parameter which is the width
of the display. This is needed for calculating the angle of the FOV
(<EM>field of view</EM>). In addition, there are now new <CODE>SetFOVAngle()</CODE>
and <CODE>GetFOVAngle()</CODE> functions. <CODE>GetFOVAngle()</CODE> used to be in
<CODE>csRenderView()</CODE>.
</P><P>
<A NAME="SEC710"></A>
<H3> API Changes: <CODE>csWorld</CODE> </H3>
<!--docid::SEC710::-->
<P>
Here is a list of the more significant API changes to `<SAMP>csWorld</SAMP>'.
</P><P>
<UL>
<LI>
Added <CODE>csWorld::FindLight(char const* name)</CODE>.
<P>
<LI>
Removed <CODE>csWorld::NewSector()</CODE>. Use <CODE>world->CreateCsSector()</CODE>
instead.
<P>
<LI>
Removed <CODE>csWorld::GetThing()</CODE>. Use <CODE>world->things.FindByName()</CODE>
instead.
<P>
<LI>
Removed the method <CODE>csWorld::GetSpriteTemplate()</CODE>. Instead, use this
expression: <CODE>world->sprite_templates.FindByName()</CODE>
<P>
<LI>
Removed the method <CODE>csWorld::GetThingTemplate()</CODE>. Instead, use this
expression: <CODE>world->thing_templates.FindByName()</CODE> instead.
<P>
<LI>
Added <CODE>csWorld::UnlinkCollection()</CODE> and
<CODE>csWorld::RemoveCollection()</CODE>.
<P>
<LI>
Added <CODE>csWorld::GetBeginDrawFlags()</CODE>. This is a very important function
that you <EM>must</EM> invoke when calling <CODE>iGraphics3D::BeginDraw()</CODE> in
your application just before you give control to the engine for drawing.
</UL>
<P>
<A NAME="Index"></A>
<HR SIZE=1>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_283.html#SEC692"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_285.html#SEC711"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_279.html#SEC650"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_279.html#SEC650"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_285.html#SEC711"> >> </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>
|
