diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api.texi | 233 |
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 |