[SESI logo]

Houdini Development Toolkit - Version 6.5

Side Effects Software Inc. 2004

Particle Operators

POP Classes and Data Structures

POP_ContextData

The POP_ContextData class is used to pass information from whatever is cooking the POP (usually the POP editor viewport or a POP Sop) to the POPs. It contains the geometry detail to cook as well as lots of attribute information. It is also used to pass information from POP to POP as cooking occurs. For example, a Color POP which adds a diffuse color attribute will also set the offset value in the POP_ContextData.

Some useful methods:

float random (void)
random() returns a random number between 0-1. This should be used instead of UTfastRandom() so that random numbers used within POPs are completely deterministic.

GEO_PrimParticle* getPrimPart (POP_Node* node)
getPrimPart() returns the particle primitive generated by a particular POP. If this particle doesn't exist already, it creates a new one.

GEO_PrimParticle* hasPrimPart (POP_Node* node)
hasPrimPart() returns whether the particular POP already has a corresponding particle primitive created for it.

GU_Detail* getDetail (void)
getDetail() returns the GU_Detail being processed by this POP_ContextData.

void addEvent (UT_String& events)
addEvent() signals that an event has occurred.

void removeEvent (UT_String& events)
removeEvent() signals that an event has ended.

void recacheOffset (void)
recacheOffset() reacquires all of the cached offset values in the detail. This may be necessary, if the offsets have shifted around (which is possible after a gdp merge).

int isGuideOnly (void)
isGuideOnly() returns whether to cook the guide geometry only.

int get____Offset (void)
There are many methods that retrieve attribute offsets.

The attribute offset that can be retrieved include:
Name Description Type Size
Accel Acceleration UT_Vector3 1
Alpha Point alpha float 1
Attract Attractor index. Particle is attracted to this point number. int 1
Charge Charge float 1
Diffuse Diffuse color float 3
Distance Distance to collision object. float 1
Drag Drag float 1
Follow Follow index. Particle will follow this leader number. int 1
Gen Generation. int 1
HitDiffuse Diffuse color at point of collision float 3
HitID ID of collision int 1
HitNormal Normal at point of collision UT_Vector3 1
HitPos Position where collision occurred float 3
HitPosUV Parametric UV coordinates where collision occurred float 2
HitTime When the collision occurred. float 1
HitUV Texture UV at point of collision. float 3
ID ID int 1
Instance Instanced geometry index 1
Life Total expected lifespan float 1
Mass Mass float 1
Normal Normal UT_Vector3 1
NumHit Number of times collision has occurred int 1
OrbitAxis Orbit Axis UT_Vector3 1
OrbitCenter Orbit Center Position float 3
OrbitCntrID Orbit Center ID int 1
OrbitRadius Orbit Radius float 1
OrbitSpeed Orbit Speed float 1
Origin Birth origin int 1
Parent ID of parent int 1
PrevVel Previous velocity UT_Vector3 1
Rot Rotation about particle axis float 4
Scale Scale float 1
SpeedLimit Speed Limit float 2
springk Spring Constant float 1
State State of the particle int 1
tension Spring Tension float 1
Texture Texture UV float 3
Trans Particle Axis Translation UT_Vector3 1
Up Up Vector UT_Vector3 1
Velocity Velocity UT_Vector3 1

Some useful data:

float myTime;
Time when cook was requested.

float myTimeInc;
Time increment for this cook.

OP_Network* myXformObj;
Transform Object

UT_PtrArray<OP_Guide*> myOPGuides;
List of Guide Geometries.

UT_PtrArray<POP_Node*> myGuidePOPs;
List of POPs that add guide geometry.


POP_Node

POP_Node is the base class for POPs.

Some useful methods:

void add____Attrib (POP_ContextData* data)
add____Attrib() is used to add attributes to the detail if they don't exist already. Not only will the attribute be added, but the offset value will also be set in the POP_ContextData.

