Crystal Space: 4.10.9 Thing Mesh Object

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 4.10.9 Thing Mesh Object

Written by Jorrit Tyberghein, (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 (see section Creating a Thing Mesh).

#### Basic Structure

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

- Type plugin: ``crystalspace.mesh.object.thing'`
- Loader plugin: ``crystalspace.mesh.loader.thing'`
- Factory loader plugin: ``crystalspace.mesh.loader.factory.thing'`

Objects in this plugin implement the following SCF interfaces (get with `scfQueryInterface`):

- MeshObjectFactory
  - Implements ``iMeshObjectFactory'`
  - Implements ``iThingFactoryState'`
- MeshObject
  - Implements ``iMeshObject'`
  - Implements ``iThingState'`
  - Implements ``iVisibilityCuller'`
  - Implements ``iLightingInfo'`
- MeshObjectType
  - Implements ``iMeshObjectType'`
  - Implements ``iThingEnvironment'`

#### State Interfaces

``iThingFactoryState'` 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.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.

``iThingState'` is for thing instances.

#### 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 <v x="" y="" z="" />`

    Define a single vertex given three coordinates. The coordinates are given in local object space for this thing.

  `polygon <p name=""> ...`

    This defines a single polygon using the vertices described above. The definition of a polygon is given below.

- Material related commands.
  `<material>materialName</material>`

    The default material to use for all following polygons. A polygon can still override this.

  `<matsetselect>materialSetName</matsetselect>`

    Use a set of textures that was defined previously.

  `<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. ``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.
  `<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.

  `<factory>factoryName</factory>`

    This thing will be made from the given thing factory.

  `<clone>thingName</clone>`

    This is similar to ``factory'` but the thing will be made from the given thing instead. i.e. it is a clone.

  `<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.

A given polygon (inside the ``polygon'` keyword) is defined as follows:

`<material>materialName</material>`

  The material to use for this polygon. If not given then the default material will be used.

`<texmap> ...`

  This keyword can be used to define additional texture mapping parameters.

`<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).

`shading(shadingParm) FIXME: still existing ?`

  This describes the kind of shading to use for this polygon. Possible values are: ``none'`, ``flat'`, ``gouraud'`, or ``lightmap'`. Default is ``lightmap'`.

`vertices <v 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)'`.

`<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.

`<color red="" green="" blue="" ... />`

  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.

`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).

`<alpha>alphaValue</alpha>`

  Using this you can set the alpha transparency factor of this polygon. This is a value between 0 and 100.

`<mixmode><mode /></mixmode>`

  With this you can control more blending options for the polygon. One of ``add'`, ``alpha'`, ``copy'`, ``keycolor'`, ``multiply2'`, ``multiply'`, or ``transparent'`.

`len(scale) FIXME: obsolete ?`

  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) FIXME: no shortcut anymore ?`

  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).

`<firstlen>scale</firstlen>`

  Scale along the u-axis.

`<secondlen>scale</secondlen>`

  Scale along the v-axis.

`<uvec x="" y="" z="" />`

  Similar to ``first'` with ``firstlen'` set to length of vector (``first'`-``orig'`).

`<vvec x="" y="" z="" />`

  Similar to ``second'` with ``secondlen'` 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) FIXME: obsolete ?`

  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) FIXME: where is this now ?`

  Given the mapping described above, further shift with the given u,v shift value.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ]

This document was generated using texi2html 1.76.