Particles tutorial (#126)

* Particle tutorial

Signed-off-by: Carlos Agüero <[email protected]>

* Tutorial tweaks.

Signed-off-by: Carlos Agüero <[email protected]>

* remove optix warning

Signed-off-by: Ian Chen <[email protected]>

Co-authored-by: Ian Chen <[email protected]>

examples/particles_demo/Main.cc

@@ -105,7 +105,7 @@ void buildScene(ScenePtr _scene)
   particleMaterial->SetAlphaFromTexture(true);
   particleMaterial->SetDepthWriteEnabled(false);
 
-  // create particle emitter.
+  //! [create particle emitter]
   ParticleEmitterPtr emitter = _scene->CreateParticleEmitter();
   emitter->SetLocalPose({0, 0, 0, 0, -1.57, 0});
   emitter->SetRate(10);
@@ -117,6 +117,7 @@ void buildScene(ScenePtr _scene)
   emitter->SetScaleRate(10);
   emitter->SetEmitting(true);
   root->AddChild(emitter);
+  //! [create particle emitter]
 }
 
 //////////////////////////////////////////////////
@@ -148,7 +149,6 @@ int main(int _argc, char** _argv)
   std::vector<CameraPtr> cameras;
 
   engineNames.push_back("ogre2");
-  engineNames.push_back("optix");
 
   for (auto engineName : engineNames)
   {

tutorials.md.in

@@ -20,6 +20,7 @@ Ignition @IGN_DESIGNATION_CAP@ library and how to use the library effectively.
 7. \subpage render_pass  "Render pass"
 8. \subpage simple_demo  "Simple demo"
 9. \subpage text_geom  "Text geom"
+10. \subpage particles  "Particles"
 
 ## License
 

tutorials/20_particles_tutorial.md

@@ -0,0 +1,73 @@
+\page particles Particles
+
+This example shows how to include a particle emitter in the scene.
+
+## Compile and run the example
+
+Create a build directory and use `cmake` and `make` to compile the code:
+
+```{.sh}
+cd ign-rendering/examples/particles_demo
+mkdir build
+cd build
+cmake ..
+make
+```
+Execute the example:
+
+```{.sh}
+./particles_demo
+[Msg] Loading plugin [ignition-rendering4-ogre2]
+===============================
+  TAB - Switch render engines
+  ESC - Exit
+===============================
+```
+@image html img/particles.png
+
+## Code
+
+A particle emitter generates a stream of particles. We can create a particle
+emitter in the same way we create other objects in the scene. We just need to
+use the scene to create the emitter using the method `CreateParticleEmitter`. It's possible to configure a few attributes of the emitter and its particles:
+
+* Type: `EM_POINT` emitters emit particles from a single point. `EM_BOX`,
+`EM_CYLINDER` and `EM_ELLIPSOID` emitters emit randomly from a box, cylinder or
+ellipsoid respectively.
+
+* Emitter size: Adjust the dimensions of the volume from which the particles are
+emitted.
+
+* Rate: Set the amount of particles per second emitted.
+
+* Duration: This parameter can be used to automatically disable the emitter
+after some time.
+
+* Emitting: Enable/Disable the emission of particles.
+
+* Particle size: Adjust the particle dimensions.
+
+* Lifetime: Set the amount of seconds each particles "lives" before being
+destroyed.
+
+* Material: Set the material which all particles in the emitter will use.
+
+* Velocity: Set a velocity range and each particle is emitted with a random
+velocity within this range.
+
+* Color range: Set the color for all particles emitted. You have two options to
+set the color.
+  * Using two color values: The actual color is interpolated between these two
+  colors along the lifetime of the particle.
+  * Using an image: The colors are taken from a specified image file. The range
+  of color values begins from the left side of the image and move to the right
+  over the lifetime of the particle, therefore only the horizontal dimension of
+  the image is used.
+
+* Scale rate: Adjust the amount by which to scale the particles in both `X` and
+`Y` direction per second.
+
+Here's the snippet of code from `examples/particles_demo/Main.cc` that includes
+a particle emitter to render particles to look like smoke:
+
+\snippet examples/particles_demo/Main.cc create particle emitter