// This code contains NVIDIA Confidential Information and is disclosed // under the Mutual Non-Disclosure Agreement. // // Notice // ALL NVIDIA DESIGN SPECIFICATIONS AND CODE ("MATERIALS") ARE PROVIDED "AS IS" NVIDIA MAKES // NO REPRESENTATIONS, WARRANTIES, EXPRESSED, IMPLIED, STATUTORY, OR OTHERWISE WITH RESPECT TO // THE MATERIALS, AND EXPRESSLY DISCLAIMS ANY IMPLIED WARRANTIES OF NONINFRINGEMENT, // MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. // // NVIDIA Corporation assumes no responsibility for the consequences of use of such // information or for any infringement of patents or other rights of third parties that may // result from its use. No license is granted by implication or otherwise under any patent // or patent rights of NVIDIA Corporation. No third party distribution is allowed unless // expressly authorized by NVIDIA. Details are subject to change without notice. // This code supersedes and replaces all information previously supplied. // NVIDIA Corporation products are not authorized for use as critical // components in life support devices or systems without express written approval of // NVIDIA Corporation. // // Copyright © 2008- 2013 NVIDIA Corporation. All rights reserved. // // NVIDIA Corporation and its licensors retain all intellectual property and proprietary // rights in and to this software and related documentation and any modifications thereto. // Any use, reproduction, disclosure or distribution of this software and related // documentation without an express license agreement from NVIDIA Corporation is // strictly prohibited. // /* * WaveWorks is a library for simulating terrain water surfaces, such as lakes and oceans, using the GPU. * The library includes shader fragments which can be used to reference the results of the simulation. * * See documentation for details */ #ifndef _GFSDK_WAVEWORKS_H #define _GFSDK_WAVEWORKS_H #include #include #include #ifdef __cplusplus extern "C" { #endif /*=========================================================================== Preamble ===========================================================================*/ #ifndef GFSDK_WAVEWORKS_LINKAGE #ifndef GFSDK_WAVEWORKS_DLL #define GFSDK_WAVEWORKS_DLL 0 #endif #if GFSDK_WAVEWORKS_DLL #define GFSDK_WAVEWORKS_LINKAGE __GFSDK_IMPORT__ #else #define GFSDK_WAVEWORKS_LINKAGE #endif #endif #define GFSDK_WAVEWORKS_DECL(ret_type) GFSDK_WAVEWORKS_LINKAGE ret_type GFSDK_WAVEWORKS_CALL_CONV /*=========================================================================== Memory management definitions ===========================================================================*/ #ifndef GFSDK_WAVEWORKS_MALLOC_HOOKS_DEFINED #define GFSDK_WAVEWORKS_MALLOC_HOOKS_DEFINED typedef void* (GFSDK_WAVEWORKS_CALL_CONV *GFSDK_WAVEWORKS_MALLOC) (size_t size); typedef void (GFSDK_WAVEWORKS_CALL_CONV *GFSDK_WAVEWORKS_FREE) (void *p); typedef void* (GFSDK_WAVEWORKS_CALL_CONV *GFSDK_WAVEWORKS_ALIGNED_MALLOC) (size_t size, size_t alignment); typedef void (GFSDK_WAVEWORKS_CALL_CONV *GFSDK_WAVEWORKS_ALIGNED_FREE) (void *p); struct GFSDK_WaveWorks_Malloc_Hooks { GFSDK_WAVEWORKS_MALLOC pMalloc; GFSDK_WAVEWORKS_FREE pFree; GFSDK_WAVEWORKS_ALIGNED_MALLOC pAlignedMalloc; GFSDK_WAVEWORKS_ALIGNED_FREE pAlignedFree; }; #endif namespace nv { class ILogger; } /*=========================================================================== Globals/init ===========================================================================*/ GFSDK_WAVEWORKS_DECL(gfsdk_cstr) GFSDK_WaveWorks_GetBuildString(); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result) GFSDK_WaveWorks_SetUserLogger(nv::ILogger* userLogger); // Use these calls to globally initialize/release on D3D device create/destroy. GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result) GFSDK_WaveWorks_InitNoGraphics(const GFSDK_WaveWorks_Malloc_Hooks* pOptionalMallocHooks, const GFSDK_WaveWorks_API_GUID& apiGUID); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result) GFSDK_WaveWorks_ReleaseNoGraphics(); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result) GFSDK_WaveWorks_InitD3D11(ID3D11Device* pD3DDevice, const GFSDK_WaveWorks_Malloc_Hooks* pOptionalMallocHooks, const GFSDK_WaveWorks_API_GUID& apiGUID); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result) GFSDK_WaveWorks_ReleaseD3D11(ID3D11Device* pD3DDevice); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result) GFSDK_WaveWorks_InitGL2(const GFSDK_WAVEWORKS_GLFunctions* pGLFuncs, const GFSDK_WaveWorks_Malloc_Hooks* pOptionalMallocHooks, const GFSDK_WaveWorks_API_GUID& apiGUID); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result) GFSDK_WaveWorks_ReleaseGL2(); // Utility function to test whether a given GL attrib is a match for a given shader input, based on name GFSDK_WAVEWORKS_DECL(gfsdk_bool) GFSDK_WaveWorks_GLAttribIsShaderInput(gfsdk_cstr attribName, const GFSDK_WaveWorks_ShaderInput_Desc& inputDesc); /*=========================================================================== Save/restore of graphics device state ===========================================================================*/ // In order to preserve D3D state across certain calls, create a save-state object, pass it to the call // and then once the call is done, use it to restore the previous D3D state GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result) GFSDK_WaveWorks_Savestate_CreateD3D11(GFSDK_WaveWorks_StatePreserveFlags PreserveFlags, ID3D11Device* pD3DDevice, GFSDK_WaveWorks_SavestateHandle* pResult); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result) GFSDK_WaveWorks_Savestate_RestoreD3D11(GFSDK_WaveWorks_SavestateHandle hSavestate, ID3D11DeviceContext* pDC); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result) GFSDK_WaveWorks_Savestate_Destroy(GFSDK_WaveWorks_SavestateHandle hSavestate); /*=========================================================================== Simulation ===========================================================================*/ struct GFSDK_WaveWorks_Simulation_Params { // Global scale factor for simulated wave amplitude gfsdk_F32 wave_amplitude; // The direction of the wind inducing the waves gfsdk_float2 wind_dir; // The speed of the wind inducing the waves. If GFSDK_WaveWorks_Simulation_Settings.UseBeaufortScale is set, this is // interpreted as a Beaufort scale value. Otherwise, it is interpreted as metres per second gfsdk_F32 wind_speed; // The degree to which waves appear to move in the wind direction (vs. standing waves), in the [0,1] range gfsdk_F32 wind_dependency; // In addition to height displacements, the simulation also applies lateral displacements. This controls the non-linearity // and therefore 'choppiness' in the resulting wave shapes. Should normally be set in the [0,1] range. gfsdk_F32 choppy_scale; // The simulation spectrum is low-pass filtered to eliminate wavelengths that could end up under-sampled, this controls // how much of the frequency range is considered 'high frequency' (i.e. small wave). gfsdk_F32 small_wave_fraction; // The global time multiplier gfsdk_F32 time_scale; // The turbulent energy representing foam and bubbles spread in water starts generating on the tips of the waves if // Jacobian of wave curvature gets higher than this threshold. The range is [0,1], the typical values are [0.2,0.4] range. gfsdk_F32 foam_generation_threshold; // The amount of turbulent energy injected in areas defined by foam_generation_threshold parameter on each simulation step. // The range is [0,1], the typical values are [0,0.1] range. gfsdk_F32 foam_generation_amount; // The speed of spatial dissipation of turbulent energy. The range is [0,1], the typical values are in [0.5,1] range. gfsdk_F32 foam_dissipation_speed; // In addition to spatial dissipation, the turbulent energy dissolves over time. This parameter sets the speed of // dissolving over time. The range is [0,1], the typical values are in [0.9,0.99] range. gfsdk_F32 foam_falloff_speed; }; struct GFSDK_WaveWorks_Simulation_Settings { // The detail level of the simulation: this drives the resolution of the FFT and also determines whether the simulation workload is done // on the GPU or CPU GFSDK_WaveWorks_Simulation_DetailLevel detail_level; // The repeat interval for the fft simulation, in world units gfsdk_F32 fft_period; // True if wind_speed in GFSDK_WaveWorks_Simulation_Params should accept Beaufort scale value // False if wind_speed in GFSDK_WaveWorks_Simulation_Params should accept meters/second gfsdk_bool use_Beaufort_scale; // Should the displacement data be read back to the CPU? gfsdk_bool readback_displacements; // If readback is enabled, displacement data can be kept alive in a FIFO for historical lookups // e.g. in order to implement predict/correct for a networked application gfsdk_U32 num_readback_FIFO_entries; // Set max aniso degree for sampling of gradient maps gfsdk_U8 aniso_level; // The threading model to use when the CPU simulation path is active // Can be set to none (meaning: simulation is performed on the calling thread, synchronously), automatic, or even // an explicitly specified thread count GFSDK_WaveWorks_Simulation_CPU_Threading_Model CPU_simulation_threading_model; // Number of GPUs used gfsdk_S32 num_GPUs; // Usage of texture arrays in GL gfsdk_bool use_texture_arrays; // Controls whether timer events will be used to gather stats on the CUDA simulation path // This can impact negatively on GPU/CPU parallelism, so it is recommended to enable this only when necessary gfsdk_bool enable_CUDA_timers; // Controls the use of graphics pipeline timers gfsdk_bool enable_gfx_timers; // Controls the use of CPU timers to gather profiling data gfsdk_bool enable_CPU_timers; }; struct GFSDK_WaveWorks_Simulation_Stats { // the times spent on particular simulation tasks, measured in milliseconds (1e-3 sec) gfsdk_F32 CPU_main_thread_wait_time; // CPU time spent by main app thread waiting for CPU FFT simulation results using CPU gfsdk_F32 CPU_threads_start_to_finish_time; // CPU time spent on CPU FFT simulation: time between 1st thread starts work and last thread finishes simulation work gfsdk_F32 CPU_threads_total_time; // CPU time spent on CPU FFT simulation: sum time spent in threads that perform simulation work gfsdk_F32 GPU_simulation_time; // GPU time spent on GPU simulation gfsdk_F32 GPU_FFT_simulation_time; // GPU simulation time spent on FFT gfsdk_F32 GPU_gfx_time; // GPU time spent on non-simulation e.g. updating gradient maps gfsdk_F32 GPU_update_time; // Total GPU time spent on simulation workloads }; struct GFSDK_WaveWorks_Simulation_GL_Pool { // Just like any other GL client, WaveWorks must use a GL texture unit each time it binds a texture // as a shader input. The app therefore needs to reserve a small pool of texture units for WaveWorks // to use when setting simulation state for GL rendering, in order to avoid clashes with the app's // own simultaneous use of texture units. All the slots in the pool must be allocated with valid // zero-based GL texture unit indices, without repeats or clashes. // // There is no particular requirement for the contents of the pool to be consistent from one invocation // to the next. The app just needs to ensure that it does not use any of the texture units in the // pool for as long as the graphics state set by WaveWorks is required to persist. // // The actual amount of reserved texture units depends on whether the library was set up to use OpenGL // Texture Arrays or not, and can be queried using GFSDK_WaveWorks_Simulation_GetTextureUnitCountGL2() enum { MaxNumReservedTextureUnits = 8 }; gfsdk_U32 Reserved_Texture_Units[MaxNumReservedTextureUnits]; }; // These functions can be used to check whether a particular graphics device supports a particular detail level, // *before* initialising the graphics device GFSDK_WAVEWORKS_DECL(gfsdk_bool) GFSDK_WaveWorks_Simulation_DetailLevelIsSupported_NoGraphics(GFSDK_WaveWorks_Simulation_DetailLevel detailLevel); GFSDK_WAVEWORKS_DECL(gfsdk_bool) GFSDK_WaveWorks_Simulation_DetailLevelIsSupported_D3D11(IDXGIAdapter* adapter, GFSDK_WaveWorks_Simulation_DetailLevel detailLevel); GFSDK_WAVEWORKS_DECL(gfsdk_bool) GFSDK_WaveWorks_Simulation_DetailLevelIsSupported_GL2(GFSDK_WaveWorks_Simulation_DetailLevel detailLevel); // Simulation lifetime management GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_CreateNoGraphics(const GFSDK_WaveWorks_Simulation_Settings& settings, const GFSDK_WaveWorks_Simulation_Params& params, GFSDK_WaveWorks_SimulationHandle* pResult); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_CreateD3D11(const GFSDK_WaveWorks_Simulation_Settings& settings, const GFSDK_WaveWorks_Simulation_Params& params, ID3D11Device* pD3DDevice, GFSDK_WaveWorks_SimulationHandle* pResult); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_CreateGL2(const GFSDK_WaveWorks_Simulation_Settings& settings, const GFSDK_WaveWorks_Simulation_Params& params, void *pGLContext, GFSDK_WaveWorks_SimulationHandle* pResult); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_Destroy(GFSDK_WaveWorks_SimulationHandle hSim); // A simulation can be 'updated' with new settings and properties - this is universally preferable to recreating // a simulation from scratch, since WaveWorks will only do as much reinitialization work as is necessary to implement // the changes in the setup. For instance, simple changes of wind speed require no reallocations and no interruptions // to the simulation and rendering pipeline GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_UpdateProperties(GFSDK_WaveWorks_SimulationHandle hSim,const GFSDK_WaveWorks_Simulation_Settings& settings, const GFSDK_WaveWorks_Simulation_Params& params); // Sets the absolute simulation time for the next kick. WaveWorks guarantees that the same displacements will be // generated for the same settings and input times, even across different platforms (e.g. to enable network- // synchronized implementations) GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_SetTime(GFSDK_WaveWorks_SimulationHandle hSim, gfsdk_F64 dAppTime); // Retrieve information about the WaveWorks shader inputs for a given platform. This information can be used to // query compiled shaders via a reflection interface to obtain register or constant buffer indices for subsequent // calls to SetRenderState GFSDK_WAVEWORKS_DECL(gfsdk_U32 ) GFSDK_WaveWorks_Simulation_GetShaderInputCountD3D11(); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_GetShaderInputDescD3D11(gfsdk_U32 inputIndex, GFSDK_WaveWorks_ShaderInput_Desc* pDesc); GFSDK_WAVEWORKS_DECL(gfsdk_U32 ) GFSDK_WaveWorks_Simulation_GetShaderInputCountGL2(); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_GetShaderInputDescGL2(gfsdk_U32 inputIndex, GFSDK_WaveWorks_ShaderInput_Desc* pDesc); // For GL only, get the number of texture units that need to be reserved for WaveWorks in GFSDK_WaveWorks_Simulation_GL_Pool GFSDK_WAVEWORKS_DECL(gfsdk_U32 ) GFSDK_WaveWorks_Simulation_GetTextureUnitCountGL2(gfsdk_bool useTextureArrays); // Set WaveWorks shader inputs ready for rendering - use GetStagingCursor() to identify the kick which produced the simulation // results that are about to be set GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_SetRenderStateD3D11(GFSDK_WaveWorks_SimulationHandle hSim, ID3D11DeviceContext* pDC, const gfsdk_float4x4& matView, const gfsdk_U32 * pShaderInputRegisterMappings, GFSDK_WaveWorks_SavestateHandle hSavestate); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_SetRenderStateGL2(GFSDK_WaveWorks_SimulationHandle hSim, const gfsdk_float4x4& matView, const gfsdk_U32 * pShaderInputRegisterMappings, const GFSDK_WaveWorks_Simulation_GL_Pool& glPool); // Retrieve an array of simulated displacements for some given array of x-y locations - use GetReadbackCursor() to identify the // kick which produced the simulation results that are about to be retrieved GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_GetDisplacements(GFSDK_WaveWorks_SimulationHandle hSim, const gfsdk_float2* inSamplePoints, gfsdk_float4* outDisplacements, gfsdk_U32 numSamples); // Get the most recent simulation statistics GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_GetStats(GFSDK_WaveWorks_SimulationHandle hSim, GFSDK_WaveWorks_Simulation_Stats& stats); // For the current simulation settings and params, calculate an estimate of the maximum displacement that can be generated by the simulation. // This can be used to conservatively inflate camera frusta for culling purposes (e.g. as a suitable value for Quadtree_SetFrustumCullMargin) GFSDK_WAVEWORKS_DECL(gfsdk_F32 ) GFSDK_WaveWorks_Simulation_GetConservativeMaxDisplacementEstimate(GFSDK_WaveWorks_SimulationHandle hSim); // Kicks off the work to update the simulation to the most recent time specified by SetTime // The top of the simulation pipeline is always run on the CPU, whereas the bottom may be run on either the CPU or GPU, depending on whether the simulation // is using the CPU or GPU path internally, and whether graphics interop is required for rendering. // If necessary, this call will block until the CPU part of the pipeline is able to accept further in-flight work. If the CPU part of the pipeline // is already completely full, this means waiting for an in-flight kick to exit the CPU pipeline (kicks are processed in FIFO order) GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_KickNoGraphics(GFSDK_WaveWorks_SimulationHandle hSim, gfsdk_U64* pKickID); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_KickD3D11(GFSDK_WaveWorks_SimulationHandle hSim, gfsdk_U64* pKickID, ID3D11DeviceContext* pDC, GFSDK_WaveWorks_SavestateHandle hSavestate); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_KickGL2(GFSDK_WaveWorks_SimulationHandle hSim, gfsdk_U64* pKickID); // The staging cursor points to the most recent kick to exit the CPU part of the simulation pipeline (and therefore the kick whose state would be set by a // subsequent call to SetRenderState) // Returns gfsdk_waveworks_result_NONE if no simulation results are staged // The staging cursor will only ever change during an API call, and is guaranteed to advance by a maximum of one kick in any one call GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_GetStagingCursor(GFSDK_WaveWorks_SimulationHandle hSim, gfsdk_U64* pKickID); // Advances the staging cursor // Use block to specify behaviour in the case where there is an in-flight kick in the CPU part of the simulation pipeline // Returns gfsdk_waveworks_result_NONE if there are no in-flight kicks in the CPU part of the simulation pipeline // Returns gfsdk_waveworks_result_WOULD_BLOCK if there are in-flight kicks in the CPU part of the pipeline, but they're not ready for staging GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_AdvanceStagingCursorNoGraphics(GFSDK_WaveWorks_SimulationHandle hSim, bool block); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_AdvanceStagingCursorD3D11(GFSDK_WaveWorks_SimulationHandle hSim, bool block, ID3D11DeviceContext* pDC, GFSDK_WaveWorks_SavestateHandle hSavestate); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_AdvanceStagingCursorGL2(GFSDK_WaveWorks_SimulationHandle hSim, bool block); // Waits until the staging cursor is ready to advance (i.e. waits until a non-blocking call to AdvanceStagingCursor would succeed) // Returns gfsdk_waveworks_result_NONE if there are no in-flight kicks in the CPU part of the simulation pipeline GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_WaitStagingCursor(GFSDK_WaveWorks_SimulationHandle hSim); // The readback cursor points to the kick whose results would be fetched by a call to GetDisplacements // Returns gfsdk_waveworks_result_NONE if no results are available for readback // The readback cursor will only ever change during an API call, and is guaranteed to advance by a maximum of one kick in any one call GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_GetReadbackCursor(GFSDK_WaveWorks_SimulationHandle hSim, gfsdk_U64* pKickID); // Advances the readback cursor // Use block to specify behaviour in the case where there is an in-flight readback // Returns gfsdk_waveworks_result_NONE if there are no readbacks in-flight beyond staging // Returns gfsdk_waveworks_result_WOULD_BLOCK if there are readbacks in-flight beyond staging, but they're not yet ready GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_AdvanceReadbackCursor(GFSDK_WaveWorks_SimulationHandle hSim, bool block); // Archives the current readback results in the readback FIFO, evicting the oldest FIFO entry if necessary // Returns gfsdk_waveworks_result_FAIL if no results are available for readback GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_ArchiveDisplacements(GFSDK_WaveWorks_SimulationHandle hSim); // Identical to GFSDK_WaveWorks_Simulation_GetDisplacements, except values are retrieved from the readback FIFO // The readback entries to use are specified using the 'coord' parameter, as follows: // - specify 0.f to read from the most recent entry in the FIFO // - specify (num_readback_FIFO_entries-1) to read from the oldest entry in the FIFO // - intervening entries may be accessed the same way, using a zero-based index // - if 'coord' is fractional, the nearest pair of entries will be lerp'd accordingly (fractional lookups are therefore more CPU-intensive) // GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Simulation_GetArchivedDisplacements(GFSDK_WaveWorks_SimulationHandle hSim, float coord, const gfsdk_float2* inSamplePoints, gfsdk_float4* outDisplacements, gfsdk_U32 numSamples); /*=========================================================================== Quad-tree geometry generator ===========================================================================*/ struct GFSDK_WaveWorks_Quadtree_Params { // Dimension of a single square patch, default to 128x128 grids gfsdk_S32 mesh_dim; // The size of the smallest permissible leaf quad in world space (i.e. the size of a lod zero patch) gfsdk_F32 min_patch_length; // The coordinates of the min corner of patch (0,0,lod). This is only necessary if AllocPatch/FreePatch // is being used to drive the quad-tree structure gfsdk_float2 patch_origin; // The lod of the root patch used for frustum culling and mesh lodding. This is only necessary if // AllocPatch/FreePatch is *not* being used to drive the quad-tree structure. This determines the furthest // coverage of the water surface from the eye point gfsdk_U32 auto_root_lod; // The upper limit of the pixel number a grid can cover in screen space gfsdk_F32 upper_grid_coverage; // The offset required to place the surface at sea level gfsdk_F32 sea_level; // The flag that defines if tessellation friendly topology and mesh must be generated gfsdk_bool use_tessellation; // The tessellation LOD scale parameter gfsdk_F32 tessellation_lod; // The degree of geomorphing to use when tessellation is not available, in the range [0,1] gfsdk_F32 geomorphing_degree; // Controls the use of CPU timers to gather profiling data gfsdk_bool enable_CPU_timers; }; struct GFSDK_WaveWorks_Quadtree_Stats { gfsdk_S32 num_patches_drawn; // CPU time spent on quadtree update, measured in milliseconds (1e-3 sec) gfsdk_F32 CPU_quadtree_update_time; }; // Quadtree lifetime management GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Quadtree_CreateD3D11(const GFSDK_WaveWorks_Quadtree_Params& params, ID3D11Device* pD3DDevice, GFSDK_WaveWorks_QuadtreeHandle* pResult); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Quadtree_CreateGL2(const GFSDK_WaveWorks_Quadtree_Params& params, unsigned int Program, GFSDK_WaveWorks_QuadtreeHandle* pResult); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Quadtree_Destroy(GFSDK_WaveWorks_QuadtreeHandle hQuadtree); // A quadtree can be udpated with new parameters. This is something of a corner-case for quadtrees, but is provided for completeness GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Quadtree_UpdateParams(GFSDK_WaveWorks_QuadtreeHandle hQuadtree, const GFSDK_WaveWorks_Quadtree_Params& params); // Retrieve information about the WaveWorks shader inputs for a given platform. This information can be used to // query compiled shaders via a reflection interface to obtain register or constant buffer indices for subsequent // calls to Draw GFSDK_WAVEWORKS_DECL(gfsdk_U32 ) GFSDK_WaveWorks_Quadtree_GetShaderInputCountD3D11(); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Quadtree_GetShaderInputDescD3D11(gfsdk_U32 inputIndex, GFSDK_WaveWorks_ShaderInput_Desc* pDesc); GFSDK_WAVEWORKS_DECL(gfsdk_U32 ) GFSDK_WaveWorks_Quadtree_GetShaderInputCountGL2(); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Quadtree_GetShaderInputDescGL2(gfsdk_U32 inputIndex, GFSDK_WaveWorks_ShaderInput_Desc* pDesc); // Explicit control over quadtree tiles, primarily for removing tiles that are known to be entirey hidden by terrain. // If AllocPatch is never called, the quadtree runs in automatic mode and is assumed to be rooted on a eye-centred // patch whose dimension is determined by GFSDK_WaveWorks_Quadtree_Params.auto_root_lod // Otherwise, WaveWorks starts frustum culling from the list of patches implied by calls to AllocPatch/FreePatch GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Quadtree_AllocPatch(GFSDK_WaveWorks_QuadtreeHandle hQuadtree, gfsdk_S32 x, gfsdk_S32 y, gfsdk_U32 lod, gfsdk_bool enabled); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Quadtree_FreePatch(GFSDK_WaveWorks_QuadtreeHandle hQuadtree, gfsdk_S32 x, gfsdk_S32 y, gfsdk_U32 lod); // Draw the water surface using the specified quadtree with the specified view and projection matrices GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Quadtree_DrawD3D11(GFSDK_WaveWorks_QuadtreeHandle hQuadtree, ID3D11DeviceContext* pDC, const gfsdk_float4x4& matView, const gfsdk_float4x4& matProj, const gfsdk_U32 * pShaderInputRegisterMappings, GFSDK_WaveWorks_SavestateHandle hSavestate); GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Quadtree_DrawGL2(GFSDK_WaveWorks_QuadtreeHandle hQuadtree, const gfsdk_float4x4& matView, const gfsdk_float4x4& matProj, const gfsdk_U32 * pShaderInputRegisterMappings); // Get the most recent quadtree rendering statistics GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Quadtree_GetStats(GFSDK_WaveWorks_QuadtreeHandle hQuadtree, GFSDK_WaveWorks_Quadtree_Stats& stats); // Patches are culled based on their undisplaced footrpint plus an additional user-supplied margin to take account // of simulated displacements. Simulation_GetConservativeMaxDisplacementEstimate() can be used for this directly // when WaveWorks is the only source of displacement on the water surface, otherwise it can be added to estimates // from any other sources as necessary (e.g. wakes, explosions etc.) GFSDK_WAVEWORKS_DECL(gfsdk_waveworks_result ) GFSDK_WaveWorks_Quadtree_SetFrustumCullMargin(GFSDK_WaveWorks_QuadtreeHandle hQuadtree, gfsdk_F32 margin); /*=========================================================================== The End ===========================================================================*/ #ifdef __cplusplus }; //extern "C" { #endif #endif // _GFSDK_WAVEWORKS_H