Writing New Behaviour Ops
=========================

NukeX 6.3 has a particle system.  It is possible to hook into this and write your own
plug-ins that operate on particles.

The base class of interest is DD::Image::ParticleBehaviour in <DDImage/ParticleOp.h>.
Subclasses should implement the following function:

.. code-block:: c

  virtual void applyBehaviour( const ParticleContext& context, ParticleSystem* ps)

This should apply the operation to the particles in ParticleSystem.  

A simple example is as follows:

.. code-block:: c

  virtual void applyBehaviour( const ParticleContext& context, ParticleSystem* ps)
  {
     for (unsigned i = 0; i < ps->numParticles(); i++) {
        if ( conditionsApply( ps, i ) ) { 
          applyAcceleration(ps, i, context, Vector3(0, -0.1, 0));
        }
     }
  }

This applies a consistent downwards acceleration to all particles.  The conditionsApply function
checks to see whether the given particle is operated upon.  It is important to call this, as 
the ParticleMerge node relies on it.  Apart from checking which branch the particle was emitted 
on for ParticleMerge, it also checks whether or not the particle matches various criteria 
set on knobs.  These are the conditionKnobs (which allow execution to be made conditional on
min/max age, channels, etc.) and the domainKnobs (which allow execution to be confined to a certain
region).  To add these knobs call the addDomainKnobs and addConditionKnobs functions from your
knobs() call, like so:

.. code-block:: c

  void knobs(Knob_Callback f)
  {
    addConditionsKnobs(f);
    addDomainKnobs(f);
 }

It is possible to access properties of particles from within the applyBehaviour function by functions
on the ParticleBehaviour.  For example, the mass of the particle is retrieved with:

.. code-block:: c

  const float& particleMass(unsigned idx) const;

and can be set by:

.. code-block:: c

  float& particleMass(unsigned idx);

The properties that exist are as follows:
  
  =================== =====================  ========================================================================
  Type                Name                   Description
  =================== =====================  ========================================================================
  Vector3             initialPosition        The position the particle was created at
  Vector3             position               The position the particle is at now
  Vector3             velocity               The velocity of the particle, expressed in units/frame
  Vector3             size                   The size of the particle, expressed in units
  Quarternion         orientation
  Vector3             rotationAxis
  float               rotationAngle
  float               rotationVelocity
  float               mass                   The mass of the particle
  float               life                   The maximum lifetime of the particle (in frames)
  float               expirationChance       The chance that this particle dies each frame (for halflife)
  float               t                      The number of frames (possibly fractional) this particle has been alive
  float               startTime              The time this particle was emitted
  int                 id                     A unique ID for the particle
  ParticleChannelSet  channels               The channel sets the particle belongs to
  int                 pathMask               The pathMasks the particle is active for (internal)
  bool                active                 Whether the particle currently exists or not
  Op*                 representation         The Iop or GeoOp to use to as the particle for rendering
  =================== =====================  ========================================================================


All of these are set by an applyBehaviour implementation, although it would not make sense to set
initialPosition/t/dtOffset/startTime/id/pathMask/active/representation.

applyBehaviour is given a ParticleContext which tells it how long to run the effect for.  For example,
a force applied for 0.5 frames ought to only result in half the acceleration that it would if it were
run for 1 frame.  This is used to implement sub-frame stepping.  A couple of helper functions
are provided on ParticleBehaviour:

.. code-block:: c

    void applyAcceleration(ParticleSystem* ps, unsigned idx, const ParticleContext& ctx, Vector3 accel);
    void applyForce(ParticleSystem* ps, unsigned idx, const ParticleContext& ctx, Vector3 force);

These take into account the ctx.dt(), and also whether or not the particle was only just emitted in the last frame,
and if so, whether only part of that force should be applied.  applyForce() takes into account the mass, dividing
the force by the mass to get the acceleration.  For example, if you're writing a plug-in that reduces the particle's
mass slightly each frame, then you need to take ctx.dt() into account too.  If, on the other hand, you are writing
a plug-in that sets the particle's color to a different value depending upon its value **t**, there is no need to take
into account ctx.dt().

Improving Particle Performance
==============================

Since Nuke 11.3v1, the Particle system API has been expanded to allow you to write more efficient Ops.

The ParticleSystem class has a new set of accessor methods which return pointers to attribute arrays. Using these is much faster than calling the individual methods for each particle. Instead of:

.. code-block:: c

    for ( int i = 0; i < ps->numParticles(); i++ )
      do_something_with( particlePosition(i) );

it's better to do this:

.. code-block:: c

    auto particlePosition = ps->particlePosition();
    for ( int i = 0; i < ps->numParticles(); i++ )
      do_something_with( particlePosition[i] );

Even better, if your code is thread safe, is to use the new ParallelFor API to multithread your particle system:

.. code-block:: c

    auto particlePosition = ps->particlePosition();
    ParallelFor(ps->numParticles(),
      [&](int i) {
        do_something_with( particlePosition[i] );
      }
    )

This will use Nuke's rendering threads to spread the work.
