diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api.texi | 222 |
1 files changed, 111 insertions, 111 deletions
diff --git a/doc/api.texi b/doc/api.texi index f3878f5..eaad84e 100644 --- a/doc/api.texi +++ b/doc/api.texi @@ -33,7 +33,7 @@ There are many hooks available, so read on to learn about all of them. For information about using Guile's hook API, see @xref{Hooks,,, guile, GNU Guile Reference Manual}. -@deffn {Scheme Procedure} run-game [#:window-title "Chickadee!"] @ +@deffn {Procedure} run-game [#:window-title "Chickadee!"] @ [#:window-width 640] [#:window-height 480] [#:window-fullscreen? #f] @ [#:update-hz 60] @@ -48,15 +48,15 @@ title, and in fullscreen mode if @var{window-fullscreen?} is @code{#t}. @end deffn -@deffn {Scheme Procedure} abort-game +@deffn {Procedure} abort-game Stop the currently running Chickadee event loop. @end deffn -@deffn {Scheme Procedure} time +@deffn {Procedure} time Return the current game time in milliseconds. @end deffn -@defvr {Scheme Variable} load-hook +@defvr {Variable} load-hook A hook that is run once when the event loop boots, before any other hook is run. This hook is run with zero arguments. @@ -66,7 +66,7 @@ hook is run. This hook is run with zero arguments. @end defvr -@defvr {Scheme Variable} update-hook +@defvr {Variable} update-hook A hook that is run every time the game simulation should be advanced. This hook is run with a single argument @var{dt}, the fixed timestep that was configured when the event loop was started, in milliseconds. @@ -77,7 +77,7 @@ that was configured when the event loop was started, in milliseconds. @end defvr -@defvr {Scheme Variable} before-draw-hook +@defvr {Variable} before-draw-hook A hook that is run before a frame is rendered. This hook is run with zero arguments. @@ -87,7 +87,7 @@ zero arguments. @end defvr -@defvr {Scheme Variable} after-draw-hook +@defvr {Variable} after-draw-hook A hook that is run after a frame is rendered. This hook is run with zero arguments. @@ -100,7 +100,7 @@ second calculation to monitor game performance and stability. @end defvr -@defvr {Scheme Variable} draw-hook +@defvr {Variable} draw-hook A hook that is run each time a frame should be rendered. This hook is run with a single argument @var{alpha}, a value in the range [0, 1] which represents how much time has past since the last game state @@ -123,7 +123,7 @@ track of previous state. @end defvr -@defvr {Scheme Variable} quit-hook +@defvr {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. @@ -133,7 +133,7 @@ window. This hook is run with zero arguments. @end defvr -@defvr {Scheme Variable} key-press-hook +@defvr {Variable} key-press-hook A hook that is run when a key is pressed on the keyboard. This hook is run with four arguments: @@ -169,7 +169,7 @@ include @code{ctrl}, @code{alt}, and @code{shift}. @end defvr -@defvr {Scheme Variable} key-release-hook +@defvr {Variable} key-release-hook A hook that is run when a key is released on the keyboard. This hook is run with three arguments: @@ -189,13 +189,13 @@ were being held down when the key was released. @end defvr -@defvr {Scheme Variable} text-input-hook +@defvr {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 +@defvr {Variable} mouse-press-hook A hook that is run when a mouse button is pressed. This hook is run with four arguments: @@ -218,7 +218,7 @@ as @code{left}, @code{middle}, or @code{right}. @end defvr -@defvr {Scheme Variable} mouse-release-hook +@defvr {Variable} mouse-release-hook A hook that is run when a mouse button is released. This hook is run with three arguments: @@ -237,7 +237,7 @@ with three arguments: @end defvr -@defvr {Scheme Variable} mouse-move-hook +@defvr {Variable} mouse-move-hook A hook that is run when the mouse is moved. This hook is run with five arguments: @@ -265,19 +265,19 @@ mouse was moved. @end defvr -@defvr {Scheme Variable} controller-add-hook +@defvr {Variable} controller-add-hook A hook that is run when a game controller is connected. This hook is run with a single argument, @var{controller}, the controller that was connected. @end defvr -@defvr {Scheme Variable} controller-remove-hook +@defvr {Variable} controller-remove-hook A hook that is run when a game controller is disconnected. This hook is run with a single argument, @var{controller}, the controller that was disconnected. @end defvr -@defvr {Scheme Variable} controller-press-hook +@defvr {Variable} controller-press-hook A hook that is run when a button on a game controller is pressed. This hook is run with two arguments: @@ -328,7 +328,7 @@ Possible buttons are: @end defvr -@defvr {Scheme Variable} controller-release-hook +@defvr {Variable} controller-release-hook A hook that is run when a button on a game controller is released. This hook is run with two arguments: @@ -345,7 +345,7 @@ This hook is run with two arguments: @end defvr -@defvr {Scheme Variable} controller-move-hook +@defvr {Variable} controller-move-hook A hook that is run when an analog stick or trigger on a game controller is moved. This hook is run with three arguments @@ -390,11 +390,11 @@ controllers. @node Keyboard @subsection Keyboard -@deffn {Scheme Procedure} key-pressed? @var{key} +@deffn {Procedure} key-pressed? @var{key} Return @code{#t} if @var{key} is currently being pressed. @end deffn -@deffn {Scheme Procedure} key-released? @var{key} +@deffn {Procedure} key-released? @var{key} Return @code{#t} if @var{key} is not currently being pressed. @end deffn @@ -417,14 +417,14 @@ detection. @node Basics @subsection Basics -@defvar {Scheme Variable} pi +@defvar pi An essential constant for all trigonometry. @code{@U{03C0}} is the ratio of a circle's circumferences to its diameter. Since @code{@U{03C0}} is an irrational number, the @var{pi} in Chickadee is a mere floating point approximation that is ``good enough.'' @end defvar -@defvar {Scheme Variable} pi/2 +@defvar pi/2 Half of @var{pi}. @end defvar @@ -440,55 +440,55 @@ Half of @var{pi}. @node Easings @subsection Easings -@deffn {Scheme Procedure} linear @var{t} +@deffn {Procedure} linear @var{t} @end deffn -@deffn {Scheme Procedure} smoothstep @var{t} +@deffn {Procedure} smoothstep @var{t} @end deffn -@deffn {Scheme Procedure} ease-in-quad @var{t} +@deffn {Procedure} ease-in-quad @var{t} @end deffn -@deffn {Scheme Procedure} ease-out-quad @var{t} +@deffn {Procedure} ease-out-quad @var{t} @end deffn -@deffn {Scheme Procedure} ease-in-out-quad @var{t} +@deffn {Procedure} ease-in-out-quad @var{t} @end deffn -@deffn {Scheme Procedure} ease-in-cubic @var{t} +@deffn {Procedure} ease-in-cubic @var{t} @end deffn -@deffn {Scheme Procedure} ease-out-cubic @var{t} +@deffn {Procedure} ease-out-cubic @var{t} @end deffn -@deffn {Scheme Procedure} ease-in-out-cubic @var{t} +@deffn {Procedure} ease-in-out-cubic @var{t} @end deffn -@deffn {Scheme Procedure} ease-in-quart @var{t} +@deffn {Procedure} ease-in-quart @var{t} @end deffn -@deffn {Scheme Procedure} ease-out-quart @var{t} +@deffn {Procedure} ease-out-quart @var{t} @end deffn -@deffn {Scheme Procedure} ease-in-out-quart @var{t} +@deffn {Procedure} ease-in-out-quart @var{t} @end deffn -@deffn {Scheme Procedure} ease-in-quint @var{t} +@deffn {Procedure} ease-in-quint @var{t} @end deffn -@deffn {Scheme Procedure} ease-out-quint @var{t} +@deffn {Procedure} ease-out-quint @var{t} @end deffn -@deffn {Scheme Procedure} ease-in-out-quint @var{t} +@deffn {Procedure} ease-in-out-quint @var{t} @end deffn -@deffn {Scheme Procedure} ease-in-sine @var{t} +@deffn {Procedure} ease-in-sine @var{t} @end deffn -@deffn {Scheme Procedure} ease-out-sine @var{t} +@deffn {Procedure} ease-out-sine @var{t} @end deffn -@deffn {Scheme Procedure} ease-in-out-sine @var{t} +@deffn {Procedure} ease-in-out-sine @var{t} @end deffn @node Graphics @@ -536,9 +536,9 @@ would be tedious to have to have to specify them each time The following procedures and syntax can be found in the @code{(chickadee render)} module. -@deffn {Scheme Syntax} gpu-apply @var{shader} @var{vertex-array} @ +@deffn {Syntax} gpu-apply @var{shader} @var{vertex-array} @ [#:uniform-key @var{uniform-value} ...] -@deffnx {Scheme Syntax} gpu-apply* @var{shader} @var{vertex-array} @ +@deffnx {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 @@ -549,61 +549,61 @@ While @code{gpu-apply} will draw every vertex in @var{vertex-array}, @end deffn -@deffn {Scheme Procedure} current-viewport +@deffn {Procedure} current-viewport Return the currently bound viewport. @xref{Viewports} for more details about using viewports. @end deffn -@deffn {Scheme Procedure} current-framebuffer +@deffn {Procedure} current-framebuffer Return the currently bound framebuffer. @xref{Framebuffers} for more details about using framebuffers. @end deffn -@deffn {Scheme Procedure} current-blend-mode +@deffn {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 +@deffn {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 +@deffn {Procedure} current-texture Return the currently bound texture. @xref{Textures} for more details about using textures. @end deffn -@deffn {Scheme Procedure} current-projection +@deffn {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} ... +@deffn {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} ... +@deffn {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} ... +@deffn {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} ... +@deffn {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} ... +@deffn {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} ... +@deffn {Syntax} with-projection @var{projection} @var{body} ... Evaluate @var{body} with the current projection matrix bound to @var{projection}. @end deffn @@ -611,7 +611,7 @@ Evaluate @var{body} with the current projection matrix bound to @node Textures @subsection Textures -@deffn {Scheme Procedure} load-image @var{file} [#:min-filter nearest] @ +@deffn {Procedure} load-image @var{file} [#:min-filter nearest] @ [#:mag-filter nearest] [#:wrap-s repeat] [#:wrap-t repeat] Load the image data from @var{file} and return a new texture object. @@ -637,7 +637,7 @@ players, NPCs, items, particles, text, etc. In Chickadee, bitmaps are stored in textures (@pxref{Textures}) and can be used to draw sprites via the @code{draw-sprite} procedure. -@deffn {Scheme Procedure} draw-sprite @var{texture} @var{region} @ +@deffn {Procedure} draw-sprite @var{texture} @var{region} @ [#:scale] [#:rotation] [#:blend-mode alpha] [#:texture-region] @ [#:shader] @@ -664,7 +664,7 @@ Taking advantage of sprite batching in Chickadee is easy, just wrap the code that is calling @code{draw-sprite} a lot in the @code{with-batched-sprites} form. -@deffn {Scheme Syntax} with-batched-sprites @var{body} @dots{} +@deffn {Syntax} with-batched-sprites @var{body} @dots{} Use batched rendering for all @code{draw-sprite} calls within @var{body}. @end deffn @@ -696,7 +696,7 @@ interface widgets like buttons and dialog boxes. By using a nine patch, they can be rendered at any size without unappealing scaling artifacts. -@deffn {Scheme Procedure} draw-nine-patch @var{texture} @var{region} @ +@deffn {Procedure} draw-nine-patch @var{texture} @var{region} @ [#:margin 0] [#:top-margin margin] [#:bottom-margin margin] @ [#:left-margin margin] [#:right-margin margin] @ [#:texture-region] [#:scale] [#:rotation] [#:blend-mode alpha] @ @@ -720,7 +720,7 @@ Sprites are fun, but sometimes simple, untextured lines and polygons are desired. That's where the @code{(chickadee render shapes)} module comes in! -@deffn {Scheme Procedure} draw-line @var{start} @var{end} @ +@deffn {Procedure} draw-line @var{start} @var{end} @ [#:thickness 0.5] [#:feather 1.0] [#:cap round] [#:color] @ [#:shader] @@ -777,36 +777,36 @@ in the meantime. The following procedures can be found in the @code{(chickadee render font)} module. -@deffn {Scheme Procedure} load-font @var{file} +@deffn {Procedure} load-font @var{file} Load the Angel Code formatted XML document in @var{file} and return a new font object. @end deffn -@deffn {Scheme Procedure} font? @var{obj} +@deffn {Procedure} font? @var{obj} Return @code{#t} if @var{obj} is a font object. @end deffn -@deffn {Scheme Procedure} font-face @var{font} +@deffn {Procedure} font-face @var{font} Return the name of @var{font}. @end deffn -@deffn {Scheme Procedure} font-line-height @var{font} +@deffn {Procedure} font-line-height @var{font} Return the line height of @var{font}. @end deffn -@deffn {Scheme Procedure} font-line-height @var{font} +@deffn {Procedure} font-line-height @var{font} Return the line height of @var{font}. @end deffn -@deffn {Scheme Procedure} font-bold? @var{font} +@deffn {Procedure} font-bold? @var{font} Return @code{#t} if @var{font} is a bold font. @end deffn -@deffn {Scheme Procedure} font-italic? @var{font} +@deffn {Procedure} font-italic? @var{font} Return @code{#t} if @var{font} is an italicized font. @end deffn -@deffn {Scheme Procedure} draw-text @var{font} @var{text} @var{position} +@deffn {Procedure} draw-text @var{font} @var{text} @var{position} [#:scale] [#:rotation] [#:blend-mode] Draw the string @var{text} with the first character starting at @@ -850,58 +850,58 @@ uh@dots{}, music. Supported file formats include WAV and OGG. -@deffn {Scheme Procedure} load-sample @var{file} +@deffn {Procedure} load-sample @var{file} Load audio sample from @var{file}. @end deffn -@deffn {Scheme Procedure} set-sample-volume! @var{volume} +@deffn {Procedure} set-sample-volume! @var{volume} Set the volume that all samples are played at to @var{volume}, an integer value between 0 and 128. @end deffn -@deffn {Scheme Procedure} play-sample @var{sample} +@deffn {Procedure} play-sample @var{sample} Play @var{sample}. Pretty straightforward! @end deffn -@deffn {Scheme Procedure} load-music @var{file} +@deffn {Procedure} load-music @var{file} Load music from @var{file}. @end deffn -@deffn {Scheme Procedure} music-volume +@deffn {Procedure} music-volume Return the volume level for music, an integer value between 0 and 128. @end deffn -@deffn {Scheme Procedure} set-music-volume! @var{volume} +@deffn {Procedure} set-music-volume! @var{volume} Set the volume that music is played at to @var{volume}, an integer value between 0 and 128. @end deffn -@deffn {Scheme Procedure} play-music @var{music} [@var{loop?}] +@deffn {Procedure} play-music @var{music} [@var{loop?}] Play @var{music}. If @var{loop?}, play it over and over and over and over and@dots{} @end deffn -@deffn {Scheme Procedure} pause-music +@deffn {Procedure} pause-music Pause the current music track. @end deffn -@deffn {Scheme Procedure} resume-music +@deffn {Procedure} resume-music Resume the current music track. @end deffn -@deffn {Scheme Procedure} rewind-music +@deffn {Procedure} rewind-music estart the current music track from the beginning. @end deffn -@deffn {Scheme Procedure} stop-music +@deffn {Procedure} stop-music Stop playing the current music track. @end deffn -@deffn {Scheme Procedure} music-playing? +@deffn {Procedure} music-playing? Return @code{#t} if music is currently playing. @end deffn -@deffn {Scheme Procedure} music-paused? +@deffn {Procedure} music-paused? Return @code{#t} if music is currently paused. @end deffn @@ -1152,58 +1152,58 @@ scoped and can be changed using the @code{with-agenda} special form: (at 240 (spawn-goblin-king))) @end example -@deffn {Scheme Procedure} make-agenda +@deffn {Procedure} make-agenda Return a new task scheduler. @end deffn -@deffn {Scheme Procedure} agenda? @var{obj} +@deffn {Procedure} agenda? @var{obj} Return @code{#t} if @var{obj} is an agenda. @end deffn -@deffn {Scheme Procedure} current-agenda -@deffnx {Scheme Procedure} current-agenda @var{agenda} +@deffn {Procedure} current-agenda +@deffnx {Procedure} current-agenda @var{agenda} When called with no arguments, return the current agenda. When called with one argument, set the current agenda to @var{agenda}. @end deffn -@deffn {Scheme Syntax} with-agenda @var{agenda} @var{body} @dots{} +@deffn {Syntax} with-agenda @var{agenda} @var{body} @dots{} Evaluate @var{body} with the current agenda set to @var{agenda}. @end deffn -@deffn {Scheme Procedure} agenda-time +@deffn {Procedure} agenda-time Return the current agenda time. @end deffn -@deffn {Scheme Procedure} update-agenda @var{dt} +@deffn {Procedure} update-agenda @var{dt} Advance the current agenda by @var{dt}. @end deffn -@deffn {Scheme Procedure} schedule-at @var{time} @var{thunk} +@deffn {Procedure} schedule-at @var{time} @var{thunk} Schedule @var{thunk}, a procedure of zero arguments, to be run at @var{time}. @end deffn -@deffn {Scheme Procedure} schedule-after @var{delay} @var{thunk} +@deffn {Procedure} schedule-after @var{delay} @var{thunk} Schedule @var{thunk}, a procedure of zero arguments, to be run after @var{delay}. @end deffn -@deffn {Scheme Procedure} schedule-every @var{interval} @var{thunk} [@var{n}] +@deffn {Procedure} schedule-every @var{interval} @var{thunk} [@var{n}] Schedule @var{thunk}, a procedure of zero arguments, to be run every @var{interval} amount of time. Repeat this @var{n} times, or indefinitely if not specified. @end deffn -@deffn {Scheme Syntax} at @var{time} @var{body} @dots{} +@deffn {Syntax} at @var{time} @var{body} @dots{} Schedule @var{body} to be evaluated at @var{time}. @end deffn -@deffn {Scheme Syntax} after @var{delay} @var{body} @dots{} +@deffn {Syntax} after @var{delay} @var{body} @dots{} Schedule @var{body} to be evaluated after @var{delay}. @end deffn -@deffn {Scheme Syntax} every @var{interval} @var{body} @dots{} -@deffnx {Scheme Syntax} every (@var{interval} @var{n}) @var{body} @dots{} +@deffn {Syntax} every @var{interval} @var{body} @dots{} +@deffnx {Syntax} every (@var{interval} @var{n}) @var{body} @dots{} Schedule @var{body} to be evaluated every @var{interval} amount of time. Repeat this @var{n} times, or indefinitely if not specified. @end deffn @@ -1256,49 +1256,49 @@ desired. (cancel-coroutine co) @end example -@deffn {Scheme Procedure} spawn-coroutine @var{thunk} +@deffn {Procedure} spawn-coroutine @var{thunk} Apply @var{thunk} as a coroutine and return a handle to it. @end deffn -@deffn {Scheme Syntax} coroutine @var{body} @dots{} +@deffn {Syntax} coroutine @var{body} @dots{} Evaluate @var{body} as a coroutine and return a handle to it. @end deffn -@deffn {Scheme Procedure} coroutine? @var{obj} +@deffn {Procedure} coroutine? @var{obj} Return @code{#t} if @var{obj} is a coroutine handle. @end deffn -@deffn {Scheme Procedure} coroutine-cancelled? @var{obj} +@deffn {Procedure} coroutine-cancelled? @var{obj} Return @code{#t} if @var{obj} has been cancelled. @end deffn -@deffn {Scheme Procedure} coroutine-running? @var{obj} +@deffn {Procedure} coroutine-running? @var{obj} Return @code{#t} if @var{obj} has not yet terminated or been cancelled. @end deffn -@deffn {Scheme Procedure} coroutine-complete? @var{obj} +@deffn {Procedure} coroutine-complete? @var{obj} Return @code{#t} if @var{obj} has terminated. @end deffn -@deffn {Scheme Procedure} cancel-coroutine @var{co} +@deffn {Procedure} cancel-coroutine @var{co} Prevent further execution of the coroutine @var{co}. @end deffn -@deffn {Scheme Procedure} yield @var{handler} +@deffn {Procedure} yield @var{handler} Suspend the current coroutine and pass its continuation to the procedure @var{handler}. @end deffn -@deffn {Scheme Procedure} wait @var{duration} +@deffn {Procedure} wait @var{duration} Wait @var{duration} before resuming the current coroutine. @end deffn -@deffn {Scheme Procedure} channel-get @var{channel} +@deffn {Procedure} channel-get @var{channel} Wait for a message from @var{channel}. @end deffn -@deffn {Scheme Syntax} forever @var{body} @dots{} +@deffn {Syntax} forever @var{body} @dots{} Evaluate @var{body} in an endless loop. @end deffn @@ -1317,7 +1317,7 @@ procedure can be used within any coroutine like so: (tween 60 0 100 (lambda (y) (set! x y)))) @end example -@deffn {Scheme Procedure} tween @var{duration} @var{start} @var{end} @var{proc} [#:step 1 #:ease @code{smoothstep} #:interpolate @code{lerp}] +@deffn {Procedure} tween @var{duration} @var{start} @var{end} @var{proc} [#:step 1 #:ease @code{smoothstep} #:interpolate @code{lerp}] Transition a value from @var{start} to @var{end} over @var{duration}, sending each succesive value to @var{proc}. @var{step} controls the amount of time between each update of the animation. @@ -1358,20 +1358,20 @@ Here's a simplistic example: (channel-put c 'potion)) @end example -@deffn {Scheme Procedure} make-channel +@deffn {Procedure} make-channel Return a new channel @end deffn -@deffn {Scheme Procedure} channel? @var{obj} +@deffn {Procedure} channel? @var{obj} Return @code{#t} if @var{obj} is a channel. @end deffn -@deffn {Scheme Procedure} channel-get @var{channel} +@deffn {Procedure} channel-get @var{channel} Retrieve a value from @var{channel}. The current coroutine suspends until a value is available. @end deffn -@deffn {Scheme Procedure} channel-put @var{channel} @var{data} +@deffn {Procedure} channel-put @var{channel} @var{data} Send @var{data} to @var{channel}. The current coroutine suspends until another coroutine is available to retrieve the value. @end deffn |