@c -*-texinfo-*-
@node MeshObject Thing, MeshObject TerrFunc, MeshObject Genmesh, MeshObject
@subsection Thing Mesh Object
@cindex MeshObject
@cindex Thing
@cindex @code{iMeshObject}
@cindex @code{iMeshObjectFactory}
@cindex @code{iMeshObjectType}
@cindex @code{iThingState}
@cindex @code{iThingFactoryState}
@cindex @code{iVisibilityCuller}
@cindex @code{iLightingInfo}
@cindex @code{iThingEnvironment}

@emph{Written by Jorrit Tyberghein,
(@email{jorrit.tyberghein@@gmail.com}).}

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 general polygons (as opposed to only supporting triangles).

There is also a howto on creating things (@pxref{HOWTO Create Thing}).

@subsubheading Basic Structure

The following @sc{scf} class names are used (for @code{csLoadPlugin}):

@itemize @bullet
@item
Type plugin: @samp{crystalspace.mesh.object.thing}
@item
Loader plugin: @samp{crystalspace.mesh.loader.thing}
@item
Factory loader plugin: @samp{crystalspace.mesh.loader.factory.thing}
@end itemize

Objects in this plugin implement the following @sc{scf} interfaces (get
with @code{scfQueryInterface}):

@itemize @bullet
@item
@emph{MeshObjectFactory}
@itemize @bullet
@item
Implements @samp{iMeshObjectFactory}
@item
Implements @samp{iThingFactoryState}
@end itemize
@item
@emph{MeshObject}
@itemize @bullet
@item
Implements @samp{iMeshObject}
@item
Implements @samp{iThingState}
@item
Implements @samp{iVisibilityCuller}
@item
Implements @samp{iLightingInfo}
@end itemize
@item
@emph{MeshObjectType}
@itemize @bullet
@item
Implements @samp{iMeshObjectType}
@item
Implements @samp{iThingEnvironment}
@end itemize
@end itemize

@subsubheading State Interfaces

@samp{iThingFactoryState} is the @sc{scf} interface that you can use to
set/get settings for a thing. The definition of this interface
can be found in @file{CS/include/imesh/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,
and various other configuration parameters for a thing.

@samp{iThingState} is for thing instances.

@subsubheading Factory and Object Loader

At load time a thing can be constructed from several @dfn{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 @dfn{part} which is also what you can use in the top level thing
definition.

@itemize @bullet

@item
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.
@table @code
@item vertex <v x="" y="" z="" />
Define a single vertex given three coordinates. The coordinates are given
in local object space for this thing.
@item polygon <p name=""> @dots{}
This defines a single polygon using the vertices described above. The
definition of a polygon is given below.
@end table

@item
Material related commands.
@table @code
@item <material>materialName</material>
The default material to use for all following polygons. A polygon can
still override this.
@item <matsetselect>materialSetName</matsetselect>
Use a set of textures that was defined previously.
@item <texlen>scaleValue</texlen>
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. @samp{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.
@end table

@item
Various other commands.
@table @code
@item <fastmesh>yes/no</fastmesh>
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
default if the number of polygons exceeds some threshold.
@item <factory>factoryName</factory>
This thing will be made from the given thing factory.
@item <clone>thingName</clone>
This is similar to @samp{factory} but the thing will be made from the
given thing instead. i.e. it is a clone.
@item <cosfact>factorValue</cosfact>
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 a 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.
@end table
@end itemize

A given polygon (inside the @samp{polygon} keyword) is defined as
follows:

@table @code
@item <material>materialName</material>
The material to use for this polygon. If not given then the default material
will be used.
@item <texmap> @dots{}
This keyword can be used to define additional texture mapping parameters.
@item <lighting>yes/no</lighting>
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).
@item shading(shadingParm) FIXME: still existing ?
This describes the kind of shading to use for this polygon. Possible values
are: @samp{none}, @samp{flat}, @samp{gouraud}, or @samp{lightmap}. Default
is @samp{lightmap}.
@item vertices <v v1="" @dots{} />
The vertices of the polygon. This is a list of vertex indices local to the
part this polygon is in. In combination with the @samp{vblock} or @samp{vroom}
commands this command can also contain something with the name: @samp{w},
@samp{e}, @samp{n}, @samp{s}, @samp{u}, or @samp{d} (for west, east, north,
south, up, or down). This will then create vertices according to the last
@samp{vblock} or @samp{vroom}. Note that there should be no other vertex
generating command between the @samp{vblock} or @samp{vroom} and this
polygon command! You can also give the first index of the @samp{vblock}
or @samp{vroom} generated vertices with a notation like this:
@samp{vertices (w,8)}.
@item <uv u1="" v1="" @dots{} />
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).
@item <uva u1="" v1="" a1="" @dots{} />
Similar to @samp{uv} but uses another technique to describe the coordinates
using angle.
@item <color red="" green="" blue="" @dots{} />
When using @samp{uv} you can use this command to give colors (r,g,b) for
every vertex.
@item colldet(boolean)
Enable/disable collision detection for this polygon. By default a normal
polygon will have collision detection enabled.
@item viscull(boolean)
Enable/disable visibility culling for this polygon. By default a normal
polygon will have visibility culling enabled. If the polygon has alpha
then it will be disabled. However if the polygon uses a transparent texture
then CS cannot easily detect that so in that case you have to disable it
manually. This flag tells the visibility culler that this polygon should NOT
be used to cull other objects (i.e. to block visibility).
@item <alpha>alphaValue</alpha>
Using this you can set the alpha transparency factor of this polygon.
This is a value between 0 and 100.
@item <mixmode><mode /></mixmode>
With this you can control more blending options for the polygon.
One of @samp{add}, @samp{alpha}, @samp{copy}, @samp{keycolor},
@samp{multiply2}, @samp{multiply}, or @samp{transparent}.
@item len(scale) FIXME: obsolete ?
This is similar to the @samp{texlen} command in the part and also to the
@samp{len} command in the texture definition but it is repeated here
as a short-hand for @samp{texture (len (...))}.
@item plane(planeName) FIXME: no shortcut anymore ?
This is a shorthand for @samp{texture (plane (...))}.
@end table

A texture mapping specification (the @samp{texture} keyword in a polygon)
has the following parameters:

@table @code
@item <orig x="" y="" z="" />
The origin for texture mapping (3D coord).
@item <first x="" y="" z="" />
The u-axis coordinate for texture mapping (3D coord).
@item <second x="" y="" z="" />
The v-axis coordinate for texture mapping (3D coord).
@item <firstlen>scale</firstlen>
Scale along the u-axis.
@item <secondlen>scale</secondlen>
Scale along the v-axis.
@item <uvec x="" y="" z="" />
Similar to @samp{first} with @samp{firstlen} set to length
of vector (@samp{first}-@samp{orig}).
@item <vvec x="" y="" z="" />
Similar to @samp{second} with @samp{secondlen} set to length
of vector (@samp{second}-@samp{orig}).
@item <matrix> @dots{}
Most general way to describe texture mapping using the transformation matrix.
@item <v x="" y="" z="" />
Most general way to describe texture mapping using the transformation vector.
@item len(scale) FIXME: obsolete ?
Use this as an easier way to describe texture scale (i.e. instead
of all the above).
@item <uv idx1="" u1="" v1="" idx2="" u2="" v2="" idx3="" u3="" v3="" />
Directly specify u,v mapping coordinates for three given vertices.
@item uv_shift(ushift,vshift) FIXME: where is this now ?
Given the mapping described above, further shift with the given
u,v shift value.
@end table

