summaryrefslogtreecommitdiff
path: root/doc/api.texi
diff options
context:
space:
mode:
authorDavid Thompson <dthompson2@worcester.edu>2021-03-14 13:02:15 -0400
committerDavid Thompson <dthompson2@worcester.edu>2021-03-14 13:02:15 -0400
commitfec2bca489fa67f67bb6047215ebceb831305109 (patch)
tree02d5b19e67e72c63506016e70128d63ebe9b0267 /doc/api.texi
parent6c652d155fe6af7af0d151c5187b8c4ed8abba2b (diff)
graphics: blend: Add proper <blend-mode> data type.
No more symbols. Hooray!
Diffstat (limited to 'doc/api.texi')
-rw-r--r--doc/api.texi101
1 files changed, 82 insertions, 19 deletions
diff --git a/doc/api.texi b/doc/api.texi
index 07005a6..5fa18b3 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -1965,7 +1965,7 @@ interface for working with sprites. Bitmaps are stored in textures
@code{draw-sprite} procedure.
@deffn {Procedure} draw-sprite texture position @
- [#:tint white] [#:origin] [#:scale] [#:rotation] [#:blend-mode alpha] @
+ [#:tint white] [#:origin] [#:scale] [#:rotation] [#:blend-mode] @
[#:rect]
Draw @var{texture} at @var{position}.
@@ -2036,7 +2036,7 @@ See @code{draw-sprite} for information about the other arguments.
Reset size of @var{batch} to 0.
@end deffn
-@deffn {Procedure} draw-sprite-batch batch [#:blend-mode @code{alpha}]
+@deffn {Procedure} draw-sprite-batch batch [#:blend-mode]
Render @var{batch} using @var{blend-mode}. Alpha blending is used by
default.
@end deffn
@@ -2071,7 +2071,7 @@ artifacts.
@deffn {Procedure} draw-nine-patch texture rect @
[#:margin 0] [#:top-margin margin] [#:bottom-margin margin] @
[#:left-margin margin] [#:right-margin margin] @
- [#:origin] [#:scale] [#:rotation] [#:blend-mode alpha] @
+ [#:origin] [#:scale] [#:rotation] [#:blend-mode] @
[#:tint white]
Draw a nine patch sprite. A nine patch sprite renders @var{texture}
@@ -2410,7 +2410,7 @@ at the coordinates @code{(320, 240)}:
To see all of the tweakable knobs and switches, read on!
-@deffn {Procedure} make-particles capacity [#:blend-mode @code{alpha}] @
+@deffn {Procedure} make-particles capacity [#:blend-mode] @
[#: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)] @
@@ -2420,7 +2420,7 @@ 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.
+- @var{blend-mode}: Pixel blending mode. Alpha blending is used by default.
(@pxref{Blending} for more about blend modes).
- @var{start-color}: The tint color of the particle at the beginning of its
@@ -2789,36 +2789,99 @@ and @var{view-matrix} applied.
Rendering a scene often involves drawing layers of objects that
overlap each other. Blending determines how two overlapping pixels
are combined in the final image that is rendered to the screen.
-Chickadee provides the following blend modes:
-
-@itemize
-@item @code{replace}
-Use the latest color, ignoring all others.
+Chickadee provides the following blend modes:
-@item @code{alpha}
+@defvar blend:alpha
Blend pixels according to the values of their alpha channels. This is
-the most commonly used blend mode and thus is Chickadee's default
-mode.
+the most commonly used blend mode.
+@end defvar
-@item @code{add}
+@defvar blend:replace
+Overwrite the output pixel color with the color being drawn.
+@end defvar
+
+@defvar blend:add
Add all pixel color values together. The more colors blended
together, the more white the final color becomes.
+@end defvar
-@item @code{subtract}
+@defvar blend:subtract
Subtract all pixel color values. The more colors blended together,
the more black the final color becomes.
+@end defvar
+
+@defvar blend:multiply
+@end defvar
-@item @code{multiply}
+@defvar blend:darken
+@end defvar
-@item @code{darken}
+@defvar blend:lighten
+@end defvar
-@item @code{lighten}
+@defvar blend:screen
+@end defvar
-@item @code{screen}
+Custom blend modes can be created using the @code{make-blend-mode} procedure:
+@deffn {Procedure} make-blend-mode equation source-function destination-function
+Return a new custom blend mode that applies @var{source-function} to
+the source color, @var{destination-function} to the destination color,
+and finally applies @var{equation} to the transformed
+source/destination color values. These arguments are @emph{not}
+procedures, but symbolic representations of the functions that OpenGL
+supports.
+
+Valid values for @var{equation} are:
+
+@itemize
+@item @code{add}
+@item @code{subtract}
+@item @code{reverse-subtract}
+@item @code{min}
+@item @code{max}
+@item @code{alpha-min}
+@item @code{alpha-max}
@end itemize
+Valid values for @var{source-function} are:
+
+@itemize
+@item @code{zero}
+@item @code{one}
+@item @code{destination-color}
+@item @code{one-minus-destination-color}
+@item @code{source-alpha-saturate}
+@item @code{source-alpha}
+@item @code{one-minus-source-alpha}
+@item @code{destination-alpha}
+@item @code{one-minus-destination-alpha}
+@item @code{constant-color}
+@item @code{one-minus-constant-color}
+@item @code{constant-alpha}
+@item @code{one-minus-constant-alpha}
+@end itemize
+
+Valid values for @var{destination-function} are:
+
+@itemize
+@item @code{zero}
+@item @code{one}
+@item @code{source-color}
+@item @code{one-minus-source-color}
+@item @code{source-alpha}
+@item @code{one-minus-source-alpha}
+@item @code{destination-alpha}
+@item @code{one-minus-destination-alpha}
+@item @code{constant-color}
+@item @code{one-minus-constant-color}
+@item @code{constant-alpha}
+@item @code{one-minus-constant-alpha}
+@end itemize
+
+@end deffn
+
@node Framebuffers
@subsection Framebuffers