7.8.17 Thing Mesh Object
Written by Jorrit Tyberghein,
(jorrit.tyberghein@uz.kuleuven.ac.be).
This mesh object represents a 'thing' which is a very often used
geometry object in Crystal Space. Things are often used to mark the bounding
geometry of a sector so that it represents a closed space. Things are not
very dynamic in nature (although you can have things that move) so they
are most often used for static geometry.
Things support both polygons and curved surfaces (bezier surfaces only
at this moment). Things also support portals which means that they can
be used to define transition polygons between adjacent or non-adjacent
sectors.
One important aspect of the thing mesh object is that there is no difference
between a mesh object and a mesh factory. You can create a mesh factory
and use it as a mesh object.
Basic Structure
The following SCF class names are used (for CS_LOAD_PLUGIN()
):
-
Type plugin: `crystalspace.mesh.object.thing'
-
Loader plugin: `crystalspace.mesh.loader.thing'
-
Factory loader plugin: `crystalspace.mesh.loader.factory.thing'
-
Plane loader addon plugin: `crystalspace.mesh.loader.thing.plane'
-
Bezier curve loader addon plugin: `crystalspace.mesh.loader.thing.bezier'
Objects in this plugin implement the following SCF interfaces (get
with SCF_QUERY_INTERFACE()
):
-
MeshObject and MeshObjectFactory
-
Implements `iMeshObject'
-
Implements `iMeshObjectFactory'
-
Implements `iThingState'
-
Implements `iPolygonMesh'
-
Implements `iVisibilityCuller'
-
Implements `iLightingInfo'
-
MeshObjectType
-
Implements `iMeshObjectType'
-
Implements `iThingEnvironment'
State Interface
Since mesh objects and mesh factories are the same for things there is
only one state interface.
`iThingState' is the SCF interface that you can use to
set/get settings for a thing. The definition of this interface
can be found in `CS/include/imesh/thing/thing.h' and that is also the
include file you need to include in your applications to use this plugin.
Using this interface you can access the vertices, polygons, materials,
curved surfaces, and various other configuration parameters for a thing.
All include files for the thing mesh can be found in the
`CS/include/imesh/thing' directory. There are include files for the
curve definition, for lightmaps, polygons, portals, ...
Factory and Object Loader
At load time a thing can be constructed from several thing parts.
At run time these parts will all be combined into one big thing but
at load time it is sometimes easy to be able to split the thing in parts
so that you can have a more logical grouping of thing data. The important
feature of parts is that the vertex table starts from zero again. This means
that you can define vertices in a part and then use them in polygons in that
part as if the vertex table starts at 0 again. This is useful because then
you can more easily add new parts and even move around parts without having
to change all vertex indices. Note that it is no problem to have duplicate
vertices between different parts as they will be combined in a post-processing
pass anyway. The table below describes everything which you can use in a
single part which is also what you can use in the top level thing
definition.
-
Vertex and polygon definition commands. Note that in a given part the vertex
table always starts at index 0. Every vertex you add will use a new index.
VERTEX(x,y,z)
- Define a single vertex given three coordinates. The coordinates are given
in local object space for this thing.
V(x,y,z)
- Shorthand for `VERTEX'.
VBLOCK(minx,miny,minz,maxx,maxy,maxz)
- This is a conveniance command that creates eight vertices shaped in a block.
You can then easily define polygons that use some of these vertices to form
one surface of the block. VBLOCK expects six parameters which
are the dimensions of the block.
VROOM(minx,miny,minz,maxx,maxy,maxz)
- This command is similar to VBLOCK. Except that it will generate the vertices
in a different order so that later created polygons will
be visible from the inside instead of the outside.
CIRCLE(x,y,z,rx,ry,rz,num)
- Generate a circle of vertices.
`x,y,z' is the centre of the circle. `rx,ry,rz' is the radius of
the circle. `num' is the number of vertices to generate. If `num'
is negative the vertices will be generated in a different direction.
POLYGON(...)
- This defines a single polygon using the vertices described above. The
definition of a polygon is given below.
P(...)
- Shorthand for `POLYGON'.
-
Curve related commands. Currently only 3x3 bezier patches are supported.
Note that to use a curve in a thing mesh object you need to describe
a curve template first (more on this later).
CURVECONTROL(x,y,z:u,v)
- A control point for a curve. There are 9 control points (for a 3x3
bezier patch). Every control point has the following format: `x,y,z:u,v'.
`x,y,z' is the location of the point in object space. `u,v' is
the texture mapping coordinate for this control point.
CURVECENTER(x,y,z)
- Set the center point (`x,y,z') of the curve.
CURVESCALE(scale)
- Set the scale of the curve.
CURVE(curveTemplateName)
- Get the name of the curve template to use for this curve. Read about curve
templates later.
-
Material related commands.
MATERIAL(materialName)
- The default material to use for all following polygons. A polygon can
still override this.
MAT_SET_SELECT(materialSetName)
- Use a set of textures that was defined previously.
TEXLEN(scale)
- This is a very general and easy command to control texture mapping on
a polygon. It basically defines the scale of a texture. If you want more
control over polygon texture mapping you should look at the texture mapping
parameters in a polygon. But if you want Quick-And-Dirty texture mapping
then this command can help you. `TEXLEN' expects a single parameter
which is a scale. A scale of 1 means that the given texture will be scaled
once in both directions for 1 unit in world space. A scale of 2 means that
the given texture will be scaled once in 2 units of world space.
-
Various other commands.
MOVEABLE(boolean)
- This command only works for the top-level thing. It indicates that the
thing can possibly move around. If you don't set this option then it is
illegal to later move the thing.
VISTREE(boolean)
- This command only works for the top-level thing. It indicates that this
thing will have an octree + mini-bsp trees. This is used for visibility
culling. Usually only big things will have VISTREE and usually there is
only one thing in a sector which has this flag set. In this case you probably
want to use the `CULLER' keyword in the sector to indicate that
this thing is the one containing the visibility culling information.
FASTMESH(boolean)
- This command only works for the top-level thing. It indicates that this
mesh will be rendered using a faster technique. At this moment this is
not properly implemented though.
FACTORY(factoryName)
- This thing will be made from the given thing factory.
TEMPLATE(factoryName)
- Same as `FACTORY'
CLONE(thingName)
- This is similar to `FACTORY' but the thing will be made from the
given thing instead. i.e. it is a clone.
A given polygon (inside the `POLYGON' keyword) is defined as
follows:
MATERIAL(materialName)
- The material to use for this polygon. If not given then the default material
will be used.
TEXTURE(...)
- This keyword can be used to define additional texture mapping parameters.
LIGHTING(boolean)
- Should this polygon use lighting or not. By default this is enabled. If
disabled the texture on this polygon will be rendered using original colors
(i.e. full-bright texture).
PORTAL(sectorName)
- If you use this keyword then this polygon is a portal to the given sector.
WARP(...)
- This keyword can be used to define additional parameters for the portal.
More on this later.
SHADING(shadingParm)
- This describes the kind of shading to use for this polygon. Possible values
are: `NONE', `FLAT', `GOURAUD', or `LIGHTMAP'. Default
is `LIGHTMAP'.
VERTICES(v1,...)
- The vertices of the polygon. This is a list of vertex indices local to the
part this polygon is in. In combination with the `VBLOCK' or `VROOM'
commands this command can also contain something with the name: `w',
`e', `n', `s', `u', or `d' (for west, east, north,
south, up, or down). This will then create vertices according to the last
`VBLOCK' or `VROOM'. Note that there should be no other vertex
generating command between the `VBLOCK' or `VROOM' and this
polygon command! You can also give the first index of the `VBLOCK'
or `VROOM' generated vertices with a notation like this:
`VERTICES (w,8)'.
V(v1,...)
- Shorthand for `VERTICES'.
UV(u1,v1,...)
- If you use this keyword the polygon will be gouraud shaded and not
lightmapped. This keyword allows you to describe the uv coordinates
for the polygon with gouraud shading. Currently a gouraud shaded polygon
is limited to three vertices. This limitation will be removed in the
future. But for now it means that UV will be followed by six parameters (three
u,v coordinate sets).
UVA(u1,v1,a1,...)
- Similar to `UV' but uses another technique to describe the coordinates
using angle.
COLORS(r,g,b...)
- When using `UV' you can use this command to give colors (r,g,b) for
every vertex.
COLLDET(boolean)
- Enable/disable collision detection for this polygon. By default a normal
polygon will have collision detection enabled. If the polygon has a portal
then collision detection will be disabled unless the portal is a mirror in
which case it will be enabled again. But using `COLLDET' allows you to
override all this.
COSFACT(factor)
- The cosinus factor to use for lighting. The default is 0 which means
that the strength of the light falling on this polygon will depend
completely on the angle of the light and this polygon. This is the most
realistic setting but in some cases it doesn't look right. To completely
disable dependence on angle you can use 1. In between values are also
possible.
ALPHA(alpha)
- Using this you can set the alpha transparency factor of this polygon.
This is a value between 0 and 100.
MIXMODE(mode)
- With this you can control more blending options for the polygon.
One of `ADD', `ALPHA', `COPY', `KEYCOLOR',
`MULTIPLY2', `MULTIPLY', or `TRANSPARENT'.
LEN(scale)
- This is similar to the `TEXLEN' command in the part and also to the
`LEN' command in the texture definition but it is repeated here
as a short-hand for `TEXTURE (LEN (...))'.
PLANE(planeName)
- This is a shorthand for `TEXTURE (PLANE (...))'.
A texture mapping specification (the `TEXTURE' keyword in a polygon)
has the following parameters:
ORIG(x,y,z)
- The origin for texture mapping (3D coord).
FIRST(x,y,z)
- The u-axis coordinate for texture mapping (3D coord).
SECOND(x,y,z)
- The v-axis coordinate for texture mapping (3D coord).
FIRST_LEN(scale)
- Scale along the u-axis.
SECOND_LEN(scale)
- Scale along the v-axis.
UVEC(x,y,z)
- Similar to `FIRST' with `FIRST_LEN' set to length
of vector (`FIRST'-`ORIG').
VVEC(x,y,z)
- Similar to `SECOND' with `SECOND_LEN' set to length
of vector (`SECOND'-`ORIG').
MATRIX(...)
- Most general way to describe texture mapping using the transformation matrix.
V(x,y,z)
- Most general way to describe texture mapping using the transformation vector.
LEN(scale)
- Use this as an easier way to describe texture scale (i.e. instead
of all the above).
UV(idx1,u1,v1,idx2,u2,v2,idx3,u3,v3)
- Directly specify u,v mapping coordinates for three given vertices.
UV_SHIFT(ushift,vshift)
- Given the mapping described above, further shift with the given
u,v shift value.
PLANE(planeName)
- Use the given texture mapping plane instead of all the above.
See how to define planes later.
The `WARP' keyword as used in a polygon has the following keywords:
MATRIX(...)
- The matrix to use for space warping the portal.
V(x,y,z)
- The vector to use for space warping before the matrix is applied.
W(x,y,z)
- The vector to use for space warping after the matrix is applied. If not
given this is the same as `V'.
MIRROR()
- Short-hand to generate a mirror portal. This will automatically calculate
`MATRIX', `V', and `W'.
STATIC()
- When this item is given the portal destination will be static. This means
that the portal will point to the same location even if the portal polygon
moves. Otherwise the portal destination will move accordingly.
ZFILL()
- Set this option on a portal that floats in the middle of a room. It will
make sure that the Z-buffer is filled AFTER rendering all objects seen
through the portal.
CLIP()
- Set this option on a portal that points to the middle of a room. It will
make sure that all geometry in the destination sector is correctly clipped
to the portal so that it is not rendered in this sector.
Plane Add-on Loader
The thing loader plugin also supports an additional plugin which can load
plane definitions. A plane definition is used for texture mapping. It is
an optional (but very useful) feature which allows you to define texture
mapping planes for polygons that share the same texture mapping.
The following keywords are supported by the plane loader:
NAME(planeName)
- The name of this plane. This can then be used later in `PLANE' commands
for the texture or polygon.
ORIG(x,y,z)
- The origin for texture mapping (3D coord).
FIRST(x,y,z)
- The u-axis coordinate for texture mapping (3D coord).
SECOND(x,y,z)
- The v-axis coordinate for texture mapping (3D coord).
FIRST_LEN(scale)
- Scale along the u-axis.
SECOND_LEN(scale)
- Scale along the v-axis.
UVEC(x,y,z)
- Similar to `FIRST' with `FIRST_LEN' set to length
of vector (`FIRST'-`ORIG').
VVEC(x,y,z)
- Similar to `SECOND' with `SECOND_LEN' set to length
of vector (`SECOND'-`ORIG').
MATRIX(...)
- Most general way to describe texture mapping using the transformation matrix.
V(x,y,z)
- Most general way to describe texture mapping using the transformation vector.
Bezier Curve Add-on Loader
The thing loader also supports an additional plugin which can load curve
template definitions.
The following keywords are supported by the bezier curve loader:
NAME(curveTemplateName)
- The name of this curve template. This can then be used later in `CURVE'
commands in the thing part definition.
MATERIAL(materialName)
- The material to use for this curve.
VERTICES(v1,...)
- Nine vertex indices (the exact position and texture mapping coordinate will
be defined in the thing mesh object using `CURVECONTROL').
V(v1,...)
- Shorthand for `VERTICES'.
This document was generated
using texi2html