The attributes that can be added include:
Name Description Type Size
Alpha Point alpha float 1
Attract Attractor index. Particle is attracted to this point number. int 1
Charge Charge float 1
Diffuse Diffuse color float 3
Distance Distance to collision object. float 1
Drag Drag float 1
Follow Follow index. Particle will follow this leader number. int 1
Gen Generation. int 1
HitDiffuse Diffuse color at point of collision float 3
HitID ID of collision int 1
HitNormal Normal at point of collision UT_Vector3 1
HitPos Position where collision occurred float 3
HitPosUV Parametric UV coordinates where collision occurred float 2
HitTime When the collision occurred. float 1
HitUV Texture UV at point of collision. float 3
ID ID int 1
Instance Instanced geometry index 1
Mass Mass float 1
NumHit Number of times collision has occurred int 1
OrbitAxis Orbit Axis UT_Vector3 1
OrbitCenter Orbit Center Position float 3
OrbitCntrID Orbit Center ID int 1
OrbitRadius Orbit Radius float 1
OrbitSpeed Orbit Speed float 1
Origin Birth origin int 1
Parent ID of parent int 1
PrevVel Previous velocity UT_Vector3 1
Rot Rotation about particle axis float 4
Scale Scale float 1
SpeedLimit Speed Limit float 2
SpringK Spring Constant float 1
Tension Spring Tension float 1
Trans Particle Axis Translation UT_Vector3 1
Up Up Vector UT_Vector3 1

int addUserVariable (const char* name, int size, GB_AttribType type, const void* def, const char* local = 0);
addUserVariable() is used to add user defined attributes to the detail. The method will also take care of adding local variables that correspond to the attribute. The attribute will require the usual information like a name, size (number of bytes the attribute requires), type (GB_ATTRIB_FLOAT, GB_ATTRIB_INT or GB_ATTRIB_VECTOR) and default values. The parameter local specifies the name of the local variable. It is optional. If it isn't specifies, the name of the attribute, all uppercased is used. For example, adding float attribute "abc" will create local variables "ABC1", "ABC2", etc. Adding vector attribute "abc" will create local variables "ABCX", "ABCY", and "ABCZ".

OP_ERROR buildParticleList (OP_Context &context);
buildParticleList() is used to build the list of particle primitives that the POP should process.

void initParticleList (OP_Context &context, GEO_PrimParticle* part = NULL);
initParticleList() is used to initialize the list of particle primitives that the POP should process. Used by generators, it will initialize the list with one specific primitive. It can also be used to clear the list if the passed in primitive is NULL.

int addToParticleList (OP_Context &context, GEO_PrimParticle* part);
addToParticleList() adds a primitive to the list of particle primitives to process. If successful, the function returns 1. If the primitive is already in the list, it is not added and the function returns 0.

void addAccelGuide (GEO_Point* ppt, float ax, float ay, float az, float scale = 1.0f, int normalize = 0);
addAccelGuide() adds guide geometry to show accelerations. Useful for modifier POPs that change the particle's acceleration.

int checkActivation (POP_ContextData* data, POP_FParam activate);
checkActivation() will evaluate the activation parameter. It takes care of allowing certain local variables in the parameter evaluation. It returns 1 if the POP should be active, and 0 otherwise.

GEO_ParticleVertex*
birthParticle(POP_ContextData* data,
GEO_PrimParticle* part, const UT_Vector4& pos,
POP_AttribMap* map, GB_AttributeData* inherit,
GB_AttributeData* split, POP_IntFunc originIndex,
int originGeo, int originUse,
POP_FloatFunc lifetime,
POP_BirthAttribFunc birthAttrib = NULL,
void* userData = NULL)
birthParticle() should be used to birth particles into a particle system.

data POP_ContextData being used.
part Particle primitive to birth into.
pos Position of the birthed particle.
map A POP_AttribMap is a mapping of attribtues from one detail to another. This particular mapping is used for inheriting attributes from the inherit GB_AttributeData. Can be set to NULL.
inherit Attribute data to inherit general attributes (i.e. color, velocity, etc.). It is required when map is used. Can be set to NULL.
split Attribute data to inherit parental attributes (parent, origin, generation) from. Can be set to NULL.
originIndex Origin index value.
originGeo Origin from geometry number.
originUse How to set origin id (i.e. origin attribute). This is a bit mask:
  • POP_ORIGIN_INDEX: add passed in index
  • POP_ORIGIN_GEO: add source geometry number
  • POP_ORIGIN_PARENT: add parent's origin
