summaryrefslogtreecommitdiff
path: root/manuals/chickadee/Particles.html
diff options
context:
space:
mode:
authorDavid Thompson <dthompson@vistahigherlearning.com>2019-06-04 20:49:16 -0400
committerDavid Thompson <dthompson@vistahigherlearning.com>2019-06-04 20:49:16 -0400
commit279f17ac0e1b3d019c2b294098e834d249376686 (patch)
tree47be849d3b35635d167e00cd8448815a75167a23 /manuals/chickadee/Particles.html
parent7b808b9268ec735a7a176d10bf1887b3fa66d13e (diff)
Update chickadee manual.
Diffstat (limited to 'manuals/chickadee/Particles.html')
-rw-r--r--manuals/chickadee/Particles.html263
1 files changed, 263 insertions, 0 deletions
diff --git a/manuals/chickadee/Particles.html b/manuals/chickadee/Particles.html
new file mode 100644
index 0000000..35a6b61
--- /dev/null
+++ b/manuals/chickadee/Particles.html
@@ -0,0 +1,263 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!-- Copyright (C) 2017, 2018, 2019 David Thompson davet@gnu.org
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+A copy of the license is included in the section entitled "GNU
+Free Documentation License".
+
+A copy of the license is also available from the Free Software
+Foundation Web site at http://www.gnu.org/licenses/fdl.html.
+
+
+* Chickadee: (chickadee). Game programming toolkit for Guile.
+
+The document was typeset with
+http://www.texinfo.org/ (GNU Texinfo).
+ -->
+<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<title>Particles (The Chickadee Game Toolkit)</title>
+
+<meta name="description" content="Particles (The Chickadee Game Toolkit)">
+<meta name="keywords" content="Particles (The Chickadee Game Toolkit)">
+<meta name="resource-type" content="document">
+<meta name="distribution" content="global">
+<meta name="Generator" content="makeinfo">
+<link href="index.html#Top" rel="start" title="Top">
+<link href="Index.html#Index" rel="index" title="Index">
+<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
+<link href="Graphics.html#Graphics" rel="up" title="Graphics">
+<link href="Blending.html#Blending" rel="next" title="Blending">
+<link href="Fonts.html#Fonts" rel="prev" title="Fonts">
+<style type="text/css">
+<!--
+a.summary-letter {text-decoration: none}
+blockquote.indentedblock {margin-right: 0em}
+blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
+blockquote.smallquotation {font-size: smaller}
+div.display {margin-left: 3.2em}
+div.example {margin-left: 3.2em}
+div.lisp {margin-left: 3.2em}
+div.smalldisplay {margin-left: 3.2em}
+div.smallexample {margin-left: 3.2em}
+div.smalllisp {margin-left: 3.2em}
+kbd {font-style: oblique}
+pre.display {font-family: inherit}
+pre.format {font-family: inherit}
+pre.menu-comment {font-family: serif}
+pre.menu-preformatted {font-family: serif}
+pre.smalldisplay {font-family: inherit; font-size: smaller}
+pre.smallexample {font-size: smaller}
+pre.smallformat {font-family: inherit; font-size: smaller}
+pre.smalllisp {font-size: smaller}
+span.nolinebreak {white-space: nowrap}
+span.roman {font-family: initial; font-weight: normal}
+span.sansserif {font-family: sans-serif; font-weight: normal}
+ul.no-bullet {list-style: none}
+@media (min-width: 1140px) {
+ body {
+ margin-left: 14rem;
+ margin-right: 4rem;
+ max-width: 52rem;
+ }
+}
+
+@media (min-width: 800px) and (max-width: 1140px) {
+ body {
+ margin-left: 6rem;
+ margin-right: 4rem;
+ max-width: 52rem;
+ }
+}
+
+@media (max-width: 800px) {
+ body {
+ margin: 1rem;
+ }
+}
+
+-->
+</style>
+<link rel="stylesheet" type="text/css" href="https://dthompson.us/css/dthompson.css">
+
+
+</head>
+
+<body lang="en">
+<a name="Particles"></a>
+<div class="header">
+<p>
+Next: <a href="Blending.html#Blending" accesskey="n" rel="next">Blending</a>, Previous: <a href="Fonts.html#Fonts" accesskey="p" rel="prev">Fonts</a>, Up: <a href="Graphics.html#Graphics" accesskey="u" rel="up">Graphics</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p>
+</div>
+<hr>
+<a name="Particles-1"></a>
+<h4 class="subsection">2.3.6 Particles</h4>
+
+<p>Effects like smoke, fire, sparks, etc. are often achieved by animating
+lots of little, short-lived sprites known as &ldquo;particles&rdquo;. In fact,
+all of these effects, and more, can be accomplished by turning a few
+configuration knobs in a &ldquo;particle system&rdquo;. 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)</code> module provides an API for
+manipulating particle systems.
+</p>
+<p>Below is an example of a very simple particle system that utilizes
+nearly all of the default configuration settings:
+</p>
+<div class="example">
+<pre class="example">(use-modules (chickadee render particles))
+(define texture (load-image &quot;particle.png&quot;))
+(define particles (make-particles 2000 #:texture texture))
+</pre></div>
+
+<p>In order to put particles into a particle system, a particle
+&ldquo;emitter&rdquo; is needed. Emitters know where to spawn new particles,
+how many of them to spawn, and for how long they should do it.
+</p>
+<p>Below is an example of an emitter that spawns 16 particles per frame
+at the coordinates <code>(320, 240)</code>:
+</p>
+<div class="example">
+<pre class="example">(use-modules (chickadee math vector))
+(define emitter (make-particle-emitter (vec2 320.0 240.0) 16))
+(add-particle-emitter particles emitter)
+</pre></div>
+
+<p>To see all of the tweakable knobs and switches, read on!
+</p>
+<dl>
+<dt><a name="index-make_002dparticles"></a>Procedure: <strong>make-particles</strong> <em>capacity [#:blend-mode <code>alpha</code>] [#: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]</em></dt>
+<dd>
+<p>Return a new particle system that may contain up to <var>capacity</var>
+particles. Achieving the desired particle effect involves tweaking
+the following keyword arguments as needed:
+</p>
+<p>- <var>blend-mode</var>: Pixel blending mode. <code>alpha</code> by default.
+(see <a href="Blending.html#Blending">Blending</a> for more about blend modes).
+</p>
+<p>- <var>start-color</var>: The tint color of the particle at the beginning of its
+life. White by default.
+</p>
+<p>- <var>end-color</var>: 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&rsquo;s life will be an interpolation of
+<var>start-color</var> and <var>end-color</var>.
+</p>
+<p>- <var>texture</var>: The texture applied to the particles. The texture
+may be subdivided into many animation frames.
+</p>
+<p>- <var>animation-rows</var>: How many animation frame rows there are in the
+texture. Default is 1.
+</p>
+<p>- <var>animation-columns</var>: How many animation frame columns there are
+in the texture. Default is 1.
+</p>
+<p>- <var>width</var>: The width of each particle. By default, the width of
+an animation frame (in pixels) is used.
+</p>
+<p>- <var>height</var>: The height of each particle. By default, the height
+of an animation frame (in pixels) is used.
+</p>
+<p>- <var>speed-range</var>: 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.
+</p>
+<p>- <var>acceleration-range</var>: 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.
+</p>
+<p>- <var>direction-range</var>: 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.
+</p>
+<p>- <var>lifetime</var>: How long each particle lives, measured in
+updates. 30 by default.
+</p>
+<p>- <var>sort</var>: <code>youngest</code> if youngest particle should be drawn
+last or <code>oldest</code> for the reverse. By default, no sorting is
+applied at all.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-particles_003f"></a>Procedure: <strong>particles?</strong> <em>obj</em></dt>
+<dd><p>Return <code>#t</code> if <var>obj</var> is a particle system.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-update_002dparticles"></a>Procedure: <strong>update-particles</strong> <em>particles</em></dt>
+<dd><p>Advance the simulation of <var>particles</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-draw_002dparticles"></a>Procedure: <strong>draw-particles</strong> <em>particles</em></dt>
+<dd><p>Render <var>particles</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-draw_002dparticles_002a"></a>Procedure: <strong>draw-particles*</strong> <em>particles matrix</em></dt>
+<dd><p>Render <var>particles</var> with <var>matrix</var> applied.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-make_002dparticle_002demitter"></a>Procedure: <strong>make-particle-emitter</strong> <em>spawn-area rate [duration]</em></dt>
+<dd>
+<p>Return a new particle emitter that spawns <var>rate</var> particles per
+frame within <var>spawn-area</var> (a rectangle or 2D vector) for
+<var>duration</var> frames. If <var>duration</var> is not specified, the
+emitter will spawn particles indefinitely.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-particle_002demitter_003f"></a>Procedure: <strong>particle-emitter?</strong> <em>obj</em></dt>
+<dd><p>Return <code>#t</code> if <var>obj</var> is a particle emitter.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-particle_002demitter_002dspawn_002darea"></a>Procedure: <strong>particle-emitter-spawn-area</strong> <em>emitter</em></dt>
+<dd><p>Return the spawn area for <var>emitter</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-particle_002demitter_002drate"></a>Procedure: <strong>particle-emitter-rate</strong> <em>emitter</em></dt>
+<dd><p>Return the number of particles that <var>emitter</var> will spawn per
+frame.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-particle_002demitter_002dlife"></a>Procedure: <strong>particle-emitter-life</strong> <em>emitter</em></dt>
+<dd><p>Return the number of frames remaining in <var>emitter</var>&rsquo;s lifespan.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-particle_002demitter_002ddone_003f"></a>Procedure: <strong>particle-emitter-done?</strong> <em>emitter</em></dt>
+<dd><p>Return <code>#t</code> if <var>emitter</var> has finished spawning particlces.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-add_002dparticle_002demitter"></a>Procedure: <strong>add-particle-emitter</strong> <em>particles emitter</em></dt>
+<dd><p>Add <var>emitter</var> to <var>particles</var>.
+</p></dd></dl>
+
+<dl>
+<dt><a name="index-remove_002dparticle_002demitter"></a>Procedure: <strong>remove-particle-emitter</strong> <em>particles emitter</em></dt>
+<dd><p>Remove <var>emitter</var> to <var>particles</var>
+</p></dd></dl>
+
+<hr>
+<div class="header">
+<p>
+Next: <a href="Blending.html#Blending" accesskey="n" rel="next">Blending</a>, Previous: <a href="Fonts.html#Fonts" accesskey="p" rel="prev">Fonts</a>, Up: <a href="Graphics.html#Graphics" accesskey="u" rel="up">Graphics</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p>
+</div>
+
+
+
+</body>
+</html>