diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api.texi | 149 |
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 |