Triton
Visual simulation library for ocean rendering.
Public Member Functions | Static Public Member Functions

Triton::Ocean Class Reference

The Ocean class allows you to configure and draw Triton's water simulation. More...

#include <Ocean.h>

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

List of all members.

Public Member Functions

virtual ~Ocean ()
 Virtual destructor.
virtual void TRITONAPI Draw (double time, bool depthWrites=true, bool drawWater=true, bool drawParticles=true)
 Draws an infinite ocean surrounding the camera (as specified in the Environment object) for the simulated conditions at the given time.
virtual bool TRITONAPI SetPatchShader (double time, int vertexStride, int positionOffset, bool doublePrecisionVertices, const double *modelMatrix=0)
 Sets the shaders and state necessary for rendering a user-provided patch of geometry as water.
virtual void TRITONAPI UnsetPatchShader (double time=0.0f, const TBoundingBox *patchBounds=0)
 Restores the graphics state prior to a previous call to Ocean::SetPatchShader().
virtual bool ReloadShaders (const TRITON_VECTOR(unsigned int)&shaders)
 OpenGL only: Reload the underlying shader programs, linking in a new list of user-supplied shader object ID's with each program.
virtual void TRITONAPI UpdateSimulation (double time)
 Updates the underlying wave simulation; calling this is optional and only necessary if you wish to perform physics updates from a pass or thread different from the rendering pass or thread.
void TRITONAPI D3D9DeviceLost ()
 DirectX9 users must call D3D9DeviceLost() in response to lost devices, prior to resetting the device.
void TRITONAPI D3D9DeviceReset ()
 DirectX9 users must call D3D9DeviceReset() in response to device resets done in response to lost devices.
float TRITONAPI GetChoppiness () const
 Retrieves the choppiness setting of the Ocean, which controls how peaked the waves are.
void TRITONAPI SetChoppiness (float chop)
 Set the choppiness of the waves, which controls how peaked the waves are.
float TRITONAPI GetLoopingPeriod () const
 Retrieves the looping period of the Ocean, which define time after which wave simulation repeats.
void TRITONAPI SetLoopingPeriod (float loopingPeriod)
 Set the looping period of the Ocean, which define time after which wave simulation repeats.
float TRITONAPI GetDepth (Triton::Vector3 &floorNormal) const
 Retrieves the simulated depth of the water in world units, and the surface normal of the sea floor, both at the current camera position.
void TRITONAPI SetDepth (float depth, const Triton::Vector3 &floorNormal)
 Sets the simulated depth of the water in world units at the camera position, and the slope of the sea floor as specified by its surface normal at the camera position.
void TRITONAPI EnableWireframe (bool wireframeOn)
 Enables or disables wireframe rendering of the ocean's mesh.
const char *TRITONAPI GetFFTName () const
 Returns a description of the FFT transform being used, if a FFT water model is active.
unsigned int TRITONAPI GetNumTriangles () const
 Returns the number of triangles rendered by the underlying projected grid.
ShaderHandle TRITONAPI GetShaderObject (Shaders shaderProgram) const
 Retrieves an underlying shader object used to render the water.
DecalHandle TRITONAPI AddDecal (TextureHandle texture, float size, const Vector3 &position)
 Applies a decal texture to the dynamic ocean surface, useful for effects involving films, debris, or foam on the water.
void TRITONAPI ScaleDecal (DecalHandle decal, float scaleWidth, float scaleDepth)
 Scales an existing decal in width and depth at runtime.
void TRITONAPI SetDecalAlpha (DecalHandle decal, float alpha)
 Sets a decal's alpha blending amount (default is 1.0.)
void TRITONAPI RemoveDecal (DecalHandle decal)
 Removes a decal texture previously applied with AddDecal().
bool TRITONAPI GetHeight (const Vector3 &point, const Vector3 &direction, float &height, Vector3 &normal, bool visualCorrelation=true, bool includeWakes=true, bool highResolution=true, bool threadSafe=true)
 Retrieves the height and normal of the ocean surface at the intersection point of the given ray.
bool TRITONAPI GetIntersection (const Vector3 &point, const Vector3 &direction, Vector3 &intersection)
 Retrieves the intersection, if any, between a ray and the ocean surface.
float TRITONAPI GetWaveHeading () const
 Retrieves the wave direction.
