Triton
Visual simulation library for ocean rendering.
Ocean.h
Go to the documentation of this file.
1 // Copyright (c) 2011-2018 Sundog Software, LLC. All rights reserved worldwide.
2 
3 #ifndef TRITON_OCEAN_H
4 #define TRITON_OCEAN_H
5 
10 #ifdef SWIG
11 #define TRITONAPI
12 %module TritonOcean
13 %include "carrays.i"
14 %include "cpointer.i"
15 %import "Environment.h"
16 %pointer_functions(float, floatp);
17 %array_functions( double, double_array )
18 SWIG_CSBODY_PROXY(public, public, SWIGTYPE)
19 SWIG_CSBODY_TYPEWRAPPER(public, public, public, SWIGTYPE)
20 %{
21 #include "Ocean.h"
22 using namespace Triton;
23 %}
24 #endif
25 
26 #include "Environment.h"
27 #include "WakeGenerator.h"
28 #include "RotorWash.h"
29 #include "TidalStreamWake.h"
30 
31 #pragma pack(push)
32 #pragma pack(8)
33 
34 namespace Triton
35 {
36 class ProjectedGrid;
37 class WakeManager;
38 class ParticleSystemManager;
39 class SprayManager;
40 class DecalManager;
41 class Mutex;
42 class GodRays;
43 class Camera;
44 class WaterModelInitializationParams;
45 class ComplexNumber;
46 
49  TESSENDORF,
52 };
53 
55 enum Shaders {
56  WATER_SURFACE
57  , WATER_SURFACE_PATCH
58  , SPRAY_PARTICLES
59  , WAKE_SPRAY_PARTICLES
60  , GOD_RAYS
61  , WATER_DECALS
62 };
63 
66  GOOD,
67  BETTER,
68  BEST
69 };
70 
72 class TritComplex : public MemObject
73 {
74 public:
75  float real, imaginary;
76 };
77 
79 class Ocean : public MemObject
80 {
81 public:
108  static Ocean * TRITONAPI Create(Environment *env, WaterModelTypes type = JONSWAP, bool enableHeightTests = false,
109  bool enableBreakingWaves = false, OceanQuality quality = GOOD);
110 
111 #ifndef SWIG
112 
144  static Ocean * TRITONAPI Create(Environment *env, const TRITON_VECTOR(unsigned int)& userShaders, WaterModelTypes type = JONSWAP,
145  bool enableHeightTests = false, bool enableBreakingWaves = false, OceanQuality quality = GOOD);
146 #endif
147 
149  virtual ~Ocean();
150 
183  virtual void TRITONAPI Draw(double time, bool depthWrites = true, bool drawWater = true, bool drawParticles = true, void* context = 0, const Camera* camera = 0);
184 
185 
227  virtual void TRITONAPI DrawConcurrent(double time, bool depthWrites = true, bool drawWater = true, bool drawParticles = true, void* context = 0, const Camera* camera = 0);
228 
233  void TRITONAPI PostDrawConcurrent();
234 
295  virtual bool TRITONAPI SetPatchShader(double time, int vertexStride, int positionOffset, bool doublePrecisionVertices,
296  const double *modelMatrix = 0, bool decalPass = false, void* context = 0, const Camera* camera = 0);
297 
311  virtual bool TRITONAPI SetPatchMatrix(const double *modelMatrix, void* context = 0, const Camera* camera = 0);
312 
330  virtual void TRITONAPI UnsetPatchShader(double time = 0.0, const TBoundingBox* patchBounds = 0, bool decalPass = false, void* context = 0, const Camera* camera = 0);
331 
332 #ifndef SWIG
333 
339  virtual bool ReloadShaders(const TRITON_VECTOR(unsigned int)& shaders, bool reloadSurface = true,
340  bool reloadWakes = true, bool reloadSprays = true, bool reloadDecals = true, bool reloadGodRays = true);
341 #endif
342 
345  virtual bool Initialize(void* context, const Camera* camera);
346 
364  virtual void TRITONAPI UpdateSimulation(double time, const Camera* camera = 0);
365 
369  void TRITONAPI D3D9DeviceLost();
370 
373  void TRITONAPI D3D9DeviceReset();
374 
376  float TRITONAPI GetChoppiness() const;
377 
383  void TRITONAPI SetChoppiness(float chop);
384 
386  float TRITONAPI GetLoopingPeriod() const;
387 
394  void TRITONAPI SetLoopingPeriod(float loopingPeriod);
395 
405  float TRITONAPI GetDepth(Triton::Vector3& floorNormal, const Camera* camera = 0) const;
406 
424  void TRITONAPI SetDepth(float depth, const Triton::Vector3& floorNormal, const Camera* camera = 0);
425 
429  void TRITONAPI EnableWireframe(bool wireframeOn);
430 
433  const char * TRITONAPI GetFFTName() const;
434 
436  unsigned int TRITONAPI GetNumTriangles() const;
437 
468  ShaderHandle TRITONAPI GetShaderObject(Shaders shaderProgram, void* context = 0, const Camera* camera = 0) const;
469 
470  // Retrives the underlying WakeManager. For internal use only.
471  WakeManager * TRITONAPI GetWakeManager() {
472  return wakeManager;
473  }
474 
475  // Retrieves the underlying DecalManager. For internal use only.
476  DecalManager * TRITONAPI GetDecalManager() {
477  return decalManager;
478  }
479 
493  DecalHandle TRITONAPI AddDecal(TextureHandle texture, float size, const Vector3& position);
494 
500  void TRITONAPI ScaleDecal(DecalHandle decal, float scaleWidth, float scaleDepth);
501 
503  void TRITONAPI MoveDecal(DecalHandle decal, const Vector3& position);
504 
509  void TRITONAPI RotateDecal(DecalHandle decal, double radians);
510 
515  void TRITONAPI SetDecalAlpha(DecalHandle decal, float alpha);
516 
518  void TRITONAPI RemoveDecal(DecalHandle decal);
519 
559  bool TRITONAPI GetHeight(const Vector3& point, const Vector3& direction, float& height, Vector3& normal,
560  bool visualCorrelation = true, bool includeWakes = true, bool highResolution = true,
561  bool threadSafe = true, Vector3 *intersectionPoint = 0, bool autoFlip = true, const Camera* camera = 0);
562 
573  bool TRITONAPI GetIntersection(const Vector3& point, const Vector3& direction, Vector3& intersection, const Camera* camera = 0);
574 
577  float TRITONAPI GetWaveHeading() const {
578  return waveHeading;
579  }
580 
584  void TRITONAPI EnableSpray(bool enable);
585 
588  bool TRITONAPI SprayEnabled() const {
589  return sprayEnabled;
590  }
591 
596  void TRITONAPI SetRefractionColor(const Vector3& refractionColor);
597 
602  const Vector3& TRITONAPI GetRefractionColor() const;
603 
606  void TRITONAPI SetReflectionScale(float reflectionScale);
607 
609  float TRITONAPI GetReflectionScale() const;
610 
614  void TRITONAPI SetPlanarReflectionBlend(float blendPercent);
615 
617  float TRITONAPI GetPlanarReflectionBlend() const;
618 
642  bool TRITONAPI ComputeReflectionMatrices(Matrix4& reflectionMatrix, Matrix3& textureMatrix, const Camera* camera = 0);
643 
645  const Environment * TRITONAPI GetEnvironment() const {
646  return environment;
647  }
648 
651  virtual bool TRITONAPI IsCameraAboveWater(const Camera* camera = 0);
652 
657  void TRITONAPI SetDepthOffset(float offset);
658 
660  float TRITONAPI GetDepthOffset() const;
661 
663  void TRITONAPI SetDisplacementDampingDistance(double distance);
664 
666  double TRITONAPI GetDisplacementDampingDistance() const;
667 
671  void TRITONAPI EnableGodRays(bool enable) {
672  enableGodRays = enable;
673  }
674 
676  bool TRITONAPI GodRaysEnabled() const {
677  return godRays != 0 && enableGodRays;
678  }
679 
681  void TRITONAPI SetGodRaysFade(float fadeAmount);
682 
684  float TRITONAPI GetGodRaysFade() const;
685 
690  void TRITONAPI Lock();
691 
693  void TRITONAPI Unlock();
694 
698  void TRITONAPI SetQuality(OceanQuality quality);
699 
701  OceanQuality TRITONAPI GetQuality() const {
702  return quality;
703  }
704 
707  void TRITONAPI SetLinearColorSpace(bool linearOn);
708 
710  bool TRITONAPI GetLinearColorSpace() const;
711 
713  void TRITONAPI SetMaximumWavePeriod(double maxPeriod);
714 
716  double TRITONAPI GetMaximumWavePeriod() const;
717 
721  void TRITONAPI SetClipDistances(double nearClip, double farClip);
722 
725  void TRITONAPI GetClipDistances(double& nearClip, double& farClip) const;
726 
755  bool TRITONAPI OverrideFFTInputArray(const TritComplex *H0, unsigned int size);
756 
758  void TRITONAPI ClearFFTInputArray();
759 
760  // Wrappers for interpreted languages require a publicly declared default constructor. You should always use Ocean::Create, however.
761  Ocean() {}
762 
763 #ifndef SWIG
764 
765  // Used internally
766  void RegisterWakeGenerator(WakeGenerator* wg);
767  void UnregisterWakeGenerator(WakeGenerator *wg);
768  void RegisterRotorWash(RotorWash *rw);
769  void UnregisterRotorWash(RotorWash *rw);
770  void RegisterTidalStreamWake(TidalStreamWake *tsw);
771  void UnregisterTidalStreamWake(TidalStreamWake *tsw);
772  void EnvironmentDeleted();
773  void NotifySwellsChanged();
774  void SetConfused(bool);
775  void UpdateHeightMap(void* context, const Camera* camera, TextureHandle heightMap, const Matrix4& heightMapMatrix);
776  GodRays *GetGodRays() const { return godRays; }
777  const TRITON_VECTOR(unsigned int)& GetUserShaders() const {return userShaders;}
778  ProjectedGrid* GetProjectedGrid() const {return grid;}
779 
780  typedef void(*GETOCEANHEIGHTPROC)(const Vector3& point, Vector3& normal, float& height);
781 
782  void TRITONAPI SetOceanHeightCB(GETOCEANHEIGHTPROC _oceanHeightCB) {
783  oceanHeightCB = _oceanHeightCB;
784  }
785 
786  GETOCEANHEIGHTPROC TRITONAPI GetOceanHeightCB() const {
787  return oceanHeightCB;
788  }
789 
790 protected:
791  Ocean(Environment *env, WaterModelTypes type, bool enableHeightTest, bool enableBreakingWaves, OceanQuality quality);
792  Ocean(Environment *env, WaterModelTypes type, bool enableHeightTest, bool enableBreakingWaves, OceanQuality quality, const TRITON_VECTOR(unsigned int)& userShaders);
793  virtual void Initialize(const Environment *env, WaterModelTypes type, bool enableHeightTest, bool enableBreakingWaves);
794 
795  virtual bool CreateWaterSimulation();
796  void DestroyWaterSimulation();
797 
798  void SetWaveHeading(const Camera* camera);
799 
800  void DrawInternal(double time, bool depthWrites, bool drawWater, bool drawParticles, void* context, const Camera* camera, bool respectThreadSafe, bool respectAvoidStalls);
801 
802  bool isGlobal, initialized, heightReadsEnabled, enableGodRays;
803 
804  Environment *environment;
805 
806  ProjectedGrid *grid;
807 
808  WakeManager *wakeManager;
809 
810  SprayManager *sprayManager;
811 
812  DecalManager *decalManager;
813 
814  GodRays *godRays;
815 
816  float waveHeading;
817 
818  bool sprayEnabled, enableKelvin;
819 
820  double dampingDistance;
821 
822  Mutex *mutex;
823 
824  bool simulationUpdated;
825 
826  WaterModelTypes waterModelType;
827 
828  double lastUpdateTime;
829  const Camera* lastCamera;
830 
831  double timeAdjustment;
832 
833  TRITON_VECTOR(WakeGenerator *) wakeGenerators;
834 
835  TRITON_VECTOR(RotorWash *) rotorWashes;
836 
837  TRITON_VECTOR(TidalStreamWake *) tidalStreams;
838 
839  TRITON_VECTOR(unsigned int) userShaders;
840 
841  bool hasBreakingWaves, linearEnabled;
842 
843  OceanQuality quality;
844 
845  GETOCEANHEIGHTPROC oceanHeightCB;
846 
847  WaterModelInitializationParams* watermodelparams;
848 
849  double cameraMotionThreshold;
850 
851  void createAndInitializeFallbackWaterModel(void);
852 #endif //SWIG
853 };
854 }
855 
856 #pragma pack(pop)
857 
858 #endif
An static wake pointing in a given direction at a fixed location, for example from a buoy or bridge p...
Definition: TidalStreamWake.h:34
bool TRITONAPI GodRaysEnabled() const
Returns whether the underwater crepuscular rays effect is enabled.
Definition: Ocean.h:676
double TRITONAPI GetDisplacementDampingDistance() const
Retrieves the distance at which 3D wave displacements are dampened to prevent aliasing when moving th...
An object that generates rotor wash wave and spray effects.
const Vector3 &TRITONAPI GetRefractionColor() const
Returns the color of light refracted into the water.
void TRITONAPI SetChoppiness(float chop)
Set the choppiness of the waves, which controls how peaked the waves are.
virtual void TRITONAPI DrawConcurrent(double time, bool depthWrites=true, bool drawWater=true, bool drawParticles=true, void *context=0, const Camera *camera=0)
Draws an infinite ocean surrounding the camera (as specified in the Environment object) for the simul...
virtual ~Ocean()
Virtual destructor.
An object that generates a static wake wave in a given direction, such as that generated by a buoy in...
This base class for all Triton objects intercepts the new and delete operators, routing them through ...
Definition: MemAlloc.h:70
void TRITONAPI RemoveDecal(DecalHandle decal)
Removes a decal texture previously applied with AddDecal().
OceanQuality TRITONAPI GetQuality() const
Retrieve the current simulation quality setting, either set by Ocean::SetQuality() or the default val...
Definition: Ocean.h:701
void TRITONAPI SetDepth(float depth, const Triton::Vector3 &floorNormal, const Camera *camera=0)
Sets the simulated depth of the water in world units at the camera position, and the slope of the sea...
Triton's public interface for specifying the environmental conditions and camera properties.
Definition: Environment.h:213
bool TRITONAPI OverrideFFTInputArray(const TritComplex *H0, unsigned int size)
Explicitly overrides the H0 input array of wave amplitudes for given wavelengths and directions...
A RotorWash object will generate spray and circular waves on the ocean surface in the direction it is...
Definition: RotorWash.h:36
bool TRITONAPI SprayEnabled() const
Returns if spray particle effects on breaking waves are enabled, which they are by default...
Definition: Ocean.h:588
void TRITONAPI SetLoopingPeriod(float loopingPeriod)
Set the looping period of the Ocean, which define time after which wave simulation repeats...
virtual bool TRITONAPI SetPatchShader(double time, int vertexStride, int positionOffset, bool doublePrecisionVertices, const double *modelMatrix=0, bool decalPass=false, void *context=0, const Camera *camera=0)
Sets the shaders and state necessary for rendering a user-provided patch of geometry as water...
unsigned int TRITONAPI GetNumTriangles() const
Returns the number of triangles rendered by the underlying projected grid.
double TRITONAPI GetMaximumWavePeriod() const
Retrieves the maximum wave period enforced regardless of wind conditions requested.
static Ocean *TRITONAPI Create(Environment *env, WaterModelTypes type=JONSWAP, bool enableHeightTests=false, bool enableBreakingWaves=false, OceanQuality quality=GOOD)
Creates an Ocean instance tied to the given Environment, using the specified wave model...
float TRITONAPI GetGodRaysFade() const
Returns the god ray fading amount set in Ocean::FadeGodRays().
void TRITONAPI SetGodRaysFade(float fadeAmount)
Fades out the underwater crepuscular rays effect by the specified amount (0 = no fading, 1 = completely faded).
void TRITONAPI SetRefractionColor(const Vector3 &refractionColor)
Modifies the color used for refracted light rays that go into deep water.
void TRITONAPI SetPlanarReflectionBlend(float blendPercent)
Sets the prominence of planar reflections on this ocean surface, if one was set using Triton::Environ...
void TRITONAPI ClearFFTInputArray()
Stops using an overridden FFT wave input array as defined in Environment::OverrideFFTInputArray.
Definition: Camera.h:23
float TRITONAPI GetWaveHeading() const
Retrieves the wave direction.
Definition: Ocean.h:577
An object that generates a ship Kelvin wake as it moves.
OceanQuality
Enumerates the ocean quality settings used in Ocean::SetQuality()
Definition: Ocean.h:65
float TRITONAPI GetChoppiness() const
Retrieves the choppiness setting of the Ocean, which controls how peaked the waves are...
virtual void TRITONAPI UpdateSimulation(double time, const Camera *camera=0)
Updates the underlying wave simulation; calling this is optional and only necessary if you wish to pe...
virtual bool ReloadShaders(const TRITON_VECTOR(unsigned int)&shaders, bool reloadSurface=true, bool reloadWakes=true, bool reloadSprays=true, bool reloadDecals=true, bool reloadGodRays=true)
OpenGL only: Reload the underlying shader programs, linking in a new list of user-supplied shader obj...
A WakeGenerator represents an object on the water that generates a wake as it moves, such as a ship.
Definition: WakeGenerator.h:131
virtual void TRITONAPI UnsetPatchShader(double time=0.0, const TBoundingBox *patchBounds=0, bool decalPass=false, void *context=0, const Camera *camera=0)
Restores the graphics state prior to a previous call to Ocean::SetPatchShader().
A 3D double-precision Vector class and its operations.
Definition: Vector3.h:35
int ShaderHandle
A renderer-agnostic handle for a shader.
Definition: TritonCommon.h:37
void TRITONAPI SetMaximumWavePeriod(double maxPeriod)
Sets a maximum wave period in the simulated wave spectra, irrespective of the wind conditions request...
The Ocean class allows you to configure and draw Triton's water simulation.
Definition: Ocean.h:79
Shaders
Enumerates the different shader programs used internally by Triton.
Definition: Ocean.h:55
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, Vector3 *intersectionPoint=0, bool autoFlip=true, const Camera *camera=0)
Retrieves the height and normal of the ocean surface at the intersection point of the given ray...
Triton's public interface for specifying the camera properties.
Definition: Camera.h:36
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 SetDepthOffset(float offset)
Applies a depth offset to the water, applied in the vertex program.
const Environment *TRITONAPI GetEnvironment() const
Retrieves the environment this ocean is attached to.
Definition: Ocean.h:645
void * DecalHandle
A renderer-agnostic handle for a decal.
Definition: TritonCommon.h:57
Tessendorf's ocean wave model with the Phillips wave spectrum, using fast Fourier transforms to simul...
Definition: Ocean.h:50
float TRITONAPI GetDepth(Triton::Vector3 &floorNormal, const Camera *camera=0) const
Retrieves the simulated depth of the water in world units, and the surface normal of the sea floor...
WaterModelTypes
Enumerates the different water models available for simluating ocean waves.
Definition: Ocean.h:48
void TRITONAPI Unlock()
Explicitly locks the ocean's mutex previously locked by Ocean::Lock().
void TRITONAPI SetDisplacementDampingDistance(double distance)
Sets the distance at which 3D wave displacements are dampened to prevent aliasing when moving the cam...
void TRITONAPI EnableWireframe(bool wireframeOn)
Enables or disables wireframe rendering of the ocean's mesh.
void TRITONAPI MoveDecal(DecalHandle decal, const Vector3 &position)
Moves an existing decal to the given location.
bool TRITONAPI GetIntersection(const Vector3 &point, const Vector3 &direction, Vector3 &intersection, const Camera *camera=0)
Retrieves the intersection, if any, between a ray and the ocean surface.
void TRITONAPI GetClipDistances(double &nearClip, double &farClip) const
Retrieves Triton's current assumptions about the projected Z values at your near and far clipping pla...
float TRITONAPI GetLoopingPeriod() const
Retrieves the looping period of the Ocean, which define time after which wave simulation repeats...
const char *TRITONAPI GetFFTName() const
Returns a description of the FFT transform being used, if a FFT water model is active.
An FFT-powered Pierson-Moskowitz wave spectrum.
Definition: Ocean.h:51
A simple 3x3 matrix class and its operations.
Definition: Matrix3.h:29
void TRITONAPI PostDrawConcurrent()
Method that must be called from the main thread after all Ocean::DrawConcurrent calls have completed ...
virtual bool Initialize(void *context, const Camera *camera)
In OpenGL, this must be called with each set of context and camera that you intend to render with See...
void TRITONAPI SetLinearColorSpace(bool linearOn)
Sets use of linear color space, in which the ocean color will be raised to the power of 2...
void TRITONAPI EnableGodRays(bool enable)
Turns the underwater crepuscular rays effect on or off.
Definition: Ocean.h:671
bool TRITONAPI ComputeReflectionMatrices(Matrix4 &reflectionMatrix, Matrix3 &textureMatrix, const Camera *camera=0)
A helper function for using planar reflections with Triton.
void TRITONAPI RotateDecal(DecalHandle decal, double radians)
Rotates an existing decal by the given amount in radians.
float TRITONAPI GetReflectionScale() const
Retrieves any reflection scale set previously by SetReflectionScale(), or 1.0 otherwise.
int TextureHandle
A renderer-agnostic handle for a texture.
Definition: TritonCommon.h:55
virtual bool TRITONAPI SetPatchMatrix(const double *modelMatrix, void *context=0, const Camera *camera=0)
If you are drawing many of your own water meshes using SetPatchShader() at once, it will be much fast...
bool TRITONAPI GetLinearColorSpace() const
Gets whether linear color space rendering is enabled via SetLinearColorSpace().
The public interface for setting Triton's environmental parameters.
Triton's Ocean model interface.
virtual bool TRITONAPI IsCameraAboveWater(const Camera *camera=0)
Returns whether the current camera position (from Environment::SetCameraMatrix()) is above the simula...
void TRITONAPI EnableSpray(bool enable)
Enables or disables spray particle effects on breaking waves.
virtual void TRITONAPI Draw(double time, bool depthWrites=true, bool drawWater=true, bool drawParticles=true, void *context=0, const Camera *camera=0)
Draws an infinite ocean surrounding the camera (as specified in the Environment object) for the simul...
void TRITONAPI SetReflectionScale(float reflectionScale)
Scales the intensity of reflections on the water (environment, planar, and light reflections combined...
void TRITONAPI Lock()
Explicitly locks the mutex used to ensure thread safety between the draw, update, and height query me...
An implementation of a 4x4 matrix and some simple operations on it.
Definition: Matrix4.h:29
void TRITONAPI D3D9DeviceReset()
DirectX9 users must call D3D9DeviceReset() in response to device resets done in response to lost devi...
ShaderHandle TRITONAPI GetShaderObject(Shaders shaderProgram, void *context=0, const Camera *camera=0) 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...
void TRITONAPI SetQuality(OceanQuality quality)
Set a quality setting (GOOD, BETTER, or BEST.) Higher quality will result in finer wave resolution...
void TRITONAPI SetDecalAlpha(DecalHandle decal, float alpha)
Sets a decal's alpha blending amount (default is 1.0.)
void TRITONAPI ScaleDecal(DecalHandle decal, float scaleWidth, float scaleDepth)
Scales an existing decal in width and depth at runtime.
void TRITONAPI SetClipDistances(double nearClip, double farClip)
Tells Triton about the projected Z values at your near and far clipping planes.
A structure describing a complex number, for use in Environment::OverrideFFTInputArray.
Definition: Ocean.h:72
void TRITONAPI D3D9DeviceLost()
DirectX9 users must call D3D9DeviceLost() in response to lost devices, prior to resetting the device...
float TRITONAPI GetPlanarReflectionBlend() const
Retrieves the current blend percentage for planar reflections.