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

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

sdl2: More 0.2.0 docs (renderer, miscellaneous).

File size: 175.5 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. Signals an error if the compiled version
2637of SDL is not high enough. Use {{(version-at-least? 2 0 2)}} to
2638check before calling this procedure.
2639
2640
2641<procedure>(gl-get-drawable-size window) → [width height]</procedure>
2642
2643See [[https://wiki.libsdl.org/SDL_GL_GetDrawableSize|SDL_GL_GetDrawableSize]].
2644
2645This procedure returns multiple values.
2646
2647Requires SDL 2.0.1 or higher. Signals an error if the compiled version
2648of SDL is not high enough. Use {{(version-at-least? 2 0 1)}} to
2649check before calling this procedure.
2650
2651
2652<procedure>(gl-swap-window!)</procedure>
2653
2654See [[https://wiki.libsdl.org/SDL_GL_SwapWindow|SDL_GL_SwapWindow]].
2655
2656
2657<procedure>(gl-swap-interval) → integer</procedure>
2658<setter>(set! (gl-swap-interval) interval)</setter>
2659<setter>(gl-set-swap-interval! interval)</setter>
2660
2661See [[https://wiki.libsdl.org/SDL_GL_GetSwapInterval|SDL_GL_GetSwapInterval]]
2662and [[https://wiki.libsdl.org/SDL_GL_SetSwapInterval|SDL_GL_SetSwapInterval]].
2663
2664The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
2665
2666
2667<procedure>(gl-extension-supported? name-string) → boolean</procedure>
2668
2669See [[https://wiki.libsdl.org/SDL_GL_ExtensionSupported|SDL_GL_ExtensionSupported]].
2670
2671
2672
2673==== sdl2:gl-context
2674
2675sdl2:gl-context is a record type that wraps a pointer to an SDL_GLContext struct.
2676
2677<procedure>(gl-context? obj) → boolean</procedure>
2678
2679Returns #t if {{obj}} is an sdl2:gl-context.
2680
2681
2682
2683=== Palette
2684
2685==== sdl2:palette
2686
2687sdl2:palette is a record type that wraps a pointer to an
2688[[https://wiki.libsdl.org/SDL_Palette|SDL_Palette]] struct.
2689
2690
2691<procedure>(palette? obj) → boolean</procedure>
2692
2693Returns #t if {{obj}} is an sdl2:palette.
2694
2695
2696<procedure>(make-palette #!optional ncolors) → sdl2:palette</procedure>
2697<procedure>(make-palette* #!optional ncolors) → sdl2:palette</procedure>
2698
2699Allocate and initialize a new sdl2:palette with the given number of colors.
2700See [[https://wiki.libsdl.org/SDL_AllocPalette|SDL_AllocPalette]].
2701
2702{{ncolors}} defaults to 256.
2703Common values are 2 (for a 1-bit surface), 16 (for a 4-bit surface), and 256 (for an 8-bit surface).
2704
2705'''NOTE:''' Usually you do not need to manually allocate a palette. A
2706palette will be created for you when you create a surface with a depth
2707of 8 or lower, and the palette will be automatically freed when the
2708surface is freed (unless the palette is still being used by other
2709surfaces).
2710
2711* {{make-palette}} returns a managed sdl2:palette.
2712* {{make-palette*}} returns an unmanaged sdl2:palette, which must be freed with {{free-palette!}} when you are done with it.
2713
2714Both procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
2715
2716
2717<procedure>(free-palette! palette)</procedure>
2718
2719Free the memory of the sdl2:palette's underlying struct. {{palette}}'s
2720pointer will be set to null (see {{struct-null?}}). It is safe to call
2721this procedure with managed or unmanaged sdl2:palettes. It is safe
2722(but has no effect) to free a struct record multiple times.
2723
2724See [[https://wiki.libsdl.org/SDL_FreePalette|SDL_FreePalette]].
2725
2726
2727<procedure>(palette-ncolors palette) → integer</procedure>
2728<procedure>(palette-ncolours palette) → integer</procedure>
2729
2730Returns the number of colors in the palette.
2731Common values are 2 (for a 1-bit surface), 16 (for a 4-bit surface), and 256 (for an 8-bit surface).
2732
2733
2734<procedure>(palette-ref palette i) → sdl2:color</procedure>
2735<setter>(set! (palette-ref palette i) color)</setter>
2736<setter>(palette-set! palette i color)</setter>
2737
2738{{palette-ref}} returns a copy of the color at the given index of the palette, as a managed sdl2:color.
2739
2740The setters set the given index of the palette to a copy of the given sdl2:color.
2741
2742These procedures signal an exception of kind {{(exn bounds)}} if the given index is out of bounds.
2743
2744
2745<procedure>(palette-colors palette) → vector of sdl2:colors </procedure>
2746<procedure>(palette-colours palette) → vector of sdl2:colors </procedure>
2747<setter>(set! (palette-colors palette) colors-vec) → boolean</setter>
2748<setter>(set! (palette-colours palette) colors-vec) → boolean</setter>
2749<setter>(palette-colors-set! colors-vec #!optional firstcolor) → boolean</setter>
2750<setter>(palette-colours-set! colors-vec #!optional firstcolor) → boolean</setter>
2751
2752{{palette-colors}} and {{palette-colours}} return copies of all colors in the palette, as a Scheme vector of managed sdl2:colors.
2753
2754The setters set multiple colors in the palette to copies of the given colors.
2755See [[https://wiki.libsdl.org/SDL_SetPaletteColors|SDL_SetPaletteColors]].
2756
2757{{colors-vec}} must be a Scheme vector of sdl2:colors.
2758
2759{{firstcolor}} specifies the first index of the palette to set.
2760I.e., palette index {{firstcolor}} will be set to the first color in {{colors-vec}},
2761palette index {{firstcolor + 1}} will be set to the second color, and so on.
2762{{firstcolor}} defaults to 0.
2763Signals an exception of kind {{(exn bounds)}} if {{firstcolor}} is out of bounds.
2764
2765The {{set!}} form cannot accept the {{firstcolor}} argument.
2766
2767The setters return #t if every color in {{colors-vec}} was used, or #f if some colors were not used,
2768e.g. because there were more colors in the vector than could fit in the palette.
2769
2770
2771
2772=== Pixel Format
2773
2774==== Pixel Format Functions
2775
2776<procedure>(map-rgb pixel-format r g b) → integer</procedure>
2777<procedure>(map-rgba pixel-format r g b a) → integer</procedure>
2778
2779See [[https://wiki.libsdl.org/SDL_MapRGB|SDL_MapRGB]]
2780and [[https://wiki.libsdl.org/SDL_MapRGBA|SDL_MapRGBA]].
2781
2782
2783<procedure>(get-rgb pixel pixel-format) → [r g b]</procedure>
2784<procedure>(get-rgba pixel pixel-format) → [r g b a]</procedure>
2785
2786See [[https://wiki.libsdl.org/SDL_GetRGB|SDL_GetRGB]]
2787and [[https://wiki.libsdl.org/SDL_GetRGBA|SDL_GetRGBA]].
2788
2789These procedures return multiple values.
2790
2791
2792<procedure>(pixel-format-enum-to-masks format-enum) → [bpp rmask gmask bmask amask]</procedure>
2793
2794See [[https://wiki.libsdl.org/SDL_PixelFormatEnumToMasks|SDL_PixelFormatEnumToMasks]].
2795
2796{{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.
2797
2798This procedure returns multiple values:
2799
2800; bpp   : The color depth (bits per pixel) of the format.
2801; rmask : The red mask of the format.
2802; gmask : The green mask of the format.
2803; bmask : The blue mask of the format.
2804; amask : The alpha mask of the format.
2805
2806Signals an exception of kind {{(exn sdl2)}} if conversion was not possible.
2807
2808
2809==== sdl2:pixel-format
2810
2811sdl2:pixel-format is a record type that wraps a pointer to an
2812[[https://wiki.libsdl.org/SDL_PixelFormat|SDL_PixelFormat]] struct.
2813
2814
2815<procedure>(pixel-format? obj) → boolean</procedure>
2816
2817Returns #t if {{obj}} is an sdl2:pixel-format.
2818
2819
2820<procedure>(make-pixel-format #!optional format) → sdl2:pixel-format</procedure>
2821<procedure>(make-pixel-format* #!optional format) → sdl2:pixel-format</procedure>
2822
2823Allocate and initialize a new sdl2:pixel-format with the given format.
2824
2825{{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.
2826See [[https://wiki.libsdl.org/SDL_AllocFormat|SDL_AllocFormat]].
2827
2828* {{make-pixel-format}} returns a managed sdl2:pixel-format.
2829* {{make-pixel-format*}} returns an unmanaged sdl2:pixel-format, which must be freed with {{free-pixel-format!}} when you are done with it.
2830
2831Both procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
2832
2833
2834<procedure>(free-pixel-format! pixel-format)</procedure>
2835
2836Free the memory of the sdl2:pixel-format's underlying struct.
2837{{pixel-format}}'s pointer will be set to null (see {{struct-null?}}).
2838It is safe to call this procedure with managed or unmanaged
2839sdl2:pixel-formats. It is safe (but has no effect) to free a struct
2840record multiple times.
2841
2842See [[https://wiki.libsdl.org/SDL_FreeFormat|SDL_FreeFormat]].
2843
2844
2845<procedure>(pixel-format-format pixel-format) → symbol</procedure>
2846<procedure>(pixel-format-format-raw pixel-format) → integer</procedure>
2847
2848Get the sdl2:pixel-format's "format" field.
2849
2850* {{pixel-format-format}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]].
2851* {{pixel-format-format-raw}} returns an integer.
2852
2853
2854<procedure>(pixel-format-palette pixel-format) → sdl2:palette or #f</procedure>
2855<setter>(set! (pixel-format-palette pixel-format) val)</setter>
2856<setter>(pixel-format-palette-set! pixel-format val)</setter>
2857
2858Get or set the sdl2:pixel-format's "palette" field, as an sdl2:palette, or #f if it does not have a palette.
2859Only sdl2:pixel-formats with bits-per-pixel of 8 or less can have a palette.
2860
2861See [[https://wiki.libsdl.org/SDL_SetPixelFormatPalette|SDL_SetPixelFormatPalette]].
2862
2863The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
2864
2865
2866<procedure>(pixel-format-bits-per-pixel pixel-format) → integer</procedure>
2867
2868Get the sdl2:pixel-format's "bits-per-pixel" field, as an integer.
2869Common values are 32, 24, 16, 15, 8, 4, and 1.
2870
2871
2872<procedure>(pixel-format-bytes-per-pixel pixel-format) → integer</procedure>
2873
2874Get the sdl2:pixel-format's "bits-per-pixel" field, as an integer.
2875Possible values are 4, 3, 2, and 1.
2876
2877
2878<procedure>(pixel-format-rmask pixel-format) → integer</procedure>
2879
2880Get the sdl2:pixel-format's "rmask" (red mask) field, as a nonnegative integer.
2881
2882
2883<procedure>(pixel-format-gmask pixel-format) → integer</procedure>
2884
2885Get the sdl2:pixel-format's "gmask" (green mask) field, as a nonnegative integer.
2886
2887
2888<procedure>(pixel-format-bmask pixel-format) → integer</procedure>
2889
2890Get the sdl2:pixel-format's "bmask" (blue mask) field, as a nonnegative integer.
2891
2892
2893<procedure>(pixel-format-amask pixel-format) → integer</procedure>
2894
2895Get the sdl2:pixel-format's "amask" (alpha mask) field, as a nonnegative integer.
2896It will be 0 if there is no alpha channel.
2897
2898
2899
2900=== Rect / Point
2901
2902==== Rect / Point Functions
2903
2904<procedure>(rect-empty? rect) → boolean</procedure>
2905
2906Returns #t if {{rect}}'s width and/or height is less than or equal to zero.
2907See [[https://wiki.libsdl.org/SDL_RectEmpty|SDL_RectEmpty]].
2908
2909
2910<procedure>(point-in-rect? point rect) → boolean</procedure>
2911
2912Returns #t if the sdl2:point is inside the sdl2:rect, or #f if it is not.
2913See [[https://wiki.libsdl.org/SDL_PointInRects|SDL_PointInRect]].
2914
2915This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
2916It requires '''SDL 2.0.4 or higher'''.
2917It signals an error if the compiled version of SDL is not high enough.
2918Use {{(version-at-least? 2 0 4)}} to check before calling this procedure.
2919
2920
2921<procedure>(enclose-points points #!optional clip result-rect) → [rect any-enclosed?]</procedure>
2922
2923See [[https://wiki.libsdl.org/SDL_EnclosePoints|SDL_EnclosePoints]].
2924
2925{{points}} must be a list of sdl2:points.
2926
2927{{clip}} must be either an sdl2:rect or #f (the default).
2928If {{clip}} is an sdl2:rect, points outside the clip rect will be ignored.
2929
2930If {{result-rect}} is omitted or #f, a new managed sdl2:rect will be returned.
2931If {{result-rect}} is an sdl2:rect, it will be modified and returned.
2932It is safe for {{result-rect}} to be the same object as {{clip}},
2933in which case {{clip}} will be modified and returned.
2934
2935This procedure returns multiple values:
2936
2937; rect : An sdl2:rect that encloses all matching points. This will be the same object as {{result-rect}}, if {{result-rect}} was specified.
2938; any-enclosed? : #t if any points were enclosed, or #f if all points were clipped
2939
2940
2941<procedure>(has-intersection? rect1 rect2) → boolean</procedure>
2942
2943Returns #t if {{rect1}} and {{rect2}} intersect, or #f if they do not.
2944See [[https://wiki.libsdl.org/SDL_HasIntersection|SDL_HasIntersection]].
2945
2946
2947<procedure>(intersect-rect rect1 rect2 #!optional result-rect) → [rect intersect?]</procedure>
2948
2949Calculates the intersection of {{rect1}} and {{rect2}}.
2950See [[https://wiki.libsdl.org/SDL_IntersectRect|SDL_IntersectRect]].
2951
2952If {{result-rect}} is omitted or #f, a new managed sdl2:rect will be returned.
2953If {{result-rect}} is an sdl2:rect, it will be modified and returned.
2954It is safe for {{result-rect}} to be the same object as {{rect1}} or {{rect2}},
2955in which case {{rect1}} or {{rect2}} will be modified and returned.
2956It is safe (but useless) for {{rect1}} and {{rect2}} to be the same object.
2957
2958This procedure returns multiple values:
2959
2960; 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.
2961; intersect? : #t if {{rect1}} and {{rect2}} intersect, otherwise #f
2962
2963
2964<procedure>(intersect-rect-and-line rect x1 y1 x2 y2) → [intersect? x1-new y1-new x2-new y2-new]</procedure>
2965
2966Calculates the intersection between {{rect}} and the line segment described by {{x1}}, {{y1}}, {{x2}}, and {{y2}}.
2967See [[https://wiki.libsdl.org/SDL_IntersectRectAndLine|SDL_IntersectRectAndLine]].
2968
2969{{rect}} must be an sdl2:rect.
2970{{x1}}, {{y1}}, {{x2}}, and {{y2}} should be integers.
2971
2972This procedure returns multiple values:
2973
2974; intersect? : #t if the line segment intersects with the rect, otherwise #f
2975; x1-new : integer x1 of the new line segment
2976; y1-new : integer y1 of the new line segment
2977; x2-new : integer x2 of the new line segment
2978; y2-new : integer y2 of the new line segment
2979
2980If the line segment does not intersect the rect, then {{intersect?}} will be #f,
2981and {{x1-new}}, {{y1-new}}, {{x2-new}}, and {{y2-new}} will be the same as the original arguments.
2982
2983
2984<procedure>(union-rect rect1 rect2 #!optional result-rect) → rect</procedure>
2985
2986See [[https://wiki.libsdl.org/SDL_UnionRect|SDL_UnionRect]].
2987
2988If {{result-rect}} is omitted or #f, a new managed sdl2:rect will be returned.
2989If {{result-rect}} is an sdl2:rect, it will be modified and returned.
2990It is safe for {{result-rect}} to be the same object as {{rect1}} or {{rect2}},
2991in which case {{rect1}} or {{rect2}} will be modified and returned.
2992It is safe (but useless) for {{rect1}} and {{rect2}} to be the same object.
2993
2994
2995
2996==== sdl2:rect
2997
2998sdl2:rect is a record type that wraps a pointer to an
2999[[https://wiki.libsdl.org/SDL_Rect|SDL_Rect]] struct.
3000
3001
3002<procedure>(rect? obj) → boolean</procedure>
3003
3004Returns #t if {{obj}} is an sdl2:rect.
3005
3006
3007<procedure>(make-rect #!optional x y w h) → sdl2:rect</procedure>
3008<procedure>(make-rect* #!optional x y w h) → sdl2:rect</procedure>
3009
3010Allocate and initialize a new sdl2:rect.
3011
3012{{x}}, {{y}}, {{w}}, and {{h}} must be integers in the range -2147483648 to 2147483647 (inclusive).
3013They all default to 0.
3014
3015* {{make-rect}} returns a managed sdl2:rect.
3016* {{make-rect*}} returns an unmanaged sdl2:rect, which must be freed with {{free-rect!}} when you are done with it.
3017
3018
3019<procedure>(free-rect! rect)</procedure>
3020
3021Free the memory of the sdl2:rect's underlying struct. {{rect}}'s
3022pointer will be set to null (see {{struct-null?}}). It is safe to call
3023this procedure with managed or unmanaged sdl2:rects. It is safe (but
3024has no effect) to free a struct record multiple times.
3025
3026
3027<procedure>(rect-x rect) → integer</procedure>
3028<setter>(set! (rect-x rect) val)</setter>
3029<setter>(rect-x-set! rect val)</setter>
3030
3031Get or set the sdl2:rect's "x" field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3032
3033
3034<procedure>(rect-y rect) → integer</procedure>
3035<setter>(set! (rect-y rect) val)</setter>
3036<setter>(rect-y-set! rect val)</setter>
3037
3038Get or set the sdl2:rect's "y" field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3039
3040
3041<procedure>(rect-w rect) → integer</procedure>
3042<setter>(set! (rect-w rect) val)</setter>
3043<setter>(rect-w-set! rect val)</setter>
3044
3045Get or set the sdl2:rect's "w" (width) field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3046
3047
3048<procedure>(rect-h rect) → integer</procedure>
3049<setter>(set! (rect-h rect) val)</setter>
3050<setter>(rect-h-set! rect val)</setter>
3051
3052Get or set the sdl2:rect's "h" (height) field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3053
3054
3055<procedure>(rect-set! rect #!optional x y w h) → rect</procedure>
3056
3057Convenient way of setting multiple fields of the sdl2:rect.
3058Any arguments that are {{#f}} will cause no change to that field.
3059E.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.
3060Returns {{rect}} after it is modified.
3061
3062
3063<procedure>(rect->list rect) → list of integers</procedure>
3064
3065Returns a list {{(x y w h)}} containing the value of each field of the sdl2:rect.
3066
3067
3068<procedure>(rect->values rect) → [x y w h]</procedure>
3069
3070Returns multiple values containing the value of each field of the sdl2:rect.
3071This is useful for destructuring an sdl2:rect using {{receive}} or {{let-values}}.
3072
3073
3074<procedure>(rect=? rect1 rect2) → boolean</procedure>
3075
3076Efficiently compare two sdl2:rects.
3077Returns #t if the value of every field in {{rect1}} is equal to the value of the corresponding field in {{rect2}}.
3078See [[https://wiki.libsdl.org/SDL_RectEquals|SDL_RectEquals]].
3079
3080
3081<procedure>(copy-rect rect) → sdl2:rect</procedure>
3082<procedure>(copy-rect* rect) → sdl2:rect</procedure>
3083
3084Efficiently copy the given sdl2:rect, returning a new sdl2:rect with the same values.
3085
3086* {{copy-rect}} returns a managed sdl2:rect.
3087* {{copy-rect*}} returns an unmanaged sdl2:rect, which must be freed with {{free-rect!}} when you are done with it.
3088
3089
3090
3091==== sdl2:point
3092
3093sdl2:point is a record type that wraps a pointer to an
3094[[https://wiki.libsdl.org/SDL_Point|SDL_Point]] struct.
3095
3096
3097<procedure>(point? obj) → boolean</procedure>
3098
3099Returns #t if {{obj}} is an sdl2:point.
3100
3101
3102<procedure>(make-point #!optional x y) → sdl2:point</procedure>
3103<procedure>(make-point* #!optional x y) → sdl2:point</procedure>
3104
3105Allocate and initialize a new sdl2:point.
3106
3107{{x}} and {{y}} must be integers in the range -2147483648 to 2147483647 (inclusive).
3108They both default to 0.
3109
3110* {{make-point}} returns a managed sdl2:point.
3111* {{make-point*}} returns an unmanaged sdl2:point, which must be freed with {{free-point!}} when you are done with it.
3112
3113
3114<procedure>(free-point! point)</procedure>
3115
3116Free the memory of the sdl2:point's underlying struct. {{point}}'s
3117pointer will be set to null (see {{struct-null?}}). It is safe to call
3118this procedure with managed or unmanaged sdl2:points. It is safe (but
3119has no effect) to free a struct record multiple times.
3120
3121
3122<procedure>(point-x point) → integer</procedure>
3123<setter>(set! (point-x point) val)</setter>
3124<setter>(point-x-set! point val)</setter>
3125
3126Get or set the sdl2:point's "x" field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3127
3128
3129<procedure>(point-y point) → integer</procedure>
3130<setter>(set! (point-y point) val)</setter>
3131<setter>(point-y-set! point val)</setter>
3132
3133Get or set the sdl2:point's "y" field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3134
3135
3136<procedure>(point-set! point #!optional x y) → point</procedure>
3137
3138Convenient way of setting multiple fields of the sdl2:point.
3139Any arguments that are {{#f}} will cause no change to that field.
3140E.g. {{(point-set! my-point 42 #f)}} will set the "x" field to 42, but will not change the "y" field.
3141Returns {{point}} after it is modified.
3142
3143
3144<procedure>(point->list point) → list of integers</procedure>
3145
3146Returns a list {{(x y)}} containing the value of each field of the sdl2:point.
3147
3148
3149<procedure>(point->values point) → [x y]</procedure>
3150
3151Returns multiple values containing the value of each field of the sdl2:point.
3152This is useful for destructuring an sdl2:point using {{receive}} or {{let-values}}.
3153
3154
3155<procedure>(point=? point1 point2) → boolean</procedure>
3156
3157Efficiently compare two sdl2:points.
3158Returns #t if the value of every field in {{point1}} is equal to the value of the corresponding field in {{point2}}.
3159
3160
3161<procedure>(copy-point point) → sdl2:point</procedure>
3162<procedure>(copy-point* point) → sdl2:point</procedure>
3163
3164Efficiently copy the given sdl2:point, returning a new sdl2:point with the same values.
3165
3166* {{copy-point}} returns a managed sdl2:point.
3167* {{copy-point*}} returns an unmanaged sdl2:point, which must be freed with {{free-point!}} when you are done with it.
3168
3169
3170
3171=== Renderer
3172
3173Renderer is one part of [[https://wiki.libsdl.org/CategoryRender|2D Accelerated Rendering]].
3174See also [[#texture|Texture]].
3175
3176Renderer support is available in '''sdl2 egg 0.2.0 and higher'''.
3177
3178
3179==== Renderer Functions
3180
3181<procedure>(create-renderer! window index #!optional flags) → sdl2:renderer</procedure>
3182
3183See [[https://wiki.libsdl.org/SDL_CreateRenderer|SDL_CreateRenderer]].
3184This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3185
3186
3187<procedure>(create-software-renderer! surface) → sdl2:renderer</procedure>
3188
3189See [[https://wiki.libsdl.org/SDL_CreateSoftwareRenderer|SDL_CreateSoftwareRenderer]].
3190This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3191
3192
3193<procedure>(destroy-renderer! renderer)</procedure>
3194
3195See [[https://wiki.libsdl.org/SDL_DestroyRenderer|SDL_DestroyRenderer]].
3196This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3197
3198
3199<procedure>(create-window-and-renderer! width height #!optional window-flags) → [window renderer]</procedure>
3200
3201See [[https://wiki.libsdl.org/SDL_CreateWindowAndRenderer|SDL_CreateWindowAndRenderer]].
3202This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3203
3204{{width}} and {{height}} specify the height of the window to create.
3205
3206{{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).
3207
3208This procedure returns multiple values:
3209
3210; window : The sdl2:window that was created.
3211; renderer : The sdl2:renderer that was created.
3212
3213
3214<procedure>(get-renderer window) → sdl2:renderer</procedure>
3215
3216See [[https://wiki.libsdl.org/SDL_GetRenderer|SDL_GetRenderer]].
3217This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3218
3219Signals an exception of kind {{(exn sdl2)}} if the window does not have a renderer,
3220or if an error occurs.
3221
3222
3223<procedure>(get-renderer-info renderer) → sdl2:renderer-info</procedure>
3224<procedure>(get-renderer-info* renderer) → sdl2:renderer-info</procedure>
3225
3226See [[https://wiki.libsdl.org/SDL_GetRendererInfo|SDL_GetRendererInfo]].
3227These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3228
3229* {{get-renderer-info}} returns a managed sdl2:renderer-info.
3230* {{get-renderer-info*}} returns an unmanaged sdl2:renderer-info, which must be freed using {{free-renderer-info!}} when you are done with it.
3231
3232
3233<procedure>(num-render-drivers) → integer</procedure>
3234
3235See [[https://wiki.libsdl.org/SDL_GetNumRenderDrivers|SDL_GetNumRenderDrivers]].
3236This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3237
3238
3239<procedure>(render-driver-info index) → sdl2:renderer-info</procedure>
3240
3241See [[https://wiki.libsdl.org/SDL_GetRenderDriverInfo|SDL_GetRenderDriverInfo]].
3242This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3243
3244
3245<procedure>(render-present!)</procedure>
3246
3247See [[https://wiki.libsdl.org/SDL_RenderPresent|SDL_RenderPresent]].
3248This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3249
3250
3251<procedure>(render-copy! renderer texture #!optional srcrect dstrect) → </procedure>
3252
3253See [[https://wiki.libsdl.org/SDL_RenderCopy|SDL_RenderCopy]].
3254This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3255
3256
3257<procedure>(render-copy-ex! renderer texture #!optional srcrect dstrect angle center flip)</procedure>
3258
3259See [[https://wiki.libsdl.org/SDL_RenderCopyEx|SDL_RenderCopyEx]].
3260This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3261
3262
3263<procedure>(render-target-supported? renderer) → boolean</procedure>
3264
3265See [[https://wiki.libsdl.org/SDL_RenderTargetSupported|SDL_RenderTargetSupported]].
3266This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3267
3268
3269<procedure>(render-target renderer) → sdl2:texture or #f</procedure>
3270<setter>(render-target-set! renderer target)</setter>
3271<setter>(set! (render-target renderer) target)</setter>
3272
3273See [[https://wiki.libsdl.org/SDL_GetRenderTarget|SDL_GetRenderTarget]]
3274and [[https://wiki.libsdl.org/SDL_SetRenderTarget|SDL_SetRenderTarget]].
3275These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3276
3277
3278<procedure>(render-read-pixels-raw renderer rect format pixels-out pitch)</procedure>
3279
3280See [[https://wiki.libsdl.org/SDL_RenderReadPixels|SDL_RenderReadPixels]].
3281This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3282
3283
3284<procedure>(render-draw-blend-mode renderer) → symbol</procedure>
3285<procedure>(render-draw-blend-mode-raw renderer) → integer</procedure>
3286<setter>(render-draw-blend-mode-set! renderer mode)</setter>
3287<setter>(set! (render-draw-blend-mode renderer) mode)</setter>
3288
3289Get or set the renderer's draw blend mode. This affects future drawing operations.
3290See [[https://wiki.libsdl.org/SDL_GetRenderDrawBlendMode|SDL_GetRenderDrawBlendMode]]
3291and [[https://wiki.libsdl.org/SDL_SetRenderDrawBlendMode|SDL_SetRenderDrawBlendMode]].
3292These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3293
3294* {{render-draw-blend-mode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-mode|blend mode symbol]]:
3295** {{'none}}
3296** {{'blend}}
3297** {{'add}}
3298** {{'mod}}
3299* {{render-draw-blend-mode-raw}} returns an integer.
3300* The setters accept either a symbol or integer.
3301
3302
3303<procedure>(render-draw-color renderer) → sdl2:color</procedure>
3304<procedure>(render-draw-colour renderer) → sdl2:color</procedure>
3305<setter>(render-draw-color-set! renderer color)</setter>
3306<setter>(render-draw-colour-set! renderer color)</setter>
3307<setter>(set! (render-draw-color renderer) color)</setter>
3308<setter>(set! (render-draw-colour renderer) color)</setter>
3309
3310Get or set the renderer's draw color. This affects future drawing operations.
3311See [[https://wiki.libsdl.org/SDL_GetRenderDrawColor|SDL_GetRenderDrawColor]]
3312and [[https://wiki.libsdl.org/SDL_SetRenderDrawColor|SDL_SetRenderDrawColor]].
3313These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3314
3315
3316<procedure>(render-clear! renderer)</procedure>
3317
3318Clear the entire renderer, using the renderer's current draw color.
3319See [[https://wiki.libsdl.org/SDL_RenderClear|SDL_RenderClear]].
3320This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3321
3322
3323<procedure>(render-draw-line! renderer x1 y1 x2 y2)</procedure>
3324<procedure>(render-draw-lines! renderer points)</procedure>
3325
3326Draw a line segment or multiple connected line segments, using the renderer's current draw color and blend mode.
3327See [[https://wiki.libsdl.org/SDL_RenderDrawLine|SDL_RenderDrawLine]]
3328and [[https://wiki.libsdl.org/SDL_RenderDrawLines|SDL_RenderDrawLines]].
3329These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3330
3331* {{render-draw-line!}} draws a single line segment.
3332* {{render-draw-lines!}} draws multiple connected line segments. {{points}} must be a list or vector of sdl2:point instances.
3333
3334
3335<procedure>(render-draw-point! renderer x y)</procedure>
3336<procedure>(render-draw-points! renderer points)</procedure>
3337
3338Draw one or multiple points, using the renderer's current draw color and blend mode.
3339See [[https://wiki.libsdl.org/SDL_RenderDrawPoint|SDL_RenderDrawPoint]]
3340and [[https://wiki.libsdl.org/SDL_RenderDrawPoints|SDL_RenderDrawPoints]].
3341These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3342
3343* {{render-draw-point!}} draws a single point.
3344* {{render-draw-points!}} draws multiple points. {{points}} must be a list or vector of sdl2:point instances.
3345
3346
3347<procedure>(render-draw-rect! renderer rect)</procedure>
3348<procedure>(render-draw-rects! renderer rects)</procedure>
3349
3350Draw one or multiple outlined rectangles, using the renderer's current draw color and blend mode.
3351See [[https://wiki.libsdl.org/SDL_RenderDrawRect|SDL_RenderDrawRect]]
3352and [[https://wiki.libsdl.org/SDL_RenderDrawRects|SDL_RenderDrawRects]].
3353These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3354
3355* {{render-draw-rect!}} draws a single outlined rect.
3356* {{render-draw-rects!}} draws multiple outlined rects. {{rects}} must be a list or vector of sdl2:rect instances.
3357
3358
3359<procedure>(render-fill-rect! renderer rect)</procedure>
3360<procedure>(render-fill-rects! renderer rects)</procedure>
3361
3362Draw one or multiple filled rectangles, using the renderer's current draw color and blend mode.
3363See [[https://wiki.libsdl.org/SDL_RenderFillRect|SDL_RenderFillRect]]
3364and [[https://wiki.libsdl.org/SDL_RenderFillRects|SDL_RenderFillRects]].
3365These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3366
3367* {{render-draw-rect!}} draws a single filled rect.
3368* {{render-draw-rects!}} draws multiple filled rects. {{rects}} must be a list or vector of sdl2:rect instances.
3369
3370
3371==== sdl2:renderer
3372
3373sdl2:renderer is a record type that wraps a pointer to an SDL_Renderer struct.
3374sdl2:renderer is available in '''sdl2 egg version 0.2.0 and higher'''.
3375
3376
3377<procedure>(renderer? obj) → boolean</procedure>
3378
3379Returns #t if {{obj}} is an sdl2:renderer.
3380This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3381
3382
3383<procedure>(renderer-output-size renderer) → [w h]</procedure>
3384
3385See [[https://wiki.libsdl.org/SDL_GetRendererOutputSize|SDL_GetRendererOutputSize]].
3386This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3387
3388This procedure returns multiple values, the output width and height, as integers.
3389
3390
3391<procedure>(render-clip-rect renderer) → sdl2:rect</procedure>
3392<setter>(render-clip-rect-set! renderer rect)</setter>
3393<setter>(set! (render-clip-rect renderer) rect)</setter>
3394
3395Get or set the sdl2:renderer's clip rect.
3396See [[https://wiki.libsdl.org/SDL_RenderGetClipRect|SDL_RenderGetClipRect]]
3397and [[https://wiki.libsdl.org/SDL_RenderSetClipRect|SDL_RenderSetClipRect]].
3398These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3399
3400{{render-clip-rect}} returns a new managed sdl2:rect describing the renderer's clip rect.
3401Returns {{#<sdl2:rect (0 0 0 0)>}} if clipping is disabled.
3402
3403But, be aware that it also returns {{#<sdl2:rect (0 0 0 0)>}} if that is the current clip rect.
3404Use {{render-clip-enabled?}} (in SDL 2.0.4 or higher) to unambiguously check whether clipping is enabled or disabled.
3405
3406The setters accept either an sdl2:rect to enable clipping and set the clip rect,
3407or #f to disable clipping.
3408
3409
3410<procedure>(render-clip-enabled? renderer) → boolean</procedure>
3411
3412Returns #t if clipping is enabled for the given sdl2:renderer,
3413or #f is clipping is disabled.
3414See [[https://wiki.libsdl.org/SDL_RenderIsClipEnabled|SDL_RenderIsClipEnabled]].
3415
3416This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3417It requires '''SDL 2.0.4 or higher'''.
3418It signals an error if the compiled version of SDL is not high enough.
3419Use {{(version-at-least? 2 0 4)}} to check before calling this procedure.
3420
3421
3422<procedure>(render-logical-size renderer) → [w h]</procedure>
3423<setter>(render-logical-size-set! renderer size)</setter>
3424<setter>(set! (render-logical-size renderer) size)</setter>
3425
3426Get or set the renderer's logical size.
3427See [[https://wiki.libsdl.org/SDL_RenderGetLogicalSize|SDL_RenderGetLogicalSize]]
3428and [[https://wiki.libsdl.org/SDL_RenderSetLogicalSize|SDL_RenderSetLogicalSize]].
3429These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3430
3431* {{render-logical-size}} returns multiple values, the logical width and height, as integers.
3432* The setters accept a list {{(w h)}} containing the new logical width and height, as integers.
3433
3434
3435<procedure>(render-scale renderer) → [x-scale y-scale]</procedure>
3436<setter>(render-scale-set! renderer scales)</setter>
3437<setter>(set! (render-scale-set! renderer) scales)</setter>
3438
3439Get or set the sdl2:renderer's x and y scaling factors.
3440See [[https://wiki.libsdl.org/SDL_RenderGetScale|SDL_RenderGetScale]]
3441and [[https://wiki.libsdl.org/SDL_RenderSetScale|SDL_RenderSetScale]].
3442These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3443
3444* {{render-scale}} returns multiple values, the x and y scaling factors, as integers..
3445* The setters accept a list {{(x-scale y-scale)}} containing the new scaling factors, as integers.
3446
3447
3448<procedure>(render-viewport renderer) → sdl2:rect</procedure>
3449<setter>(render-viewport-set! renderer rect)</setter>
3450<setter>(set! (render-viewport renderer) rect)</setter>
3451
3452Get or set the renderer's viewport.
3453See [[https://wiki.libsdl.org/SDL_RenderGetViewport|SDL_RenderGetViewport]]
3454and [[https://wiki.libsdl.org/SDL_RenderSetViewport|SDL_RenderSetViewport]].
3455These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3456
3457
3458
3459==== sdl2:renderer-info
3460
3461sdl2:renderer-info is a record type that wraps a pointer to an
3462[[https://wiki.libsdl.org/SDL_RendererInfo|SDL_RendererInfo]] struct.
3463sdl2:renderer-info is available in '''sdl2 egg version 0.2.0 and higher'''.
3464
3465<procedure>(renderer-info? obj) → boolean</procedure>
3466
3467Returns #t if {{obj}} is an sdl2:renderer-info.
3468This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3469
3470
3471<procedure>(free-renderer-info! renderer-info)</procedure>
3472
3473Free the memory of the sdl2:renderer-info's underlying struct.
3474{{renderer-info}}'s pointer will be set to null (see {{struct-null?}}).
3475It is safe to call this procedure with managed or unmanaged sdl2:renderer-infos.
3476It is safe (but has no effect) to free a struct record multiple times.
3477This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3478
3479
3480<procedure>(renderer-info-name renderer-info) → string</procedure>
3481
3482Get the sdl2:renderer-info's "name" field, as a string.
3483This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3484
3485
3486<procedure>(renderer-info-flags renderer-info) → list of symbols</procedure>
3487<procedure>(renderer-info-flags-raw renderer-info) → integer</procedure>
3488
3489Get the sdl2:renderer-info's "flags" field, as a list of symbols or an integer.
3490TODO: Link to flags enums.
3491These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3492
3493
3494<procedure>(renderer-info-num-texture-formats renderer-info) → integer</procedure>
3495
3496Get the sdl2:renderer-info's "num-texture-formats" field, as an integer.
3497This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3498
3499
3500<procedure>(renderer-info-texture-formats renderer-info) → list of symbols</procedure>
3501
3502Get the sdl2:renderer-info's "texture-formats" field,
3503as a list of [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbols]].
3504This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3505
3506
3507<procedure>(renderer-info-max-texture-width renderer-info) → integer</procedure>
3508
3509Get the sdl2:renderer-info's "max-texture-width" field, as an integer.
3510This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3511
3512
3513<procedure>(renderer-info-max-texture-height renderer-info) → integer</procedure>
3514
3515Get the sdl2:renderer-info's "max-texture-height" field, as an integer.
3516This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3517
3518
3519
3520=== RWops
3521
3522==== RWops Functions
3523
3524<procedure>(rw-from-file filepath) → sdl2:rwops</procedure>
3525
3526See [[https://wiki.libsdl.org/SDL_RWFromFile|SDL_RWFromFile]].
3527
3528You should close the sdl2:rwops when you are done with it, using
3529{{rw-close!}} or one of the procedures that can automatically close
3530the sdl2:rwops, such as {{load-bmp-rw}}.
3531
3532Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3533
3534
3535<procedure>(rw-from-const-mem pointer) → sdl2:rwops</procedure>
3536
3537See [[https://wiki.libsdl.org/SDL_RWFromConstMem|SDL_RWFromConstMem]].
3538
3539You should close the sdl2:rwops when you are done with it, using
3540{{rw-close!}} or one of the procedures that can automatically close
3541the sdl2:rwops, such as {{load-bmp-rw}}.
3542
3543Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3544
3545
3546<procedure>(rw-from-mem pointer) → sdl2:rwops</procedure>
3547
3548See [[https://wiki.libsdl.org/SDL_RWFromMem|SDL_RWFromMem]].
3549
3550You should close the sdl2:rwops when you are done with it, using
3551{{rw-close!}} or one of the procedures that can automatically close
3552the sdl2:rwops, such as {{load-bmp-rw}}.
3553
3554Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3555
3556
3557<procedure>(rw-from-blob blob) → sdl2:rwops</procedure>
3558
3559Create a new sdl2:rwops that accesses the memory of the given
3560[[http://wiki.call-cc.org/manual/Unit%20library#blobs|blob]]. You
3561should close the sdl2:rwops when you are done with it, using
3562{{rw-close!}} or one of the procedures that can automatically close
3563the sdl2:rwops, such as {{load-bmp-rw}}.
3564
3565Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3566
3567You can also use this procedure to create a sdl2:rwops from a
3568[[/manual/Unit srfi-4|SRFI-4]] numeric vector, by first converting it
3569to a blob using e.g. {{u8vector->blob/shared}}.
3570
3571'''CAUTION:''' Creating a sdl2:rwops from a blob in CHICKEN-managed
3572memory is unstable: the blob might be garbage collected or moved in
3573memory, which would break the sdl2:rwops. To be safe, you should
3574[[/manual/Unit lolevel#object-evict|evict]] the blob and create the
3575sdl2:rwops from the evicted blob (not the original). You may wish to
3576[[/manual/Unit lolevel#object-release|release]] the evicted blob after
3577you have closed the sdl2:rwops. Example:
3578
3579<enscript highlight="scheme">
3580(let* ((evicted-blob (object-evict '#${...}))
3581       (rwops (sdl2:rw-from-blob evicted-blob))
3582       (surf (sdl2:load-bmp-rw rwops #t)))
3583  (object-release evicted-blob)
3584  surf)
3585</enscript>
3586
3587
3588<procedure>(rw-from-string str) → sdl2:rwops</procedure>
3589
3590Create a new sdl2:rwops that accesses the memory of the given CHICKEN
3591Scheme string. You should close the sdl2:rwops when you are done with
3592it, using {{rw-close!}} or one of the procedures that can
3593automatically close the sdl2:rwops, such as {{load-bmp-rw}}.
3594
3595Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3596
3597'''CAUTION:''' Creating a sdl2:rwops from a string in CHICKEN-managed
3598memory is unstable: the string might be garbage collected or moved in
3599memory, which would break the sdl2:rwops. To be safe, you should
3600[[/manual/Unit lolevel#object-evict|evict]] the string and create the
3601sdl2:rwops from the evicted string (not the original). You may wish to
3602[[/manual/Unit lolevel#object-release|release]] the evicted string
3603after you have closed the sdl2:rwops. Example:
3604
3605<enscript highlight="scheme">
3606(let* ((evicted-string (object-evict "..."))
3607       (rwops (sdl2:rw-from-string evicted-string))
3608       (surf (sdl2:load-bmp-rw rwops #t)))
3609  (object-release evicted-string)
3610  surf)
3611</enscript>
3612
3613
3614<procedure>(rw-close! rwops)</procedure>
3615
3616See [[https://wiki.libsdl.org/SDL_RWclose|SDL_RWclose]].
3617
3618Close and clean up the given sdl2:rwops. This frees the memory used by
3619the SDL_RWops struct itself, but does not free or release the pointer,
3620blob, or string that the sdl2:rwops was reading/writing from. (It does
3621close files opened with {{rw-from-file}}, though.)
3622
3623Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3624
3625
3626==== sdl2:rwops
3627
3628sdl2:rwops is a record type that wraps a pointer to an
3629[[https://wiki.libsdl.org/SDL_RWops|SDL_RWops]] struct.
3630
3631
3632<procedure>(rwops? obj) → boolean</procedure>
3633
3634Returns #t if {{obj}} is an sdl2:rwops.
3635
3636
3637<procedure>(rwops-type rwops) → symbol</procedure>
3638<procedure>(rwops-type-raw rwops) → integer</procedure>
3639
3640Get the sdl2:rwops' "type" field, indicating the data source type.
3641
3642* {{rwops-type}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#rwops-types|RWops type symbol]]:
3643** {{'unknown}}
3644** {{'win-file}}
3645** {{'std-file}}
3646** {{'jni-file}}
3647** {{'memory}}
3648** {{'memory-ro}}
3649* {{rwops-type-raw}} returns an integer.
3650
3651
3652
3653=== Surface
3654
3655==== Surface Functions
3656
3657<procedure>(create-rgb-surface* flags width height depth rmask gmask bmask amask) → sdl2:surface</procedure>
3658
3659See [[https://wiki.libsdl.org/SDL_CreateRGBSurface|SDL_CreateRGBSurface]].
3660
3661Returns a new '''unmanaged''' sdl2:surface with the given properties.
3662You must call {{free-surface!}} when you are done with it.
3663
3664See {{make-surface}} for a more convenient interface.
3665
3666Signals an exception of kind {{(exn sdl2)}} if the surface cannot be created.
3667
3668
3669<procedure>(create-rgb-surface-from* pixels width height depth pitch rmask gmask bmask amask) → sdl2:surface</procedure>
3670
3671Returns a new '''unmanaged''' sdl2:surface with the given properties,
3672using existing pixel data (a pointer, e.g. from {{surface-pixels-raw}}).
3673You must call {{free-surface!}} when you are done with it.
3674
3675See [[https://wiki.libsdl.org/SDL_CreateRGBSurfaceFrom|SDL_CreateRGBSurfaceFrom]].
3676
3677Signals an exception of kind {{(exn sdl2)}} if the surface cannot be created.
3678
3679
3680<procedure>(convert-surface surface pixel-format) → sdl2:surface</procedure>
3681<procedure>(convert-surface* surface pixel-format) → sdl2:surface</procedure>
3682
3683Creates a copy of the given sdl2:surface, but converts it to the given sdl2:pixel-format.
3684
3685See [[https://wiki.libsdl.org/SDL_ConvertSurface|SDL_ConvertSurface]].
3686
3687* {{convert-surface}} returns a managed sdl2:surface.
3688* {{convert-surface*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
3689
3690Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3691
3692
3693<procedure>(load-bmp  filepath) → sdl2:surface</procedure>
3694<procedure>(load-bmp* filepath) → sdl2:surface</procedure>
3695
3696See [[https://wiki.libsdl.org/SDL_LoadBMP|SDL_LoadBMP]].
3697
3698Attempts to load a BMP image file.
3699Returns a sdl2:surface containing the image data.
3700Signals an exception of kind {{(exn sdl2)}} if the image could not be loaded.
3701
3702'''NOTE:''' This procedure only supports certain kinds of BMP image.
3703Use the [[/egg/sdl2-image|sdl2-image egg]] for better BMP support,
3704plus support for loading other image formats like JPG, PNG, and GIF.
3705
3706* {{load-bmp}} returns a managed sdl2:surface.
3707* {{load-bmp*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
3708
3709
3710<procedure>(load-bmp-rw  rwops #!optional close?) → sdl2:surface</procedure>
3711<procedure>(load-bmp-rw* rwops #!optional close?) → sdl2:surface</procedure>
3712
3713See [[https://wiki.libsdl.org/SDL_LoadBMP_RW|SDL_LoadBMP_RW]].
3714
3715Attempts to load a BMP image from the given sdl2:rwops.
3716Returns a sdl2:surface containing the image data.
3717Signals an exception of kind {{(exn sdl2)}} if the image could not be loaded.
3718
3719If {{close?}} is #t, {{rwops}} will be automatically closed (see
3720{{rw-close!}}) after the image is loaded. If {{close?}} is #f or
3721omitted, {{rwops}} will not be closed.
3722
3723'''NOTE:''' This procedure only supports certain kinds of BMP image.
3724Use the [[/egg/sdl2-image|sdl2-image egg]] for better BMP support,
3725plus support for loading other image formats like JPG, PNG, and GIF.
3726
3727* {{load-bmp-rw}} returns a managed sdl2:surface.
3728* {{load-bmp-rw*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
3729
3730
3731<procedure>(save-bmp! surface filepath)</procedure>
3732
3733See [[https://wiki.libsdl.org/SDL_SaveBMP|SDL_SaveBMP]].
3734
3735Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3736
3737
3738<procedure>(save-bmp-rw! surface rwops #!optional close?)</procedure>
3739
3740See [[https://wiki.libsdl.org/SDL_SaveBMP_RW|SDL_SaveBMP_RW]].
3741
3742If {{close?}} is #t, {{rwops}} will be automatically closed (see
3743{{rw-close!}}) after the image is loaded. If {{close?}} is #f or
3744omitted, {{rwops}} will not be closed.
3745
3746Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3747
3748
3749<procedure>(lock-surface! surface)</procedure>
3750<procedure>(unlock-surface! surface)</procedure>
3751
3752See [[https://wiki.libsdl.org/SDL_LockSurface|SDL_LockSurface]]
3753and [[https://wiki.libsdl.org/SDL_UnlockSurface|SDL_UnlockSurface]].
3754
3755{{lock-surface!}} signals an exception of kind {{(exn sdl2)}} if an error occurs.
3756
3757
3758<procedure>(must-lock? surface) → boolean</procedure>
3759
3760See [[https://wiki.libsdl.org/SDL_MUSTLOCK|SDL_MUSTLOCK]].
3761
3762
3763<procedure>(blit-surface! src src-rect dest dest-rect)</procedure>
3764
3765See [[https://wiki.libsdl.org/SDL_BlitSurface|SDL_BlitSurface]].
3766
3767May modify dest-rect.
3768
3769Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3770
3771
3772<procedure>(blit-scaled! src src-rect dest dest-rect)</procedure>
3773
3774See [[https://wiki.libsdl.org/SDL_BlitScaled|SDL_BlitScaled]].
3775
3776May modify dest-rect.
3777
3778Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3779
3780
3781<procedure>(fill-rect! surface rect color)</procedure>
3782
3783See [[https://wiki.libsdl.org/SDL_FillRect|SDL_FillRect]].
3784
3785{{rect}} may be an sdl2:rect to fill part of the surface, or #f to fill
3786the entire surface.
3787
3788{{color}} may be an sdl2:color or a mapped color (an integer, like
3789returned by {{map-rgba}}).
3790
3791Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3792
3793
3794<procedure>(fill-rects! surface rects color)</procedure>
3795
3796See [[https://wiki.libsdl.org/SDL_FillRects|SDL_FillRects]].
3797
3798{{rects}} must be a list of sdl2:rects.
3799
3800{{color}} may be an sdl2:color or a mapped color (an integer, like
3801returned by {{map-rgba}}).
3802
3803Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3804
3805
3806<procedure>(surface-ref surface x y) → sdl2:color</procedure>
3807<procedure>(surface-ref-raw surface x y) → integer</procedure>
3808<setter>(set! (surface-ref surface x y) color)</setter>
3809<setter>(surface-set! surface x y color)</setter>
3810
3811Get or set the color of the specified pixel on the surface.
3812
3813* {{surface-ref}} returns an sdl2:color.
3814* {{surface-ref-raw}} returns a mapped color (an integer). You can use {{get-rgba}} to convert the mapped color to color fields.
3815* The setters accept either an sdl2:color or a mapped color.
3816
3817These procedures automatically lock and unlock the surface if needed.
3818They signal an exception of kind {{(exn sdl2)}} if the surface cannot be locked.
3819
3820These procedures signal an exception of kind {{(exn bounds)}} if {{x}} or {{y}} is out of bounds.
3821
3822The setters ignore the surface's clip rect.
3823
3824
3825<procedure>(rotate-surface-90  surface turns) → sdl2:surface</procedure>
3826<procedure>(rotate-surface-90* surface turns) → sdl2:surface</procedure>
3827
3828Return a copy of the given surface rotated by the given number of 90º clockwise turns.
3829{{turns}} must be an integer.
3830For example:
3831
3832* {{turns}} 0 means no rotation
3833* {{turns}} 1 means 90º clockwise rotation
3834* {{turns}} 2 means 180º rotation
3835* {{turns}} 3 (or -1) means 270º clockwise (i.e. 90º counter-clockwise) rotation
3836
3837The new surface will have an equivalent pixel format, color key, blend mode, alpha mod, and color mod as the given surface.
3838If the given surface has a palette, the new surface will share the same palette.
3839The new surface will have no clip rect.
3840
3841Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3842
3843* {{rotate-surface-90}} returns a managed sdl2:surface.
3844* {{rotate-surface-90*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
3845
3846
3847<procedure>(flip-surface  surface flip-x? flip-y?) → sdl2:surface</procedure>
3848<procedure>(flip-surface* surface flip-x? flip-y?) → sdl2:surface</procedure>
3849
3850Return a copy of the given surface flipped on the X (horizontal) and/or Y (vertical) axes.
3851
3852The new surface will have an equivalent pixel format, color key, blend mode, alpha mod, and color mod as the given surface.
3853If the given surface has a palette, the new surface will share the same palette.
3854The new surface will have no clip rect.
3855
3856Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3857
3858* {{flip-surface}} returns a managed sdl2:surface.
3859* {{flip-surface*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
3860
3861
3862
3863==== sdl2:surface
3864
3865sdl2:surface is a record type that wraps a pointer to an
3866[[https://wiki.libsdl.org/SDL_Surface|SDL_Surface]] struct.
3867
3868
3869<procedure>(surface? obj) → boolean</procedure>
3870
3871Returns #t if {{obj}} is an sdl2:surface.
3872
3873
3874<procedure>(make-surface width height depth) → sdl2:surface</procedure>
3875<procedure>(make-surface* width height depth) → sdl2:surface</procedure>
3876
3877Create a new sdl2:surface with the given width, height, and color depth (bits per pixel).
3878This is a more convenient interface for {{create-rgb-surface}}.
3879The sdl2:surface's pixel format and masks will be chosen automatically
3880based on the requested depth and the current platform's byte order (little endian or big endian).
3881
3882These procedures signal an exception of kind {{(exn sdl2)}}
3883if the sdl2:surface could not be created (e.g. because the color depth is unsupported).
3884
3885* {{make-surface}} returns a managed sdl2:surface.
3886* {{make-surface*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
3887
3888
3889<procedure>(free-surface! surface)</procedure>
3890
3891Free the memory of the sdl2:surface's underlying struct. {{surface}}'s
3892pointer will be set to null (see {{struct-null?}}). It is safe to call
3893this procedure with managed or unmanaged sdl2:surfaces. It is safe
3894(but has no effect) to free a struct record multiple times.
3895
3896See [[https://wiki.libsdl.org/SDL_FreeSurface|SDL_FreeSurface]].
3897
3898'''NOTE:''' if {{surface}} was created using
3899{{create-rgb-surface-from}}, then the pixel data is not freed.
3900
3901
3902<procedure>(surface-format surface) → sdl2:pixel-format</procedure>
3903
3904Get the sdl2:surface's "format" field, as a sdl2:pixel-format describing the format of the surface's pixels.
3905
3906
3907<procedure>(surface-w surface) → integer</procedure>
3908
3909Get the sdl2:surface's "w" field, as a nonnegative integer indicating the surface's width in pixels.
3910
3911
3912<procedure>(surface-h surface) → integer</procedure>
3913
3914Get the sdl2:surface's "h" field, as a nonnegative integer indicating the surface's height in pixels.
3915
3916
3917<procedure>(surface-pitch surface) → integer</procedure>
3918
3919Get the sdl2:surface's "pitch" field, as a nonnegative integer indicating how many bytes are used to represent one row of pixel data.
3920
3921
3922<procedure>(surface-pixels-raw surface) → pointer or #f</procedure>
3923
3924Get the sdl2:surface's "pixels" field, as a raw pointer to the sdl2:surface's pixels.
3925Don't use this unless you really know what you are doing!
3926
3927If you want to get or set a pixel, use {{surface-ref}} and {{surface-set!}} instead.
3928They are much safer, more convenient, and more efficient than accessing the pixel data using this pointer.
3929
3930
3931<procedure>(surface-userdata-raw surface) → pointer or #f</procedure>
3932<setter>(set! (surface-userdata-raw surface) val)</setter>
3933<setter>(surface-userdata-raw-set! surface val)</setter>
3934
3935Get or set the sdl2:surface's "userdata" field, as a pointer or #f.
3936
3937If you want to store a pointer to a Scheme object here, be sure to
3938[[/manual/Unit lolevel#object-evict|evict the object]] first. Otherwise
3939the object's location in memory might change, rendering the pointer
3940invalid.
3941
3942
3943<procedure>(surface-refcount surface) → integer</procedure>
3944<setter>(set! (surface-refcount surface) val)</setter>
3945<setter>(surface-refcount-set! surface val)</setter>
3946
3947Get or set the sdl2:surface's "refcount" field, as an integer.
3948
3949
3950<procedure>(surface-clip-rect surface) → sdl2:rect</procedure>
3951<setter>(set! (surface-clip-rect surface) rect) → boolean</setter>
3952<setter>(surface-clip-rect-set! surface rect) → boolean</setter>
3953
3954{{surface-clip-rect}} returns a copy of the surface's clip rect.
3955See [[https://wiki.libsdl.org/SDL_GetClipRect|SDL_GetClipRect]].
3956
3957The setters sets the surface's clip rect to a copy of the given rect.
3958{{rect}} may be #f, which disables clipping.
3959See [[https://wiki.libsdl.org/SDL_SetClipRect|SDL_SetClipRect]].
3960
3961The 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).
3962
3963
3964<procedure>(surface-color-key surface) → sdl2:color or #f</procedure>
3965<procedure>(surface-colour-key surface) → sdl2:color or #f</procedure>
3966<procedure>(surface-color-key-raw surface) → integer or #f</procedure>
3967<procedure>(surface-colour-key-raw surface) → integer or #f</procedure>
3968<setter>(set! (surface-color-key surface) color)</setter>
3969<setter>(set! (surface-colour-key surface) color)</setter>
3970<setter>(surface-color-key-set! surface color)</setter>
3971<setter>(surface-colour-key-set! surface color)</setter>
3972
3973Get or set the sdl2:surface's color key.
3974
3975See [[https://wiki.libsdl.org/SDL_GetColorKey|SDL_GetColorKey]]
3976and [[https://wiki.libsdl.org/SDL_SetColorKey|SDL_SetColorKey]].
3977
3978* {{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.
3979* {{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.
3980* The setters accept either an sdl2:color, a mapped color (an integer), or #f to disable color keying.
3981
3982These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
3983
3984
3985<procedure>(surface-alpha-mod surface) → integer</procedure>
3986<setter>(set! (surface-alpha-mod surface) mod)</setter>
3987<setter>(surface-alpha-mod-set! surface mod)</setter>
3988
3989See [[https://wiki.libsdl.org/SDL_GetSurfaceAlphaMod|SDL_GetSurfaceAlphaMod]]
3990and [[https://wiki.libsdl.org/SDL_SetSurfaceAlphaMod|SDL_SetSurfaceAlphaMod]].
3991
3992These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
3993
3994
3995<procedure>(surface-blend-mode surface) → symbol</procedure>
3996<procedure>(surface-blend-mode-raw surface) → integer</procedure>
3997<setter>(set! (surface-blend-mode surface) mode)</setter>
3998<setter>(surface-blend-mode-set! surface mode)</setter>
3999
4000See [[https://wiki.libsdl.org/SDL_GetSurfaceBlendMode|SDL_GetSurfaceBlendMode]]
4001and [[https://wiki.libsdl.org/SDL_SetSurfaceBlendMode|SDL_SetSurfaceBlendMode]].
4002
4003* {{surface-blend-mode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-mode|blend mode symbol]]:
4004** {{'none}}
4005** {{'blend}}
4006** {{'add}}
4007** {{'mod}}
4008* {{surface-blend-mode-raw}} returns an integer.
4009* The setters accept either a symbol or integer.
4010
4011These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4012
4013
4014<procedure>(surface-color-mod surface) → [r g b]</procedure>
4015<procedure>(surface-colour-mod surface) → [r g b]</procedure>
4016<setter>(set! (surface-color-mod surface) rgb)</setter>
4017<setter>(set! (surface-colour-mod surface) rgb)</setter>
4018<setter>(surface-color-mod-set! surface rgb)</setter>
4019<setter>(surface-colour-mod-set! surface rgb)</setter>
4020
4021See [[https://wiki.libsdl.org/SDL_GetSurfaceColorMod|SDL_GetSurfaceColorMod]]
4022and [[https://wiki.libsdl.org/SDL_SetSurfaceColorMod|SDL_SetSurfaceColorMod]].
4023
4024{{surface-color-mod}} and {{surface-colour-mod}} return multiple values.
4025
4026The setters accept either a list {{(r g b)}} of color values, or an sdl2:color (the sdl2:color's "a" field will be ignored).
4027
4028These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4029
4030
4031<procedure>(surface-palette surface) → sdl2:palette or #f</procedure>
4032<setter>(set! (surface-palette surface) palette)</setter>
4033<setter>(surface-palette-set! surface palette)</setter>
4034
4035{{surface-palette}} returns the surface's palette, or #f if it has no palette.
4036It is equivalent to {{(compose pixel-format-palette surface-format)}}.
4037
4038The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
4039
4040See [[https://wiki.libsdl.org/SDL_SetSurfacePalette|SDL_SetSurfacePalette]].
4041
4042
4043<setter>(surface-rle-set! surface enable?)</setter>
4044
4045Enable RLE acceleration if {{enable?}} is #t, or disable RLE acceleration if {{enable?}} is #f.
4046See [[https://wiki.libsdl.org/SDL_SetSurfaceRLE|SDL_SetSurfaceRLE]].
4047
4048Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4049
4050
4051
4052=== Timer
4053
4054<procedure>(delay! milliseconds)</procedure>
4055
4056See [[https://wiki.libsdl.org/SDL_Delay|SDL_Delay]].
4057
4058'''CAUTION:''' This procedure is not compatible with [[/manual/Unit srfi-18|SRFI-18]]
4059threads. It will cause '''all threads to sleep''' for the given
4060duration. If you are using multiple threads, you should instead call
4061SRFI-18's {{thread-sleep!}}, which will cause only the current thread
4062to sleep. For example, call {{(thread-sleep! 0.025)}} instead of
4063{{(delay! 25)}}.
4064
4065
4066<procedure>(get-ticks) → integer</procedure>
4067
4068See [[https://wiki.libsdl.org/SDL_GetTicks|SDL_GetTicks]].
4069
4070
4071<procedure>(get-performance-counter) → integer</procedure>
4072
4073See [[https://wiki.libsdl.org/SDL_GetPerformanceCounter|SDL_GetPerformanceCounter]].
4074
4075
4076<procedure>(get-performance-frequency) → integer</procedure>
4077
4078See [[https://wiki.libsdl.org/SDL_GetPerformanceFrequency|SDL_GetPerformanceFrequency]].
4079
4080
4081
4082=== Touch / Gesture
4083
4084==== Touch / Gesture Functions
4085
4086<procedure>(get-num-touch-devices) → integer</procedure>
4087
4088See [[https://wiki.libsdl.org/SDL_GetNumTouchDevices|SDL_GetNumTouchDevices]].
4089
4090
4091<procedure>(get-touch-device device-id) → integer</procedure>
4092
4093See [[https://wiki.libsdl.org/SDL_GetTouchDevice|SDL_GetTouchDevice]].
4094
4095Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4096
4097
4098<procedure>(get-num-touch-fingers touch-id) → integer</procedure>
4099
4100See [[https://wiki.libsdl.org/SDL_GetNumTouchFingers|SDL_GetNumTouchFingers]].
4101
4102
4103<procedure>(get-touch-finger touch-id index) → sdl2:finger</procedure>
4104
4105See [[https://wiki.libsdl.org/SDL_GetTouchFinger|SDL_GetTouchFinger]].
4106
4107Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4108
4109
4110==== sdl2:finger
4111
4112sdl2:finger is a record type that wraps a pointer to an
4113[[https://wiki.libsdl.org/SDL_Finger|SDL_Finger]] struct.
4114
4115
4116<procedure>(finger? obj) → boolean</procedure>
4117
4118Returns #t if {{obj}} is an sdl2:finger.
4119
4120
4121<procedure>(finger-id finger) → integer</procedure>
4122
4123Get the sdl2:finger's "id" field, as an integer.
4124
4125
4126<procedure>(finger-x finger) → float</procedure>
4127
4128Get 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.
4129
4130
4131<procedure>(finger-y finger) → float</procedure>
4132
4133Get 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.
4134
4135
4136<procedure>(finger-pressure finger) → float</procedure>
4137
4138Get 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.
4139
4140
4141
4142=== Version
4143
4144<procedure>(version-at-least? major minor patch) → boolean</procedure>
4145
4146See [[https://wiki.libsdl.org/SDL_VERSION_ATLEAST|SDL_VERSION_ATLEAST]].
4147
4148Returns #t if the sdl2 egg was compiled with a version of SDL at least as high as specified.
4149For example, {{(version-at-least? 2 0 1)}} returns #t if the sdl2 egg was compiled with SDL 2.0.1 or higher.
4150
4151Some SDL features are only available after a certain version, so you can use this procedure to check whether the feature is available.
4152
4153
4154<procedure>(compiled-version) → list of integers</procedure>
4155<procedure>(current-version) → list of integers</procedure>
4156
4157Returns a list of three nonnegative integers, indicating a version number of SDL.
4158For example, the list {{(2 0 3)}} indicates SDL 2.0.3.
4159
4160* {{compiled-version}} returns the version of SDL that the sdl2 egg was compiled with.
4161* {{current-version}} returns the version of SDL that the sdl2 egg is currently using.
4162
4163For 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.
4164In such a case, {{compiled-version}} would return {{(2 0 3)}}, and {{current-version}} would return {{(2 1 0)}}.
4165But, features from the new version would not be available until the user recompiles the sdl2 egg.
4166
4167See [[https://wiki.libsdl.org/SDL_VERSION|SDL_VERSION]]
4168and [[https://wiki.libsdl.org/SDL_GetVersion|SDL_GetVersion]].
4169
4170
4171<constant>(egg-version) → list of integers</constant>
4172
4173Returns a list of three nonnegative integers, indicating the version number of the sdl2 egg itself, which is independent of the version number of SDL.
4174For example, the list {{'(1 2 3)}} indicates sdl2 egg version 1.2.3.
4175
4176'''NOTE:''' This procedure is available in '''sdl2 egg version 0.2.0 or later'''.
4177If you want to check the egg version, but users of your program might be using earlier than egg version 0.2.0,
4178you can define and use the following procedure in your program:
4179
4180<enscript highlight="scheme">
4181;; Return sdl2 egg version if possible, otherwise return '(0 1 0).
4182(define (get-sdl2-egg-version)
4183  (condition-case (sdl2#egg-version)
4184    (() '(0 1 0))))
4185</enscript>
4186
4187
4188
4189=== Window / Display Mode
4190
4191==== Window / Display Mode Functions
4192
4193<procedure>(create-window! title x y w h #!optional flags) → sdl2:window</procedure>
4194
4195See [[https://wiki.libsdl.org/SDL_CreateWindow|SDL_CreateWindow]].
4196
4197{{x}} and {{y}} can be integers, the symbol {{'centered}}, or the symbol {{'undefined}}.
4198
4199{{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):
4200
4201* {{'fullscreen}}
4202* {{'fullscreen-desktop}}
4203* {{'opengl}}
4204* {{'shown}}
4205* {{'hidden}}
4206* {{'borderless}}
4207* {{'resizable}}
4208* {{'minimized}}
4209* {{'maximized}}
4210* {{'input-grabbed}}
4211* {{'input-focus}}
4212* {{'mouse-focus}}
4213* {{'foreign}}
4214* {{'allow-high-dpi}} (requires '''sdl2 egg 0.2.0 and SDL 2.0.1 or higher''')
4215* {{'mouse-capture}} (requires '''sdl2 egg 0.2.0 and SDL 2.0.4 or higher''')
4216
4217
4218<procedure>(destroy-window! window)</procedure>
4219
4220See [[https://wiki.libsdl.org/SDL_DestroyWindow|SDL_DestroyWindow]].
4221
4222
4223<procedure>(get-window-from-id id) → sdl2:window</procedure>
4224
4225See [[https://wiki.libsdl.org/SDL_GetWindowFromID|SDL_GetWindowFromID]].
4226
4227
4228<procedure>(update-window-surface! window)</procedure>
4229
4230See [[https://wiki.libsdl.org/SDL_UpdateWindowSurface|SDL_UpdateWindowSurface]].
4231
4232Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4233
4234
4235<procedure>(update-window-surface-rects! window rects)</procedure>
4236
4237See [[https://wiki.libsdl.org/SDL_UpdateWindowSurfaceRects|SDL_UpdateWindowSurfaceRects]].
4238
4239{{rects}} must be a list of sdl2:rects.
4240
4241Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4242
4243
4244<procedure>(show-window! window)</procedure>
4245
4246See [[https://wiki.libsdl.org/SDL_ShowWindow|SDL_ShowWindow]].
4247
4248
4249<procedure>(hide-window! window)</procedure>
4250
4251See [[https://wiki.libsdl.org/SDL_HideWindow|SDL_HideWindow]].
4252
4253
4254<procedure>(maximize-window! window)</procedure>
4255
4256See [[https://wiki.libsdl.org/SDL_MaximizeWindow|SDL_MaximizeWindow]].
4257
4258
4259<procedure>(minimize-window! window)</procedure>
4260
4261See [[https://wiki.libsdl.org/SDL_MinimizeWindow|SDL_MinimizeWindow]].
4262
4263
4264<procedure>(raise-window! window)</procedure>
4265
4266See [[https://wiki.libsdl.org/SDL_RaiseWindow|SDL_RaiseWindow]].
4267
4268
4269<procedure>(restore-window! window)</procedure>
4270
4271See [[https://wiki.libsdl.org/SDL_RestoreWindow|SDL_RestoreWindow]].
4272
4273
4274
4275==== sdl2:window
4276
4277sdl2:window is a record type that wraps a pointer to an
4278[[https://wiki.libsdl.org/SDL_CreateWindow|SDL_Window]] struct.
4279
4280
4281<procedure>(window? obj) → boolean</procedure>
4282
4283Returns #t if {{obj}} is an sdl2:window.
4284
4285
4286<procedure>(window-bordered? window) → boolean</procedure>
4287<setter>(set! (window-bordered? window) bordered)</setter>
4288<setter>(window-bordered-set! window bordered)</setter>
4289
4290Get or set whether the window has a border (window decoration).
4291#t means the window has a border, #f means the window is borderless.
4292
4293Setting this to #f has essentially the same effect as passing the {{'borderless}} flag to {{create-window!}} when creating the window.
4294
4295See [[https://wiki.libsdl.org/SDL_SetWindowBordered|SDL_SetWindowBordered]].
4296
4297
4298<procedure>(window-brightness window) → float</procedure>
4299<setter>(set! (window-brightness window) brightness)</setter>
4300<setter>(window-brightness-set! window brightness)</setter>
4301
4302See [[https://wiki.libsdl.org/SDL_GetWindowBrightness|SDL_GetWindowBrightness]]
4303and [[https://wiki.libsdl.org/SDL_SetWindowBrightness|SDL_SetWindowBrightness]].
4304
4305The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
4306
4307
4308<procedure>(window-display-index window) → integer</procedure>
4309
4310See [[https://wiki.libsdl.org/SDL_GetWindowDisplayIndex|SDL_GetWindowDisplayIndex]].
4311
4312Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4313
4314
4315<procedure>(window-display-mode window) → sdl2:display-mode</procedure>
4316<setter>(set! (window-display-mode window) display-mode)</setter>
4317<setter>(window-display-mode-set! window display-mode)</setter>
4318
4319See [[https://wiki.libsdl.org/SDL_GetWindowDisplayMode|SDL_GetWindowDisplayMode]]
4320and [[https://wiki.libsdl.org/SDL_SetWindowDisplayMode|SDL_SetWindowDisplayMode]].
4321
4322These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4323
4324
4325<procedure>(window-flags window) → list of symbols</procedure>
4326<procedure>(window-flags-raw window) → integer</procedure>
4327
4328See [[https://wiki.libsdl.org/SDL_GetWindowFlags|SDL_GetWindowFlags]].
4329
4330* {{window-flags}} returns a list of [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#window-flags|window flag symbols]].
4331* {{window-flags-raw}} returns an integer bitfield.
4332
4333
4334<procedure>(window-fullscreen window) → symbol or #f</procedure>
4335<setter>(set! (window-fullscreen window) mode)</setter>
4336<setter>(window-fullscreen-set! window mode)</setter>
4337
4338Get or set the sdl2:window's fullscreen mode.
4339See [[https://wiki.libsdl.org/SDL_SetWindowFullscreen|SDL_SetWindowFullscreen]].
4340
4341{{window-fullscreen}} returns one of the following values:
4342
4343* {{'fullscreen}} means "real" fullscreen mode
4344* {{'fullscreen-desktop}} means "fake" fullscreen mode that takes the size of the desktop
4345* {{#f}} means windowed (non-fullscreen) mode
4346
4347The setters accept any of the above values, or #t (which means the same as {{'fullscreen}}), or an equivalent integer value.
4348
4349The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
4350
4351
4352<procedure>(window-grab? window) → boolean</procedure>
4353<setter>(set! (window-grab? window) grab?)</setter>
4354<setter>(window-grab-set! window grab?)</setter>
4355
4356See [[https://wiki.libsdl.org/SDL_GetWindowGrab|SDL_GetWindowGrab]]
4357and [[https://wiki.libsdl.org/SDL_SetWindowGrab|SDL_SetWindowGrab]].
4358
4359
4360<setter>(window-icon-set! window icon-surface)</setter>
4361
4362See [[https://wiki.libsdl.org/SDL_SetWindowIcon|SDL_SetWindowIcon]].
4363
4364
4365<procedure>(window-id window) → integer</procedure>
4366
4367See [[https://wiki.libsdl.org/SDL_GetWindowID|SDL_GetWindowID]].
4368
4369
4370<procedure>(window-maximum-size window) → [width height]</procedure>
4371<setter>(set! (window-maximum-size window) size)</setter>
4372<setter>(window-maximum-size-set! window size)</setter>
4373
4374See [[https://wiki.libsdl.org/SDL_GetWindowMaximumSize|SDL_GetWindowMaximumSize]]
4375and [[https://wiki.libsdl.org/SDL_SetWindowMaximumSize|SDL_SetWindowMaximumSize]].
4376
4377{{window-maximum-size}} returns multiple values.
4378
4379The setters accept a list of integers {{(width height)}}.
4380
4381
4382<procedure>(window-minimum-size window) → [width height]</procedure>
4383<setter>(set! (window-minimum-size window) size)</setter>
4384<setter>(window-minimum-size-set! window size)</setter>
4385
4386See [[https://wiki.libsdl.org/SDL_GetWindowMinimumSize|SDL_GetWindowMinimumSize]]
4387and [[https://wiki.libsdl.org/SDL_SetWindowMinimumSize|SDL_SetWindowMinimumSize]].
4388
4389{{window-minimum-size}} returns multiple values.
4390
4391The setters accept a list of integers {{(width height)}}.
4392
4393
4394<procedure>(window-pixel-format window) → symbol</procedure>
4395<procedure>(window-pixel-format-raw window) → integer</procedure>
4396
4397Returns a symbol or integer indicating the given window's pixel format.
4398See [[https://wiki.libsdl.org/SDL_GetWindowPixelFormat|SDL_GetWindowPixelFormat]].
4399
4400* {{window-pixel-format}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]].
4401* {{window-pixel-format-raw}} returns an integer.
4402
4403
4404<procedure>(window-position window) → [x y]</procedure>
4405<setter>(set! (window-position window) pos)</setter>
4406<setter>(window-position-set! window pos)</setter>
4407
4408See [[https://wiki.libsdl.org/SDL_GetWindowPosition|SDL_GetWindowPosition]]
4409and [[https://wiki.libsdl.org/SDL_SetWindowPosition|SDL_SetWindowPosition]].
4410
4411{{window-position}} returns multiple values.
4412
4413The setters accept a list of integers {{(x y)}}.
4414
4415
4416<procedure>(window-size window) → [width height]</procedure>
4417<setter>(set! (window-size window) size)</setter>
4418<setter>(window-size-set! window size)</setter>
4419
4420See [[https://wiki.libsdl.org/SDL_GetWindowSize|SDL_GetWindowSize]]
4421and [[https://wiki.libsdl.org/SDL_SetWindowSize|SDL_SetWindowSize]].
4422
4423{{window-size}} returns multiple values.
4424
4425The setters accept a list of integers {{(width height)}}.
4426
4427
4428<procedure>(window-surface window) → sdl2:surface</procedure>
4429
4430See [[https://wiki.libsdl.org/SDL_GetWindowSurface|SDL_GetWindowSurface]].
4431
4432Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4433
4434
4435<procedure>(window-title window) → string</procedure>
4436<setter>(set! (window-title window) title)</setter>
4437<setter>(window-title-set! window title)</setter>
4438
4439See [[https://wiki.libsdl.org/SDL_GetWindowTitle|SDL_GetWindowTitle]]
4440and [[https://wiki.libsdl.org/SDL_SetWindowTitle|SDL_SetWindowTitle]].
4441
4442
4443
4444==== sdl2:display-mode
4445
4446sdl2:display-mode is a record type that wraps a pointer to an
4447[[https://wiki.libsdl.org/SDL_DisplayMode|SDL_DisplayMode]] struct.
4448
4449
4450<procedure>(display-mode? obj) → boolean</procedure>
4451
4452Returns #t if {{obj}} is an sdl2:display-mode.
4453
4454
4455<procedure>(make-display-mode #!optional format w h refresh-rate) → sdl2:display-mode</procedure>
4456<procedure>(make-display-mode* #!optional format w h refresh-rate) → sdl2:display-mode</procedure>
4457
4458Allocate and initialize a new sdl2:display-mode.
4459
4460{{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.
4461
4462{{w}}, {{h}}, and {{refresh-rate}} default to 0. They must be integers.
4463
4464* {{make-display-mode}} returns a managed sdl2:display-mode.
4465* {{make-display-mode*}} returns an unmanaged sdl2:display-mode, which must be freed with {{free-display-mode!}} when you are done with it.
4466
4467
4468<procedure>(free-display-mode! display-mode)</procedure>
4469
4470Free the memory of the sdl2:display-mode's underlying struct.
4471{{display-mode}}'s pointer will be set to null (see {{struct-null?}}).
4472It is safe to call this procedure with managed or unmanaged
4473sdl2:display-modes. It is safe (but has no effect) to free a struct
4474record multiple times.
4475
4476
4477<procedure>(display-mode-format display-mode) → symbol</procedure>
4478<procedure>(display-mode-format-raw display-mode) → integer</procedure>
4479<setter>(set! (display-mode-format display-mode) val)</setter>
4480<setter>(display-mode-format-set! display-mode val)</setter>
4481
4482Get or set the sdl2:display-mode's "format" field.
4483
4484* {{display-mode-format}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]].
4485* {{display-mode-format-raw}} returns an integer.
4486* The setters accept either a symbol or an integer.
4487
4488
4489<procedure>(display-mode-w display-mode) → integer</procedure>
4490<setter>(set! (display-mode-w display-mode) val)</setter>
4491<setter>(display-mode-w-set! display-mode val)</setter>
4492
4493Get or set the sdl2:display-mode's "w" field, as an integer.
4494
4495
4496<procedure>(display-mode-h display-mode) → integer</procedure>
4497<setter>(set! (display-mode-h display-mode) val)</setter>
4498<setter>(display-mode-h-set! display-mode val)</setter>
4499
4500Get or set the sdl2:display-mode's "h" field, as an integer.
4501
4502
4503<procedure>(display-mode-refresh-rate display-mode) → integer</procedure>
4504<setter>(set! (display-mode-refresh-rate display-mode) val)</setter>
4505<setter>(display-mode-refresh-rate-set! display-mode val)</setter>
4506
4507Get or set the sdl2:display-mode's "refresh-rate" field, as an integer.
4508
4509
4510
4511=== Miscellaneous
4512
4513<procedure>(clear-error!)</procedure>
4514
4515See [[https://wiki.libsdl.org/SDL_ClearError|SDL_ClearError]].
4516
4517
4518<procedure>(get-error) → string</procedure>
4519
4520See [[https://wiki.libsdl.org/SDL_GetError|SDL_GetError]].
4521
4522
4523<procedure>(set-error! message)</procedure>
4524
4525See [[https://wiki.libsdl.org/SDL_SetError|SDL_SetError]].
4526
4527Unlike SDL_SetError, this procedure only accepts one argument, a
4528string. You can use {{sprintf}} to do string substitution if desired.
4529
4530
4531<procedure>(get-platform) → string</procedure>
4532
4533See [[https://wiki.libsdl.org/SDL_GetPlatform|SDL_GetPlatform]].
4534
4535
4536<procedure>(screen-saver-enabled?) → boolean</procedure>
4537<setter>(set! (screen-saver-enabled?) enabled?)</setter>
4538<setter>(screen-saver-enabled-set! enabled?)</setter>
4539
4540See [[https://wiki.libsdl.org/SDL_IsScreenSaverEnabled|SDL_IsScreenSaverEnabled]],
4541[[https://wiki.libsdl.org/SDL_EnableScreenSaver|SDL_EnableScreenSaver]],
4542and [[https://wiki.libsdl.org/SDL_DisableScreenSaver|SDL_DisableScreenSaver]].
4543
4544
4545<procedure>(has-clipboard-text?) → boolean</procedure>
4546
4547See [[https://wiki.libsdl.org/SDL_HasClipboardText|SDL_HasClipboardText]].
4548
4549
4550<procedure>(get-clipboard-text) → string</procedure>
4551
4552See [[https://wiki.libsdl.org/SDL_GetClipboardText|SDL_GetClipboardText]].
4553
4554Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4555
4556
4557<procedure>(set-clipboard-text! text)</procedure>
4558
4559See [[https://wiki.libsdl.org/SDL_SetClipboardText|SDL_SetClipboardText]].
4560
4561Signals an exception of kind {{(exn sdl2)}} if an error occurs.
Note: See TracBrowser for help on using the repository browser.