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) or LWPST_TRAIL (line segments). LWPST_TRAIL particle systems should include an LWPSB_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 function nparticles times.

cleanup( psys )

Frees the memory allocated by init and addParticle.

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 or addParticle. (The predefined buffer types should be added when create 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.