void TRITONAPI EnableSpray (bool enable)
 Enables or disables spray particle effects on breaking waves.
bool TRITONAPI SprayEnabled () const
 Returns if spray particle effects on breaking waves are enabled, which they are by default.
void TRITONAPI SetRefractionColor (const Vector3 &refractionColor)
 Modifies the color used for refracted light rays that go into deep water.
const Vector3 &TRITONAPI GetRefractionColor () const
 Returns the color of light refracted into the water.
void TRITONAPI SetPlanarReflectionBlend (float blendPercent)
 Sets the prominence of planar reflections on this ocean surface, if one was set using Triton::Environment::SetPlanarReflectionMap().
float TRITONAPI GetPlanarReflectionBlend () const
 Retrieves the current blend percentage for planar reflections.
bool TRITONAPI ComputeReflectionMatrices (Matrix4 &reflectionMatrix, Matrix3 &textureMatrix)
 A helper function for using planar reflections with Triton.
const Environment *TRITONAPI GetEnvironment () const
 Retrieves the environment this ocean is attached to.
bool TRITONAPI IsCameraAboveWater ()
 Returns whether the current camera position (from Environment::SetCameraMatrix()) is above the simulated water surface for this Ocean.
void TRITONAPI SetDepthOffset (float offset)
 Applies a depth offset to the water, applied in the vertex program.
float TRITONAPI GetDepthOffset () const
 Retrieves the depth offset (if any) previously set via Triton::Ocean::SetDepthOffset(), used to combat "z fighting" near coastlines.
void TRITONAPI SetDisplacementDampingDistance (double distance)
 Sets the distance at which 3D wave displacements are dampened to prevent aliasing when moving the camera.
double TRITONAPI GetDisplacementDampingDistance () const
 Retrieves the distance at which 3D wave displacements are dampened to prevent aliasing when moving the camera.
void TRITONAPI Lock ()
 Explicitly locks the mutex used to ensure thread safety between the draw, update, and height query methods.
void TRITONAPI Unlock ()
 Explicitly locks the ocean's mutex previously locked by Ocean::Lock().

Static Public Member Functions

static Ocean *TRITONAPI Create (Environment *env, WaterModelTypes type=TESSENDORF, bool enableHeightTests=false, bool enableBreakingWaves=false)
 Creates an Ocean instance tied to the given Environment, using the specified wave model.
static Ocean *TRITONAPI Create (Environment *env, const TRITON_VECTOR(unsigned int)&userShaders, WaterModelTypes type=TESSENDORF, bool enableHeightTests=false, bool enableBreakingWaves=false)
 Creates an Ocean instance tied to the given Environment, using additional user-supplied OpenGL shader objects.

Detailed Description

The Ocean class allows you to configure and draw Triton's water simulation.


Constructor & Destructor Documentation

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

Virtual destructor.


Member Function Documentation

DecalHandle TRITONAPI Triton::Ocean::AddDecal ( TextureHandle  texture,
float  size,
const Vector3 position 
)

Applies a decal texture to the dynamic ocean surface, useful for effects involving films, debris, or foam on the water.

Parameters:
textureThe texture to apply to the water surface. 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.
sizeThe size of the decal, in world units.
positionThe center position of the decal on the water surface, in world units.
Returns:
An identifier for this decal, which may be passed to RemoveDecal() to later dispose of this decal.
bool TRITONAPI Triton::Ocean::ComputeReflectionMatrices ( Matrix4 reflectionMatrix,
Matrix3 textureMatrix 
)

A helper function for using planar reflections with Triton.

This will suggest useful matrices for flipping your scene about the plane of the local water surface, and a texture matrix to transform world vectors into texture coordinates in a reflection map. You may need to transpose and/or adjust these matrices for left handed coordinates, depending on the conventions of your engine. The texture matrix returned will take the differences between OpenGL and DirectX normalized device coordinates and texture coordinates into account, however.

