-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
169 lines (167 loc) · 19.7 KB
/
index.html
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
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.3"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>ParticleAPI: The Particle System API</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr id="projectrow">
<td id="projectalign">
<div id="projectname">ParticleAPI<span id="projectnumber"> 3.0.0</span>
</div>
<div id="projectbrief">Performant particle system API in C++ for interactive graphics</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.3 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search",'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div><div class="header">
<div class="headertitle"><div class="title">The Particle System API </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="intro"></a>
Introduction</h1>
<p >The Particle System API (Application Programmer Interface) allows C++ programs to simulate the dynamics of particles. It is intended for special effects in interactive and non-interactive graphics applications, not for scientific simulation, although principles of Newtonian physics have been used to implement the particle dynamics where applicable.</p>
<p >The API consists of four sets of functions:</p><ul>
<li><b>Particle Group Calls</b> - A particle group is a system of particles that are all acted on together. It can be considered a dynamic geometric object. From the point of view of the graphics system, a particle group is often treated as just another model to be drawn. These calls create and destroy particle groups, etc. Details are in <a class="el" href="class_p_a_p_i_1_1_p_context_particle_group__t.html" title="This class contains the API calls that operate on particle groups.">PAPI::PContextParticleGroup_t</a>.</li>
<li><b>Source State Calls</b> - As in OpenGL, some calls actually do something and some calls modify the behavior of the subsequent calls that do something. The source state setting calls set the attributes of particles that will be created with the <a class="el" href="class_p_a_p_i_1_1_p_context_actions__t.html#a1c29fe77db016b32899474911e9c6c60" title="Add particles with positions in the specified domain.">PAPI::PContextActions_t::Source</a> or <a class="el" href="class_p_a_p_i_1_1_p_context_actions__t.html#a306e8cc660a2bfe39c1f53358cf7230c" title="Add a single particle at the specified location.">PAPI::PContextActions_t::Vertex</a> calls. The source state calls are in <a class="el" href="class_p_a_p_i_1_1p_source_state.html" title="These functions set the current state needed by Source() and Vertex() actions.">PAPI::pSourceState</a>.</li>
<li><b>Actions</b> - These implement the particle dynamics. Bounce and Gravity are examples of actions. The Actions are in the class <a class="el" href="class_p_a_p_i_1_1_p_context_actions__t.html" title="This class contains the Action API.">PAPI::PContextActions_t</a>.</li>
<li><b>Action List Calls</b> - These create and operate on lists of actions. These are not needed by the new <a class="el" href="class_p_a_p_i_1_1_p_context_actions__t.html#inline_actions">Inline Actions</a> API.</li>
</ul>
<p >Following are several basic concepts central to the Particle System API.</p>
<h2><a class="anchor" id="particles"></a>
Particles</h2>
<p >For the purposes of the Particle System API, a particle is not just a very tiny speck. Particles can be drawn as anything - water droplets, birds, tumbleweeds, boulders, etc.. The Particle System API is generally useful for operating on many similar objects that all move and change according to the same basic rules, no matter what the objects and rules are.</p>
<p >A particle in the abstract sense used by the API is merely an entity with a small set of attributes such as position and color that ultimately dictate the particle's behavior and appearance. Particles are declared in <a class="el" href="p_particle_8h.html">pParticle.h</a> or <a class="el" href="struct_p_a_p_i_1_1_particle__t.html">PAPI::Particle_t</a>. Here are the particle attributes:</p>
<table border="1">
<tr>
<td>Position </td><td>location of the particle center </td><td>3 floats</td></tr>
<tr>
<td>Color </td><td>color (in any color space) </td><td>3 floats </td></tr>
<tr>
<td>Velocity </td><td>velocity vector (direction and speed) </td><td>3 floats </td></tr>
<tr>
<td>Up </td><td>up vector (together with velocity vector, yields an orientation frame) </td><td>3 floats </td></tr>
<tr>
<td>Rotational Velocity </td><td>direction of rotation of the up vector </td><td>3 floats </td></tr>
<tr>
<td>Size </td><td>how large the particle is for rendering (doesn't affect particle dynamics or collision) </td><td>3 floats </td></tr>
<tr>
<td>PositionB </td><td>initial or target position for returning to (see Restore()) </td><td>3 floats </td></tr>
<tr>
<td>UpB </td><td>initial or target orientation for returning to (see Restore()) </td><td>3 floats </td></tr>
<tr>
<td>VelocityB </td><td>can be used as velocity from last frame for computing a side vector </td><td>3 floats </td></tr>
<tr>
<td>Mass </td><td>how large the particle is for dynamics computations (doesn't affect collision location) </td><td>1 float </td></tr>
<tr>
<td>Age </td><td>time since the particle's creation </td><td>1 float </td></tr>
<tr>
<td>Alpha </td><td>opacity, or a fourth color channel </td><td>1 float </td></tr>
<tr>
<td>Tmp </td><td>for a sorting key or for tagging particles to kill by setting to P_MAXFLOAT </td><td>1 float </td></tr>
<tr>
<td>Data </td><td>user data to be passed back to user callbacks </td><td>1 uint32 </td></tr>
</table>
<h2><a class="anchor" id="actions"></a>
Actions</h2>
<p >Actions are the core of the Particle System API. They are the functions in the API that directly manipulate particles in particle groups. They perform effects such as gravity, explosions, bouncing, etc. to all particles in the current particle group. Actions modify the position, color, velocity, size, age, and other attributes of particles. A program typically creates and initializes one or more particle groups, then during each frame it calls particle actions to animate the particles then gets the particle data and draws the group of particles onto the screen.</p>
<p >All actions apply to the current particle group, as set by CurrentGroup. Some actions will add particles to or delete them from the particle group, and others will modify the particles in other ways. Typically, a series of actions will be applied to each particle group once (or more) per rendered frame.</p>
<p >The Particle System API uses a discrete time approximation to all actions. The amount of effect of an action call depends on the time step size, dt, as set by <a class="el" href="class_p_a_p_i_1_1_p_context_action_list__t.html#a0330f623cbd0686e4fd84abe6f2a3828">PAPI::PContextActionList_t::TimeStep</a>. A smaller time step improves simulation quality.</p>
<p >Some functions have parameters with a default value of P_EPS. P_EPS is a very small floating point constant that is most often used as the default value of the epsilon parameter to actions whose influence on a particle is relative to the inverse square of its distance from something. If that distance is very small, the amount of influence approaches infinity. Since all actions are computed using Euler's method, this can cause unsatisfying results in which particles are accelerated way too much. So this epsilon parameter is added to the distance before taking its inverse square, thus keeping the acceleration within reasonable limits. By varying epsilon, you specify what is reasonable. Larger epsilon make particles accelerate less.</p>
<p >The Actions are in the class <a class="el" href="class_p_a_p_i_1_1_p_context_actions__t.html" title="This class contains the Action API.">PAPI::PContextActions_t</a>.</p>
<h2><a class="anchor" id="domains"></a>
Domains</h2>
<p >A Domain is a representation of a region of 3D space. For example, the Source action uses a domain to describe the volume in which a particle's random initial position will be. The Avoid(), Sink() and Bounce() actions use domains to describe a volume in space for particles to steer to avoid, die when they enter, or to bounce off, respectively. Domains are used as parameters to many functions within the API.</p>
<p >See <a class="el" href="class_p_a_p_i_1_1p_domain.html" title="A representation of a region of space.">PAPI::pDomain</a> and <a class="el" href="p_domain_8h.html">pDomain.h</a> for more.</p>
<h2><a class="anchor" id="sourcestate"></a>
Source State Setting Calls</h2>
<p >These calls dictate the properties of particles to be created by Source or Vertex. When particles are created within a NewActionList / EndActionList block, they will receive attributes from the state that was current when the action list was created. When in immediate mode (not creating or calling an action list), particles are created with attributes from the current state.</p>
<p >See the Source State Setting Calls in the class <a class="el" href="class_p_a_p_i_1_1p_source_state.html" title="These functions set the current state needed by Source() and Vertex() actions.">PAPI::pSourceState</a>.</p>
<h2><a class="anchor" id="pgroup"></a>
Particle Group Calls</h2>
<p >A particle group is first created using <a class="el" href="class_p_a_p_i_1_1_p_context_particle_group__t.html#ad6b48bdc6e998672ff0df1c4f581230b" title="Create particle groups, each with a maximum of max_particles.">PAPI::PContextParticleGroup_t::GenParticleGroups</a>, which will create a sequentially-numbered set of particle groups and return the identifying number of the first generated particle group. You specify which group is current using <a class="el" href="class_p_a_p_i_1_1_p_context_particle_group__t.html#af1ddcf82756a87ded68e545cad3e8d90" title="Change which group is current.">PAPI::PContextParticleGroup_t::CurrentGroup</a>. Unless otherwise stated, all other commands operate on the current particle group. The maximum number of particles in the group is specified using <a class="el" href="class_p_a_p_i_1_1_p_context_particle_group__t.html#ac89a60f3740531bba39533bf75d3e990" title="Change the maximum number of particles in the current group.">PAPI::PContextParticleGroup_t::SetMaxParticles</a>. The particle group is then acted upon using the Actions (<a class="el" href="class_p_a_p_i_1_1_p_context_actions__t.html" title="This class contains the Action API.">PAPI::PContextActions_t</a>).</p>
<p >After the actions have been applied, the particles are rendered. This is done at the same stage of the application's execution as drawing other geometry. To draw a particle group in a graphics API, the application calls <a class="el" href="class_p_a_p_i_1_1_p_context_particle_group__t.html#af589e7bdf0c3280bce5442782563ae6b" title="Copy particles from the current group to application memory.">PAPI::PContextParticleGroup_t::GetParticles</a> or <a class="el" href="class_p_a_p_i_1_1_p_context_particle_group__t.html#a75cdf009111297f02b803ac08d0a4213" title="Return a pointer to particle data stored in API memory.">PAPI::PContextParticleGroup_t::GetParticlePointer</a> functions to get the vertex data, then sends it to the graphics API. When a particle group is no longer needed, it is deleted using <a class="el" href="class_p_a_p_i_1_1_p_context_particle_group__t.html#a49aab2a3887103f5bbeccebef529a31b" title="Delete one or more consecutive particle groups.">PAPI::PContextParticleGroup_t::DeleteParticleGroups</a>.</p>
<p >See the particle group calls in <a class="el" href="class_p_a_p_i_1_1_p_context_particle_group__t.html" title="This class contains the API calls that operate on particle groups.">PAPI::PContextParticleGroup_t</a>.</p>
<h2><a class="anchor" id="alists"></a>
Action Lists</h2>
<p >Action lists are blocks of actions that are applied together to a particle group. An action list is conceptually similar to a script or procedure. Action lists are implemented and expressed similarly to display lists in OpenGL. An action list encapsulates the specifics of a particular effect and allows complex effects to be treated as primitives like actions. An action list can be called from within another action list.</p>
<p >When using the <a class="el" href="class_p_a_p_i_1_1_p_context_actions__t.html#legacy_actions">Legacy Actions</a> API, rather than the more performant <a class="el" href="class_p_a_p_i_1_1_p_context_actions__t.html#inline_actions">Inline Actions</a> API, action lists also allow effects to be simulated much more efficiently. This is because the entire set of actions is known at the start, and this knowledge can be used by the implementation of the Particle System API. For example, several actions can be applied to one set of particles before moving to the next set of particles, yielding better memory access patterns. Also, in future versions common sequences of actions might be detected and replaced by efficient code that handles all those actions in one pass.</p>
<p >To take advantage of the up to 50% performance increase of action lists, you need to order your actions carefully. The performance advantage is achieved when two or more actions that can be combined are ordered next to each other in the list. Actions that create (Vertex(), Source()) or delete (Sink*(), and KillOld()) particles, and actions that reorder particles (Sort()) cannot be combined. All other actions can be combined to yield the performance advantage. See Effects.cpp for several examples of efficient ordering.</p>
<p >Action List Calls create and operate on action lists. An empty action list is first created using <a class="el" href="class_p_a_p_i_1_1_p_context_action_list__t.html#a93f9538f37bfc3bba040d658fa2847a6" title="Generate a block of empty action lists.">PAPI::PContextActionList_t::GenActionLists</a>, and is then filled or compiled by calling <a class="el" href="class_p_a_p_i_1_1_p_context_action_list__t.html#aec2d30f3336b2be2ab34ba3cccc55d53" title="Begin the creation of the specified action list.">PAPI::PContextActionList_t::NewActionList</a>, then calling Actions, then calling <a class="el" href="class_p_a_p_i_1_1_p_context_action_list__t.html#af0ffaad952c3b2df8bc7161deb9f9127" title="End the creation of a new action list.">PAPI::PContextActionList_t::EndActionList</a>. Once the action list is filled, it is run via <a class="el" href="class_p_a_p_i_1_1_p_context_action_list__t.html#a1fd276780b4ea073d187576f2459e1b4" title="Execute the specified action list on the current particle group.">PAPI::PContextActionList_t::CallActionList</a>. Thus, an action list is sort of a higher-level action. Complex behaviors can be stored in an action list and then called later, even as part of another action list. Action lists cannot be edited. They can only be created or destroyed. To destroy an action list, call <a class="el" href="class_p_a_p_i_1_1_p_context_action_list__t.html#abef97a9286180f1e53cb81a5c17e6205" title="Delete one or more consecutive action lists.">PAPI::PContextActionList_t::DeleteActionLists</a>. When particles are created within a NewActionList / EndActionList block, they will receive attributes from the state that was current when the action list was created.</p>
<p >When in immediate mode (not creating or calling an action list), particles are created with attributes from the current state. However, the time step length, dt, uses the value that is current when CallActionList is executed, not the value of dt when the action list was created. This allows dt to be modified without recompiling action lists.</p>
<p >See the Action List Calls in the class <a class="el" href="class_p_a_p_i_1_1_p_context_action_list__t.html" title="Action List Calls.">PAPI::PContextActionList_t</a>.</p>
<h2><a class="anchor" id="defparams"></a>
Default Parameters</h2>
<p >Many functions in the Particle System API take arguments with default values. This is a feature of C++. For example, in </p><div class="fragment"><div class="line">Color(<span class="keywordtype">float</span> r, <span class="keywordtype">float</span> g, <span class="keywordtype">float</span> b, <span class="keywordtype">float</span> alpha = 1.0f) </div>
</div><!-- fragment --><p>, the parameter alpha has a default value of 1.0. This means that Color can be called with either three parameters or four. When called with three parameters, they are the values of r, g, and b; and alpha receives the default value, 1.0. Only parameters at the end of the parameter list can have default values. Likewise, when calling functions that have default values for parameters, all values specified will be applied to parameters starting with the left. This means that there is no way to specify a value for a parameter at the end of the list without specifying values for all parameters to its left.</p>
<h2><a class="anchor" id="except"></a>
Exception Handling</h2>
<p >See <a class="el" href="p_error_8h.html">pError.h</a> for the list of exceptions thrown by the API.</p>
<h1><a class="anchor" id="other"></a>
Other Stuff</h1>
<ul>
<li>Change log is <a href="../../ChangeLog.html">[here]</a>.</li>
<li>Future work is <a href="../../ToDo.html">[here]</a>.</li>
<li>Project is hosted <a href="https://github.com/davemc0/Particle">[here]</a>.</li>
</ul>
<h2><a class="anchor" id="acks"></a>
Acknowledgements</h2>
<ul>
<li>Code for some of the particle actions and several concepts regarding the structure of the API are thanks to Jonathan P. Leech. See also: Jonathan Leech and Russell M. Taylor II, "Interactive Modeling Using Particle Systems", Proceedings of the 2nd Conference on Discrete Element Methods, MIT, spring 1993, pp. 105-116.</li>
<li>Thanks to Mark B. Allen of NASA Ames Research Center for finding bugs, making suggestions and implementing the particle length attribute.</li>
<li>Thanks to Jason Pratt of CMU Stage 3 research group (makers of ALICE) for adding the PDTriangle domain. This is a powerful feature that should have been there the whole time. </li>
</ul>
</div></div><!-- PageDoc -->
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.3
</small></address>
</body>
</html>