iTerrainCell Struct Reference (Crystal Space 2.0 Public API Reference)

| ## Public API Reference

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Types | Public Member Functions
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 | CollideSegment (const csVector3 &start, const csVector3 &end, csVector3 &hitPoint)=0
| Collide segment with cell.
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 iMaterialWrapper * | GetAlphaSplatMaterial () const =0
| Get the optional alpha-splat material for the cell.
virtual iMaterialWrapper * | GetBaseMaterial () 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 csLockedNormalData | GetBitangentData ()=0
| Get tangent data (for reading purposes: do not modify it!).
virtual csRefCount * | GetCollisionData () const =0
| Get collider-specific data. Only to be used by collision plugin.
virtual iTerrainCellCollisionProperties * | GetCollisionProperties () const =0
| Get cell collision properties.
virtual csRefCount * | GetFeederData () 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 (int x, int y) const =0
| Get normal value.
virtual csVector3 | GetNormal (const csVector2 &pos) const =0
| Get normal with bilinear interpolation.
virtual csLockedNormalData | GetNormalData ()=0
| Get normal data (for reading purposes: do not modify it!) This can be used to perform very fast normal lookups.
virtual const csVector2 & | GetPosition () const =0
| Get cell position (in object space).
virtual csRefCount * | GetRenderData () const =0
| Get render-specific data. Only to be used by renderer plugin.
virtual iTerrainCellRenderProperties * | GetRenderProperties () const =0
| Get cell rendering properties.
virtual const csVector3 & | GetSize () const =0
| Get cell size (in object space).
virtual iMaterialWrapper * | GetSplatBaseMaterial () const =0
| Get splat base material for the cell.
virtual csVector3 | GetTangent (int x, int y) const =0
| Get tangent value.
virtual csVector3 | GetTangent (const csVector2 &pos) const =0
| Get tangent with bilinear interpolation.
virtual csLockedNormalData | GetTangentData ()=0
| Get tangent data (for reading purposes: do not modify it!).
virtual iTerrainSystem * | GetTerrain ()=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 csLockedNormalData | LockNormalData (const csRect &rectangle)=0
| Lock an area of normal data (for reading/writing purposes) If you want to lock the whole cell, use the rectangle csRect(0, 0, grid width, grid height).
virtual void | RecalculateNormalData ()=0
| Recalculates the cell normals.
virtual void | SetAlphaMask (iMaterialWrapper *material, iImage *alphaMap)=0
| Set alpha mask for a specified material.
virtual void | SetAlphaSplatMaterial (iMaterialWrapper *material)=0
| Set the optional alpha-splat material for the cell.
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, iImage *image)=0
| Set new material mask for the specified material.
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 | 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 | SetSplatBaseMaterial (iMaterialWrapper *material)=0
| Set optional splat base material for the cell.
virtual void | UnlockHeightData ()=0
| Commit changes to height data.
virtual void | UnlockMaterialMap ()=0
| Commit changes to material data.
virtual void | UnlockNormalData ()=0
| Commit changes to height 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 928 of file terrain2.h.

## Member Enumeration Documentation

enum iTerrainCell::LoadState

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 933 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::CollideSegment | ( | const csVector3 & | start,
|  | const csVector3 & | end,
|  | csVector3 & | hitPoint
| ) |  | `[pure virtual]`

Collide segment with cell.

Stops on finding the first intersection point (the closest to the segment start).

Parameters:

  cell | cell
  start | segment start (specified in object space)
  end | segment end (specified in object space)
  hitPoint | receives the intersection point

Returns:
  true if there was an intersections, false if there was 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::GetAlphaSplatMaterial | ( |  | ) | const`[pure virtual]`

Get the optional alpha-splat material for the cell.

Returns:
  nullptr if no material, else the material.

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 csLockedNormalData iTerrainCell::GetBitangentData | ( |  | ) | `[pure virtual]`

Get tangent data (for reading purposes: do not modify it!).

Returns:
  cell tangent data

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 | ( | 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 csVector3 iTerrainCell::GetNormal | ( | const csVector2 & | pos | ) | const`[pure virtual]`

Get normal with bilinear interpolation.

Parameters:

  pos | object-space position.

Returns:
  normal value

virtual csLockedNormalData iTerrainCell::GetNormalData | ( |  | ) | `[pure virtual]`

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

Returns:
  cell normal data

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 iMaterialWrapper* iTerrainCell::GetSplatBaseMaterial | ( |  | ) | const`[pure virtual]`

Get splat base material for the cell.

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 csVector3 iTerrainCell::GetTangent | ( | const csVector2 & | pos | ) | const`[pure virtual]`

Get tangent with bilinear interpolation.

Parameters:

  pos | object-space position.

Returns:
  tangent value

virtual csLockedNormalData iTerrainCell::GetTangentData | ( |  | ) | `[pure virtual]`

Get tangent data (for reading purposes: do not modify it!).

Returns:
  cell tangent data

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 csLockedNormalData iTerrainCell::LockNormalData | ( | const csRect & | rectangle | ) | `[pure virtual]`

Lock an area of normal data (for reading/writing purposes) 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 normal data

virtual void iTerrainCell::RecalculateNormalData | ( |  | ) | `[pure virtual]`

Recalculates the cell normals.

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::SetAlphaSplatMaterial | ( | iMaterialWrapper * | material | ) | `[pure virtual]`

Set the optional alpha-splat material for the cell.

Parameters:

  material | material handle of the alpha-splat material.

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,
|  | 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::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::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::SetSplatBaseMaterial | ( | iMaterialWrapper * | material | ) | `[pure virtual]`

Set optional splat base material for the cell.

The splat base material is rendered before splatting or alpha-splatting is rendered for the cell.

Parameters:

  material | material handle of spalt base material.

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.

virtual void iTerrainCell::UnlockNormalData | ( |  | ) | `[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

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

- imesh/terrain2.h