source: project/wiki/eggref/4/sdl2 @ 32860

Last change on this file since 32860 was 32860, checked in by John Croisant, 5 years ago

sdl2: Changes related to rwops.

File size: 123.4 KB
Line 
1== sdl2
2
3[[toc:]]
4
5== Introduction
6
7The sdl2 egg provides bindings to [[http://libsdl.org/|Simple
8DirectMedia Layer]] version 2 (SDL2). SDL is a popular library
9used in games and other media-rich software.
10
11The sdl2 egg provides a programmer-friendly, convenient, and
12CHICKEN-idiomatic interface to SDL2. It takes care of the annoying
13low-level C stuff for you, so you can focus on making your game.
14
15If a feature you need is not yet available, please
16[[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/CONTRIBUTING.md#filing-feature-requests|file a feature request]]
17or contact a maintainer, so we can prioritize adding it.
18
19; Project / Source Code Repository : [[https://gitlab.com/chicken-sdl2/chicken-sdl2]]
20; Issue Tracker : [[https://gitlab.com/chicken-sdl2/chicken-sdl2/issues]]
21; Maintainer : John Croisant (john+chicken at croisant dot net)
22; License: [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/LICENSE-BSD.txt|BSD 2-Clause]]
23
24
25== Help Wanted!
26
27This egg needs volunteers to help with several things:
28
29* Writing API reference docs, guides, and tutorials
30* Writing unit tests and semi-automated test programs
31* Testing on different platforms and helping create good installation instructions
32* Creating feature demos and example games/programs
33
34If you wish to help in any way, please contact the project maintainer.
35
36
37== Requirements
38
39The sdl2 egg requires [[http://libsdl.org/|Simple DirectMedia Layer]]
40version 2.0.0 or higher. It will not work with older versions of SDL.
41
42The unit tests depend on the [[/egg/test|test]] egg, and many demos
43and examples depend on the [[/egg/miscmacros|miscmacros]] egg. Some
44demos and examples have other dependencies as well.
45
46
47== Installation
48
49'''ATTENTION:''' The sdl2 egg has not been released yet. For now, you
50must download it from its source code repository and follow the
51instructions in the README.
52
53When installing the egg, you should set the SDL2_FLAGS environment
54variable to a string of compiler flags to be used when compiling the
55egg. If you have the {{sdl2-config}} helper program installed on your
56system, you can set appropriate flags and install the extension like
57so (notice these are back ticks, not quotes):
58
59 export SDL2_FLAGS=`sdl2-config --cflags --libs`
60 chicken-install sdl2
61
62If you do not have the [[sdl2-config]] helper program installed on your
63computer, you may manually specify SDL-related compiler flags (notice
64these are double quotes, not back ticks):
65
66 export SDL2_FLAGS="-I/usr/local/include/SDL2 -L/usr/local/lib -lSDL2"
67 chicken-install sdl2
68
69The SDL2_FLAGS environment variable only needs to be set during
70installation of the egg, not during normal use.
71
72
73== Usage and Examples
74
75It is recommended that you import the sdl2 module using the prefix
76"sdl2:", like so:
77
78<enscript highlight="scheme">
79(use (prefix sdl2 sdl2:))
80(sdl2:init! '(everything))
81(sdl2:create-window! "Test" 0 0 600 400)
82(sdl2:delay! 1000)
83(sdl2:quit!)
84</enscript>
85
86The [[https://gitlab.com/chicken-sdl2/chicken-sdl2/tree/master/demos|demos directory]]
87contains small programs demonstrating how to use various features of sdl2.
88E.g. to compile and run the basics demo:
89
90 csc demos/basics.scm
91 demos/basics
92
93The [[https://gitlab.com/chicken-sdl2/chicken-sdl2-examples|chicken-sdl2-examples repository]]
94contains complete example games and programs made with sdl2.
95
96
97== Related Libraries
98
99The [[/egg/sdl2-image|sdl2-image egg]] provides bindings to version 2
100of the SDL_image library. It is built to be compatible with sdl2.
101
102The [[/egg/sdl-base|sdl-base egg]] provides bindings to older versions
103of SDL. Its API is not cross-compatible with sdl2.
104
105
106== Version History
107
108The sdl2 egg has not yet been released. Coming soon!
109
110
111== Backwards Compatibility and Stability
112
113The sdl2 egg follows "[[http://semver.org/|semantic versioning]]". The
114API is not stable until version 1.0 is released. That means the API
115may change in ways that break backwards compatibility with previous
116versions. After version 1.0 is released, the API will remain stable
117(no backwards-incompatible changes) until the next new major version
118(e.g. going from version 1.x to 2.0, or 2.x to 3.0).
119
120The sdl2 egg's API is not cross-compatible with the [[/egg/sdl-base|sdl-base egg]].
121
122
123== API
124
125=== Conventions
126
127* Procedure names are lower case and hyphenated, with no "SDL_"
128  prefix.
129
130* Procedures that return #t or #f are suffixed with "?".
131
132* Procedures that cause a mutation or side effect are suffixed with "!".
133
134* Procedures that set the value of an attribute are named like
135  {{TYPE-ATTR-set!}}, e.g. {{rect-x-set!}}.
136** In most cases, it is also possible to use {{(set! ...)}} to set
137   the value of attributes, e.g. {{(set! (rect-x my-rect) 42)}}.
138
139* Some procedures return multiple values, e.g. {{window-size}}
140  returns two values, the width and height. You can use {{receive}},
141  {{let-values}}, etc. to catch all the return values.
142
143* Procedures that allocate a new struct often have two versions, one
144  that returns a managed struct record and one that returns an
145  unmanaged struct record, e.g. {{make-surface}} and
146  {{make-surface*}}. See the Struct Memory Management section below
147  for more information.
148
149* Some procedures have a "raw" version, which returns a value that is
150  "lower level", such as an integer constant or memory pointer. These
151  are intended for advanced usage, such as interoperating with other
152  libraries, or for situations where performance is more important
153  than convenience or safety.
154
155* Many procedures that return an enum symbol or a list of enum
156  symbols, also have a "raw" version that returns an integer value,
157  e.g. {{event-type}} and {{event-type-raw}}.
158** Setters that accept an enum symbol will also accept the
159   corresponding integer value. Setters that accept a list of enum
160   symbols will also accept an integer representing bitwise-or'd
161   integer flags or masks.
162
163* Most procedures with a name containing the word "color" have an
164  alias spelled as "colour", for the convenience of anyone who spells
165  it that way. Both names refer to exactly the same procedure.
166
167
168
169=== Enums
170
171The sdl2 egg uses symbols instead of integer constants, for things
172like event types, keyboard keys, and init flags. See the
173[[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md|enum tables]]
174for details.
175
176
177
178=== Struct Record Types
179
180The sdl2 egg has many "struct record types", which are record types
181that wrap a pointer to a certain kind of C structure from SDL. For
182example, the sdl2:surface record type wraps a pointer to an
183SDL_Surface struct.
184
185Each struct record type has some associated procedures, which get or
186set the value of a certain field of the underlying C struct.
187
188
189==== Struct Memory Management
190
191Some struct record types have procedures for allocating or freeing an
192instance of that type. Every type that can be allocated, has two
193allocator procedures, one without an asterisk and one with an
194asterisk:
195
196* The procedure with NO asterisk (e.g. {{alloc-event}}) returns a
197  '''managed''' struct record, whose underlying struct will be
198  automatically freed when the record is garbage collected.
199
200* The procedure with an asterisk (e.g. {{alloc-event*}}) returns an
201  '''unmanaged''' struct record, which must be manually freed when you
202  are done with it (e.g. using {{free-event!}}).
203
204Some procedures that return new objects also follow this convention,
205for example {{make-surface}} vs. {{make-surface*}}, and {{load-bmp}}
206vs. {{load-bmp*}}.
207
208In general, it is recommended to create managed struct records, so
209that you don't have to worry about manually freeing them. However,
210there is a slight overhead to managing struct records, so if you are
211creating and destroying many thousands of struct records, it is more
212efficient to create unmanaged struct records and manually free them
213when you are done with them. (But be careful! If you forget to free
214them, your program will leak memory.)
215
216If you create an unmanaged struct record but later change your mind,
217you can start managing it by using {{set-finalizer!}} with the
218appropriate "free" procedure. (Note: it is not currently possible to
219''stop'' managing a struct record.) For example:
220
221<enscript highlight="scheme">
222;; Allocate an unmanaged sdl2:event.
223(let ((my-event (sdl2:alloc-event*)))
224  ;; Overwrite its data with the next pending event.
225  (sdl2:wait-event! my-event)
226
227  (case (sdl2:event-type my-event)
228    ;; Put keyboard events in a queue for later processing. We aren't
229    ;; sure how long it will live, so start managing it, to be safe.
230    ((key-down key-up)
231     (set-finalizer! my-event sdl2:free-event!)
232     (put-in-queue my-event))
233    ;; If it is any other type of event, perform an immediate action
234    ;; on it, then free it.
235    (else
236     (perform-immediate-action my-event)
237     (sdl2:free-event! my-event))))
238</enscript>
239
240It is safe to manually free managed struct records. In fact, doing so
241can be beneficial to your program's memory footprint and performance,
242because there will be less memory waiting to be freed by the garbage
243collector. For example:
244
245<enscript highlight="scheme">
246(let ((my-surf (sdl2:make-surface 800 600 32)))
247  ;; ... do stuff with my-surf ...
248  ;; Once you are done with my-surf, manually free it.
249  (sdl2:free-surface! my-surf))
250</enscript>
251
252As soon as you free a struct record, its pointer will be set to null,
253and it will no longer be usable for most purposes. You cannot get or
254set its fields, or pass it as an argument to most procedures. So be
255careful not to free struct records that you still want to use!
256
257Some struct record types, such as sdl2:window, are not allocated or
258freed. Instead, you use certain SDL functions to work with them, such
259as {{create-window!}} and {{destroy-window!}}.
260
261
262<procedure>(struct-null? record) → boolean</procedure>
263
264Returns #t if the given record is wrapping a null pointer (i.e. a
265pointer with memory address 0). This procedure can be used with any
266struct record type provided by this library.
267
268There are two common reasons why a record might be wrapping a null
269pointer:
270
271* After you free a record (e.g. using {{free-surface!}}), its pointer
272  will be set to null.
273* Certain procedures may return a record with a null pointer if an
274  error occurs or the requested object does not exist.
275
276It is an error to get or set any field of a record that is wrapping a
277null pointer. And, it is an error to pass null struct records to many
278procedures. So, you can use this procedure to check whether it is safe
279to use the record.
280
281
282
283==== sdl2:audio-cvt
284
285sdl2:audio-cvt is a record type that wraps a pointer to an
286[[https://wiki.libsdl.org/SDL_AudioCVT|SDL_AudioCVT]] struct.
287
288
289<procedure>(audio-cvt? obj) → boolean</procedure>
290
291Returns #t if {{obj}} is an sdl2:audio-cvt.
292
293
294<procedure>(audio-cvt-needed audio-cvt) → fixnum</procedure>
295
296Get the value of the SDL_AudioCVT's "needed" field, as an integer.
297
298
299<procedure>(audio-cvt-src-format audio-cvt) → symbol</procedure>
300
301Get the value of the SDL_AudioCVT's "src_format" field, as an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#audio-formats|audio format symbol]].
302
303
304<procedure>(audio-cvt-src-format-raw audio-cvt) → fixnum</procedure>
305
306Get the value of the SDL_AudioCVT's "src_format" field, as an integer.
307See also {{audio-cvt-src-format}}.
308
309
310<procedure>(audio-cvt-dst-format audio-cvt) → symbol</procedure>
311
312Get the value of the SDL_AudioCVT's "dst_format" field, as an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#audio-formats|audio format symbol]].
313
314
315<procedure>(audio-cvt-dst-format-raw audio-cvt) → fixnum</procedure>
316
317Get the value of the SDL_AudioCVT's "dst_format" field, as an integer.
318See also {{audio-cvt-dst-format}}.
319
320
321<procedure>(audio-cvt-rate-incr audio-cvt) → double</procedure>
322
323Get the value of the SDL_AudioCVT's "rate_incr" field, as a double
324precision floating point number.
325
326
327<procedure>(audio-cvt-buf-raw audio-cvt) → pointer</procedure>
328
329Get the value of the SDL_AudioCVT's "buf" field, as a pointer to a C
330array of Uint8 numbers. Use audio-cvt-len to get the length of the
331array.
332
333
334<procedure>(audio-cvt-len audio-cvt) → fixnum</procedure>
335
336Get the value of the SDL_AudioCVT's "len" field, as an integer. This
337is the length of the array returned by {{audio-cvt-buf-raw}}.
338
339
340<procedure>(audio-cvt-len-cvt audio-cvt) → fixnum</procedure>
341
342Get the value of the SDL_AudioCVT's "len_cvt" field, as an integer.
343
344
345<procedure>(audio-cvt-len-mult audio-cvt) → fixnum</procedure>
346
347Get the value of the SDL_AudioCVT's "len_mult" field, as an integer.
348
349
350<procedure>(audio-cvt-len-ratio audio-cvt) → double</procedure>
351
352Get the value of the SDL_AudioCVT's "len_ratio" field, as a double
353precision floating point number.
354
355
356
357==== sdl2:audio-spec
358
359sdl2:audio-spec is a record type that wraps a pointer to an
360[[https://wiki.libsdl.org/SDL_AudioSpec|SDL_AudioSpec]] struct.
361
362
363<procedure>(audio-spec? obj) → boolean</procedure>
364
365Returns #t if {{obj}} is an sdl2:audio-spec.
366
367
368<procedure>(audio-spec-freq audio-spec) → fixnum</procedure>
369<setter>(set! (audio-spec-freq audio-spec) val)</setter>
370<setter>(audio-spec-freq-set! audio-spec freq)</setter>
371
372Get or set the value of the SDL_AudioSpec's "freq" field, as an
373integer (int).
374
375
376<procedure>(audio-spec-format audio-spec) → symbol</procedure>
377<setter>(set! (audio-spec-format audio-spec) format)</setter>
378<setter>(audio-spec-format-set! audio-spec format)</setter>
379
380Get or set the value of the SDL_AudioSpec's "format" field, as an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#audio-formats|audio format symbol]]. When setting, either a symbol or an integer will be accepted.
381
382
383<procedure>(audio-spec-format-raw audio-spec) → fixnum</procedure>
384<setter>(set! (audio-spec-format-raw audio-spec) val)</setter>
385
386Get or set the value of the SDL_AudioSpec's "format" field, as an
387integer. See also {{audio-spec-format}}.
388
389
390<procedure>(audio-spec-channels audio-spec) → fixnum</procedure>
391<setter>(set! (audio-spec-channels audio-spec) val)</setter>
392<setter>(audio-spec-channels-set! audio-spec channels)</setter>
393
394Get or set the value of the SDL_AudioSpec's "channels" field, as an
395integer (Uint8).
396
397
398<procedure>(audio-spec-silence audio-spec) → fixnum</procedure>
399
400Returns the value of the SDL_AudioSpec's "silence" field, as an
401integer (Uint8).
402
403
404<procedure>(audio-spec-samples audio-spec) → fixnum</procedure>
405<setter>(set! (audio-spec-samples audio-spec) val)</setter>
406<setter>(audio-spec-samples-set! audio-spec samples)</setter>
407
408Get or set the value of the SDL_AudioSpec's "samples" field, as an
409integer (Uint16).
410
411
412<procedure>(audio-spec-size audio-spec) → fixnum</procedure>
413
414Returns the value of the SDL_AudioSpec's "size" field, as an integer
415(Uint32).
416
417
418<procedure>(audio-spec-userdata-raw audio-spec) → pointer</procedure>
419<setter>(set! (audio-spec-userdata-raw audio-spec) val)</setter>
420<setter>(audio-spec-userdata-raw-set! audio-spec userdata)</setter>
421
422Get or set the value of the SDL_AudioSpec's "userdata" field, as a
423pointer.
424
425
426
427==== sdl2:color
428
429sdl2:color is a record type that wraps a pointer to an
430[[https://wiki.libsdl.org/SDL_Color|SDL_Color]] struct.
431
432
433<procedure>(color? obj) → boolean</procedure>
434<procedure>(colour? obj) → boolean</procedure>
435
436Returns #t if {{obj}} is an sdl2:color.
437
438
439<procedure>(make-color #!optional r g b a) → sdl2:color</procedure>
440<procedure>(make-colour #!optional r g b a) → sdl2:color</procedure>
441
442Allocate and initialize a new managed sdl2:color record.
443
444{{r}} {{g}} {{b}} and {{a}} are the red, green, blue, and alpha
445(opacity) fields of the color. They must be integers in the range 0 to
446255 (inclusive). {{r}} {{g}} and {{b}} default to 0. {{a}} defaults to
447255 (full opacity).
448
449
450<procedure>(alloc-color) → sdl2:color</procedure>
451<procedure>(alloc-colour) → sdl2:color</procedure>
452
453Allocate a new managed sdl2:color record. You probably want to use
454{{make-color}} instead.
455
456
457<procedure>(alloc-color*) → sdl2:color</procedure>
458<procedure>(alloc-colour*) → sdl2:color</procedure>
459
460Allocate a new '''unmanaged''' sdl2:color record. This is like
461{{alloc-color}}, except you must call {{free-color!}} on the record
462when you are done with it.
463
464
465<procedure>(free-color! color)</procedure>
466<procedure>(free-colour! color)</procedure>
467
468Free the memory of the sdl2:color's underlying struct. {{color}}'s
469pointer will be set to null (see {{struct-null?}}). It is safe to call
470this procedure with managed or unmanaged sdl2:color records. It is
471safe (but has no effect) to free a struct record multiple times.
472
473
474<procedure>(color-r color) → fixnum</procedure>
475<procedure>(colour-r color) → fixnum</procedure>
476<setter>(set! (color-r color) r)</setter>
477<setter>(set! (colour-r color) r)</setter>
478<setter>(color-r-set! color r)</setter>
479<setter>(colour-r-set! color r)</setter>
480
481Get or set the SDL_Color's "r" (red) field, as an integer in the range
4820 to 255 (inclusive).
483
484
485<procedure>(color-g color) → fixnum</procedure>
486<procedure>(colour-g color) → fixnum</procedure>
487<setter>(set! (color-g color) g)</setter>
488<setter>(set! (colour-g color) g)</setter>
489<setter>(color-g-set! color g)</setter>
490<setter>(colour-g-set! color g)</setter>
491
492Get or set the SDL_Color's "g" (green) field, as an integer in the
493range 0 to 255 (inclusive).
494
495
496<procedure>(color-b color) → fixnum</procedure>
497<procedure>(colour-b color) → fixnum</procedure>
498<setter>(set! (color-b color) b)</setter>
499<setter>(set! (colour-b color) b)</setter>
500<setter>(color-b-set! color b)</setter>
501<setter>(colour-b-set! color b)</setter>
502
503Get or set the SDL_Color's "b" (blue) field, as an integer in the
504range 0 to 255 (inclusive).
505
506
507<procedure>(color-a color) → fixnum</procedure>
508<procedure>(colour-a color) → fixnum</procedure>
509<setter>(set! (color-a color) a)</setter>
510<setter>(set! (colour-a color) a)</setter>
511<setter>(color-a-set! color a)</setter>
512<setter>(colour-a-set! color a)</setter>
513
514Get or set the SDL_Color's "a" (alpha) field, as an integer in the
515range 0 to 255 (inclusive).
516
517
518<setter>(color-set! color #!optional r g b a) → color</setter>
519<setter>(colour-set! color #!optional r g b a) → color</setter>
520
521Convenient way of setting multiple fields of the SDL_Color. Any
522arguments that are {{#f}} will cause no change to that field. E.g.
523{{(color-set! my-color 42 #f 255 #f)}} will set the {{r}} field to 42
524and the {{b}} field to 255, but will not change the {{g}} or {{a}}
525fields. Returns {{color}} after it is modified.
526
527
528<procedure>(color->list color) → list of fixnums</procedure>
529<procedure>(colour->list color) → list of fixnums</procedure>
530
531Returns a list {{(r g b a)}} containing all the fields of the
532sdl2:color.
533
534
535
536==== sdl2:cursor
537
538sdl2:cursor is a record type that wraps a pointer to an
539[[https://wiki.libsdl.org/SDL_CreateCursor|SDL_Cursor]] struct.
540
541
542<procedure>(cursor? obj) → boolean</procedure>
543
544Returns #t if {{obj}} is an sdl2:cursor.
545
546
547
548==== sdl2:display-mode
549
550sdl2:display-mode is a record type that wraps a pointer to an
551[[https://wiki.libsdl.org/SDL_DisplayMode|SDL_DisplayMode]] struct.
552
553
554<procedure>(display-mode? obj) → boolean</procedure>
555
556Returns #t if {{obj}} is an sdl2:display-mode.
557
558
559<procedure>(alloc-display-mode) → sdl2:display-mode</procedure>
560
561Allocate a new managed sdl2:display-mode record.
562
563
564<procedure>(alloc-display-mode*) → sdl2:display-mode</procedure>
565
566Allocate a new '''unmanaged''' sdl2:display-mode record. This is like
567{{alloc-display-mode}}, except you must call {{free-display-mode!}} on
568the record when you are done with it.
569
570
571<procedure>(free-display-mode! display-mode)</procedure>
572
573Free the memory of the sdl2:display-mode's underlying struct.
574{{display-mode}}'s pointer will be set to null (see {{struct-null?}}).
575It is safe to call this procedure with managed or unmanaged
576sdl2:display-mode records. It is safe (but has no effect) to free a
577struct record multiple times.
578
579
580<procedure>(display-mode-format display-mode) → symbol</procedure>
581<setter>(set! (display-mode-format display-mode) val)</setter>
582<setter>(display-mode-format-set! display-mode)</setter>
583
584TODO: Docs.
585Returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]].
586
587
588<procedure>(display-mode-format-raw display-mode) → fixnum</procedure>
589<setter>(set! (display-mode-format-raw display-mode) val)</setter>
590
591TODO: Docs.
592See also {{display-mode-format}}.
593
594
595<procedure>(display-mode-w display-mode) → fixnum</procedure>
596<setter>(set! (display-mode-w display-mode) val)</setter>
597<setter>(display-mode-w-set! display-mode)</setter>
598
599TODO: Docs.
600
601
602<procedure>(display-mode-h display-mode) → fixnum</procedure>
603<setter>(set! (display-mode-h display-mode) val)</setter>
604<setter>(display-mode-h-set! display-mode)</setter>
605
606TODO: Docs.
607
608
609<procedure>(display-mode-refresh-rate display-mode) → fixnum</procedure>
610<setter>(set! (display-mode-refresh-rate display-mode) val)</setter>
611<setter>(display-mode-refresh-rate-set! display-mode)</setter>
612
613TODO: Docs.
614
615
616
617==== sdl2:event
618
619sdl2:event is a record type that wraps a pointer to an
620[[https://wiki.libsdl.org/SDL_Event|SDL_Event]]. There are many
621specific event structs in SDL, and the sdl2:event record type wraps
622them all. Each event struct has a corresponding variant of sdl2:event,
623described below. Each variant has one or more associated
624[[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbols]].
625
626
627<table>
628  <tr>
629    <th>Variant of sdl2:event</th>
630    <th>Underlying struct</th>
631    <th>Event type symbol(s)</th>
632  </tr>
633  <tr>
634    <td>[[#sdl2controller-axis-event|sdl2:controller-axis-event]]</td>
635    <td>[[https://wiki.libsdl.org/SDL_ControllerAxisEvent|SDL_ControllerAxisEvent]]</td>
636    <td>controller-axis-motion</td>
637  </tr>
638  <tr>
639    <td>[[#sdl2controller-button-event|sdl2:controller-button-event]]</td>
640    <td>[[https://wiki.libsdl.org/SDL_ControllerButtonEvent|SDL_ControllerButtonEvent]]</td>
641    <td>controller-button-down<br>
642        controller-button-up</td>
643  </tr>
644  <tr>
645    <td>[[#sdl2controller-device-event|sdl2:controller-device-event]]</td>
646    <td>[[https://wiki.libsdl.org/SDL_ControllerDeviceEvent|SDL_ControllerDeviceEvent]]</td>
647    <td>controller-device-added<br>
648        controller-device-removed<br>
649        controller-device-remapped</td>
650  </tr>
651  <tr>
652    <td>[[#sdl2dollar-gesture-event|sdl2:dollar-gesture-event]]</td>
653    <td>[[https://wiki.libsdl.org/SDL_DollarGestureEvent|SDL_DollarGestureEvent]]</td>
654    <td>dollar-gesture<br>
655        dollar-record</td>
656  </tr>
657  <tr>
658    <td>[[#sdl2drop-event|sdl2:drop-event]]</td>
659    <td>[[https://wiki.libsdl.org/SDL_DropEvent|SDL_DropEvent]]</td>
660    <td>drop-file</td>
661  </tr>
662  <tr>
663    <td>[[#sdl2joy-axis-event|sdl2:joy-axis-event]]</td>
664    <td>[[https://wiki.libsdl.org/SDL_JoyAxisEvent|SDL_JoyAxisEvent]]</td>
665    <td>joy-axis-motion</td>
666  </tr>
667  <tr>
668    <td>[[#sdl2joy-ball-event|sdl2:joy-ball-event]]</td>
669    <td>[[https://wiki.libsdl.org/SDL_JoyBallEvent|SDL_JoyBallEvent]]</td>
670    <td>joy-ball-motion</td>
671  </tr>
672  <tr>
673    <td>[[#sdl2joy-button-event|sdl2:joy-button-event]]</td>
674    <td>[[https://wiki.libsdl.org/SDL_JoyButtonEvent|SDL_JoyButtonEvent]]</td>
675    <td>joy-button-down<br>
676        joy-button-up</td>
677  </tr>
678  <tr>
679    <td>[[#sdl2joy-device-event|sdl2:joy-device-event]]</td>
680    <td>[[https://wiki.libsdl.org/SDL_JoyDeviceEvent|SDL_JoyDeviceEvent]]</td>
681    <td>joy-device-added<br>
682        joy-device-removed</td>
683  </tr>
684  <tr>
685    <td>[[#sdl2joy-hat-event|sdl2:joy-hat-event]]</td>
686    <td>[[https://wiki.libsdl.org/SDL_JoyHatEvent|SDL_JoyHatEvent]]</td>
687    <td>joy-hat-motion</td>
688  </tr>
689  <tr>
690    <td>[[#sdl2keyboard-event|sdl2:keyboard-event]]</td>
691    <td>[[https://wiki.libsdl.org/SDL_KeyboardEvent|SDL_KeyboardEvent]]</td>
692    <td>key-down<br>
693        key-up</td>
694  </tr>
695  <tr>
696    <td>[[#sdl2mouse-button-event|sdl2:mouse-button-event]]</td>
697    <td>[[https://wiki.libsdl.org/SDL_MouseButtonEvent|SDL_MouseButtonEvent]]</td>
698    <td>mouse-button-down<br>
699        mouse-button-up</td>
700  </tr>
701  <tr>
702    <td>[[#sdl2mouse-motion-event|sdl2:mouse-motion-event]]</td>
703    <td>[[https://wiki.libsdl.org/SDL_MouseMotionEvent|SDL_MouseMotionEvent]]</td>
704    <td>mouse-motion</td>
705  </tr>
706  <tr>
707    <td>[[#sdl2mouse-wheel-event|sdl2:mouse-wheel-event]]</td>
708    <td>[[https://wiki.libsdl.org/SDL_MouseWheelEvent|SDL_MouseWheelEvent]]</td>
709    <td>mouse-wheel</td>
710  </tr>
711  <tr>
712    <td>[[#sdl2multi-gesture-event|sdl2:multi-gesture-event]]</td>
713    <td>[[https://wiki.libsdl.org/SDL_MultiGestureEvent|SDL_MultiGestureEvent]]</td>
714    <td>multi-gesture</td>
715  </tr>
716  <tr>
717    <td>[[#sdl2quit-event|sdl2:quit-event]]</td>
718    <td>[[https://wiki.libsdl.org/SDL_QuitEvent|SDL_QuitEvent]]</td>
719    <td>quit</td>
720  </tr>
721  <tr>
722    <td>[[#sdl2sys-wm-event|sdl2:sys-wm-event]]</td>
723    <td>[[https://wiki.libsdl.org/SDL_SysWMEvent|SDL_SysWMEvent]]</td>
724    <td>sys-wm</td>
725  </tr>
726  <tr>
727    <td>[[#sdl2text-editing-event|sdl2:text-editing-event]]</td>
728    <td>[[https://wiki.libsdl.org/SDL_TextEditingEvent|SDL_TextEditingEvent]]</td>
729    <td>text-editing</td>
730  </tr>
731  <tr>
732    <td>[[#sdl2text-input-event|sdl2:text-input-event]]</td>
733    <td>[[https://wiki.libsdl.org/SDL_TextInputEvent|SDL_TextInputEvent]]</td>
734    <td>text-input</td>
735  </tr>
736  <tr>
737    <td>[[#sdl2touch-finger-event|sdl2:touch-finger-event]]</td>
738    <td>[[https://wiki.libsdl.org/SDL_TouchFingerEvent|SDL_TouchFingerEvent]]</td>
739    <td>finger-down<br>
740        finger-up<br>
741        finger-motion</td>
742  </tr>
743  <tr>
744    <td>[[#sdl2user-event|sdl2:user-event]]</td>
745    <td>[[https://wiki.libsdl.org/SDL_UserEvent|SDL_UserEvent]]</td>
746    <td>Call {{register-events!}} to register your own custom event type symbols</td>
747  </tr>
748  <tr>
749    <td>[[#sdl2window-event|sdl2:window-event]]</td>
750    <td>[[https://wiki.libsdl.org/SDL_WindowEvent|SDL_WindowEvent]]</td>
751    <td>window</td>
752  </tr>
753</table>
754
755
756
757<procedure>(event? obj) → boolean</procedure>
758
759Returns #t if {{obj}} is any variant of sdl2:event.
760
761
762<procedure>(alloc-event) → sdl2:event</procedure>
763
764Allocate a new managed sdl2:event record. You can set the event's type
765with {{event-type-set!}} to choose what variant of sdl2:event it
766should be.
767
768
769<procedure>(alloc-event*) → sdl2:event</procedure>
770
771Allocate a new '''unmanaged''' sdl2:event record. This is like
772{{alloc-event}}, except you must call {{free-event!}} on the record
773when you are done with it.
774
775
776<procedure>(free-event! event)</procedure>
777
778Free the memory of the sdl2:event's underlying struct. You can call
779this procedure with any variant of sdl2:event. {{event}}'s pointer
780will be set to null (see {{struct-null?}}). It is safe to call this
781procedure with managed or unmanaged sdl2:event records. It is safe
782(but has no effect) to free a struct record multiple times.
783
784
785<procedure>(event-type event) → symbol</procedure>
786<setter>(set! (event-type event) val)</setter>
787<setter>(event-type-set! event val)</setter>
788
789Get or set the sdl2:event's event type, as a
790[[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbol]].
791You can use this procedure with any variant of sdl2:event. Setting this
792will change what variant of sdl2:event it is. E.g. if you set it to the
793symbol {{'key-down}}, the event will become an sdl2:keyboard-event.
794
795
796<procedure>(event-type-raw event) → fixnum</procedure>
797<setter>(set! (event-type-raw event) val)</setter>
798<setter>(event-type-raw-set! event val)</setter>
799
800Get or set the sdl2:event's event type, as a nonnegative integer. You
801can use this procedure with any variant of sdl2:event.
802See also {{event-type}}.
803
804
805<procedure>(event-timestamp event) → fixnum</procedure>
806<setter>(set! (event-timestamp event) val)</setter>
807<setter>(event-timestamp-set! event val)</setter>
808
809Get or set the event timestamp, as a nonnegative integer representing
810the time that the event occurred, in milliseconds since the SDL timer
811system was initialized. You can use this procedure with any variant of
812sdl2:event.
813
814
815
816===== sdl2:controller-axis-event
817
818sdl2:controller-axis-event is a variant of sdl2:event that wraps a pointer to an
819[[https://wiki.libsdl.org/SDL_ControllerAxisEvent|SDL_ControllerAxisEvent]].
820
821
822<procedure>(controller-axis-event? obj) → boolean</procedure>
823
824Returns #t if {{obj}} is an sdl2:controller-axis-event.
825
826
827<procedure>(controller-axis-event-which event) → fixnum</procedure>
828<setter>(set! (controller-axis-event-which event) val)</setter>
829<setter>(controller-axis-event-which-set! event val)</setter>
830
831TODO: Docs.
832
833
834<procedure>(controller-axis-event-axis event) → fixnum</procedure>
835<setter>(set! (controller-axis-event-axis event) val)</setter>
836<setter>(controller-axis-event-axis-set! event val)</setter>
837
838TODO: Docs.
839
840
841<procedure>(controller-axis-event-value event) → fixnum</procedure>
842<setter>(set! (controller-axis-event-value event) val)</setter>
843<setter>(controller-axis-event-value-set! event val)</setter>
844
845TODO: Docs.
846
847
848
849===== sdl2:controller-button-event
850
851sdl2:controller-button-event is a variant of sdl2:event that wraps a pointer to an
852[[https://wiki.libsdl.org/SDL_ControllerButtonEvent|SDL_ControllerButtonEvent]].
853
854
855<procedure>(controller-button-event? obj) → boolean</procedure>
856
857TODO: Docs.
858
859
860<procedure>(controller-button-event-which event) → fixnum</procedure>
861<setter>(set! (controller-button-event-which event) val)</setter>
862<setter>(controller-button-event-which-set! event val)</setter>
863
864TODO: Docs.
865
866
867<procedure>(controller-button-event-button event) → fixnum</procedure>
868<setter>(set! (controller-button-event-button event) val)</setter>
869<setter>(controller-button-event-button-set! event val)</setter>
870
871TODO: Docs.
872
873
874<procedure>(controller-button-event-state event) → boolean</procedure>
875<setter>(set! (controller-button-event-state event) val)</setter>
876<setter>(controller-button-event-state-set! event val)</setter>
877
878TODO: Docs.
879
880
881
882===== sdl2:controller-device-event
883
884sdl2:controller-device-event is a variant of sdl2:event that wraps a pointer to an
885[[https://wiki.libsdl.org/SDL_ControllerDeviceEvent|SDL_ControllerDeviceEvent]].
886
887
888<procedure>(controller-device-event? obj) → boolean</procedure>
889
890Returns #t if {{obj}} is an sdl2:controller-device-event.
891
892
893<procedure>(controller-device-event-which event) → fixnum</procedure>
894<setter>(set! (controller-device-event-which event) val)</setter>
895<setter>(controller-device-event-which-set! event val)</setter>
896
897TODO: Docs.
898
899
900
901===== sdl2:dollar-gesture-event
902
903sdl2:dollar-gesture-event is a variant of sdl2:event that wraps a pointer to an
904[[https://wiki.libsdl.org/SDL_DollarGestureEvent|SDL_DollarGestureEvent]].
905
906
907<procedure>(dollar-gesture-event? obj) → boolean</procedure>
908
909Returns #t if {{obj}} is an sdl2:dollar-gesture-event.
910
911
912<procedure>(dollar-gesture-event-touch-id event) → fixnum</procedure>
913<setter>(set! (dollar-gesture-event-touch-id event) val)</setter>
914<setter>(dollar-gesture-event-touch-id-set! event val)</setter>
915
916TODO: Docs.
917
918
919<procedure>(dollar-gesture-event-gesture-id event) → fixnum</procedure>
920<setter>(set! (dollar-gesture-event-gesture-id event) val)</setter>
921<setter>(dollar-gesture-event-gesture-id-set! event val)</setter>
922
923TODO: Docs.
924
925
926<procedure>(dollar-gesture-event-num-fingers event) → fixnum</procedure>
927<setter>(set! (dollar-gesture-event-num-fingers event) val)</setter>
928<setter>(dollar-gesture-event-num-fingers-set! event val)</setter>
929
930TODO: Docs.
931
932
933<procedure>(dollar-gesture-event-error event) → float</procedure>
934<setter>(set! (dollar-gesture-event-error event) val)</setter>
935<setter>(dollar-gesture-event-error-set! event val)</setter>
936
937TODO: Docs.
938
939
940<procedure>(dollar-gesture-event-x event) → float</procedure>
941<setter>(set! (dollar-gesture-event-x event) val)</setter>
942<setter>(dollar-gesture-event-x-set! event val)</setter>
943
944TODO: Docs.
945
946
947<procedure>(dollar-gesture-event-y event) → float</procedure>
948<setter>(set! (dollar-gesture-event-y event) val)</setter>
949<setter>(dollar-gesture-event-y-set! event val)</setter>
950
951TODO: Docs.
952
953
954
955===== sdl2:drop-event
956
957sdl2:drop-event is a variant of sdl2:event that wraps a pointer to an
958[[https://wiki.libsdl.org/SDL_DropEvent|SDL_DropEvent]].
959
960
961<procedure>(drop-event? obj) → boolean</procedure>
962
963Returns #t if {{obj}} is an sdl2:drop-event.
964
965
966<procedure>(drop-event-file event) → string</procedure>
967<setter>(set! (drop-event-file event) val)</setter>
968<setter>(drop-event-file-set! event val)</setter>
969
970TODO: Docs.
971
972
973
974===== sdl2:joy-axis-event
975
976sdl2:joy-axis-event is a variant of sdl2:event that wraps a pointer to an
977[[https://wiki.libsdl.org/SDL_JoyAxisEvent|SDL_JoyAxisEvent]].
978
979
980<procedure>(joy-axis-event? obj) → boolean</procedure>
981
982Returns #t if {{obj}} is an sdl2:joy-axis-event.
983
984
985<procedure>(joy-axis-event-which event) → fixnum</procedure>
986<setter>(set! (joy-axis-event-which event) val)</setter>
987<setter>(joy-axis-event-which-set! event val)</setter>
988
989Returns the joystick ID number of the joystick that caused the event.
990
991
992<procedure>(joy-axis-event-axis event) → fixnum</procedure>
993<setter>(set! (joy-axis-event-axis event) val)</setter>
994<setter>(joy-axis-event-axis-set! event val)</setter>
995
996Returns the number of the axis that was moved.
997
998
999<procedure>(joy-axis-event-value event) → fixnum</procedure>
1000<setter>(set! (joy-axis-event-value event) val)</setter>
1001<setter>(joy-axis-event-value-set! event val)</setter>
1002
1003Returns the new value of the axis, as an integer in the range -32768
1004to 32767 (inclusive).
1005
1006
1007
1008===== sdl2:joy-ball-event
1009
1010sdl2:joy-ball-event is a variant of sdl2:event that wraps a pointer to an
1011[[https://wiki.libsdl.org/SDL_JoyBallEvent|SDL_JoyBallEvent]].
1012
1013
1014<procedure>(joy-ball-event? obj) → boolean</procedure>
1015
1016Returns #t if {{obj}} is an sdl2:joy-ball-event.
1017
1018
1019<procedure>(joy-ball-event-which event) → fixnum</procedure>
1020<setter>(set! (joy-ball-event-which event) val)</setter>
1021<setter>(joy-ball-event-which-set! event val)</setter>
1022
1023Returns the joystick ID number of the joystick that caused the event.
1024
1025
1026<procedure>(joy-ball-event-ball event) → fixnum</procedure>
1027<setter>(set! (joy-ball-event-ball event) val)</setter>
1028<setter>(joy-ball-event-ball-set! event val)</setter>
1029
1030Returns the number of the trackball that was moved.
1031
1032
1033<procedure>(joy-ball-event-xrel event) → fixnum</procedure>
1034<setter>(set! (joy-ball-event-xrel event) val)</setter>
1035<setter>(joy-ball-event-xrel-set! event val)</setter>
1036
1037Returns an integer (possibly negative) indicating how the trackball
1038position changed on the X axis, relative to its previous position.
1039
1040
1041<procedure>(joy-ball-event-yrel event) → fixnum</procedure>
1042<setter>(set! (joy-ball-event-yrel event) val)</setter>
1043<setter>(joy-ball-event-yrel-set! event val)</setter>
1044
1045Returns an integer (possibly negative) indicating how the trackball
1046position changed on the Y axis, relative to its previous position.
1047
1048
1049
1050===== sdl2:joy-button-event
1051
1052sdl2:joy-button-event is a variant of sdl2:event that wraps a pointer to an
1053[[https://wiki.libsdl.org/SDL_JoyButtonEvent|SDL_JoyButtonEvent]].
1054
1055
1056<procedure>(joy-button-event? obj) → boolean</procedure>
1057
1058Returns #t if {{obj}} is an sdl2:joy-button-event.
1059
1060
1061<procedure>(joy-button-event-which event) → fixnum</procedure>
1062<setter>(set! (joy-button-event-which event) val)</setter>
1063<setter>(joy-button-event-which-set! event val)</setter>
1064
1065Returns the joystick ID number of the joystick that caused the event.
1066
1067
1068<procedure>(joy-button-event-button event) → fixnum</procedure>
1069<setter>(set! (joy-button-event-button event) val)</setter>
1070<setter>(joy-button-event-button-set! event val)</setter>
1071
1072Returns the number of the button that was pressed or released.
1073
1074
1075<procedure>(joy-button-event-state event) → boolean</procedure>
1076<setter>(set! (joy-button-event-state event) val)</setter>
1077<setter>(joy-button-event-state-set! event val)</setter>
1078
1079Returns #t if the button was pressed, or #f if the button was released.
1080You can also find out by checking the event type: {{'joy-button-down}}
1081for pressed, or {{'joy-button-up}} for released.
1082
1083
1084
1085===== sdl2:joy-device-event
1086
1087sdl2:joy-device-event is a variant of sdl2:event that wraps a pointer to an
1088[[https://wiki.libsdl.org/SDL_JoyDeviceEvent|SDL_JoyDeviceEvent]].
1089
1090
1091<procedure>(joy-device-event? obj) → boolean</procedure>
1092
1093Returns #t if {{obj}} is an sdl2:joy-device-event.
1094
1095
1096<procedure>(joy-device-event-which event) → fixnum</procedure>
1097<setter>(set! (joy-device-event-which event) val)</setter>
1098<setter>(joy-device-event-which-set! event val)</setter>
1099
1100Returns the joystick ID number of the joystick that caused the event.
1101
1102
1103
1104===== sdl2:joy-hat-event
1105
1106sdl2:joy-hat-event is a variant of sdl2:event that wraps a pointer to an
1107[[https://wiki.libsdl.org/SDL_JoyHatEvent|SDL_JoyHatEvent]].
1108
1109
1110<procedure>(joy-hat-event? obj) → boolean</procedure>
1111
1112Returns #t if {{obj}} is an sdl2:joy-hat-event.
1113
1114
1115<procedure>(joy-hat-event-which event) → fixnum</procedure>
1116<setter>(set! (joy-hat-event-which event) val)</setter>
1117<setter>(joy-hat-event-which-set! event val)</setter>
1118
1119Returns the joystick ID number of the joystick that caused the event.
1120
1121
1122<procedure>(joy-hat-event-hat event) → fixnum</procedure>
1123<setter>(set! (joy-hat-event-hat event) val)</setter>
1124<setter>(joy-hat-event-hat-set! event val)</setter>
1125
1126Returns the number of the hat that was moved.
1127
1128
1129<procedure>(joy-hat-event-value event) → symbol</procedure>
1130<setter>(set! (joy-hat-event-value event) val)</setter>
1131<setter>(joy-hat-event-value-set! event val)</setter>
1132
1133Returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#joystick-hat-position|joystick hat position symbol]] indicating the new joystick hat position.
1134
1135
1136<procedure>(joy-hat-event-value-raw event) → fixnum</procedure>
1137<setter>(set! (joy-hat-event-value-raw event) val)</setter>
1138<setter>(joy-hat-event-value-raw-set! event val)</setter>
1139
1140Returns an integer indicating the new joystick hat position.
1141See also {{joy-hat-event-value}}.
1142
1143
1144===== sdl2:keyboard-event
1145
1146sdl2:keyboard-event is a variant of sdl2:event that wraps a pointer to an
1147[[https://wiki.libsdl.org/SDL_KeyboardEvent|SDL_KeyboardEvent]].
1148
1149
1150<procedure>(keyboard-event? obj) → boolean</procedure>
1151
1152Returns #t if {{obj}} is an sdl2:keyboard-event.
1153
1154
1155<procedure>(keyboard-event-window-id event) → fixnum</procedure>
1156<setter>(set! (keyboard-event-window-id event) val)</setter>
1157<setter>(keyboard-event-window-id-set! event val)</setter>
1158
1159Returns the ID number of the sdl2:window that had keyboard focus at the
1160time this event occurred, or 0 if no sdl2:window had keyboard focus.
1161
1162
1163<procedure>(keyboard-event-state event) → boolean</procedure>
1164<setter>(set! (keyboard-event-state event) val)</setter>
1165<setter>(keyboard-event-state-set! event val)</setter>
1166
1167Returns #t if the key was pressed, or #f if the key was released. You
1168can also find out by checking the event type: {{'key-down}} for
1169pressed, or {{'key-up}} for released.
1170
1171
1172<procedure>(keyboard-event-repeat event) → fixnum</procedure>
1173<setter>(set! (keyboard-event-repeat event) val)</setter>
1174<setter>(keyboard-event-repeat-set! event val)</setter>
1175
1176Returns non-zero if this is a "key repeat" event (caused by the user
1177pressing and holding the key for some time), or zero if this is not a
1178"key repeat" event.
1179
1180
1181<procedure>(keyboard-event-keysym event) → sdl2:keysym</procedure>
1182<setter>(set! (keyboard-event-keysym event) val)</setter>
1183<setter>(keyboard-event-keysym-set! event val)</setter>
1184
1185Returns a copy of the sdl2:keysym representing the key that was pressed
1186or released. Modifying the returned sdl2:keysym will ''not'' change the
1187event, but setting this field to a new sdl2:keysym ''will'' change the
1188event.
1189
1190Instead of using this procedure, it is more efficient and convenient
1191to directly access the fields of the event's keysym, using these
1192procedures:
1193
1194* {{keyboard-event-sym}}
1195* {{keyboard-event-scancode}}
1196* {{keyboard-event-mod}}
1197
1198
1199<procedure>(keyboard-event-sym event) → symbol</procedure>
1200<setter>(set! (keyboard-event-sym event) val)</setter>
1201<setter>(keyboard-event-sym-set! event val)</setter>
1202
1203Returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]]
1204representing the key that was pressed or released. Setting this will
1205change the event.
1206
1207
1208<procedure>(keyboard-event-sym-raw event) → fixnum</procedure>
1209<setter>(set! (keyboard-event-sym-raw event) val)</setter>
1210<setter>(keyboard-event-sym-raw-set! event val)</setter>
1211
1212Returns an integer representing a keyboard keycode of the key that was
1213pressed or released. Setting this will change the event.
1214See also {{keyboard-event-sym}}.
1215
1216
1217<procedure>(keyboard-event-scancode event) → symbol</procedure>
1218<setter>(set! (keyboard-event-scancode event) val)</setter>
1219<setter>(keyboard-event-scancode-set! event val)</setter>
1220
1221Returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]]
1222representing the key that was pressed or released. Setting this will
1223change the event.
1224
1225
1226<procedure>(keyboard-event-scancode-raw event) → fixnum</procedure>
1227<setter>(set! (keyboard-event-scancode-raw event) val)</setter>
1228<setter>(keyboard-event-scancode-raw-set! event val)</setter>
1229
1230Returns an integer representing a keyboard scancode of the key that
1231was pressed or released. Setting this will change the event.
1232See also {{keyboard-event-scancode}}.
1233
1234
1235<procedure>(keyboard-event-mod event) → list of symbols</procedure>
1236<setter>(set! (keyboard-event-mod event) val)</setter>
1237<setter>(keyboard-event-mod-set! event val)</setter>
1238
1239Returns a list of zero or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-modifiers|keyboard modifier symbols]],
1240representing the modifier keys that were being pressed at the time the
1241event occurred. Setting this will change the event.
1242
1243
1244<procedure>(keyboard-event-mod-raw event) → fixnum</procedure>
1245<setter>(set! (keyboard-event-mod-raw event) val)</setter>
1246<setter>(keyboard-event-mod-raw-set! event val)</setter>
1247
1248Returns an integer representing a bitfield of keyboard modifiers,
1249representing the modifier keys that were being pressed at the time the
1250event occurred. Setting this will change the event.
1251See also {{keyboard-event-mod}}.
1252
1253
1254===== sdl2:mouse-button-event
1255
1256sdl2:mouse-button-event is a variant of sdl2:event that wraps a pointer to an
1257[[https://wiki.libsdl.org/SDL_MouseButtonEvent|SDL_MouseButtonEvent]].
1258
1259
1260<procedure>(mouse-button-event? obj) → boolean</procedure>
1261
1262Returns #t if {{obj}} is an sdl2:mouse-button-event.
1263
1264
1265<procedure>(mouse-button-event-window-id event) → fixnum</procedure>
1266<setter>(set! (mouse-button-event-window-id event) val)</setter>
1267<setter>(mouse-button-event-window-id-set! event val)</setter>
1268
1269Returns the ID number of the sdl2:window that had mouse focus at the
1270time this event occurred, or 0 if no sdl2:window had mouse focus.
1271
1272
1273<procedure>(mouse-button-event-which event) → fixnum</procedure>
1274<setter>(set! (mouse-button-event-which event) val)</setter>
1275<setter>(mouse-button-event-which-set! event val)</setter>
1276
1277TODO: Docs.
1278
1279
1280<procedure>(mouse-button-event-button event) → symbol</procedure>
1281<setter>(set! (mouse-button-event-button event) val)</setter>
1282<setter>(mouse-button-event-button-set! event val)</setter>
1283
1284Returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#mouse-buttons|mouse button symbol]] indicating which button was pressed or released.
1285
1286
1287<procedure>(mouse-button-event-button-raw event) → fixnum</procedure>
1288<setter>(set! (mouse-button-event-button-raw event) val)</setter>
1289<setter>(mouse-button-event-button-raw-set! event val)</setter>
1290
1291Returns an integer indicating which button was pressed or released.
1292See also {{mouse-button-event-button}}.
1293
1294
1295<procedure>(mouse-button-event-state event) → boolean</procedure>
1296<setter>(set! (mouse-button-event-state event) val)</setter>
1297<setter>(mouse-button-event-state-set! event val)</setter>
1298
1299Returns #t if the button was pressed, or #f if the button was
1300released. You can also find out by checking the event type:
1301{{'mouse-button-down}} for pressed, or {{'mouse-button-up}} for
1302released.
1303
1304
1305<procedure>(mouse-button-event-x event) → fixnum</procedure>
1306<setter>(set! (mouse-button-event-x event) val)</setter>
1307<setter>(mouse-button-event-x-set! event val)</setter>
1308
1309Returns the X position (in pixels) of the mouse cursor at the time the
1310button was pressed or released.
1311
1312
1313<procedure>(mouse-button-event-y event) → fixnum</procedure>
1314<setter>(set! (mouse-button-event-y event) val)</setter>
1315<setter>(mouse-button-event-y-set! event val)</setter>
1316
1317Returns the Y position (in pixels) of the mouse cursor at the time the
1318button was pressed or released.
1319
1320
1321
1322===== sdl2:mouse-motion-event
1323
1324sdl2:mouse-motion-event is a variant of sdl2:event that wraps a pointer to an
1325[[https://wiki.libsdl.org/SDL_MouseMotionEvent|SDL_MouseMotionEvent]].
1326
1327
1328<procedure>(mouse-motion-event? obj) → boolean</procedure>
1329
1330Returns #t if {{obj}} is an sdl2:mouse-motion-event.
1331
1332
1333<procedure>(mouse-motion-event-window-id event) → fixnum</procedure>
1334<setter>(set! (mouse-motion-event-window-id event) val)</setter>
1335<setter>(mouse-motion-event-window-id-set! event val)</setter>
1336
1337Returns the ID number of the sdl2:window that had mouse focus at the
1338time this event occurred, or 0 if no sdl2:window had mouse focus.
1339
1340
1341<procedure>(mouse-motion-event-which event) → fixnum</procedure>
1342<setter>(set! (mouse-motion-event-which event) val)</setter>
1343<setter>(mouse-motion-event-which-set! event val)</setter>
1344
1345TODO: Docs.
1346
1347
1348<procedure>(mouse-motion-event-state event) → list of symbols</procedure>
1349<setter>(set! (mouse-motion-event-state event) val)</setter>
1350<setter>(mouse-motion-event-state-set! event val)</setter>
1351
1352Returns a list of zero or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#mouse-button-masks|mouse button mask symbols]],
1353representing the mouse buttons that were being pressed at the time
1354this event occurred.
1355
1356
1357<procedure>(mouse-motion-event-state-raw event) → fixnum</procedure>
1358<setter>(set! (mouse-motion-event-state-raw event) val)</setter>
1359<setter>(mouse-motion-event-state-raw-set! event val)</setter>
1360
1361Returns an integer representing the mouse buttons that were being
1362pressed at the time this event occurred.
1363See also {{mouse-motion-event-state}}
1364
1365
1366<procedure>(mouse-motion-event-x event) → fixnum</procedure>
1367<setter>(set! (mouse-motion-event-x event) val)</setter>
1368<setter>(mouse-motion-event-x-set! event val)</setter>
1369
1370Returns the X coordinate (in pixels) of the mouse cursor at the time
1371the event occurred.
1372
1373
1374<procedure>(mouse-motion-event-y event) → fixnum</procedure>
1375<setter>(set! (mouse-motion-event-y event) val)</setter>
1376<setter>(mouse-motion-event-y-set! event val)</setter>
1377
1378Returns the Y coordinate (in pixels) of the mouse cursor at the time
1379the event occurred.
1380
1381
1382<procedure>(mouse-motion-event-xrel event) → fixnum</procedure>
1383<setter>(set! (mouse-motion-event-xrel event) val)</setter>
1384<setter>(mouse-motion-event-xrel-set! event val)</setter>
1385
1386Returns how much the mouse cursor moved on the X axis (in pixels)
1387since its previous position.
1388
1389
1390<procedure>(mouse-motion-event-yrel event) → fixnum</procedure>
1391<setter>(set! (mouse-motion-event-yrel event) val)</setter>
1392<setter>(mouse-motion-event-yrel-set! event val)</setter>
1393
1394Returns how much the mouse cursor moved on the Y axis (in pixels)
1395since its previous position.
1396
1397
1398
1399===== sdl2:mouse-wheel-event
1400
1401sdl2:mouse-wheel-event is a variant of sdl2:event that wraps a pointer to an
1402[[https://wiki.libsdl.org/SDL_MouseWheelEvent|SDL_MouseWheelEvent]].
1403
1404
1405<procedure>(mouse-wheel-event? obj) → boolean</procedure>
1406
1407Returns #t if {{obj}} is an sdl2:mouse-wheel-event.
1408
1409
1410<procedure>(mouse-wheel-event-window-id event) → fixnum</procedure>
1411<setter>(set! (mouse-wheel-event-window-id event) val)</setter>
1412<setter>(mouse-wheel-event-window-id-set! event val)</setter>
1413
1414Returns the ID number of the sdl2:window that had mouse focus at the
1415time this event occurred, or 0 if no sdl2:window had mouse focus.
1416
1417
1418<procedure>(mouse-wheel-event-which event) → fixnum</procedure>
1419<setter>(set! (mouse-wheel-event-which event) val)</setter>
1420<setter>(mouse-wheel-event-which-set! event val)</setter>
1421
1422TODO: Docs.
1423
1424
1425<procedure>(mouse-wheel-event-x event) → fixnum</procedure>
1426<setter>(set! (mouse-wheel-event-x event) val)</setter>
1427<setter>(mouse-wheel-event-x-set! event val)</setter>
1428
1429TODO: Docs.
1430
1431
1432<procedure>(mouse-wheel-event-y event) → fixnum</procedure>
1433<setter>(set! (mouse-wheel-event-y event) val)</setter>
1434<setter>(mouse-wheel-event-y-set! event val)</setter>
1435
1436TODO: Docs.
1437
1438
1439
1440===== sdl2:multi-gesture-event
1441
1442sdl2:multi-gesture-event is a variant of sdl2:event that wraps a pointer to an
1443[[https://wiki.libsdl.org/SDL_MultiGestureEvent|SDL_MultiGestureEvent]].
1444
1445
1446<procedure>(multi-gesture-event? obj) → boolean</procedure>
1447
1448Returns #t if {{obj}} is an sdl2:multi-gesture-event.
1449
1450
1451<procedure>(multi-gesture-event-touch-id event) → fixnum</procedure>
1452<setter>(set! (multi-gesture-event-touch-id event) val)</setter>
1453<setter>(multi-gesture-event-touch-id-set! event val)</setter>
1454
1455TODO: Docs.
1456
1457
1458<procedure>(multi-gesture-event-dtheta event) → float</procedure>
1459<setter>(set! (multi-gesture-event-dtheta event) val)</setter>
1460<setter>(multi-gesture-event-dtheta-set! event val)</setter>
1461
1462TODO: Docs.
1463
1464
1465<procedure>(multi-gesture-event-ddist event) → float</procedure>
1466<setter>(set! (multi-gesture-event-ddist event) val)</setter>
1467<setter>(multi-gesture-event-ddist-set! event val)</setter>
1468
1469TODO: Docs.
1470
1471
1472<procedure>(multi-gesture-event-x event) → float</procedure>
1473<setter>(set! (multi-gesture-event-x event) val)</setter>
1474<setter>(multi-gesture-event-x-set! event val)</setter>
1475
1476TODO: Docs.
1477
1478
1479<procedure>(multi-gesture-event-y event) → float</procedure>
1480<setter>(set! (multi-gesture-event-y event) val)</setter>
1481<setter>(multi-gesture-event-y-set! event val)</setter>
1482
1483TODO: Docs.
1484
1485
1486<procedure>(multi-gesture-event-num-fingers event) → fixnum</procedure>
1487<setter>(set! (multi-gesture-event-num-fingers event) val)</setter>
1488<setter>(multi-gesture-event-num-fingers-set! event val)</setter>
1489
1490TODO: Docs.
1491
1492
1493
1494===== sdl2:quit-event
1495
1496sdl2:quit-event is a variant of sdl2:event that wraps a pointer to an
1497[[https://wiki.libsdl.org/SDL_QuitEvent|SDL_QuitEvent]].
1498
1499
1500<procedure>(quit-event? obj) → boolean</procedure>
1501
1502Returns #t if {{obj}} is an sdl2:quit-event.
1503
1504
1505
1506===== sdl2:sys-wm-event
1507
1508sdl2:sys-wm-event is a variant of sdl2:event that wraps a pointer to an
1509[[https://wiki.libsdl.org/SDL_SysWMEvent|SDL_SysWMEvent]].
1510
1511
1512<procedure>(sys-wm-event? obj) → boolean</procedure>
1513
1514Returns #t if {{obj}} is an sdl2:sys-wm-event.
1515
1516
1517<procedure>(sys-wm-event-msg event) → sdl2:sys-wm-msg</procedure>
1518<setter>(set! (sys-wm-event-msg event) val)</setter>
1519<setter>(sys-wm-event-msg-set! event val)</setter>
1520
1521TODO: Docs.
1522
1523
1524
1525===== sdl2:text-editing-event
1526
1527sdl2:text-editing-event is a variant of sdl2:event that wraps a pointer to an
1528[[https://wiki.libsdl.org/SDL_TextEditingEvent|SDL_TextEditingEvent]].
1529
1530
1531<procedure>(text-editing-event? obj) → boolean</procedure>
1532
1533Returns #t if {{obj}} is an sdl2:text-editing-event.
1534
1535
1536<procedure>(text-editing-event-window-id event) → fixnum</procedure>
1537<setter>(set! (text-editing-event-window-id event) val)</setter>
1538<setter>(text-editing-event-window-id-set! event val)</setter>
1539
1540TODO: Docs.
1541
1542
1543<procedure>(text-editing-event-text event) → string</procedure>
1544<setter>(set! (text-editing-event-text event) val)</setter>
1545<setter>(text-editing-event-text-set! event val)</setter>
1546
1547TODO: Docs.
1548
1549
1550<procedure>(text-editing-event-start event) → fixnum</procedure>
1551<setter>(set! (text-editing-event-start event) val)</setter>
1552<setter>(text-editing-event-start-set! event val)</setter>
1553
1554TODO: Docs.
1555
1556
1557<procedure>(text-editing-event-length event) → fixnum</procedure>
1558<setter>(set! (text-editing-event-length event) val)</setter>
1559<setter>(text-editing-event-length-set! event val)</setter>
1560
1561TODO: Docs.
1562
1563
1564
1565===== sdl2:text-input-event
1566
1567sdl2:text-input-event is a variant of sdl2:event that wraps a pointer to an
1568[[https://wiki.libsdl.org/SDL_TextInputEvent|SDL_TextInputEvent]].
1569
1570
1571<procedure>(text-input-event? obj) → boolean</procedure>
1572
1573Returns #t if {{obj}} is an sdl2:text-input-event.
1574
1575
1576<procedure>(text-input-event-window-id event) → fixnum</procedure>
1577<setter>(set! (text-input-event-window-id event) val)</setter>
1578<setter>(text-input-event-window-id-set! event val)</setter>
1579
1580TODO: Docs.
1581
1582
1583<procedure>(text-input-event-text event) → string</procedure>
1584<setter>(set! (text-input-event-text event) val)</setter>
1585<setter>(text-input-event-text-set! event val)</setter>
1586
1587TODO: Docs.
1588
1589
1590
1591===== sdl2:touch-finger-event
1592
1593sdl2:touch-finger-event is a variant of sdl2:event that wraps a pointer to an
1594[[https://wiki.libsdl.org/SDL_TouchFingerEvent|SDL_TouchFingerEvent]].
1595
1596
1597<procedure>(touch-finger-event? obj) → boolean</procedure>
1598
1599Returns #t if {{obj}} is an sdl2:touch-finger-event.
1600
1601
1602<procedure>(touch-finger-event-touch-id event) → fixnum</procedure>
1603<setter>(set! (touch-finger-event-touch-id event) val)</setter>
1604<setter>(touch-finger-event-touch-id-set! event val)</setter>
1605
1606TODO: Docs.
1607
1608
1609<procedure>(touch-finger-event-finger-id event) → fixnum</procedure>
1610<setter>(set! (touch-finger-event-finger-id event) val)</setter>
1611<setter>(touch-finger-event-finger-id-set! event val)</setter>
1612
1613TODO: Docs.
1614
1615
1616<procedure>(touch-finger-event-x event) → float</procedure>
1617<setter>(set! (touch-finger-event-x event) val)</setter>
1618<setter>(touch-finger-event-x-set! event val)</setter>
1619
1620TODO: Docs.
1621
1622
1623<procedure>(touch-finger-event-y event) → float</procedure>
1624<setter>(set! (touch-finger-event-y event) val)</setter>
1625<setter>(touch-finger-event-y-set! event val)</setter>
1626
1627TODO: Docs.
1628
1629
1630<procedure>(touch-finger-event-dx event) → float</procedure>
1631<setter>(set! (touch-finger-event-dx event) val)</setter>
1632<setter>(touch-finger-event-dx-set! event val)</setter>
1633
1634TODO: Docs.
1635
1636
1637<procedure>(touch-finger-event-dy event) → float</procedure>
1638<setter>(set! (touch-finger-event-dy event) val)</setter>
1639<setter>(touch-finger-event-dy-set! event val)</setter>
1640
1641TODO: Docs.
1642
1643
1644<procedure>(touch-finger-event-pressure event) → float</procedure>
1645<setter>(set! (touch-finger-event-pressure event) val)</setter>
1646<setter>(touch-finger-event-pressure-set! event val)</setter>
1647
1648TODO: Docs.
1649
1650
1651
1652===== sdl2:user-event
1653
1654sdl2:user-event is a variant of sdl2:event that wraps a pointer to an
1655[[https://wiki.libsdl.org/SDL_UserEvent|SDL_UserEvent]].
1656
1657Call {{register-events!}} to register your own custom event type
1658symbols.
1659
1660
1661<procedure>(user-event? obj) → boolean</procedure>
1662
1663Returns #t if {{obj}} is an sdl2:user-event.
1664
1665
1666<procedure>(user-event-window-id event) → fixnum</procedure>
1667<setter>(set! (user-event-window-id event) val)</setter>
1668<setter>(user-event-window-id-set! event val)</setter>
1669
1670TODO: Docs.
1671
1672
1673<procedure>(user-event-code event) → fixnum</procedure>
1674<setter>(set! (user-event-code event) val)</setter>
1675<setter>(user-event-code-set! event val)</setter>
1676
1677TODO: Docs.
1678
1679
1680<procedure>(user-event-data1-raw event) → pointer</procedure>
1681<setter>(set! (user-event-data1-raw event) val)</setter>
1682<setter>(user-event-data1-rawset! event val)</setter>
1683
1684TODO: Docs.
1685
1686
1687<procedure>(user-event-data2-raw event) → pointer</procedure>
1688<setter>(set! (user-event-data2-raw event) val)</setter>
1689<setter>(user-event-data2-raw-set! event val)</setter>
1690
1691TODO: Docs.
1692
1693
1694
1695===== sdl2:window-event
1696
1697sdl2:window-event is a variant of sdl2:event that wraps a pointer to an
1698[[https://wiki.libsdl.org/SDL_WindowEvent|SDL_WindowEvent]].
1699
1700
1701<procedure>(window-event? obj) → boolean</procedure>
1702
1703Returns #t if {{obj}} is an sdl2:window-event.
1704
1705
1706<procedure>(window-event-window-id event) → fixnum</procedure>
1707<setter>(set! (window-event-window-id event) val)</setter>
1708<setter>(window-event-window-id-set! event val)</setter>
1709
1710TODO: Docs.
1711
1712
1713<procedure>(window-event-event event) → symbol</procedure>
1714<setter>(set! (window-event-event event) val)</setter>
1715<setter>(window-event-event-set! event val)</setter>
1716
1717Returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#window-event-types|window event type]] indicating what happened to the window.
1718
1719
1720<procedure>(window-event-event-raw event) → fixnum</procedure>
1721<setter>(set! (window-event-event-raw event) val)</setter>
1722<setter>(window-event-event-raw-set! event val)</setter>
1723
1724Returns an integer indicating what happened to the window.
1725See also {{window-event-event}}.
1726
1727
1728<procedure>(window-event-data1 event) → fixnum</procedure>
1729<setter>(set! (window-event-data1 event) val)</setter>
1730<setter>(window-event-data1-set! event val)</setter>
1731
1732Get or set the sdl2:window-event's "data1" field, as an integer. The
1733meaning of this value depends on what kind of window event it was.
1734E.g. if the window was resized, this will hold the new window width;
1735if the window was moved, this will hold the new x position.
1736
1737
1738<procedure>(window-event-data2 event) → fixnum</procedure>
1739<setter>(set! (window-event-data2 event) val)</setter>
1740<setter>(window-event-data2-set! event val)</setter>
1741
1742Get or set the sdl2:window-event's "data2" field, as an integer. The
1743meaning of this value depends on what kind of window event it was.
1744E.g. if the window was resized, this will hold the new window height;
1745if the window was moved, this will hold the new y position.
1746
1747
1748
1749==== sdl2:finger
1750
1751sdl2:finger is a record type that wraps a pointer to an
1752[[https://wiki.libsdl.org/SDL_Finger|SDL_Finger]] struct.
1753
1754
1755<procedure>(finger? obj) → boolean</procedure>
1756
1757Returns #t if {{obj}} is an sdl2:finger.
1758
1759
1760<procedure>(finger-id finger) → fixnum</procedure>
1761
1762TODO: Docs.
1763
1764
1765<procedure>(finger-x finger) → float</procedure>
1766
1767TODO: Docs.
1768
1769
1770<procedure>(finger-y finger) → float</procedure>
1771
1772TODO: Docs.
1773
1774
1775<procedure>(finger-pressure finger) → float</procedure>
1776
1777TODO: Docs.
1778
1779
1780
1781==== sdl2:joystick
1782
1783sdl2:joystick is a record type that wraps a pointer to an
1784[[https://wiki.libsdl.org/SDL_Joystick|SDL_Joystick]] struct.
1785
1786
1787<procedure>(joystick? obj) → boolean</procedure>
1788
1789Returns #t if {{obj}} is an sdl2:joystick.
1790
1791
1792
1793==== sdl2:joystick-guid?
1794
1795sdl2:joystick-guid is a record type that wraps a pointer to an
1796[[https://wiki.libsdl.org/SDL_JoystickGetGUID|SDL_JoystickGUID]]
1797struct.
1798
1799
1800<procedure>(joystick-guid? obj) → boolean</procedure>
1801
1802Returns #t if {{obj}} is an sdl2:joystick-guid.
1803
1804
1805
1806==== sdl2:keysym
1807
1808sdl2:keysym is a record type that wraps a pointer to an
1809[[https://wiki.libsdl.org/SDL_Keysym|SDL_Keysym]] struct.
1810
1811
1812<procedure>(keysym? obj) → boolean</procedure>
1813
1814Returns #t if {{obj}} is an sdl2:keysym.
1815
1816
1817<procedure>(alloc-keysym) → sdl2:keysym</procedure>
1818
1819Allocate a new managed sdl2:keysym record.
1820
1821
1822<procedure>(alloc-keysym*) → sdl2:keysym</procedure>
1823
1824Allocate a new '''unmanaged''' sdl2:keysym record. This is like
1825{{alloc-keysym}}, except you must call {{free-keysym!}} on the record
1826when you are done with it.
1827
1828
1829<procedure>(free-keysym! keysym)</procedure>
1830
1831Free the memory of the sdl2:keysym's underlying struct. {{keysym}}'s
1832pointer will be set to null (see {{struct-null?}}). It is safe to call
1833this procedure with managed or unmanaged sdl2:keysym records. It is
1834safe (but has no effect) to free a struct record multiple times.
1835
1836
1837<procedure>(keysym-scancode keysym) → symbol</procedure>
1838<setter>(set! (keysym-scancode keysym) val)</setter>
1839<setter>(keysym-scancode-set! keysym)</setter>
1840
1841TODO: Docs.
1842Returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]].
1843
1844
1845<procedure>(keysym-scancode-raw keysym) → fixnum</procedure>
1846<setter>(set! (keysym-scancode-raw keysym) val)</setter>
1847<setter>(keysym-scancode-raw-set! keysym)</setter>
1848
1849TODO: Docs.
1850See also {{keysym-scancode}}.
1851
1852
1853<procedure>(keysym-sym keysym) → symbol</procedure>
1854<setter>(set! (keysym-sym keysym) val)</setter>
1855<setter>(keysym-sym-set! keysym)</setter>
1856
1857TODO: Docs.
1858Returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]].
1859
1860
1861<procedure>(keysym-sym-raw keysym) → fixnum</procedure>
1862<setter>(set! (keysym-sym-raw keysym) val)</setter>
1863<setter>(keysym-sym-raw-set! keysym)</setter>
1864
1865TODO: Docs.
1866See also {{keysym-sym}}.
1867
1868
1869<procedure>(keysym-mod keysym) → list of symbols</procedure>
1870<setter>(set! (keysym-mod keysym) val)</setter>
1871<setter>(keysym-mod-set! keysym)</setter>
1872
1873TODO: Docs.
1874Returns a list of zero or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-modifiers|keyboard modifier symbols]].
1875
1876
1877<procedure>(keysym-mod-raw keysym) → fixnum</procedure>
1878<setter>(set! (keysym-mod-raw keysym) val)</setter>
1879<setter>(keysym-mod-raw-set! keysym)</setter>
1880
1881TODO: Docs.
1882See also {{keysym-mod}}.
1883
1884
1885
1886==== sdl2:palette
1887
1888sdl2:palette is a record type that wraps a pointer to an
1889[[https://wiki.libsdl.org/SDL_Palette|SDL_Palette]] struct.
1890
1891
1892<procedure>(palette? obj) → boolean</procedure>
1893
1894Returns #t if {{obj}} is an sdl2:palette.
1895
1896
1897<procedure>(alloc-palette ncolors) → sdl2:palette</procedure>
1898
1899Allocate a new managed sdl2:palette record with the given number of colors.
1900See [[https://wiki.libsdl.org/SDL_AllocPalette|SDL_AllocPalette]].
1901
1902'''NOTE:''' Normally you do not need to manually allocate a palette. A
1903palette will be created for you when you create a surface with a depth
1904of 8 or lower, and the palette will be automatically freed when the
1905surface is freed (unless the palette is still being used by other
1906surfaces).
1907
1908
1909<procedure>(alloc-palette* ncolors) → sdl2:palette</procedure>
1910
1911Allocate a new '''unmanaged''' sdl2:palette record. This is like
1912{{alloc-palette}}, except you must call {{free-palette!}} on the
1913record when you are done with it.
1914
1915
1916<procedure>(free-palette! palette)</procedure>
1917
1918Free the memory of the sdl2:palette's underlying struct. {{palette}}'s
1919pointer will be set to null (see {{struct-null?}}). It is safe to call
1920this procedure with managed or unmanaged sdl2:palette records. It is
1921safe (but has no effect) to free a struct record multiple times.
1922
1923See [[https://wiki.libsdl.org/SDL_FreePalette|SDL_FreePalette]].
1924
1925
1926<procedure>(palette-ncolors palette) → fixnum</procedure>
1927<procedure>(palette-ncolours palette) → fixnum</procedure>
1928
1929Returns the number of colors in the palette.
1930
1931
1932
1933==== sdl2:pixel-format
1934
1935sdl2:pixel-format is a record type that wraps a pointer to an
1936[[https://wiki.libsdl.org/SDL_PixelFormat|SDL_PixelFormat]] struct.
1937
1938
1939<procedure>(pixel-format? obj) → boolean</procedure>
1940
1941Returns #t if {{obj}} is an sdl2:pixel-format.
1942
1943
1944<procedure>(alloc-pixel-format pixel-format-enum) → sdl2:pixel-format</procedure>
1945
1946Allocate a new managed sdl2:pixel-format record with the given format.
1947{{pixel-format-enum}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]] or equivalent integer.
1948See [[https://wiki.libsdl.org/SDL_AllocFormat|SDL_AllocFormat]].
1949
1950
1951<procedure>(alloc-pixel-format* pixel-format-enum) → sdl2:pixel-format</procedure>
1952
1953Allocate a new '''unmanaged''' sdl2:pixel-format record. This is like
1954{{alloc-pixel-format}}, except you must call {{free-pixel-format!}} on
1955the record when you are done with it.
1956
1957
1958<procedure>(free-pixel-format! pixel-format)</procedure>
1959
1960Free the memory of the sdl2:pixel-format's underlying struct.
1961{{pixel-format}}'s pointer will be set to null (see {{struct-null?}}).
1962It is safe to call this procedure with managed or unmanaged
1963sdl2:pixel-format records. It is safe (but has no effect) to free a
1964struct record multiple times.
1965
1966See [[https://wiki.libsdl.org/SDL_FreeFormat|SDL_FreeFormat]].
1967
1968<procedure>(pixel-format-format pixel-format) → symbol</procedure>
1969
1970Returns the SDL_PixelFormat's "format" field, as a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]].
1971
1972
1973<procedure>(pixel-format-format-raw pixel-format) → fixnum</procedure>
1974
1975Returns the SDL_PixelFormat's "format" field, as an integer.
1976See also {{pixel-format-format}}.
1977
1978
1979<procedure>(pixel-format-palette pixel-format) → sdl2:palette or #f</procedure>
1980<setter>(set! (pixel-format-palette pixel-format) val)</setter>
1981<setter>(pixel-format-palette-set! pixel-format palette)</setter>
1982
1983Get or set the SDL_PixelFormat's palette (as an sdl2:palette), or #f
1984if it does not have a palette. Only pixel formats with a
1985bits-per-pixel of 8 or less can have a palette.
1986
1987
1988<procedure>(pixel-format-bits-per-pixel pixel-format) → fixnum</procedure>
1989
1990TODO: Docs
1991
1992
1993<procedure>(pixel-format-bytes-per-pixel pixel-format) → fixnum</procedure>
1994
1995TODO: Docs
1996
1997
1998<procedure>(pixel-format-rmask pixel-format) → fixnum</procedure>
1999
2000TODO: Docs
2001
2002
2003<procedure>(pixel-format-gmask pixel-format) → fixnum</procedure>
2004
2005TODO: Docs
2006
2007
2008<procedure>(pixel-format-bmask pixel-format) → fixnum</procedure>
2009
2010TODO: Docs
2011
2012
2013<procedure>(pixel-format-amask pixel-format) → fixnum</procedure>
2014
2015TODO: Docs.
2016
2017
2018
2019==== sdl2:point
2020
2021sdl2:point is a record type that wraps a pointer to an
2022[[https://wiki.libsdl.org/SDL_Point|SDL_Point]] struct.
2023
2024
2025<procedure>(point? obj) → boolean</procedure>
2026
2027Returns #t if {{obj}} is an sdl2:point.
2028
2029
2030<procedure>(make-point #!optional x y) → sdl2:point</procedure>
2031
2032Allocate and initialize a new managed sdl2:point record.
2033
2034{{x}} and {{y}} are the x and y fields of the point. They must be
2035integers in the range -2147483648 to 2147483647 (inclusive). They both
2036default to 0.
2037
2038
2039<procedure>(alloc-point) → sdl2:point</procedure>
2040
2041Allocate a new managed sdl2:point record. You probably want to use
2042{{make-point}} instead.
2043
2044
2045<procedure>(alloc-point*) → sdl2:point</procedure>
2046
2047Allocate a new '''unmanaged''' sdl2:point record. This is like
2048{{alloc-point}}, except you must call {{free-point!}} on the record
2049when you are done with it.
2050
2051
2052<procedure>(free-point! point)</procedure>
2053
2054Free the memory of the sdl2:point's underlying struct. {{point}}'s
2055pointer will be set to null (see {{struct-null?}}). It is safe to call
2056this procedure with managed or unmanaged sdl2:point records. It is
2057safe (but has no effect) to free a struct record multiple times.
2058
2059
2060<procedure>(point-x point) → fixnum</procedure>
2061<setter>(set! (point-x point) x)</setter>
2062<setter>(point-x-set! point x)</setter>
2063
2064Get or set the SDL_Point's "x" field, as an integer in the range
2065-2147483648 to 2147483647 (inclusive).
2066
2067
2068<procedure>(point-y point) → fixnum</procedure>
2069<setter>(set! (point-y point) y)</setter>
2070<setter>(point-y-set! point y)</setter>
2071
2072Get or set the SDL_Point's "y" field, as an integer in the range
2073-2147483648 to 2147483647 (inclusive).
2074
2075
2076<procedure>(point-set! point #!optional x y) → point</procedure>
2077
2078Convenient way of setting multiple fields of the SDL_Point. Any
2079arguments that are {{#f}} will cause no change to that field. E.g.
2080{{(point-set! my-point 42 #f)}} will set the {{x}} field to 42, but
2081will not change the {{y}} field. Returns {{point}} after it is
2082modified.
2083
2084
2085<procedure>(point->list point) → list of fixnums</procedure>
2086
2087Returns a list {{(x y)}} containing the fields of the sdl2:point.
2088
2089
2090
2091==== sdl2:rect
2092
2093sdl2:rect is a record type that wraps a pointer to an
2094[[https://wiki.libsdl.org/SDL_Rect|SDL_Rect]] struct.
2095
2096
2097<procedure>(rect? obj) → boolean</procedure>
2098
2099Returns #t if {{obj}} is an sdl2:rect.
2100
2101
2102<procedure>(make-rect #!optional x y w h) → sdl2:rect</procedure>
2103
2104Allocate and initialize a new managed sdl2:rect record.
2105
2106{{x}}, {{y}}, {{w}}, and {{h}} are the fields of the rect. They must
2107be integers in the range -2147483648 to 2147483647 (inclusive). They
2108all default to 0.
2109
2110
2111<procedure>(alloc-rect) → sdl2:rect</procedure>
2112
2113Allocate a new managed sdl2:rect record. You probably want to use
2114{{make-rect}} instead.
2115
2116
2117<procedure>(alloc-rect*) → sdl2:rect</procedure>
2118
2119Allocate a new '''unmanaged''' sdl2:rect record. This is like
2120{{alloc-rect}}, except you must call {{free-rect!}} on the record when
2121you are done with it.
2122
2123
2124<procedure>(free-rect! rect)</procedure>
2125
2126Free the memory of the sdl2:rect's underlying struct. {{rect}}'s
2127pointer will be set to null (see {{struct-null?}}). It is safe to call
2128this procedure with managed or unmanaged sdl2:rect records. It is safe
2129(but has no effect) to free a struct record multiple times.
2130
2131
2132<procedure>(rect-x rect) → fixnum</procedure>
2133<setter>(set! (rect-x rect) x)</setter>
2134<setter>(rect-x-set! rect x)</setter>
2135
2136Get or set the sdl2:rect's "x" field, as an integer in the range
2137-2147483648 to 2147483647 (inclusive).
2138
2139
2140<procedure>(rect-y rect) → fixnum</procedure>
2141<setter>(set! (rect-y rect) y)</setter>
2142<setter>(rect-y-set! rect y)</setter>
2143
2144Get or set the sdl2:rect's "y" field, as an integer in the range
2145-2147483648 to 2147483647 (inclusive).
2146
2147
2148<procedure>(rect-w rect) → fixnum</procedure>
2149<setter>(set! (rect-w rect) w)</setter>
2150<setter>(rect-w-set! rect w)</setter>
2151
2152Get or set the "w" (width) field of the sdl2:rect, as an integer in the
2153range -2147483648 to 2147483647 (inclusive).
2154
2155
2156<procedure>(rect-h rect) → fixnum</procedure>
2157<setter>(set! (rect-h rect) h)</setter>
2158<setter>(rect-h-set! rect h)</setter>
2159
2160Get or set the "h" (height) field of the sdl2:rect, as an integer in
2161the range -2147483648 to 2147483647 (inclusive).
2162
2163
2164<procedure>(rect-set! rect #!optional x y w h) → rect</procedure>
2165
2166Convenient way of setting multiple fields of the SDL_Rect. Any
2167arguments that are {{#f}} will cause no change to that field. E.g.
2168{{(rect-set! my-rect 42 #f 1337 #f)}} will set the {{x}} field to 42
2169and the {{w}} field to 1337, but will not change the {{y}} or {{h}}
2170fields. Returns {{rect}} after it is modified.
2171
2172
2173<procedure>(rect->list rect) → list of fixnums</procedure>
2174
2175Returns a list {{(x y w h)}} containing the fields of the sdl2:rect.
2176
2177
2178
2179==== sdl2:rwops
2180
2181sdl2:rwops is a record type that wraps a pointer to an
2182[[https://wiki.libsdl.org/SDL_RWops|SDL_RWops]] struct.
2183
2184
2185<procedure>(rwops? obj) → boolean</procedure>
2186
2187Returns #t if {{obj}} is an sdl2:rwops.
2188
2189
2190<procedure>(rwops-type rwops) → symbol</procedure>
2191
2192Returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#rwops-types|RWops type symbol]] indicating what type of RWops this is.
2193
2194
2195<procedure>(rwops-type-raw rwops) → fixnum</procedure>
2196
2197Returns an integer indicating what type of RWops this is.
2198See also {{rwops-type}}.
2199
2200
2201
2202==== sdl2:surface
2203
2204sdl2:surface is a record type that wraps a pointer to an
2205[[https://wiki.libsdl.org/SDL_Surface|SDL_Surface]] struct.
2206
2207
2208<procedure>(surface? obj) → boolean</procedure>
2209
2210Returns #t if {{obj}} is an sdl2:surface.
2211
2212
2213<procedure>(free-surface! surface)</procedure>
2214
2215Free the memory of the sdl2:surface's underlying struct. {{surface}}'s
2216pointer will be set to null (see {{struct-null?}}). It is safe to call
2217this procedure with managed or unmanaged sdl2:surface records. It is
2218safe (but has no effect) to free a struct record multiple times.
2219
2220See [[https://wiki.libsdl.org/SDL_FreeSurface|SDL_FreeSurface]].
2221
2222'''NOTE:''' if {{surface}} was created using
2223{{create-rgb-surface-from}}, then the pixel data is not freed.
2224
2225
2226<procedure>(surface-format surface) → sdl2:pixel-format</procedure>
2227
2228Returns a sdl2:pixel-format describing the pixel format of the
2229sdl2:surface's pixels.
2230
2231
2232<procedure>(surface-w surface) → fixnum</procedure>
2233
2234Returns the width of the sdl2:surface, in pixels.
2235
2236
2237<procedure>(surface-h surface) → fixnum</procedure>
2238
2239Returns the height of the sdl2:surface, in pixels.
2240
2241
2242<procedure>(surface-pitch surface) → fixnum</procedure>
2243
2244Returns the pitch of the sdl2:surface, in bytes. (The pitch describes
2245how many bytes are used to represent one row of pixel data.)
2246
2247
2248<procedure>(surface-pixels-raw surface) → pointer</procedure>
2249
2250Returns a raw pointer to the sdl2:surface's pixels. Don't use this
2251unless you really know what you are doing!
2252
2253If you just want to get or set a pixel, use {{surface-ref}} and
2254{{surface-set!}} instead. They are much safer, more convenient, and
2255more efficient than using this pointer.
2256
2257
2258<procedure>(surface-refcount surface) → fixnum</procedure>
2259<setter>(set! (surface-refcount surface) val)</setter>
2260<setter>(surface-refcount-set! surface)</setter>
2261
2262TODO: Docs.
2263
2264
2265
2266==== sdl2:sys-wm-info
2267
2268sdl2:sys-wm-info is a record type that wraps a pointer to an
2269[[https://wiki.libsdl.org/SDL_SysWMinfo|SDL_SysWMinfo]] struct.
2270
2271
2272<procedure>(sys-wm-info? obj) → boolean</procedure>
2273
2274Returns #t if {{obj}} is an sdl2:sys-wm-info.
2275
2276
2277
2278==== sdl2:sys-wm-msg
2279
2280sdl2:sys-wm-msg is a record type that wraps a pointer to an
2281[[https://wiki.libsdl.org/SDL_SysWMmsg|SDL_SysWMmsg]] struct.
2282
2283
2284<procedure>(sys-wm-msg? obj) → boolean</procedure>
2285
2286Returns #t if {{obj}} is an sdl2:sys-wm-msg.
2287
2288
2289
2290==== sdl2:texture
2291
2292sdl2:texture is a record type that wraps a pointer to an
2293[[https://wiki.libsdl.org/SDL_Texture|SDL_Texture]] struct.
2294
2295
2296<procedure>(texture? obj) → boolean</procedure>
2297
2298Returns #t if {{obj}} is an sdl2:texture.
2299
2300
2301
2302==== sdl2:version
2303
2304sdl2:version is a record type that wraps a pointer to an
2305[[https://wiki.libsdl.org/SDL_version|SDL_version]] struct.
2306
2307
2308<procedure>(version? obj) → boolean</procedure>
2309
2310Returns #t if {{obj}} is an sdl2:version.
2311
2312
2313<procedure>(make-version #!optional major minor patch) → sdl2:version</procedure>
2314
2315Allocate and initialize a new managed sdl2:version record.
2316
2317{{major}}, {{minor}}, and {{patch}} are the fields of the version.
2318They must be integers in the range 0 to 255 (inclusive). They all
2319default to 0.
2320
2321
2322<procedure>(alloc-version) → sdl2:version</procedure>
2323
2324Allocate a new managed sdl2:version record. You probably want to use
2325{{make-version}} instead.
2326
2327
2328<procedure>(alloc-version*) → sdl2:version</procedure>
2329
2330Allocate a new '''unmanaged''' sdl2:version record. This is like
2331{{alloc-version}}, except you must call {{free-version!}} on the
2332record when you are done with it.
2333
2334
2335<procedure>(free-version! version)</procedure>
2336
2337Free the memory of the sdl2:version's underlying struct. {{version}}'s
2338pointer will be set to null (see {{struct-null?}}). It is safe to call
2339this procedure with managed or unmanaged sdl2:version records. It is
2340safe (but has no effect) to free a struct record multiple times.
2341
2342
2343<procedure>(version-major version) → fixnum</procedure>
2344<setter>(set! (version-major version) major)</setter>
2345<setter>(version-major-set! version major)</setter>
2346
2347Get or set the SDL_version's "major" field, as an integer in the
2348range 0 to 255 (inclusive).
2349
2350
2351<procedure>(version-minor version) → fixnum</procedure>
2352<setter>(set! (version-minor version) minor)</setter>
2353<setter>(version-minor-set! version minor)</setter>
2354
2355Get or set the SDL_version's "minor" field, as an integer in the
2356range 0 to 255 (inclusive).
2357
2358
2359<procedure>(version-patch version) → fixnum</procedure>
2360<setter>(set! (version-patch version) patch)</setter>
2361<setter>(version-patch-set! version patch)</setter>
2362
2363Get or set the SDL_version's "patch" field, as an integer in the
2364range 0 to 255 (inclusive).
2365
2366
2367<procedure>(version-set! version #!optional major minor patch) → version</procedure>
2368
2369Convenient way of setting multiple fields of the SDL_version. Any
2370arguments that are {{#f}} will cause no change to that field. E.g.
2371{{(version-set! my-version 42 #f 255)}} will set the {{major}} field
2372to 42 and the {{patch}} field to 255, but will not change the
2373{{minor}} field. Returns {{version}} after it is modified.
2374
2375
2376<procedure>(version->list version) → list of fixnums</procedure>
2377
2378Returns a list {{(major minor patch)}} containing the value of each
2379field of the SDL_version.
2380
2381
2382
2383==== sdl2:window
2384
2385sdl2:window is a record type that wraps a pointer to an
2386[[https://wiki.libsdl.org/SDL_CreateWindow|SDL_Window]] struct.
2387
2388
2389<procedure>(window? obj) → boolean</procedure>
2390
2391Returns #t if {{obj}} is an sdl2:window.
2392
2393
2394
2395=== Procedures
2396
2397==== General / Miscellaneous
2398
2399<procedure>(init! #!optional flags-list) → fixnum</procedure>
2400
2401See [[https://wiki.libsdl.org/SDL_Init|SDL_Init]].
2402Returns zero if successful.
2403
2404{{flags-list}} defaults to {{'(everything)}}. It must be a list of one or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#init-flags|init flag symbols]]:
2405
2406* {{'timer}}
2407* {{'audio}}
2408* {{'video}}
2409* {{'joystick}}
2410* {{'haptic}}
2411* {{'game-controller}}
2412* {{'events}}
2413* {{'everything}}
2414
2415
2416<procedure>(init-subsystem! flags-list) → fixnum</procedure>
2417
2418See [[https://wiki.libsdl.org/SDL_InitSubSystem|SDL_InitSubSystem]].
2419Returns zero if successful.
2420
2421{{flags-list}} must be a list of one or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#init-flags|init flag]] symbols.
2422
2423
2424<procedure>(quit!)</procedure>
2425
2426See [[https://wiki.libsdl.org/SDL_Quit|SDL_Quit]].
2427
2428
2429<procedure>(quit-subsystem! flags-list)</procedure>
2430
2431See [[https://wiki.libsdl.org/SDL_QuitSubSystem|SDL_QuitSubSystem]].
2432
2433{{flags-list}} must be a list of one or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#init-flags|init flag]] symbols.
2434
2435
2436<procedure>(was-init #!optional flags-list) → list of symbols</procedure>
2437
2438See [[https://wiki.libsdl.org/SDL_WasInit|SDL_WasInit]].
2439
2440{{flags-list}} defaults to {{'(everything)}}. It must be a list of one or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#init-flags|init flag]] symbols.
2441
2442
2443<procedure>(set-main-ready!)</procedure>
2444
2445See [[https://wiki.libsdl.org/SDL_SetMainReady|SDL_SetMainReady]].
2446
2447
2448<procedure>(clear-error!)</procedure>
2449
2450See [[https://wiki.libsdl.org/SDL_ClearError|SDL_ClearError]].
2451
2452
2453<procedure>(get-error) → string</procedure>
2454
2455See [[https://wiki.libsdl.org/SDL_GetError|SDL_GetError]].
2456
2457
2458<procedure>(set-error! message)</procedure>
2459
2460See [[https://wiki.libsdl.org/SDL_SetError|SDL_SetError]].
2461
2462Unlike SDL_SetError, this procedure only accepts one argument, a
2463string. You can use {{sprintf}} to do string substitution if desired.
2464
2465
2466<procedure>(get-platform) → string</procedure>
2467
2468See [[https://wiki.libsdl.org/SDL_GetPlatform|SDL_GetPlatform]].
2469
2470
2471<procedure>(disable-screen-saver!)</procedure>
2472
2473See [[https://wiki.libsdl.org/SDL_DisableScreenSaver|SDL_DisableScreenSaver]].
2474
2475
2476<procedure>(enable-screen-saver!)</procedure>
2477
2478See [[https://wiki.libsdl.org/SDL_EnableScreenSaver|SDL_EnableScreenSaver]].
2479
2480
2481<procedure>(screen-saver-enabled?) → boolean</procedure>
2482
2483See [[https://wiki.libsdl.org/SDL_IsScreenSaverEnabled|SDL_IsScreenSaverEnabled]].
2484
2485
2486<procedure>(has-clipboard-text?) → boolean</procedure>
2487
2488See [[https://wiki.libsdl.org/SDL_HasClipboardText|SDL_HasClipboardText]].
2489
2490
2491<procedure>(get-clipboard-text) → string</procedure>
2492
2493See [[https://wiki.libsdl.org/SDL_GetClipboardText|SDL_GetClipboardText]].
2494
2495
2496<procedure>(set-clipboard-text! text) → fixnum</procedure>
2497
2498See [[https://wiki.libsdl.org/SDL_SetClipboardText|SDL_SetClipboardText]].
2499Returns zero if successful.
2500
2501
2502<procedure>(get-version) → sdl2:version</procedure>
2503
2504See [[https://wiki.libsdl.org/SDL_GetVersion|SDL_GetVersion]].
2505
2506Returns an sdl2:version record containing the version number of SDL
2507that the sdl2 egg is currently using. (This may be different than the
2508version it was compiled with.)
2509
2510
2511<procedure>(get-compiled-version) → sdl2:version</procedure>
2512
2513See [[https://wiki.libsdl.org/SDL_VERSION|SDL_VERSION]].
2514
2515Returns an sdl2:version record containing the version number of SDL
2516that the sdl2 egg was compiled with. (This may be different than the
2517version it is currently using.)
2518
2519
2520<procedure>(version-at-least? major minor patch) → boolean</procedure>
2521
2522See [[https://wiki.libsdl.org/SDL_VERSION_ATLEAST|SDL_VERSION_ATLEAST]].
2523
2524Returns #t if the sdl2 egg was compiled with a version of SDL at least
2525as high as specified. E.g. {{(version-at-least? 2 0 1)}} returns
2526#t if the sdl2 egg was compiled with SDL 2.0.1 or higher. Some SDL
2527features are only available after a certain version, so you can use
2528this procedure to check whether the feature is available.
2529
2530
2531
2532==== Pixel Format / Palette
2533
2534<procedure>(map-rgb pixel-format r g b) → fixnum</procedure>
2535
2536See [[https://wiki.libsdl.org/SDL_MapRGB|SDL_MapRGB]].
2537
2538
2539<procedure>(map-rgba pixel-format r g b a) → fixnum</procedure>
2540
2541See [[https://wiki.libsdl.org/SDL_MapRGBA|SDL_MapRGBA]].
2542
2543
2544<procedure>(get-rgb pixel pixel-format) → [r g b]</procedure>
2545
2546See [[https://wiki.libsdl.org/SDL_GetRGB|SDL_GetRGB]].
2547
2548This procedure returns multiple values.
2549
2550
2551<procedure>(get-rgba pixel pixel-format) → [r g b a]</procedure>
2552
2553See [[https://wiki.libsdl.org/SDL_GetRGBA|SDL_GetRGBA]].
2554
2555This procedure returns multiple values.
2556
2557
2558<procedure>(palette-ref palette i) → sdl2:color</procedure>
2559
2560Return the sdl2:color at the given index of the palette.
2561
2562
2563<setter>(set! (palette-ref palette i) color)</setter>
2564<setter>(palette-set! palette i color)</setter>
2565
2566Set the given index of the palette to the given sdl2:color.
2567
2568
2569<procedure>(palette-colors palette) → vector of sdl2:colors </procedure>
2570<procedure>(palette-colours palette) → vector of sdl2:colors </procedure>
2571
2572Return all colors in the palette, as a Scheme vector of sdl2:colors.
2573
2574
2575<setter>(palette-colors-set! colors-vec #!optional start) -> fixnum</setter>
2576<setter>(palette-colours-set! colors-vec #!optional start) -> fixnum</setter>
2577
2578See [[https://wiki.libsdl.org/SDL_SetPaletteColors|SDL_SetPaletteColors]].
2579
2580Set multiple colors in the palette. {{colors-vec}} must be a Scheme
2581vector of sdl2:colors. {{start}} defaults to 0.
2582
2583Returns zero if successful.
2584
2585
2586
2587==== Events
2588
2589<procedure>(event-state type) → boolean</procedure>
2590
2591See [[https://wiki.libsdl.org/SDL_EventState|SDL_EventState]].
2592
2593Like calling SDL_EventState with SDL_QUERY. {{type}} must be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbol]] or corresponding integer.
2594
2595Returns #t if the given event type is currently enabled, or #f if it
2596is currently disabled.
2597
2598
2599<setter>(set! (event-state type) state) → boolean</setter>
2600<setter>(event-state-set! type state) → boolean</setter>
2601
2602See [[https://wiki.libsdl.org/SDL_EventState|SDL_EventState]].
2603
2604Like calling SDL_EventState with SDL_ENABLE or SDL_IGNORE.
2605
2606If {{state}} is #t, the given event type will be enabled. If {{state}} is #f, it will be disabled, i.e. all future events of that type will be ignored.
2607
2608Returns the previous state for the given event type.
2609
2610{{type}} must be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbol]] or corresponding integer.
2611
2612
2613<procedure>(flush-event! type)</procedure>
2614
2615See [[https://wiki.libsdl.org/SDL_FlushEvent|SDL_FlushEvent]].
2616
2617Note: Contrary to what its name suggests, this procedure will flush
2618ALL events matching the given type, not just a single event.
2619
2620{{type}} must be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbol]] or corresponding integer.
2621
2622
2623<procedure>(flush-events! #!optional min-type max-type)</procedure>
2624
2625See [[https://wiki.libsdl.org/SDL_FlushEvents|SDL_FlushEvents]].
2626
2627{{min-type}} and {{max-type}} must be [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbols]] or corresponding integers. If omitted, {{min-type}} defaults to {{'first}} and {{max-type}} defaults to {{'last}}.
2628
2629
2630<procedure>(has-event? type) → boolean</procedure>
2631
2632See [[https://wiki.libsdl.org/SDL_HasEvent|SDL_HasEvent]].
2633
2634{{type}} must be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbol]] or corresponding integer.
2635
2636
2637<procedure>(has-events? #!optional min-type max-type) → boolean</procedure>
2638
2639See [[https://wiki.libsdl.org/SDL_HasEvents|SDL_HasEvents]].
2640
2641{{min-type}} and {{max-type}} must be [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbols]] or corresponding integers. If omitted, {{min-type}} defaults to {{'first}} and {{max-type}} defaults to {{'last}}.
2642
2643
2644<procedure>(quit-requested?) → boolean</procedure>
2645
2646See [[https://wiki.libsdl.org/SDL_QuitRequested|SDL_QuitRequested]].
2647
2648
2649<procedure>(peek-events num #!optional min-type max-type) → list of sdl2:events</procedure>
2650
2651See [[https://wiki.libsdl.org/SDL_PeepEvents|SDL_PeepEvents]].
2652
2653This procedure is similar to {{get-events!}}, except that this
2654procedure does not remove the events from the SDL event queue.
2655
2656{{min-type}} and {{max-type}} must be [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbols]] or corresponding integers. If omitted, {{min-type}} defaults to {{'first}} and {{max-type}} defaults to {{'last}}.
2657
2658Returns a list of managed sdl2:events.
2659
2660
2661<procedure>(get-events! num #!optional min-type max-type) → list of sdl2:events</procedure>
2662
2663See [[https://wiki.libsdl.org/SDL_PeepEvents|SDL_PeepEvents]].
2664
2665This procedure is similar to {{peek-events}}, except that this
2666procedure removes the events from the SDL event queue.
2667
2668{{min-type}} and {{max-type}} must be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbol]] or corresponding integer. If omitted, {{min-type}} defaults to {{'first}} and {{max-type}} defaults to {{'last}}.
2669
2670Returns a list of managed sdl2:events.
2671
2672
2673<procedure>(poll-event! #!optional result-event) → sdl2:event</procedure>
2674
2675See [[https://wiki.libsdl.org/SDL_PollEvent|SDL_PollEvent]].
2676
2677If {{result-event}} is omitted or #f, a new managed sdl2:event will be
2678allocated and returned. If {{result-event}} is an existing sdl2:event
2679record, it will be modified and returned. This allows you to allocate
2680a single event and reuse it many times in your event loop, so that
2681your program does not create as much garbage for the garbage
2682collector.
2683
2684
2685<procedure>(pump-events!)</procedure>
2686
2687See [[https://wiki.libsdl.org/SDL_PumpEvents|SDL_PumpEvents]].
2688
2689
2690<procedure>(push-event! event) → fixnum</procedure>
2691
2692See [[https://wiki.libsdl.org/SDL_PushEvent|SDL_PushEvent]].
2693
2694Returns 1 if successful.
2695
2696
2697<procedure>(wait-event! #!optional result-event) → sdl2:event </procedure>
2698
2699See [[https://wiki.libsdl.org/SDL_WaitEvent|SDL_WaitEvent]].
2700
2701If {{result-event}} is omitted or #f, a new managed sdl2:event will be
2702allocated and returned. If {{result-event}} is an existing sdl2:event
2703record, it will be modified and returned. This allows you to allocate
2704a single event and reuse it many times in your event loop, so that
2705your program does not create as much garbage for the garbage
2706collector.
2707
2708
2709<procedure>(wait-event-timeout! timeout #!optional result-event) → sdl2:event</procedure>
2710
2711See [[https://wiki.libsdl.org/SDL_WaitEventTimeout|SDL_WaitEventTimeout]].
2712
2713If {{result-event}} is omitted of #f, a new managed sdl2:event will be
2714allocated and returned. If {{result-event}} is an existing sdl2:event
2715record, it will be modified and returned. This allows you to allocate
2716a single event and reuse it many times in your event loop, so that
2717your program does not create as much garbage for the garbage
2718collector.
2719
2720Please note that the argument order is reversed compared to SDL_WaitEventTimeout. This is to allow the event argument to be optional.
2721
2722
2723<procedure>(register-events! event-symbols) → list of pairs</procedure>
2724
2725Register zero or more symbols as new user event types. After
2726registration, the given symbols may be used as event types, e.g. with
2727{{event-type-set!}}. The symbols will be associated with the
2728sdl2:user-event variant of sdl2:event.
2729
2730{{event-symbols}} must be a list of symbols that are not already being
2731used as event types. If any symbol is already being used, or if any
2732member of the list is not a symbol, an error will be signalled and
2733none of the new event types will be registered.
2734
2735There are 32767 user event type numbers available to register. Each
2736symbol in {{event-symbols}} will be automatically assigned a distinct
2737number. If there are not enough remaining numbers to register all the
2738symbols in {{event-symbols}}, this procedure will signal an error, and
2739none of the new event types will be registered.
2740
2741This procedure returns an association list (list of pairs) of each of
2742the new event type symbols (as the pair car) with its assigned number
2743(as the pair cdr).
2744
2745This procedure is based on [[https://wiki.libsdl.org/SDL_RegisterEvents|SDL_RegisterEvents]].
2746
2747
2748
2749<procedure>(get-num-touch-devices) → fixnum</procedure>
2750
2751See [[https://wiki.libsdl.org/SDL_GetNumTouchDevices|SDL_GetNumTouchDevices]].
2752
2753
2754<procedure>(get-num-touch-fingers touch-id) → fixnum</procedure>
2755
2756See [[https://wiki.libsdl.org/SDL_GetNumTouchFingers|SDL_GetNumTouchFingers]].
2757
2758
2759<procedure>(get-touch-device device-id) → fixnum</procedure>
2760
2761See [[https://wiki.libsdl.org/SDL_GetTouchDevice|SDL_GetTouchDevice]].
2762
2763
2764<procedure>(get-touch-finger touch-id index) → sdl2:finger</procedure>
2765
2766See [[https://wiki.libsdl.org/SDL_GetTouchFinger|SDL_GetTouchFinger]].
2767
2768
2769
2770==== OpenGL integration
2771
2772<procedure>(gl-create-context! window) → sdl2:gl-context</procedure>
2773
2774See [[https://wiki.libsdl.org/SDL_GL_CreateContext|SDL_GL_CreateContext]].
2775
2776
2777<procedure>(gl-delete-context! gl-context)</procedure>
2778
2779See [[https://wiki.libsdl.org/SDL_GL_DeleteContext|SDL_GL_DeleteContext]].
2780
2781
2782<procedure>(gl-make-current! window gl-context) → fixnum</procedure>
2783
2784See [[https://wiki.libsdl.org/SDL_GL_MakeCurrent|SDL_GL_MakeCurrent]].
2785
2786
2787<procedure>(gl-get-current-window) → sdl2:window</procedure>
2788
2789See [[https://wiki.libsdl.org/SDL_GL_GetCurrentWindow|SDL_GL_GetCurrentWindow]].
2790
2791
2792<procedure>(gl-get-current-context) → sdl2:gl-context</procedure>
2793
2794See [[https://wiki.libsdl.org/SDL_GL_GetCurrentContext|SDL_GL_GetCurrentContext]].
2795
2796
2797<procedure>(gl-get-attribute attr) → value</procedure>
2798
2799See [[https://wiki.libsdl.org/SDL_GL_GetAttribute|SDL_GL_GetAttribute]].
2800
2801{{attr}} must be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#opengl-attributes|OpenGL attribute symbol]] or corresponding integer.
2802
2803The return type varies depending on {{attr}}:
2804
2805* If {{attr}} is {{'context-profile-mask}}, an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#opengl-profiles|OpenGL profile symbol]] will be returned.
2806
2807* If {{attr}} is {{'context-flags}}, a list of zero or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#opengl-context-flags|OpenGL context flag symbols]] will be returned.
2808
2809* Otherwise, an integer will be returned.
2810
2811
2812<procedure>(gl-set-attribute! attr value) → fixnum</procedure>
2813
2814See [[https://wiki.libsdl.org/SDL_GL_SetAttribute|SDL_GL_SetAttribute]].
2815Returns zero if successful.
2816
2817{{attr}} must be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#opengl-attributes|OpenGL attribute symbol]] or corresponding integer.
2818
2819{{value}} must be one of these types, depending on what {{attr}} is:
2820
2821* If {{attr}} is {{'context-profile-mask}}, {{value}} must be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#opengl-profiles|OpenGL profile symbol]] or corresponding integer.
2822
2823* If {{attr}} is {{'context-flags}}, {{value}} must be a list of zero or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#opengl-context-flags|OpenGL context flag symbols]] or an integer bitfield.
2824
2825* Otherwise, {{value}} must be an integer.
2826
2827
2828<procedure>(gl-reset-attributes!)</procedure>
2829
2830See [[https://wiki.libsdl.org/SDL_GL_ResetAttributes|SDL_GL_ResetAttributes]].
2831
2832Requires SDL 2.0.2 or higher. Signals an error if the compiled version
2833of SDL is not high enough. Use {{(version-at-least? 2 0 2)}} to
2834check before calling this procedure.
2835
2836
2837<procedure>(gl-get-drawable-size window) → [width height]</procedure>
2838
2839See [[https://wiki.libsdl.org/SDL_GL_GetDrawableSize|SDL_GL_GetDrawableSize]].
2840
2841This procedure returns multiple values.
2842
2843Requires SDL 2.0.1 or higher. Signals an error if the compiled version
2844of SDL is not high enough. Use {{(version-at-least? 2 0 1)}} to
2845check before calling this procedure.
2846
2847
2848<procedure>(gl-swap-window!)</procedure>
2849
2850See [[https://wiki.libsdl.org/SDL_GL_SwapWindow|SDL_GL_SwapWindow]].
2851
2852
2853<procedure>(gl-get-swap-interval) → fixnum</procedure>
2854
2855See [[https://wiki.libsdl.org/SDL_GL_GetSwapInterval|SDL_GL_GetSwapInterval]].
2856
2857
2858<procedure>(gl-set-swap-interval! interval) → fixnum</procedure>
2859
2860See [[https://wiki.libsdl.org/SDL_GL_SetSwapInterval|SDL_GL_SetSwapInterval]].
2861
2862Returns zero if successful
2863
2864
2865<procedure>(gl-extension-supported? name-string) → boolean</procedure>
2866
2867See [[https://wiki.libsdl.org/SDL_GL_ExtensionSupported|SDL_GL_ExtensionSupported]].
2868
2869
2870
2871==== Joystick
2872
2873<procedure>(num-joysticks) → fixnum</procedure>
2874
2875See [[https://wiki.libsdl.org/SDL_NumJoysticks|SDL_NumJoysticks]].
2876
2877
2878<procedure>(joystick-open! index) → sdl2:joystick</procedure>
2879
2880See [[https://wiki.libsdl.org/SDL_JoystickOpen|SDL_JoystickOpen]].
2881
2882
2883<procedure>(joystick-close! joystick)</procedure>
2884
2885See [[https://wiki.libsdl.org/SDL_JoystickClose|SDL_JoystickClose]].
2886
2887
2888<procedure>(joystick-update!)</procedure>
2889
2890See [[https://wiki.libsdl.org/SDL_JoystickUpdate|SDL_JoystickUpdate]].
2891
2892
2893<procedure>(joystick-event-state) → boolean</procedure>
2894
2895See [[https://wiki.libsdl.org/SDL_JoystickEventState|SDL_JoystickEventState]].
2896
2897Like SDL_JoystickEventState with SDL_QUERY.
2898
2899
2900<setter>(set! (joystick-event-state) state) → boolean</setter>
2901<setter>(joystick-event-state-set! state) → boolean</setter>
2902
2903See [[https://wiki.libsdl.org/SDL_JoystickEventState|SDL_JoystickEventState]].
2904
2905Like SDL_JoystickEventState with SDL_ENABLE or SDL_IGNORE
2906
2907
2908<procedure>(joystick-attached? joystick) → boolean</procedure>
2909
2910See [[https://wiki.libsdl.org/SDL_JoystickGetAttached|SDL_JoystickGetAttached]].
2911
2912
2913<procedure>(joystick-num-axes joystick) → fixnum</procedure>
2914
2915See [[https://wiki.libsdl.org/SDL_JoystickNumAxes|SDL_JoystickNumAxes]].
2916
2917
2918<procedure>(joystick-num-balls joystick) → fixnum</procedure>
2919
2920See [[https://wiki.libsdl.org/SDL_JoystickNumBalls|SDL_JoystickNumBalls]].
2921
2922
2923<procedure>(joystick-num-buttons joystick) → fixnum</procedure>
2924
2925See [[https://wiki.libsdl.org/SDL_JoystickNumButtons|SDL_JoystickNumButtons]].
2926
2927
2928<procedure>(joystick-num-hats joystick) → fixnum</procedure>
2929
2930See [[https://wiki.libsdl.org/SDL_JoystickNumHats|SDL_JoystickNumHats]].
2931
2932
2933<procedure>(joystick-get-axis joystick axis-num) → fixnum</procedure>
2934
2935See [[https://wiki.libsdl.org/SDL_JoystickGetAxis|SDL_JoystickGetAxis]].
2936
2937
2938<procedure>(joystick-get-ball joystick ball-num) → [dx dy]</procedure>
2939
2940See [[https://wiki.libsdl.org/SDL_JoystickGetBall|SDL_JoystickGetBall]].
2941
2942This procedure returns multiple values. Returns #f for both values if
2943the ball values cannot be retrieved (e.g. because {{ball-num}} is
2944invalid for the joystick).
2945
2946
2947<procedure>(joystick-get-button joystick button-num) → boolean</procedure>
2948
2949See [[https://wiki.libsdl.org/SDL_JoystickGetButton|SDL_JoystickGetButton]].
2950
2951
2952<procedure>(joystick-get-hat joystick hat-num) → symbol</procedure>
2953
2954See [[https://wiki.libsdl.org/SDL_JoystickGetHat|SDL_JoystickGetHat]].
2955
2956
2957<procedure>(joystick-get-hat-raw joystick hat-num) → fixnum</procedure>
2958
2959See [[https://wiki.libsdl.org/SDL_JoystickGetHat|SDL_JoystickGetHat]].
2960See also {{joystick-get-hat}}.
2961
2962<procedure>(joystick-instance-id joystick) → fixnum</procedure>
2963
2964See [[https://wiki.libsdl.org/SDL_JoystickInstanceID|SDL_JoystickInstanceID]].
2965
2966
2967<procedure>(joystick-name joystick) → string</procedure>
2968
2969See [[https://wiki.libsdl.org/SDL_JoystickName|SDL_JoystickName]].
2970
2971
2972<procedure>(joystick-name-for-index device-index) → string</procedure>
2973
2974See [[https://wiki.libsdl.org/SDL_JoystickNameForIndex|SDL_JoystickNameForIndex]].
2975
2976
2977<procedure>(joystick-get-device-guid device-index) → sdl2:joystick-guid</procedure>
2978
2979See [[https://wiki.libsdl.org/SDL_JoystickGetDeviceGUID|SDL_JoystickGetDeviceGUID]].
2980
2981
2982<procedure>(joystick-get-guid joystick) → sdl2:joystick-guid</procedure>
2983
2984See [[https://wiki.libsdl.org/SDL_JoystickGetGUID|SDL_JoystickGetGUID]].
2985
2986
2987<procedure>(joystick-get-guid-from-string str) → sdl2:joystick-guid</procedure>
2988
2989See [[https://wiki.libsdl.org/SDL_JoystickGetGUIDFromString|SDL_JoystickGetGUIDFromString]].
2990
2991
2992<procedure>(joystick-get-guid-string guid) → string</procedure>
2993
2994See [[https://wiki.libsdl.org/SDL_JoystickGetGUIDString|SDL_JoystickGetGUIDString]].
2995
2996
2997
2998==== Keyboard
2999
3000<procedure>(get-key-from-name name-str) → symbol</procedure>
3001
3002See [[https://wiki.libsdl.org/SDL_GetKeyFromName|SDL_GetKeyFromName]].
3003
3004Returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]].
3005
3006
3007<procedure>(get-key-from-name-raw name-str) → fixnum</procedure>
3008
3009See [[https://wiki.libsdl.org/SDL_GetKeyFromName|SDL_GetKeyFromName]].
3010
3011Returns an integer representing a keyboard keycode.
3012See also {{get-key-from-name}}.
3013
3014
3015<procedure>(get-key-from-scancode scancode) → symbol</procedure>
3016
3017See [[https://wiki.libsdl.org/SDL_GetKeyFromScancode|SDL_GetKeyFromScancode]].
3018
3019{{scancode}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]] or an integer representing a keyboard scancode.
3020
3021Returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]].
3022
3023
3024<procedure>(get-key-from-scancode-raw scancode) → fixnum</procedure>
3025
3026See [[https://wiki.libsdl.org/SDL_GetKeyFromScancode|SDL_GetKeyFromScancode]].
3027
3028{{scancode}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]] or an integer representing a keyboard scancode.
3029
3030Returns an integer representing a keyboard keycode.
3031See also {{get-key-from-scancode}}.
3032
3033
3034<procedure>(get-key-name key) → string</procedure>
3035
3036See [[https://wiki.libsdl.org/SDL_GetKeyName|SDL_GetKeyName]].
3037
3038{{key}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]] or an integer representing a keyboard keycode.
3039
3040
3041<procedure>(get-scancode-from-name name-str) → symbol</procedure>
3042
3043See [[https://wiki.libsdl.org/SDL_GetScancodeFromName|SDL_GetScancodeFromName]].
3044
3045Returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]].
3046
3047
3048<procedure>(get-scancode-from-name-raw name-str) → fixnum</procedure>
3049
3050See [[https://wiki.libsdl.org/SDL_GetScancodeFromName|SDL_GetScancodeFromName]].
3051
3052Returns an integer representing a keyboard scancode.
3053See also {{get-scancode-from-name}}.
3054
3055
3056<procedure>(get-scancode-from-key key) → symbol</procedure>
3057
3058See [[https://wiki.libsdl.org/SDL_GetScancodeFromKey|SDL_GetScancodeFromKey]].
3059
3060{{key}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]] or an integer representing a keyboard keycode.
3061
3062Returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]].
3063
3064
3065<procedure>(get-scancode-from-key-raw key) → fixnum</procedure>
3066
3067See [[https://wiki.libsdl.org/SDL_GetScancodeFromKey|SDL_GetScancodeFromKey]].
3068
3069{{key}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]] or an integer representing a keyboard keycode.
3070
3071Returns an integer representing a keyboard scancode.
3072See also {{get-scancode-from-key}}.
3073
3074
3075<procedure>(get-scancode-name scancode) → string</procedure>
3076
3077See [[https://wiki.libsdl.org/SDL_GetScancodeName|SDL_GetScancodeName]].
3078
3079{{scancode}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]] or an integer representing a keyboard scancode.
3080
3081
3082<procedure>(get-keyboard-focus) → window</procedure>
3083
3084See [[https://wiki.libsdl.org/SDL_GetKeyboardFocus|SDL_GetKeyboardFocus]].
3085
3086
3087<procedure>(keyboard-scancode-pressed? scancode) → boolean</procedure>
3088
3089Returns #t if the specified key is being pressed on the keyboard.
3090
3091{{scancode}} must be either a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]] or an integer representing a scancode.
3092
3093This procedure queries SDL's internal state, which is tied to the
3094event system. Call {{pump-events!}} to update the keyboard state.
3095
3096This procedure is based on
3097[[https://wiki.libsdl.org/SDL_GetKeyboardState|SDL_GetKeyboardState]].
3098
3099
3100<procedure>(mod-state) → list of symbols </procedure>
3101
3102See [[https://wiki.libsdl.org/SDL_GetModState|SDL_GetModState]].
3103
3104Returns a list of zero or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-modifiers|keyboard modifier symbols]].
3105
3106
3107<procedure>(mod-state-raw) → fixnum</procedure>
3108
3109See [[https://wiki.libsdl.org/SDL_GetModState|SDL_GetModState]].
3110
3111Returns an integer representing a bitfield of keyboard modifiers.
3112See also {{mod-state}}.
3113
3114
3115<setter>(set! (mod-state) state)</setter>
3116<setter>(mod-state-set! state)</setter>
3117
3118See [[https://wiki.libsdl.org/SDL_SetModState|SDL_SetModState]].
3119
3120State can be either a list of [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-modifiers|keyboard modifier symbols]] or an integer representing a bitfield of keyboard modifiers.
3121
3122
3123<setter>(text-input-rect-set! rect)</setter>
3124
3125{{rect}} can be an sdl2:rect or #f.
3126
3127See [[https://wiki.libsdl.org/SDL_SetTextInputRect|SDL_SetTextInputRect]].
3128
3129
3130<procedure>(start-text-input!)</procedure>
3131
3132See [[https://wiki.libsdl.org/SDL_StartTextInput|SDL_StartTextInput]].
3133
3134
3135<procedure>(stop-text-input!)</procedure>
3136
3137See [[https://wiki.libsdl.org/SDL_StopTextInput|SDL_StopTextInput]].
3138
3139
3140<procedure>(text-input-active?) → boolean</procedure>
3141
3142See [[https://wiki.libsdl.org/SDL_IsTextInputActive|SDL_IsTextInputActive]].
3143
3144
3145<procedure>(screen-keyboard-support?) → boolean</procedure>
3146
3147See [[https://wiki.libsdl.org/SDL_HasScreenKeyboardSupport|SDL_HasScreenKeyboardSupport]].
3148
3149
3150<procedure>(screen-keyboard-shown? window) → boolean</procedure>
3151
3152See [[https://wiki.libsdl.org/SDL_IsScreenKeyboardShown|SDL_IsScreenKeyboardShown]].
3153
3154
3155
3156==== Rect / Point
3157
3158<procedure>(rect-empty? rect) → boolean</procedure>
3159
3160See [[https://wiki.libsdl.org/SDL_RectEmpty|SDL_RectEmpty]].
3161
3162
3163<procedure>(rect=? rect1 rect2) → boolean</procedure>
3164
3165See [[https://wiki.libsdl.org/SDL_RectEquals|SDL_RectEquals]].
3166
3167
3168<procedure>(enclose-points points #!optional clip result-rect) → [rect any-enclosed?]</procedure>
3169
3170See [[https://wiki.libsdl.org/SDL_EnclosePoints|SDL_EnclosePoints]].
3171
3172{{points}} must be a list of sdl2:points.
3173
3174{{clip}} must be either an sdl2:rect or #f (the default). If {{clip}}
3175is an sdl2:rect, points outside the clip rect will be ignored.
3176
3177If {{result-rect}} is omitted or #f, a new managed sdl2:rect will be
3178returned. If {{result-rect}} is an sdl2:rect, it will be modified and
3179returned. {{result-rect}} must not be the same object as either
3180{{rect1}} or {{rect2}}.
3181
3182This procedure returns multiple values:
3183
3184; rect : An sdl2:rect that encloses all matching points. Possibly the same object as {{result-rect}}.
3185; any-enclosed? : #t if any points were enclosed, or #f if all points were clipped
3186
3187
3188<procedure>(has-intersection? rect1 rect2) → boolean</procedure>
3189
3190See [[https://wiki.libsdl.org/SDL_HasIntersection|SDL_HasIntersection]].
3191
3192
3193<procedure>(intersect-rect rect1 rect2 #!optional result-rect) → [rect intersect?]</procedure>
3194
3195See [[https://wiki.libsdl.org/SDL_IntersectRect|SDL_IntersectRect]].
3196
3197If {{result-rect}} is omitted or #f, a new managed sdl2:rect will be
3198returned. If {{result-rect}} is an sdl2:rect, it will be modified and
3199returned. {{result-rect}} must not be the same object as either
3200{{rect1}} or {{rect2}}.
3201
3202This procedure returns multiple values:
3203
3204; rect : An sdl2:rect of the intersection of {{rect1}} and {{rect2}}. Possibly the same object as {{result-rect}}.
3205; intersect? : #t if {{rect1}} and {{rect2}} intersect, otherwise #f
3206
3207
3208<procedure>(intersect-rect-and-line rect x1 y1 x2 y2) → [intersect? x1-new y1-new x2-new y2-new]</procedure>
3209
3210See [[https://wiki.libsdl.org/SDL_IntersectRectAndLine|SDL_IntersectRectAndLine]].
3211
3212This procedure returns multiple values:
3213
3214; intersect? : #t if the given line intersects with the rect
3215; x1-new : the x value of the point within rect that is closest to the first point
3216; y1-new : the y value ...
3217; x2-new : the x value of the point within rect that is closest to the second point
3218; y2-new : the y value ...
3219
3220
3221<procedure>(union-rect rect1 rect2 #!optional result-rect) → rect</procedure>
3222
3223See [[https://wiki.libsdl.org/SDL_UnionRect|SDL_UnionRect]].
3224
3225If {{result-rect}} is omitted or #f, a new managed sdl2:rect will be
3226returned. If {{result-rect}} is an sdl2:rect, it will be modified and
3227returned. {{result-rect}} must not be the same object as either
3228{{rect1}} or {{rect2}}.
3229
3230
3231==== RWops
3232
3233<procedure>(rw-from-file filepath) → sdl2:rwops</procedure>
3234
3235See [[https://wiki.libsdl.org/SDL_RWFromFile|SDL_RWFromFile]].
3236
3237You should close the sdl2:rwops when you are done with it, using
3238{{rw-close!}} or one of the procedures that can automatically close
3239the sdl2:rwops, such as {{load-bmp-rw}}.
3240
3241
3242<procedure>(rw-from-const-mem pointer) → sdl2:rwops</procedure>
3243
3244See [[https://wiki.libsdl.org/SDL_RWFromConstMem|SDL_RWFromConstMem]].
3245
3246You should close the sdl2:rwops when you are done with it, using
3247{{rw-close!}} or one of the procedures that can automatically close
3248the sdl2:rwops, such as {{load-bmp-rw}}.
3249
3250
3251<procedure>(rw-from-mem pointer) → sdl2:rwops</procedure>
3252
3253See [[https://wiki.libsdl.org/SDL_RWFromMem|SDL_RWFromMem]].
3254
3255You should close the sdl2:rwops when you are done with it, using
3256{{rw-close!}} or one of the procedures that can automatically close
3257the sdl2:rwops, such as {{load-bmp-rw}}.
3258
3259
3260<procedure>(rw-from-blob blob) → sdl2:rwops</procedure>
3261
3262Create a new sdl2:rwops that accesses the memory of the given
3263[[http://wiki.call-cc.org/man/4/Unit%20library#blobs|blob]]. You
3264should close the sdl2:rwops when you are done with it, using
3265{{rw-close!}} or one of the procedures that can automatically close
3266the sdl2:rwops, such as {{load-bmp-rw}}.
3267
3268You can also use this procedure to create a sdl2:rwops from a
3269[[/man/4/Unit srfi-4|SRFI-4]] numeric vector, by first converting it
3270to a blob using e.g. {{u8vector->blob/shared}}.
3271
3272'''CAUTION:''' Creating a sdl2:rwops from a blob in CHICKEN-managed
3273memory is unstable: the blob might be garbage collected or moved in
3274memory, which would break the sdl2:rwops. To be safe, you should
3275[[/man/4/Unit lolevel#object-evict|evict]] the blob and create the
3276sdl2:rwops from the evicted blob (not the original). You may wish to
3277[[/man/4/Unit lolevel#object-release|release]] the evicted blob after
3278you have closed the sdl2:rwops. Example:
3279
3280<enscript highlight="scheme">
3281(let* ((evicted-blob (object-evict '#${...}))
3282       (rwops (sdl2:rw-from-blob evicted-blob))
3283       (surf (sdl2:load-bmp-rw rwops #t)))
3284  (object-release evicted-blob)
3285  surf)
3286</enscript>
3287
3288
3289<procedure>(rw-from-string str) → sdl2:rwops</procedure>
3290
3291Create a new sdl2:rwops that accesses the memory of the given CHICKEN
3292Scheme string. You should close the sdl2:rwops when you are done with
3293it, using {{rw-close!}} or one of the procedures that can
3294automatically close the sdl2:rwops, such as {{load-bmp-rw}}.
3295
3296'''CAUTION:''' Creating a sdl2:rwops from a string in CHICKEN-managed
3297memory is unstable: the string might be garbage collected or moved in
3298memory, which would break the sdl2:rwops. To be safe, you should
3299[[/man/4/Unit lolevel#object-evict|evict]] the string and create the
3300sdl2:rwops from the evicted string (not the original). You may wish to
3301[[/man/4/Unit lolevel#object-release|release]] the evicted string
3302after you have closed the sdl2:rwops. Example:
3303
3304<enscript highlight="scheme">
3305(let* ((evicted-string (object-evict "..."))
3306       (rwops (sdl2:rw-from-string evicted-string))
3307       (surf (sdl2:load-bmp-rw rwops #t)))
3308  (object-release evicted-string)
3309  surf)
3310</enscript>
3311
3312
3313<procedure>(rw-close! rwops) → fixnum</procedure>
3314
3315See [[https://wiki.libsdl.org/SDL_RWclose|SDL_RWclose]].
3316
3317Close and clean up the given sdl2:rwops. This frees the memory used by
3318the SDL_RWops struct itself, but does not free or release the pointer,
3319blob, or string that the sdl2:rwops was reading/writing from. (It does
3320close files opened with {{rw-from-file}}, though.)
3321
3322Returns zero if successful.
3323
3324
3325
3326==== Surface
3327
3328<procedure>(make-surface width height depth) → sdl2:surface or #f</procedure>
3329
3330Create a new managed sdl2:surface with the given width, height, and
3331color depth (bits per pixel). This is a more convenient interface for
3332{{create-rgb-surface}}. The sdl2:surface's pixel format and masks will
3333be chosen automatically based on the requested depth and the current
3334platform's byte order (little endian or big endian). Returns #f if the
3335sdl2:surface could not be created (e.g. because the color depth is
3336unsupported).
3337
3338
3339<procedure>(make-surface* width height depth) → sdl2:surface or #f</procedure>
3340
3341Similar to {{make-surface}}, except that the returned sdl2:surface
3342will be '''unmanaged'''. You must call {{free-surface!}} when you are
3343done with it.
3344
3345
3346<procedure>(create-rgb-surface flags width height depth rmask gmask bmask amask) → sdl2:surface</procedure>
3347
3348See [[https://wiki.libsdl.org/SDL_CreateRGBSurface|SDL_CreateRGBSurface]].
3349
3350Returns a new '''unmanaged''' sdl2:surface with the given properties.
3351You must call {{free-surface!}} when you are done with it.
3352
3353See also {{make-surface}} for a more convenient interface.
3354
3355
3356<procedure>(create-rgb-surface-from pixels width height depth pitch rmask gmask bmask amask) → sdl2:surface</procedure>
3357
3358See [[https://wiki.libsdl.org/SDL_CreateRGBSurfaceFrom|SDL_CreateRGBSurfaceFrom]].
3359
3360Returns a new '''unmanaged''' sdl2:surface with the given properties,
3361using existing pixel data (a pointer). You must call {{free-surface!}}
3362when you are done with it.
3363
3364
3365<procedure>(convert-surface surface pixel-format) → sdl2:surface</procedure>
3366
3367See [[https://wiki.libsdl.org/SDL_ConvertSurface|SDL_ConvertSurface]].
3368
3369Returns a managed sdl2:surface.
3370
3371
3372<procedure>(convert-surface* surface pixel-format) → sdl2:surface</procedure>
3373
3374See [[https://wiki.libsdl.org/SDL_ConvertSurface|SDL_ConvertSurface]].
3375
3376Similar to {{convert-surface}}, except that the returned sdl2:surface
3377will be '''unmanaged'''. You must call {{free-surface!}} when you are
3378done with it.
3379
3380
3381
3382<procedure>(load-bmp path-string) → sdl2:surface</procedure>
3383
3384See [[https://wiki.libsdl.org/SDL_LoadBMP|SDL_LoadBMP]].
3385
3386Attempts to load a BMP image file. Returns a managed sdl2:surface
3387containing the image data, or #f if the image could not be loaded.
3388
3389'''NOTE:''' This procedure only supports certain kinds of BMP image.
3390Use the [[/egg/sdl2-image|sdl2-image egg]] for better BMP support,
3391plus support for loading other image formats like JPG, PNG, and GIF.
3392
3393
3394<procedure>(load-bmp* filepath) → sdl2:surface</procedure>
3395
3396Similar to {{load-bmp}}, except that the returned sdl2:surface will be
3397'''unmanaged'''. You must call {{free-surface!}} when you are done
3398with it.
3399
3400
3401<procedure>(load-bmp-rw rwops #!optional close?) → sdl2:surface</procedure>
3402
3403See [[https://wiki.libsdl.org/SDL_LoadBMP_RW|SDL_LoadBMP_RW]].
3404
3405Attempts to load a BMP image from the given sdl2:rwops. Returns a
3406managed sdl2:surface containing the image data, or #f if the image
3407could not be loaded.
3408
3409If {{close?}} is #t, {{rwops}} will be automatically closed (see
3410{{rw-close!}}) after the image is loaded. If {{close?}} is #f or
3411omitted, {{rwops}} will not be closed.
3412
3413'''NOTE:''' This procedure only supports certain kinds of BMP image.
3414Use the [[/egg/sdl2-image|sdl2-image egg]] for better BMP support,
3415plus support for loading other image formats like JPG, PNG, and GIF.
3416
3417
3418
3419<procedure>(load-bmp-rw* rwops #!optional close?) → sdl2:surface</procedure>
3420
3421Similar to {{load-bmp-rw}}, except that the sdl2:surface will be
3422'''unmanaged'''. You must call {{free-surface!}} when you are done
3423with it.
3424
3425
3426<procedure>(save-bmp! surface filepath) → fixnum</procedure>
3427
3428See [[https://wiki.libsdl.org/SDL_SaveBMP|SDL_SaveBMP]].
3429
3430Returns zero if successful.
3431
3432
3433<procedure>(save-bmp-rw! surface rwops #!optional close?) → fixnum</procedure>
3434
3435See [[https://wiki.libsdl.org/SDL_SaveBMP_RW|SDL_SaveBMP_RW]].
3436
3437If {{close?}} is #t, {{rwops}} will be automatically closed (see
3438{{rw-close!}}) after the image is loaded. If {{close?}} is #f or
3439omitted, {{rwops}} will not be closed.
3440
3441Returns zero if successful.
3442
3443
3444<procedure>(lock-surface! surface) → fixnum</procedure>
3445
3446See [[https://wiki.libsdl.org/SDL_LockSurface|SDL_LockSurface]].
3447
3448Returns zero if successful.
3449
3450
3451<procedure>(unlock-surface! surface)</procedure>
3452
3453See [[https://wiki.libsdl.org/SDL_UnlockSurface|SDL_UnlockSurface]].
3454
3455
3456<procedure>(must-lock? surface) → boolean</procedure>
3457
3458See [[https://wiki.libsdl.org/SDL_MUSTLOCK|SDL_MUSTLOCK]].
3459
3460
3461<procedure>(blit-surface! src src-rect dest dest-rect) → fixnum</procedure>
3462
3463See [[https://wiki.libsdl.org/SDL_BlitSurface|SDL_BlitSurface]].
3464
3465Returns zero if successful. May modify dest-rect.
3466
3467
3468<procedure>(blit-scaled! src src-rect dest dest-rect) → fixnum</procedure>
3469
3470See [[https://wiki.libsdl.org/SDL_BlitScaled|SDL_BlitScaled]].
3471
3472Returns zero if successful. May modify dest-rect.
3473
3474
3475<procedure>(lower-blit! src src-rect dest dest-rect) → fixnum</procedure>
3476
3477See [[https://wiki.libsdl.org/SDL_LowerBlit|SDL_LowerBlit]].
3478
3479Returns zero if successful. May modify dest-rect.
3480
3481
3482<procedure>(lower-blit-scaled! src src-rect dest dest-rect) → fixnum</procedure>
3483
3484See [[https://wiki.libsdl.org/SDL_LowerBlitScaled|SDL_LowerBlitScaled]].
3485
3486Returns zero if successful. May modify dest-rect.
3487
3488
3489<procedure>(fill-rect! surface rect color) → fixnum</procedure>
3490
3491See [[https://wiki.libsdl.org/SDL_FillRect|SDL_FillRect]].
3492
3493{{rect}} may be an sdl2:rect to fill part of the surface, or #f to fill
3494the entire surface.
3495
3496{{color}} may be an sdl2:color or a mapped color (an integer, like
3497returned by {{map-rgba}}).
3498
3499Returns zero if successful.
3500
3501
3502<procedure>(fill-rects! surface rects color) → fixnum</procedure>
3503
3504See [[https://wiki.libsdl.org/SDL_FillRects|SDL_FillRects]].
3505
3506{{rects}} must be a list of sdl2:rects.
3507
3508{{color}} may be an sdl2:color or a mapped color (an integer, like
3509returned by {{map-rgba}}).
3510
3511Returns zero if successful.
3512
3513
3514<procedure>(surface-ref surface x y) → sdl2:color</procedure>
3515
3516Returns the color of the specified pixel on the surface, as an
3517sdl2:color. Signals an error if {{x}} or {{y}} is out of bounds.
3518
3519
3520<procedure>(surface-ref-raw surface x y) → fixnum</procedure>
3521
3522Similar to {{surface-ref}}, but returns a mapped color (an integer)
3523instead of an sdl2:color. You can use {{get-rgba}} to convert the
3524mapped color to color fields.
3525
3526
3527<setter>(set! (surface-ref surface x y) color)</setter>
3528<setter>(surface-set! surface x y color)</setter>
3529
3530Set the color of the specified pixel on the surface. Automatically
3531locks and unlocks the surface if needed. Signals an error if {{x}} or
3532{{y}} is out of bounds. {{color}} can be either an sdl2:color or a
3533mapped color (an integer). Note: This procedure ignores the surface's
3534clip rect (if any).
3535
3536
3537<procedure>(surface-clip-rect surface) → sdl2:rect</procedure>
3538
3539See [[https://wiki.libsdl.org/SDL_GetClipRect|SDL_GetClipRect]].
3540
3541Returns a copy of the surface's clip rect.
3542
3543
3544<setter>(set! (surface-clip-rect surface) rect) → boolean</setter>
3545<setter>(surface-clip-rect-set! surface rect) → boolean</setter>
3546
3547See [[https://wiki.libsdl.org/SDL_SetClipRect|SDL_SetClipRect]].
3548
3549Sets the surface's clip rect to a copy of the given rect. Or {{rect}}
3550can be #f to disable clipping.
3551
3552Returns #t if the given rect intersects the surface at all, or #f if
3553the rect is out of bounds (completely clips out the surface).
3554
3555
3556<procedure>(surface-color-key surface) → sdl2:color or #f</procedure>
3557<procedure>(surface-colour-key surface) → sdl2:color or #f</procedure>
3558
3559See [[https://wiki.libsdl.org/SDL_GetColorKey|SDL_GetColorKey]].
3560
3561
3562<procedure>(surface-color-key-raw surface) → fixnum or #f</procedure>
3563<procedure>(surface-colour-key-raw surface) → fixnum or #f</procedure>
3564
3565Similar to {{surface-color-key}}, but returns a mapped color (an
3566integer) instead of an sdl2:color.
3567
3568
3569<setter>(set! (surface-color-key surface) color) → boolean</setter>
3570<setter>(set! (surface-colour-key surface) color) → boolean</setter>
3571<setter>(surface-color-key-set! surface color) → boolean</setter>
3572<setter>(surface-colour-key-set! surface color) → boolean</setter>
3573
3574See [[https://wiki.libsdl.org/SDL_SetColorKey|SDL_SetColorKey]].
3575
3576{{color}} can be an sdl2:color, a mapped color (an integer), or #f to
3577disable color keying.
3578
3579Returns zero if successful.
3580
3581
3582<procedure>(surface-alpha-mod surface) → fixnum</procedure>
3583
3584See [[https://wiki.libsdl.org/SDL_GetSurfaceAlphaMod|SDL_GetSurfaceAlphaMod]].
3585
3586
3587<setter>(set! (surface-alpha-mod surface) mod) → fixnum</setter>
3588<setter>(surface-alpha-mod-set! surface mod) → fixnum</setter>
3589
3590See [[https://wiki.libsdl.org/SDL_SetSurfaceAlphaMod|SDL_SetSurfaceAlphaMod]].
3591
3592Returns zero on success.
3593
3594
3595<procedure>(surface-blend-mode surface) → symbol</procedure>
3596
3597See [[https://wiki.libsdl.org/SDL_GetSurfaceBlendMode|SDL_GetSurfaceBlendMode]].
3598
3599Returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-mode|blend mode symbol]]:
3600
3601* {{'none}}
3602* {{'blend}}
3603* {{'add}}
3604* {{'mod}}
3605
3606
3607<setter>(set! (surface-blend-mode surface) mode)</setter>
3608<setter>(surface-blend-mode-set! surface mode)</setter>
3609
3610See [[https://wiki.libsdl.org/SDL_SetSurfaceBlendMode|SDL_SetSurfaceBlendMode]].
3611
3612{{mode}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-mode|blend mode symbol]] or equivalent integer:
3613
3614* {{'none}}
3615* {{'blend}}
3616* {{'add}}
3617* {{'mod}}
3618
3619
3620<procedure>(surface-color-mod surface) → [r g b]</procedure>
3621<procedure>(surface-colour-mod surface) → [r g b]</procedure>
3622
3623See [[https://wiki.libsdl.org/SDL_GetSurfaceColorMod|SDL_GetSurfaceColorMod]].
3624
3625This procedure returns multiple values.
3626
3627
3628<setter>(set! (surface-color-mod surface) rgb)</setter>
3629<setter>(set! (surface-colour-mod surface) rgb)</setter>
3630<setter>(surface-color-mod-set! surface rgb)</setter>
3631<setter>(surface-colour-mod-set! surface rgb)</setter>
3632
3633See [[https://wiki.libsdl.org/SDL_SetSurfaceColorMod|SDL_SetSurfaceColorMod]].
3634
3635{{rgb}} can be a list {{(r g b)}} of color values, or an sdl2:color (the
3636sdl2:color's "a" field will be ignored).
3637
3638
3639<procedure>(surface-palette surface) → sdl2:palette or #f</procedure>
3640
3641Returns the surface's palette, or #f if it has no palette. This is
3642equivalent to:
3643
3644 (pixel-format-palette
3645  (surface-format surface))
3646
3647
3648<setter>(set! (surface-palette surface) palette)</setter>
3649<setter>(surface-palette-set! surface palette)</setter>
3650
3651See [[https://wiki.libsdl.org/SDL_SetSurfacePalette|SDL_SetSurfacePalette]].
3652
3653
3654<setter>(surface-rle-set! surface enable)</setter>
3655
3656See [[https://wiki.libsdl.org/SDL_SetSurfaceRLE|SDL_SetSurfaceRLE]].
3657
3658{{enable}} is #t to enable RLE acceleration or #f to disable it.
3659
3660
3661
3662==== Timer
3663
3664<procedure>(delay! milliseconds)</procedure>
3665
3666See [[https://wiki.libsdl.org/SDL_Delay|SDL_Delay]].
3667
3668'''NOTE:''' This will (probably) cause all CHICKEN threads to pause,
3669not only the thread that this is called from.
3670
3671
3672<procedure>(get-ticks) → fixnum</procedure>
3673
3674See [[https://wiki.libsdl.org/SDL_GetTicks|SDL_GetTicks]].
3675
3676
3677<procedure>(get-performance-counter) → fixnum</procedure>
3678
3679See [[https://wiki.libsdl.org/SDL_GetPerformanceCounter|SDL_GetPerformanceCounter]].
3680
3681
3682<procedure>(get-performance-frequency) → fixnum</procedure>
3683
3684See [[https://wiki.libsdl.org/SDL_GetPerformanceFrequency|SDL_GetPerformanceFrequency]].
3685
3686
3687<procedure>(ticks-passed? ticks-a ticks-b) → boolean</procedure>
3688
3689See [[https://wiki.libsdl.org/SDL_TICKS_PASSED|SDL_TICKS_PASSED]].
3690
3691Requires SDL 2.0.1 or higher. Signals an error if the compiled version
3692of SDL is not high enough. Use {{(version-at-least? 2 0 1)}} to
3693check before calling this procedure.
3694
3695
3696
3697==== Window
3698
3699<procedure>(create-window! title x y w h #!optional flags) → sdl2:window</procedure>
3700
3701See [[https://wiki.libsdl.org/SDL_CreateWindow|SDL_CreateWindow]].
3702
3703{{x}} and {{y}} can be integers, the symbol {{'centered}}, or the symbol {{'undefined}}.
3704
3705{{flags}} defaults to {{'()}}. It must be a list of zero or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#window-flags|window flag symbols]] (or an equivalent integer bitfield):
3706
3707* {{'fullscreen}}
3708* {{'fullscreen-desktop}}
3709* {{'opengl}}
3710* {{'shown}}
3711* {{'hidden}}
3712* {{'borderless}}
3713* {{'resizable}}
3714* {{'minimized}}
3715* {{'maximized}}
3716* {{'input-grabbed}}
3717* {{'input-focus}}
3718* {{'mouse-focus}}
3719* {{'foreign}}
3720
3721
3722<procedure>(get-window-from-id id) → sdl2:window</procedure>
3723
3724See [[https://wiki.libsdl.org/SDL_GetWindowFromID|SDL_GetWindowFromID]].
3725
3726
3727<procedure>(destroy-window! window)</procedure>
3728
3729See [[https://wiki.libsdl.org/SDL_DestroyWindow|SDL_DestroyWindow]].
3730
3731
3732<procedure>(update-window-surface! window) → fixnum</procedure>
3733
3734See [[https://wiki.libsdl.org/SDL_UpdateWindowSurface|SDL_UpdateWindowSurface]].
3735
3736Returns zero if successful.
3737
3738
3739<procedure>(update-window-surface-rects! window rects) → fixnum</procedure>
3740
3741See [[https://wiki.libsdl.org/SDL_UpdateWindowSurfaceRects|SDL_UpdateWindowSurfaceRects]].
3742
3743{{rects}} must be a list of sdl2:rects.
3744
3745Returns zero if successful.
3746
3747
3748<procedure>(show-window! window)</procedure>
3749
3750See [[https://wiki.libsdl.org/SDL_ShowWindow|SDL_ShowWindow]].
3751
3752
3753<procedure>(hide-window! window)</procedure>
3754
3755See [[https://wiki.libsdl.org/SDL_HideWindow|SDL_HideWindow]].
3756
3757
3758<procedure>(maximize-window! window)</procedure>
3759
3760See [[https://wiki.libsdl.org/SDL_MaximizeWindow|SDL_MaximizeWindow]].
3761
3762
3763<procedure>(minimize-window! window)</procedure>
3764
3765See [[https://wiki.libsdl.org/SDL_MinimizeWindow|SDL_MinimizeWindow]].
3766
3767
3768<procedure>(raise-window! window)</procedure>
3769
3770See [[https://wiki.libsdl.org/SDL_RaiseWindow|SDL_RaiseWindow]].
3771
3772
3773<procedure>(restore-window! window)</procedure>
3774
3775See [[https://wiki.libsdl.org/SDL_RestoreWindow|SDL_RestoreWindow]].
3776
3777
3778<setter>(window-bordered-set! window bordered)</setter>
3779
3780See [[https://wiki.libsdl.org/SDL_SetWindowBordered|SDL_SetWindowBordered]].
3781
3782{{bordered}} is #t to enable window decoration or #f to disable window
3783decoration.
3784
3785(There is currently no getter.)
3786
3787
3788<procedure>(window-brightness window) → float</procedure>
3789
3790See [[https://wiki.libsdl.org/SDL_GetWindowBrightness|SDL_GetWindowBrightness]].
3791
3792
3793<setter>(set! (window-brightness window) brightness) → fixnum</setter>
3794<setter>(window-brightness-set! window brightness) → fixnum</setter>
3795
3796See [[https://wiki.libsdl.org/SDL_SetWindowBrightness|SDL_SetWindowBrightness]].
3797
3798Returns zero if successful.
3799
3800
3801<procedure>(window-display-index window) → fixnum</procedure>
3802
3803See [[https://wiki.libsdl.org/SDL_GetWindowDisplayIndex|SDL_GetWindowDisplayIndex]].
3804
3805
3806<procedure>(window-display-mode window) → sdl2:display-mode</procedure>
3807
3808See [[https://wiki.libsdl.org/SDL_GetWindowDisplayMode|SDL_GetWindowDisplayMode]].
3809
3810
3811<setter>(set! (window-display-mode surface) mode) → boolean</setter>
3812<setter>(window-display-mode-set! surface mode) → boolean</setter>
3813
3814TODO: Docs.
3815
3816
3817<procedure>(window-flags window) → list of symbols</procedure>
3818
3819See [[https://wiki.libsdl.org/SDL_GetWindowFlags|SDL_GetWindowFlags]].
3820
3821Returns a list of [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#window-flags|window flag symbols]].
3822
3823
3824<setter>(window-fullscreen-set! window mode)</setter>
3825
3826See [[https://wiki.libsdl.org/SDL_SetWindowFullscreen|SDL_SetWindowFullscreen]].
3827
3828{{mode}} can be:
3829
3830; 'fullscreen or #t : fullscreen
3831; 'fullscreen-desktop : fullscreen desktop
3832; #f : not fullscreen
3833
3834Returns zero if successful.
3835
3836
3837<procedure>(window-grab window) → boolean</procedure>
3838
3839See [[https://wiki.libsdl.org/SDL_GetWindowGrab|SDL_GetWindowGrab]].
3840
3841
3842<setter>(set! (window-grab window) grab?</setter>
3843<setter>(window-grab-set! window grab?)</setter>
3844
3845See [[https://wiki.libsdl.org/SDL_SetWindowGrab|SDL_SetWindowGrab]].
3846
3847
3848<setter>(window-icon-set! window icon-surface)</setter>
3849
3850See [[https://wiki.libsdl.org/SDL_SetWindowIcon|SDL_SetWindowIcon]].
3851
3852
3853<procedure>(window-id window) → fixnum</procedure>
3854
3855See [[https://wiki.libsdl.org/SDL_GetWindowID|SDL_GetWindowID]].
3856
3857
3858<procedure>(window-maximum-size window) → [width height]</procedure>
3859
3860See [[https://wiki.libsdl.org/SDL_GetWindowMaximumSize|SDL_GetWindowMaximumSize]].
3861
3862This procedure returns multiple values.
3863
3864
3865<setter>(set! (window-maximum-size window) size)</setter>
3866<setter>(window-maximum-size-set! window size)</setter>
3867
3868See [[https://wiki.libsdl.org/SDL_SetWindowMaximumSize|SDL_SetWindowMaximumSize]].
3869
3870{{size}} must be a list of integers {{(width height)}}.
3871
3872
3873<procedure>(window-minimum-size window) → [width height]</procedure>
3874
3875See [[https://wiki.libsdl.org/SDL_GetWindowMinimumSize|SDL_GetWindowMinimumSize]].
3876
3877This procedure returns multiple values.
3878
3879
3880<setter>(set! (window-minimum-size window) size)</setter>
3881<setter>(window-minimum-size-set! window size)</setter>
3882
3883See [[https://wiki.libsdl.org/SDL_SetWindowMinimumSize|SDL_SetWindowMinimumSize]].
3884
3885{{size}} must be a list of integers {{(width height)}}.
3886
3887
3888<procedure>(window-pixel-format window) → sdl2:pixel-format</procedure>
3889
3890See [[https://wiki.libsdl.org/SDL_GetWindowPixelFormat|SDL_GetWindowPixelFormat]].
3891
3892
3893<procedure>(window-position window) → [x y]</procedure>
3894
3895See [[https://wiki.libsdl.org/SDL_GetWindowPosition|SDL_GetWindowPosition]].
3896
3897This procedure returns multiple values.
3898
3899
3900<setter>(set! (window-position window) pos)</setter>
3901<setter>(window-position-set! window pos)</setter>
3902
3903See [[https://wiki.libsdl.org/SDL_SetWindowPosition|SDL_SetWindowPosition]].
3904
3905{{pos}} must be a list of integers {{(x y)}}.
3906
3907
3908<procedure>(window-size window) → [width height]</procedure>
3909
3910See [[https://wiki.libsdl.org/SDL_GetWindowSize|SDL_GetWindowSize]].
3911
3912This procedure returns multiple values.
3913
3914
3915<setter>(set! (window-size window) size)</setter>
3916<setter>(window-size-set! window size)</setter>
3917
3918See [[https://wiki.libsdl.org/SDL_SetWindowSize|SDL_SetWindowSize]].
3919
3920{{size}} must be a list of integers {{(width height)}}.
3921
3922
3923<procedure>(window-surface window) → sdl2:surface</procedure>
3924
3925See [[https://wiki.libsdl.org/SDL_GetWindowSurface|SDL_GetWindowSurface]].
3926
3927
3928<procedure>(window-title window) → string</procedure>
3929
3930See [[https://wiki.libsdl.org/SDL_GetWindowTitle|SDL_GetWindowTitle]].
3931
3932
3933<setter>(set! (window-title window) title)</setter>
3934<setter>(window-title-set! window title)</setter>
3935
3936See [[https://wiki.libsdl.org/SDL_SetWindowTitle|SDL_SetWindowTitle]].
Note: See TracBrowser for help on using the repository browser.