summaryrefslogtreecommitdiff
path: root/doc/api.texi
diff options
context:
space:
mode:
authorDavid Thompson <dthompson2@worcester.edu>2019-05-10 08:34:53 -0400
committerDavid Thompson <dthompson2@worcester.edu>2019-05-12 11:38:43 -0400
commit34975b307a85cbb34b040b8a0c6a0f9104b4c331 (patch)
tree26e27980c64491026eaa1d1d51af9c861d5f7102 /doc/api.texi
parentdd1ccc8afc8ec0411ac636f542fd4bb8d4d242af (diff)
render: sprite: Rewrite sprite batching API.
This new version performs better and has a better API. It closely resembles Love2D's sprite batch API. * chickadee/render/sprite.scm (with-batched-sprites, sprite-batch-reset!, sprite-batch-begin!, draw-sprite-batched, *batch?*, %batch): Delete. (draw-sprite-unbatched): Rename to 'draw-sprite*'. (<sprite-batch>)[index-buffer, position-buffer, texture-buffer]: Delete fields. [vertex-buffer]: New field. (init-sprite-batch, double-sprite-batch-size!, sprite-batch-add!, sprite-batch-flush!): Rewrite. (make-sprite-batch): Add 'capacity' and 'blend-mode' arguments. (draw-sprite-batch): New procedure. (draw-nine-patch*): Stop using sprite batches for now. * chickadee/render/font.scm: (<font>)[sprite-batches]: New field. (load-tile-font, load-font): Create a sprite batch for each texture loaded. (draw-text*): Use sprite batches. * chickadee/render/tiled.scm: (<tile>)[batch]: New field. (<tileset>)[batch]: New field. (load-tile-map): Create a sprite batch for each tileset. (draw-tile-layer): Use new sprite batch API. (draw-tile-map*): Remove reference to deleted macro.
Diffstat (limited to 'doc/api.texi')
-rw-r--r--doc/api.texi69
1 files changed, 49 insertions, 20 deletions
diff --git a/doc/api.texi b/doc/api.texi
index 6669b5f..473e3b9 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -1359,26 +1359,55 @@ 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} on its own
-will involve at least one GPU call @emph{per sprite}, 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'' (@pxref{Textures}) to access the sub-images within.
-
-Taking advantage of sprite batching in Chickadee is easy, just wrap
-the code that is calling @code{draw-sprite} a lot in the
-@code{with-batched-sprites} form.
-
-@deffn {Syntax} with-batched-sprites @var{body} @dots{}
-Use batched rendering for all @code{draw-sprite} calls within
-@var{body}.
+will involve at least one GPU call @emph{per sprite}. 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''
+(@pxref{Textures}) to access the sub-images within.
+
+@deffn {Procedure} make-sprite-batch @var{texture} [#:capacity 256]
+Create a new sprite batch for @var{texture} with initial space for
+@var{capacity} sprites. Sprite batches automatically resize when they
+are full to accomodate as many sprites as necessary.
+@end deffn
+
+@deffn {Procedure} sprite-batch? @var{obj}
+Return @code{#t} if @var{obj} is a sprite batch.
+@end deffn
+
+@deffn {Procedure} sprite-batch-texture @var{batch}
+Return the texture for @var{batch}.
+@end deffn
+
+@deffn {Procedure} set-sprite-batch-texture! @var{batch} @var{texture}
+Set texture for @var{batch} to @var{texture}.
+@end deffn
+
+@deffn {Procedure} sprite-batch-add! @var{batch} @var{position} @@
+ [#:origin] [#:scale] [:rotation] @@
+ [#:tint @code{white}] [#:texture-region]
+
+Add sprite located at @var{position} to @var{batch}.
+
+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}.
+
+See @code{draw-sprite} for information about the other arguments.
+@end deffn
+
+@deffn {Procedure} sprite-batch-clear! @var{batch}
+Reset size of @var{batch} to 0.
+@end deffn
+
+@deffn {Procedure} draw-sprite-batch @var{batch} [#:blend-mode @code{alpha}]
+Render @var{batch} using @var{blend-mode}. Alpha blending is used by
+default.
@end deffn
With a basic sprite abstraction in place, it's possible to build other