Particle Services
Availability LightWave 6.0 | Component Layout | Header lwprtcl.h
The particles global returns functions that allow you to create particle systems and to read and write particle data. Particles are typically used by volumetric renderers to define the extent and local density of a volume. LightWave's Hypervoxels, for example, uses them this way.
The host side of the particles global manages a database of particle systems. The global supplies methods for adding, deleting and reading particle data in the database. Having such a database allows one plug-in to create particle systems that others can later use.
Global Call
LWPSysFuncs *psysf; psysf = global( LWPSYSFUNCS_GLOBAL, GFUSE_TRANSIENT );
The global function returns a pointer to an LWPSysFuncs.
typedef struct st_LWPSysFuncs { LWPSysID (*create) (int flags, int type); int (*destroy) (LWPSysID); int (*init) (LWPSysID, int np); void (*cleanup) (LWPSysID); void (*load) (LWPSysID, LWLoadState *); void (*save) (LWPSysID, LWSaveState *); int (*getPCount) (LWPSysID); void (*attach) (LWPSysID, LWItemID); void (*detach) (LWPSysID, LWItemID); LWPSysID * (*getPSys) (LWItemID); LWPSBufID (*addBuf) (LWPSysID, LWPSBufDesc); LWPSBufID (*getBufID) (LWPSysID, int bufFlag); void (*setBufData) (LWPSBufID, void *data); void (*getBufData) (LWPSBufID, void *data); int (*addParticle) (LWPSysID); void (*setParticle) (LWPSBufID, int index, void *data); void (*getParticle) (LWPSBufID, int index, void *data); void (*remParticle) (LWPSysID, int index); } LWPSysFuncs;
You can allocate, initialize and read particle data either individually (one particle at a time) or all at once. Which approach you take will depend primarily on where the data comes from and how you use it.
psys = create( flags, type )
- Create a particle system. The flags indicate which buffers should be allocated for the
particles and can be any of the following, combined using bitwise-or.
LWPSB_POS
position float[3]
LWPSB_SIZ
size float
LWPSB_SCL
scale float[3]
LWPSB_ROT
rotation float[3]
LWPSB_VEL
velocity float[3]
LWPSB_AGE
age float
LWPSB_FCE
force float
LWPSB_PRS
pressure float
LWPSB_TMP
temperature float
LWPSB_MAS
mass float
LWPSB_LNK
link to particle (for trails) int
LWPSB_ID
ID (unique index for the particle) int
LWPSB_ENB
enable state (dead/alive/limbo) char
LWPSB_RGBA
display color and alpha char[4]
LWPSB_CAGE
time since last collision float
The particle type can be either
LWPST_PRTCL
(single points) orLWPST_TRAIL
(line segments).LWPST_TRAIL
particle systems should include anLWPSB_LNK
buffer for the second point in each trail. result = destroy( psys )
- Free the particle system.
error = init( psys, nparticles )
- Allocate memory for the particles. This is equivalent to calling the
addParticle
functionnparticles
times. cleanup( psys )
- Frees the memory allocated by
init
andaddParticle
. load( psys, loadstate )
- Read the particle system data from a file. This will typically be used by handler load callbacks.
save( psys, savestate )
- Write the particle system data to a file. This will typically be used by handler save callbacks.
count = getPCount( psys )
- Returns the number of particles.
attach( psys, item )
- Associate a particle system with an item in the scene, usually an object. More than one
particle system can be attached to an item, and more than one item can share the same
particle system. Attaching a particle system to an item makes it possible for others,
Hypervoxels in particular, to use the
getPSys
function to find it. detach( psys, item )
- Remove the association between a particle system and an item.
psys_array = getPSys( item )
- Returns a NULL-terminated array of particle system IDs that have been associated with
the item by the
attach
function. psbuf = addBuf( psys, bufdesc )
- Add a custom per-particle buffer. Call this before any calls to
init
oraddParticle
. (The predefined buffer types should be added whencreate
is called.) The structure used to define the buffer is described below. The buffer ID returned by this function can be used with the functions that get and set buffer data. psbuf = getBufID( psys, bufbit )
- Returns a buffer ID for one of the predefined buffers. This is used with the functions
that get and set buffer data. The second argument is one of the buffer flags passed to
create
. setBufData( psbuf, data )
- Set the buffer values for all particles. The data is an array of the appropriate type
for the buffer, with a number of entries equal to the number of particles. Use
setParticle
to set the buffer data for one particle at a time. getBufData( psbuf, data )
- Get the buffer values for all particles. Use
getParticle
to get the buffer data for one particle at a time. index = addParticle( psys )
- Add a particle.
setParticle( psbuf, index, data )
- Set the buffer value for a particle. Particles are numbered from 0 to
getPCount
- 1 in the order in which they're added. getParticle( psbuf, index, data )
- Get the buffer value for a particle.
remParticle( psys, index )
- Remove a particle.
Particle Buffers
The addBuf
function uses a buffer descriptor to define the buffer to be added.
typedef struct st_LWPSBufDesc { const char *name; int dataType; int dataSize; } LWPSBufDesc;
name
- A string that names the buffer. In the future, this may allow users or plug-ins to refer to the buffer by name.
dataType
- The data type of the data in the buffer.
LWPSBT_FLOAT LWPSBT_INT LWPSBT_CHAR
dataSize
- The number of values per particle in the buffer (and not the number of bytes).
Example
The particle sample is a displacement handler that demonstrates the use of the particle system global. Its operation is similar to that of the HVParticle displacement handler Hypervoxels adds to objects that lack particle systems.