1 files changed, 149 insertions, 0 deletions
diff --git a/doc/api.texi b/doc/api.texi
index 6581ae7..490a532 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -1277,6 +1277,7 @@ blocks to implement additional rendering techniques.
 * Tile Maps::                   Draw 2D tile maps.
 * Lines and Shapes::            Draw line segments and polygons.
 * Fonts::                       Drawing text.
+* Particles::                   Pretty little flying pieces!
 * Blending and Depth Testing::  Control how pixels are combined.
 * Vertex Arrays::               Create 2D/3D models.
 * Shaders::                     Create custom GPU programs.
@@ -1663,6 +1664,154 @@ Refer to @code{draw-sprite} (@pxref{Sprites}) for information about
 the other arguments.
 @end deffn
 
+@node Particles
+@subsection Particles
+
+Effects like smoke, fire, sparks, etc. are often achieved by animating
+lots of little, short-lived sprites known as ``particles''.  In fact,
+all of these effects, and more, can be accomplished by turning a few
+configuration knobs in a ``particle system''.  A particle system takes
+care of managing the many miniscule moving morsels so the developer
+can quickly produce an effect and move on with their life.  The
+@code{(chickadee render particles)} module provides an API for
+manipulating particle systems.
+
+Below is an example of a very simple particle system that utilizes
+nearly all of the default configuration settings:
+
+@example
+(use-modules (chickadee render particles))
+(define texture (load-image "particle.png"))
+(define particles (make-particles 2000 #:texture texture))
+@end example
+
+In order to put particles into a particle system, a particle
+``emitter'' is needed.  Emitters know where to spawn new particles,
+how many of them to spawn, and for how long they should do it.
+
+Below is an example of an emitter that spawns 16 particles per frame
+at the coordinates @code{(320, 240)}:
+
+@example
+(use-modules (chickadee math vector))
+(define emitter (make-particle-emitter (vec2 320.0 240.0) 16))
+(add-particle-emitter particles emitter)
+@end example
+
+To see all of the tweakable knobs and switches, read on!
+
+@deffn {Procedure} make-particles @var{capacity} [#:blend-mode @code{alpha}] @
+       [#:color white] [#:end-color transparent] [#:texture] @
+       [#:animation-rows 1] [#:animation-columns 1] [#:width] [#:height] @
+       [#:speed-range (vec2 0.1 1.0)] [#:acceleration-range (vec2 0.0 0.1)] @
+       [#:direction-range (vec2 0 (* 2 pi))] [#:lifetime 30] [#:sort]
+
+Return a new particle system that may contain up to @var{capacity}
+particles.  Achieving the desired particle effect involves tweaking
+the following keyword arguments as needed:
+
+- @var{blend-mode}: Pixel blending mode.  @code{alpha} by default.
+(@pxref{Blending and Depth Testing} for more about blend modes).
+
+- @var{start-color}: The tint color of the particle at the beginning of its
+life.  White by default.
+
+- @var{end-color}: The tint color of the particle at the end of of its
+life.  Completely transparent by default for a fade-out effect.  The
+color in the middle of a particle's life will be an interpolation of
+@var{start-color} and @var{end-color}.
+
+- @var{texture}: The texture applied to the particles.  The texture
+may be subdivided into many animation frames.
+
+- @var{animation-rows}: How many animation frame rows there are in the
+texture.  Default is 1.
+
+- @var{animation-columns}: How many animation frame columns there are
+in the texture.  Default is 1.
+
+- @var{width}: The width of each particle.  By default, the width of
+an animation frame (in pixels) is used.
+
+- @var{height}: The height of each particle.  By default, the height
+of an animation frame (in pixels) is used.
+
+- @var{speed-range}: A 2D vector containing the min and max particle
+speed.  Each particle will have a speed chosen at random from this
+range.  By default, speed ranges from 0.1 to 1.0.
+
+- @var{acceleration-range}: A 2D vector containing the min and max
+particle acceleration.  Each particle will have an acceleration chosen
+at random from this range.  By default, acceleration ranges from 0.0
+to 0.1.
+
+- @var{direction-range}: A 2D vector containing the min and max
+particle direction as an angle in radians.  Each particle will have a
+direction chosen at random from this range.  By default, the range
+covers all possible angles.
+
+- @var{lifetime}: How long each particle lives, measured in
+updates. 30 by default.
+
+- @var{sort}: @code{youngest} if youngest particle should be drawn
+last or @code{oldest} for the reverse.  By default, no sorting is
+applied at all.
+@end deffn
+
+@deffn {Procedure} particles? @var{obj}
+Return @code{#t} if @var{obj} is a particle system.
+@end deffn
+
+@deffn {Procedure} update-particles @var{particles}
+Advance the simulation of @var{particles}.
+@end deffn
+
+@deffn {Procedure} draw-particles @var{particles}
+Render @var{particles}.
+@end deffn
+
+@deffn {Procedure} draw-particles* @var{particles} @var{matrix}
+Render @var{particles} with @var{matrix} applied.
+@end deffn
+
+@deffn {Procedure} make-particle-emitter @var{spawn-area} @
+       @var{rate} [@var{duration}]
+
+Return a new particle emitter that spawns @var{rate} particles per
+frame within @var{spawn-area} (a rectangle or 2D vector) for
+@var{duration} frames.  If @var{duration} is not specified, the
+emitter will spawn particles indefinitely.
+@end deffn
+
+@deffn {Procedure} particle-emitter? @var{obj}
+Return @code{#t} if @var{obj} is a particle emitter.
+@end deffn
+
+@deffn {Procedure} particle-emitter-spawn-area @var{emitter}
+Return the spawn area for @var{emitter}.
+@end deffn
+
+@deffn {Procedure} particle-emitter-rate @var{emitter}
+Return the number of particles that @var{emitter} will spawn per
+frame.
+@end deffn
+
+@deffn {Procedure} particle-emitter-life @var{emitter}
+Return the number of frames remaining in @var{emitter}'s lifespan.
+@end deffn
+
+@deffn {Procedure} particle-emitter-done? @var{emitter}
+Return @code{#t} if @var{emitter} has finished spawning particlces.
+@end deffn
+
+@deffn {Procedure} add-particle-emitter @var{particles} @var{emitter}
+Add @var{emitter} to @var{particles}.
+@end deffn
+
+@deffn {Procedure} remove-particle-emitter @var{particles} @var{emitter}
+Remove @var{emitter} to @var{particles}
+@end deffn
+
 @node Blending and Depth Testing
 @subsection Blending and Depth Testing