See also:
Triton::Environment::SetPlanarReflectionMap()
Parameters:
reflectionMatrixA matrix that will flip the scene about the local water plane, taking the current sea level into account. If you multiply this matrix into your modelview matrix after your camera transforms, all objects will be flipped about the water plane - making them suitable for rendering into a reflection texture map to later be passed in to Triton::Environment::SetPlanarReflectionMap(). You will need to change the winding order used for back face culling when this matrix is active, and you may also need to enable a user clipping plane to prevent geometry that is normally underwater from rendering into your reflection texture.
textureMatrixA matrix to transform world vectors into texture coordinate space of the reflection map texture. This matrix would be passed into Triton::Environment::SetPlanarReflectionMap(). This is equal to the product of view * projection * NDCtoTexCoords, based on the view and projection matrices last passed to Environment::SetCameraMatrix() and Environment::SetProjectionMatrix(). The matrix to transform normalized device coordinates to texture coordinates will differ depending on whether an OpenGL or DirectX renderer is being used.
Returns:
True if valid matrices were computed; will return false if the camera is below sea level, in which case you probably don't want reflections anyhow.
static Ocean* TRITONAPI Triton::Ocean::Create ( Environment env,
WaterModelTypes  type = TESSENDORF,
bool  enableHeightTests = false,
bool  enableBreakingWaves = false 
) [static]

Creates an Ocean instance tied to the given Environment, using the specified wave model.

Parameters:
envA pointer to an Environment object created previously, which contains the environmental conditions, coordinate system, camera, and rendering system used by the Ocean. The caller is responsible for deleting this object after the Ocean is deleted.
typeYou may choose between the faster TESSENDORF implementation, or the more physically accurate JONSWAP and PIERSON_MOSKOWITZ spectral models. JONSWAP is an extension of PIERSON_MOSKOWITZ that accounts for wind "fetch length," so be sure to specify realistic distances (~100km) travelled by the wind in your WindFetch objects to make the most of JONSWAP. The GERSTNER model is deprecated.
enableHeightTestsSpecifies whether the application will call Ocean::GetHeight() or not. If false, Triton may be able to keep the ocean simulation entirely on the GPU leading to better performance, but any calls to Ocean::GetHeight() may return 0. Set to true if you need to read back height information from the water surface.
enableBreakingWavesSpecifies whether shoreline effects with breaking waves are enabled. This does create additional demands on the vertex and fragment programs and should only be enabled if you're going to use them. Breaking waves require a floating-point height map containing bathymetry data to be passed in via Environment::SetHeightMap().
See also:
Environment::SetBreakingWavesParameters()
Returns:
An instance of Ocean that may be used for rendering. The caller is responsible for deleting this object when finished. NULL may be returned if the ocean could not initialize itself; in this case, enable the setting enable-debug-messages in resource/triton.config to get more details on what went wrong sent to your debugger output window. Contact support@sundog-soft.com with this output if necessary.
static Ocean* TRITONAPI Triton::Ocean::Create ( Environment env,
const TRITON_VECTOR(unsigned int)&  userShaders,
WaterModelTypes  type = TESSENDORF,
bool  enableHeightTests = false,
bool  enableBreakingWaves = false 
) [static]

Creates an Ocean instance tied to the given Environment, using additional user-supplied OpenGL shader objects.

Parameters:
envA pointer to an Environment object created previously, which contains the environmental conditions, coordinate system, camera, and rendering system used by the Ocean. The caller is responsible for deleting this object after the Ocean is deleted.
userShadersA vector of OpenGL shader objects (created via glCreateShader) that will be linked into all shader programs created by Triton. This allows you to provide your own shader functions to Triton, which your modified Triton shaders may then call into. Triton::Ocean::GetShaderObject() may be used to retrieve the linked shader programs, allowing you to set any uniforms your functions require. The caller is responsible for deleting these custom shader object after this Ocean object has been deleted.
typeYou may choose between the faster TESSENDORF implementation, or the more physically accurate JONSWAP and PIERSON_MOSKOWITZ spectral models. JONSWAP is an extension of PIERSON_MOSKOWITZ that accounts for wind "fetch length," so be sure to specify realistic distances (~100km) travelled by the wind in your WindFetch objects to make the most of JONSWAP. The GERSTNER model is deprecated.
enableHeightTestsSpecifies whether the application will call Ocean::GetHeight() or not. If false, Triton may be able to keep the ocean simulation entirely on the GPU leading to better performance, but any calls to Ocean::GetHeight() may return 0. Set to true if you need to read back height information from the water surface.
enableBreakingWavesSpecifies whether shoreline effects with breaking waves are enabled. This does create additional demands on the vertex and fragment programs and should only be enabled if you're going to use them. Breaking waves require a floating-point height map containing bathymetry data to be passed in via Environment::SetHeightMap().
See also:
Environment::SetBreakingWavesParameters()
Returns:
An instance of Ocean that may be used for rendering. The caller is responsible for deleting this object when finished. NULL may be returned if the ocean could not initialize itself; in this case, enable the setting enable-debug-messages in resource/triton.config to get more details on what went wrong sent to your debugger output window. Contact support@sundog-soft.com with this output if necessary.
void TRITONAPI Triton::Ocean::D3D9DeviceLost ( )

