graphics: blend: Add proper <blend-mode> data type.

No more symbols.  Hooray!

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