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

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

sdl2: Started documenting changes in 0.2.0 (hints and egg-version).

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