org.critterai.nmgen
Class OpenHeightfield

java.lang.Object
  extended by org.critterai.nmgen.BoundedField
      extended by org.critterai.nmgen.OpenHeightfield

public final class OpenHeightfield
extends BoundedField

Provides a representation of the open (unobstructed) space above solid surfaces in a voxel field.

For this type of heightfield, spans represent the floor and ceiling of the open spaces.

WARNING: This class has very little protections build into it. It is basically an uncontrolled data structure with convenience functions.

See Also:
Introduction to Height Fields

Nested Class Summary
 class OpenHeightfield.OpenHeightFieldIterator
          An iterator that will iterate through all spans within a height field.
 
Constructor Summary
OpenHeightfield(float[] gridBoundsMin, float[] gridBoundsMax, float cellSize, float cellHeight)
          Constructor
 
Method Summary
 OpenHeightSpan addData(int widthIndex, int depthIndex, OpenHeightSpan span)
          Puts the span at the grid location, replacing any spans already at the location.
 void clearBorderDistanceBounds()
          Resets the border distance values so they will be recacluated the next time they are needed.
 OpenHeightfield.OpenHeightFieldIterator dataIterator()
          An iterator for the heightfields spans.
 OpenHeightSpan getData(int widthIndex, int depthIndex)
          Retrieves the base (lowest) grid for the specified grid location.
 int incrementSpanCount()
          Increments the span count.
 int maxBorderDistance()
          The maximum distance a span in the heightfield is from its nearest border.
 int minBorderDistance()
          The minimum distance a span in the height field is from its nearest border.
 void printDistanceField()
          Sends a tab delimited table of the distance field values to standard out.
 void printRegionField()
          Sends a tab delimited table of the region ID values to standard out.
 int regionCount()
          The number of regions in the height field.
 void setRegionCount(int value)
          Sets the region count.
 int spanCount()
          The number of spans in the heightfield.
 
Methods inherited from class org.critterai.nmgen.BoundedField
boundsMax, boundsMin, cellHeight, cellSize, depth, getDirOffsetDepth, getDirOffsetWidth, gridIndex, isInBounds, overlaps, resetBounds, resetCellInfo, setBounds, setBounds, setBoundsMax, setBoundsMin, setCellHeight, setCellSize, width
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

OpenHeightfield

public OpenHeightfield(float[] gridBoundsMin,
                       float[] gridBoundsMax,
                       float cellSize,
                       float cellHeight)
                throws IllegalArgumentException
Constructor

Parameters:
gridBoundsMin - The minimum bounds of the field in the form (minX, minY, minZ).
gridBoundsMax - The maximum bounds of the field in the form (maxX, maxY, maxZ).
cellSize - The size of the cells. (The grid that forms the base of the field.)
cellHeight - The height increment of the field.
Throws:
IllegalArgumentException - If the bounds are null or the wrong size.
Method Detail

addData

public OpenHeightSpan addData(int widthIndex,
                              int depthIndex,
                              OpenHeightSpan span)
Puts the span at the grid location, replacing any spans already at the location. The added span becomes the new base span for the location.

WARNING: The span count must be manually updated to reflect changes in span count

Behavior is undefined if the indices are invalid.

Parameters:
widthIndex - The width index of the grid location to add the span to. (0 <= value < BoundedField.width())
depthIndex - The depth index of the grid location to add the span to. (0 <= value < BoundedField.depth())
span - The span to put at the grid location.
Returns:
The original base span that was in the grid location, or null if there was no pre-existing span in the location.

clearBorderDistanceBounds

public void clearBorderDistanceBounds()
Resets the border distance values so they will be recacluated the next time they are needed.


dataIterator

public OpenHeightfield.OpenHeightFieldIterator dataIterator()
An iterator for the heightfields spans. The returned iterator does not support the OpenHeightfield.OpenHeightFieldIterator.remove() operation.


getData

public OpenHeightSpan getData(int widthIndex,
                              int depthIndex)
Retrieves the base (lowest) grid for the specified grid location.

Behavior is undefined if the indices are invalid.

Parameters:
widthIndex - The width index of the grid location the span is located in. (0 <= value < BoundedField.width())
depthIndex - The depth index of the grid location the span is located in. (0 <= value < BoundedField.depth())
Returns:
The base (lowest) span for the specified grid location. Null if there is no data for the grid location.

incrementSpanCount

public int incrementSpanCount()
Increments the span count.

IMPORTANT: There is no automatic span count updates. Span count must be managed manually.

Returns:
The new span count.

maxBorderDistance

public int maxBorderDistance()
The maximum distance a span in the heightfield is from its nearest border.

Returns:
The maximum distance a span in the heightfield is from its nearest border.

minBorderDistance

public int minBorderDistance()
The minimum distance a span in the height field is from its nearest border. (Usually zero. But can depend on the generation method.)

Returns:
The minimum distance a span in the height field is from its nearest border.

printDistanceField

public void printDistanceField()
Sends a tab delimited table of the distance field values to standard out.

Only the lowest spans in the field are output. So this operation is really only suitable for simple tests on fields that don't contain overlapping spans.

Columns: Width
Rows: Depth


printRegionField

public void printRegionField()
Sends a tab delimited table of the region ID values to standard out.

Only the lowest spans in the field are output. So this operation is really only suitable for simple tests on fields that don't contain overlapping spans.

Columns: Width
Rows: Depth


regionCount

public int regionCount()
The number of regions in the height field.

Includes the null region. So unless all spans are in the null region, this value will be >= 2. (E.g. The null region and at least one other region.)


setRegionCount

public void setRegionCount(int value)
Sets the region count.

The region count is expected to be zero based with the zero region representing the null region. So the region count is expected to be one more that the maximum region value. E.g. If the highest region value is 14, then the region count is 15.

IMPORTANT: There is no automatic region count management. Region count must be managed manually.

Parameters:
value - The new region count.

spanCount

public int spanCount()
The number of spans in the heightfield.

A value of zero indicates an empty heightfield.



Project Home and Source Code

Copyright 2010 Stephen Pratt. All rights reserved. Use is subject to license terms.