1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
|
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions
// are met:
// * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
// * Redistributions in binary form must reproduce the above copyright
// notice, this list of conditions and the following disclaimer in the
// documentation and/or other materials provided with the distribution.
// * Neither the name of NVIDIA CORPORATION nor the names of its
// contributors may be used to endorse or promote products derived
// from this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY
// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
// OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// Copyright (c) 2018 NVIDIA Corporation. All rights reserved.
#ifndef MODULE_PARTICLES_H
#define MODULE_PARTICLES_H
#include "Apex.h"
namespace nvidia
{
namespace apex
{
PX_PUSH_PACK_DEFAULT
class Module;
class Scene;
class EffectPackageActor;
/**
\brief Defines the API for the Particles Module
The particles module combines the features of a number of particle related APEX modules
into one location; with the exception of APEX turbulence. It also provides support for
the EffectPackage actor and asset as well as integration with the ParticleEffectAuthoring
tool.
Loading the APEX Particles module will now automatically cause the following related modules
to be instantiated.
APEX_Emitter
APEX_BasicIOS
APEX_IOFX
APEX_FieldSampler
APEX_BasicIOS
APEX_ParticleIOS
APEX_ForceField
These modules are no longer loaded as separate DLLs and instantiated individually like they were
prior to APEX 1.3. Instead simply loading the APEX_Particles DLL or calling 'instantiateModuleParticles'
will cause the other particle related modules to be loaded.
The rationale for making this change was to simplify the startup/shutdown sequence for applications
using APEX particle related effects. It also dramatically simplifies the distribution process for
developers as they now only have to deal with a single DLL rather than as many as 8 which were
required before.
The turbulence module was not folded into the unified APEX_Particles module at this time since
the source code for it is not yet made available to licensees.
It is important to note that since the APEX_Particles module does not load the Turbulence module,
the application *must* load the Turbulence module first so that it will already be registered.
*/
class ModuleParticles : public Module
{
public:
/**
\brief Return one of the particle related modules, by name, created by the particles module
*/
virtual nvidia::apex::Module* getModule(const char* moduleName) = 0;
/**
\brief Registers and adds either a single GraphicsMaterial definition or an entire array of them to the particles module.
The EffectPackage system works with a set of predefined assets which have been authored using
the ParticleEffectTool. This method adds or revises either a single asset or an array of assets.
When an EffectPackageActor is instantiated it may refer to assets which have been previously authored and
registered using this method.
\return Returns true if during the registration of this asset the contents were modified.
*/
virtual bool setEffectPackageGraphicsMaterialsDatabase(const NvParameterized::Interface* dataBase) = 0;
/**
\brief Registers and adds either a single IOS definition or an entire array of them to the particles module.
The EffectPackage system works with a set of predefined assets which have been authored using
the ParticleEffectTool. This method adds or revises either a single asset or an array of assets.
When an EffectPackageActor is instantiated it may refer to assets which have been previously authored and
registered using this method.
\return Returns true if during the registration of this asset the contents were modified.
*/
virtual bool setEffectPackageIOSDatabase(const NvParameterized::Interface* dataBase) = 0;
/**
\brief Registers and adds either a single IOFX definition or an entire array of them to the particles module.
The EffectPackage system works with a set of predefined assets which have been authored using
the ParticleEffectTool. This method adds or revises either a single asset or an array of assets.
When an EffectPackageActor is instantiated it may refer to assets which have been previously authored and
registered using this method.
\return Returns true if during the registration of this asset the contents were modified.
*/
virtual bool setEffectPackageIOFXDatabase(const NvParameterized::Interface* dataBase) = 0;
/**
\brief Registers and adds either a single Emitter definition or an entire array of them to the particles module.
The EffectPackage system works with a set of predefined assets which have been authored using
the ParticleEffectTool. This method adds or revises either a single asset or an array of assets.
When an EffectPackageActor is instantiated it may refer to assets which have been previously authored and
registered using this method.
\return Returns true if during the registration of this asset the contents were modified.
*/
virtual bool setEffectPackageEmitterDatabase(const NvParameterized::Interface* dataBase) = 0;
/**
\brief Registers and adds either a single EffectPackage definition or an entire array of them to the particles module.
The EffectPackage system works with a set of predefined assets which have been authored using
the ParticleEffectTool. This method adds or revises either a single asset or an array of assets.
When an EffectPackageActor is instantiated it may refer to assets which have been previously authored and
registered using this method.
\return Returns true if during the registration of this asset the contents were modified.
*/
virtual bool setEffectPackageDatabase(const NvParameterized::Interface* dataBase) = 0;
/**
\brief Registers and adds either a single FieldSampler definition or an entire array of them to the particles module.
The EffectPackage system works with a set of predefined assets which have been authored using
the ParticleEffectTool. This method adds or revises either a single asset or an array of assets.
When an EffectPackageActor is instantiated it may refer to assets which have been previously authored and
registered using this method.
\return Returns true if during the registration of this asset the contents were modified.
*/
virtual bool setEffectPackageFieldSamplerDatabase(const NvParameterized::Interface* dataBase) = 0;
/**
\brief Returns the NvParameterized::Interface representing the array of GraphicsMaterial assets registered by the Paricles modules
*/
virtual const NvParameterized::Interface* getEffectPackageGraphicsMaterialsDatabase() const = 0;
/**
\brief Returns the NvParameterized::Interface representing the array of IOS assets registered by the Paricles modules
*/
virtual const NvParameterized::Interface* getEffectPackageIOSDatabase() const = 0;
/**
\brief Returns the NvParameterized::Interface representing the array of IOFX assets registered by the Paricles modules
*/
virtual const NvParameterized::Interface* getEffectPackageIOFXDatabase() const = 0;
/**
\brief Returns the NvParameterized::Interface representing the array of Emitter assets registered by the Paricles modules
*/
virtual const NvParameterized::Interface* getEffectPackageEmitterDatabase() const = 0;
/**
\brief Returns the NvParameterized::Interface representing the array of EffectPackage assets registered by the Paricles modules
*/
virtual const NvParameterized::Interface* getEffectPackageDatabase() const = 0;
/**
\brief Returns the NvParameterized::Interface representing the array of FieldSampler assets registered by the Paricles modules
*/
virtual const NvParameterized::Interface* getEffectPackageFieldSamplerDatabase() const = 0;
/**
\brief This helper method will return the NvParameterized::Interface for a previously defined 'GraphicsMaterial'
This 'GraphicsMaterial' contains settings which were defined in the ParticleEffectTool. The ParticleEffectTool
will let the user define things like a source texture, a blend mode, user properties, and celled animation settings,
relative to a particular named material. The application can use all of these settings or none of them as they prefer.
These settings are used by the ParticleEffectTool to provide a prototype visualization of a sprite based particle effect.
\param [in] name : The name of the predefined graphics material
\return A pointer to the NvParameterized::Interface representing this material or NULL if not found.
*/
virtual const NvParameterized::Interface* locateGraphicsMaterialData(const char* name) const = 0;
/**
\brief This helper method will return the NvParameterized::Interface data for a predefined asset in one of the registered 'databases'
When an application gets a callback asking for an asset which was authored using the ParticleEffectTool it can use
this method to extract the current parameter data necessary to create that asset.
\param [in] resourceName : The name of the previously defined/registered asset
\param [in] nameSpace : The namespace of the asset.
\return Returns the NvParamterized::Interface pointer for that asset or NULL if not found.
*/
virtual NvParameterized::Interface* locateResource(const char* resourceName,
const char* nameSpace) = 0;
/**
\brief This is a helper method to return the names of all assets registered relative to a particular namespace.
\param [in] nameSpace : The namespace of the asset type we are searching for.
\param [in] nameCount : A reference to a counter which will contain the number of assets found matching this namespace
\param [in] variants : A reference to an array of const char pointers which will contain what reference variant each returned asset matches.
\return Returns an array of const char pointers representing the asset names matching this resource type.
*/
virtual const char** getResourceNames(const char* nameSpace, uint32_t& nameCount, const char** &variants) = 0;
/**
\brief This method globally enabled or disables the screen-space culling LOD feature for EffectPackageActors
EffectPackageActors can be culled based on whether or not they are on screen. For this to work the application
must provide a valid projection matrix, in addition to a current view matrix, into the SDK.
The projection matrix in some engines define Z positive as being in front of the screen and others Z negative.
\param [in] state : Whether to enable or disable the screen culling feature
\param [in] znegative : Whether or not Z is positive or negative when a point projected into screen-space is in front or behind the camera.
*/
virtual void setEnableScreenCulling(bool state, bool znegative) = 0;
/**
\brief Resets the emitter pool; causing all cached emitters to be released.
*/
virtual void resetEmitterPool() = 0;
/**
\brief Sets the state to determine whether or not the particles module is going to use the emitter pool.
The emitter pool is an optimization which prevents the effect system from constantly creating and the immediately releasing a great deal of APEX related
assets and resources. Take for example the case of a short lived particle effect. Without an emitter pool, triggering this effect would cause a number of
assets and rendering resources to be allocated sufficient to render and simulate this effect. But, in just a very short time, the effect lifespan is over and
all of those assets and rendering resources are deleted. Then the same effect gets fired again causing the assets and render resources to be immediately re-allocated
yet once again. With the emitter pool enabled, the original emitter is not actually released when it times out. Therefore the render resources and associated assets
stay resident in memory. When the same effect gets triggered again, it simply reuses the previously allocated emitter from the emitter pool.
*/
virtual void setUseEmitterPool(bool state) = 0;
/**
\brief Returns the current state of the emitter pool status.
*/
virtual bool getUseEmitterPool() const = 0;
/**
\brief Used by the ParticleEffectTool to initialize the default database values for the editor
*/
virtual void initializeDefaultDatabases() = 0;
protected:
virtual ~ModuleParticles() {}
};
#if !defined(_USRDLL)
/**
* If this module is distributed as a static library, the user must call this
* function before calling ApexSDK::createModule("Particles")
*/
void instantiateModuleParticles();
#endif
PX_POP_PACK
}
} // end namespace nvidia
#endif // MODULE_PARTICLES_H
|