diff options
Diffstat (limited to 'manuals/chickadee/Sprites.html')
| -rw-r--r-- | manuals/chickadee/Sprites.html | 87 |
1 files changed, 61 insertions, 26 deletions
diff --git a/manuals/chickadee/Sprites.html b/manuals/chickadee/Sprites.html index 29d16ea..a0e308b 100644 --- a/manuals/chickadee/Sprites.html +++ b/manuals/chickadee/Sprites.html @@ -1,6 +1,6 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> -<!-- Copyright (C) 2017 David Thompson davet@gnu.org +<!-- 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 @@ -13,6 +13,8 @@ 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). --> @@ -94,7 +96,7 @@ Next: <a href="Tile-Maps.html#Tile-Maps" accesskey="n" rel="next">Tile Maps</a>, </div> <hr> <a name="Sprites-1"></a> -<h4 class="subsection">2.3.3 Sprites</h4> +<h4 class="subsection">2.3.2 Sprites</h4> <p>For those who are new to this game, a sprite is a 2D rectangular bitmap that is rendered to the screen. For 2D games, sprites are the @@ -104,7 +106,7 @@ stored in textures (see <a href="Textures.html#Textures">Textures</a>) and can b via the <code>draw-sprite</code> procedure. </p> <dl> -<dt><a name="index-draw_002dsprite"></a>Procedure: <strong>draw-sprite</strong> <em><var>texture</var> <var>position</var> [#:origin] [#:scale] [#:rotation] [#:blend-mode alpha] [#:rect] [#:shader]</em></dt> +<dt><a name="index-draw_002dsprite"></a>Procedure: <strong>draw-sprite</strong> <em>texture position [#:tint white] [#:origin] [#:scale] [#:rotation] [#:blend-mode alpha] [#:rect]</em></dt> <dd> <p>Draw <var>texture</var> at <var>position</var>. </p> @@ -114,47 +116,80 @@ via the <code>draw-sprite</code> procedure. transformations are applied relative to <var>origin</var>, a 2D vector, which defaults to the lower-left corner. </p> +<p><var>tint</var> specifies the color to multiply against all the sprite’s +pixels. By default white is used, which does no tinting at all. +</p> <p>Alpha blending is used by default but the blending method can be changed by specifying <var>blend-mode</var>. </p> <p>The area drawn to is as big as the texture, by default. To draw to an arbitrary section of the screen, specify <var>rect</var>. -</p> -<p>Finally, advanced users may specify <var>shader</var> to change the way the -sprite is rendered entirely. </p></dd></dl> <p>It’s not uncommon to need to draw hundreds or thousands of sprites each frame. However, GPUs (graphics processing units) are tricky beasts that prefer to be sent few, large chunks of data to render rather than many, small chunks. Using <code>draw-sprite</code> on its own -will involve at least one GPU call <em>per sprite</em>, which will -quickly lead to poor performance. To deal with this, a technique -known as “sprite batching” can be used. Instead of drawing each -sprite immediately, the sprite batch will build up a large of buffer -of sprites to draw and defer rendering until the last possible moment. -Batching isn’t a panacea, though. Batching only works if the sprites -being drawn share as much in common as possible. Every time you draw -a sprite with a different texture or blend mode, the batch will be -sent off to the GPU. Therefore, batching is most useful if you -minimize such changes. A good strategy for reducing texture changes -is to stuff many bitmaps into a single image file and create a -“texture atlas” (see <a href="Textures.html#Textures">Textures</a>) to access the sub-images within. +will involve at least one GPU call <em>per sprite</em>. This is fine +for rendering a few dozen sprites, but will become a serious +bottleneck when rendering hundreds or thousands of sprites. To deal +with this, a technique known as “sprite batching” is used. Instead +of drawing each sprite immediately, the sprite batch will build up a +large of buffer of sprites to draw and send them to the GPU all at +once. There is one caveat, however. Batching only works if the +sprites being drawn share a common texture. A good strategy for +reducing the number of different textures is to stuff many bitmaps +into a single image file and create a “texture atlas” +(see <a href="Textures.html#Textures">Textures</a>) to access the sub-images within. </p> -<p>Taking advantage of sprite batching in Chickadee is easy, just wrap -the code that is calling <code>draw-sprite</code> a lot in the -<code>with-batched-sprites</code> form. +<dl> +<dt><a name="index-make_002dsprite_002dbatch"></a>Procedure: <strong>make-sprite-batch</strong> <em>texture [#:capacity 256]</em></dt> +<dd><p>Create a new sprite batch for <var>texture</var> with initial space for +<var>capacity</var> sprites. Sprite batches automatically resize when they +are full to accomodate as many sprites as necessary. +</p></dd></dl> + +<dl> +<dt><a name="index-sprite_002dbatch_003f"></a>Procedure: <strong>sprite-batch?</strong> <em>obj</em></dt> +<dd><p>Return <code>#t</code> if <var>obj</var> is a sprite batch. +</p></dd></dl> + +<dl> +<dt><a name="index-sprite_002dbatch_002dtexture"></a>Procedure: <strong>sprite-batch-texture</strong> <em>batch</em></dt> +<dd><p>Return the texture for <var>batch</var>. +</p></dd></dl> + +<dl> +<dt><a name="index-set_002dsprite_002dbatch_002dtexture_0021"></a>Procedure: <strong>set-sprite-batch-texture!</strong> <em>batch texture</em></dt> +<dd><p>Set texture for <var>batch</var> to <var>texture</var>. +</p></dd></dl> + +<dl> +<dt><a name="index-sprite_002dbatch_002dadd_0021"></a>Procedure: <strong>sprite-batch-add!</strong> <em>batch position [#:origin] [#:scale] [:rotation] [#:tint <code>white</code>] [#:texture-region]</em></dt> +<dd> +<p>Add sprite located at <var>position</var> to <var>batch</var>. +</p> +<p>To render a subsection of the batch’s texture, a texture object whose +parent is the batch texture may be specified as <var>texture-region</var>. </p> +<p>See <code>draw-sprite</code> for information about the other arguments. +</p></dd></dl> + +<dl> +<dt><a name="index-sprite_002dbatch_002dclear_0021"></a>Procedure: <strong>sprite-batch-clear!</strong> <em>batch</em></dt> +<dd><p>Reset size of <var>batch</var> to 0. +</p></dd></dl> + <dl> -<dt><a name="index-with_002dbatched_002dsprites"></a>Syntax: <strong>with-batched-sprites</strong> <em><var>body</var> …</em></dt> -<dd><p>Use batched rendering for all <code>draw-sprite</code> calls within -<var>body</var>. +<dt><a name="index-draw_002dsprite_002dbatch"></a>Procedure: <strong>draw-sprite-batch</strong> <em>batch [#:blend-mode <code>alpha</code>]</em></dt> +<dd><p>Render <var>batch</var> using <var>blend-mode</var>. Alpha blending is used by +default. </p></dd></dl> <p>With a basic sprite abstraction in place, it’s possible to build other abstractions on top of it. One such example is the “nine patch”. A nine patch is a sprite that can be rendered at various sizes without -becoming distorted. This is achieved by diving up the sprite into +becoming distorted. This is achieved by dividing up the sprite into nine regions: </p> <ul> @@ -175,7 +210,7 @@ patch, they can be rendered at any size without unappealing scaling artifacts. </p> <dl> -<dt><a name="index-draw_002dnine_002dpatch"></a>Procedure: <strong>draw-nine-patch</strong> <em><var>texture</var> <var>rect</var> [#:margin 0] [#:top-margin margin] [#:bottom-margin margin] [#:left-margin margin] [#:right-margin margin] [#:origin] [#:scale] [#:rotation] [#:blend-mode alpha] [#:shader]</em></dt> +<dt><a name="index-draw_002dnine_002dpatch"></a>Procedure: <strong>draw-nine-patch</strong> <em>texture rect [#:margin 0] [#:top-margin margin] [#:bottom-margin margin] [#:left-margin margin] [#:right-margin margin] [#:origin] [#:scale] [#:rotation] [#:blend-mode alpha] [#:tint white]</em></dt> <dd> <p>Draw a nine patch sprite. A nine patch sprite renders <var>texture</var> as a <var>width</var> x <var>height</var> rectangle whose stretchable areas are |