|
Triton
Visual simulation library for ocean rendering.
|
|
Triton
Visual simulation library for ocean rendering.
|
The Ocean class allows you to configure and draw Triton's water simulation. More...
#include <Ocean.h>
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 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 () const |
| Retrieves the underlying shader object used to render the water. | |
| bool TRITONAPI | GetHeight (const Vector3 &point, const Vector3 &direction, float &height, Vector3 &normal, bool visualCorrelation=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 () const |
| 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. | |
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. | |
The Ocean class allows you to configure and draw Triton's water simulation.
| virtual Triton::Ocean::~Ocean | ( | ) | [virtual] |
Virtual destructor.
| 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.
| reflectionMatrix | A 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. |
| textureMatrix | A 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. |
| 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.
| env | A 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. |
| type | You 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. |
| enableHeightTests | Specifies 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. |
| enableBreakingWaves | Specifies 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(). |
| 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.
| time | The 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. |
| depthWrites | Whether 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. |
| drawWater | Whether 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. |
| drawParticles | Whether spray particles from breaking waves, rotor wash, impacts, etc. are drawn with this call. |
| void TRITONAPI Triton::Ocean::EnableSpray | ( | bool | enable | ) | [inline] |
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.
| wireframeOn | Set 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.
| 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().
| floorNormal | A reference to a Vector3 to retrieve the surface normal of the sea floor 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 |
||
| ) |
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.
| point | The origin of the ray to test the height against. |
| direction | The normalized direction vector of the ray. |
| height | Receives the height at the ray's intersection with the ocean, if an intersection was found. |
| normal | Receives a normalized unit vector pointing in the direction of the normal vector of the sea surface at the intersection point. |
| visualCorrelation | Set 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. |
| 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.
| point | The origin of the ray to intersect with, in world coordinates. |
| direction | The direction of the ray to intersect with, in world coordinates. |
| intersection | Receives the intersection point if an intersection exists. |
| float TRITONAPI Triton::Ocean::GetLoopingPeriod | ( | ) | const |
Retrieves the looping period of the Ocean, which define time after which wave simulation repeats.
| 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.
| const Vector3& TRITONAPI Triton::Ocean::GetRefractionColor | ( | ) | const |
Returns the color of light refracted into the water.
| ShaderHandle TRITONAPI Triton::Ocean::GetShaderObject | ( | ) | const |
Retrieves the 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 shader. Depending on the renderer you're using, you'll need to cast this to a GLhandleARB, ID3DXEffect, or ID3DX11Effect.
| 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 | ( | ) | const |
Returns whether the current camera position (from Environment::SetCameraMatrix()) is above the simulated water surface for this Ocean.
| void TRITONAPI Triton::Ocean::SetChoppiness | ( | float | chop | ) |
Set the choppiness of the waves, which controls how peaked the waves are.
| chop | The 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::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.
| depth | The 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). |
| floorNormal | The 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.
| offset | The 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.
| 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 vertex data is relative to the center of the Earth being at 0, 0, 0. They subtract off the camera position internally to preserve precision on their own. 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.
| time | The 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. |
| vertexStride | The 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. |
| positionOffset | The number of bytes from the start of each vertex to the x,y,z floating point position data. Used only in OpenGL 3.2+. |
| doublePrecisionVertices | Pass in true if your vertex data is "double" precision, or false for "float" single precision data. Only relevant in OpenGL 3.2 or newer. |
| modelMatrix | Receives an array of 16 doubles defining a 4x4 model matrix for the ocean patch. If set to NULL, an identity matrix is assumed. |
| 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().
| percent | The 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.
| refractionColor | the 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.
| 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.
| time | The current time, in seconds, used for particle animations. Optional. |
| patchBounds | A bounding box defining the bounds of your patch, used for particle animations. Optional. |
| 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.
| time | The 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. |
1.7.3
