4.10.8 Genmesh Mesh Object

Written by Jorrit Tyberghein, [email protected].

A Genmesh is a complex set of 3D triangles (just like a 3D sprite) that normally doesn't support any automatic animation (unlike a 3D sprite) unless you use a genmesh animation plugin (see section GenMesh Animation). In general genmeshes are ideal for high detailed objects. Genmeshes also support multiple materials using submeshes.

There is also a HOWTO discussing the creation of genmeshes. See section Creating a Genmesh Mesh.

Basic Structure

The following SCF class names are used (for csLoadPlugin):

• Type plugin: crystalspace.mesh.object.genmesh
• Loader plugin: crystalspace.mesh.loader.genmesh
• Factory loader plugin: crystalspace.mesh.loader.factory.genmesh

Objects in this plugin implement the following SCF interfaces, which you can retrieve with scfQueryInterface:

• MeshObject
  • Implements `iMeshObject'
  • Implements `iGeneralMeshState'
• MeshObjectFactory
  • Implements `iMeshObjectFactory'
  • Implements `iGeneralFactoryState'
• MeshObjectType
  • Implements `iMeshObjectType'

Factory State Interface

Use the `iGeneralFactoryState' SCF interface to access settings for a genmesh factory. The definition of this interface can be found in `CS/include/imesh/genmesh.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 material, triangles, vertices, texture coordinates, normals, and various other configuration parameters for a genmesh factory.

Factory Loader

Here is a list of all the tags supported by a genmesh factory and their meaning:

• `box' This is a shortcut for defining a box geometry. It contains two vectors named `min' and `max': `<box> <min x="0" y="0" z="0" /> <max x="1" y="1" z="1" /> </box>'.
• `sphere' This is a short cut for defining sphere geometry: `<sphere rimvertices="6" reversed="true" cylindrical="false"> <radius x="10" y="10" z="1" /> </sphere>'
• `numtri' Deprecated. This is the old way to specify the number of triangles this genmesh will use. It is no longer needed and it is most certainly not needed if you use `box' or `sphere'.
• `numvt' Deprecated. This is the old way to specify the number of vertices this genmesh will use. It is no longer needed and it is most certainly not needed if you use `box' or `sphere'. Note that if you do not use `numvt' that you have to specify vertices with uv in the same `v' command but colors and normals have to be specified seperatelly. If you don't use `numvt' then you can specify everything in one statement.
• `v' Unless you use `box' or `sphere' you can use this to add a vertex. If you don't use `numvt' (prefered) then you should specify all vertex information here: `<v x="0" y="0" z="0" nx="1" ny="0" nz="0" red=".5" green=".g" blue=".g" u="0" v=".1" />'. Otherwise you must specify normal and color information seperatelly. Note that normal and color information is optional. Default color is black and default normal is the 0-vector (meaning you'll have to use `autonormals' then).
• `n' This is only used if you specified `numvt' and it specifies the normal information for every vertex. You must have the same number of `n' statements as there are vertices. Note that if you use `autonormals' then you don't need to specify normals.
• `color' This is only used if you specified `numvt' and it specifies the color information for every vertex. You must have the same number of `color' statements as there are vertices.
• `submesh' Using submeshes you can define subsets of the factory that use different material and mixmode. When you don't use `submesh' the entire mesh will use the same material and mixmode. As soon as you use submeshes you should make sure that every triangle is contained in some submesh. Basically inside the `submesh' node you need to specify the triangle indices to use, the material, and the mixmode: `<submesh> <t>0</t> <t>3</t> ... <material>stone</material> <mixmode> <add /> </mixmode> </submesh>'.
• `t' Add a triangle to the factory. You need to specify the three vertex indices that are used for the triangle: `<t v1="3" v2="1" v3="10" />'.
• `material' The name of the master material to use for this genmesh. Mesh objects that are created from this factory can override this material. Also note that if you use submeshes then multiple materials can be used for the same factory/object.
• `autonormals' If you use this then the normals will be calculated automatically from the given vertices. By default the vertex table is compressed (all doubles removed) in a temporary table and from that table the normal data is calculated so that you get a smooth result. If you don't want that compression (because you want to ensure that there are explicit seams in the object) you need to set the `normalnocompress' flag before this statement.
• `normalnocompress' Disable compression of the vertex table before `autonormals' is used.
• `back2front' If you have an object that uses transparency that requires perfect sorting from back to front (like objects using alpha transparency) then you may need to set this flag. This will ensure that internally there is a BSP tree to sort the polygons from back to front when rendering. Note that this slows down considerably so only use it if you really need it.
• `manualcolors' If this flag is set then no lighting values are processed and the colors specified for every vertex (which are default black!) are used.
• `lighting' If this flag is set (default true) then lighting information (from nearby lights) is added to the colors of the vertices.
• `defaultcolor' This color is the default color as used for objects created from this factory. Objects can override this default with the `color' statement in the object.
• `localshadows' If this flag is set (default false) then lighting calculation is not dynamic but instead static and precalculated. This is faster at runtime and additionally shadows on the genmesh object will be supported (only shadows calculated per vertex).
• `noshadows' If this flag is set (default false) then the object will not cast shadows on other objects.
• `mixmode' Control the transparency of this object. @@@TODO: document more!
• `animcontrol' Add an animation control to the object. @@@TODO: document more!
• `renderbuffer' Using this statement you can add your own user renderbuffers to the object. These renderbuffers can be used by shaders. @@@TODO: document more!

Object State Interface

`iGeneralMeshState' (residing in `CS/include/imesh/genmesh.h') is the SCF interface that you can use to manipulate settings for a genmesh object. By using this interface you can access the material, blending mode (mixmode), and various other configuration parameters for a genmesh object.

Object Loader

Here is a list of all the tags supported by a genmesh object and their meaning:

• `factory' The name of the factory to use.
• `material' For this object, override the material from the factory.
• `mixmode' For this object, override the mixmode from the factory.
• `manualcolors' For this object, override the manualcolors flag from the factory.
• `lighting' For this object, override the lighting flag from the factory.
• `noshadows' For this object, override the noshadows flag from the factory.
• `localshadows' For this object, override the localshadows flag from the factory.
• `renderbuffer' Add additional render buffers to this object (the ones added to the factory will also be valid).
• `submesh' You can also define submeshes on the object level instead of the factory level. If you use `submesh' in the mesh then the submeshes of the factory are ignored.
• `color' Color of this mesh (overrides `defaultcolor' from factory).

Lighting and Colors

Lighting of genmesh objects is a bit complicated. In this section we describe the different possibilities:

• In all cases the color array from the factory will be added to the colors calculated below.
• If manualcolors is enabled then only the optional animation control still matters. No other lighting values are processed.
• Otherwise if lighting is disabled then the base color of the mesh will be added to the factory colors.
• If lighting is enabled and localshadows is disabled then lighting is calculated as follows: factory colors + base color + static ambient + dynamic ambient + lighting as calculated from nearby/relevant lights.
• If both lighting and localshadows are enabled then lighting is calculated as follows: factory colors + base color + static ambient + dynamic ambient + lighting as precalculated during static lighting + dynamic lights

This document was generated using texi2html 1.76.