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

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

sdl2: Added docs about version feature identifiers.

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