Triton
Visual simulation library for ocean rendering.
Public Member Functions

Triton::Environment Class Reference

Triton's public interface for specifying the environmental conditions and camera properties. More...

#include <Environment.h>

Inheritance diagram for Triton::Environment:
Inheritance graph
[legend]
Collaboration diagram for Triton::Environment:
Collaboration graph
[legend]

List of all members.

Public Member Functions

 Environment ()
 Constructor.
EnvironmentError TRITONAPI Initialize (CoordinateSystem cs, Renderer ren, ResourceLoader *rl, void *device=NULL, bool hdr=false)
 Initializes the environment prior to use.
virtual ~Environment ()
 Virtual destructor.
void TRITONAPI SetLicenseCode (const char *userName, const char *registrationCode)
 Licensed users must call SetLicenseCode with your user name and registration code prior to using the Environment object.
void TRITONAPI SetRandomNumberGenerator (RandomNumberGenerator *rng)
 Set a custom RandomNumberGenerator - derived random number generator, to override Triton's default use of stdlib's rand() function.
RandomNumberGenerator *TRITONAPI GetRandomNumberGenerator () const
 Returns either the default RandomNumberGenerator used for all random numbers in Triton, or a custom subclass of RandomNumberGenerator that was passed in via Environment::SetRandomNumberGenerator().
ResourceLoader *TRITONAPI GetResourceLoader () const
 Retrieves the ResourceLoader object passed in to the Environment() constructor.
void *TRITONAPI GetDevice () const
 Retrieves the DirectX device pointer passed in to the Environment() constructor, or NULL for OpenGL users.
void TRITONAPI SetDirectionalLight (const Vector3 &direction, const Vector3 &color)
 Sets the color and direction of directional light used to light the water, as from the sun or moon.
void TRITONAPI SetAmbientLight (const Vector3 &color)
 Sets the color of ambient light used to light the water, as from skylight.
const Vector3 &TRITONAPI GetLightDirection () const
 Retrieves the vector toward the infinitely distant directional light source passed in via SetDirectionalLight().
const Vector3 &TRITONAPI GetDirectionalLightColor () const
 Retrieves the RGB color of the directional light source passed in via SetDirectionalLight().
const Vector3 &TRITONAPI GetAmbientLightColor () const
 Retrieves the RGB color of the ambient light passed in via SetAmbientLight().
void TRITONAPI SetEnvironmentMap (TextureHandle cubeMap, const Matrix3 &textureMatrix=Matrix3::Identity)
 Passes in an optional environment cube map used for rendering reflections in the water.
TextureHandle TRITONAPI GetEnvironmentMap () const
 Retrieves the environment cube map passed in via SetEnvironmentMap(), which may be a GLuint, LPDIRECT3DCUBETEXTURE9, or ID3D11ShaderResourceView* depending on the renderer being used.
Matrix3 TRITONAPI GetEnvironmentMapMatrix () const
 Retrieves the texture matrix used to transform the environment map lookups at runtime, which was optionally passed in via SetEnvironmentMap().
void TRITONAPI SetHeightMap (TextureHandle pHeightMap, const Matrix4 &worldToTextureCoords, void *context=0, const Camera *camera=0)
 Optionally sets a height map used by Triton for improved water / shoreline interactions.
TextureHandle TRITONAPI GetHeightMap (const Camera *camera=0) const
 Retrieves the height map passed in via SetHeightMap(), which may be a GLuint, LPDIRECT3DTEXTURE9, or ID3D11ShaderResourceView* depending on the renderer being used.
Matrix4 TRITONAPI GetHeightMapMatrix (const Camera *camera=0) const
 Retrieves the texture matrix used to transform the height map lookups at runtime, which was passed in via SetHeightMap().
void TRITONAPI SetUserHeightCB (GETUSERHEIGHTPROC _userHeightCB)
 Sets an optional user-provided callback to obtain height data.
GETUSERHEIGHTPROC TRITONAPI GetUserHeightCB () const
 Retrieves the function pointer for the user-provided height callback.
void TRITONAPI SetHeightMapRange (float _range)
 Sets a height map multiplier.
void TRITONAPI SetHeightMapOffset (float _offset)
 Sets a height map offset.
float TRITONAPI GetHeightMapRange () const
 Retrieves the height map range.
float TRITONAPI GetHeightMapOffset () const
 Retrieves the heightmap offset.
void TRITONAPI SetDepthMap (TextureHandle pDepthMap)
 Optionally sets a depth texture map used for terrain / water blending at coastlines.
TextureHandle TRITONAPI GetDepthMap () const
 Retrieves the depth map passed in via SetDepthMap(), which may be a GLuint, LPDIRECT3DTEXTURE9, or ID3D11ShaderResourceView* depending on the renderer being used.
void TRITONAPI SetBreakingWavesParameters (const BreakingWavesParameters &params)
 Configures the parameters used to simulate breaking waves at shorelines.
const BreakingWavesParameters
&TRITONAPI 
GetBreakingWavesParameters () const
 Retrieves the current parameters for breaking waves.
void TRITONAPI SetPlanarReflectionMap (TextureHandle textureMap, const Matrix3 &textureMatrix, float normalDisplacementScale=0.125f)
 Passes in an optional planar reflection map used for rendering local reflections in the water.
TextureHandle TRITONAPI GetPlanarReflectionMap () const
 Retrieves the environment cube map passed in via SetPlanarReflectionMap(), which may be a GLuint, LPDIRECT3DTEXTURE9, or ID3D11ShaderResourceView* depending on the renderer being used.
Matrix3 TRITONAPI GetPlanarReflectionMapMatrix () const
 Retrieves the texture matrix used to transform the planar reflection map lookups at runtime, which was passed in via SetPlanarReflectionMap().
float TRITONAPI GetPlanarReflectionDisplacementScale () const
 Retrieves normal displacement scale set for planar reflections via SetPlanarReflectionMap().
void TRITONAPI SimulateSeaState (double beaufortScale, double windDirection, bool leftHanded=false)
 Simulates a specific sea state on the Beaufort scale, by clearing out any existing wind fetches passed into the Environment and setting up a new one consistent with the state specified.
void TRITONAPI AddWindFetch (const WindFetch &fetch, bool leftHanded=false)
 Adds a Triton::WindFetch to the environment, which specifies an area of wind of a given speed and direction, which may or may not be localized.
