doc: Add "Colors" section.

1 files changed, 233 insertions, 0 deletions

diff --git a/doc/api.texi b/doc/api.texi
index 3992c06..99fadce 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -1475,6 +1475,7 @@ tasks like rendering a sprite while also providing all of the building
 blocks to implement additional rendering techniques.
 
 @menu
+* Colors::                      Such pretty colors...
 * Textures::                    2D images.
 * Sprites::                     Draw 2D images.
 * Tile Maps::                   Draw 2D tile maps.
@@ -1489,6 +1490,238 @@ blocks to implement additional rendering techniques.
 * Shaders::                     Create custom GPU programs.
 @end menu
 
+@node Colors
+@subsection Colors
+
+Merriam-Webster defines color as ``a phenomenon of light (such as red,
+brown, pink, or gray) or visual perception that enables one to
+differentiate otherwise identical objects.''  In this essay, I
+will@dots{}
+
+Okay, okay.  We all know what colors are.  Chickadee provides a data
+type to represent color and some convenient procedures to work with
+them in the @code{(chickadee render color)} module.  Colors are made
+up of four components, or channels: red, green, blue, and alpha
+(transparency.)  Each of these values is expressed as a uniform
+floating point value in the range [0, 1].  0 means that color channel
+is unrepresented in the resulting color, whereas 1 means that color
+channel is at full intensity.
+
+Making a color object is easy, and there's a few ways to do it
+depending on what's most convenient.  The first is @code{make-color},
+where you specify each channel exactly as described above.  This is
+fully opaque magenta:
+
+@example
+(make-color 1.0 0.0 1.0 1.0)
+@end example
+
+Many people are used to representing colors as 6 or 8 digit
+hexadecimal numbers, so Chickadee also allows that.  Here's magenta,
+again:
+
+@example
+(rgba #xFF00FFFF)
+(rgb #xFF00FF) ; equivalent to the above
+@end example
+
+@deffn {Procedure} make-color r g b a
+Return a new color object with a red value of @var{r}, a green value
+of @var{g}, a blue value of @var{b}, and an alpha (transparency) value
+of @var{a}.  All values are clamped to the range [0, 1].
+@end deffn
+
+@deffn {Procedure} rgba color-code
+Return a new color object using the values of the first 32 bits of
+@var{color-code}.  Each channel occupies 8 bits.  Starting from the
+most significant bit, red is first, followed by green, then blue, then
+alpha.  Color codes are often represented as 6 or 8 digit hexadecimal
+numbers in various other programs.
+@end deffn
+
+@deffn {Procedure} rgb color-code
+Like @code{rgba}, but @var{color-code} is a 24 bit code with no alpha
+channel.
+@end deffn
+
+@deffn {Procedure} color? obj
+Return @code{#t} if @var{obj} is a color object.
+@end deffn
+
+@deffn {Procedure} color-r color
+Return the red channel of @var{color}.
+@end deffn
+
+@deffn {Procedure} color-g color
+Return the green channel of @var{color}.
+@end deffn
+
+@deffn {Procedure} color-b color
+Return the blue channel of @var{color}.
+@end deffn
+
+@deffn {Procedure} color-a color
+Return the alpha channel of @var{color}.
+@end deffn
+
+@deffn {Procedure} transparency alpha
+Return a new color that is white (RGB channels set to 1) with an alpha
+channel value of @var{alpha}.  This can be useful for creating a color
+that can be multiplied against another color to make it more
+transparent.
+@end deffn
+
+@deffn {Procedure} string->color s
+Convert the hexadecimal color code in the string @var{s} to a color
+object.  The following string formats are supported:
+
+@example
+(string->color "#FF00FFFF")
+(string->color "FF00FFFF")
+(string->color "#FF00FF")
+(string->color "FF00FF")
+@end example
+
+@end deffn
+
+@deffn {Procedure} color* a b
+Multiply the color @var{a} with the color or number @var{b} and return
+a new color with the result.
+@end deffn
+
+@deffn {Procedure} color+ a b
+Add the color @var{a} to the color @var{b} and return a new color with
+the result.
+@end deffn
+
+@deffn {Procedure} color- a b
+Subtract the color @var{b} from the color @var{a} and return a new
+color with the result.
+@end deffn
+
+@deffn {Procedure} color-inverse color
+Invert the red, green, and blue channels of @var{color} and return a
+new color with the result.
+@end deffn
+
+@deffn {Procedure} color-lerp start end alpha
+Linearly interpolate the colors @var{start} and @var{end} using the
+factor @var{alpha}, a number in the range [0, 1].
+@end deffn
+
+@subsubsection Stock Colors
+
+For convenience, Chickadee comes with some basic colors predefined:
+
+@defvar white
+@end defvar
+
+@defvar black
+@end defvar
+
+@defvar red
+@end defvar
+
+@defvar green
+@end defvar
+
+@defvar blue
+@end defvar
+
+@defvar yellow
+@end defvar
+
+@defvar magenta
+@end defvar
+
+@defvar cyan
+@end defvar
+
+For fun, there are also predefined colors for the classic
+@url{https://en.wikipedia.org/wiki/Tango_Desktop_Project#Palette,
+Tango color palette}.
+
+@defvar tango-light-butter
+@end defvar
+
+@defvar tango-butter
+@end defvar
+
+@defvar tango-dark-butter
+@end defvar
+
+@defvar tango-light-orange
+@end defvar
+
+@defvar tango-orange
+@end defvar
+
+@defvar tango-dark-orange
+@end defvar
+
+@defvar tango-light-chocolate
+@end defvar
+
+@defvar tango-chocolate
+@end defvar
+
+@defvar tango-dark-chocolate
+@end defvar
+
+@defvar tango-light-chameleon
+@end defvar
+
+@defvar tango-chameleon
+@end defvar
+
+@defvar tango-dark-chameleon
+@end defvar
+
+@defvar tango-light-sky-blue
+@end defvar
+
+@defvar tango-sky-blue
+@end defvar
+
+@defvar tango-dark-sky-blue
+@end defvar
+
+@defvar tango-light-plum
+@end defvar
+
+@defvar tango-plum
+@end defvar
+
+@defvar tango-dark-plum
+@end defvar
+
+@defvar tango-light-scarlet-red
+@end defvar
+
+@defvar tango-scarlet-red
+@end defvar
+
+@defvar tango-dark-scarlet-red
+@end defvar
+
+@defvar tango-aluminium-1
+@end defvar
+
+@defvar tango-aluminium-2
+@end defvar
+
+@defvar tango-aluminium-3
+@end defvar
+
+@defvar tango-aluminium-4
+@end defvar
+
+@defvar tango-aluminium-5
+@end defvar
+
+@defvar tango-aluminium-6
+@end defvar
+
 @node Textures
 @subsection Textures