CrystalSpace

Public API Reference

iTerrainCell Struct Reference

Terrain cell class. More...

#include <imesh/terrain2.h>

Inheritance diagram for iTerrainCell:

List of all members.

Public Types

enum  LoadState { NotLoaded, PreLoaded, Loaded }
 

Enumeration that specifies current cell state.

More...

Public Member Functions

virtual bool Collide (iCollider *collider, float radius, const csReversibleTransform &trans, bool oneHit, iTerrainCollisionPairArray *pairs)=0
 Collide collider with cell (using the collider).
virtual bool CollideSegment (const csVector3 &start, const csVector3 &end, bool oneHit, iTerrainVector3Array *points)=0
 Collide segment with cell (using the collider).
virtual bool CollideTriangles (const csVector3 *vertices, size_t tri_count, const unsigned int *indices, float radius, const csReversibleTransform &trans, bool oneHit, iTerrainCollisionPairArray *pairs)=0
 Collide set of triangles with cell (using the collider).
virtual iMaterialWrapperGetBaseMaterial () const =0
 Get base material for the cell.
virtual csVector3 GetBinormal (int x, int y) const =0
 Get binormal value.
virtual csVector3 GetBinormal (const csVector2 &pos) const =0
 Get binormal with bilinear interpolation.
virtual csRefCountGetCollisionData () const =0
 Get collider-specific data. Only to be used by collision plugin.
virtual
iTerrainCellCollisionProperties
GetCollisionProperties () const =0
 Get cell collision properties.
virtual csRefCountGetFeederData () const =0
 Get feeder-specific data. Only to be used by feeder plugin.
virtual
iTerrainCellFeederProperties
GetFeederProperties () const =0
 Get cell feeder properties.
virtual int GetGridHeight () const =0
 Get grid height.
virtual int GetGridWidth () const =0
 Get grid width.
virtual float GetHeight (int x, int y) const =0
 Query height, that is, do a lookup on height table.
virtual float GetHeight (const csVector2 &pos) const =0
 Query height doing bilinear interpolation.
virtual csLockedHeightData GetHeightData ()=0
 Get height data (for reading purposes: do not modify it!) This can be used to perform very fast height lookups.
virtual LoadState GetLoadState () const =0
 Get cell's current loading state.
virtual int GetMaterialMapHeight () const =0
 Get material map height (essentially a height of both material array and material masks, if any).
virtual int GetMaterialMapWidth () const =0
 Get material map width (essentially a width of both material array and material masks, if any).
virtual bool GetMaterialPersistent () const =0
 Get material persistent flag.
virtual const char * GetName () const =0
 Get cell name.
virtual csVector3 GetNormal (const csVector2 &pos) const =0
 Get normal with bilinear interpolation.
virtual csVector3 GetNormal (int x, int y) const =0
 Get normal value.
virtual const csVector2GetPosition () const =0
 Get cell position (in object space).
virtual csRefCountGetRenderData () const =0
 Get render-specific data. Only to be used by renderer plugin.
virtual
iTerrainCellRenderProperties
GetRenderProperties () const =0
 Get cell rendering properties.
virtual const csVector3GetSize () const =0
 Get cell size (in object space).
virtual csVector3 GetTangent (const csVector2 &pos) const =0
 Get tangent with bilinear interpolation.
virtual csVector3 GetTangent (int x, int y) const =0
 Get tangent value.
virtual iTerrainSystemGetTerrain ()=0
 Get the terrain to which the cell belongs.
virtual csLockedHeightData LockHeightData (const csRect &rectangle)=0
 Lock an area of height data (for reading/writing purposes) This can be used for terrain deforming.
virtual csLockedMaterialMap LockMaterialMap (const csRect &rectangle)=0
 Lock an area of material map (practically write-only, reading the values will not produce sensible values if you did not just write them that is, the returned block memory is a read-write one, but it is a temporary block of memory filled with garbage).
virtual void SetAlphaMask (iMaterialWrapper *material, iImage *alphaMap)=0
 Set alpha mask for a specified material.
virtual void SetBaseMaterial (iMaterialWrapper *material)=0
 Set base material for the cell.
virtual void SetCollisionData (csRefCount *data)=0
 Set collider-specific data. Only to be used by collision plugin.
virtual void SetFeederData (csRefCount *data)=0
 Set feeder-specific data. Only to be used by feeder plugin.
