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

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

More work on sdl2 docs.

File size: 121.8 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
3237
3238<procedure>(rw-from-const-mem pointer) → sdl2:rwops</procedure>
3239
3240See [[https://wiki.libsdl.org/SDL_RWFromConstMem|SDL_RWFromConstMem]].
3241
3242
3243<procedure>(rw-from-mem pointer) → sdl2:rwops</procedure>
3244
3245See [[https://wiki.libsdl.org/SDL_RWFromMem|SDL_RWFromMem]].
3246
3247
3248<procedure>(rw-from-blob blob) → sdl2:rwops</procedure>
3249
3250Create a new sdl2:rwops that accesses the memory of the given CHICKEN
3251Scheme blob.
3252
3253'''CAUTION:''' You must make sure that the blob remains in scope for
3254at least as long as the resulting sdl2:rwops is open. If the blob is
3255garbage collected before the sdl2:rwops, the program may crash if you
3256try to read or write from the sdl2:rwops.
3257
3258
3259<procedure>(rw-from-string str) → sdl2:rwops</procedure>
3260
3261Create a new sdl2:rwops that accesses the memory of the given CHICKEN
3262Scheme string.
3263
3264'''CAUTION:''' You must make sure that the string remains in scope for
3265at least as long as the resulting sdl2:rwops is open. If the string is
3266garbage collected before the sdl2:rwops, the program may crash if you
3267try to read or write from the sdl2:rwops.
3268
3269
3270<procedure>(rw-from-u8vector u8v) → sdl2:rwops</procedure>
3271
3272Create a new sdl2:rwops that accesses the memory of the given
3273[[/man/4/Unit srfi-4|SRFI-4]] u8vector.
3274
3275'''CAUTION:''' You must make sure that the u8vector remains in scope
3276for at least as long as the resulting sdl2:rwops is open. If the
3277u8vector is garbage collected before the sdl2:rwops, the program may
3278crash if you try to read or write from the sdl2:rwops.
3279
3280
3281<procedure>(rw-close! rwops) → fixnum</procedure>
3282
3283See [[https://wiki.libsdl.org/SDL_RWclose|SDL_RWclose]].
3284
3285Close and clean up the given sdl2:rwops. This frees the memory used by
3286the SDL_RWops struct itself, but does not free the original pointer,
3287blob, string, or u8vector. (It does close files, though.)
3288
3289Returns zero if successful.
3290
3291
3292
3293==== Surface
3294
3295<procedure>(make-surface width height depth) → sdl2:surface or #f</procedure>
3296
3297Create a new managed sdl2:surface with the given width, height, and
3298color depth (bits per pixel). This is a more convenient interface for
3299{{create-rgb-surface}}. The sdl2:surface's pixel format and masks will
3300be chosen automatically based on the requested depth and the current
3301platform's byte order (little endian or big endian). Returns #f if the
3302sdl2:surface could not be created (e.g. because the color depth is
3303unsupported).
3304
3305
3306<procedure>(make-surface* width height depth) → sdl2:surface or #f</procedure>
3307
3308Similar to {{make-surface}}, except that the returned sdl2:surface
3309will be '''unmanaged'''. You must call {{free-surface!}} when you are
3310done with it.
3311
3312
3313<procedure>(create-rgb-surface flags width height depth rmask gmask bmask amask) → sdl2:surface</procedure>
3314
3315See [[https://wiki.libsdl.org/SDL_CreateRGBSurface|SDL_CreateRGBSurface]].
3316
3317Returns a new '''unmanaged''' sdl2:surface with the given properties.
3318You must call {{free-surface!}} when you are done with it.
3319
3320See also {{make-surface}} for a more convenient interface.
3321
3322
3323<procedure>(create-rgb-surface-from pixels width height depth pitch rmask gmask bmask amask) → sdl2:surface</procedure>
3324
3325See [[https://wiki.libsdl.org/SDL_CreateRGBSurfaceFrom|SDL_CreateRGBSurfaceFrom]].
3326
3327Returns a new '''unmanaged''' sdl2:surface with the given properties,
3328using existing pixel data (a pointer). You must call {{free-surface!}}
3329when you are done with it.
3330
3331
3332<procedure>(convert-surface surface pixel-format) → sdl2:surface</procedure>
3333
3334See [[https://wiki.libsdl.org/SDL_ConvertSurface|SDL_ConvertSurface]].
3335
3336Returns a managed sdl2:surface.
3337
3338
3339<procedure>(convert-surface* surface pixel-format) → sdl2:surface</procedure>
3340
3341See [[https://wiki.libsdl.org/SDL_ConvertSurface|SDL_ConvertSurface]].
3342
3343Similar to {{convert-surface}}, except that the returned sdl2:surface
3344will be '''unmanaged'''. You must call {{free-surface!}} when you are
3345done with it.
3346
3347
3348
3349<procedure>(load-bmp path-string) → sdl2:surface</procedure>
3350
3351See [[https://wiki.libsdl.org/SDL_LoadBMP|SDL_LoadBMP]].
3352
3353Attempts to load a BMP image file. Returns a managed sdl2:surface
3354containing the image data, or #f if the image could not be loaded.
3355
3356'''NOTE:''' This procedure only supports certain kinds of BMP image.
3357Use the [[/egg/sdl2-image|sdl2-image egg]] for better BMP support,
3358plus support for loading other image formats like JPG, PNG, and GIF.
3359
3360
3361<procedure>(load-bmp* filepath) → sdl2:surface</procedure>
3362
3363Similar to {{load-bmp}}, except that the returned sdl2:surface will be
3364'''unmanaged'''. You must call {{free-surface!}} when you are done
3365with it.
3366
3367
3368<procedure>(load-bmp-rw rwops #!optional close?) → sdl2:surface</procedure>
3369
3370See [[https://wiki.libsdl.org/SDL_LoadBMP_RW|SDL_LoadBMP_RW]].
3371
3372Attempts to load a BMP image from the given sdl2:rwops. Returns a
3373managed sdl2:surface containing the image data, or #f if the image
3374could not be loaded.
3375
3376If {{close?}} is #t, {{rwops}} will be automatically closed (see
3377{{rw-close!}}) after the image is loaded. If {{close?}} is #f or
3378omitted, {{rwops}} will not be closed.
3379
3380'''NOTE:''' This procedure only supports certain kinds of BMP image.
3381Use the [[/egg/sdl2-image|sdl2-image egg]] for better BMP support,
3382plus support for loading other image formats like JPG, PNG, and GIF.
3383
3384
3385
3386<procedure>(load-bmp-rw* rwops #!optional close?) → sdl2:surface</procedure>
3387
3388Similar to {{load-bmp-rw}}, except that the sdl2:surface will be
3389'''unmanaged'''. You must call {{free-surface!}} when you are done
3390with it.
3391
3392
3393<procedure>(save-bmp! surface filepath) → fixnum</procedure>
3394
3395See [[https://wiki.libsdl.org/SDL_SaveBMP|SDL_SaveBMP]].
3396
3397Returns zero if successful.
3398
3399
3400<procedure>(save-bmp-rw! surface rwops #!optional close?) → fixnum</procedure>
3401
3402See [[https://wiki.libsdl.org/SDL_SaveBMP_RW|SDL_SaveBMP_RW]].
3403
3404If {{close?}} is #t, {{rwops}} will be automatically closed (see
3405{{rw-close!}}) after the image is loaded. If {{close?}} is #f or
3406omitted, {{rwops}} will not be closed.
3407
3408Returns zero if successful.
3409
3410
3411<procedure>(lock-surface! surface) → fixnum</procedure>
3412
3413See [[https://wiki.libsdl.org/SDL_LockSurface|SDL_LockSurface]].
3414
3415Returns zero if successful.
3416
3417
3418<procedure>(unlock-surface! surface)</procedure>
3419
3420See [[https://wiki.libsdl.org/SDL_UnlockSurface|SDL_UnlockSurface]].
3421
3422
3423<procedure>(must-lock? surface) → boolean</procedure>
3424
3425See [[https://wiki.libsdl.org/SDL_MUSTLOCK|SDL_MUSTLOCK]].
3426
3427
3428<procedure>(blit-surface! src src-rect dest dest-rect) → fixnum</procedure>
3429
3430See [[https://wiki.libsdl.org/SDL_BlitSurface|SDL_BlitSurface]].
3431
3432Returns zero if successful. May modify dest-rect.
3433
3434
3435<procedure>(blit-scaled! src src-rect dest dest-rect) → fixnum</procedure>
3436
3437See [[https://wiki.libsdl.org/SDL_BlitScaled|SDL_BlitScaled]].
3438
3439Returns zero if successful. May modify dest-rect.
3440
3441
3442<procedure>(lower-blit! src src-rect dest dest-rect) → fixnum</procedure>
3443
3444See [[https://wiki.libsdl.org/SDL_LowerBlit|SDL_LowerBlit]].
3445
3446Returns zero if successful. May modify dest-rect.
3447
3448
3449<procedure>(lower-blit-scaled! src src-rect dest dest-rect) → fixnum</procedure>
3450
3451See [[https://wiki.libsdl.org/SDL_LowerBlitScaled|SDL_LowerBlitScaled]].
3452
3453Returns zero if successful. May modify dest-rect.
3454
3455
3456<procedure>(fill-rect! surface rect color) → fixnum</procedure>
3457
3458See [[https://wiki.libsdl.org/SDL_FillRect|SDL_FillRect]].
3459
3460{{rect}} may be an sdl2:rect to fill part of the surface, or #f to fill
3461the entire surface.
3462
3463{{color}} may be an sdl2:color or a mapped color (an integer, like
3464returned by {{map-rgba}}).
3465
3466Returns zero if successful.
3467
3468
3469<procedure>(fill-rects! surface rects color) → fixnum</procedure>
3470
3471See [[https://wiki.libsdl.org/SDL_FillRects|SDL_FillRects]].
3472
3473{{rects}} must be a list of sdl2:rects.
3474
3475{{color}} may be an sdl2:color or a mapped color (an integer, like
3476returned by {{map-rgba}}).
3477
3478Returns zero if successful.
3479
3480
3481<procedure>(surface-ref surface x y) → sdl2:color</procedure>
3482
3483Returns the color of the specified pixel on the surface, as an
3484sdl2:color. Signals an error if {{x}} or {{y}} is out of bounds.
3485
3486
3487<procedure>(surface-ref-raw surface x y) → fixnum</procedure>
3488
3489Similar to {{surface-ref}}, but returns a mapped color (an integer)
3490instead of an sdl2:color. You can use {{get-rgba}} to convert the
3491mapped color to color fields.
3492
3493
3494<setter>(set! (surface-ref surface x y) color)</setter>
3495<setter>(surface-set! surface x y color)</setter>
3496
3497Set the color of the specified pixel on the surface. Automatically
3498locks and unlocks the surface if needed. Signals an error if {{x}} or
3499{{y}} is out of bounds. {{color}} can be either an sdl2:color or a
3500mapped color (an integer). Note: This procedure ignores the surface's
3501clip rect (if any).
3502
3503
3504<procedure>(surface-clip-rect surface) → sdl2:rect</procedure>
3505
3506See [[https://wiki.libsdl.org/SDL_GetClipRect|SDL_GetClipRect]].
3507
3508Returns a copy of the surface's clip rect.
3509
3510
3511<setter>(set! (surface-clip-rect surface) rect) → boolean</setter>
3512<setter>(surface-clip-rect-set! surface rect) → boolean</setter>
3513
3514See [[https://wiki.libsdl.org/SDL_SetClipRect|SDL_SetClipRect]].
3515
3516Sets the surface's clip rect to a copy of the given rect. Or {{rect}}
3517can be #f to disable clipping.
3518
3519Returns #t if the given rect intersects the surface at all, or #f if
3520the rect is out of bounds (completely clips out the surface).
3521
3522
3523<procedure>(surface-color-key surface) → sdl2:color or #f</procedure>
3524<procedure>(surface-colour-key surface) → sdl2:color or #f</procedure>
3525
3526See [[https://wiki.libsdl.org/SDL_GetColorKey|SDL_GetColorKey]].
3527
3528
3529<procedure>(surface-color-key-raw surface) → fixnum or #f</procedure>
3530<procedure>(surface-colour-key-raw surface) → fixnum or #f</procedure>
3531
3532Similar to {{surface-color-key}}, but returns a mapped color (an
3533integer) instead of an sdl2:color.
3534
3535
3536<setter>(set! (surface-color-key surface) color) → boolean</setter>
3537<setter>(set! (surface-colour-key surface) color) → boolean</setter>
3538<setter>(surface-color-key-set! surface color) → boolean</setter>
3539<setter>(surface-colour-key-set! surface color) → boolean</setter>
3540
3541See [[https://wiki.libsdl.org/SDL_SetColorKey|SDL_SetColorKey]].
3542
3543{{color}} can be an sdl2:color, a mapped color (an integer), or #f to
3544disable color keying.
3545
3546Returns zero if successful.
3547
3548
3549<procedure>(surface-alpha-mod surface) → fixnum</procedure>
3550
3551See [[https://wiki.libsdl.org/SDL_GetSurfaceAlphaMod|SDL_GetSurfaceAlphaMod]].
3552
3553
3554<setter>(set! (surface-alpha-mod surface) mod) → fixnum</setter>
3555<setter>(surface-alpha-mod-set! surface mod) → fixnum</setter>
3556
3557See [[https://wiki.libsdl.org/SDL_SetSurfaceAlphaMod|SDL_SetSurfaceAlphaMod]].
3558
3559Returns zero on success.
3560
3561
3562<procedure>(surface-blend-mode surface) → symbol</procedure>
3563
3564See [[https://wiki.libsdl.org/SDL_GetSurfaceBlendMode|SDL_GetSurfaceBlendMode]].
3565
3566Returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-mode|blend mode symbol]]:
3567
3568* {{'none}}
3569* {{'blend}}
3570* {{'add}}
3571* {{'mod}}
3572
3573
3574<setter>(set! (surface-blend-mode surface) mode)</setter>
3575<setter>(surface-blend-mode-set! surface mode)</setter>
3576
3577See [[https://wiki.libsdl.org/SDL_SetSurfaceBlendMode|SDL_SetSurfaceBlendMode]].
3578
3579{{mode}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-mode|blend mode symbol]] or equivalent integer:
3580
3581* {{'none}}
3582* {{'blend}}
3583* {{'add}}
3584* {{'mod}}
3585
3586
3587<procedure>(surface-color-mod surface) → [r g b]</procedure>
3588<procedure>(surface-colour-mod surface) → [r g b]</procedure>
3589
3590See [[https://wiki.libsdl.org/SDL_GetSurfaceColorMod|SDL_GetSurfaceColorMod]].
3591
3592This procedure returns multiple values.
3593
3594
3595<setter>(set! (surface-color-mod surface) rgb)</setter>
3596<setter>(set! (surface-colour-mod surface) rgb)</setter>
3597<setter>(surface-color-mod-set! surface rgb)</setter>
3598<setter>(surface-colour-mod-set! surface rgb)</setter>
3599
3600See [[https://wiki.libsdl.org/SDL_SetSurfaceColorMod|SDL_SetSurfaceColorMod]].
3601
3602{{rgb}} can be a list {{(r g b)}} of color values, or an sdl2:color (the
3603sdl2:color's "a" field will be ignored).
3604
3605
3606<procedure>(surface-palette surface) → sdl2:palette or #f</procedure>
3607
3608Returns the surface's palette, or #f if it has no palette. This is
3609equivalent to:
3610
3611 (pixel-format-palette
3612  (surface-format surface))
3613
3614
3615<setter>(set! (surface-palette surface) palette)</setter>
3616<setter>(surface-palette-set! surface palette)</setter>
3617
3618See [[https://wiki.libsdl.org/SDL_SetSurfacePalette|SDL_SetSurfacePalette]].
3619
3620
3621<setter>(surface-rle-set! surface enable)</setter>
3622
3623See [[https://wiki.libsdl.org/SDL_SetSurfaceRLE|SDL_SetSurfaceRLE]].
3624
3625{{enable}} is #t to enable RLE acceleration or #f to disable it.
3626
3627
3628
3629==== Timer
3630
3631<procedure>(delay! milliseconds)</procedure>
3632
3633See [[https://wiki.libsdl.org/SDL_Delay|SDL_Delay]].
3634
3635'''NOTE:''' This will (probably) cause all CHICKEN threads to pause,
3636not only the thread that this is called from.
3637
3638
3639<procedure>(get-ticks) → fixnum</procedure>
3640
3641See [[https://wiki.libsdl.org/SDL_GetTicks|SDL_GetTicks]].
3642
3643
3644<procedure>(get-performance-counter) → fixnum</procedure>
3645
3646See [[https://wiki.libsdl.org/SDL_GetPerformanceCounter|SDL_GetPerformanceCounter]].
3647
3648
3649<procedure>(get-performance-frequency) → fixnum</procedure>
3650
3651See [[https://wiki.libsdl.org/SDL_GetPerformanceFrequency|SDL_GetPerformanceFrequency]].
3652
3653
3654<procedure>(ticks-passed? ticks-a ticks-b) → boolean</procedure>
3655
3656See [[https://wiki.libsdl.org/SDL_TICKS_PASSED|SDL_TICKS_PASSED]].
3657
3658Requires SDL 2.0.1 or higher. Signals an error if the compiled version
3659of SDL is not high enough. Use {{(version-at-least? 2 0 1)}} to
3660check before calling this procedure.
3661
3662
3663
3664==== Window
3665
3666<procedure>(create-window! title x y w h #!optional flags) → sdl2:window</procedure>
3667
3668See [[https://wiki.libsdl.org/SDL_CreateWindow|SDL_CreateWindow]].
3669
3670{{x}} and {{y}} can be integers, the symbol {{'centered}}, or the symbol {{'undefined}}.
3671
3672{{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):
3673
3674* {{'fullscreen}}
3675* {{'fullscreen-desktop}}
3676* {{'opengl}}
3677* {{'shown}}
3678* {{'hidden}}
3679* {{'borderless}}
3680* {{'resizable}}
3681* {{'minimized}}
3682* {{'maximized}}
3683* {{'input-grabbed}}
3684* {{'input-focus}}
3685* {{'mouse-focus}}
3686* {{'foreign}}
3687
3688
3689<procedure>(get-window-from-id id) → sdl2:window</procedure>
3690
3691See [[https://wiki.libsdl.org/SDL_GetWindowFromID|SDL_GetWindowFromID]].
3692
3693
3694<procedure>(destroy-window! window)</procedure>
3695
3696See [[https://wiki.libsdl.org/SDL_DestroyWindow|SDL_DestroyWindow]].
3697
3698
3699<procedure>(update-window-surface! window) → fixnum</procedure>
3700
3701See [[https://wiki.libsdl.org/SDL_UpdateWindowSurface|SDL_UpdateWindowSurface]].
3702
3703Returns zero if successful.
3704
3705
3706<procedure>(update-window-surface-rects! window rects) → fixnum</procedure>
3707
3708See [[https://wiki.libsdl.org/SDL_UpdateWindowSurfaceRects|SDL_UpdateWindowSurfaceRects]].
3709
3710{{rects}} must be a list of sdl2:rects.
3711
3712Returns zero if successful.
3713
3714
3715<procedure>(show-window! window)</procedure>
3716
3717See [[https://wiki.libsdl.org/SDL_ShowWindow|SDL_ShowWindow]].
3718
3719
3720<procedure>(hide-window! window)</procedure>
3721
3722See [[https://wiki.libsdl.org/SDL_HideWindow|SDL_HideWindow]].
3723
3724
3725<procedure>(maximize-window! window)</procedure>
3726
3727See [[https://wiki.libsdl.org/SDL_MaximizeWindow|SDL_MaximizeWindow]].
3728
3729
3730<procedure>(minimize-window! window)</procedure>
3731
3732See [[https://wiki.libsdl.org/SDL_MinimizeWindow|SDL_MinimizeWindow]].
3733
3734
3735<procedure>(raise-window! window)</procedure>
3736
3737See [[https://wiki.libsdl.org/SDL_RaiseWindow|SDL_RaiseWindow]].
3738
3739
3740<procedure>(restore-window! window)</procedure>
3741
3742See [[https://wiki.libsdl.org/SDL_RestoreWindow|SDL_RestoreWindow]].
3743
3744
3745<setter>(window-bordered-set! window bordered)</setter>
3746
3747See [[https://wiki.libsdl.org/SDL_SetWindowBordered|SDL_SetWindowBordered]].
3748
3749{{bordered}} is #t to enable window decoration or #f to disable window
3750decoration.
3751
3752(There is currently no getter.)
3753
3754
3755<procedure>(window-brightness window) → float</procedure>
3756
3757See [[https://wiki.libsdl.org/SDL_GetWindowBrightness|SDL_GetWindowBrightness]].
3758
3759
3760<setter>(set! (window-brightness window) brightness) → fixnum</setter>
3761<setter>(window-brightness-set! window brightness) → fixnum</setter>
3762
3763See [[https://wiki.libsdl.org/SDL_SetWindowBrightness|SDL_SetWindowBrightness]].
3764
3765Returns zero if successful.
3766
3767
3768<procedure>(window-display-index window) → fixnum</procedure>
3769
3770See [[https://wiki.libsdl.org/SDL_GetWindowDisplayIndex|SDL_GetWindowDisplayIndex]].
3771
3772
3773<procedure>(window-display-mode window) → sdl2:display-mode</procedure>
3774
3775See [[https://wiki.libsdl.org/SDL_GetWindowDisplayMode|SDL_GetWindowDisplayMode]].
3776
3777
3778<setter>(set! (window-display-mode surface) mode) → boolean</setter>
3779<setter>(window-display-mode-set! surface mode) → boolean</setter>
3780
3781TODO: Docs.
3782
3783
3784<procedure>(window-flags window) → list of symbols</procedure>
3785
3786See [[https://wiki.libsdl.org/SDL_GetWindowFlags|SDL_GetWindowFlags]].
3787
3788Returns a list of [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#window-flags|window flag symbols]].
3789
3790
3791<setter>(window-fullscreen-set! window mode)</setter>
3792
3793See [[https://wiki.libsdl.org/SDL_SetWindowFullscreen|SDL_SetWindowFullscreen]].
3794
3795{{mode}} can be:
3796
3797; 'fullscreen or #t : fullscreen
3798; 'fullscreen-desktop : fullscreen desktop
3799; #f : not fullscreen
3800
3801Returns zero if successful.
3802
3803
3804<procedure>(window-grab window) → boolean</procedure>
3805
3806See [[https://wiki.libsdl.org/SDL_GetWindowGrab|SDL_GetWindowGrab]].
3807
3808
3809<setter>(set! (window-grab window) grab?</setter>
3810<setter>(window-grab-set! window grab?)</setter>
3811
3812See [[https://wiki.libsdl.org/SDL_SetWindowGrab|SDL_SetWindowGrab]].
3813
3814
3815<setter>(window-icon-set! window icon-surface)</setter>
3816
3817See [[https://wiki.libsdl.org/SDL_SetWindowIcon|SDL_SetWindowIcon]].
3818
3819
3820<procedure>(window-id window) → fixnum</procedure>
3821
3822See [[https://wiki.libsdl.org/SDL_GetWindowID|SDL_GetWindowID]].
3823
3824
3825<procedure>(window-maximum-size window) → [width height]</procedure>
3826
3827See [[https://wiki.libsdl.org/SDL_GetWindowMaximumSize|SDL_GetWindowMaximumSize]].
3828
3829This procedure returns multiple values.
3830
3831
3832<setter>(set! (window-maximum-size window) size)</setter>
3833<setter>(window-maximum-size-set! window size)</setter>
3834
3835See [[https://wiki.libsdl.org/SDL_SetWindowMaximumSize|SDL_SetWindowMaximumSize]].
3836
3837{{size}} must be a list of integers {{(width height)}}.
3838
3839
3840<procedure>(window-minimum-size window) → [width height]</procedure>
3841
3842See [[https://wiki.libsdl.org/SDL_GetWindowMinimumSize|SDL_GetWindowMinimumSize]].
3843
3844This procedure returns multiple values.
3845
3846
3847<setter>(set! (window-minimum-size window) size)</setter>
3848<setter>(window-minimum-size-set! window size)</setter>
3849
3850See [[https://wiki.libsdl.org/SDL_SetWindowMinimumSize|SDL_SetWindowMinimumSize]].
3851
3852{{size}} must be a list of integers {{(width height)}}.
3853
3854
3855<procedure>(window-pixel-format window) → sdl2:pixel-format</procedure>
3856
3857See [[https://wiki.libsdl.org/SDL_GetWindowPixelFormat|SDL_GetWindowPixelFormat]].
3858
3859
3860<procedure>(window-position window) → [x y]</procedure>
3861
3862See [[https://wiki.libsdl.org/SDL_GetWindowPosition|SDL_GetWindowPosition]].
3863
3864This procedure returns multiple values.
3865
3866
3867<setter>(set! (window-position window) pos)</setter>
3868<setter>(window-position-set! window pos)</setter>
3869
3870See [[https://wiki.libsdl.org/SDL_SetWindowPosition|SDL_SetWindowPosition]].
3871
3872{{pos}} must be a list of integers {{(x y)}}.
3873
3874
3875<procedure>(window-size window) → [width height]</procedure>
3876
3877See [[https://wiki.libsdl.org/SDL_GetWindowSize|SDL_GetWindowSize]].
3878
3879This procedure returns multiple values.
3880
3881
3882<setter>(set! (window-size window) size)</setter>
3883<setter>(window-size-set! window size)</setter>
3884
3885See [[https://wiki.libsdl.org/SDL_SetWindowSize|SDL_SetWindowSize]].
3886
3887{{size}} must be a list of integers {{(width height)}}.
3888
3889
3890<procedure>(window-surface window) → sdl2:surface</procedure>
3891
3892See [[https://wiki.libsdl.org/SDL_GetWindowSurface|SDL_GetWindowSurface]].
3893
3894
3895<procedure>(window-title window) → string</procedure>
3896
3897See [[https://wiki.libsdl.org/SDL_GetWindowTitle|SDL_GetWindowTitle]].
3898
3899
3900<setter>(set! (window-title window) title)</setter>
3901<setter>(window-title-set! window title)</setter>
3902
3903See [[https://wiki.libsdl.org/SDL_SetWindowTitle|SDL_SetWindowTitle]].
Note: See TracBrowser for help on using the repository browser.