DirectX9 users must call D3D9DeviceLost() in response to lost devices, prior to resetting the device.

A lost device may occur when the user locks and unlocks a system or changes the monitor resolution, and must be explicitly handled under DX9. Call D3D9DeviceReset() once the device has been recreated.

void TRITONAPI Triton::Ocean::D3D9DeviceReset ( )

DirectX9 users must call D3D9DeviceReset() in response to device resets done in response to lost devices.

You must have called D3D9DeviceLost() first in response to the lost device.

virtual void TRITONAPI Triton::Ocean::Draw ( double  time,
bool  depthWrites = true,
bool  drawWater = true,
bool  drawParticles = true 
) [virtual]

Draws an infinite ocean surrounding the camera (as specified in the Environment object) for the simulated conditions at the given time.

Parameters:
timeThe simulated point in time to render, in seconds. Note that this is an absolute time which can be relative to any arbitrary point in time. It's not the delta time between frames.
depthWritesWhether the ocean will write to the depth buffer; you should probably leave this set to true, since disabling it will lead to some artifacts. One technique for integrating the ocean with terrain is to draw the ocean first with depth writes disabled, then draw the terrain on top of it, thereby avoiding any depth buffer precision issues. Be sure to remove or disable any existing ocean surfaces from your terrain database first if using this technique. Be aware that disabling depth writes will lead to artifacts at certain camera angles, since the waves won't be able to depth-sort against themselves; a better and simpler approach would be to leave depthWrites on, and then clear the depth buffer after calling Draw early in your frame.
drawWaterWhether the water surface should be drawn in this call. You may want to draw the water (which is non-transparent) separately from the spray particles (which are transparent.) This parameter, together with drawParticles, lets you choose what combination of water and particles should be drawn with this call.
drawParticlesWhether spray particles from breaking waves, rotor wash, impacts, etc. are drawn with this call.
void TRITONAPI Triton::Ocean::EnableSpray ( bool  enable)

Enables or disables spray particle effects on breaking waves.

This does incur a performance penalty, so if you need faster performance, try disabling spray effects or even disable it entirely with the fft-enable-spray config setting in resources/Triton.config.

void TRITONAPI Triton::Ocean::EnableWireframe ( bool  wireframeOn)

Enables or disables wireframe rendering of the ocean's mesh.

Parameters:
wireframeOnSet to true to render in wireframe mode, false to render normally.
float TRITONAPI Triton::Ocean::GetChoppiness ( ) const

Retrieves the choppiness setting of the Ocean, which controls how peaked the waves are.

See also:
SetChoppiness()
float TRITONAPI Triton::Ocean::GetDepth ( Triton::Vector3 floorNormal) const

Retrieves the simulated depth of the water in world units, and the surface normal of the sea floor, both at the current camera position.

Only returns the values set by SetDepth().

See also:
SetDepth()
Parameters:
floorNormalA reference to a Vector3 to retrieve the surface normal of the sea floor as set by SetDepth().
Returns:
The depth of the sea floor at the camera position, as set by SetDepth().
float TRITONAPI Triton::Ocean::GetDepthOffset ( ) const

Retrieves the depth offset (if any) previously set via Triton::Ocean::SetDepthOffset(), used to combat "z fighting" near coastlines.

double TRITONAPI Triton::Ocean::GetDisplacementDampingDistance ( ) const

Retrieves the distance at which 3D wave displacements are dampened to prevent aliasing when moving the camera.

const Environment* TRITONAPI Triton::Ocean::GetEnvironment ( ) const [inline]

Retrieves the environment this ocean is attached to.

const char* TRITONAPI Triton::Ocean::GetFFTName ( ) const

Returns a description of the FFT transform being used, if a FFT water model is active.