virtual void SetLoadState (LoadState state)=0
 Set cell's current loading state.
virtual void SetMaterialMask (unsigned int material, const unsigned char *data, unsigned int width, unsigned int height)=0
 Set new material mask for the specified material.
virtual void SetMaterialMask (unsigned int material, iImage *image)=0
 Set new material mask for the specified material.
virtual void SetName (const char *name)=0
 Set name of this cell.
virtual void SetRenderData (csRefCount *data)=0
 Set render-specific data. Only to be used by renderer plugin.
virtual void UnlockHeightData ()=0
 Commit changes to height data.
virtual void UnlockMaterialMap ()=0
 Commit changes to material data.

Detailed Description

Terrain cell class.

Terrain consists of cells, each cell has its own coordinate system (2-axis position and 3-axis scaling). All operations (loading, preloading, destroying, construction of inner structures for rendering, etc.) are done at cell level.

A cell can be created via iTerrainFactory interface.

Definition at line 844 of file terrain2.h.


Member Enumeration Documentation

Enumeration that specifies current cell state.

Enumerator:
NotLoaded 

cell is not loaded in memory, do not do any operations with it directly

PreLoaded 

cell is in preload state, do not do any operations with it directly

Loaded 

cell is loaded, you can use it as you like

Definition at line 849 of file terrain2.h.


Member Function Documentation

virtual bool iTerrainCell::Collide ( iCollider collider,
float  radius,
const csReversibleTransform trans,
bool  oneHit,
iTerrainCollisionPairArray pairs 
) [pure virtual]

Collide collider with cell (using the collider).

