doc: Add more documentation!

1 files changed, 273 insertions, 1 deletions

diff --git a/doc/api.texi b/doc/api.texi
index 8633883..4ea97fb 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -3,6 +3,7 @@
 * Input::                       Keyboard, mouse, and controller input.
 * Math::                        Linear algebra and more.
 * Graphics::                    Eye candy.
+* Audio::                       Sound effects and music.
 @end menu
 
 @node Kernel
@@ -111,7 +112,7 @@ position and its previous position.  This odd trick has the pleasing
 result of making the animation look smooth again, but requires keeping
 track of previous state.
 
-(TODO: Add example of linear interpolation)
+@c TODO: Add example of linear interpolation
 
 @example
 (add-hook! draw-hook (lambda (alpha) (display "<(._.<) \n")))
@@ -119,11 +120,282 @@ track of previous state.
 
 @end defvr
 
+@defvr {Scheme Variable} quit-hook
+A hook that is run when the user clicks the close button on the game
+window.  This hook is run with zero arguments.
+
+@example
+(add-hook! quit-hook (lambda () (display "bye!\n")))
+@end example
+
+@end defvr
+
+@defvr {Scheme Variable} key-press-hook
+A hook that is run when a key is pressed on the keyboard.  This hook
+is run with four arguments:
+
+@enumerate
+@item
+@var{key}: The symbolic name of the ``virtual'' key that was pressed.
+For example: @code{backspace}.  It's called a virtual key because the
+operating system may map a physical keyboard key to another key
+entirely, such as how the author binds the ``caps lock'' key to mean
+``control''.
+
+@item
+@var{scancode}: The symbolic name of the physical key that was
+pressed.
+
+@item
+@var{modifiers}: A list of the symbolic names of modifier keys that
+were being held down when the key was pressed.  Possible values
+include @code{ctrl}, @code{alt}, and @code{shift}.
+
+@item
+@var{repeat?}: @code{#t} if this is a repeated press of the same key.
+
+@end enumerate
+
+@example
+(add-hook! key-press-hook
+           (lambda (key scancode modifiers repeat?)
+             (display "pressed key: ")
+             (display key)
+             (newline)))
+@end example
+
+@end defvr
+
+@defvr {Scheme Variable} key-release-hook
+A hook that is run when a key is released on the keyboard.  This hook
+is run with three arguments:
+
+@enumerate
+@item
+@var{key}: The symbolic name of the ``virtual'' key that was released.
+
+@item
+@var{scancode}: The symbolic name of the physical key that was
+released.
+
+@item
+@var{modifiers}: A list of the symbolic names of modifier keys that
+were being held down when the key was released.
+
+@end enumerate
+
+@end defvr
+
+@defvr {Scheme Variable} text-input-hook
+A hook that is run when printable text is typed on the keyboard.  This
+hook is run with a single argument, @var{text}, a string containing
+the text that was entered.
+@end defvr
+
+@defvr {Scheme Variable} mouse-press-hook
+A hook that is run when a mouse button is pressed.
+@end defvr
+
+@defvr {Scheme Variable} mouse-release-hook
+A hook that is run when a mouse button is released.
+@end defvr
+
+@defvr {Scheme Variable} mouse-move-hook
+A hook that is run when the mouse is moved.
+@end defvr
+
+@defvr {Scheme Variable} controller-add-hook
+A hook that is run when a game controller is connected.
+@end defvr
+
+@defvr {Scheme Variable} controller-remove-hook
+A hook that is run when a game controller is disconnected.
+@end defvr
+
+@defvr {Scheme Variable} controller-press-hook
+A hook that is run when a button on a game controller is pressed.
+@end defvr
+
+@defvr {Scheme Variable} controller-release-hook
+A hook that is run when a button on a game controller is released.
+@end defvr
+
+@defvr {Scheme Variable} controller-move-hook
+A hook that is run when an analog stick or trigger on a game
+controller is moved.
+@end defvr
+
 @node Input
 @section Input
 
 @node Math
 @section Math
 
+Chickadee contains data types and procedures for performing the most
+common computations in video game simulations such as linear algebra
+with vectors and matrices and axis-aligned bounding box collision
+detection.
+
+@menu
+* Vectors::                     Euclidean vectors.
+* Matrices::                    Transformation matrices.
+* Rectangles::                  Axis-aligned bounding boxes.
+@end menu
+
+@node Vectors
+@subsection Vectors
+
+@node Matrices
+@subsection Matrices
+
+@node Rectangles
+@subsection Rectangles
+
 @node Graphics
 @section Graphics
+
+Chickadee aims to make hardware-accelerated graphics rendering as
+simple and efficient as possible by providing high-level APIs that
+interact with the low-level OpenGL API under the hood.  Anyone that
+has worked with OpenGL directly knows that it has a steep learning
+curve and a lot of effort is needed to render even a single triangle.
+The Chickadee rendering engine attempts to make it easy to do common
+tasks like rendering a sprite while also providing all of the building
+blocks to implement additional rendering techniques.
+
+@menu
+* Rendering Engine::            Rendering state management.
+* Sprites::                     Draw 2D images.
+* Lines and Shapes::            Draw line segments and polygons.
+* Textures::                    2D images.
+* Blending and Depth Testing::  Control how pixels are combined.
+* Vertex Arrays::               Create 2D/3D models.
+* Shaders::                     Create custom GPU programs.
+* Framebuffers::                Render to texture.
+* Viewports::                   Restrict rendering to
+@end menu
+
+@node Rendering Engine
+@subsection Rendering Engine
+
+Chickadee defines rendering using a metaphor familiar to Scheme
+programmers: procedure application.  A shader (@pxref{Shaders}) is
+like a procedure for the GPU to apply.  Shaders are passed arguments:
+A vertex array containing the geometry to render (@pxref{Vertex
+Arrays}) and zero or more keyword arguments that the shader
+understands.  Similar to how Scheme has @code{apply} for calling
+procedures, Chickadee provides @code{gpu-apply} for calling shaders.
+
+Additionally, there is some dynamic state that effects how
+@code{gpu-apply} will behave.  Things like the current viewport,
+framebuffer, and blend mode are stored as dynamic state because it
+would be tedious to have to have to specify them each time
+@code{gpu-apply} is called.
+
+The following procedures and syntax can be found in the
+@code{(chickadee render)} module.
+
+@deffn {Scheme Syntax} gpu-apply @var{shader} @var{vertex-array} [#:uniform-key @var{uniform-value} ...]
+@deffnx {Scheme Syntax} gpu-apply* @var{shader} @var{vertex-array} @var{count} [#:uniform-key @var{uniform-value} ...]
+
+Render @var{vertex-array} using @var{shader} with the uniform values
+specified in the following keyword arguments.
+
+While @code{gpu-apply} will draw every vertex in @var{vertex-array},
+@code{gpu-apply*} will only draw @var{count} vertices.
+
+@end deffn
+
+@deffn {Scheme Procedure} current-viewport
+Return the currently bound viewport.  @xref{Viewports} for more
+details about using viewports.
+@end deffn
+
+@deffn {Scheme Procedure} current-framebuffer
+Return the currently bound framebuffer.  @xref{Framebuffers} for more
+details about using framebuffers.
+@end deffn
+
+@deffn {Scheme Procedure} current-blend-mode
+Return the currently bound blend mode.  @xref{Blending and Depth
+Testing} for more details about using blend modes.
+@end deffn
+
+@deffn {Scheme Procedure} current-depth-test
+Return @code{#t} if depth testing is currently enabled.
+@xref{Blending and Depth Testing} for more details about using the
+depth test.
+@end deffn
+
+@deffn {Scheme Procedure} current-texture
+Return the currently bound texture.  @xref{Textures} for more details
+about using textures.
+@end deffn
+
+@deffn {Scheme Procedure} current-projection
+Return the currently bound projection matrix.  @xref{Matrices} for
+more details about matrices.
+@end deffn
+
+@deffn {Scheme Syntax} with-viewport @var{viewport} @var{body} ...
+Evaluate @var{body} with the current viewport bound to @var{viewport}.
+@end deffn
+
+@deffn {Scheme Syntax} with-framebuffer @var{framebuffer} @var{body} ...
+Evaluate @var{body} with the current framebuffer bound to
+@var{framebuffer}.
+@end deffn
+
+@deffn {Scheme Syntax} with-blend-mode @var{blend-mode} @var{body} ...
+Evaluate @var{body} with the current blend mode bound to
+@var{blend-mode}.
+@end deffn
+
+@deffn {Scheme Syntax} with-depth-test @var{depth-test?} @var{body} ...
+Evaluate @var{body} with the depth-test disabled if @var{depth-test?}
+is @code{#f}, or enabled otherwise.
+@end deffn
+
+@deffn {Scheme Syntax} with-texture @var{texture} @var{body} ...
+Evaluate @var{body} with the current texture bound to @var{texture}.
+@end deffn
+
+@deffn {Scheme Syntax} with-projection @var{projection} @var{body} ...
+Evaluate @var{body} with the current projection matrix bound to
+@var{projection}.
+@end deffn
+
+@node Sprites
+@subsection Sprites
+
+@node Lines and Shapes
+@subsection Lines and Shapes
+
+@node Textures
+@subsection Textures
+
+@node Blending and Depth Testing
+@subsection Blending and Depth Testing
+
+@node Vertex Arrays
+@subsection Vertex Arrays
+
+@node Shaders
+@subsection Shaders
+
+Shaders are programs for the GPU to evaluate.  They are written in the
+OpenGL Shading Language, or GLSL.  Chickadee does not currently
+provide a Scheme-like domain specific language for writing shaders.
+Since shaders must be written in GLSL and not Scheme, they are
+considered an advanced feature.
+
+@node Framebuffers
+@subsection Framebuffers
+
+@node Viewports
+@subsection Viewports
+
+@node Audio
+@section Audio
+
+There is no audio support yet.  Stay tuned!