bool TRITONAPI Triton::Ocean::GetHeight ( const Vector3 point,
const Vector3 direction,
float &  height,
Vector3 normal,
bool  visualCorrelation = true,
bool  includeWakes = true,
bool  highResolution = true,
bool  threadSafe = true 
)

Retrieves the height and normal of the ocean surface at the intersection point of the given ray.

The results of this method are only valid if Ocean::Create() was called with the parameter enableHeightReads set to true. The height returned is relative to sea level, as specified by Triton::Environment::SetSeaLevel(). For example, the crest of a one-meter-high wave will always return a height of one meter, irrespective of the environment's sea level height. Depending on the application, you may want to add in the result of Triton::Environment::GetSeaLevel() to the height returned.

Parameters:
pointThe origin of the ray to test the height against.
directionThe normalized direction vector of the ray.
heightReceives the height at the ray's intersection with the ocean, if an intersection was found.
normalReceives a normalized unit vector pointing in the direction of the normal vector of the sea surface at the intersection point.
visualCorrelationSet to true in order to have the height returned match the visuals, which dampen height offsets with distance to avoid sampling artifacts. To return the true wave height at the given location, set to false.
includeWakesWhether this height query should include waves from ship wakes, rotor wash, and impacts in its results.
highResolutionIf true, the ocean grid points surrounding the intersection point will be sampled and interpolated. If false, the height will be based on the nearest grid point alone.
threadSafeWhether a mutex will be locked with this call to ensure thread safety with Ocean::Draw(). If you are conducting many intersection tests and are only single threaded, pass false for better performance. You may also use Ocean::Lock() and Ocean::Unlock() to manually lock and unlock the mutex surrounding many GetHeight calls.
Returns:
True if an intersection was found, false if not. If a height map was passed in using Environment::SetHeightMap(), this will return false if the intersection is over terrain.
bool TRITONAPI Triton::Ocean::GetIntersection ( const Vector3 point,
const Vector3 direction,
Vector3 intersection 
)

Retrieves the intersection, if any, between a ray and the ocean surface.

This method does NOT take wave heights into account; use Ocean::GetHeight() for that level of resolution.

Parameters:
pointThe origin of the ray to intersect with, in world coordinates.
directionThe direction of the ray to intersect with, in world coordinates.
intersectionReceives the intersection point if an intersection exists.
Returns:
True if an intersection was found, false if not. If height map data has been given using Environment::SetHeightMap(), false will also be returned if the intersection point is over terrain.
float TRITONAPI Triton::Ocean::GetLoopingPeriod ( ) const

Retrieves the looping period of the Ocean, which define time after which wave simulation repeats.

See also:
SetLoopingPeriod()
unsigned int TRITONAPI Triton::Ocean::GetNumTriangles ( ) const

Returns the number of triangles rendered by the underlying projected grid.

float TRITONAPI Triton::Ocean::GetPlanarReflectionBlend ( ) const

Retrieves the current blend percentage for planar reflections.

See also:
SetPlanarReflectionBlend().
const Vector3& TRITONAPI Triton::Ocean::GetRefractionColor ( ) const

Returns the color of light refracted into the water.

See also:
SetRefractionColor();
Returns:
The RGB value of the refraction color.
ShaderHandle TRITONAPI Triton::Ocean::GetShaderObject ( Shaders  shaderProgram) const

Retrieves an underlying shader object used to render the water.

If you make modifications to our shaders to add additional effects, you can use this in order to pass your own uniform variables into the shaders. Depending on the renderer you're using, you'll need to cast this to a GLhandleARB, ID3DXEffect, or ID3DX11Effect.

Parameters:
shaderProgramSpecifies which shader program you want to retrieve: WATER_SURFACE, SPRAY_PARTICLES, or WAKE_SPRAY_PARTICLES.
Returns:
The GLhandleARB, ID3DXEffect, or ID3DX11Effect representing the shader object, or 0 if no shader is loaded.
float TRITONAPI Triton::Ocean::GetWaveHeading ( ) const [inline]

Retrieves the wave direction.

Normally this is the same as the wind direction, but in shallow water it will align with the slope of the sea floor as specified in SetDepth().

bool TRITONAPI Triton::Ocean::IsCameraAboveWater ( )

Returns whether the current camera position (from Environment::SetCameraMatrix()) is above the simulated water surface for this Ocean.

void TRITONAPI Triton::Ocean::Lock ( )

