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

Last change on this file since 33082 was 33082, checked in by John Croisant, 4 years ago

sdl2: Corrected and clarified Rect/Point? function docs.

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