lifetime Total expected life of the particle.
birthAttrib Function to set attributes after particle is birthed.
userdata User data passed into birthAttrib.

The originIndex and lifetime parameters are function pointers. Here are the prototypes and some examples for these functions.

// Prototype for function that returns a floating point value. // Function returns the value. // data POP_ContextData being used. Needed for random num generation. typedef float (POP_Node::*POP_FloatFunc)(POP_ContextData* data); float POP_Source::getLifetime (POP_ContextData* data) { return (myLife + 2.0f * (data->random() - 0.5f) * myLifeVar)); } // Prototype for function that returns a integer value. // Function returns the value. // data POP_ContextData being used. Needed for random num generation. typedef int (POP_Node::*POP_IntFunc)(POP_ContextData* data); int POP_Source::getOriginIndex (POP_ContextData* data) { return (myOrigin); } The birhtAttrib is also a function pointer. Here is the prototype and an example. // Prototype for function that sets attributes after points are birthed. // data POP_ContextData being used // ppt particle's point // vel particle velocity // userdata passed in data typedef void (POP_Node::*POP_BirthAttribFunc) (POP_ContextData* data, GEO_Point* ppt, UT_Vector3* vel, void* userdata); void POP_Source::setVel (POP_ContextData* data, GEO_Point*, UT_Vector3* vel, void*) { vel->x() = myVelX + 2.0f * (.5 - data->random()) * myVarX; vel->y() = myVelY + 2.0f * (.5 - data->random()) * myVarY; vel->z() = myVelZ + 2.0f * (.5 - data->random()) * myVarZ; }
void
intersectParticle (POP_ContextData* data,
float t, int behavior, GEO_Point* ppt,
UT_Vector4& p0, UT_Vector3& vel,
UT_Vector3& accel,
int* state, float timeinc, int isectMax,
POP_FloatFunc gainTan, POP_FloatFunc gainNml,
POP_IntFunc id, int addprim,
POP_VertexIntersectFunc vertexIntersect)
intersectParticle() handles particle collision. It handles different collision behaviors and also sets the required collision attributes.

data POP_ContextData being used.
t Current time.
behavior Behavior:
  • 0 = die on collision
  • 1 = bounce on collision
  • 2 = stick on collision
  • 3 = continue on course
ppt Point being tested for intersection.
p0 Where the point is.
vel Current velocity of the particle.
accel Acceleration of the particle.
state Particle state (state attribute).
timeinc Time increment. How much time is passing during this cook.
iSectMax Maximum number of bounces to perform for bounce behavior.
gainTan Velocity gain factor in tangential direction for bounces.
gainNml Velocity gain factor in normal direction for bounces.
id Collision id to be used. The collision ID is just an integer number to associate with this collision.
addprim If 1, adds the primitive number collided against to the collision id.
vertexIntersect Function that performs interersection.

The vertexIntersect is a function pointer. Here is the prototype and an example.