Explicitly locks the mutex used to ensure thread safety between the draw, update, and height query methods.

For example, if you wish to conduct many calls to Ocean::GetHeight(), it is more efficient to enclose them with calls to Lock / Unlock and then pass false for Ocean::GetHeight()'s threadSafety parameter. Make sure this call is balanced by a call to Triton::Unlock() under every circumstance.

virtual bool Triton::Ocean::ReloadShaders ( const TRITON_VECTOR(unsigned int)&  shaders) [virtual]

OpenGL only: Reload the underlying shader programs, linking in a new list of user-supplied shader object ID's with each program.

void TRITONAPI Triton::Ocean::RemoveDecal ( DecalHandle  decal)

Removes a decal texture previously applied with AddDecal().

void TRITONAPI Triton::Ocean::ScaleDecal ( DecalHandle  decal,
float  scaleWidth,
float  scaleDepth 
)

Scales an existing decal in width and depth at runtime.

Parameters:
decalA decal handle retrieved from a previous call to AddDecal().
scaleWidthThe scale factor for the decal's width (ie, 0.5 = half size, 2.0 = double.)
scaleDepthThe scale factor for the decal's depth.
void TRITONAPI Triton::Ocean::SetChoppiness ( float  chop)

Set the choppiness of the waves, which controls how peaked the waves are.

See also:
GetChoppiness()
Parameters:
chopThe choppiness parameter; 0.0 yields no chop, 3.0 yields strong chop. Values that are too high may result in wave geometry folding over itself, so take care to set reasonable values.
void TRITONAPI Triton::Ocean::SetDecalAlpha ( DecalHandle  decal,
float  alpha 
)

Sets a decal's alpha blending amount (default is 1.0.)

Parameters:
decalA decal handle retrieved from a previous call to AddDecal().
alphaThe alpha value applied to the decal texture. 0 = transparent, 1.0 = opaque.
void TRITONAPI Triton::Ocean::SetDepth ( float  depth,
const Triton::Vector3 floorNormal 
)

Sets the simulated depth of the water in world units at the camera position, and the slope of the sea floor as specified by its surface normal at the camera position.

This information is used to interpolate the water depth at various positions in the scene, affecting the transparency of the water as well as the height of the waves. Avoid changing this every frame for performance reasons.

See also:
GetDepth()
Parameters:
depthThe depth of the water, in world units, at the camera position. Negative values will be clamped to zero. For open ocean, either do not call this method or set depth to a large number (like 1000).
floorNormalThe surface normal of the sea floor at the camera position. The point defined by the depth parameter under the camera position together with this normal will define a plane that approximates the position of the sea floor surrounding the current location.
void TRITONAPI Triton::Ocean::SetDepthOffset ( float  offset)

Applies a depth offset to the water, applied in the vertex program.

This can be used to mitigate "z fighting" artifacts near shorelines. By default, there is no depth offset. A value of 0.01 is generally effective.

Parameters:
offsetThe depth offset subtracted from the Z (depth) value in normalized coordinate space when rendering the ocean.
void TRITONAPI Triton::Ocean::SetDisplacementDampingDistance ( double  distance)

Sets the distance at which 3D wave displacements are dampened to prevent aliasing when moving the camera.

void TRITONAPI Triton::Ocean::SetLoopingPeriod ( float  loopingPeriod)

Set the looping period of the Ocean, which define time after which wave simulation repeats.

See also:
GetLoopingPeriod() If set to non zero, wave sumulation loops after that period. 0 is the default. FFT Wave model uses mixture of compound frequency waves. When Period value is set, these compound frequencies are constrained to be a multiply of looping frequence. Hence period may affect the wave shapes. General rule is to use highest possible period length to minimize the imapact on wave field realism. We recommend periods larger than 30 seconds.
virtual bool TRITONAPI Triton::Ocean::SetPatchShader ( double  time,
int  vertexStride,
int  positionOffset,
bool  doublePrecisionVertices,
const double *  modelMatrix = 0 
) [virtual]

Sets the shaders and state necessary for rendering a user-provided patch of geometry as water.

Use this if you don't want Triton to draw an infinite ocean using Ocean::Draw(), but only want to draw your own water patches. All that's required is the rendering of vertex data containing 3D position data following this call, and a call to Ocean::UnsetPatchShader() must be called after you've drawn your water geometry.

