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