org.j3d.geom.terrain
Class FractalTerrainGenerator

java.lang.Object
  org.j3d.geom.GeometryGenerator
      org.j3d.geom.terrain.FractalTerrainGenerator

public class FractalTerrainGenerator
extends GeometryGenerator

A terrain generator using the standard "fractal" algorithm.

The algorithm used is the standard "fractal" method of subdivision and vertex perturbation. You can find a copy of this algorithm at http://astronomy.swin.edu.au/pbourke/terrain/frachill/. Roughness values are always greater than 1 to avoid problems with the calculations going out of whack.

Geometry is generated about the origin with to the half distance either side of that along the X-Z plane. X dimension is the width and Z dimension is the depth. Internally, this generator just creates the height points and then uses the ElevationGridGenerator to create the geometry array data.

The generator may take a seed terrain to start with. A common example of this is to use this generator to make a height map and then pass that through again from a heightfield to image coverter to generate clouds. If a seed terrain is given, then the number of coordinates along both sides must conform to the iteration requirements. It is best to provide a basic terrain site with either 3 or 5 points on a side although the generator will accept a seed terrain, so long as it is square and contains more than 2 points on a side.

Version:

$Revision: 1.5 $

Author:

Justin Couch

Constructor Summary

FractalTerrainGenerator()
Construct a default terrain with the following properties:
Size: 100x100 Height: 20 Sea Level: 0 Iterations: 20 Roughness: 2

FractalTerrainGenerator(boolean useSea, float seaLevel)
Create a new fractal terrain that can select whether the sea is in use or not.

FractalTerrainGenerator(float[][] terrain)
Create a new fractal terrain that uses the given seed terrain

FractalTerrainGenerator(float[][] terrain, boolean useSea, float seaLevel)
Create a new fractal terrain that can select whether the sea is in use or not and is based on the given seed terrain.

FractalTerrainGenerator(float[][] terrain, float width, float depth)
Construct a fractal terrain of the given width and depth that is based on the given seed terrain.

FractalTerrainGenerator(float width, float depth)
Construct a new fractal terrain with a given width and depth.

FractalTerrainGenerator(float width, float depth, float height, boolean useSea, float seaLevel, int iterations, float roughness, long seed, float[][] terrain)
Construct a terrain generator with all items configurable.

FractalTerrainGenerator(float width, float depth, float height, int iterations, float roughness, long seed)
Construct a terrain generator with the given width and depth.

FractalTerrainGenerator(float height, int iterations, float roughness, long seed)
Construct a new terrain that starts at the given maximum height and is iterated through the given number of times.

Method Summary

void	forceRegenerate() Force the generator to create a new set of points without having to reset any other data.
float[][]	generate() Generate height values only based on the current configuration.
void	generate(GeometryData data) Generate a new set of geometry items based on the passed data.
float[]	getDimensions() Get the dimensions of the terrain.
int	getVertexCount(GeometryData data) Get the number of vertices that this generator will create for the shape given in the definition.
boolean	hasSeaLevel() Check to see that this cylinder has ends in use or not
void	setDimensions(float width, float depth) Change the dimensions of the cone to be generated.
void	setGenerationFactors(float height, int iterations, float roughness, long seed) Set the factors that effect the generation of the terrain - heights randomness etc
void	setSeaData(boolean useSea, float seaLevel) Set all of the items related to the sea level information.
void	setSeedTerrain(float[][] terrain) Set the terrain that is used as a seed for the generator.

Methods inherited from class org.j3d.geom.GeometryGenerator

createFaceNormal, createFaceNormal, createRadialNormal, createRadialNormal

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FractalTerrainGenerator

public FractalTerrainGenerator()

Construct a default terrain with the following properties:
Size: 100x100 Height: 20 Sea Level: 0 Iterations: 20 Roughness: 2

FractalTerrainGenerator

public FractalTerrainGenerator(float[][] terrain)

Create a new fractal terrain that uses the given seed terrain

Parameters:

terrain - The spot heights to use

Throws:

java.lang.IllegalArgumentException - The provided matrix is not square

FractalTerrainGenerator

public FractalTerrainGenerator(boolean useSea,
                               float seaLevel)

Create a new fractal terrain that can select whether the sea is in use or not.

Parameters:

useSea - true if the sea level is to be used

seaLevel - The height of the sea

Throws:

java.lang.IllegalArgumentException - seaLevel, if used is greater than the default height of the ground (20)

FractalTerrainGenerator

public FractalTerrainGenerator(float[][] terrain,
                               boolean useSea,
                               float seaLevel)

Create a new fractal terrain that can select whether the sea is in use or not and is based on the given seed terrain.

Parameters:

useSea - true if the sea level is to be used

seaLevel - The height of the sea

terrain - The spot heights to use

Throws:

java.lang.IllegalArgumentException - seaLevel, if used is greater than the default height of the ground (20) or the provided terrain matrix is not square

FractalTerrainGenerator

public FractalTerrainGenerator(float width,
                               float depth)

Construct a new fractal terrain with a given width and depth. A sea level is used and defaults to a height of zero.

Parameters:

width - The width of the terrain to generate

depth - The depth of the terrain to generate

