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
|
<!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: MeshObject TerrFunc</TITLE>
<META NAME="description" CONTENT="Crystal Space: MeshObject TerrFunc">
<META NAME="keywords" CONTENT="Crystal Space: MeshObject TerrFunc">
<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="SEC530"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_216.html#SEC529"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_218.html#SEC536"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_196.html#SEC414"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_201.html#SEC452"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_220.html#SEC543"> >> </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.8.16 Terrain Mesh Object </H3>
<!--docid::SEC530::-->
<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>
This mesh object represents a landscape engine. It features four static
LOD levels and dynamic lighting for one directional light. In future
it will also have support for dynamic shadows but this is still a todo
at this moment.
</P><P>
The basic principle behind the terrain engine is that the entire terrain
is divided in a number of blocks. Usually this is equal to 8x8 blocks
for the terrain but this is something that you can control. The division
into blocks is important for three reasons. The first reason is that LOD
selection happens on a block level. i.e. every block is shown at one level
of LOD independent from the other blocks. The second reason is that
visibility culling for terrain engine also works on block granularity (also
the visibility algo itself goes deeper for doing the actual tests). The
last reason for the blocks is that every block can have a seperate texture.
This is important because some hardware has texture limitations and you
often want to overlay a very big texture on a landscape. Since very block
has its own texture you can do this easily.
</P><P>
The terrain engine is based on a height function (as opposed to a heightmap
alone). Support for heightmaps is provided too by converting a heightmap
to a height function. But in general you can feed the terrain engine with
any function <CODE>height=heightfunc(x,y)</CODE>. You can also optionally give
a normal function. If not given the landscape engine will calculate normals
from the height function automatically.
</P><P>
Every block is further divided into a grid. For example, with a grid
of 16x16 every block will have 16x16 quads or 16x16x2 triangles at the
highest detail level. The combination of blocks and grids control how
many triangles the entire terrain will have.
</P><P>
The terrain engine supports four levels of LOD which it will use
independently for every block. Level 0 is highest detail. You can control
the distance at which every LOD level kicks in and you can also
control the quality of every level.
</P><P>
The terrain engine supports a visibility algorithm based on a quad-tree.
The visibility algorithm will cull away geometry on a blocks level (i.e.
either an entire block is visible or not). But internally it will use
a quad-tree which can (and should) go deeper than the blocks resolution
to make sure that the visibility testing is fine enough.
</P><P>
Every block has its own texture. You can use a big texture and split it
into individual parts. One part for every block. Crystal Space also has
a texture generation utility which is able to create realistic terrain
textures given several base textures and a heightmap.
</P><P>
The terrain engine also supports one colored directional light without
shadows. In the future we will have support for dynamic shadows.
</P><P>
<A NAME="SEC531"></A>
<H4> Basic Structure </H4>
<!--docid::SEC531::-->
<P>
The following SCF class names are used (for <CODE>CS_LOAD_PLUGIN()</CODE>):
</P><P>
<UL>
<LI>
Type plugin: `<SAMP>crystalspace.mesh.object.terrfunc</SAMP>'
<LI>
Loader plugin: `<SAMP>crystalspace.mesh.loader.terrfunc</SAMP>'
<LI>
Factory loader plugin: `<SAMP>crystalspace.mesh.loader.factory.terrfunc</SAMP>'
</UL>
<P>
Objects in this plugin implement the following SCF interfaces (get
with <CODE>SCF_QUERY_INTERFACE()</CODE>):
</P><P>
<UL>
<LI>
<EM>MeshObject</EM>
<UL>
<LI>
Implements `<SAMP>iMeshObject</SAMP>'
<LI>
Implements `<SAMP>iTerrFuncState</SAMP>'
</UL>
<LI>
<EM>MeshObjectFactory</EM>
<UL>
<LI>
Implements `<SAMP>iMeshObjectFactory</SAMP>'
</UL>
<LI>
<EM>MeshObjectFactory</EM>
<UL>
<LI>
Implements `<SAMP>iMeshObjectType</SAMP>'
</UL>
</UL>
<P>
<A NAME="SEC532"></A>
<H4> Factory State Interface </H4>
<!--docid::SEC532::-->
<P>
This plugin has no factory state interface.
</P><P>
<A NAME="SEC533"></A>
<H4> Factory Loader </H4>
<!--docid::SEC533::-->
<P>
The fire mesh factory loader has no parameters.
</P><P>
<A NAME="SEC534"></A>
<H4> Object State Interface </H4>
<!--docid::SEC534::-->
<P>
`<SAMP>iTerrFuncState</SAMP>' is the SCF interface that you can
use to set/get settings for a landscape object. The definition of this
interface can be found in `<TT>CS/include/imesh/terrfunc.h</TT>' and that's also
the include file you need to include in your applications to use this plugin.
Using this interface you can access the terrain parameters.
</P><P>
<A NAME="SEC535"></A>
<H4> Object Loader </H4>
<!--docid::SEC535::-->
<P>
The terrain loader recognizes the following keywords:
</P><P>
<DL COMPACT>
<DT><CODE>FACTORY(factoryName)</CODE>
<DD>Name of the factory to use for creation of this instance.
<DT><CODE>MATERIAL(number,materialName)</CODE>
<DD>The material to use for the given block of the terrain. The
block number is 0 to the total number of blocks (see the
`<SAMP>BLOCKS</SAMP>' command).
<DT><CODE>ALLMATERIAL(materialName)</CODE>
<DD>The material to use for all blocks of the terrain.
<DT><CODE>GROUPMATERIAL(materialNameFormat,start,end)</CODE>
<DD>`<SAMP>materialNameFormat</SAMP>' is a <CODE>printf</CODE> style string
containing a <CODE>%d</CODE> to indicate the number used for the material
name. `<SAMP>start</SAMP>' and `<SAMP>end</SAMP>' indicate the range of materials
to set (block numbers).
<DT><CODE>CORRECTSEAMS(textureWidth,textureHeight)</CODE>
<DD>When the given materials are split from a big texture you can use
`<SAMP>CORRECTSEAMS</SAMP>' to make sure the textures line up correctly at
the borders of blocks. Here is an example. Given a terrain of 8x8
blocks (64 total) and given a texture size of 128x128 for every block
you would have to generate a total big texture with horizontal and
vertical dimensions equal to <CODE>(partsize-2)*8+2</CODE>. In this case (with
partsize equal to 128) this would mean a total texture of 1010x1010 where
every block gets a 128x128 texture where the borders are shared with the
adjacent block (hence the 126x126 that is really allocated for one block).
If you follow these guidelines you can then use <CODE>CORRECTSEAMS(128,128)</CODE>
and you will have perfectly aligned textures for all 8x8 blocks.
<DT><CODE>BLOCKS(xblocks,yblocks)</CODE>
<DD>The number of blocks in horizontal and vertical direction. Blocks are
important for visibility culling and LOD selection because these happen
on a block level. So you should use enough blocks to make sure that
everything works smoothly. 8x8 is probably a good bet in most cases.
4x4 is a default though.
Warning! Due to a current limitation in the terrain
engine the number of horizontal blocks must be equal to the number of
vertical blocks.
<DT><CODE>GRID(xgrid,ygrid)</CODE>
<DD>With `<SAMP>GRID</SAMP>' you control the highest detail resolution of every
block. For example <CODE>GRID(16,16)</CODE> means that every block will use
16x16 quads (or 16x16x2 triangles) at highest detail. The default value
for `<SAMP>GRID</SAMP>' is 8x8.
<DT><CODE>TOPLEFT(x,y,z)</CODE>
<DD>The top-left coordinate of the terrain. By default this is (0,0,0).
For `<SAMP>x</SAMP>' and `<SAMP>z</SAMP>' the terrain will be generated from 0 to
`<SAMP>xblocks-1</SAMP>' and `<SAMP>yblocks-1</SAMP>' respectively. Use `<SAMP>SCALE</SAMP>'
to scale this first and then use `<SAMP>TOPLEFT</SAMP>' to relocate.
The `<SAMP>y</SAMP>' value in `<SAMP>TOPLEFT</SAMP>' will be added to the height
function (after scaling).
<DT><CODE>SCALE(x,y,z)</CODE>
<DD>Scale the entire terrain. `<SAMP>x</SAMP>' and `<SAMP>z</SAMP>' will scale the
default 0 to `<SAMP>xblocks-1</SAMP>' and `<SAMP>yblocks-1</SAMP>'. The `<SAMP>y</SAMP>'
scale will be used to multiply with the value from the height function.
<DT><CODE>COLOR(r,g,b)</CODE>
<DD>This is the base color which will be added to all triangle of the
terrain. Consider this a kind of ambient lighting. Default is black.
Full bright would be <CODE>1,1,1</CODE>.
<DT><CODE>DIRLIGHT(x,y,z:r,g,b)</CODE>
<DD>Set a directional light. <CODE>x,y,z</CODE> is a normal vector for the light.
<CODE>r,g,b</CODE> is the color of the light.
<DT><CODE>LODDIST(lodlevel,distance)</CODE>
<DD>Set the distance at which we switch to the given LOD level. LOD
level 0 (highest detail) is always used for very close viewpoints but you
can control distance for levels 1, 2, and 3. Default values are 100,
400, and 800 for the three levels. Note that LOD happens on a
block basis so for every block the distance here will be used to see
what LOD level to select.
<DT><CODE>LODCOST(lodlevel,maxcost)</CODE>
<DD>Set the cost factor to use for going from the previous LOD level
to the new one. High values for `<SAMP>maxcost</SAMP>' mean that more triangles
will be removed (i.e. better LOD but worse quality). The default
values are <CODE>0.03</CODE>, <CODE>0.08</CODE>, and <CODE>0.2</CODE>. So `<SAMP>LODDIST</SAMP>'
controls at which distance a new LOD level is selected while
`<SAMP>LODCOST</SAMP>' controls the quality of every LOD level. The base
quality (i.e. highest quality) of every block is controlled with the
`<SAMP>GRID</SAMP>' command.
<DT><CODE>QUADDEPTH(quaddepth)</CODE>
<DD>Control the depth of the quad-tree which is used for visibility culling.
This depth is measured from the entire terrain. Usually you make sure
that the depth is high enough so that individual blocks are at least
sub-divided about three extra times. i.e. given a terrain with 8x8 blocks
you would probably want to use a depth of six (which is default). Higher
quadtree depth's will increase the cost of visibility culling but also
increase the accuracy. So a higher depth will be more important for a
slow renderer (software renderer for example).
<DT><CODE>VISTEST(enabled)</CODE>
<DD>Enable or disable visibility culling. Default is on.
<DT><CODE>HEIGHTMAP(heightmapFile,scale,shift)</CODE>
<DD>Use the given image file as a heightmap for the landscape. Values from
this heightmap will go between 0 and 256. You can alter the range by
playing with `<SAMP>scale</SAMP>' (default 1) and `<SAMP>shift</SAMP>' (default 0).
</DL>
<P>
<A NAME="MeshObject Thing"></A>
<HR SIZE=1>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_216.html#SEC529"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_218.html#SEC536"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_196.html#SEC414"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_201.html#SEC452"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_220.html#SEC543"> >> </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>
|
