ParticleAPI 3.0.0 Performant particle system API in C++ for interactive graphics

pSourceState.h
Go to the documentation of this file.
1/// PSourceState.h
2///
3/// Copyright 1997-2007, 2022 by David K. McAllister
4///
5/// Defines these classes: pSourceState
6
7#ifndef pSourceState_h
8#define pSourceState_h
9
10#include "Particle/pDomain.h"
11
12namespace PAPI {
13
14/// These functions set the current state needed by Source() and Vertex() actions.
15///
16/// These calls dictate the properties of particles to be created by Source() or Vertex().
17/// When particles are created within a NewActionList() / EndActionList() block, they will
18/// receive attributes from the state that was current when the action list was created (unlike OpenGL).
19/// When in immediate mode (not creating or calling an action list), particles are created
20/// with attributes from the current state.
21 class pSourceState {
22public:
23 // TODO: Make these private.
24 std::shared_ptr<pDomain> Up_;
25 std::shared_ptr<pDomain> Vel_;
26 std::shared_ptr<pDomain> RotVel_;
27 std::shared_ptr<pDomain> VertexB_;
28 std::shared_ptr<pDomain> Size_;
29 std::shared_ptr<pDomain> Color_;
30 std::shared_ptr<pDomain> Alpha_;
31 pdata_t Data_;
32 float Age_;
33 float AgeSigma_;
34 float Mass_;
35 bool vertexB_tracks_;
36
37public:
38 PINLINE pSourceState() :
39 Up_(new PDPoint(pVec(0, 1, 0))), Vel_(new PDPoint(pVec(0, 0, 0))), RotVel_(new PDPoint(pVec(0, 0, 0))), VertexB_(new PDPoint(pVec(0, 0, 0))),
40 Size_(new PDPoint(pVec(1, 1, 1))), Color_(new PDPoint(pVec(1, 1, 1))), Alpha_(new PDPoint(pVec(1, 1, 1)))
41 {
42 Data_ = 0;
43 Age_ = 0.0f;
44 AgeSigma_ = 0.0f;
45 Mass_ = 1.0f;
46 vertexB_tracks_ = true;
47 }
48
49 pSourceState& operator=(const pSourceState& src)
50 {
51 Up_ = src.Up_->copy();
52 Vel_ = src.Vel_->copy();
53 RotVel_ = src.RotVel_->copy();
54 VertexB_ = src.VertexB_->copy();
55 Size_ = src.Size_->copy();
56 Color_ = src.Color_->copy();
57 Alpha_ = src.Alpha_->copy();
58
59 Data_ = src.Data_;
60 Age_ = src.Age_;
61 AgeSigma_ = src.AgeSigma_;
62 Mass_ = src.Mass_;
63 vertexB_tracks_ = src.vertexB_tracks_;
64
65 return *this;
66 }
67
68 /// Specify the color of particles to be created.
69 ///
70 /// This call is short-hand for Color(PDPoint(color), PDPoint(pVec(alpha)).
71 ///
72 /// The default color is 1,1,1,1 (opaque white if you interpret it as RGBA).
73 PINLINE void Color(const pVec& color, const float alpha = 1.0f) { Color(PDPoint(color), PDPoint(pVec(alpha))); }
74
75 /// Specify the color of particles to be created.
76 ///
77 /// This call is short-hand for Color(PDPoint(color), PDPoint(pVec(alpha)).
78 ///
79 /// The default color is 1,1,1,1 (opaque white if you interpret it as RGBA).
80 PINLINE void Color(const float red, const float green, const float blue, const float alpha = 1.0f) { Color(pVec(red, green, blue), alpha); }
81
82 /// Specify the domain for colors and alpha value of new particles.
83 ///
84 /// Your application can interpret the color triple in any color space you choose. RGB is the most common, with colors ranging on 0.0 -> 1.0.
85 /// For example, the PDLine(pVec(1, 0, 0), pVec(1, 1, 0)) will choose points on a line between red and yellow. Points outside the 0.0 -> 1.0
86 /// range will not be clamped by the Particle System API. Some renderers may use colors on the range 0 -> 255, so the domain used to choose
87 /// the colors can be on that range. The alpha value is usually used for transparency.
88 ///
89 /// The particle color does not necessarily need to be used to represent color. It can be interpreted as an arbitrary three-vector.
90 ///
91 /// The default color is 1,1,1,1 (opaque white).
92 PINLINE void Color(const pDomain& cdom) ///< The color domain.
93 {
94 Color_ = std::shared_ptr<pDomain>(cdom.copy());
95 Alpha_ = std::shared_ptr<pDomain>(new PDPoint(pVec(1)));
96 }
97
98 /// Specify the domain for colors and alpha value of new particles.
99 ///
100 /// Your application can interpret the color triple in any color space you choose. RGB is the most common, with colors ranging on 0.0 -> 1.0.
101 /// For example, the PDLine(pVec(1, 0, 0), pVec(1, 1, 0)) will choose points on a line between red and yellow. Points outside the 0.0 -> 1.0
102 /// range will not be clamped by the Particle System API. Some renderers may use colors on the range 0 -> 255, so the domain used to choose
103 /// the colors can be on that range. The alpha value is usually used for transparency.
104 ///
105 /// The particle color does not necessarily need to be used to represent color. It can be interpreted as an arbitrary three-vector.
106 ///
107 /// The default color is 1,1,1,1 (opaque white).
108 PINLINE void Color(const pDomain& cdom, ///< The color domain.
109 const pDomain& adom ///< The X dimension of the alpha domain is used for alpha.
110 )
111 {
112 Color_ = cdom.copy();
113 Alpha_ = adom.copy();
114 }
115
116 /// Specify the user data of particles to be created.
117 ///
118 /// All new particles will have the given user data value. This value could be cast from a pointer or could be any other useful value.
119 ///
120 /// The default user data is 0.
121 PINLINE void Data(const pdata_t data) { Data_ = data; }
122
123 /// Specify the size of particles to be created.
124 ///
125 /// This call is short-hand for Size(PDPoint(size)).
126 ///
127 /// The default size is 1,1,1.
128 PINLINE void Size(const pVec& size) { Size_ = std::shared_ptr<pDomain>(new PDPoint(size)); }
129
130 /// Specify the domain for the size of particles to be created.
131 ///
132 /// All new particles will have a size chosen randomly from within the specified domain. The size values may be negative.
133 ///
134 /// The size is not mass. It does not affect any particle dynamics, including acceleration and bouncing. It is merely a triple of rendering
135 /// attributes, like color, and can be interpreted at the whim of the application programmer (that's you). In particular, the three
136 /// components do not need to be used together as three dimensions of the particle's size. For example, one could be interpreted as radius,
137 /// another as length, and another as density.
138 ///
139 /// The default size is 1,1,1.
140 PINLINE void Size(const pDomain& dom) { Size_ = dom.copy(); }
141
142 /// Specify the mass of particles to be created.
143 ///
144 /// The mass is used in the particle dynamics math, such as F=m*a. It doesn't affect size for bouncing, etc.
145 ///
146 /// The default mass is 1.
147 PINLINE void Mass(const float mass) { Mass_ = mass; }
148
149 /// Specify the initial rotational velocity vector of particles to be created.
150 PINLINE void RotVelocity(const pVec& v) { RotVel_ = std::shared_ptr<pDomain>(new PDPoint(v)); }
151
152 /// Specify the domain for the initial rotational velocity vector of particles to be created.
153 ///
154 /// For particles that will be rendered with complex shapes, like boulders, a rotation frame may be defined. The frame consists of the
155 /// velocity vector, the Up vector, and the cross product of those, which you compute yourself.
156 ///
157 /// The default rotational velocity is 0,0,0.
158 PINLINE void RotVelocity(const pDomain& dom) { RotVel_ = dom.copy(); }
159
160 /// Specify the initial age of particles to be created.
161 ///
162 /// The age parameter can be positive, zero, or negative. Giving particles different starting ages allows KillOld() to distinguish between
163 /// which to kill in interesting ways. Setting sigma to a non-zero value will give the particles an initial age with a normal distribution
164 /// with mean age and standard deviation sigma. When many particles are created at once this allows a few particles to die at each time step,
165 /// yielding a more natural effect.
166 ///
167 /// The default age is 0 and its sigma is 0.
168 PINLINE void StartingAge(const float age, ///< mean starting age of particles
169 const float sigma = 0.0f) ///< standard deviation of particle starting age
170 {
171 Age_ = age;
172 AgeSigma_ = sigma;
173 }
174
175 /// Specify the initial up vector of particles to be created.
176 ///
177 /// This call is short-hand for UpVec(PDPoint(v)).
178 ///
179 /// The default Up vector is 0,1,0.
180 PINLINE void UpVec(const pVec& up) { Up_ = std::shared_ptr<pDomain>(new PDPoint(up)); }
181
182 /// Specify the domain for the initial up vector of particles to be created.
183 ///
184 /// For particles that will be rendered with complex shapes, like boulders, a rotation frame may be defined. The frame consists of the
185 /// velocity vector, the Up vector, and the cross product of those, which you compute yourself.
186 ///
187 /// The default Up vector is 0,1,0.
188 PINLINE void UpVec(const pDomain& dom) { Up_ = dom.copy(); }
189
190 /// Specify the initial velocity vector of particles to be created.
191 ///
192 /// This call is short-hand for Velocity(PDPoint(vel)).
193 ///
194 /// The default Velocity vector is 0,0,0.
195 PINLINE void Velocity(const pVec& vel) { Vel_ = std::shared_ptr<pDomain>(new PDPoint(vel)); }
196
197 /// Specify the domain for the initial velocity vector of particles to be created.
198 ///
199 /// The default Velocity vector is 0,0,0.
200 PINLINE void Velocity(const pDomain& dom) { Vel_ = dom.copy(); }
201
202 /// Specify the initial secondary position of new particles.
203 ///
204 /// The PositionB attribute is used to store a destination position for the particle. This is designed for actions such as Restore().
205 ///
206 /// The default PositionB is 0,0,0.
207 PINLINE void VertexB(const pVec& v) { VertexB_ = std::shared_ptr<pDomain>(new PDPoint(v)); }
208
209 /// Specify the domain for the initial secondary position of new particles.
210 ///
211 /// The PositionB attribute is used to store a destination position for the particle. This is designed for actions such as Restore().
212 ///
213 /// The default PositionB is 0,0,0.
214 PINLINE void VertexB(const pDomain& dom) { VertexB_ = dom.copy(); }
215
216 /// Specify that the initial secondary position of new particles be the same as their position.
217 ///
218 /// If true, the PositionB attribute of new particles comes from their position, rather than from the VertexB domain.
219 ///
220 /// The default value of VertexBTracks is true.
221 PINLINE void VertexBTracks(const bool track_vertex = true) { vertexB_tracks_ = track_vertex; }
222
223 /// Reset all particle creation state to default values.
224 ///
225 /// All state set by the pSourceState functions will be reset.
226 PINLINE void Reset() { *this = pSourceState(); }
227};
228}; // namespace PAPI
229
230#endif
PAPI::pDomain
A representation of a region of space.
Definition: pDomain.h:55
PAPI::pDomain::copy
virtual std::shared_ptr< pDomain > copy() const =0
PAPI::pSourceState
These functions set the current state needed by Source() and Vertex() actions.
Definition: pSourceState.h:21
PAPI::pSourceState::Color_
std::shared_ptr< pDomain > Color_
Definition: pSourceState.h:29
PAPI::pSourceState::operator=
pSourceState & operator=(const pSourceState &src)
Definition: pSourceState.h:49
PAPI::pSourceState::VertexB
void VertexB(const pDomain &dom)
Specify the domain for the initial secondary position of new particles.
Definition: pSourceState.h:214
PAPI::pSourceState::RotVelocity
void RotVelocity(const pVec &v)
Specify the initial rotational velocity vector of particles to be created.
Definition: pSourceState.h:150
PAPI::pSourceState::Reset
void Reset()
Reset all particle creation state to default values.
Definition: pSourceState.h:226
PAPI::pSourceState::VertexBTracks
void VertexBTracks(const bool track_vertex=true)
Specify that the initial secondary position of new particles be the same as their position.
Definition: pSourceState.h:221
PAPI::pSourceState::Data_
pdata_t Data_
Definition: pSourceState.h:31
PAPI::pSourceState::StartingAge
void StartingAge(const float age, const float sigma=0.0f)
Specify the initial age of particles to be created.
Definition: pSourceState.h:168
PAPI::pSourceState::Velocity
void Velocity(const pVec &vel)
Specify the initial velocity vector of particles to be created.
Definition: pSourceState.h:195
PAPI::pSourceState::Color
void Color(const float red, const float green, const float blue, const float alpha=1.0f)
Specify the color of particles to be created.
Definition: pSourceState.h:80
PAPI::pSourceState::Vel_
std::shared_ptr< pDomain > Vel_
Definition: pSourceState.h:25
PAPI::pSourceState::Color
void Color(const pDomain &cdom, const pDomain &adom)
Specify the domain for colors and alpha value of new particles.
Definition: pSourceState.h:108
PAPI::pSourceState::Mass
void Mass(const float mass)
Specify the mass of particles to be created.
Definition: pSourceState.h:147
PAPI::pSourceState::RotVel_
std::shared_ptr< pDomain > RotVel_
Definition: pSourceState.h:26
PAPI::pSourceState::VertexB_
std::shared_ptr< pDomain > VertexB_
Definition: pSourceState.h:27
PAPI::pSourceState::Age_
float Age_
Definition: pSourceState.h:32
PAPI::pSourceState::Mass_
float Mass_
Definition: pSourceState.h:34
PAPI::pSourceState::Alpha_
std::shared_ptr< pDomain > Alpha_
Definition: pSourceState.h:30
PAPI::pSourceState::AgeSigma_
float AgeSigma_
Definition: pSourceState.h:33
PAPI::pSourceState::Velocity
void Velocity(const pDomain &dom)
Specify the domain for the initial velocity vector of particles to be created.
Definition: pSourceState.h:200
PAPI::pSourceState::RotVelocity
void RotVelocity(const pDomain &dom)
Specify the domain for the initial rotational velocity vector of particles to be created.
Definition: pSourceState.h:158
PAPI::pSourceState::Size
void Size(const pDomain &dom)
Specify the domain for the size of particles to be created.
Definition: pSourceState.h:140
PAPI::pSourceState::pSourceState
pSourceState()
Definition: pSourceState.h:38
PAPI::pSourceState::Color
void Color(const pVec &color, const float alpha=1.0f)
Specify the color of particles to be created.
Definition: pSourceState.h:73
PAPI::pSourceState::Size_
std::shared_ptr< pDomain > Size_
Definition: pSourceState.h:28
PAPI::pSourceState::Color
void Color(const pDomain &cdom)
Specify the domain for colors and alpha value of new particles.
Definition: pSourceState.h:92
PAPI::pSourceState::Up_
std::shared_ptr< pDomain > Up_
Definition: pSourceState.h:24
PAPI::pSourceState::Data
void Data(const pdata_t data)
Specify the user data of particles to be created.
Definition: pSourceState.h:121
PAPI::pSourceState::VertexB
void VertexB(const pVec &v)
Specify the initial secondary position of new particles.
Definition: pSourceState.h:207
PAPI::pSourceState::Size
void Size(const pVec &size)
Specify the size of particles to be created.
Definition: pSourceState.h:128
PAPI::pSourceState::UpVec
void UpVec(const pDomain &dom)
Specify the domain for the initial up vector of particles to be created.
Definition: pSourceState.h:188
PAPI::pSourceState::UpVec
void UpVec(const pVec &up)
Specify the initial up vector of particles to be created.
Definition: pSourceState.h:180
PAPI::pSourceState::vertexB_tracks_
bool vertexB_tracks_
Definition: pSourceState.h:35
PAPI::pVec
A single-precision floating point three-vector.
Definition: pVec.h:63
PAPI::pVec::pVec
pVec(float ax, float ay, float az)
Definition: pVec.h:67
PAPI::pVec::pVec
pVec(float a)
Definition: pVec.h:68
PAPI
PAPIClasses.h.
Definition: pAPIContext.h:16
PAPI::pdata_t
unsigned int pdata_t
Definition: pDeclarations.h:16
PINLINE
#define PINLINE
Definition: pVec.h:20
PAPI::PDPoint
A single point.
Definition: pDomain.h:176
PAPI::PDPoint::PDPoint
PDPoint(const pVec &p0)
Definition: pDomain.h:179