// Prototype for function that performs particle intersections. // Function returns 1 if hit. 0 otherwise. If there is a hit, // function should set thit, when, nml, primnum, posuv, uv and diff. // A default is passed in so only change if required. // The function should set dist regardless of hit or miss. // origin Where the particle is. // dir Particle velocity. // tmin Parametric minimum for intersection testing // (i.e. hit pos = origin + dir * parametric). // tmax Parametric maximum for intersection testing. // ttest If thit <= ttest, surface was hit. // isect Iteration # of bounce test for particular particle. // dist Distance from origin to point of intersection. Set to -1 // if the collision object is not in the path of the particle. // This is absolute distance. Not parametric distance. // thit Parametric distance from origin to point of intersection. // when Time of hit. // nml Normal direction of intersection. // primnum Primitive number of geometry hit // posuv Parametric uv coordinates at point of intersection // (or NULL if does not need to be set). // uv Texture coordinates at point of intersection // (or NULL if does not need to be set). // diff Diffuse color at point of intersection // (or NULL if does not need to be set). typedef int (POP_Node::*POP_VertexIntersectFunc) (const UT_Vector3& origin, const UT_Vector3& dir, float tmin, float tmax, float ttest, int isect, float& dist, float& thit, float& when, UT_Vector3& nml, int* primnum, UT_Vector3* posuv, UT_Vector3* uv, UT_Vector3* diff); int POP_Limit::vertexIntersect (const UT_Vector3& origin, const UT_Vector3& dir, float tmin, float tmax, float ttest, int isect, float& dist, float& thit, float& when, UT_Vector3& nml, int* primnum, UT_Vector3* posuv, UT_Vector3* uv, UT_Vector3* cd) { GU_RayInfo hitInfo; int result; int hit; hitInfo.myTmin = tmin; hitInfo.myTmax = tmax; hitInfo.myTValid = 0; result = myIntersector->sendRay(origin, dir, hitInfo); // Handle interrupted sendray if (result <= 0) { hit = 0; dist = -1.0f; } else { hit = (hitInfo.myT <= ttest); dist = hitInfo.myT * dir.length(); if (hit) { thit = hitInfo.myT; nml = hitInfo.myNml; *primnum = 0; if (posuv) posuv->assign(0, 0, 0); if (uv) uv->assign(0, 0, 0); if (cd) cd->assign(0, 0, 0); } } return(hit); } Some useful data:

POP_ParticleList myParticleList;
List of particle primitives that this POP should process.

OP_Guide* myGuide;
Holds the guide geometry for this POP.


POP_LocalVar

The POP_LocalVar class inherits from POP_Node. It is used to handle the local variables that are associated with particle attributes.

Some useful methods:

void setupVars (POP_ContextData* data, GB_PointGroup* source = 0)
The setupVars() method should be called during cooking to initialize the use of local variables by the POP.

void setupDynamicVars (POP_ContextData* data)
The setupDynamicVars() should be called at the beginning of cooking (right after the lockInputs()) to initialize the use of user defined local variables by the POP.

void allowVar (int val)
Although some parameters may allow the use of local variables, some may not. If evaluating a parameter that should not be using local variables, do something like this.

allowVar(0); angle = ANGLE(t); delta = DELTA(t); setCone(angle, delta, ROLLOFF(t)); maxDistance = MAXDISTANCE(t); allowVar(1); If a local variable is contained in any of these parameters, an OP error will occur.

Some useful data:

GEO_Point* myCurrPt;
This GEO_Point represents the point that is currently being modified. The myCurrPt variable should be updated as the processing occurs so that the appropriate attributes can be retrieved.

int myCurrIter;
This integer represents the iteration number of the processing. It is accessed with the $ITER variable. The variable should be updated as the processing occurs.


POP_ParticleList

The POP_ParticleList class is a list of particle primitive. It is used in POP_Nodes (as the variable myParticleList) to represent the particle primitives that a POP should process.

Some useful methods:

void clear (void)
Clear the list.

void add (GEO_PrimParticle* part)
Add a new primitive to the list.

GEO_PrimParticle* iterateInit (void)
Return the first primitive in the list.

GEO_PrimParticle* iterateNext (void)
Return the next primitive in the list. iterateInit() should be called before a call to iterateNext().

int find (GEO_PrimParticle* part)
Find out whether the primitive is in the list.


Table of Contents
Operators | Surface Operations | Particle Operations | Composite Operators | Channel Operators
Material & Texture | Objects | Command and Expression | Render Output |
Mantra Shaders | Utility Classes | Geometry Library | Image Library | Clip Library
Customizing UI | Questions & Answers

Copyright © 2004 Side Effects Software Inc.
477 Richmond Street West, Toronto, Ontario, Canada M5V 3E7