The geometry drawn should be flat, relative to sea level. Our shaders will displace the vertices rendered and apply all the textures and reflections to make it look like water. Remember to call Ocean::SetDepth() if you are drawing an area of shallow water and don't want this patch to look like open ocean.

For best results, ensure your depth tests are set to "less than or equal" to ensure proper sorting of Triton's waves against each other.

Note that particle-based spray effects won't be rendered when you're drawing your own geometry, all this does is shade the geometry you draw following this call to make your geometry look like water. You'll still get foam, reflections, and refractions. This method only works with TESSENDORF waves.

If you are using a WGS84 or SPHERICAL CoordinateSystem, our shaders assume that your mesh is positioned relative to the center of the Earth being at 0, 0, 0. To preserve precision, your vertices when transformed by the modelMatrix provided should be relative to the camera position. Our shaders are compiled at runtime, so you may modify them if your data is of an unusual format. Look for the shaders ending with -patch.fx or -patch.glsl inside the Resources directory; these are used only by this method.

OpenGL users should ensure that your vertex array is bound prior to calling this method; DirectX11 users should set their vertex buffer with the input assembly stage prior to calling this method.

See also:
UnsetPatchShader()
Parameters:
timeThe simulated point in time to render, in seconds. Note that this is an absolute time which can be relative to any arbitrary point in time. It's not the delta time between frames.
vertexStrideThe number of bytes between vertices in your vertex array. This is only used in OpenGL 3.2+ and DirectX11 to allow binding of your vertex array with the appropriate vertex attribute in our shaders.
positionOffsetThe number of bytes from the start of each vertex to the x,y,z floating point position data. Used only in OpenGL 3.2+.
doublePrecisionVerticesPass in true if your vertex data is "double" precision, or false for "float" single precision data. Only relevant in OpenGL 3.2 or newer.
modelMatrixReceives an array of 16 doubles defining a 4x4 model matrix for the ocean patch. If set to NULL, an identity matrix is assumed.
Returns:
True if the state was successfully set and drawing may continue.
void TRITONAPI Triton::Ocean::SetPlanarReflectionBlend ( float  blendPercent)

Sets the prominence of planar reflections on this ocean surface, if one was set using Triton::Environment::SetPlanarReflectionMap().

Parameters:
percentThe percent by which planar reflections will be blended into the reflected color of the water (0 - 1.0).
void TRITONAPI Triton::Ocean::SetRefractionColor ( const Vector3 refractionColor)

Modifies the color used for refracted light rays that go into deep water.

You can use this to modify the color of the water in areas that are not purely reflective.

Parameters:
refractionColorthe RGB color value of the deep water color; each component should be in the range 0-1.
bool TRITONAPI Triton::Ocean::SprayEnabled ( ) const [inline]

Returns if spray particle effects on breaking waves are enabled, which they are by default.

See also:
EnableSpray().
void TRITONAPI Triton::Ocean::Unlock ( )

Explicitly locks the ocean's mutex previously locked by Ocean::Lock().

virtual void TRITONAPI Triton::Ocean::UnsetPatchShader ( double  time = 0.0f,
const TBoundingBox *  patchBounds = 0 
) [virtual]

Restores the graphics state prior to a previous call to Ocean::SetPatchShader().

Every call to Ocean::SetPatchShader() must be matched with a call to Ocean::UnsetPatchShader() following the drawing of any user-defined patches of water. If you want particle-based spray effects, you may optionally pass in a timestamp and bounding box for your patch to enable these effects.

Parameters:
timeThe current time, in seconds, used for particle animations. Optional.
patchBoundsA bounding box defining the bounds of your patch, used for particle animations. Optional.
See also:
SetPatchShader()
virtual void TRITONAPI Triton::Ocean::UpdateSimulation ( double  time) [virtual]

Updates the underlying wave simulation; calling this is optional and only necessary if you wish to perform physics updates from a pass or thread different from the rendering pass or thread.

If UpdateSimulation() is not called prior to Draw() or SetPatchShader(), then Draw() or SetPatchShader() will call it automatically. A mutex is enforced between this method and the Draw(), SetPatchShader(), and GetHeight() methods.

Parameters:
timeThe simulated point in time to render, in seconds. Note that this is an absolute time which can be relative to any arbitrary point in time. It's not the delta time between frames.

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