Parameters:
collider collider
radius radius of the bounding sphere surrounding the given set of triangles (used for fast rejection)
trans triangle set transformation (vertices' coordinates are specified in the space defined by this transformation)
oneHit if this is true, than stop on finding the first collision pair; otherwise, detect all collisions
points destination collision pair array
Returns:
true if there were any collisions, false if there were none
virtual bool iTerrainCell::CollideSegment ( const csVector3 start,
const csVector3 end,
bool  oneHit,
iTerrainVector3Array points 
) [pure virtual]

Collide segment with cell (using the collider).

Parameters:
start segment start (specified in object space)
end segment end (specified in object space)
oneHit if this is true, than stop on finding the first intersection point (the closest to the segment start); otherwise, detect all intersections
points destination point array
Returns:
true if there were any intersections, false if there were none
virtual bool iTerrainCell::CollideTriangles ( const csVector3 vertices,
size_t  tri_count,
const unsigned int *  indices,
float  radius,
const csReversibleTransform trans,
bool  oneHit,
iTerrainCollisionPairArray pairs 
) [pure virtual]

Collide set of triangles with cell (using the collider).

Parameters:
vertices vertex array
tri_count triangle count
indices vertex indices, 3 indices for each triangle
radius radius of the bounding sphere surrounding the given set of triangles (used for fast rejection)
trans triangle set transformation (vertices' coordinates are specified in the space defined by this transformation)
oneHit if this is true, than stop on finding the first collision pair; otherwise, detect all collisions
points destination collision pair array
Returns:
true if there were any collisions, false if there were none
virtual iMaterialWrapper* iTerrainCell::GetBaseMaterial (  )  const [pure virtual]

Get base material for the cell.

virtual csVector3 iTerrainCell::GetBinormal ( int  x,
int  y 
) const [pure virtual]

Get binormal value.

Parameters:
x x coordinate (from 0 to grid width - 1 all inclusive)
y y coordinate (from 0 to grid height - 1 all inclusive)
Returns:
binormal value
virtual csVector3 iTerrainCell::GetBinormal ( const csVector2 pos  )  const [pure virtual]

Get binormal with bilinear interpolation.

Parameters:
pos object-space position.
Returns:
binormal value
virtual csRefCount* iTerrainCell::GetCollisionData (  )  const [pure virtual]

Get collider-specific data. Only to be used by collision plugin.

virtual iTerrainCellCollisionProperties* iTerrainCell::GetCollisionProperties (  )  const [pure virtual]

Get cell collision properties.

Returns pointer to a collider-specific class, though it is possible to check/change some general properties.

Returns:
cell collision properties
virtual csRefCount* iTerrainCell::GetFeederData (  )  const [pure virtual]

Get feeder-specific data. Only to be used by feeder plugin.

virtual iTerrainCellFeederProperties* iTerrainCell::GetFeederProperties (  )  const [pure virtual]

Get cell feeder properties.

Returns pointer to a feeder-specific class though it is possible to check/change some general properties.

Returns:
cell feeder properties
virtual int iTerrainCell::GetGridHeight (  )  const [pure virtual]

Get grid height.

It is the height of an array of height data. You can expect it to be 2^n + 1 (note: it is equal to grid width)

Returns:
grid height
virtual int iTerrainCell::GetGridWidth (  )  const [pure virtual]

Get grid width.

It is the width of an array of height data. You can expect it to be 2^n + 1.

Returns:
grid width
virtual float iTerrainCell::GetHeight ( int  x,
int  y 
) const [pure virtual]

Query height, that is, do a lookup on height table.

For a set of lookups, use GetHeightData for efficiency reasons.

Parameters:
x x coordinate (from 0 to grid width - 1 all inclusive)
y y coordinate (from 0 to grid height - 1 all inclusive)
Returns:
height value
virtual float iTerrainCell::GetHeight ( const csVector2 pos  )  const [pure virtual]

Query height doing bilinear interpolation.

This is equivalent to doing an intersection with vertical ray, except that it is faster.

Parameters:
pos object-space position.
Returns:
height value
virtual csLockedHeightData iTerrainCell::GetHeightData (  )  [pure virtual]

Get height data (for reading purposes: do not modify it!) This can be used to perform very fast height lookups.

Returns:
cell height data
virtual LoadState iTerrainCell::GetLoadState (  )  const [pure virtual]

Get cell's current loading state.

Returns:
cell's current loading state
virtual int iTerrainCell::GetMaterialMapHeight (  )  const [pure virtual]

Get material map height (essentially a height of both material array and material masks, if any).

Returns:
material map height
virtual int iTerrainCell::GetMaterialMapWidth (  )  const [pure virtual]

Get material map width (essentially a width of both material array and material masks, if any).

Returns:
material map width
virtual bool iTerrainCell::GetMaterialPersistent (  )  const [pure virtual]

Get material persistent flag.

If it is true, material data is stored in the cell (that makes updating material data faster and makes material data lock read/write, but it means larger memory overhead)

virtual const char* iTerrainCell::GetName (  )  const [pure virtual]

Get cell name.

It is specified at creation time and may be 0. The name is used only for cell identification purposes (i.e. to get the needed cell from a terrain, see iTerrainSystem::GetCell)

Returns:
cell name
virtual csVector3 iTerrainCell::GetNormal ( const csVector2 pos  )  const [pure virtual]

Get normal with bilinear interpolation.

Parameters:
pos object-space position.
Returns:
normal value
virtual csVector3 iTerrainCell::GetNormal ( int  x,
int  y 
) const [pure virtual]

Get normal value.

Parameters:
x x coordinate (from 0 to grid width - 1 all inclusive)
y y coordinate (from 0 to grid height - 1 all inclusive)
Returns:
normal value
virtual const csVector2& iTerrainCell::GetPosition (  )  const [pure virtual]

Get cell position (in object space).

X and Y components specify the offsets along X and Z axes, respectively.

Returns:
cell position
virtual csRefCount* iTerrainCell::GetRenderData (  )  const [pure virtual]

Get render-specific data. Only to be used by renderer plugin.

virtual iTerrainCellRenderProperties* iTerrainCell::GetRenderProperties (  )  const [pure virtual]

Get cell rendering properties.

Returns pointer to a renderer-specific class, though it is possible to check/change some general properties.

Returns:
cell rendering properties
virtual const csVector3& iTerrainCell::GetSize (  )  const [pure virtual]

Get cell size (in object space).

X and Y components specify the sizes along X and Z axes, respectively. Z component specifies height scale (warning: it is used only at loading stage, after that all scales are in object space).

Returns:
cell size
virtual csVector3 iTerrainCell::GetTangent ( const csVector2 pos  )  const [pure virtual]

Get tangent with bilinear interpolation.

Parameters:
pos object-space position.
Returns:
tangent value
virtual csVector3 iTerrainCell::GetTangent ( int  x,
int  y 
) const [pure virtual]

Get tangent value.

Parameters:
x x coordinate (from 0 to grid width - 1 all inclusive)
y y coordinate (from 0 to grid height - 1 all inclusive)
Returns:
tangent value
virtual iTerrainSystem* iTerrainCell::GetTerrain (  )  [pure virtual]

Get the terrain to which the cell belongs.

Returns:
terrain object
virtual csLockedHeightData iTerrainCell::LockHeightData ( const csRect rectangle  )  [pure virtual]

Lock an area of height data (for reading/writing purposes) This can be used for terrain deforming.

If you want to lock the whole cell, use the rectangle csRect(0, 0, grid width, grid height).

Only one area may be locked at a time, locking more than once results in undefined behaviour.

Parameters:
rectangle the rectangle which you want to lock.
Returns:
cell height data
virtual csLockedMaterialMap iTerrainCell::LockMaterialMap ( const csRect rectangle  )  [pure virtual]

Lock an area of material map (practically write-only, reading the values will not produce sensible values if you did not just write them that is, the returned block memory is a read-write one, but it is a temporary block of memory filled with garbage).

Note, that if you created cell with 'material_persistent' flag, the lock is read/write.

If you want to lock the whole cell, use the rectangle csRect(0, 0, material map width, material map height).

Only one area may be locked at a time, locking more than once results in undefined behaviour.

Parameters:
rectangle the rectangle which you want to lock.
Returns:
cell material data
virtual void iTerrainCell::SetAlphaMask ( iMaterialWrapper material,
iImage alphaMap 
) [pure virtual]

Set alpha mask for a specified material.

Parameters:
material the material
alphaMap the alpha map to use
virtual void iTerrainCell::SetBaseMaterial ( iMaterialWrapper material  )  [pure virtual]

Set base material for the cell.

Parameters:
material material handle of base material
virtual void iTerrainCell::SetCollisionData ( csRefCount data  )  [pure virtual]

Set collider-specific data. Only to be used by collision plugin.

virtual void iTerrainCell::SetFeederData ( csRefCount data  )  [pure virtual]

Set feeder-specific data. Only to be used by feeder plugin.

virtual void iTerrainCell::SetLoadState ( LoadState  state  )  [pure virtual]

Set cell's current loading state.

If the cell's current state is equal to the passed state, nothing happens. If the cell was not loaded (NotLoaded state), then it is put into the passed state (either preloading or loading is started) If the cell was loaded, then it is unloaded in case of NotLoaded state. Passing PreLoaded state has no effect. If the cell was being preloaded, then it is loaded in case of Loaded state. Passing NotLoaded state has no effect (note, that if you want to stop preloading, you'll have to finish it (SetLoadState (Loaded)) and then unload the cell (SetLoadState (NotLoaded)).)

Parameters:
state cell's new loading state
virtual void iTerrainCell::SetMaterialMask ( unsigned int  material,
const unsigned char *  data,
unsigned int  width,
unsigned int  height 
) [pure virtual]

Set new material mask for the specified material.

This function will do image rescaling if needed (i.e. if material map dimensions and image dimensions do not match).

Parameters:
material material index
data linearized array with material indices
width image width
height image height
virtual void iTerrainCell::SetMaterialMask ( unsigned int  material,
iImage image 
) [pure virtual]

Set new material mask for the specified material.

This function will do image rescaling if needed (i.e. if material map dimensions and image dimensions do not match).

Parameters:
material material index
image an image of format CS_IMGFMT_PALETTED8
virtual void iTerrainCell::SetName ( const char *  name  )  [pure virtual]

Set name of this cell.

Warning:
The cell name is used to map object cells to factory cells. Changing the name of a cell does not change any existing mappings, however, it will take effect when saving the mesh. If that is done careless changing of cell names can confuse the mapping of cells.
virtual void iTerrainCell::SetRenderData ( csRefCount data  )  [pure virtual]

Set render-specific data. Only to be used by renderer plugin.

virtual void iTerrainCell::UnlockHeightData (  )  [pure virtual]

Commit changes to height data.

Use it after changing the desired height values.

Unlocking the cell that was not locked results in undefined behaviour

virtual void iTerrainCell::UnlockMaterialMap (  )  [pure virtual]

Commit changes to material data.

Use it after setting the desired material map values.

Unlocking the cell that was not locked results in undefined behaviour

This updates the material masks with appropriate values.


The documentation for this struct was generated from the following file:

Generated for Crystal Space 1.4.1 by doxygen 1.7.1