[Bf-blender-cvs] [4bdc04e8fb9] functions: comment particle system api

Jacques Lucke noreply at git.blender.org
Mon Jul 1 12:12:35 CEST 2019


Commit: 4bdc04e8fb9bababad84b48fa9e6db27a8356e93
Author: Jacques Lucke
Date:   Mon Jul 1 12:12:05 2019 +0200
Branches: functions
https://developer.blender.org/rB4bdc04e8fb9bababad84b48fa9e6db27a8356e93

comment particle system api

===================================================================

M	source/blender/simulations/bparticles/core.hpp

===================================================================

diff --git a/source/blender/simulations/bparticles/core.hpp b/source/blender/simulations/bparticles/core.hpp
index cbf30c37c99..073289b4fab 100644
--- a/source/blender/simulations/bparticles/core.hpp
+++ b/source/blender/simulations/bparticles/core.hpp
@@ -17,6 +17,163 @@
 
 namespace BParticles {
 
+class EventFilterInterface;
+class EventExecuteInterface;
+class EmitterInterface;
+
+/* Main API for the particle simulation. These classes have to be subclassed to define how the
+ * particles should behave.
+ ******************************************/
+
+/**
+ * An event consists of two parts.
+ *   1. Filter the particles that trigger the event within a specific time span.
+ *   2. Modify the particles that were triggered.
+ *
+ * In some cases it is necessary to pass data from the filter to the execute function (e.g. the
+ * normal of the surface at a collision point). So that is supported as well. Currently, only POD
+ * (plain-old-data / simple C structs) can be used.
+ */
+class Event {
+ public:
+  virtual ~Event();
+
+  /**
+   * Return how many bytes this event wants to pass between the filter and execute function.
+   */
+  virtual uint storage_size()
+  {
+    return 0;
+  }
+
+  /**
+   * Gets a set of particles and checks which of those trigger the event.
+   */
+  virtual void filter(EventFilterInterface &interface) = 0;
+
+  /**
+   * Gets a set of particles that trigger this event and can do the following operations:
+   *   - Change any attribute of the particles.
+   *   - Change the remaining integrated attribute offsets of the particles.
+   *   - Kill the particles.
+   *   - Spawn new particles of any type.
+   *
+   * Currently, it is not supported to change the attributes of other particles, that exist
+   * already. However, the attributes of new particles can be changed.
+   */
+  virtual void execute(EventExecuteInterface &interface) = 0;
+};
+
+/**
+ * An emitter creates new particles of possibly different types within a certain time span.
+ */
+class Emitter {
+ public:
+  virtual ~Emitter();
+
+  /**
+   * Create new particles within a time span.
+   *
+   * In general it works like so:
+   *   1. Prepare vectors with attribute values for e.g. position and velocity of the new
+   *      particles.
+   *   2. Request an emit target that can contain a given amount of particles of a specific type.
+   *   3. Copy the prepared attribute arrays into the target. Other attributes are initialized with
+   *      some default value.
+   *   4. Specify the exact birth times of every particle within the time span. This will allow the
+   *      framework to simulate the new particles for partial time steps to avoid stepping.
+   *
+   * To create particles of different types, multiple emit targets have to be requested.
+   */
+  virtual void emit(EmitterInterface &interface) = 0;
+};
+
+/**
+ * The integrator is the core of the particle system. It's main task is to determine how the
+ * simulation would go if there were no events.
+ */
+class Integrator {
+ public:
+  virtual ~Integrator();
+
+  /**
+   * Specify which attributes are integrated (usually Position and Velocity).
+   */
+  virtual AttributesInfo &offset_attributes_info() = 0;
+
+  /**
+   * Compute the offsets for all integrated attributes. Those are not applied immediately, because
+   * there might be events that modify the attributes within a time step.
+   */
+  virtual void integrate(ParticlesBlock &block,
+                         ArrayRef<float> durations,
+                         AttributeArrays r_offsets) = 0;
+};
+
+/**
+ * Describes how one type of particle behaves and which attributes it has.
+ */
+class ParticleType {
+ public:
+  virtual ~ParticleType();
+
+  /**
+   * Return the integrator to be used with particles of this type.
+   */
+  virtual Integrator &integrator() = 0;
+
+  /**
+   * Return the events that particles of this type can trigger.
+   */
+  virtual ArrayRef<Event *> events() = 0;
+
+  virtual ArrayRef<std::string> byte_attributes()
+  {
+    return {};
+  }
+
+  virtual ArrayRef<std::string> float_attributes()
+  {
+    return {};
+  }
+
+  virtual ArrayRef<std::string> float3_attributes()
+  {
+    return {};
+  }
+};
+
+/**
+ * Describes how the current state of a particle system transitions to the next state.
+ */
+class StepDescription {
+ public:
+  virtual ~StepDescription();
+
+  /**
+   * Return how many seconds the this time step takes.
+   */
+  virtual float step_duration() = 0;
+
+  /**
+   * Return the emitters that might emit particles in this time step.
+   */
+  virtual ArrayRef<Emitter *> emitters() = 0;
+
+  /**
+   * Return the particle type ids that will be modified in this step.
+   */
+  virtual ArrayRef<uint> particle_type_ids() = 0;
+
+  /**
+   * Return the description of a particle type based on its id.
+   */
+  virtual ParticleType &particle_type(uint type_id) = 0;
+};
+
+/* Classes used by the interface
+ ***********************************************/
+
 class ParticlesState {
  private:
   SmallMap<uint, ParticlesContainer *> m_container_by_id;
@@ -242,74 +399,6 @@ class EventExecuteInterface {
   AttributeArrays attribute_offsets();
 };
 
-/* Functions to be subclassed
- ******************************************/
-
-class Event {
- public:
-  virtual ~Event();
-
-  virtual uint storage_size()
-  {
-    return 0;
-  }
-
-  virtual void filter(EventFilterInterface &interface) = 0;
-  virtual void execute(EventExecuteInterface &interface) = 0;
-};
-
-class Emitter {
- public:
-  virtual ~Emitter();
-
-  virtual void emit(EmitterInterface &interface) = 0;
-};
-
-class Integrator {
- public:
-  virtual ~Integrator();
-
-  virtual AttributesInfo &offset_attributes_info() = 0;
-
-  virtual void integrate(ParticlesBlock &block,
-                         ArrayRef<float> durations,
-                         AttributeArrays r_offsets) = 0;
-};
-
-class ParticleType {
- public:
-  virtual ~ParticleType();
-
-  virtual Integrator &integrator() = 0;
-  virtual ArrayRef<Event *> events() = 0;
-
-  virtual ArrayRef<std::string> byte_attributes()
-  {
-    return {};
-  }
-
-  virtual ArrayRef<std::string> float_attributes()
-  {
-    return {};
-  }
-
-  virtual ArrayRef<std::string> float3_attributes()
-  {
-    return {};
-  }
-};
-
-class StepDescription {
- public:
-  virtual ~StepDescription();
-
-  virtual float step_duration() = 0;
-  virtual ArrayRef<Emitter *> emitters() = 0;
-
-  virtual ArrayRef<uint> particle_type_ids() = 0;
-  virtual ParticleType &particle_type(uint type_id) = 0;
-};
-
 /* ParticlesState inline functions
  ********************************************/



More information about the Bf-blender-cvs mailing list