summaryrefslogtreecommitdiff
path: root/doc/api.texi
diff options
context:
space:
mode:
authorDavid Thompson <dthompson2@worcester.edu>2023-04-21 22:23:13 -0400
committerDavid Thompson <dthompson2@worcester.edu>2023-04-21 22:23:13 -0400
commit08283ce8448f9ebf6be28fecf8c730e9f99e3f47 (patch)
treede460786949318848d2b710e65f767ee3495d587 /doc/api.texi
parentb4daa495779da4cfc80f00a642648143cbf313b6 (diff)
Add syntax highlighting to html manual.
Diffstat (limited to 'doc/api.texi')
-rw-r--r--doc/api.texi136
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