Throws:

java.lang.IllegalArgumentException - The width or height is non-positive

FractalTerrainGenerator

public FractalTerrainGenerator(float[][] terrain,
                               float width,
                               float depth)

Construct a fractal terrain of the given width and depth that is based on the given seed terrain. A sea level is used and defaults to a height of zero.

Parameters:

width - The width of the terrain to generate

depth - The depth of the terrain to generate

Throws:

java.lang.IllegalArgumentException - The width or height is non-positive or the terrain given is non-square.

FractalTerrainGenerator

public FractalTerrainGenerator(float height,
                               int iterations,
                               float roughness,
                               long seed)

Construct a new terrain that starts at the given maximum height and is iterated through the given number of times. The seed is can be used to control the seed value for the random number generator. A value of zero says to use the default seed provided by the Java runtime.

Parameters:

height - The (approx) max height of the terrain to generate

iterations - The number of subdivisions to calculate

roughness - Division factor for each iteration of height

seed - The seed for the random number generator (0 to be ignored)

Throws:

java.lang.IllegalArgumentException - Roughness < 1 or the height is lower than the default sea height (0).

FractalTerrainGenerator

public FractalTerrainGenerator(float width,
                               float depth,
                               float height,
                               int iterations,
                               float roughness,
                               long seed)

Construct a terrain generator with the given width and depth. Maximum height can be set as well as the iterations to generate terrain.

Parameters:

width - The width of the terrain to generate

depth - The depth of the terrain to generate

height - The (approx) max height of the terrain to generate

iterations - The number of subdivisions to calculate

roughness - Division factor for each iteration of height

seed - The seed for the random number generator (0 to be ignored)

Throws:

java.lang.IllegalArgumentException - Various reasons. See message or other constructors

FractalTerrainGenerator

public FractalTerrainGenerator(float width,
                               float depth,
                               float height,
                               boolean useSea,
                               float seaLevel,
                               int iterations,
                               float roughness,
                               long seed,
                               float[][] terrain)

Construct a terrain generator with all items configurable.

Parameters:

width - The width of the terrain to generate

depth - The depth of the terrain to generate

height - The (approx) max height of the terrain to generate

useSea - true if the sea level is to be used

seaLevel - The height of the sea

iterations - The number of subdivisions to calculate

roughness - Division factor for each iteration of height

seed - The seed for the random number generator (0 to be ignored)

terrain - The spot heights to use

Throws:

java.lang.IllegalArgumentException - Various reasons. See message or other constructors

Method Detail

hasSeaLevel

public boolean hasSeaLevel()

Check to see that this cylinder has ends in use or not

Returns:

true if there is are end caps in use

getDimensions

public float[] getDimensions()

Get the dimensions of the terrain. These are returned as 2 values of width and depth respectively for the array. A new array is created each time so you can do what you like with it.

Returns:

The current size of the terrain

setGenerationFactors

public void setGenerationFactors(float height,
                                 int iterations,
                                 float roughness,
                                 long seed)

Set the factors that effect the generation of the terrain - heights randomness etc

Parameters:

height - The (approx) max height of the terrain to generate

iterations - The number of subdivisions to calculate

roughness - Division factor for each iteration of height

seed - A value to use to seed the random number generator with

setDimensions

public void setDimensions(float width,
                          float depth)

Change the dimensions of the cone to be generated. Calling this will make the points be re-calculated next time you ask for geometry or normals.

Parameters:

width - The width of the terrain to generate

depth - The depth of the terrain to generate

setSeaData

public void setSeaData(boolean useSea,
                       float seaLevel)

Set all of the items related to the sea level information.

Parameters:

useSea - true if the sea level is to be used

seaLevel - The height of the sea

setSeedTerrain

public void setSeedTerrain(float[][] terrain)

Set the terrain that is used as a seed for the generator. This can be used to set a basic shape of the terrain. Provided points must be a square array. A null reference can be used to return the seed terrain to the default.

Parameters:

terrain - The new seed terrain to use or null

Throws:

java.lang.IllegalArgumentException - The provided matrix is not square

forceRegenerate

public void forceRegenerate()

Force the generator to create a new set of points without having to reset any other data.

getVertexCount

public int getVertexCount(GeometryData data)
                   throws UnsupportedTypeException

Get the number of vertices that this generator will create for the shape given in the definition.

Specified by:

getVertexCount in class GeometryGenerator

Parameters:

data - The data to base the calculations on

Returns:

The vertex count for the object

Throws:

UnsupportedTypeException - The generator cannot handle the type of geometry you have requested.

generate

public void generate(GeometryData data)
              throws UnsupportedTypeException,
                     InvalidArraySizeException

Generate a new set of geometry items based on the passed data. If the data does not contain the right minimum array lengths an exception will be generated. If the array reference is null, this will create arrays of the correct length and assign them to the return value.

Specified by:

generate in class GeometryGenerator

Parameters:

data - The data to base the calculations on

Throws:

InvalidArraySizeException - The array is not big enough to contain the requested geometry

UnsupportedTypeException - The generator cannot handle the type of geometry you have requested

generate

public float[][] generate()

Generate height values only based on the current configuration.

Returns:

The last generated height values