void TRITONAPI ClearWindFetches ()
 Removes all wind fetches or sea state simulations from the simulated environment, resulting in a perfectly calm sea.
void TRITONAPI AddSwell (float waveLength, float waveHeight, float direction, float phase=0, bool leftHanded=false)
 Adds a swell wave to the ocean conditions in addition to the local wind waves.
void TRITONAPI ClearSwells ()
 Clears any swells previously added via AddSwell().
const TRITON_VECTOR (SwellDescription)&TRITONAPI GetSwells() const
 Retrieves the list of swells added via AddSwell() following startup or the last call to ClearSwells().
void TRITONAPI SetDouglasSeaScale (int seaState, float windWaveDirection, int swellState, float swellDirection, bool leftHanded=false)
 Simulate conditions as described by the Douglas sea scale (http://en.wikipedia.org/wiki/Douglas_Sea_Scale).
void TRITONAPI GetWind (const Vector3 &pos, double &windSpeed, double &windDirection, double &fetchLength) const
 Computes the wind conditions at a given location, by evaluating all WindFetch objects that include the position.
void TRITONAPI SetSeaLevel (double altitudeMSL)
 If you want to change the mean sea level from a height of 0 in flat-earth coordinates, or from the WGS84 ellipsoid in geocentric coordinates, you may do so here.
double TRITONAPI GetSeaLevel () const
 Returns the offset for the mean sea level previously set by SetSeaLevel().
void TRITONAPI SetAboveWaterVisibility (double visibility, const Vector3 &fogColor)
 Sets the simulated atmospheric visibility above the water, used to fog out the surface of the water when viewed from above.
void TRITONAPI GetAboveWaterVisibility (double &visibility, Vector3 &fogColor) const
 Retrieves the above-water visibility settings previously set with SetAboveWaterVisibility().
void TRITONAPI SetBelowWaterVisibility (double visibility, const Vector3 &fogColor)
 Sets the simulated atmospheric visibility below the water, used to fog out the surface of the water when viewed from below.
void TRITONAPI GetBelowWaterVisibility (double &visibility, Vector3 &fogColor) const
 Retrieves the below-water visibility settings previously set with SetBelowWaterVisibility().
void TRITONAPI SetWaveBlendDepth (double depth)
 Sets the ocean depth at which wave heights will start to become dampened, and the water will start becoming transparent, for smooth coastline blending.
double TRITONAPI GetWaveBlendDepth () const
 Retrieves the ocean depth at which wave heights will start to become dampened, and the water will start becoming transparent, for smooth coastline blending.
void TRITONAPI SetSunIntensity (float intensity)
 Sets the intensity of the sunlight visible at the ocean surface; used to modulate the specular highlights of the sun on the water surface.
float TRITONAPI GetSunIntensity () const
 Retrieves the intensity of the transmitted direct sunlight on the water surface, as set with SetSunIntensity().
void TRITONAPI SetWorldUnits (double worldUnits)
 Sets the size of one world unit in meters.
double TRITONAPI GetWorldUnits () const
 Retrieves the size of one world unit, in meters.
CoordinateSystem TRITONAPI GetCoordinateSystem () const
 Returns the CoordinateSystem passed into the Environment() constructor, indicating the up vector and the presence of a geocentric or flat coordinate system.
bool TRITONAPI IsGeocentric () const
 Returns whether the CoordinateSystem passed into the Environment() constructor is geocentric, indicating an elliptical or spherical coordinate system where all points are relative to the center of the Earth.
Renderer TRITONAPI GetRenderer () const
 Returns the Renderer specified in the Environment() constructor, telling you what flavor of OpenGL or DirectX is being used to render Triton's water.
bool TRITONAPI IsOpenGL () const
 Returns whether the Renderer specified in the Envrionment() constructor is an OpenGL renderer.
bool TRITONAPI IsDirectX () const
 Returns whether the Renderer specified in the Environment() constructor is a DirectX renderer.
void TRITONAPI SetCameraMatrix (const double *m)
 Sets the modelview matrix used for rendering the ocean; this must be called every frame prior to calling Ocean::Draw() if your camera orientation or position changes.
void TRITONAPI SetProjectionMatrix (const double *p)
 Sets the projection matrix used for rendering the ocean; this must be called every frame prior to calling Ocean::Draw().
void TRITONAPI SetViewport (int x, int y, int width, int height)
 Informs Triton of the current viewport position and size.
void TRITONAPI SetZoomLevel (float zoom)
 If your camera is being zoomed from its typical field of view, use this method to let Triton know about the zoom factor.
float TRITONAPI GetZoomLevel () const
 Retrieves any zoom level previously set with SetZoomLevel(), or 1.0 if default.
void TRITONAPI SetUserDefinedVertString (const char *userDefinedString)
 Sets a user defined string to be prepended to all vertex shaders.
void TRITONAPI SetUserDefinedFragString (const char *userDefinedString)
 Sets a user defined string to be prepended to all fragment shaders.
const char *TRITONAPI GetUserDefinedVertString () const
 Retrieves the user defined vertex string previously set with SetUserDefinedVertString.
const char *TRITONAPI GetUserDefinedFragString () const
 Retrieves the user defined fragment string previously set with SetUserDefinedFragString.
bool TRITONAPI GetViewport (int &x, int &y, int &width, int &height) const
 Retrieves any viewport information previously set via SetViewport().
const Camera *TRITONAPI GetCamera () const
 Deprecated method to get Triton Camera.
Camera *TRITONAPI GetCamera ()
 Deprecated method to get Triton Camera.
Camera *TRITONAPI CreateCamera (void)
 Create a camera.
void TRITONAPI DestroyCamera (Camera *camera)
 Destroy a camera.
const TRITON_SET (Camera *)&GetCameras(void) const
 Get all cameras.
const double *TRITONAPI GetCameraMatrix () const
 Retrieves an array of 16 doubles representing the modelview matrix passed in via SetCameraMatrix().
const double *TRITONAPI GetProjectionMatrix () const
 Retrieves an array of 16 doubles representing the projection matrix passed in via SetProjectionMatrix().
const double *TRITONAPI GetCameraPosition () const
 Retrieves an array of 3 doubles representing the X, Y, and Z position of the camera, extracted from the modelview matrix passed in via SetCameraMatrix().
Vector3 TRITONAPI GetUpVector () const
 Retrieves a normalized vector pointing "up", based on the coordinate system specified in Environment::Initialize() and the current position from the modelview matrix passed in through Environment::SetCameraMatrix().
Vector3 TRITONAPI GetRightVector () const
 Retrieves a normalized vector pointing "right", based on the coordinate system specified in Environment::Initialize() and the current position from the modelview matrix passed in through Environment::SetCameraMatrix().
void TRITONAPI SetConfigOption (const char *key, const char *value)
 Sets a configuration setting (defaults in resources/triton.config.) Many settings are read at initialization, so call this as early as possible after initializing the Environment.
const char *TRITONAPI GetConfigOption (const char *key)
 Retrieves the configuration setting for the given configuration key, as set in resources/triton.config or via SetConfigOption().
bool TRITONAPI CullSphere (const Vector3 &position, double radius) const
 Returns true if the given sphere lies within the view frustum, as defined by the modelview - projection matrix passed in via SetCameraMatrix() and SetProjectionMatrix().
const bool TRITONAPI GetHDREnabled () const
 Retrieves whether HDR mode is enabled, indicating whether color values are clamped to [0,1.0], as set in Environment::Initialize()
void TRITONAPI EnableOpenMP (bool enabled)
 Sets Triton's usage of OpenMP to enable parallel proccessing of CPU-intensive tasks across multiple CPU cores.
bool TRITONAPI GetOpenMPEnabled () const
 Retrieves whether OpenMP has been enabled to take advantage of multi-core CPU's.
float TRITONAPI GetMaximumWaveHeight () const
 Gets the estimated maximum wave height in meters at the camera position, given the current wind and swell conditions.
void TRITONAPI SetCurrent (const Vector3 &direction, double speed)
 Sets a simulated current in the given direction at the given speed.
void TRITONAPI GetCurrent (Vector3 &direction, double &speed) const
 Retrieves the current direction and speed previously set with SetCurrent().
void TRITONAPI SetWaterTransparency (float t)
 Sets an explicit transparency on the water surface.
float TRITONAPI GetWaterTransparency () const
 Gets the explicit transparency of the water set via SetWaterTransparency().

Detailed Description

Triton's public interface for specifying the environmental conditions and camera properties.

The Ocean constructor requires an Environment object, so you'll need to create this first.


Constructor & Destructor Documentation

Triton::Environment::Environment ( )

Constructor.

virtual Triton::Environment::~Environment ( ) [virtual]

Virtual destructor.


Member Function Documentation

void TRITONAPI Triton::Environment::AddSwell ( float  waveLength,
float  waveHeight,
float  direction,
float  phase = 0,
bool  leftHanded = false 
)

Adds a swell wave to the ocean conditions in addition to the local wind waves.

Swells may sometimes originate from distant storms and not have anything to do with the local conditions. You may add as many swells as you wish; they incur no run-time performance impact. Swells are not supported in the GERSTNER water model.

See also:
ClearSwells()
Parameters:
waveLengthThe wavelength of the swell wave, from peak to peak, in world units. Swells are generally around 100-200 m.
waveHeightThe swell wave height, from peak to trough, in world units.
directionThe direction of the swell wave, in radians. This could be different from the local wind direction.
phaseThe phase offset of the swell wave, in radians.
leftHandedIf you are using a left-handed coordinate system (for example, Y is "up" but positive Z is "North"), pass true in order to ensure your wave direction is represented correctly.
void TRITONAPI Triton::Environment::AddWindFetch ( const WindFetch fetch,
bool  leftHanded = false 
)

Adds a Triton::WindFetch to the environment, which specifies an area of wind of a given speed and direction, which may or may not be localized.

This WindFetch will be added to any other wind passed in previously, unless ClearWindFetches() is called first.

All waves in Triton are a result of simulated wind conditions. Without wind, there will be no waves. Stronger winds traveling across longer distances will result in higher waves.

Parameters:
fetchThe WindFetch to add to the simulated environment.
leftHandedIf you are using a left-handed coordinate system (for example, Y is "up" but positive Z is "North"), pass true in order to ensure your wave direction is represented correctly.
void TRITONAPI Triton::Environment::ClearSwells ( )

Clears any swells previously added via AddSwell().

See also:
AddSwell()
void TRITONAPI Triton::Environment::ClearWindFetches ( )

Removes all wind fetches or sea state simulations from the simulated environment, resulting in a perfectly calm sea.

Call AddWindFetch() or SimulateSeaState() to add wind back in and generate waves as a result.

bool TRITONAPI Triton::Environment::CullSphere ( const Vector3 position,
double  radius 
) const

Returns true if the given sphere lies within the view frustum, as defined by the modelview - projection matrix passed in via SetCameraMatrix() and SetProjectionMatrix().

Parameters:
positionThe center of the sphere in world coordinates.
radiusThe radius of the sphere in world coordinates.
Returns:
True if the sphere is not visible and should be culled.
void TRITONAPI Triton::Environment::EnableOpenMP ( bool  enabled) [inline]

Sets Triton's usage of OpenMP to enable parallel proccessing of CPU-intensive tasks across multiple CPU cores.

You might want to disable this if you are more concerned about limiting CPU usage than maintaining the fastest possible ocean rendering. OpenMP is enabled by default. Note, if the IPP FFT implementation is being used instead of CUDA or OpenCL, multi-core usage will happen regardless of this setting.

void TRITONAPI Triton::Environment::GetAboveWaterVisibility ( double &  visibility,
Vector3 fogColor 
) const [inline]

Retrieves the above-water visibility settings previously set with SetAboveWaterVisibility().

Parameters:
visibilityReceives the visibility, in world units, above the water.
fogColorReceives the fog color, in normalized RGB units.
const Vector3& TRITONAPI Triton::Environment::GetAmbientLightColor ( ) const [inline]

Retrieves the RGB color of the ambient light passed in via SetAmbientLight().

void TRITONAPI Triton::Environment::GetBelowWaterVisibility ( double &  visibility,
Vector3 fogColor 
) const [inline]

Retrieves the below-water visibility settings previously set with SetBelowWaterVisibility().

Parameters:
visibilityReceives the visibility, in world units, above the water.
fogColorReceives the fog color, in normalized RGB units.
const BreakingWavesParameters& TRITONAPI Triton::Environment::GetBreakingWavesParameters ( ) const [inline]

Retrieves the current parameters for breaking waves.

See also:
Environment::SetBreakingWavesParameters()
const Camera* TRITONAPI Triton::Environment::GetCamera ( ) const [inline]

Deprecated method to get Triton Camera.

See CreateCamera(), DestroyCamera(), GetCameras()

Camera* TRITONAPI Triton::Environment::GetCamera ( ) [inline]

Deprecated method to get Triton Camera.

See CreateCamera(), DestroyCamera(), GetCameras()

const double* TRITONAPI Triton::Environment::GetCameraMatrix ( ) const

Retrieves an array of 16 doubles representing the modelview matrix passed in via SetCameraMatrix().

Deprecated* See CreateCamera(), DestroyCamera(), GetCameras()

const double* TRITONAPI Triton::Environment::GetCameraPosition ( ) const

Retrieves an array of 3 doubles representing the X, Y, and Z position of the camera, extracted from the modelview matrix passed in via SetCameraMatrix().

Deprecated* See CreateCamera(), DestroyCamera(), GetCameras()

const char* TRITONAPI Triton::Environment::GetConfigOption ( const char *  key)

Retrieves the configuration setting for the given configuration key, as set in resources/triton.config or via SetConfigOption().

Parameters:
keyThe configuration key to retrieve
Returns:
The value of the key specified, or NULL if not found.
CoordinateSystem TRITONAPI Triton::Environment::GetCoordinateSystem ( void  ) const [inline]

Returns the CoordinateSystem passed into the Environment() constructor, indicating the up vector and the presence of a geocentric or flat coordinate system.

void TRITONAPI Triton::Environment::GetCurrent ( Vector3 direction,
double &  speed 
) const [inline]

Retrieves the current direction and speed previously set with SetCurrent().

TextureHandle TRITONAPI Triton::Environment::GetDepthMap ( ) const [inline]

Retrieves the depth map passed in via SetDepthMap(), which may be a GLuint, LPDIRECT3DTEXTURE9, or ID3D11ShaderResourceView* depending on the renderer being used.

void* TRITONAPI Triton::Environment::GetDevice ( ) const [inline]

Retrieves the DirectX device pointer passed in to the Environment() constructor, or NULL for OpenGL users.

const Vector3& TRITONAPI Triton::Environment::GetDirectionalLightColor ( ) const [inline]

Retrieves the RGB color of the directional light source passed in via SetDirectionalLight().

TextureHandle TRITONAPI Triton::Environment::GetEnvironmentMap ( ) const [inline]

Retrieves the environment cube map passed in via SetEnvironmentMap(), which may be a GLuint, LPDIRECT3DCUBETEXTURE9, or ID3D11ShaderResourceView* depending on the renderer being used.

Matrix3 TRITONAPI Triton::Environment::GetEnvironmentMapMatrix ( ) const [inline]

Retrieves the texture matrix used to transform the environment map lookups at runtime, which was optionally passed in via SetEnvironmentMap().

TextureHandle TRITONAPI Triton::Environment::GetHeightMap ( const Camera camera = 0) const

Retrieves the height map passed in via SetHeightMap(), which may be a GLuint, LPDIRECT3DTEXTURE9, or ID3D11ShaderResourceView* depending on the renderer being used.

Parameters:
cameraAn optional camera. Height maps are camera specific. This parameter allows you to retrieve the height map for the camera in question. See SetHeightMap()
Matrix4 TRITONAPI Triton::Environment::GetHeightMapMatrix ( const Camera camera = 0) const

Retrieves the texture matrix used to transform the height map lookups at runtime, which was passed in via SetHeightMap().

This matrix transforms world coordinates into height map texture coordinates.

Parameters:
cameraAn optional camera. Height maps are camera specific. This parameter allows you to retrieve the height map matrix for the height map, for the camera in question. See SetHeightMap()
float TRITONAPI Triton::Environment::GetHeightMapOffset ( ) const [inline]

Retrieves the heightmap offset.

float TRITONAPI Triton::Environment::GetHeightMapRange ( ) const [inline]

Retrieves the height map range.

const Vector3& TRITONAPI Triton::Environment::GetLightDirection ( ) const [inline]

Retrieves the vector toward the infinitely distant directional light source passed in via SetDirectionalLight().

float TRITONAPI Triton::Environment::GetMaximumWaveHeight ( ) const

Gets the estimated maximum wave height in meters at the camera position, given the current wind and swell conditions.

bool TRITONAPI Triton::Environment::GetOpenMPEnabled ( ) const [inline]

Retrieves whether OpenMP has been enabled to take advantage of multi-core CPU's.

See also:
EnableOpenMP()
float TRITONAPI Triton::Environment::GetPlanarReflectionDisplacementScale ( ) const [inline]

Retrieves normal displacement scale set for planar reflections via SetPlanarReflectionMap().

TextureHandle TRITONAPI Triton::Environment::GetPlanarReflectionMap ( ) const [inline]

Retrieves the environment cube map passed in via SetPlanarReflectionMap(), which may be a GLuint, LPDIRECT3DTEXTURE9, or ID3D11ShaderResourceView* depending on the renderer being used.

Matrix3 TRITONAPI Triton::Environment::GetPlanarReflectionMapMatrix ( ) const [inline]

Retrieves the texture matrix used to transform the planar reflection map lookups at runtime, which was passed in via SetPlanarReflectionMap().

const double* TRITONAPI Triton::Environment::GetProjectionMatrix ( ) const

Retrieves an array of 16 doubles representing the projection matrix passed in via SetProjectionMatrix().

Deprecated* See CreateCamera(), DestroyCamera(), GetCameras()

RandomNumberGenerator* TRITONAPI Triton::Environment::GetRandomNumberGenerator ( ) const [inline]

Returns either the default RandomNumberGenerator used for all random numbers in Triton, or a custom subclass of RandomNumberGenerator that was passed in via Environment::SetRandomNumberGenerator().

Returns:
The RandomNumberGenerator instance in use by Triton.
Renderer TRITONAPI Triton::Environment::GetRenderer ( ) const [inline]

Returns the Renderer specified in the Environment() constructor, telling you what flavor of OpenGL or DirectX is being used to render Triton's water.

ResourceLoader* TRITONAPI Triton::Environment::GetResourceLoader ( ) const [inline]

Retrieves the ResourceLoader object passed in to the Environment() constructor.

Vector3 TRITONAPI Triton::Environment::GetRightVector ( ) const

Retrieves a normalized vector pointing "right", based on the coordinate system specified in Environment::Initialize() and the current position from the modelview matrix passed in through Environment::SetCameraMatrix().

Deprecated* See CreateCamera(), DestroyCamera(), GetCameras()

double TRITONAPI Triton::Environment::GetSeaLevel ( ) const [inline]

Returns the offset for the mean sea level previously set by SetSeaLevel().

Returns:
The offset in world units that the mean sea level is displaced by.
float TRITONAPI Triton::Environment::GetSunIntensity ( ) const [inline]

Retrieves the intensity of the transmitted direct sunlight on the water surface, as set with SetSunIntensity().

Vector3 TRITONAPI Triton::Environment::GetUpVector ( ) const

Retrieves a normalized vector pointing "up", based on the coordinate system specified in Environment::Initialize() and the current position from the modelview matrix passed in through Environment::SetCameraMatrix().

Deprecated* See CreateCamera(), DestroyCamera(), GetCameras()

GETUSERHEIGHTPROC TRITONAPI Triton::Environment::GetUserHeightCB ( ) const [inline]

Retrieves the function pointer for the user-provided height callback.

bool TRITONAPI Triton::Environment::GetViewport ( int &  x,
int &  y,
int &  width,
int &  height 
) const

Retrieves any viewport information previously set via SetViewport().

If SetViewport() has not been called, this method will return false and return zeros for all parameters.

Parameters:
xThe x position of the current viewport origin.
yThe y position of the current viewport origin.
widthThe width of the current viewport.
heightThe height of the current viewport.
Returns:
true if SetViewport was previously called, and valid information is returned.
float TRITONAPI Triton::Environment::GetWaterTransparency ( ) const [inline]

Gets the explicit transparency of the water set via SetWaterTransparency().

double TRITONAPI Triton::Environment::GetWaveBlendDepth ( ) const [inline]

Retrieves the ocean depth at which wave heights will start to become dampened, and the water will start becoming transparent, for smooth coastline blending.

If Environment::SetWaveBlendDepth() has been called, then that value will be returned. Otherwise, the below water visiblity set via Environment::SetBelowWaterVisibility() will be returned instead.

void TRITONAPI Triton::Environment::GetWind ( const Vector3 pos,
double &  windSpeed,
double &  windDirection,
double &  fetchLength 
) const

Computes the wind conditions at a given location, by evaluating all WindFetch objects that include the position.

See also:
AddWindFetch()
SimulateSeaState()
Parameters:
posA const reference to the position at which wind conditions should be computed.
windSpeedA reference to a double that will receive the overall wind speed at this location, in world units per second.
windDirectionA reference to a double that will receive the overall wind direction at this location, in radians.
fetchLengthA reference to a double that will receive the fetch length of the farthest WindFetch affecting this location. May return 0 if the local WindFetches have no fetch length specified via WindFetch::SetLocalization() or WindFetch::SetFetchLength().
double TRITONAPI Triton::Environment::GetWorldUnits ( ) const [inline]

Retrieves the size of one world unit, in meters.

See also:
SetWorldUnits()
float TRITONAPI Triton::Environment::GetZoomLevel ( ) const [inline]

Retrieves any zoom level previously set with SetZoomLevel(), or 1.0 if default.

Returns:
The zoom level specified by Environment::SetZoomLevel() if any, 1.0 otherwise.
EnvironmentError TRITONAPI Triton::Environment::Initialize ( CoordinateSystem  cs,
Renderer  ren,
ResourceLoader rl,
void *  device = NULL,
bool  hdr = false 
)

Initializes the environment prior to use.

Parameters:
csThe CoordinateSystem your application is using, which may be a geocentric system based on an elliptical WGS84 or spherical earth model, or a flat cartesian model, with up pointing along either the Y or Z axes.
renSpecifies the version of OpenGL or DirectX your application is using. Triton will render the ocean using the same graphics subsystem.
rlA ResourceLoader object that is used by Triton for loading its graphics, shader, and configuration resources. This may be an instance of Triton's default ResourceLoader class that loads loose files in Triton's resources directory directly from disk, or your own derived class that handles resource management in some other way.
deviceUnused for OpenGL contexts. For DirectX users, this must be a pointer to your valid and initialized DIRECT3DDEVICE9 or ID3D11Device.
hdrWhether High Dynamic Range rendering is desired, meaning colors will not be clamped to [0.0,1.0]. If true, HDR lighting values passed in via Environment::SetDirectionalLight(), Environment::SetAmbientLight(), and/or via floating point reflection or environment maps will be preserved.
Returns:
An error code if the environment failed to initialize, in which case you can't use this environment. To receive more details on why it failed, enable the setting enable-debug-messages in resources/triton.config which will send more info to your debugger's output. If initialization succeeded, you'll get back SUCCEEDED.
bool TRITONAPI Triton::Environment::IsDirectX ( ) const [inline]

Returns whether the Renderer specified in the Environment() constructor is a DirectX renderer.

bool TRITONAPI Triton::Environment::IsGeocentric ( ) const [inline]

Returns whether the CoordinateSystem passed into the Environment() constructor is geocentric, indicating an elliptical or spherical coordinate system where all points are relative to the center of the Earth.

bool TRITONAPI Triton::Environment::IsOpenGL ( ) const [inline]

Returns whether the Renderer specified in the Envrionment() constructor is an OpenGL renderer.

void TRITONAPI Triton::Environment::SetAboveWaterVisibility ( double  visibility,
const Vector3 fogColor 
) [inline]

Sets the simulated atmospheric visibility above the water, used to fog out the surface of the water when viewed from above.

You may use this method to fog the ocean consistently with other objects in your scene.

The visibility specified will be transformed into an exponential fog extinction value using the Koschmieder equation: visibility = 3.912 / extinction

Parameters:
visibilityThe visibility, in world units, above the water.
fogColorThe fog color, in normalized RGB units.
void TRITONAPI Triton::Environment::SetAmbientLight ( const Vector3 color) [inline]

Sets the color of ambient light used to light the water, as from skylight.

Parameters:
colorthe RGB color of the ambient light.
void TRITONAPI Triton::Environment::SetBelowWaterVisibility ( double  visibility,
const Vector3 fogColor 
) [inline]

Sets the simulated atmospheric visibility below the water, used to fog out the surface of the water when viewed from below.

You may use this method to fog the ocean consistently with other objects in your scene. While underwater, the application is responsible for clearing the back buffer to the fog color to match the color passed in here.

The visibility specified will be transformed into an exponential fog extinction value using the Koschmieder equation: visibility = 3.912 / extinction

Parameters:
visibilityThe visibility, in world units, below the water.
fogColorThe fog color, in normalized RGB units.
void TRITONAPI Triton::Environment::SetBreakingWavesParameters ( const BreakingWavesParameters params) [inline]

Configures the parameters used to simulate breaking waves at shorelines.

This will only have an effect if you created your Ocean object with the enableBreakingWaves parameter of Ocean::Ocean() set to true, and if you have also passed in a height map containing bathymetry information via Environment::SetHeightMap(). Please see the documentation for Triton::BreakingWavesParameters for a description of the various settings. Generally, you'll be OK just setting the direction of the waves to point toward the nearest shoreline, and leave the rest of the settings at their defaults.

See also:
GetBreakingWavesParmeters()
void TRITONAPI Triton::Environment::SetCameraMatrix ( const double *  m)

Sets the modelview matrix used for rendering the ocean; this must be called every frame prior to calling Ocean::Draw() if your camera orientation or position changes.

Deprecated* See CreateCamera(), DestroyCamera(), GetCameras()

Parameters:
mA pointer to 16 doubles representing a 4x4 modelview matrix.
void TRITONAPI Triton::Environment::SetConfigOption ( const char *  key,
const char *  value 
)

Sets a configuration setting (defaults in resources/triton.config.) Many settings are read at initialization, so call this as early as possible after initializing the Environment.

Parameters:
keyThe configuration entry name to modify
valueThe value to set this entry to.
void TRITONAPI Triton::Environment::SetCurrent ( const Vector3 direction,
double  speed 
) [inline]

Sets a simulated current in the given direction at the given speed.

The effects of this current will probably expand in future releases, but at present it only causes propeller backwash effects on ship wakes to drift. To set the direction of the waves, specify a wind value instead, or set up swell waves in the direction you want.

Parameters:
directionA unit vector pointing in the direction you want the current to run. This must be parallel to the water surface, and is specified in world space.
speedThe speed of the current in meters per second.
void TRITONAPI Triton::Environment::SetDepthMap ( TextureHandle  pDepthMap)

Optionally sets a depth texture map used for terrain / water blending at coastlines.

The preferred approach is to use SetHeightMap() instead, but sometimes height maps cannot be generated easily or quickly enough. SetDepthMap() provides a simpler alternative, especially if you already have a depth texture available as part of your engine.

To go this route, you would pass your depth texture in via SetDepthMap() every frame once it contains terrain information. Triton will de-project it into world space, and use it to compute how much water lies behind each vertex of the ocean mesh.

Be sure Triton's ocean itself has not been rendered into the depth map!

There are a few downsides to this approach, which is why we recommend using SetHeightMap() instead whenever possible:

  • The depth map cannot be used to provide accurate height queries in shallow water; as a result, you may receive height queries representing high waves in shallow harbors when using SetDepthMap() together with Triton::Ocean::GetHeight().
  • The depth map must be updated every frame, while height maps may be set once and regenerated only if the viewpoint leaves the area it covers.
  • The depths computed using the depth map will be along the line of sight from the camera to the seafloor, instead of directly underneath each ocean point. This can lead to the transparency of water at the shoreline varying with the view angle, exposing z-fighting only from certain angles. You will probably need to use higher underwater visibility settings with SetDepthMap() than you used with SetHeightMap() for smooth blending.
  • The effect is only as good as your depth buffer resolution. If you have a distant far clip plane, and/or a close near clip plane, banding may occur.

If a height map has been provided via SetHeightMap(), the depth map will not be used.

See also:
Environment::SetHeightMap()
Environment::GetDepthMap()
Parameters:
pDepthMapUnder OpenGL, this must be a GLuint indicating the ID of the GL_TEXTURE_2D returned from glGenTextures. Under DirectX9, this must be a LPDIRECT3DTEXTURE9. Under DirectX11, this must be a ID3D11ShaderResourceView pointer with an underlying ViewDimension of D3D11_SRV_DIMENSION_TEXTURE2D. This texture is expected to contain a copy of the depth buffer for this frame. Pass NULL to disable any previously set depth map.
void TRITONAPI Triton::Environment::SetDirectionalLight ( const Vector3 direction,
const Vector3 color 
)

Sets the color and direction of directional light used to light the water, as from the sun or moon.

Take care that the direction points toward the light source, and not from it - invalid coloration of the water will result if this direction is negated.

Parameters:
directionA normalized vector pointing toward the infinitely distant light source.
colorThe RGB color of the light.
void TRITONAPI Triton::Environment::SetDouglasSeaScale ( int  seaState,
float  windWaveDirection,
int  swellState,
float  swellDirection,
bool  leftHanded = false 
)

Simulate conditions as described by the Douglas sea scale (http://en.wikipedia.org/wiki/Douglas_Sea_Scale).

This will clear out any previously set WindFetches, Beaufort scale setting from SimulateSeaState(), and swells created with AddSwell(). Swell simulation is not supported with the GERSTNER water model.

Parameters:
seaStateA value from 0 to 9, 0 describing "calm and glassy" and 9 describing "phenomenal" conditions.
windWaveDirectionThe direction of wind waves in radians.
swellStateA value from 0 to 9 describing high-wavelength swell waves, 0 describing no swell and 9 describing "confused" seas.
swellDirectionThe direction of the swell waves in radians.
leftHandedIf you are using a left-handed coordinate system (for example, Y is "up" but positive Z is "North"), pass true in order to ensure your wave direction is represented correctly.
void TRITONAPI Triton::Environment::SetEnvironmentMap ( TextureHandle  cubeMap,
const Matrix3 textureMatrix = Matrix3::Identity 
) [inline]

Passes in an optional environment cube map used for rendering reflections in the water.

If unused, Triton will instead reflect a constant color based on the ambient light passed in via SetAmbientLight(). The caller is responsible for releasing or deleting this resource at shutdown.

See also:
SetEnvironmentMap()
Parameters:
cubeMapA cube map texture resource, which should be cast to a TextureHandle. Under OpenGL, this must be a GLuint indicating the ID of the GL_TEXTURE_CUBE_MAP returned from glGenTextures. Under DirectX9, this must be a LPDIRECT3DCUBETEXTURE9. Under DirectX11, this must be a ID3D11ShaderResourceView pointer with an underlying ViewDimension of D3D11_SRV_DIMENSION_TEXTURECUBE.
textureMatrixAn optional texture matrix used to transform the 3D coordinates used to access the cube map. If your cube map isn't oriented with the same cartesian axes used by your simulation, you can use this parameter to account for any differences in your cube map's coordinate system and your simulation's. When using DirectX, it's likely that you will need to use this matrix to flip the cube map upside-down due to DirectX's left-handed convention. For example, if Y is "up", pass a scaling matrix to scale Y by -1 if reflections seem to be coming from the bottom of the environment map instead of from the top.
void TRITONAPI Triton::Environment::SetHeightMap ( TextureHandle  pHeightMap,
const Matrix4 worldToTextureCoords,
void *  context = 0,
const Camera camera = 0 
)

Optionally sets a height map used by Triton for improved water / shoreline interactions.

If a height map is provided that includes bathymetry data - that is, it extends below sea level to include the surface of the sea floor - Triton can use this to obtain the depth of the water at each point. This is used for transparency effects and breaking waves at shorelines, and to prevent Triton from drawing water over the terrain.

Take care to only call this method when your height map's content changes. Triton must make a system memory copy of it for height queries, which impacts performance.

For accurate water surface height queries near the shore, DirectX9 users must provide a lockable texture (meaning it is not created in the default pool, or it is created with render target usage,) in D3DFMT_R32F format. DirectX11 users must use format DXGI_FORMAT_R32_FLOAT. OpenGL users may use any floating-point format, with the height in the red or luminance channel, such as GL_LUMINANCE32F_ARB.

If no height map is provided, you can instead use Triton::Ocean::SetDepth() to specify a uniformly sloping sea floor from the current camera location, and the depth buffer will be used to properly sort terrain against the water. Another option is to pass a depth texture every frame using Triton::Environment::SetDepthMap().

See also:
Environment::SetBreakingWavesParameters()
Environment::SetDepthMap()
Parameters:
pHeightMapUnder OpenGL, this must be a GLuint indicating the ID of the GL_TEXTURE_2D returned from glGenTextures. Under DirectX9, this must be a LPDIRECT3DTEXTURE9. Under DirectX11, this must be a ID3D11ShaderResourceView pointer with an underlying ViewDimension of D3D11_SRV_DIMENSION_TEXTURE2D. This texture is expected to contain a single 16 or 32-bit-per-component floating-point channel representing the height at each point, in world units. Pass NULL to disable any previously set height map.
worldToTextureCoordsA matrix to transform world coordinates to texture coordinates in the height map. Generally this is an orthographic matrix looking down at the height field, scaled and translated into texture coordinate space.
contextAn optional context, depending on the rendering system in question. For example, you can render in DX 11 into a command list in a deferred context and execute the command list on the immediate context at a later time.
cameraAn optional camera. Height maps are camera specific. This parameter allows a height map to be specified for the camera in question. This is useful when multiple views are at vastly different locations. In cases where views don't differ by much (e.g. left, right stereo rendering), you can get away by not specifying anything (or 0), in which case you have to ensure that the environment camera (gotten using GetCamera()) matches the main view for the split left, right views
void TRITONAPI Triton::Environment::SetHeightMapOffset ( float  _offset) [inline]

Sets a height map offset.

For non-floating point textures, a texture call in the shader will return a value in the range 0.0 - 1.0. When used in conjunction with SetHeightMapRange, the range can be transformed into something else.

void TRITONAPI Triton::Environment::SetHeightMapRange ( float  _range) [inline]

Sets a height map multiplier.

For non-floating point textures, a texture call in the shader will return a value in the range 0.0 - 1.0. When used in conjunction with SetHeightMapOffset, the range can be transformed into something else.

void TRITONAPI Triton::Environment::SetLicenseCode ( const char *  userName,
const char *  registrationCode 
)

Licensed users must call SetLicenseCode with your user name and registration code prior to using the Environment object.

Visit http://www.sundog-soft.com/ to purchase a license. If you don't call SetLicenseCode or pass invalid parameters to it, Triton will run in evaluation mode, which will terminate your application after five minutes of runtime.

Parameters:
userNameThe user name given to you with your license purchase.
registrationCodeThe registration code given to you with your license purchase.
void TRITONAPI Triton::Environment::SetPlanarReflectionMap ( TextureHandle  textureMap,
const Matrix3 textureMatrix,
float  normalDisplacementScale = 0.125f 
) [inline]

Passes in an optional planar reflection map used for rendering local reflections in the water.

Triton can use planar reflection map & environment map together. Alpha channel in planar reflection map is used to blend between planar reflection & environment map. If planar reflection is not used Triton falls back to environment map (it is the same result as if planar reflection had 0 on alpha in every texel).

See also:
SetEnvironmentMap()
Triton::Ocean::SetPlanarReflectionBlend()
Triton::Ocean::ComputeReflectionMatrices()
Parameters:
textureMapA 2D map texture resource, which should be cast to a TextureHandle. Under OpenGL, this must be a GLuint indicating the ID of the GL_TEXTURE_2D returned from glGenTextures. Under DirectX9, this must be a LPDIRECT3DTEXTURE9. Under DirectX11, this must be a ID3D11ShaderResourceView pointer with an underlying ViewDimension of D3D11_SRV_DIMENSION_TEXTURE2D.
textureMatrixA required texture matrix used to project the vector computed by triton to reflection map texture coordinates. Generally, this will be the main scene's view rotation matrix * projection matrix, multiplied by a translation of (1, 1, 1) and then by a scale of (0.5, 0.5, 0.5) to transform normalized device coordinates to texture coordinates. Triton's "Input" is a view vector perturbed by normal.xy components. Such a vector approximates wave reflection wiggle and can be used to directly access planar reflection map. See description of parameter normalDisplacementScale to learn why reflection vector cannot be used directly to access the planar reflection map. The input Vector passed to textureMatrix will be defined in world space coordinates translated to the view point. In other words this coordinate space has the same orientation as world space but its origin (point 0,0,0) is moved to the camera location. This is the same coordinate space that env map projection uses. Advanced users may see how reflection (P) variable is handled in Triton pixel (fragment) shaders.
normalDisplacementScaleA scale factor used to perturb vertex by normal.xy to get more realistic reflection from rough waves. Range of reasonable values is 0..4. Default is 0.125 Realtime bumpy surface reflection approaches are usually based on aproximation of reflection from flat surface. However, method of reflection based on planar projection has serious limitation. It assumes that view vector(and reflection vector) angle strictly corresponds to the incident point on the surface where vector was reflected. If surface is not perfectly flat and water waves are of course an example of such surface, above assumption fails and many points at the ocean surface can reflect vectors at the same direction. If such reflection was used to address a planar map texel we could see reflections of the objects at random points on the surface. To avoid such effect, usually some limits are imposed on reflected vector or reflected texture coords. Triton adopts classic approach to the above problem which works by actually using a view vector perturbed by an offset computed from normal.xy scaled by normalDisplacementScale. Since normal.xy components are never larger than unit value we can be sure that reflection vector will fit in finite margin defined by normalDisplacementScale.
void TRITONAPI Triton::Environment::SetProjectionMatrix ( const double *  p)

Sets the projection matrix used for rendering the ocean; this must be called every frame prior to calling Ocean::Draw().

Deprecated* See CreateCamera(), DestroyCamera(), GetCameras()

Parameters:
pA pointer to 16 doubles representing a 4x4 projection matrix.
void TRITONAPI Triton::Environment::SetRandomNumberGenerator ( RandomNumberGenerator rng)

Set a custom RandomNumberGenerator - derived random number generator, to override Triton's default use of stdlib's rand() function.

This may be useful for ensuring deterministic behavior across channels (although a simpler approach may be calling srand() with a consistent seed from your application.) If this method is not called, a default random number generator will be used automatically.

Parameters:
rngAn instance of a class derived from RandomNumberGenerator that will handle all random number generation within Triton.
void TRITONAPI Triton::Environment::SetSeaLevel ( double  altitudeMSL) [inline]

If you want to change the mean sea level from a height of 0 in flat-earth coordinates, or from the WGS84 ellipsoid in geocentric coordinates, you may do so here.

See also:
GetSeaLevel()
Parameters:
altitudeMSLThe offset in world units to displace mean sea level by.
void TRITONAPI Triton::Environment::SetSunIntensity ( float  intensity) [inline]

Sets the intensity of the sunlight visible at the ocean surface; used to modulate the specular highlights of the sun on the water surface.

Normally this is 1.0, but you might want to decrease it for example if the sun is obscured by clouds.

void TRITONAPI Triton::Environment::SetUserHeightCB ( GETUSERHEIGHTPROC  _userHeightCB) [inline]

Sets an optional user-provided callback to obtain height data.

void TRITONAPI Triton::Environment::SetViewport ( int  x,
int  y,
int  width,
int  height 
)

Informs Triton of the current viewport position and size.

Calling this is optional, but allows Triton to avoid querying OpenGL or DirectX for the current viewport parameters, which can cause a pipeline stall. If you call this method, you are responsible for calling it whenever the viewport changes.

Deprecated* See CreateCamera(), DestroyCamera(), GetCameras()

Parameters:
xThe x position of the current viewport origin.
yThe y position of the current viewport origin.
widthThe width of the current viewport.
heightThe height of the current viewport.
void TRITONAPI Triton::Environment::SetWaterTransparency ( float  t) [inline]

Sets an explicit transparency on the water surface.

This is in addition to any transparency resulting from shallow water.

Parameters:
tThe transparency of the water; 0 = transparent; 1 = opaque.
void TRITONAPI Triton::Environment::SetWaveBlendDepth ( double  depth) [inline]

Sets the ocean depth at which wave heights will start to become dampened, and the water will start becoming transparent, for smooth coastline blending.

Calling this is optional; if not called, the visibility distance specified in Environmnet::SetBelowWaterVisibility() will be used instead.

Parameters:
depthThe water depth, in world units, at which coastal blending begins.
void TRITONAPI Triton::Environment::SetWorldUnits ( double  worldUnits) [inline]

Sets the size of one world unit in meters.

By default, one world unit is assumed to mean one meter. If this is not the case for your coordinate system, be sure to call SetWorldUnits() immediately after instantiating your Environment class.

void TRITONAPI Triton::Environment::SetZoomLevel ( float  zoom) [inline]

If your camera is being zoomed from its typical field of view, use this method to let Triton know about the zoom factor.

This will automatically adjust things like LOD switch distances, noise blending distances, etc. to ensure the ocean looks as you would expect when zoomed in. This method does NOT modify the projection matrix you passed in with SetProjectionMatrix(), so it will NOT actually change the field of view of the ocean rendering - that's up to you when constructing the projection matrix.

Parameters:
zoomThe zoom level of the current camera, if any. 1.0 represents no zoom, 10.0 would represent 10X.
void TRITONAPI Triton::Environment::SimulateSeaState ( double  beaufortScale,
double  windDirection,
bool  leftHanded = false 
)

Simulates a specific sea state on the Beaufort scale, by clearing out any existing wind fetches passed into the Environment and setting up a new one consistent with the state specified.

Any subsequent calls to AddWindFetch() will create wind additive to that created for the given sea state, so be sure to call ClearWindFetches() if you intend to mix and match calls to SimulateSeaState() and AddWindFetch().

See http://en.wikipedia.org/wiki/Beaufort_scale for detailed descriptions of Beaufort numbers and the wave conditions they specify. At a high level,

0: Calm 1: Light air 2: Light breeze 3: Gentle breeze 4: Moderate breeze 5: Fresh breeze 6: Strong breeze 7: High wind 8: Gale 9: Storm 10: Strong Storm 11: Violent Storm 12: Hurricane

Parameters:
beaufortScaleThe Beaufort scale number specifying the desired wind and sea conditions. This may be a floating point value.
windDirectionThe direction of the wind, specified in radians.
leftHandedIf you are using a left-handed coordinate system (for example, Y is "up" but positive Z is "North"), pass true in order to ensure your wave direction is represented correctly.
const Triton::Environment::TRITON_VECTOR ( SwellDescription  ) const

Retrieves the list of swells added via AddSwell() following startup or the last call to ClearSwells().

See also:
AddSwell().

The documentation for this class was generated from the following file:
 All Classes Files Functions Variables Friends