diff options
Diffstat (limited to 'doc/api.texi')
| -rw-r--r-- | doc/api.texi | 136 |
1 files changed, 68 insertions, 68 deletions
diff --git a/doc/api.texi b/doc/api.texi index c36a36b..6ec5f9b 100644 --- a/doc/api.texi +++ b/doc/api.texi @@ -586,9 +586,9 @@ release. Here's a quick example of adding two vectors: -@example +@lisp (define v (vec2+ (vec2 1 2) (vec2 3 4))) -@end example +@end lisp @emph{A Note About Performance} @@ -1013,11 +1013,11 @@ Return a new 3x3 identity matrix. Any matrix multiplied by the identity matrix yields the original matrix. This procedure is equivalent to the following code: -@example +@lisp (make-matrix3 1 0 0 0 1 0 0 0 1) -@end example +@end lisp @end deffn @@ -1125,12 +1125,12 @@ Return a new 4x4 identity matrix. Any matrix multiplied by the identity matrix yields the original matrix. This procedure is equivalent to the following code: -@example +@lisp (make-matrix4 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1) -@end example +@end lisp @end deffn @@ -1468,18 +1468,18 @@ 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 +@lisp (make-color 1.0 0.0 1.0 1.0) -@end example +@end lisp Many people are used to representing colors as 6 or 8 digit hexadecimal numbers, so Chickadee also allows that. Here's magenta, again: -@example +@lisp (rgba #xFF00FFFF) (rgb #xFF00FF) ; equivalent to the above -@end example +@end lisp @deffn {Procedure} make-color r g b a Return a new color object with a red value of @var{r}, a green value @@ -1531,12 +1531,12 @@ transparent. Convert the hexadecimal color code in the string @var{s} to a color object. The following string formats are supported: -@example +@lisp (string->color "#FF00FFFF") (string->color "FF00FFFF") (string->color "#FF00FF") (string->color "FF00FF") -@end example +@end lisp @end deffn @@ -2005,9 +2005,9 @@ as they are the same. Printing text to the screen is quite easy: -@example +@lisp (draw-text "Hello, world" (vec2 100.0 100.0)) -@end example +@end lisp Chickadee supports OpenType/TrueType fonts (via the FreeType library), bitmap fonts in Angel Code bmfont format, and simple sprite sheet @@ -2064,9 +2064,9 @@ Draw the string @var{text} with the first character starting at @var{position} using @var{font}. If @var{font} is not specified, a built-in font is used. -@example +@lisp (draw-text "Hello, world!" (vec2 128.0 128.0)) -@end example +@end lisp To render a substring of @var{text}, use the @var{start} and @var{end} arguments. @@ -2097,14 +2097,14 @@ the first. @deffn {Procedure} path . commands Return a new path that follows @var{commands}. -@example +@lisp (path (move-to (vec2 50.0 50.0)) (line-to (vec2 500.0 50.0)) (line-to (vec2 400.0 200.0)) (bezier-to (vec2 500.0 250.0) (vec2 380.0 300.0) (vec2 400.0 400.0)) (line-to (vec2 300.0 400.0)) (close-path)) -@end example +@end lisp @end deffn @@ -2231,11 +2231,11 @@ Possible style attributes are: @item @code{stroke-cap} @end itemize -@example +@lisp (with-style ((stroke-color green) (stroke-width 4.0)) (stroke (circle (vec2 100.0 100.0) 50.0))) -@end example +@end lisp @end deffn @@ -2427,11 +2427,11 @@ manipulating particle systems. Below is an example of a very simple particle system that utilizes nearly all of the default configuration settings: -@example +@lisp (use-modules (chickadee graphics particles)) (define texture (load-image "particle.png")) (define particles (make-particles 2000 #:texture texture)) -@end example +@end lisp In order to put particles into a particle system, a particle ``emitter'' is needed. Emitters know where to spawn new particles, @@ -2440,11 +2440,11 @@ how many of them to spawn, and for how long they should do it. Below is an example of an emitter that spawns 16 particles per frame at the coordinates @code{(320, 240)}: -@example +@lisp (use-modules (chickadee math rect)) (define emitter (make-particle-emitter (make-rect 0.0 0.0 320.0 240.0) 16)) (add-particle-emitter particles emitter) -@end example +@end lisp To see all of the tweakable knobs and switches, read on! @@ -2794,7 +2794,7 @@ formats. Here's some basic boilerplate to render a 3D model: -@example +@lisp (use-modules (chickadee graphics light) (chickadee graphics model) (chickadee graphics skybox)) @@ -2808,7 +2808,7 @@ Here's some basic boilerplate to render a 3D model: (define (draw alpha) (with-projection projection (draw-model model world view camera-position -@end example +@end lisp @deffn {Procedure} load-obj file-name Load the OBJ formatted model in @var{file-name} and return a 3D model @@ -3278,7 +3278,7 @@ In OpenGL terminology, a chunk of data allocated on the GPU is a that could be transformed into a GPU buffer that packs together vertex position and texture coordinates: -@example +@lisp (use-modules (chickadee graphics buffer) (srfi srfi-4)) (define data (f32vector -8.0 -8.0 ; 2D vertex @@ -3289,15 +3289,15 @@ position and texture coordinates: 1.0 1.0 ; 2D texture coordinate -8.0 8.0 ; 2D vertex 0.0 1.0)) ; 2D texture coordinate -@end example +@end lisp This data represents a textured 16x16 square centered on the origin. To send this data to the GPU, the @code{make-buffer} procedure is needed: -@example +@lisp (define buffer (make-buffer data #:stride 16)) -@end example +@end lisp The @code{#:stride} keyword argument indicates how many bytes make up each element of the buffer. In this case, there are 4 floats per @@ -3310,7 +3310,7 @@ particular data type. In this case, there are two attributes packed into the buffer. To define vertex attributes, the @code{make-vertex-attribute} procedure is needed: -@example +@lisp (define vertices (make-vertex-attribute #:buffer buffer #:type 'vec2 @@ -3322,7 +3322,7 @@ into the buffer. To define vertex attributes, the #:component-type 'float #:length 4 #:offset 8)) -@end example +@end lisp To render a square, the GPU needs to draw two triangles, which means we need 6 vertices in total. However, the above buffer only contains @@ -3331,7 +3331,7 @@ for a square, but 2 of them must be repeated for each triangle. To work with deduplicated vertex data, an ``index buffer'' must be created. -@example +@lisp (define index-buffer (make-buffer (u32vector 0 3 2 0 2 1) #:target 'index) @@ -3339,7 +3339,7 @@ created. (make-vertex-attribute #:type 'scalar #:component-type 'unsigned-int #:buffer index-buffer)) -@end example +@end lisp Note the use of the @code{#:target} keyword argument. It is required because the GPU treats index data in a special way and must be told @@ -3351,12 +3351,12 @@ each vertex attribute with an attribute index on the GPU. The indices that are chosen must correspond with the indices that the shader (@pxref{Shaders}) expects for each attribute. -@example +@lisp (define vertex-array (make-vertex-array #:indices indices #:attributes `((0 . ,vertices) (1 . ,texcoords)))) -@end example +@end lisp With the vertex array created, the GPU is now fully aware of how to interpret the data that it has been given in the original buffer. @@ -3573,11 +3573,11 @@ attributes @var{indices} and the vertex attribute data within @var{attributes} is an alist mapping shader attribute indices to vertex attributes: -@example +@lisp `((1 . ,vertex-attribute-a) (2 . ,vertex-attribute-b) - @dots{}) -@end example + ...) +@end lisp By default, the vertex array is interpreted as containing a series of triangles. If another primtive type is desired, the @var{mode} @@ -3684,11 +3684,11 @@ Chickadee uses, is to think about it as a function call: The shader is a function, and it is applied to some ``attributes'' (positional arguments), and some ``uniforms'' (keyword arguments). -@example +@lisp (define my-shader (load-shader "vert.glsl" "frag.glsl")) -(define vertices (make-vertex-array @dots{})) +(define vertices (make-vertex-array ...)) (shader-apply my-shader vertices #:color red) -@end example +@end lisp @xref{Rendering Engine} for more details about the @code{shader-apply} procedure. @@ -3807,7 +3807,7 @@ shader struct. Some example code will explain this concept best. Here is the Scheme equivalent of the @code{Light} struct: -@example +@lisp (define-shader-type <light> make-light light? @@ -3818,7 +3818,7 @@ equivalent of the @code{Light} struct: (float-vec4 color light-color) (float intensity light-intensity) (float cut-off light-cut-off)) -@end example +@end lisp The macro @code{define-shader-type} closely resembles the familiar @code{define-record-type} from SRFI-9, but with one notable @@ -4407,11 +4407,11 @@ and state changes happen within the context of this engine. Performing a custom draw call could look something like this: -@example +@lisp (with-graphics-state ((g:blend-mode blend:alpha) (g:texture-0 my-texture)) (shader-apply my-shader #:foo 1)) -@end example +@end lisp @subsubsection Render States @@ -4495,11 +4495,11 @@ The basics of playing audio are very simple. Just load an audio file in the load hook (or anywhere else once the game loop is running) and play it! -@example +@lisp (define sample (load-audio "neat-sound-effect.wav")) (audio-play sample) -@end example +@end lisp For more advanced usage, check out the full API reference in the following sections. @@ -4962,26 +4962,26 @@ additional agendas may be created for different purposes. The following example prints the text ``hello'' when the agenda has advanced to time unit 10. -@example +@lisp (at 10 (display "hello\n")) -@end example +@end lisp Most of the time it is more convenient to schedule tasks relative to the current time. This is where @code{after} comes in handy: -@example +@lisp (after 10 (display "hello\n")) -@end example +@end lisp Time units in the agenda are in no way connected to real time. It's up to the programmer to decide what agenda time means. A simple and effective approach is to map each call of the update procedure (@pxref{Kernel}) to 1 unit of agenda time, like so: -@example +@lisp (define (update dt) (update-agenda 1)) -@end example +@end lisp It is important to call @code{update-agenda} periodically, otherwise no tasks will ever be run! @@ -4993,14 +4993,14 @@ a simple matter of not updating the world's agenda while continuing to update the user interface's agenda. The current agenda is dynamically scoped and can be changed using the @code{with-agenda} special form: -@example +@lisp (define game-world-agenda (make-agenda)) (with-agenda game-world-agenda (at 60 (spawn-goblin)) (at 120 (spawn-goblin)) (at 240 (spawn-goblin-king))) -@end example +@end lisp @deffn {Procedure} make-agenda Return a new task scheduler. @@ -5081,13 +5081,13 @@ turn and prevent blocking the game loop. Building on top of the scheduling that agendas provide, here is a script that models a child trying to get their mother's attention: -@example +@lisp (script (while #t (display "mom!") (newline) (sleep 60))) ; where 60 = 1 second of real time -@end example +@end lisp This code runs in an endless loop, but the @code{sleep} procedure suspends the script and schedules it to be run later by the agenda. @@ -5108,11 +5108,11 @@ been started. For example, when an enemy is defeated their AI routine needs to be shut down. When a script is spawned, a handle to that script is returned that can be used to cancel it when desired. -@example +@lisp (define script (script (while #t (display "hey\n") (sleep 60)))) ;; sometime later (cancel-script script) -@end example +@end lisp @deffn {Procedure} spawn-script thunk Apply @var{thunk} as a script and return a handle to it. @@ -5159,11 +5159,11 @@ Wait @var{duration} before resuming the current script. @deffn {Syntax} wait-until condition Wait until @var{condition} is met before resuming the current script. -@example +@lisp (script (wait-until (key-pressed? 'z)) (display "you pressed the Z key!\n")) -@end example +@end lisp @end deffn @@ -5179,12 +5179,12 @@ state to a final state over a pre-determined period of time. In other words, tweening is a way to create animation. The @code{tween} procedure can be used within any script like so: -@example +@lisp (define x 0) (script ;; 0 to 100 in 60 ticks of the agenda. (tween 60 0 100 (lambda (y) (set! x y)))) -@end example +@end lisp @deffn {Procedure} tween duration start end proc @ [#:step @code{1}] [#:ease @code{smoothstep}] @ @@ -5214,7 +5214,7 @@ someone on the other end of the line to complete the transaction. Here's a simplistic example: -@example +@lisp (define c (make-channel)) (script @@ -5226,7 +5226,7 @@ Here's a simplistic example: (channel-put c 'sword) (channel-put c 'shield) (channel-put c 'potion)) -@end example +@end lisp @deffn {Procedure} make-channel Return a new channel @@ -5652,7 +5652,7 @@ map implementation! The example below defines a very simple town map and finds the quickest way to get from the town common to the school. -@example +@lisp (define world-map '((town-common . (town-hall library)) (town-hall . (town-common school)) @@ -5665,7 +5665,7 @@ quickest way to get from the town common to the school. (define (distance a b) 1) (define pf (make-path-finder)) (a* pf 'town-common 'school neighbors cost distance) -@end example +@end lisp In this case, the @code{a*} procedure will return the list @code{(town-common town-hall school)}, which is indeed the shortest |