summaryrefslogtreecommitdiff
path: root/doc/api.texi
blob: cb3c8850f6f4bd9adf2b02bfbea4cbfd1408ec8c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
@menu
* Kernel::                      The fundamental components.
* Input::                       Keyboard, mouse, and controller input.
* Math::                        Linear algebra and more.
* Graphics::                    Eye candy.
* Audio::                       Sound effects and music.
* Buffers::                     Splitting games into logical components.
* Scripting::                   Bringing the game world to life.
@end menu

@node Kernel
@section Kernel

At the very core of Chickadee, in the @code{(chickadee)} module, lies
an event loop.  This loop, or ``kernel'', is responsible for creating
and managing the game window, dispatching input events, ensuring that
the game is updated at the desired interval, and rendering graphics.
The kernel implements what is known as a ``fixed timestep'' game loop,
meaning that the game simulation will be advanced by a fixed interval
of time and will never vary from frame to frame, unlike some other
styles of game loops.  The appropriately named @code{run-game} and
@code{abort-game} procedures are the entry and exit points to the
Chickadee kernel.

On its own, the kernel does not do very much at all.  In order to
actually respond to input events, update game state, or draw something
to the game window, a hacker with a penchant for game development must
latch onto extension points built into the kernel, called ``hooks'',
and specify what action ought to be taken for any given event.  For
example, the @code{key-press-hook} can be used to respond to the
@code{a} key being pressed by swinging the player's mighty sword.
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 {Procedure} run-game [#:window-title "Chickadee!"] @
       [#:window-width 640] [#:window-height 480] [#:window-fullscreen? #f] @
       [#:update-hz 60]

Start the event loop.  This procedure will not return until
@code{abort-game} is called.

The @code{update-hook} will be run @var{update-hz} times per second.

A new graphical window will be opened with @var{window-width} x
@var{window-height} as its dimensions, @var{window-title} as its
title, and in fullscreen mode if @var{window-fullscreen?} is
@code{#t}.
@end deffn

@deffn {Procedure} abort-game
Stop the currently running Chickadee event loop.
@end deffn

@deffn {Procedure} time
Return the current game time in milliseconds.
@end deffn

@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.

@example
(add-hook! load-hook (lambda () (display "hello!\n")))
@end example

@end defvr

@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.

@example
(add-hook! update-hook (lambda (dt) (display "tick!\n")))
@end example

@end defvr

@defvr {Variable} before-draw-hook
A hook that is run before a frame is rendered.  This hook is run with
zero arguments.

@example
(add-hook! before-draw-hook (lambda () (display "about to draw!\n")))
@end example

@end defvr

@defvr {Variable} after-draw-hook
A hook that is run after a frame is rendered.  This hook is run with
zero arguments.

@example
(add-hook! after-draw-hook (lambda () (display "done drawing!\n")))
@end example

Combined with @code{before-draw-hook}, one can perform a frames per
second calculation to monitor game performance and stability.

@end defvr

@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
update relative to the upcoming game state update, as a percentage.
Because the game state is updated independent of rendering, it is
often the case that rendering is occuring between two updates.  If the
game is rendered as it was during the last update, a strange
side-effect will occur that makes animation appear rough or
``choppy''.  To counter this, the @var{alpha} value can be used to
perfrom a linear interpolation of a moving object between its current
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.

@c TODO: Add example of linear interpolation

@example
(add-hook! draw-hook (lambda (alpha) (display "<(._.<) \n")))
@end example

@end defvr

@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.

@example
(add-hook! quit-hook (lambda () (display "bye!\n")))
@end example

@end defvr

@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:

@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 {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 {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 {Variable} mouse-press-hook
A hook that is run when a mouse button is pressed.  This hook is run
with four arguments:

@enumerate

@item
@var{button}: The symbolic name of the button that was pressed, such
as @code{left}, @code{middle}, or @code{right}.

@item
@var{clicks}: The number of times the button has been clicked in a row.

@item
@var{x}: The x coordinate of the mouse cursor.

@item
@var{y}: The y coordinate of the mouse cursor.

@end enumerate

@end defvr

@defvr {Variable} mouse-release-hook
A hook that is run when a mouse button is released.  This hook is run
with three arguments:

@enumerate

@item
@var{button}: The symbolic name of the button that was released.

@item
@var{x}: The x coordinate of the mouse cursor.

@item
@var{y}: The y coordinate of the mouse cursor.

@end enumerate

@end defvr

@defvr {Variable} mouse-move-hook
A hook that is run when the mouse is moved.  This hook is run with
five arguments:

@enumerate

@item
@var{x}: The x coordinate of the mouse cursor.

@item
@var{y}: The y coordinate of the mouse cursor.

@item
@var{dx}: The amount the mouse has moved along the x axis since the
last mouse move event.

@item
@var{dy}: The amount the mouse has moved along the y axis since the
last mouse move event.

@item
@var{buttons}: A list of the buttons that were pressed down when the
mouse was moved.

@end enumerate

@end defvr

@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 {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 {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:

@enumerate

@item
@var{controller}: The controller that triggered the event.

@item
@var{button}: The symbolic name of the button that was pressed.
Possible buttons are:

@itemize
@item
@code{a}
@item
@code{b}
@item
@code{x}
@item
@code{y}
@item
@code{back}
@item
@code{guide}
@item
@code{start}
@item
@code{left-stick}
@item
@code{right-stick}
@item
@code{left-shoulder}
@item
@code{right-shoulder}
@item
@code{dpad-up}
@item
@code{dpad-down}
@item
@code{dpad-left}
@item
@code{dpad-right}

@end itemize

@end enumerate

@end defvr

@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:

@enumerate

@item
@var{controller}: The controller that triggered the event.

@item
@var{button}: The symbolic name of the button that was released.

@end enumerate

@end defvr

@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

@enumerate

@item
@var{controller}: The controller that triggered the event.

@item
@var{axis}: The symbolic name of the axis that was moved.  Possible
values are:

@itemize
@item
@code{left-x}
@item
@code{left-y}
@item
@code{right-x}
@item
@code{right-y}
@item
@code{trigger-left}
@item
@code{trigger-right}
@end itemize

@end enumerate

@end defvr

@node Input
@section Input

Chickadee can handle input events from the keyboard, mouse, and game
controllers.

@menu
* Keyboard::                    Keyboard input.
@end menu

@node Keyboard
@subsection Keyboard

@deffn {Procedure} key-pressed? @var{key}
Return @code{#t} if @var{key} is currently being pressed.
@end deffn

@deffn {Procedure} key-released? @var{key}
Return @code{#t} if @var{key} is not currently being pressed.
@end deffn

@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
* Basics::                      Commonly used, miscellaneous things.
* Vectors::                     Euclidean vectors.
* Matrices::                    Transformation matrices.
* Quaternions::                 Rotations.
* Rectangles::                  Axis-aligned bounding boxes.
* Easings::                     Easing functions for interesting animations.
@end menu

@node Basics
@subsection Basics

@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 pi/2
Half of @var{pi}.
@end defvar

@deffn {Procedure} cotan @var{z}
Return the cotangent of @var{z}.
@end deffn

@node Vectors
@subsection Vectors

@node Matrices
@subsection Matrices

@node Quaternions
@subsection Quaternions

In game development, the quaternion is most often used to represent
rotations.  Why not use a matrix for that, you may ask.  Unlike
matrices, quaternions can be interpolated (animated) and produce a
meaningful result.  When interpolating two quaternions, there is a
smooth transition from one rotation to another, whereas interpolating
two matrices would yield garbage.

@deffn {Procedure} quaternion @var{x} @var{y} @var{z} @var{w}
Return a new quaternion with values @var{x}, @var{y}, @var{z}, and
@var{w}.
@end deffn

@deffn {Procedure} quaternion? @var{obj}
Return @code{#t} if @var{obj} is a quaternion.
@end deffn

@deffn {Procedure} quaternion-w @var{q}
Return the W component of the quaternion @var{q}.
@end deffn

@deffn {Procedure} quaternion-x @var{q}
Return the X component of the quaternion @var{q}.
@end deffn

@deffn {Procedure} quaternion-y @var{q}
Return the Y component of the quaternion @var{q}.
@end deffn

@deffn {Procedure} quaternion-z @var{q}
Return the Z component of the quaternion @var{q}.
@end deffn

@deffn {Procedure} make-identity-quaternion
Return the identity quaternion.
@end deffn

@node Rectangles
@subsection Rectangles

@node Easings
@subsection Easings

@deffn {Procedure} linear @var{t}
@end deffn

@deffn {Procedure} smoothstep @var{t}
@end deffn

@deffn {Procedure} ease-in-quad @var{t}
@end deffn

@deffn {Procedure} ease-out-quad @var{t}
@end deffn

@deffn {Procedure} ease-in-out-quad @var{t}
@end deffn

@deffn {Procedure} ease-in-cubic @var{t}
@end deffn

@deffn {Procedure} ease-out-cubic @var{t}
@end deffn

@deffn {Procedure} ease-in-out-cubic @var{t}
@end deffn

@deffn {Procedure} ease-in-quart @var{t}
@end deffn

@deffn {Procedure} ease-out-quart @var{t}
@end deffn

@deffn {Procedure} ease-in-out-quart @var{t}
@end deffn

@deffn {Procedure} ease-in-quint @var{t}
@end deffn

@deffn {Procedure} ease-out-quint @var{t}
@end deffn

@deffn {Procedure} ease-in-out-quint @var{t}
@end deffn

@deffn {Procedure} ease-in-sine @var{t}
@end deffn

@deffn {Procedure} ease-out-sine @var{t}
@end deffn

@deffn {Procedure} ease-in-out-sine @var{t}
@end deffn

@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.
* Textures::                    2D images.
* Sprites::                     Draw 2D images.
* Lines and Shapes::            Draw line segments and polygons.
* Fonts::                       Drawing text.
* 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 {Syntax} gpu-apply @var{shader} @var{vertex-array} @
       [#:uniform-key @var{uniform-value} ...]
@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
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 {Procedure} current-viewport
Return the currently bound viewport.  @xref{Viewports} for more
details about using viewports.
@end deffn

@deffn {Procedure} current-framebuffer
Return the currently bound framebuffer.  @xref{Framebuffers} for more
details about using framebuffers.
@end deffn

@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 {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 {Procedure} current-texture
Return the currently bound texture.  @xref{Textures} for more details
about using textures.
@end deffn

@deffn {Procedure} current-projection
Return the currently bound projection matrix.  @xref{Matrices} for
more details about matrices.
@end deffn

@deffn {Syntax} with-viewport @var{viewport} @var{body} ...
Evaluate @var{body} with the current viewport bound to @var{viewport}.
@end deffn

@deffn {Syntax} with-framebuffer @var{framebuffer} @var{body} ...
Evaluate @var{body} with the current framebuffer bound to
@var{framebuffer}.
@end deffn

@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 {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 {Syntax} with-texture @var{texture} @var{body} ...
Evaluate @var{body} with the current texture bound to @var{texture}.
@end deffn

@deffn {Syntax} with-projection @var{projection} @var{body} ...
Evaluate @var{body} with the current projection matrix bound to
@var{projection}.
@end deffn

@node Textures
@subsection Textures

@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.

@var{min-filter} and @var{mag-filter} describe the method that should
be used for minification and magnification when rendering,
respectively.  Possible values are @code{nearest} and @code{linear}.

@var{wrap-s} and @var{wrap-t} describe how to interpret texture
coordinates that are greater than @code{1.0}.  Possible values are
@code{repeat}, @code{clamp}, @code{clamp-to-border}, and
@code{clamp-to-edge}.

@end deffn

@node Sprites
@subsection Sprites

For those who are new to this game, a sprite is a 2D rectangular
bitmap that is rendered to the screen.  For 2D games, sprites are the
most essential graphical abstraction.  They are used for drawing maps,
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 {Procedure} draw-sprite @var{texture} @var{region} @
       [#:scale] [#:rotation] [#:blend-mode alpha] [#:texcoords] @
       [#:shader]

@end deffn

It's not uncommon to need to draw hundreds or thousands of sprites
each frame.  However, GPUs (graphics processing units) are tricky
beasts that prefer to be sent few, large chunks of data to render
rather than many, small chunks.  Using @code{draw-sprite} on its own
will involve at least one GPU call @emph{per sprite}, which will
quickly lead to poor performance.  To deal with this, a technique
known as ``sprite batching'' can be used.  Instead of drawing each
sprite immediately, the sprite batch will build up a large of buffer
of sprites to draw and defer rendering until the last possible moment.
Batching isn't a panacea, though.  Batching only works if the sprites
being drawn share as much in common as possible.  Every time you draw
a sprite with a different texture or blend mode, the batch will be
sent off to the GPU.  Therefore, batching is most useful if you
minimize such changes.  A good strategy for reducing texture changes
is to stuff many bitmaps into a single image file and create a
``texture atlas'' (@pxref{Textures}) to access the sub-images within.

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 {Syntax} with-batched-sprites @var{body} @dots{}
Use batched rendering for all @code{draw-sprite} calls within
@var{body}.
@end deffn

With a basic sprite abstraction in place, it's possible to build other
abstractions on top of it.  One such example is the ``nine patch''.  A
nine patch is a sprite that can be rendered at various sizes without
becoming distorted.  This is achieved by diving up the sprite into
nine regions:

@itemize
@item
the center, which can be scaled horizontally and vertically
@item
the four corners, which can never be scaled
@item
the left and right sides, which can be scaled vertically
@item
the top and bottom sides, which can be scaled horizontally
@end itemize

The one caveat is that the bitmap regions must be designed in such a
way so that they are not distorted when stretched along the affected
axes.  For example, that means that the top and bottom sides could
have varying colored pixels vertically, but not horizontally.

The most common application of this technique is for graphical user
interface widgets like buttons and dialog boxes.  By using a nine
patch, they can be rendered at any size without unappealing scaling
artifacts.

@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] @
       [#:shader]

Draw a nine patch sprite.  A nine patch sprite renders @var{texture}
as a @var{width} x @var{height} rectangle whose stretchable areas are
defined by the given margin measurements @var{top-margin},
@var{bottom-margin}, @var{left-margin}, and @var{right-margin}. The
@var{margin} argument may be used to configure all four margins at
once.

Refer to @code{draw-sprite} (@pxref{Sprites}) for information about
the other arguments.
@end deffn

@node Lines and Shapes
@subsection Lines and Shapes

Sprites are fun, but sometimes simple, untextured lines and polygons
are desired.  That's where the @code{(chickadee render shapes)} module
comes in!

@deffn {Procedure} draw-line @var{start} @var{end} @
       [#:thickness 0.5] [#:feather 1.0] [#:cap round] [#:color] @
       [#:shader]

Draw a line segment from @var{start} to @var{end}. The line will be
@var{thickness} pixels thick with an antialiased border @var{feather}
pixels wide.  The line will be colored @var{color}. @var{cap}
specifies the type of end cap that should be used to terminate the
lines, either @code{none}, @code{butt}, @code{square}, @code{round},
@code{triangle-in}, or @code{triangle-out}.  Advanced users may use
the @var{shader} argument to override the built-in line segment
shader.
@end deffn

@node Fonts
@subsection Fonts

Unlike the traditional TrueType font format that many are accustomed
to, Chickadee loads and renders bitmap fonts in the
@url{http://www.angelcode.com/products/bmfont/doc/file_format.html,
Angel Code format}.  But why use this seemingly obscure format?  It's
easy to find TTFs but not easy to find FNTs (the canonical file
extension used for Angel Code fonts) and bitmap fonts don't scale
well.  The reason is efficiency.

If all of the glyphs of a font are pre-rendered and packed into an
image file then it becomes possible to use a texture atlas
(@pxref{Textures}) and a sprite batch (@pxref{Sprites}) when
rendering, which is a more efficient way to render fonts than using,
say, @url{https://www.libsdl.org/projects/SDL_ttf/, SDL_ttf} or other
solutions that involve using the FreeType library directly.

Now what about scaling?  In libraries that use TTF fonts, one must
choose the size that the glyphs will be rasterized at up front.  To
use @code{n} sizes of the same font, one must load @code{n} variants
of that font.  If the size of the text is dynamic, some kind of
texture scaling algorithm must be used and the text will inevitably
look blurry.  At first glance, using bitmap fonts seem to have an even
worse issue.  Instead of just loading the same font @code{n} times at
different sizes, one would need to generate @code{n} image files for
each font size needed.  This is where the ``signed distance field''
rendering technique comes in.  Introduced by
@url{http://www.valvesoftware.com/.../2007/SIGGRAPH2007_AlphaTestedMagnification.pdf,
Valve} in 2007, signed distance field fonts can be efficiently stored
in a bitmap and be rendered at arbitrary scale factors with good
results.  Chickadee can render both traditional bitmap fonts and
signed distance field fonts.  @emph{Signed distance field font
rendering is not yet available, so be patient.}

While Chickadee does not yet offer a tool for converting TTF fonts
into FNT fonts, tools such as
@url{https://github.com/libgdx/libgdx/wiki/Hiero, Hiero} may be used
in the meantime.

The following procedures can be found in the @code{(chickadee render
font)} module.

@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 {Procedure} font? @var{obj}
Return @code{#t} if @var{obj} is a font object.
@end deffn

@deffn {Procedure} font-face @var{font}
Return the name of @var{font}.
@end deffn

@deffn {Procedure} font-line-height @var{font}
Return the line height of @var{font}.
@end deffn

@deffn {Procedure} font-line-height @var{font}
Return the line height of @var{font}.
@end deffn

@deffn {Procedure} font-bold? @var{font}
Return @code{#t} if @var{font} is a bold font.
@end deffn

@deffn {Procedure} font-italic? @var{font}
Return @code{#t} if @var{font} is an italicized font.
@end deffn

@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
@var{position} using @var{font}.

@example
(draw-text font "Hello, world!" (vec2 128.0 128.0))
@end example

Refer to @code{draw-sprite} (@pxref{Sprites}) for information about
the other arguments.
@end deffn

@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

Chickadee has two data types for audio: samples and music.  Samples
are for short sound effects like explosions.  Music is for, well,
uh@dots{}, music.

Supported file formats include WAV and OGG.

@deffn {Procedure} load-sample @var{file}
Load audio sample from @var{file}.
@end deffn

@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 {Procedure} play-sample @var{sample}
Play @var{sample}.  Pretty straightforward!
@end deffn

@deffn {Procedure} load-music @var{file}
Load music from @var{file}.
@end deffn

@deffn {Procedure} music-volume
Return the volume level for music, an integer value between 0 and 128.
@end deffn

@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 {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 {Procedure} pause-music
Pause the current music track.
@end deffn

@deffn {Procedure} resume-music
Resume the current music track.
@end deffn

@deffn {Procedure} rewind-music
estart the current music track from the beginning.
@end deffn

@deffn {Procedure} stop-music
Stop playing the current music track.
@end deffn

@deffn {Procedure} music-playing?
Return @code{#t} if music is currently playing.
@end deffn

@deffn {Procedure} music-paused?
Return @code{#t} if music is currently paused.
@end deffn

@node Buffers
@section Buffers

Games are big state machines and they can get complex quickly, thus we
need tools to manage that complexity.  One useful technique is to
separate the many ``screens'' of a game (such as the main menu, player
select screen, high score table, game over screen, etc.) from each
other, so that it is possible to program the logic for one section of
the game independent of another.  In Chickadee, these ``screens'' are
called ``buffers''.  In other game engines this same construct may be
called a ``scene'' or ``room''.

A buffer knows how to update its state, render, handle input events,
etc.  Only one buffer is ever active at a time, and the current buffer
can be changed with procedures like @code{push-buffer},
@code{replace-buffer}, and @code{pop-buffer}.

Buffers are implemented using Guile's object oriented programming
system (@pxref{GOOPS,,, guile, GNU Guile Reference Manual}).  Each
type of buffer is represented as a subclass of the @code{<buffer>}
class.  Once a new buffer class has been created, there are many
methods that can be specialized for that class.

To install buffer support and set the initial buffer, call the
@code{use-buffers!} procedure.

Let's take a look at a simple example to see how it all comes
together:

@example
(use-modules (chickadee)
             (chickadee buffer)
             (chickadee math vector)
             (chickadee render sprite)
             (chickadee render texture)
             (oop goops))

;; Define a new buffer type.
(define-class <splash-screen> (<buffer>)
  (chickadee #:accessor chickadee #:init-value #f))

;; Define the logic for when the buffer is first activated.
(define-method (start (splash <splash-screen>))
  (set! (chickadee splash) (load-image "images/chickadee.png")))

;; Define how the buffer should be rendered.
(define-method (draw (splash <splash-screen>) alpha)
  (draw-sprite (chickadee splash) (vec2 256.0 176.0)))

;; Hook into the game engine and make the splash screen the initial buffer.
(use-buffers! (make <splash-screen>))

;; Start the game!
(run-game)
@end example

@deffn {Class} <buffer>
The parent class for all buffers.
@end deffn

@deffn {Method} started? @var{buffer}
Return @code{#t} if @var{buffer} has been activated by the game engine.
@end deffn

@deffn {Method} start @var{buffer}
Called when @var{buffer} becomes the current buffer for the first time.
@end deffn

@deffn {Method} stop @var{buffer}
Called when @var{buffer} is no longer in use.
@end deffn

@deffn {Method} pause @var{buffer}
Called when @var{buffer} is no longer the current buffer but still in
use.
@end deffn

@deffn {Method} resume @var{buffer}
Called when @var{buffer} becomes the current buffer after having been
suspended.
@end deffn

The following methods are simply wrappers around the hooks described
in @xref{Kernel}, so see that section for more detail about the
arguments to these methods.  The engine calls these methods with the
current buffer as the first argument.

@deffn {Method} update @var{buffer} @var{dt}
Advance the simulation running in @var{buffer} by @var{dt} units of
time.
@end deffn

@deffn {Method} abort @var{buffer}
Called when the user tries to close the game window.
@end deffn

@deffn {Method} before-draw @var{buffer}
Called before @var{buffer} is rendered.
@end deffn

@deffn {Method} after-draw @var{buffer}
Called after @var{buffer} is rendered.
@end deffn

@deffn {Method} draw @var{buffer} @var{alpha}
Render @var{buffer}.
@end deffn

@deffn {Method} key-press @var{buffer} @var{key} @var{scancode} @var{modifiers} @var{repeat?}
Handle key press event.
@end deffn

@deffn {Method} key-release @var{buffer} @var{key} @var{scancode} @var{modifiers}
Handle key release event.
@end deffn

@deffn {Method} text-input @var{buffer} @var{text}
Handle text input event.
@end deffn

@deffn {Method} mouse-press @var{buffer} @var{button} @var{clicks} @var{x} @var{y}
Handle mouse press event.
@end deffn

@deffn {Method} mouse-release @var{buffer} @var{button} @var{x} @var{y}
Handle mouse release event.
@end deffn

@deffn {Method} mouse-move @var{buffer} @var{x} @var{y} @var{x-rel} @var{y-rel} @var{buttons}
Handle mouse move event.
@end deffn

@deffn {Method} controller-add @var{buffer} @var{controller}
Handle controller add event.
@end deffn

@deffn {Method} controller-remove @var{buffer} @var{controller}
Handle controller remove event.
@end deffn

@deffn {Method} controller-press @var{buffer} @var{controller} @var{button}
Handle controller press event.
@end deffn

@deffn {Method} controller-release @var{buffer} @var{controller} @var{button}
Handle controller release event.
@end deffn

@deffn {Method} controller-move @var{buffer} @var{controller} @var{axis} @var{value}
Handle controller move event.
@end deffn

The following procedures are used to manage the buffer stack:

@deffn {Procedure} use-buffers! @var{initial-buffer}
Install buffers into the game engine and set the current buffer to
@var{initial-buffer}.
@end deffn

@deffn {Procedure} push-buffer! @var{buffer}
Pause the current buffer and switch to @var{buffer}.
@end deffn

@deffn {Procedure} pop-buffer!
Stop the current buffer and switch back to the previously active
buffer, or terminate the game loop if the buffer stack is empty.
@end deffn

@deffn {Procedure} replace-buffer! @var{buffer}
Stop the current buffer and switch to @var{buffer}
@end deffn

@deffn {Procedure} current-buffer
Return the current buffer.
@end deffn

@node Scripting
@section Scripting

Game logic is a web of asynchronous events that are carefully
coordinated to bring the game world to life.  In order to make an
enemy follow and attack the player, or move an NPC back and forth in
front of the item shop, or do both at the same time, a scripting
system is a necessity.  Chickadee comes with an asynchronous
programming system in the @code{(chickadee scripting)} module.
Lightweight, cooperative threads known as ``scripts'' allow the
programmer to write asynchronous code as if it were synchronous, and
allow many such ``threads'' to run concurrently.

But before we dig deeper into scripts, let's discuss the simple act
of scheduling tasks.

@menu
* Agendas::                     Scheduling tasks.
* Scripts::                     Cooperative multitasking.
* Tweening::                    Animations.
* Channels::                    Publish data to listeners.
@end menu

@node Agendas
@subsection Agendas

To schedule a task to be performed later, an ``agenda'' is used.
There is a default, global agenda that is ready to be used, or
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
(at 10 (display "hello\n"))
@end example

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
(after 10 (display "hello\n"))
@end example

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 hook
(@pxref{Kernel}) to 1 unit of agenda time, like so:

@example
(add-hook! update-hook (lambda (dt) (update-agenda 1)))
@end example

It is important to call @code{update-agenda} periodically, otherwise
no tasks will ever be run!

In addition to using the global agenda, it is useful to have multiple
agendas for different purposes.  For example, the game world can use a
different agenda than the user interface, so that pausing the game is
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
(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

@deffn {Procedure} make-agenda
Return a new task scheduler.
@end deffn

@deffn {Procedure} agenda? @var{obj}
Return @code{#t} if @var{obj} is an agenda.
@end deffn

@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 {Syntax} with-agenda @var{agenda} @var{body} @dots{}
Evaluate @var{body} with the current agenda set to @var{agenda}.
@end deffn

@deffn {Procedure} agenda-time
Return the current agenda time.
@end deffn

@deffn {Procedure} update-agenda @var{dt}
Advance the current agenda by @var{dt}.
@end deffn

@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 {Procedure} schedule-after @var{delay} @var{thunk}
Schedule @var{thunk}, a procedure of zero arguments, to be run after
@var{delay}.
@end deffn

@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 {Syntax} at @var{time} @var{body} @dots{}
Schedule @var{body} to be evaluated at @var{time}.
@end deffn

@deffn {Syntax} after @var{delay} @var{body} @dots{}
Schedule @var{body} to be evaluated after @var{delay}.
@end deffn

@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

@node Scripts
@subsection Scripts

Now that we can schedule tasks, let's take things to the next level.
It sure would be great if we could make procedures that described a
series of actions that happened over time, especially if we could do
so without contorting our code into a nest of callback procedures.
This is where scripts come in.  With scripts we can write code in a
linear way, in a manner that appears to be synchronous, but with the
ability to suspend periodically in order to let other scripts have a
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
(script
  (while #t
    (display "mom!")
    (newline)
    (sleep 60))) ; where 60 = 1 second of real time
@end example

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.
So, after each iteration of the loop, control is returned back to the
game loop and the program is not stuck spinning in a loop that will
never exit.  Pretty neat, eh?

Scripts can suspend to any capable handler, not just the agenda.
The @code{yield} procedure will suspend the current script and pass
its ``continuation'' to a handler procedure.  This handler procedure
could do anything.  Perhaps the handler stashes the continuation
somewhere where it will be resumed when the user presses a specific
key on the keyboard, or maybe it will be resumed when the player picks
up an item off of the dungeon floor; the sky is the limit.

Sometimes it is necessary to abruptly terminate a script after it has
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
(define script (script (while #t (display "hey\n") (sleep 60))))
;; sometime later
(cancel-script script)
@end example

@deffn {Procedure} spawn-script @var{thunk}
Apply @var{thunk} as a script and return a handle to it.
@end deffn

@deffn {Syntax} script @var{body} @dots{}
Evaluate @var{body} as a script and return a handle to it.
@end deffn

@deffn {Procedure} script? @var{obj}
Return @code{#t} if @var{obj} is a script handle.
@end deffn

@deffn {Procedure} script-cancelled? @var{obj}
Return @code{#t} if @var{obj} has been cancelled.
@end deffn

@deffn {Procedure} script-running? @var{obj}
Return @code{#t} if @var{obj} has not yet terminated or been
cancelled.
@end deffn

@deffn {Procedure} script-complete? @var{obj}
Return @code{#t} if @var{obj} has terminated.
@end deffn

@deffn {Procedure} cancel-script @var{co}
Prevent further execution of the script @var{co}.
@end deffn

@deffn {Procedure} yield @var{handler}
Suspend the current script and pass its continuation to the
procedure @var{handler}.
@end deffn

@deffn {Procedure} sleep @var{duration}
Wait @var{duration} before resuming the current script.
@end deffn

@deffn {Procedure} channel-get @var{channel}
Wait for a message from @var{channel}.
@end deffn

@deffn {Syntax} forever @var{body} @dots{}
Evaluate @var{body} in an endless loop.
@end deffn

@node Tweening
@subsection Tweening

Tweening is the process of transitioning something from an initial
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
(define x 0)
(script
  ;; 0 to 100 in 60 ticks of the agenda.
  (tween 60 0 100 (lambda (y) (set! x y))))
@end example

@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.

To control how the animation goes from the initial to final state, an
``easing'' procedure may be specified.  By default, the
@code{smoothstep} easing is used, which is a more pleasing default
than a simplistic linear function.  @xref{Easings} for a complete list
of available easing procedures.

The @var{interpolate} procedure computes the values in between
@var{start} and @var{end}.  By default, linear interpolation (``lerp''
for short) is used.
@end deffn

@node Channels
@subsection Channels

Channels are a tool for communicating amongst different scripts.  One
script can write a value to the channel and another can read from it.
Reading or writing to a channel suspends that script until there is
someone on the other end of the line to complete the transaction.

Here's a simplistic example:

@example
(define c (make-channel))

(script
 (forever
  (let ((item (channel-get c)))
    (pk 'got item))))

(script
 (channel-put c 'sword)
 (channel-put c 'shield)
 (channel-put c 'potion))
@end example

@deffn {Procedure} make-channel
Return a new channel
@end deffn

@deffn {Procedure} channel? @var{obj}
Return @code{#t} if @var{obj} is a channel.
@end deffn

@deffn {Procedure} channel-get @var{channel}
Retrieve a value from @var{channel}.  The current script suspends
until a value is available.
@end deffn

@deffn {Procedure} channel-put @var{channel} @var{data}
Send @var{data} to @var{channel}.  The current script suspends until
another script is available to retrieve the value.
@end deffn