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

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

sdl2: More 0.2.0 docs.

File size: 192.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 normally indicate scrolling to the right,
1519negative numbers indicate scrolling to the left.
1520But if the "direction" field is set to {{'flipped}} in SDL 2.0.4 or higher,
1521the meaning of this field is reversed.
1522
1523
1524<procedure>(mouse-wheel-event-y event) → integer</procedure>
1525<setter>(set! (mouse-wheel-event-y event) val)</setter>
1526<setter>(mouse-wheel-event-y-set! event val)</setter>
1527
1528Get or set the event's "y" field, as an integer (possibly negative) indicating the amount the wheel scrolled vertically.
1529Positive numbers normally indicate scrolling away from the user,
1530negative numbers indicate scrolling toward the user.
1531But if the "direction" field is set to {{'flipped}} in SDL 2.0.4 or higher,
1532the meaning of this field is reversed.
1533
1534
1535<procedure>(mouse-wheel-event-direction event) → symbol</procedure>
1536<setter>(set! (mouse-wheel-event-direction event) val)</setter>
1537<setter>(mouse-wheel-event-direction-set! event val)</setter>
1538
1539Get or set the event's "direction" field, as one of the following symbols:
1540
1541; {{'normal}} : "Normal" scrolling mode.
1542; {{'flipped}} : "Flipped" or "natural" scrolling mode. You can multiple the "x" and "y" field values by -1 to get the "normal" values.
1543
1544This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
1545It requires '''SDL 2.0.4 or higher'''.
1546It signals an error if the compiled version of SDL is not high enough.
1547Use the [[#version-feature-identifiers|{{libSDL-2.0.4+}} feature identifier]]
1548to check before calling this procedure.
1549
1550
1551==== sdl2:multi-gesture-event
1552
1553sdl2:multi-gesture-event is a variant of sdl2:event that wraps a pointer to an
1554[[https://wiki.libsdl.org/SDL_MultiGestureEvent|SDL_MultiGestureEvent]].
1555
1556This event variant occurs when a multi-finger gesture is performed on a touch device.
1557This is useful for recognizing common gestures that involve multiple fingers, e.g. pinching or rotating.
1558
1559sdl2:multi-gesture-event has the following event type symbols:
1560
1561; {{'multi-gesture}} : A multi-finger gesture was performed.
1562
1563
1564<procedure>(multi-gesture-event? obj) → boolean</procedure>
1565
1566Returns #t if {{obj}} is an sdl2:multi-gesture-event.
1567
1568
1569<procedure>(multi-gesture-event-touch-id event) → integer</procedure>
1570<setter>(set! (multi-gesture-event-touch-id event) val)</setter>
1571<setter>(multi-gesture-event-touch-id-set! event val)</setter>
1572
1573Get or set the event's "touch-id" field, as an integer indicating the ID number of the touch device this event is related to.
1574
1575
1576<procedure>(multi-gesture-event-dtheta event) → float</procedure>
1577<setter>(set! (multi-gesture-event-dtheta event) val)</setter>
1578<setter>(multi-gesture-event-dtheta-set! event val)</setter>
1579
1580Get or set the event's "dtheta" field, as a float indicating the amount that the fingers rotated during this motion.
1581
1582
1583<procedure>(multi-gesture-event-ddist event) → float</procedure>
1584<setter>(set! (multi-gesture-event-ddist event) val)</setter>
1585<setter>(multi-gesture-event-ddist-set! event val)</setter>
1586
1587Get or set the event's "ddist" field, as a float indicating the amount that the fingers pinched during this motion.
1588
1589
1590<procedure>(multi-gesture-event-x event) → float</procedure>
1591<setter>(set! (multi-gesture-event-x event) val)</setter>
1592<setter>(multi-gesture-event-x-set! event val)</setter>
1593
1594Get or set the event's "x" field, as a float indicating the normalized X coordinate of the center of the gesture.
1595
1596
1597<procedure>(multi-gesture-event-y event) → float</procedure>
1598<setter>(set! (multi-gesture-event-y event) val)</setter>
1599<setter>(multi-gesture-event-y-set! event val)</setter>
1600
1601Get or set the event's "y" field, as a float indicating the normalized Y coordinate of the center of the gesture.
1602
1603
1604<procedure>(multi-gesture-event-num-fingers event) → integer</procedure>
1605<setter>(set! (multi-gesture-event-num-fingers event) val)</setter>
1606<setter>(multi-gesture-event-num-fingers-set! event val)</setter>
1607
1608Get or set the event's "num-fingers" field, as an integer indicating the number of fingers used in the gesture.
1609
1610
1611
1612==== sdl2:quit-event
1613
1614sdl2:quit-event is a variant of sdl2:event that wraps a pointer to an
1615[[https://wiki.libsdl.org/SDL_QuitEvent|SDL_QuitEvent]].
1616
1617This event variant occurs when the user requests to quit the program.
1618There are [[https://wiki.libsdl.org/SDL_EventType#SDL_QUIT|various ways this might happen]], depending on the platform.
1619
1620sdl2:quit-event has the following event type symbols:
1621
1622; {{'quit}} : The user requested to quit the program.
1623
1624
1625<procedure>(quit-event? obj) → boolean</procedure>
1626
1627Returns #t if {{obj}} is an sdl2:quit-event.
1628
1629
1630
1631==== sdl2:sys-wm-event
1632
1633sdl2:sys-wm-event is a variant of sdl2:event that wraps a pointer to an
1634[[https://wiki.libsdl.org/SDL_SysWMEvent|SDL_SysWMEvent]].
1635
1636This event variant is for very advanced use cases. Most people can ignore it.
1637
1638sdl2:sys-wm-event has the following event type symbols:
1639
1640; {{'sys-wm}} : A platform-specific event occurred.
1641
1642
1643<procedure>(sys-wm-event? obj) → boolean</procedure>
1644
1645Returns #t if {{obj}} is an sdl2:sys-wm-event.
1646
1647
1648<procedure>(sys-wm-event-msg-raw event) → pointer</procedure>
1649<setter>(set! (sys-wm-event-msg-raw event) val)</setter>
1650<setter>(sys-wm-event-msg-raw-set! event val)</setter>
1651
1652Get 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.
1653This is for very advanced use cases. Most people can ignore it.
1654
1655
1656
1657==== sdl2:text-editing-event
1658
1659sdl2:text-editing-event is a variant of sdl2:event that wraps a pointer to an
1660[[https://wiki.libsdl.org/SDL_TextEditingEvent|SDL_TextEditingEvent]].
1661
1662This event occurs when a user is editing (composing) text, e.g. using an Input Method Editor (IME).
1663See the [[https://wiki.libsdl.org/Tutorials/TextInput|Text Input tutorial for SDL]].
1664
1665sdl2:text-editing-event has the following event type symbols:
1666
1667; {{'text-editing}} : The user editted some text being composed.
1668
1669
1670<procedure>(text-editing-event? obj) → boolean</procedure>
1671
1672Returns #t if {{obj}} is an sdl2:text-editing-event.
1673
1674
1675<procedure>(text-editing-event-window-id event) → integer</procedure>
1676<setter>(set! (text-editing-event-window-id event) val)</setter>
1677<setter>(text-editing-event-window-id-set! event val)</setter>
1678
1679Get 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.
1680
1681
1682<procedure>(text-editing-event-text event) → string</procedure>
1683<setter>(set! (text-editing-event-text event) val)</setter>
1684<setter>(text-editing-event-text-set! event val)</setter>
1685
1686Get 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.
1687
1688
1689<procedure>(text-editing-event-start event) → integer</procedure>
1690<setter>(set! (text-editing-event-start event) val)</setter>
1691<setter>(text-editing-event-start-set! event val)</setter>
1692
1693Get or set the event's "start" field, as an integer indicating the location to begin editing from.
1694
1695
1696<procedure>(text-editing-event-length event) → integer</procedure>
1697<setter>(set! (text-editing-event-length event) val)</setter>
1698<setter>(text-editing-event-length-set! event val)</setter>
1699
1700Get or set the event's "length" field, as an integer indicating the number of characters to edit from the start point.
1701
1702
1703
1704==== sdl2:text-input-event
1705
1706sdl2:text-input-event is a variant of sdl2:event that wraps a pointer to an
1707[[https://wiki.libsdl.org/SDL_TextInputEvent|SDL_TextInputEvent]].
1708
1709This event occurs when the users enters some text, possibly using an Input Metod Editor (IME).
1710See the [[https://wiki.libsdl.org/Tutorials/TextInput|Text Input tutorial for SDL]].
1711
1712sdl2:text-input-event has the following event type symbols:
1713
1714; {{'text-input}} : The use inputted some text.
1715
1716
1717<procedure>(text-input-event? obj) → boolean</procedure>
1718
1719Returns #t if {{obj}} is an sdl2:text-input-event.
1720
1721
1722<procedure>(text-input-event-window-id event) → integer</procedure>
1723<setter>(set! (text-input-event-window-id event) val)</setter>
1724<setter>(text-input-event-window-id-set! event val)</setter>
1725
1726Get 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.
1727
1728
1729<procedure>(text-input-event-text event) → string</procedure>
1730<setter>(set! (text-input-event-text event) val)</setter>
1731<setter>(text-input-event-text-set! event val)</setter>
1732
1733Get 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.
1734
1735
1736
1737==== sdl2:touch-finger-event
1738
1739sdl2:touch-finger-event is a variant of sdl2:event that wraps a pointer to an
1740[[https://wiki.libsdl.org/SDL_TouchFingerEvent|SDL_TouchFingerEvent]].
1741
1742This event variant occurs when the user presses, lifts, or moves a finger (or stylus, etc.) on a supported touch device,
1743e.g. the touch screen of a mobile phone or tablet device, or certain laptop trackpads.
1744There may be more than one finger touching at the same time;
1745you can distinguish the fingers by the {{finger-id}} number.
1746
1747sdl2:touch-finger-event has the following event type symbols:
1748
1749; {{'finger-down}} : A finger started touching a touch device (i.e. was pressed down).
1750; {{'finger-up}} : A finger stopped touching a touch device (i.e. was lifted up).
1751; {{'finger-motion}} : A finger moved while touching a touch device.
1752
1753
1754<procedure>(touch-finger-event? obj) → boolean</procedure>
1755
1756Returns #t if {{obj}} is an sdl2:touch-finger-event.
1757
1758
1759<procedure>(touch-finger-event-touch-id event) → integer</procedure>
1760<setter>(set! (touch-finger-event-touch-id event) val)</setter>
1761<setter>(touch-finger-event-touch-id-set! event val)</setter>
1762
1763Get or set the event's "touch-id" field, as an integer indicating the ID number of the touch device this event is related to.
1764
1765
1766<procedure>(touch-finger-event-finger-id event) → integer</procedure>
1767<setter>(set! (touch-finger-event-finger-id event) val)</setter>
1768<setter>(touch-finger-event-finger-id-set! event val)</setter>
1769
1770Get or set the event's "finger-id" field, as an integer indicating the ID number of the finger this event is related to.
1771
1772
1773<procedure>(touch-finger-event-x event) → float</procedure>
1774<setter>(set! (touch-finger-event-x event) val)</setter>
1775<setter>(touch-finger-event-x-set! event val)</setter>
1776
1777Get 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.
1778
1779
1780<procedure>(touch-finger-event-y event) → float</procedure>
1781<setter>(set! (touch-finger-event-y event) val)</setter>
1782<setter>(touch-finger-event-y-set! event val)</setter>
1783
1784Get 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.
1785
1786
1787<procedure>(touch-finger-event-dx event) → float</procedure>
1788<setter>(set! (touch-finger-event-dx event) val)</setter>
1789<setter>(touch-finger-event-dx-set! event val)</setter>
1790
1791Get 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.
1792
1793
1794<procedure>(touch-finger-event-dy event) → float</procedure>
1795<setter>(set! (touch-finger-event-dy event) val)</setter>
1796<setter>(touch-finger-event-dy-set! event val)</setter>
1797
1798Get 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.
1799
1800
1801<procedure>(touch-finger-event-pressure event) → float</procedure>
1802<setter>(set! (touch-finger-event-pressure event) val)</setter>
1803<setter>(touch-finger-event-pressure-set! event val)</setter>
1804
1805Get or set the event's "pressure" field, as a float in the range 0.0 to 1.0 (inclusive), indicating the pressure being applied.
1806
1807
1808
1809==== sdl2:user-event
1810
1811sdl2:user-event is a variant of sdl2:event that wraps a pointer to an
1812[[https://wiki.libsdl.org/SDL_UserEvent|SDL_UserEvent]].
1813
1814This event variant does not occur normally.
1815Instead, you can make instances of this event variant and push them to the event queue using {{push-event!}}.
1816The meaning of this event variant is entirely up for you to decide.
1817For example, you can use it to create custom event types related to your gameplay.
1818
1819sdl2:user-event does not have any event type symbols by default.
1820Call {{register-events!}} to register your own custom event type symbols for sdl2:user-event.
1821
1822
1823<procedure>(user-event? obj) → boolean</procedure>
1824
1825Returns #t if {{obj}} is an sdl2:user-event.
1826
1827
1828<procedure>(user-event-window-id event) → integer</procedure>
1829<setter>(set! (user-event-window-id event) val)</setter>
1830<setter>(user-event-window-id-set! event val)</setter>
1831
1832Get or set the event's "window-id" field, as an integer indicating the ID number of the sdl2:window associated with this event.
1833
1834
1835<procedure>(user-event-code event) → integer</procedure>
1836<setter>(set! (user-event-code event) val)</setter>
1837<setter>(user-event-code-set! event val)</setter>
1838
1839Get or set the event's "code" field, as an integer in the range -32768 to 32767 (inclusive).
1840The meaning of this field is for you to decide.
1841
1842
1843<procedure>(user-event-data1-raw event) → pointer or #f</procedure>
1844<setter>(set! (user-event-data1-raw event) val)</setter>
1845<setter>(user-event-data1-raw-set! event val)</setter>
1846
1847Get or set the event's "data1" field, as a raw pointer or #f.
1848The meaning of this field is for you to decide.
1849
1850If you want to store a pointer to a Scheme object here, be sure to
1851[[/manual/Unit lolevel#object-evict|evict the object]] first. Otherwise
1852the object's location in memory might change, rendering the pointer
1853invalid.
1854
1855
1856<procedure>(user-event-data2-raw event) → pointer or #f</procedure>
1857<setter>(set! (user-event-data2-raw event) val)</setter>
1858<setter>(user-event-data2-raw-set! event val)</setter>
1859
1860Get or set the event's "data2" field, as a raw pointer or #f.
1861The meaning of this field is for you to decide.
1862
1863If you want to store a pointer to a Scheme object here, be sure to
1864[[/manual/Unit lolevel#object-evict|evict the object]] first. Otherwise
1865the object's location in memory might change, rendering the pointer
1866invalid.
1867
1868
1869
1870==== sdl2:window-event
1871
1872sdl2:window-event is a variant of sdl2:event that wraps a pointer to an
1873[[https://wiki.libsdl.org/SDL_WindowEvent|SDL_WindowEvent]].
1874
1875This event variant occurs when various changes occur to a window,
1876e.g. when a window is moved, resized, minimized, closed, etc.
1877
1878sdl2:window-event has the following event type symbols:
1879
1880; {{'window}} : A window-related event occurred.
1881
1882
1883<procedure>(window-event? obj) → boolean</procedure>
1884
1885Returns #t if {{obj}} is an sdl2:window-event.
1886
1887
1888<procedure>(window-event-window-id event) → integer</procedure>
1889<setter>(set! (window-event-window-id event) val)</setter>
1890<setter>(window-event-window-id-set! event val)</setter>
1891
1892Get or set the event's "window-id" field, as an integer indicating the ID of the sdl2:window that the event is related to.
1893
1894
1895<procedure>(window-event-event event) → symbol</procedure>
1896<procedure>(window-event-event-raw event) → integer</procedure>
1897<setter>(set! (window-event-event event) val)</setter>
1898<setter>(window-event-event-set! event val)</setter>
1899
1900Get or set the event's "event" field, indicating what happened to the window.
1901
1902* {{window-event-event}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#window-event-types|window event type symbol]].
1903* {{window-event-event-raw}} returns an integer.
1904* The setters accept either a symbol or an integer.
1905
1906
1907<procedure>(window-event-data1 event) → integer</procedure>
1908<setter>(set! (window-event-data1 event) val)</setter>
1909<setter>(window-event-data1-set! event val)</setter>
1910
1911Get or set the sdl2:window-event's "data1" field, as an integer.
1912The meaning of this value depends on what kind of window event it was (see {{window-event-event}}).
1913E.g. if the window was resized, this will hold the new window width;
1914if the window was moved, this will hold the new x position.
1915
1916
1917<procedure>(window-event-data2 event) → integer</procedure>
1918<setter>(set! (window-event-data2 event) val)</setter>
1919<setter>(window-event-data2-set! event val)</setter>
1920
1921Get or set the sdl2:window-event's "data2" field, as an integer.
1922The meaning of this value depends on what kind of window event it was (see {{window-event-event}}).
1923E.g. if the window was resized, this will hold the new window height;
1924if the window was moved, this will hold the new y position.
1925
1926
1927
1928=== Hints
1929
1930[[https://wiki.libsdl.org/CategoryHints|Hints (aka Configuration Variables)]]
1931are a way for you to give hints to the SDL library about how you would like it to behave.
1932Most hints affect platform-specific behavior.
1933Hints are merely suggestions, and SDL may or may not obey them.
1934
1935Hints can also be specified or overriden by environment variables.
1936This allows the user to configure SDL to work best on their system.
1937Usually the environment variable is similar to the SDL constant name,
1938but prefixed with "SDL_" instead of "SDL_HINT_".
1939For more information see [[https://hg.libsdl.org/SDL/file/default/include/SDL_hints.h|SDL_hints.h]].
1940
1941Procedures for getting and setting hints is available in '''sdl2 egg version 0.2.0 and higher'''.
1942But, SDL will notice environment variables even if you are using an earlier version of the sdl2 egg.
1943
1944The tables below list the hint name symbol,
1945which you can pass to {{get-hint}} and {{set-hint!}},
1946and the corresponding SDL constant.
1947See the linked documentation for more information about what the hint does,
1948and valid values for the hint.
1949
1950Some hints are only effective after a certain version of SDL.
1951You may safely set the hint with any version of SDL,
1952but it will have no effect on older versions of SDL.
1953
1954==== Hints in SDL 2.0.0 and later
1955
1956<table>
1957  <tr>
1958    <th>Hint name symbol</th>
1959    <th>SDL constant name</th>
1960  </tr>
1961  <tr>
1962    <td>framebuffer-acceleration</td>
1963    <td>[[https://wiki.libsdl.org/SDL_HINT_FRAMEBUFFER_ACCELERATION|SDL_HINT_FRAMEBUFFER_ACCELERATION]]</td>
1964  </tr>
1965  <tr>
1966    <td>gamecontrollerconfig</td>
1967    <td>[[https://wiki.libsdl.org/SDL_HINT_GAMECONTROLLERCONFIG|SDL_HINT_GAMECONTROLLERCONFIG]]</td>
1968  </tr>
1969  <tr>
1970    <td>grab-keyboard</td>
1971    <td>[[https://wiki.libsdl.org/SDL_HINT_GRAB_KEYBOARD|SDL_HINT_GRAB_KEYBOARD]]</td>
1972  </tr>
1973  <tr>
1974    <td>idle-timer-disabled</td>
1975    <td>[[https://wiki.libsdl.org/SDL_HINT_IDLE_TIMER_DISABLED|SDL_HINT_IDLE_TIMER_DISABLED]]</td>
1976  </tr>
1977  <tr>
1978    <td>joystick-allow-background-events</td>
1979    <td>[[https://wiki.libsdl.org/SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS|SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS]]</td>
1980  </tr>
1981  <tr>
1982    <td>orientations</td>
1983    <td>[[https://wiki.libsdl.org/SDL_HINT_ORIENTATIONS|SDL_HINT_ORIENTATIONS]]</td>
1984  </tr>
1985  <tr>
1986    <td>render-driver</td>
1987    <td>[[https://wiki.libsdl.org/SDL_HINT_RENDER_DRIVER|SDL_HINT_RENDER_DRIVER]]</td>
1988  </tr>
1989  <tr>
1990    <td>render-opengl-shaders</td>
1991    <td>[[https://wiki.libsdl.org/SDL_HINT_RENDER_OPENGL_SHADERS|SDL_HINT_RENDER_OPENGL_SHADERS]]</td>
1992  </tr>
1993  <tr>
1994    <td>render-scale-quality</td>
1995    <td>[[https://wiki.libsdl.org/SDL_HINT_RENDER_SCALE_QUALITY|SDL_HINT_RENDER_SCALE_QUALITY]]</td>
1996  </tr>
1997  <tr>
1998    <td>render-vsync</td>
1999    <td>[[https://wiki.libsdl.org/SDL_HINT_RENDER_VSYNC|SDL_HINT_RENDER_VSYNC]]</td>
2000  </tr>
2001  <tr>
2002    <td>timer-resolution</td>
2003    <td>[[https://wiki.libsdl.org/SDL_HINT_TIMER_RESOLUTION|SDL_HINT_TIMER_RESOLUTION]]</td>
2004  </tr>
2005  <tr>
2006    <td>video-minimize-on-focus-loss</td>
2007    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS|SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS]]</td>
2008  </tr>
2009  <tr>
2010    <td>video-x11-xinerama</td>
2011    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_X11_XINERAMA|SDL_HINT_VIDEO_X11_XINERAMA]]</td>
2012  </tr>
2013  <tr>
2014    <td>video-x11-xrandr</td>
2015    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_X11_XRANDR|SDL_HINT_VIDEO_X11_XRANDR]]</td>
2016  </tr>
2017  <tr>
2018    <td>video-x11-xvidmode</td>
2019    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_X11_XVIDMODE|SDL_HINT_VIDEO_X11_XVIDMODE]]</td>
2020  </tr>
2021  <tr>
2022    <td>xinput-enabled</td>
2023    <td>[[https://wiki.libsdl.org/SDL_HINT_XINPUT_ENABLED|SDL_HINT_XINPUT_ENABLED]]</td>
2024  </tr>
2025</table>
2026
2027==== Hints in SDL 2.0.1 and later
2028
2029<table>
2030  <tr>
2031    <th>Hint name symbol</th>
2032    <th>SDL constant name</th>
2033  </tr>
2034  <tr>
2035    <td>render-direct3d-threadsafe</td>
2036    <td>[[https://wiki.libsdl.org/SDL_HINT_RENDER_DIRECT3D_THREADSAFE|SDL_HINT_RENDER_DIRECT3D_THREADSAFE]]</td>
2037  </tr>
2038  <tr>
2039    <td>video-highdpi-disabled</td>
2040    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_HIGHDPI_DISABLED|SDL_HINT_VIDEO_HIGHDPI_DISABLED]]</td>
2041  </tr>
2042</table>
2043
2044
2045==== Hints in SDL 2.0.2 and later
2046
2047<table>
2048  <tr>
2049    <th>Hint name symbol</th>
2050    <th>SDL constant name</th>
2051  </tr>
2052  <tr>
2053    <td>accelerometer-as-joystick</td>
2054    <td>[[https://wiki.libsdl.org/SDL_HINT_ACCELEROMETER_AS_JOYSTICK|SDL_HINT_ACCELEROMETER_AS_JOYSTICK]]</td>
2055  </tr>
2056  <tr>
2057    <td>mac-ctrl-click-emulate-right-click</td>
2058    <td>[[https://wiki.libsdl.org/SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK|SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK]]</td>
2059  </tr>
2060  <tr>
2061    <td>mouse-relative-mode-warp</td>
2062    <td>[[https://wiki.libsdl.org/SDL_HINT_MOUSE_RELATIVE_MODE_WARP|SDL_HINT_MOUSE_RELATIVE_MODE_WARP]]</td>
2063  </tr>
2064  <tr>
2065    <td>video-allow-screensaver</td>
2066    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_ALLOW_SCREENSAVER|SDL_HINT_VIDEO_ALLOW_SCREENSAVER]]</td>
2067  </tr>
2068  <tr>
2069    <td>video-mac-fullscreen-spaces</td>
2070    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES|SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES]]</td>
2071  </tr>
2072  <tr>
2073    <td>video-window-share-pixel-format</td>
2074    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT|SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT]]</td>
2075  </tr>
2076  <tr>
2077    <td>video-win-d3dcompiler</td>
2078    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_WIN_D3DCOMPILER|SDL_HINT_VIDEO_WIN_D3DCOMPILER]]</td>
2079  </tr>
2080</table>
2081
2082
2083==== Hints in SDL 2.0.3 and later
2084
2085<table>
2086  <tr>
2087    <th>Hint name symbol</th>
2088    <th>SDL constant name</th>
2089  </tr>
2090  <tr>
2091    <td>render-direct3d11-debug</td>
2092    <td>[[https://wiki.libsdl.org/SDL_HINT_RENDER_DIRECT3D11_DEBUG|SDL_HINT_RENDER_DIRECT3D11_DEBUG]]</td>
2093  </tr>
2094  <tr>
2095    <td>winrt-handle-back-button</td>
2096    <td>[[https://wiki.libsdl.org/SDL_HINT_WINRT_HANDLE_BACK_BUTTON|SDL_HINT_WINRT_HANDLE_BACK_BUTTON]]</td>
2097  </tr>
2098  <tr>
2099    <td>winrt-privacy-policy-label</td>
2100    <td>[[https://wiki.libsdl.org/SDL_HINT_WINRT_PRIVACY_POLICY_LABEL|SDL_HINT_WINRT_PRIVACY_POLICY_LABEL]]</td>
2101  </tr>
2102  <tr>
2103    <td>winrt-privacy-policy-url</td>
2104    <td>[[https://wiki.libsdl.org/SDL_HINT_WINRT_PRIVACY_POLICY_URL|SDL_HINT_WINRT_PRIVACY_POLICY_URL]]</td>
2105  </tr>
2106</table>
2107
2108
2109==== Hints in SDL 2.0.4 and later
2110
2111<table>
2112  <tr>
2113    <th>Hint name symbol</th>
2114    <th>SDL constant name</th>
2115  </tr>
2116  <tr>
2117    <td>android-apk-expansion-main-file-version</td>
2118    <td>[[https://wiki.libsdl.org/SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION|SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION]]</td>
2119  </tr>
2120  <tr>
2121    <td>android-apk-expansion-patch-file-version</td>
2122    <td>[[https://wiki.libsdl.org/SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION|SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION]]</td>
2123  </tr>
2124  <tr>
2125    <td>android-separate-mouse-and-touch</td>
2126    <td>[[https://wiki.libsdl.org/SDL_HINT_ANDROID_SEPARATE_MOUSE_AND_TOUCH|SDL_HINT_ANDROID_SEPARATE_MOUSE_AND_TOUCH]]</td>
2127  </tr>
2128  <tr>
2129    <td>emscripten-keyboard-element</td>
2130    <td>[[https://wiki.libsdl.org/SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT|SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT]]</td>
2131  </tr>
2132  <tr>
2133    <td>ime-internal-editing</td>
2134    <td>[[https://wiki.libsdl.org/SDL_HINT_IME_INTERNAL_EDITING|SDL_HINT_IME_INTERNAL_EDITING]]</td>
2135  </tr>
2136  <tr>
2137    <td>mac-background-app</td>
2138    <td>[[https://wiki.libsdl.org/SDL_HINT_MAC_BACKGROUND_APP|SDL_HINT_MAC_BACKGROUND_APP]]</td>
2139  </tr>
2140  <tr>
2141    <td>no-signal-handlers</td>
2142    <td>[[https://wiki.libsdl.org/SDL_HINT_NO_SIGNAL_HANDLERS|SDL_HINT_NO_SIGNAL_HANDLERS]]</td>
2143  </tr>
2144  <tr>
2145    <td>thread-stack-size</td>
2146    <td>[[https://wiki.libsdl.org/SDL_HINT_THREAD_STACK_SIZE|SDL_HINT_THREAD_STACK_SIZE]]</td>
2147  </tr>
2148  <tr>
2149    <td>video-x11-net-wm-ping</td>
2150    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_X11_NET_WM_PING|SDL_HINT_VIDEO_X11_NET_WM_PING]]</td>
2151  </tr>
2152  <tr>
2153    <td>windows-enable-messageloop</td>
2154    <td>[[https://wiki.libsdl.org/SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP|SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP]]</td>
2155  </tr>
2156  <tr>
2157    <td>windows-no-close-on-alt-f4</td>
2158    <td>[[https://wiki.libsdl.org/SDL_HINT_WINDOWS_NO_CLOSE_ON_ALT_F4|SDL_HINT_WINDOWS_NO_CLOSE_ON_ALT_F4]]</td>
2159  </tr>
2160  <tr>
2161    <td>window-frame-usable-while-cursor-hidden</td>
2162    <td>[[https://wiki.libsdl.org/SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN|SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN]]</td>
2163  </tr>
2164  <tr>
2165    <td>xinput-use-old-joystick-mapping</td>
2166    <td>[[https://wiki.libsdl.org/SDL_HINT_XINPUT_USE_OLD_JOYSTICK_MAPPING|SDL_HINT_XINPUT_USE_OLD_JOYSTICK_MAPPING]]</td>
2167  </tr>
2168</table>
2169
2170==== Hint Functions
2171
2172<procedure>(get-hint name) → string or #f</procedure>
2173
2174Returns the current value of the hint as a string, or #f if the hint has no value.
2175See [[https://wiki.libsdl.org/SDL_GetHint|SDL_GetHint]].
2176This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
2177
2178
2179<procedure>(set-hint! name value #!optional priority) → boolean</procedure>
2180
2181Sets the value of the hint.
2182See [[https://wiki.libsdl.org/SDL_SetHintWithPriority|SDL_SetHintWithPriority]].
2183This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
2184
2185{{name}} specifies which hint to change.
2186It must be a symbol from the tables above, or a string.
2187This procedure signals an exception if {{name}} is an unrecognized symbol
2188(i.e. is not listed in any of the tables above).
2189This procedures accepts any string name, even if it is not recognized.
2190
2191{{value}} specifies the new value of the hint. It must be a string.
2192
2193{{priority}} specifies the priorily level for setting the hint.
2194If it is omitted, the priority will be {{'normal}}.
2195It must be one of these symbols:
2196
2197* {{'default}}
2198* {{'normal}}
2199* {{'override}}
2200
2201Returns #t if the hint's value was changed, or #f if it was not changed
2202(e.g. because the hint was already set with a higher priority).
2203
2204
2205<procedure>(clear-hints!)</procedure>
2206
2207Removes the values and priorities of all hints.
2208See [[https://wiki.libsdl.org/SDL_ClearHints|SDL_ClearHints]].
2209This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
2210
2211
2212
2213=== Joystick
2214
2215==== Joystick Functions
2216
2217<procedure>(num-joysticks) → integer</procedure>
2218
2219See [[https://wiki.libsdl.org/SDL_NumJoysticks|SDL_NumJoysticks]].
2220
2221Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2222
2223
2224<procedure>(joystick-open! index) → sdl2:joystick</procedure>
2225
2226See [[https://wiki.libsdl.org/SDL_JoystickOpen|SDL_JoystickOpen]].
2227
2228Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2229
2230
2231<procedure>(joystick-close! joystick)</procedure>
2232
2233See [[https://wiki.libsdl.org/SDL_JoystickClose|SDL_JoystickClose]].
2234
2235
2236<procedure>(joystick-from-instance-id id) → sdl2:joystick</procedure>
2237
2238See [[https://wiki.libsdl.org/SDL_JoystickFromInstanceID|SDL_JoystickFromInstanceID]].
2239
2240'''NOTE:''' The returned joystick will be a new sdl2:joystick record pointing to the address of the existing joystick.
2241It will be {{equal?}} to other sdl2:joystick records for the same joystick, but not {{eq?}}.
2242
2243This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
2244It requires '''SDL 2.0.4 or higher'''.
2245It signals an error if the compiled version of SDL is not high enough.
2246Use the [[#version-feature-identifiers|{{libSDL-2.0.4+}} feature identifier]]
2247to check before calling this procedure.
2248
2249
2250<procedure>(joystick-update!)</procedure>
2251
2252See [[https://wiki.libsdl.org/SDL_JoystickUpdate|SDL_JoystickUpdate]].
2253
2254
2255<procedure>(joystick-event-state) → boolean</procedure>
2256<setter>(set! (joystick-event-state) state) → boolean</setter>
2257<setter>(joystick-event-state-set! state) → boolean</setter>
2258
2259{{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).
2260
2261The setters enable (if {{state}} is #t) or disable (if {{state}} is #f) joytsick events.
2262'''WARNING:''' Calling the setters may delete all events currently in the event queue.
2263
2264These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
2265
2266See [[https://wiki.libsdl.org/SDL_JoystickEventState|SDL_JoystickEventState]].
2267
2268
2269<procedure>(joystick-name-for-index device-index) → string or #f</procedure>
2270
2271See [[https://wiki.libsdl.org/SDL_JoystickNameForIndex|SDL_JoystickNameForIndex]].
2272
2273Returns #f if no name can be found.
2274
2275
2276<procedure>(joystick-get-device-guid device-index) → sdl2:joystick-guid</procedure>
2277
2278See [[https://wiki.libsdl.org/SDL_JoystickGetDeviceGUID|SDL_JoystickGetDeviceGUID]].
2279
2280Returns a new managed sdl2:joystick-guid.
2281
2282
2283==== sdl2:joystick
2284
2285sdl2:joystick is a record type that wraps a pointer to an
2286[[https://wiki.libsdl.org/SDL_Joystick|SDL_Joystick]] struct.
2287
2288
2289<procedure>(joystick? obj) → boolean</procedure>
2290
2291Returns #t if {{obj}} is an sdl2:joystick.
2292
2293
2294<procedure>(joystick-instance-id joystick) → integer</procedure>
2295
2296See [[https://wiki.libsdl.org/SDL_JoystickInstanceID|SDL_JoystickInstanceID]].
2297
2298Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2299
2300
2301<procedure>(joystick-name joystick) → string or #f</procedure>
2302
2303See [[https://wiki.libsdl.org/SDL_JoystickName|SDL_JoystickName]].
2304
2305Returns #f if no name can be found.
2306
2307
2308<procedure>(joystick-get-guid joystick) → sdl2:joystick-guid</procedure>
2309
2310See [[https://wiki.libsdl.org/SDL_JoystickGetGUID|SDL_JoystickGetGUID]].
2311
2312Returns a new managed sdl2:joystick-guid.
2313
2314
2315<procedure>(joystick-attached? joystick) → boolean</procedure>
2316
2317See [[https://wiki.libsdl.org/SDL_JoystickGetAttached|SDL_JoystickGetAttached]].
2318
2319
2320<procedure>(joystick-current-power-level joystick) → symbol</procedure>
2321
2322See [[https://wiki.libsdl.org/SDL_JoystickCurrentPowerLevel|SDL_JoystickCurrentPowerLevel]].
2323
2324Returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#joystick-power-level|joystick power level enum symbol]]:
2325
2326* {{'unknown}}
2327* {{'empty}}
2328* {{'low}}
2329* {{'medium}}
2330* {{'full}}
2331* {{'wired}}
2332* {{'max}}
2333
2334This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
2335It requires '''SDL 2.0.4 or higher'''.
2336It signals an error if the compiled version of SDL is not high enough.
2337Use the [[#version-feature-identifiers|{{libSDL-2.0.4+}} feature identifier]]
2338to check before calling this procedure.
2339
2340
2341<procedure>(joystick-num-axes joystick) → integer</procedure>
2342
2343See [[https://wiki.libsdl.org/SDL_JoystickNumAxes|SDL_JoystickNumAxes]].
2344
2345Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2346
2347
2348<procedure>(joystick-num-balls joystick) → integer</procedure>
2349
2350See [[https://wiki.libsdl.org/SDL_JoystickNumBalls|SDL_JoystickNumBalls]].
2351
2352Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2353
2354
2355<procedure>(joystick-num-buttons joystick) → integer</procedure>
2356
2357See [[https://wiki.libsdl.org/SDL_JoystickNumButtons|SDL_JoystickNumButtons]].
2358
2359Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2360
2361
2362<procedure>(joystick-num-hats joystick) → integer</procedure>
2363
2364See [[https://wiki.libsdl.org/SDL_JoystickNumHats|SDL_JoystickNumHats]].
2365
2366Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2367
2368
2369<procedure>(joystick-get-axis joystick axis-num) → integer</procedure>
2370
2371See [[https://wiki.libsdl.org/SDL_JoystickGetAxis|SDL_JoystickGetAxis]].
2372
2373Signals 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}}).
2374
2375
2376<procedure>(joystick-get-ball joystick ball-num) → [dx dy]</procedure>
2377
2378See [[https://wiki.libsdl.org/SDL_JoystickGetBall|SDL_JoystickGetBall]].
2379
2380This procedure returns multiple values.
2381
2382Signals 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}}).
2383Signals an exception of kind {{(exn sdl2)}} if some other error occurs.
2384
2385
2386<procedure>(joystick-get-button joystick button-num) → boolean</procedure>
2387
2388See [[https://wiki.libsdl.org/SDL_JoystickGetButton|SDL_JoystickGetButton]].
2389
2390Signals 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}}).
2391
2392
2393<procedure>(joystick-get-hat joystick hat-num) → symbol</procedure>
2394<procedure>(joystick-get-hat-raw joystick hat-num) → integer</procedure>
2395
2396See [[https://wiki.libsdl.org/SDL_JoystickGetHat|SDL_JoystickGetHat]].
2397
2398* {{joystick-get-hat}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#joystick-hat-position|joystick hat position symbol]].
2399* {{joystick-get-hat-raw}} returns an integer.
2400
2401Both 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}}).
2402
2403
2404
2405==== sdl2:joystick-guid
2406
2407sdl2:joystick-guid is a record type that wraps a pointer to an
2408[[https://wiki.libsdl.org/SDL_JoystickGetGUID|SDL_JoystickGUID]]
2409struct.
2410
2411
2412<procedure>(joystick-guid? obj) → boolean</procedure>
2413
2414Returns #t if {{obj}} is an sdl2:joystick-guid.
2415
2416
2417<procedure>(free-joystick-guid! guid)</procedure>
2418
2419Free the memory of the sdl2:joystick-guid's underlying struct.
2420{{guid}}'s pointer will be set to null (see {{struct-null?}}). It is
2421safe to call this procedure with managed or unmanaged
2422sdl2:joystick-guids. It is safe (but has no effect) to free a struct
2423record multiple times.
2424
2425
2426<procedure>(joystick-get-guid-from-string str) → sdl2:joystick-guid</procedure>
2427
2428See [[https://wiki.libsdl.org/SDL_JoystickGetGUIDFromString|SDL_JoystickGetGUIDFromString]].
2429
2430Returns a new managed sdl2:joystick-guid.
2431
2432
2433<procedure>(joystick-get-guid-string guid) → string</procedure>
2434
2435See [[https://wiki.libsdl.org/SDL_JoystickGetGUIDString|SDL_JoystickGetGUIDString]].
2436
2437
2438
2439=== Keyboard
2440
2441==== Keyboard Functions
2442
2443<procedure>(get-key-from-name name-str) → symbol</procedure>
2444<procedure>(get-key-from-name-raw name-str) → integer</procedure>
2445
2446See [[https://wiki.libsdl.org/SDL_GetKeyFromName|SDL_GetKeyFromName]].
2447
2448* {{get-key-from-name}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]].
2449* {{get-key-from-name-raw}} returns an integer.
2450
2451
2452<procedure>(get-key-from-scancode scancode) → symbol</procedure>
2453<procedure>(get-key-from-scancode-raw scancode) → integer</procedure>
2454
2455See [[https://wiki.libsdl.org/SDL_GetKeyFromScancode|SDL_GetKeyFromScancode]].
2456
2457{{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.
2458
2459* {{get-key-from-scancode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]].
2460* {{get-key-from-scancode-raw}} returns an integer.
2461
2462
2463<procedure>(get-key-name key) → string</procedure>
2464
2465See [[https://wiki.libsdl.org/SDL_GetKeyName|SDL_GetKeyName]].
2466
2467{{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.
2468
2469
2470<procedure>(get-scancode-from-name name-str) → symbol</procedure>
2471<procedure>(get-scancode-from-name-raw name-str) → integer</procedure>
2472
2473See [[https://wiki.libsdl.org/SDL_GetScancodeFromName|SDL_GetScancodeFromName]].
2474
2475* {{get-scancode-from-name}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]].
2476* {{get-scancode-from-name-raw}} returns an integer.
2477
2478
2479<procedure>(get-scancode-from-key key) → symbol</procedure>
2480<procedure>(get-scancode-from-key-raw key) → integer</procedure>
2481
2482See [[https://wiki.libsdl.org/SDL_GetScancodeFromKey|SDL_GetScancodeFromKey]].
2483
2484{{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.
2485
2486* {{get-scancode-from-key}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]].
2487* {{get-scancode-from-key-raw}} returns an integer.
2488
2489
2490<procedure>(get-scancode-name scancode) → string</procedure>
2491
2492See [[https://wiki.libsdl.org/SDL_GetScancodeName|SDL_GetScancodeName]].
2493
2494{{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.
2495
2496
2497<procedure>(get-keyboard-focus) → sdl2:window</procedure>
2498
2499See [[https://wiki.libsdl.org/SDL_GetKeyboardFocus|SDL_GetKeyboardFocus]].
2500
2501
2502<procedure>(scancode-pressed? scancode) → boolean</procedure>
2503
2504Returns #t if the keyboard key with the given scancode is currently
2505being pressed.
2506
2507{{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.
2508
2509This procedure queries SDL's internal keyboard state, which is tied to
2510the event system. Call {{pump-events!}} to update the keyboard state.
2511
2512This procedure is based on
2513[[https://wiki.libsdl.org/SDL_GetKeyboardState|SDL_GetKeyboardState]].
2514
2515
2516<procedure>(mod-state) → list of symbols </procedure>
2517<procedure>(mod-state-raw) → integer</procedure>
2518<setter>(set! (mod-state) state)</setter>
2519<setter>(mod-state-set! state)</setter>
2520
2521See [[https://wiki.libsdl.org/SDL_GetModState|SDL_GetModState]].
2522
2523* {{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]].
2524* {{mod-state-raw}} returns an integer representing a bitfield of keyboard modifiers.
2525* The setters accept either a list of zero or more symbols, or an integer.
2526
2527
2528<setter>(text-input-rect-set! rect)</setter>
2529
2530{{rect}} can be an sdl2:rect or #f.
2531
2532See [[https://wiki.libsdl.org/SDL_SetTextInputRect|SDL_SetTextInputRect]].
2533
2534
2535<procedure>(start-text-input!)</procedure>
2536
2537See [[https://wiki.libsdl.org/SDL_StartTextInput|SDL_StartTextInput]].
2538
2539
2540<procedure>(stop-text-input!)</procedure>
2541
2542See [[https://wiki.libsdl.org/SDL_StopTextInput|SDL_StopTextInput]].
2543
2544
2545<procedure>(text-input-active?) → boolean</procedure>
2546
2547See [[https://wiki.libsdl.org/SDL_IsTextInputActive|SDL_IsTextInputActive]].
2548
2549
2550<procedure>(screen-keyboard-support?) → boolean</procedure>
2551
2552See [[https://wiki.libsdl.org/SDL_HasScreenKeyboardSupport|SDL_HasScreenKeyboardSupport]].
2553
2554
2555<procedure>(screen-keyboard-shown? window) → boolean</procedure>
2556
2557See [[https://wiki.libsdl.org/SDL_IsScreenKeyboardShown|SDL_IsScreenKeyboardShown]].
2558
2559
2560==== sdl2:keysym
2561
2562sdl2:keysym is a record type that wraps a pointer to an
2563[[https://wiki.libsdl.org/SDL_Keysym|SDL_Keysym]] struct.
2564
2565
2566<procedure>(keysym? obj) → boolean</procedure>
2567
2568Returns #t if {{obj}} is an sdl2:keysym.
2569
2570
2571<procedure>(make-keysym #!optional scancode sym mod) → sdl2:keysym</procedure>
2572<procedure>(make-keysym* #!optional scancode sym mod) → sdl2:keysym</procedure>
2573
2574Allocate and initialize a new sdl2:keysym.
2575
2576{{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.
2577
2578{{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.
2579
2580{{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.
2581
2582* {{make-keysym}} returns a managed sdl2:keysym.
2583* {{make-keysym*}} returns an unmanaged sdl2:keysym, which must be freed with {{free-keysym!}} when you are done with it.
2584
2585
2586<procedure>(free-keysym! keysym)</procedure>
2587
2588Free the memory of the sdl2:keysym's underlying struct. {{keysym}}'s
2589pointer will be set to null (see {{struct-null?}}). It is safe to call
2590this procedure with managed or unmanaged sdl2:keysyms. It is safe (but
2591has no effect) to free a struct record multiple times.
2592
2593
2594<procedure>(keysym-scancode keysym) → symbol</procedure>
2595<procedure>(keysym-scancode-raw keysym) → integer</procedure>
2596<setter>(set! (keysym-scancode keysym) val)</setter>
2597<setter>(keysym-scancode-set! keysym val)</setter>
2598
2599Get or set the sdl2:keysym's "scancode" field, indicating the physical key that this keysym describes.
2600
2601* {{keysym-scancode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]].
2602* {{keysym-scancode-raw}} returns an integer.
2603* The setters accept either a symbol or an integer.
2604
2605
2606<procedure>(keysym-sym keysym) → symbol</procedure>
2607<procedure>(keysym-sym-raw keysym) → integer</procedure>
2608<setter>(set! (keysym-sym keysym) val)</setter>
2609<setter>(keysym-sym-set! keysym val)</setter>
2610
2611Get or set the sdl2:keysym's "sym" field, indicating the logical key that this keysym describes.
2612
2613* {{keysym-sym}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]].
2614* {{keysym-sym-raw}} returns an integer.
2615* The setters accept either a symbol or an integer.
2616
2617
2618<procedure>(keysym-mod keysym) → list of symbols</procedure>
2619<procedure>(keysym-mod-raw keysym) → integer</procedure>
2620<setter>(set! (keysym-mod keysym) val)</setter>
2621<setter>(keysym-mod-set! keysym val)</setter>
2622
2623Get or set the sdl2:keysym's "mod" field, indicating the modifier keys that this keysym describes.
2624
2625* {{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]].
2626* {{keysym-mod-raw}} returns an integer.
2627* The setters accept either a list of zero or more symbols, or an integer.
2628
2629
2630
2631=== OpenGL
2632
2633==== OpenGL Functions
2634
2635<procedure>(gl-create-context! window) → sdl2:gl-context</procedure>
2636
2637See [[https://wiki.libsdl.org/SDL_GL_CreateContext|SDL_GL_CreateContext]].
2638
2639Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2640
2641
2642<procedure>(gl-delete-context! gl-context)</procedure>
2643
2644See [[https://wiki.libsdl.org/SDL_GL_DeleteContext|SDL_GL_DeleteContext]].
2645
2646
2647<procedure>(gl-make-current! window gl-context)</procedure>
2648
2649See [[https://wiki.libsdl.org/SDL_GL_MakeCurrent|SDL_GL_MakeCurrent]].
2650
2651Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2652
2653
2654<procedure>(gl-get-current-window) → sdl2:window</procedure>
2655
2656See [[https://wiki.libsdl.org/SDL_GL_GetCurrentWindow|SDL_GL_GetCurrentWindow]].
2657
2658Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2659
2660
2661<procedure>(gl-get-current-context) → sdl2:gl-context</procedure>
2662
2663See [[https://wiki.libsdl.org/SDL_GL_GetCurrentContext|SDL_GL_GetCurrentContext]].
2664
2665Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2666
2667
2668<procedure>(gl-attribute attr) → value</procedure>
2669<setter>(set! (gl-attribute attr) value)</setter>
2670<setter>(gl-attribute-set! attr value)</setter>
2671
2672See [[https://wiki.libsdl.org/SDL_GL_GetAttribute|SDL_GL_GetAttribute]]
2673and [[https://wiki.libsdl.org/SDL_GL_SetAttribute|SDL_GL_SetAttribute]].
2674
2675{{attr}} must be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#opengl-attributes|OpenGL attribute symbol]] or corresponding integer.
2676
2677The value's type depends on {{attr}}:
2678
2679* 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.)
2680
2681* 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.)
2682
2683* If {{attr}} is {{'context-release-flags}}, the value will be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#opengl-context-release-flags|OpenGL context release flag symbol]]: {{'none}} or {{'flush}}. (This attribute requires '''SDL 2.0.4 and higher''' and '''sdl2 egg version 0.2.0 or higher'''.)
2684
2685* Otherwise, the value is an integer.
2686
2687The getter and the setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
2688
2689
2690<procedure>(gl-reset-attributes!)</procedure>
2691
2692See [[https://wiki.libsdl.org/SDL_GL_ResetAttributes|SDL_GL_ResetAttributes]].
2693
2694Requires '''SDL 2.0.2 or higher'''.
2695Signals an error if the compiled version of SDL is not high enough.
2696Use the [[#version-feature-identifiers|{{libSDL-2.0.2+}} feature identifier]]
2697to check before calling this procedure.
2698
2699
2700<procedure>(gl-get-drawable-size window) → [width height]</procedure>
2701
2702See [[https://wiki.libsdl.org/SDL_GL_GetDrawableSize|SDL_GL_GetDrawableSize]].
2703
2704This procedure returns multiple values.
2705
2706Requires '''SDL 2.0.1 or higher'''.
2707Signals an error if the compiled version of SDL is not high enough.
2708Use the [[#version-feature-identifiers|{{libSDL-2.0.1+}} feature identifier]]
2709to check before calling this procedure.
2710
2711
2712<procedure>(gl-swap-window!)</procedure>
2713
2714See [[https://wiki.libsdl.org/SDL_GL_SwapWindow|SDL_GL_SwapWindow]].
2715
2716
2717<procedure>(gl-swap-interval) → integer</procedure>
2718<setter>(set! (gl-swap-interval) interval)</setter>
2719<setter>(gl-set-swap-interval! interval)</setter>
2720
2721See [[https://wiki.libsdl.org/SDL_GL_GetSwapInterval|SDL_GL_GetSwapInterval]]
2722and [[https://wiki.libsdl.org/SDL_GL_SetSwapInterval|SDL_GL_SetSwapInterval]].
2723
2724The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
2725
2726
2727<procedure>(gl-extension-supported? name-string) → boolean</procedure>
2728
2729See [[https://wiki.libsdl.org/SDL_GL_ExtensionSupported|SDL_GL_ExtensionSupported]].
2730
2731
2732<procedure>(gl-bind-texture! texture) → [tex-w tex-h]</procedure>
2733
2734Bind the given sdl2:texture for use with the current OpenGL context.
2735See [[https://wiki.libsdl.org/SDL_GL_BindTexture|SDL_GL_BindTexture]].
2736
2737Returns multiple values:
2738
2739; tex-w : The bound OpenGL texture's width, as a float (usually 1.0)
2740; tex-h : The bound OpenGL texture's height, as a float (usually 1.0)
2741
2742Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2743
2744This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
2745
2746
2747<procedure>(gl-unbind-texture! texture)</procedure>
2748
2749Unbind the given sdl2:texture from the OpenGL context.
2750See [[https://wiki.libsdl.org/SDL_GL_UnbindTexture|SDL_GL_UnbindTexture]].
2751
2752Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2753
2754This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
2755
2756
2757
2758==== sdl2:gl-context
2759
2760sdl2:gl-context is a record type that wraps a pointer to an SDL_GLContext struct.
2761
2762<procedure>(gl-context? obj) → boolean</procedure>
2763
2764Returns #t if {{obj}} is an sdl2:gl-context.
2765
2766
2767
2768=== Palette
2769
2770==== sdl2:palette
2771
2772sdl2:palette is a record type that wraps a pointer to an
2773[[https://wiki.libsdl.org/SDL_Palette|SDL_Palette]] struct.
2774
2775
2776<procedure>(palette? obj) → boolean</procedure>
2777
2778Returns #t if {{obj}} is an sdl2:palette.
2779
2780
2781<procedure>(make-palette #!optional ncolors) → sdl2:palette</procedure>
2782<procedure>(make-palette* #!optional ncolors) → sdl2:palette</procedure>
2783
2784Allocate and initialize a new sdl2:palette with the given number of colors.
2785See [[https://wiki.libsdl.org/SDL_AllocPalette|SDL_AllocPalette]].
2786
2787{{ncolors}} defaults to 256.
2788Common values are 2 (for a 1-bit surface), 16 (for a 4-bit surface), and 256 (for an 8-bit surface).
2789
2790'''NOTE:''' Usually you do not need to manually allocate a palette. A
2791palette will be created for you when you create a surface with a depth
2792of 8 or lower, and the palette will be automatically freed when the
2793surface is freed (unless the palette is still being used by other
2794surfaces).
2795
2796* {{make-palette}} returns a managed sdl2:palette.
2797* {{make-palette*}} returns an unmanaged sdl2:palette, which must be freed with {{free-palette!}} when you are done with it.
2798
2799Both procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
2800
2801
2802<procedure>(free-palette! palette)</procedure>
2803
2804Free the memory of the sdl2:palette's underlying struct. {{palette}}'s
2805pointer will be set to null (see {{struct-null?}}). It is safe to call
2806this procedure with managed or unmanaged sdl2:palettes. It is safe
2807(but has no effect) to free a struct record multiple times.
2808
2809See [[https://wiki.libsdl.org/SDL_FreePalette|SDL_FreePalette]].
2810
2811
2812<procedure>(palette-ncolors palette) → integer</procedure>
2813<procedure>(palette-ncolours palette) → integer</procedure>
2814
2815Returns the number of colors in the palette.
2816Common values are 2 (for a 1-bit surface), 16 (for a 4-bit surface), and 256 (for an 8-bit surface).
2817
2818
2819<procedure>(palette-ref palette i) → sdl2:color</procedure>
2820<setter>(set! (palette-ref palette i) color)</setter>
2821<setter>(palette-set! palette i color)</setter>
2822
2823{{palette-ref}} returns a copy of the color at the given index of the palette, as a managed sdl2:color.
2824
2825The setters set the given index of the palette to a copy of the given sdl2:color.
2826
2827These procedures signal an exception of kind {{(exn bounds)}} if the given index is out of bounds.
2828
2829
2830<procedure>(palette-colors palette) → vector of sdl2:colors </procedure>
2831<procedure>(palette-colours palette) → vector of sdl2:colors </procedure>
2832<setter>(set! (palette-colors palette) colors-vec) → boolean</setter>
2833<setter>(set! (palette-colours palette) colors-vec) → boolean</setter>
2834<setter>(palette-colors-set! colors-vec #!optional firstcolor) → boolean</setter>
2835<setter>(palette-colours-set! colors-vec #!optional firstcolor) → boolean</setter>
2836
2837{{palette-colors}} and {{palette-colours}} return copies of all colors in the palette, as a Scheme vector of managed sdl2:colors.
2838
2839The setters set multiple colors in the palette to copies of the given colors.
2840See [[https://wiki.libsdl.org/SDL_SetPaletteColors|SDL_SetPaletteColors]].
2841
2842{{colors-vec}} must be a Scheme vector of sdl2:colors.
2843
2844{{firstcolor}} specifies the first index of the palette to set.
2845I.e., palette index {{firstcolor}} will be set to the first color in {{colors-vec}},
2846palette index {{firstcolor + 1}} will be set to the second color, and so on.
2847{{firstcolor}} defaults to 0.
2848Signals an exception of kind {{(exn bounds)}} if {{firstcolor}} is out of bounds.
2849
2850The {{set!}} form cannot accept the {{firstcolor}} argument.
2851
2852The setters return #t if every color in {{colors-vec}} was used, or #f if some colors were not used,
2853e.g. because there were more colors in the vector than could fit in the palette.
2854
2855
2856
2857=== Pixel Format
2858
2859==== Pixel Format Functions
2860
2861<procedure>(map-rgb pixel-format r g b) → integer</procedure>
2862<procedure>(map-rgba pixel-format r g b a) → integer</procedure>
2863
2864See [[https://wiki.libsdl.org/SDL_MapRGB|SDL_MapRGB]]
2865and [[https://wiki.libsdl.org/SDL_MapRGBA|SDL_MapRGBA]].
2866
2867
2868<procedure>(get-rgb pixel pixel-format) → [r g b]</procedure>
2869<procedure>(get-rgba pixel pixel-format) → [r g b a]</procedure>
2870
2871See [[https://wiki.libsdl.org/SDL_GetRGB|SDL_GetRGB]]
2872and [[https://wiki.libsdl.org/SDL_GetRGBA|SDL_GetRGBA]].
2873
2874These procedures return multiple values.
2875
2876
2877<procedure>(pixel-format-enum-to-masks format-enum) → [bpp rmask gmask bmask amask]</procedure>
2878
2879See [[https://wiki.libsdl.org/SDL_PixelFormatEnumToMasks|SDL_PixelFormatEnumToMasks]].
2880
2881{{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.
2882
2883This procedure returns multiple values:
2884
2885; bpp   : The color depth (bits per pixel) of the format.
2886; rmask : The red mask of the format.
2887; gmask : The green mask of the format.
2888; bmask : The blue mask of the format.
2889; amask : The alpha mask of the format.
2890
2891Signals an exception of kind {{(exn sdl2)}} if conversion was not possible.
2892
2893
2894==== sdl2:pixel-format
2895
2896sdl2:pixel-format is a record type that wraps a pointer to an
2897[[https://wiki.libsdl.org/SDL_PixelFormat|SDL_PixelFormat]] struct.
2898
2899
2900<procedure>(pixel-format? obj) → boolean</procedure>
2901
2902Returns #t if {{obj}} is an sdl2:pixel-format.
2903
2904
2905<procedure>(make-pixel-format #!optional format) → sdl2:pixel-format</procedure>
2906<procedure>(make-pixel-format* #!optional format) → sdl2:pixel-format</procedure>
2907
2908Allocate and initialize a new sdl2:pixel-format with the given format.
2909
2910{{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.
2911See [[https://wiki.libsdl.org/SDL_AllocFormat|SDL_AllocFormat]].
2912
2913* {{make-pixel-format}} returns a managed sdl2:pixel-format.
2914* {{make-pixel-format*}} returns an unmanaged sdl2:pixel-format, which must be freed with {{free-pixel-format!}} when you are done with it.
2915
2916Both procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
2917
2918
2919<procedure>(free-pixel-format! pixel-format)</procedure>
2920
2921Free the memory of the sdl2:pixel-format's underlying struct.
2922{{pixel-format}}'s pointer will be set to null (see {{struct-null?}}).
2923It is safe to call this procedure with managed or unmanaged
2924sdl2:pixel-formats. It is safe (but has no effect) to free a struct
2925record multiple times.
2926
2927See [[https://wiki.libsdl.org/SDL_FreeFormat|SDL_FreeFormat]].
2928
2929
2930<procedure>(pixel-format-format pixel-format) → symbol</procedure>
2931<procedure>(pixel-format-format-raw pixel-format) → integer</procedure>
2932
2933Get the sdl2:pixel-format's "format" field.
2934
2935* {{pixel-format-format}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]].
2936* {{pixel-format-format-raw}} returns an integer.
2937
2938
2939<procedure>(pixel-format-palette pixel-format) → sdl2:palette or #f</procedure>
2940<setter>(set! (pixel-format-palette pixel-format) val)</setter>
2941<setter>(pixel-format-palette-set! pixel-format val)</setter>
2942
2943Get or set the sdl2:pixel-format's "palette" field, as an sdl2:palette, or #f if it does not have a palette.
2944Only sdl2:pixel-formats with bits-per-pixel of 8 or less can have a palette.
2945
2946See [[https://wiki.libsdl.org/SDL_SetPixelFormatPalette|SDL_SetPixelFormatPalette]].
2947
2948The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
2949
2950
2951<procedure>(pixel-format-bits-per-pixel pixel-format) → integer</procedure>
2952
2953Get the sdl2:pixel-format's "bits-per-pixel" field, as an integer.
2954Common values are 32, 24, 16, 15, 8, 4, and 1.
2955
2956
2957<procedure>(pixel-format-bytes-per-pixel pixel-format) → integer</procedure>
2958
2959Get the sdl2:pixel-format's "bits-per-pixel" field, as an integer.
2960Possible values are 4, 3, 2, and 1.
2961
2962
2963<procedure>(pixel-format-rmask pixel-format) → integer</procedure>
2964
2965Get the sdl2:pixel-format's "rmask" (red mask) field, as a nonnegative integer.
2966
2967
2968<procedure>(pixel-format-gmask pixel-format) → integer</procedure>
2969
2970Get the sdl2:pixel-format's "gmask" (green mask) field, as a nonnegative integer.
2971
2972
2973<procedure>(pixel-format-bmask pixel-format) → integer</procedure>
2974
2975Get the sdl2:pixel-format's "bmask" (blue mask) field, as a nonnegative integer.
2976
2977
2978<procedure>(pixel-format-amask pixel-format) → integer</procedure>
2979
2980Get the sdl2:pixel-format's "amask" (alpha mask) field, as a nonnegative integer.
2981It will be 0 if there is no alpha channel.
2982
2983
2984
2985=== Rect / Point
2986
2987==== Rect / Point Functions
2988
2989<procedure>(rect-empty? rect) → boolean</procedure>
2990
2991Returns #t if {{rect}}'s width and/or height is less than or equal to zero.
2992See [[https://wiki.libsdl.org/SDL_RectEmpty|SDL_RectEmpty]].
2993
2994
2995<procedure>(point-in-rect? point rect) → boolean</procedure>
2996
2997Returns #t if the sdl2:point is inside the sdl2:rect, or #f if it is not.
2998See [[https://wiki.libsdl.org/SDL_PointInRects|SDL_PointInRect]].
2999
3000This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3001It requires '''SDL 2.0.4 or higher'''.
3002It signals an error if the compiled version of SDL is not high enough.
3003Use the [[#version-feature-identifiers|{{libSDL-2.0.4+}} feature identifier]]
3004to check before calling this procedure.
3005
3006
3007<procedure>(enclose-points points #!optional clip result-rect) → [rect any-enclosed?]</procedure>
3008
3009See [[https://wiki.libsdl.org/SDL_EnclosePoints|SDL_EnclosePoints]].
3010
3011{{points}} must be a list of sdl2:points.
3012
3013{{clip}} must be either an sdl2:rect or #f (the default).
3014If {{clip}} is an sdl2:rect, points outside the clip rect will be ignored.
3015
3016If {{result-rect}} is omitted or #f, a new managed sdl2:rect will be returned.
3017If {{result-rect}} is an sdl2:rect, it will be modified and returned.
3018It is safe for {{result-rect}} to be the same object as {{clip}},
3019in which case {{clip}} will be modified and returned.
3020
3021This procedure returns multiple values:
3022
3023; rect : An sdl2:rect that encloses all matching points. This will be the same object as {{result-rect}}, if {{result-rect}} was specified.
3024; any-enclosed? : #t if any points were enclosed, or #f if all points were clipped
3025
3026
3027<procedure>(has-intersection? rect1 rect2) → boolean</procedure>
3028
3029Returns #t if {{rect1}} and {{rect2}} intersect, or #f if they do not.
3030See [[https://wiki.libsdl.org/SDL_HasIntersection|SDL_HasIntersection]].
3031
3032
3033<procedure>(intersect-rect rect1 rect2 #!optional result-rect) → [rect intersect?]</procedure>
3034
3035Calculates the intersection of {{rect1}} and {{rect2}}.
3036See [[https://wiki.libsdl.org/SDL_IntersectRect|SDL_IntersectRect]].
3037
3038If {{result-rect}} is omitted or #f, a new managed sdl2:rect will be returned.
3039If {{result-rect}} is an sdl2:rect, it will be modified and returned.
3040It is safe for {{result-rect}} to be the same object as {{rect1}} or {{rect2}},
3041in which case {{rect1}} or {{rect2}} will be modified and returned.
3042It is safe (but useless) for {{rect1}} and {{rect2}} to be the same object.
3043
3044This procedure returns multiple values:
3045
3046; 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.
3047; intersect? : #t if {{rect1}} and {{rect2}} intersect, otherwise #f
3048
3049
3050<procedure>(intersect-rect-and-line rect x1 y1 x2 y2) → [intersect? x1-new y1-new x2-new y2-new]</procedure>
3051
3052Calculates the intersection between {{rect}} and the line segment described by {{x1}}, {{y1}}, {{x2}}, and {{y2}}.
3053See [[https://wiki.libsdl.org/SDL_IntersectRectAndLine|SDL_IntersectRectAndLine]].
3054
3055{{rect}} must be an sdl2:rect.
3056{{x1}}, {{y1}}, {{x2}}, and {{y2}} should be integers.
3057
3058This procedure returns multiple values:
3059
3060; intersect? : #t if the line segment intersects with the rect, otherwise #f
3061; x1-new : integer x1 of the new line segment
3062; y1-new : integer y1 of the new line segment
3063; x2-new : integer x2 of the new line segment
3064; y2-new : integer y2 of the new line segment
3065
3066If the line segment does not intersect the rect, then {{intersect?}} will be #f,
3067and {{x1-new}}, {{y1-new}}, {{x2-new}}, and {{y2-new}} will be the same as the original arguments.
3068
3069
3070<procedure>(union-rect rect1 rect2 #!optional result-rect) → rect</procedure>
3071
3072See [[https://wiki.libsdl.org/SDL_UnionRect|SDL_UnionRect]].
3073
3074If {{result-rect}} is omitted or #f, a new managed sdl2:rect will be returned.
3075If {{result-rect}} is an sdl2:rect, it will be modified and returned.
3076It is safe for {{result-rect}} to be the same object as {{rect1}} or {{rect2}},
3077in which case {{rect1}} or {{rect2}} will be modified and returned.
3078It is safe (but useless) for {{rect1}} and {{rect2}} to be the same object.
3079
3080
3081
3082==== sdl2:rect
3083
3084sdl2:rect is a record type that wraps a pointer to an
3085[[https://wiki.libsdl.org/SDL_Rect|SDL_Rect]] struct.
3086
3087
3088<procedure>(rect? obj) → boolean</procedure>
3089
3090Returns #t if {{obj}} is an sdl2:rect.
3091
3092
3093<procedure>(make-rect #!optional x y w h) → sdl2:rect</procedure>
3094<procedure>(make-rect* #!optional x y w h) → sdl2:rect</procedure>
3095
3096Allocate and initialize a new sdl2:rect.
3097
3098{{x}}, {{y}}, {{w}}, and {{h}} must be integers in the range -2147483648 to 2147483647 (inclusive).
3099They all default to 0.
3100
3101* {{make-rect}} returns a managed sdl2:rect.
3102* {{make-rect*}} returns an unmanaged sdl2:rect, which must be freed with {{free-rect!}} when you are done with it.
3103
3104
3105<procedure>(free-rect! rect)</procedure>
3106
3107Free the memory of the sdl2:rect's underlying struct. {{rect}}'s
3108pointer will be set to null (see {{struct-null?}}). It is safe to call
3109this procedure with managed or unmanaged sdl2:rects. It is safe (but
3110has no effect) to free a struct record multiple times.
3111
3112
3113<procedure>(rect-x rect) → integer</procedure>
3114<setter>(set! (rect-x rect) val)</setter>
3115<setter>(rect-x-set! rect val)</setter>
3116
3117Get or set the sdl2:rect's "x" field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3118
3119
3120<procedure>(rect-y rect) → integer</procedure>
3121<setter>(set! (rect-y rect) val)</setter>
3122<setter>(rect-y-set! rect val)</setter>
3123
3124Get or set the sdl2:rect's "y" field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3125
3126
3127<procedure>(rect-w rect) → integer</procedure>
3128<setter>(set! (rect-w rect) val)</setter>
3129<setter>(rect-w-set! rect val)</setter>
3130
3131Get or set the sdl2:rect's "w" (width) field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3132
3133
3134<procedure>(rect-h rect) → integer</procedure>
3135<setter>(set! (rect-h rect) val)</setter>
3136<setter>(rect-h-set! rect val)</setter>
3137
3138Get or set the sdl2:rect's "h" (height) field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3139
3140
3141<procedure>(rect-set! rect #!optional x y w h) → rect</procedure>
3142
3143Convenient way of setting multiple fields of the sdl2:rect.
3144Any arguments that are {{#f}} will cause no change to that field.
3145E.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.
3146Returns {{rect}} after it is modified.
3147
3148
3149<procedure>(rect->list rect) → list of integers</procedure>
3150
3151Returns a list {{(x y w h)}} containing the value of each field of the sdl2:rect.
3152
3153
3154<procedure>(rect->values rect) → [x y w h]</procedure>
3155
3156Returns multiple values containing the value of each field of the sdl2:rect.
3157This is useful for destructuring an sdl2:rect using {{receive}} or {{let-values}}.
3158
3159
3160<procedure>(rect=? rect1 rect2) → boolean</procedure>
3161
3162Efficiently compare two sdl2:rects.
3163Returns #t if the value of every field in {{rect1}} is equal to the value of the corresponding field in {{rect2}}.
3164See [[https://wiki.libsdl.org/SDL_RectEquals|SDL_RectEquals]].
3165
3166
3167<procedure>(copy-rect rect) → sdl2:rect</procedure>
3168<procedure>(copy-rect* rect) → sdl2:rect</procedure>
3169
3170Efficiently copy the given sdl2:rect, returning a new sdl2:rect with the same values.
3171
3172* {{copy-rect}} returns a managed sdl2:rect.
3173* {{copy-rect*}} returns an unmanaged sdl2:rect, which must be freed with {{free-rect!}} when you are done with it.
3174
3175
3176
3177==== sdl2:point
3178
3179sdl2:point is a record type that wraps a pointer to an
3180[[https://wiki.libsdl.org/SDL_Point|SDL_Point]] struct.
3181
3182
3183<procedure>(point? obj) → boolean</procedure>
3184
3185Returns #t if {{obj}} is an sdl2:point.
3186
3187
3188<procedure>(make-point #!optional x y) → sdl2:point</procedure>
3189<procedure>(make-point* #!optional x y) → sdl2:point</procedure>
3190
3191Allocate and initialize a new sdl2:point.
3192
3193{{x}} and {{y}} must be integers in the range -2147483648 to 2147483647 (inclusive).
3194They both default to 0.
3195
3196* {{make-point}} returns a managed sdl2:point.
3197* {{make-point*}} returns an unmanaged sdl2:point, which must be freed with {{free-point!}} when you are done with it.
3198
3199
3200<procedure>(free-point! point)</procedure>
3201
3202Free the memory of the sdl2:point's underlying struct. {{point}}'s
3203pointer will be set to null (see {{struct-null?}}). It is safe to call
3204this procedure with managed or unmanaged sdl2:points. It is safe (but
3205has no effect) to free a struct record multiple times.
3206
3207
3208<procedure>(point-x point) → integer</procedure>
3209<setter>(set! (point-x point) val)</setter>
3210<setter>(point-x-set! point val)</setter>
3211
3212Get or set the sdl2:point's "x" field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3213
3214
3215<procedure>(point-y point) → integer</procedure>
3216<setter>(set! (point-y point) val)</setter>
3217<setter>(point-y-set! point val)</setter>
3218
3219Get or set the sdl2:point's "y" field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3220
3221
3222<procedure>(point-set! point #!optional x y) → point</procedure>
3223
3224Convenient way of setting multiple fields of the sdl2:point.
3225Any arguments that are {{#f}} will cause no change to that field.
3226E.g. {{(point-set! my-point 42 #f)}} will set the "x" field to 42, but will not change the "y" field.
3227Returns {{point}} after it is modified.
3228
3229
3230<procedure>(point->list point) → list of integers</procedure>
3231
3232Returns a list {{(x y)}} containing the value of each field of the sdl2:point.
3233
3234
3235<procedure>(point->values point) → [x y]</procedure>
3236
3237Returns multiple values containing the value of each field of the sdl2:point.
3238This is useful for destructuring an sdl2:point using {{receive}} or {{let-values}}.
3239
3240
3241<procedure>(point=? point1 point2) → boolean</procedure>
3242
3243Efficiently compare two sdl2:points.
3244Returns #t if the value of every field in {{point1}} is equal to the value of the corresponding field in {{point2}}.
3245
3246
3247<procedure>(copy-point point) → sdl2:point</procedure>
3248<procedure>(copy-point* point) → sdl2:point</procedure>
3249
3250Efficiently copy the given sdl2:point, returning a new sdl2:point with the same values.
3251
3252* {{copy-point}} returns a managed sdl2:point.
3253* {{copy-point*}} returns an unmanaged sdl2:point, which must be freed with {{free-point!}} when you are done with it.
3254
3255
3256
3257=== Renderer
3258
3259Renderer is one part of [[https://wiki.libsdl.org/CategoryRender|2D Accelerated Rendering]].
3260See also [[#texture|Texture]].
3261
3262Renderer support is available in '''sdl2 egg 0.2.0 and higher'''.
3263
3264
3265==== Renderer Functions
3266
3267<procedure>(create-renderer! window index #!optional flags) → sdl2:renderer</procedure>
3268
3269See [[https://wiki.libsdl.org/SDL_CreateRenderer|SDL_CreateRenderer]].
3270This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3271
3272
3273<procedure>(create-software-renderer! surface) → sdl2:renderer</procedure>
3274
3275See [[https://wiki.libsdl.org/SDL_CreateSoftwareRenderer|SDL_CreateSoftwareRenderer]].
3276This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3277
3278
3279<procedure>(destroy-renderer! renderer)</procedure>
3280
3281See [[https://wiki.libsdl.org/SDL_DestroyRenderer|SDL_DestroyRenderer]].
3282This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3283
3284
3285<procedure>(create-window-and-renderer! width height #!optional window-flags) → [window renderer]</procedure>
3286
3287See [[https://wiki.libsdl.org/SDL_CreateWindowAndRenderer|SDL_CreateWindowAndRenderer]].
3288This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3289
3290{{width}} and {{height}} specify the height of the window to create.
3291
3292{{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).
3293
3294This procedure returns multiple values:
3295
3296; window : The sdl2:window that was created.
3297; renderer : The sdl2:renderer that was created.
3298
3299
3300<procedure>(get-renderer window) → sdl2:renderer</procedure>
3301
3302See [[https://wiki.libsdl.org/SDL_GetRenderer|SDL_GetRenderer]].
3303This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3304
3305Signals an exception of kind {{(exn sdl2)}} if the window does not have a renderer,
3306or if an error occurs.
3307
3308
3309<procedure>(get-renderer-info renderer) → sdl2:renderer-info</procedure>
3310<procedure>(get-renderer-info* renderer) → sdl2:renderer-info</procedure>
3311
3312See [[https://wiki.libsdl.org/SDL_GetRendererInfo|SDL_GetRendererInfo]].
3313These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3314
3315* {{get-renderer-info}} returns a managed sdl2:renderer-info.
3316* {{get-renderer-info*}} returns an unmanaged sdl2:renderer-info, which must be freed using {{free-renderer-info!}} when you are done with it.
3317
3318
3319<procedure>(num-render-drivers) → integer</procedure>
3320
3321See [[https://wiki.libsdl.org/SDL_GetNumRenderDrivers|SDL_GetNumRenderDrivers]].
3322This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3323
3324
3325<procedure>(render-driver-info index) → sdl2:renderer-info</procedure>
3326
3327See [[https://wiki.libsdl.org/SDL_GetRenderDriverInfo|SDL_GetRenderDriverInfo]].
3328This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3329
3330
3331<procedure>(render-present!)</procedure>
3332
3333See [[https://wiki.libsdl.org/SDL_RenderPresent|SDL_RenderPresent]].
3334This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3335
3336
3337<procedure>(render-copy! renderer texture #!optional srcrect dstrect) → </procedure>
3338
3339See [[https://wiki.libsdl.org/SDL_RenderCopy|SDL_RenderCopy]].
3340This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3341
3342
3343<procedure>(render-copy-ex! renderer texture #!optional srcrect dstrect angle center flip)</procedure>
3344
3345See [[https://wiki.libsdl.org/SDL_RenderCopyEx|SDL_RenderCopyEx]].
3346This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3347
3348
3349<procedure>(render-target-supported? renderer) → boolean</procedure>
3350
3351See [[https://wiki.libsdl.org/SDL_RenderTargetSupported|SDL_RenderTargetSupported]].
3352This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3353
3354
3355<procedure>(render-target renderer) → sdl2:texture or #f</procedure>
3356<setter>(render-target-set! renderer target)</setter>
3357<setter>(set! (render-target renderer) target)</setter>
3358
3359See [[https://wiki.libsdl.org/SDL_GetRenderTarget|SDL_GetRenderTarget]]
3360and [[https://wiki.libsdl.org/SDL_SetRenderTarget|SDL_SetRenderTarget]].
3361These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3362
3363
3364<procedure>(render-read-pixels-raw renderer rect format pixels-out pitch)</procedure>
3365
3366See [[https://wiki.libsdl.org/SDL_RenderReadPixels|SDL_RenderReadPixels]].
3367This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3368
3369
3370<procedure>(render-draw-blend-mode renderer) → symbol</procedure>
3371<procedure>(render-draw-blend-mode-raw renderer) → integer</procedure>
3372<setter>(render-draw-blend-mode-set! renderer mode)</setter>
3373<setter>(set! (render-draw-blend-mode renderer) mode)</setter>
3374
3375Get or set the renderer's draw blend mode. This affects future drawing operations.
3376See [[https://wiki.libsdl.org/SDL_GetRenderDrawBlendMode|SDL_GetRenderDrawBlendMode]]
3377and [[https://wiki.libsdl.org/SDL_SetRenderDrawBlendMode|SDL_SetRenderDrawBlendMode]].
3378These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3379
3380* {{render-draw-blend-mode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-mode|blend mode symbol]]:
3381** {{'none}}
3382** {{'blend}}
3383** {{'add}}
3384** {{'mod}}
3385* {{render-draw-blend-mode-raw}} returns an integer.
3386* The setters accept either a symbol or integer.
3387
3388
3389<procedure>(render-draw-color renderer) → sdl2:color</procedure>
3390<procedure>(render-draw-colour renderer) → sdl2:color</procedure>
3391<setter>(render-draw-color-set! renderer color)</setter>
3392<setter>(render-draw-colour-set! renderer color)</setter>
3393<setter>(set! (render-draw-color renderer) color)</setter>
3394<setter>(set! (render-draw-colour renderer) color)</setter>
3395
3396Get or set the renderer's draw color. This affects future drawing operations.
3397See [[https://wiki.libsdl.org/SDL_GetRenderDrawColor|SDL_GetRenderDrawColor]]
3398and [[https://wiki.libsdl.org/SDL_SetRenderDrawColor|SDL_SetRenderDrawColor]].
3399These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3400
3401
3402<procedure>(render-clear! renderer)</procedure>
3403
3404Clear the entire renderer, using the renderer's current draw color.
3405See [[https://wiki.libsdl.org/SDL_RenderClear|SDL_RenderClear]].
3406This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3407
3408
3409<procedure>(render-draw-line! renderer x1 y1 x2 y2)</procedure>
3410<procedure>(render-draw-lines! renderer points)</procedure>
3411
3412Draw a line segment or multiple connected line segments, using the renderer's current draw color and blend mode.
3413See [[https://wiki.libsdl.org/SDL_RenderDrawLine|SDL_RenderDrawLine]]
3414and [[https://wiki.libsdl.org/SDL_RenderDrawLines|SDL_RenderDrawLines]].
3415These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3416
3417* {{render-draw-line!}} draws a single line segment.
3418* {{render-draw-lines!}} draws multiple connected line segments. {{points}} must be a list or vector of sdl2:point instances.
3419
3420
3421<procedure>(render-draw-point! renderer x y)</procedure>
3422<procedure>(render-draw-points! renderer points)</procedure>
3423
3424Draw one or multiple points, using the renderer's current draw color and blend mode.
3425See [[https://wiki.libsdl.org/SDL_RenderDrawPoint|SDL_RenderDrawPoint]]
3426and [[https://wiki.libsdl.org/SDL_RenderDrawPoints|SDL_RenderDrawPoints]].
3427These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3428
3429* {{render-draw-point!}} draws a single point.
3430* {{render-draw-points!}} draws multiple points. {{points}} must be a list or vector of sdl2:point instances.
3431
3432
3433<procedure>(render-draw-rect! renderer rect)</procedure>
3434<procedure>(render-draw-rects! renderer rects)</procedure>
3435
3436Draw one or multiple outlined rectangles, using the renderer's current draw color and blend mode.
3437See [[https://wiki.libsdl.org/SDL_RenderDrawRect|SDL_RenderDrawRect]]
3438and [[https://wiki.libsdl.org/SDL_RenderDrawRects|SDL_RenderDrawRects]].
3439These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3440
3441* {{render-draw-rect!}} draws a single outlined rect.
3442* {{render-draw-rects!}} draws multiple outlined rects. {{rects}} must be a list or vector of sdl2:rect instances.
3443
3444
3445<procedure>(render-fill-rect! renderer rect)</procedure>
3446<procedure>(render-fill-rects! renderer rects)</procedure>
3447
3448Draw one or multiple filled rectangles, using the renderer's current draw color and blend mode.
3449See [[https://wiki.libsdl.org/SDL_RenderFillRect|SDL_RenderFillRect]]
3450and [[https://wiki.libsdl.org/SDL_RenderFillRects|SDL_RenderFillRects]].
3451These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3452
3453* {{render-draw-rect!}} draws a single filled rect.
3454* {{render-draw-rects!}} draws multiple filled rects. {{rects}} must be a list or vector of sdl2:rect instances.
3455
3456
3457==== sdl2:renderer
3458
3459sdl2:renderer is a record type that wraps a pointer to an SDL_Renderer struct.
3460sdl2:renderer is available in '''sdl2 egg version 0.2.0 and higher'''.
3461
3462
3463<procedure>(renderer? obj) → boolean</procedure>
3464
3465Returns #t if {{obj}} is an sdl2:renderer.
3466This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3467
3468
3469<procedure>(renderer-output-size renderer) → [w h]</procedure>
3470
3471See [[https://wiki.libsdl.org/SDL_GetRendererOutputSize|SDL_GetRendererOutputSize]].
3472This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3473
3474This procedure returns multiple values, the output width and height, as integers.
3475
3476
3477<procedure>(render-clip-rect renderer) → sdl2:rect</procedure>
3478<setter>(render-clip-rect-set! renderer rect)</setter>
3479<setter>(set! (render-clip-rect renderer) rect)</setter>
3480
3481Get or set the sdl2:renderer's clip rect.
3482See [[https://wiki.libsdl.org/SDL_RenderGetClipRect|SDL_RenderGetClipRect]]
3483and [[https://wiki.libsdl.org/SDL_RenderSetClipRect|SDL_RenderSetClipRect]].
3484These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3485
3486{{render-clip-rect}} returns a new managed sdl2:rect describing the renderer's clip rect.
3487Returns {{#<sdl2:rect (0 0 0 0)>}} if clipping is disabled.
3488
3489But, be aware that it also returns {{#<sdl2:rect (0 0 0 0)>}} if that is the current clip rect.
3490Use {{render-clip-enabled?}} (in SDL 2.0.4 or higher) to unambiguously check whether clipping is enabled or disabled.
3491
3492The setters accept either an sdl2:rect to enable clipping and set the clip rect,
3493or #f to disable clipping.
3494
3495
3496<procedure>(render-clip-enabled? renderer) → boolean</procedure>
3497
3498Returns #t if clipping is enabled for the given sdl2:renderer,
3499or #f is clipping is disabled.
3500See [[https://wiki.libsdl.org/SDL_RenderIsClipEnabled|SDL_RenderIsClipEnabled]].
3501This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3502
3503Requires '''SDL 2.0.4 or higher'''.
3504Signals an error if the compiled version of SDL is not high enough.
3505Use the [[#version-feature-identifiers|{{libSDL-2.0.4+}} feature identifier]]
3506to check before calling this procedure.
3507
3508
3509<procedure>(render-logical-size renderer) → [w h]</procedure>
3510<setter>(render-logical-size-set! renderer size)</setter>
3511<setter>(set! (render-logical-size renderer) size)</setter>
3512
3513Get or set the renderer's logical size.
3514See [[https://wiki.libsdl.org/SDL_RenderGetLogicalSize|SDL_RenderGetLogicalSize]]
3515and [[https://wiki.libsdl.org/SDL_RenderSetLogicalSize|SDL_RenderSetLogicalSize]].
3516These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3517
3518* {{render-logical-size}} returns multiple values, the logical width and height, as integers.
3519* The setters accept a list {{(w h)}} containing the new logical width and height, as integers.
3520
3521
3522<procedure>(render-scale renderer) → [x-scale y-scale]</procedure>
3523<setter>(render-scale-set! renderer scales)</setter>
3524<setter>(set! (render-scale-set! renderer) scales)</setter>
3525
3526Get or set the sdl2:renderer's x and y scaling factors.
3527See [[https://wiki.libsdl.org/SDL_RenderGetScale|SDL_RenderGetScale]]
3528and [[https://wiki.libsdl.org/SDL_RenderSetScale|SDL_RenderSetScale]].
3529These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3530
3531* {{render-scale}} returns multiple values, the x and y scaling factors, as integers..
3532* The setters accept a list {{(x-scale y-scale)}} containing the new scaling factors, as integers.
3533
3534
3535<procedure>(render-viewport renderer) → sdl2:rect</procedure>
3536<setter>(render-viewport-set! renderer rect)</setter>
3537<setter>(set! (render-viewport renderer) rect)</setter>
3538
3539Get or set the renderer's viewport.
3540See [[https://wiki.libsdl.org/SDL_RenderGetViewport|SDL_RenderGetViewport]]
3541and [[https://wiki.libsdl.org/SDL_RenderSetViewport|SDL_RenderSetViewport]].
3542These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3543
3544
3545
3546==== sdl2:renderer-info
3547
3548sdl2:renderer-info is a record type that wraps a pointer to an
3549[[https://wiki.libsdl.org/SDL_RendererInfo|SDL_RendererInfo]] struct.
3550sdl2:renderer-info is available in '''sdl2 egg version 0.2.0 and higher'''.
3551
3552<procedure>(renderer-info? obj) → boolean</procedure>
3553
3554Returns #t if {{obj}} is an sdl2:renderer-info.
3555This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3556
3557
3558<procedure>(free-renderer-info! renderer-info)</procedure>
3559
3560Free the memory of the sdl2:renderer-info's underlying struct.
3561{{renderer-info}}'s pointer will be set to null (see {{struct-null?}}).
3562It is safe to call this procedure with managed or unmanaged sdl2:renderer-infos.
3563It is safe (but has no effect) to free a struct record multiple times.
3564This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3565
3566
3567<procedure>(renderer-info-name renderer-info) → string</procedure>
3568
3569Get the sdl2:renderer-info's "name" field, as a string.
3570This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3571
3572
3573<procedure>(renderer-info-flags renderer-info) → list of symbols</procedure>
3574<procedure>(renderer-info-flags-raw renderer-info) → integer</procedure>
3575
3576Get the sdl2:renderer-info's "flags" field, as a list of symbols or an integer.
3577TODO: Link to flags enums.
3578These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3579
3580
3581<procedure>(renderer-info-num-texture-formats renderer-info) → integer</procedure>
3582
3583Get the sdl2:renderer-info's "num-texture-formats" field, as an integer.
3584This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3585
3586
3587<procedure>(renderer-info-texture-formats renderer-info) → list of symbols</procedure>
3588
3589Get the sdl2:renderer-info's "texture-formats" field,
3590as a list of [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbols]].
3591This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3592
3593
3594<procedure>(renderer-info-max-texture-width renderer-info) → integer</procedure>
3595
3596Get the sdl2:renderer-info's "max-texture-width" field, as an integer.
3597This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3598
3599
3600<procedure>(renderer-info-max-texture-height renderer-info) → integer</procedure>
3601
3602Get the sdl2:renderer-info's "max-texture-height" field, as an integer.
3603This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3604
3605
3606
3607=== RWops
3608
3609==== RWops Functions
3610
3611<procedure>(rw-from-file filepath) → sdl2:rwops</procedure>
3612
3613See [[https://wiki.libsdl.org/SDL_RWFromFile|SDL_RWFromFile]].
3614
3615You should close the sdl2:rwops when you are done with it, using
3616{{rw-close!}} or one of the procedures that can automatically close
3617the sdl2:rwops, such as {{load-bmp-rw}}.
3618
3619Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3620
3621
3622<procedure>(rw-from-const-mem pointer) → sdl2:rwops</procedure>
3623
3624See [[https://wiki.libsdl.org/SDL_RWFromConstMem|SDL_RWFromConstMem]].
3625
3626You should close the sdl2:rwops when you are done with it, using
3627{{rw-close!}} or one of the procedures that can automatically close
3628the sdl2:rwops, such as {{load-bmp-rw}}.
3629
3630Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3631
3632
3633<procedure>(rw-from-mem pointer) → sdl2:rwops</procedure>
3634
3635See [[https://wiki.libsdl.org/SDL_RWFromMem|SDL_RWFromMem]].
3636
3637You should close the sdl2:rwops when you are done with it, using
3638{{rw-close!}} or one of the procedures that can automatically close
3639the sdl2:rwops, such as {{load-bmp-rw}}.
3640
3641Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3642
3643
3644<procedure>(rw-from-blob blob) → sdl2:rwops</procedure>
3645
3646Create a new sdl2:rwops that accesses the memory of the given
3647[[http://wiki.call-cc.org/manual/Unit%20library#blobs|blob]]. You
3648should close the sdl2:rwops when you are done with it, using
3649{{rw-close!}} or one of the procedures that can automatically close
3650the sdl2:rwops, such as {{load-bmp-rw}}.
3651
3652Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3653
3654You can also use this procedure to create a sdl2:rwops from a
3655[[/manual/Unit srfi-4|SRFI-4]] numeric vector, by first converting it
3656to a blob using e.g. {{u8vector->blob/shared}}.
3657
3658'''CAUTION:''' Creating a sdl2:rwops from a blob in CHICKEN-managed
3659memory is unstable: the blob might be garbage collected or moved in
3660memory, which would break the sdl2:rwops. To be safe, you should
3661[[/manual/Unit lolevel#object-evict|evict]] the blob and create the
3662sdl2:rwops from the evicted blob (not the original). You may wish to
3663[[/manual/Unit lolevel#object-release|release]] the evicted blob after
3664you have closed the sdl2:rwops. Example:
3665
3666<enscript highlight="scheme">
3667(let* ((evicted-blob (object-evict '#${...}))
3668       (rwops (sdl2:rw-from-blob evicted-blob))
3669       (surf (sdl2:load-bmp-rw rwops #t)))
3670  (object-release evicted-blob)
3671  surf)
3672</enscript>
3673
3674
3675<procedure>(rw-from-string str) → sdl2:rwops</procedure>
3676
3677Create a new sdl2:rwops that accesses the memory of the given CHICKEN
3678Scheme string. You should close the sdl2:rwops when you are done with
3679it, using {{rw-close!}} or one of the procedures that can
3680automatically close the sdl2:rwops, such as {{load-bmp-rw}}.
3681
3682Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3683
3684'''CAUTION:''' Creating a sdl2:rwops from a string in CHICKEN-managed
3685memory is unstable: the string might be garbage collected or moved in
3686memory, which would break the sdl2:rwops. To be safe, you should
3687[[/manual/Unit lolevel#object-evict|evict]] the string and create the
3688sdl2:rwops from the evicted string (not the original). You may wish to
3689[[/manual/Unit lolevel#object-release|release]] the evicted string
3690after you have closed the sdl2:rwops. Example:
3691
3692<enscript highlight="scheme">
3693(let* ((evicted-string (object-evict "..."))
3694       (rwops (sdl2:rw-from-string evicted-string))
3695       (surf (sdl2:load-bmp-rw rwops #t)))
3696  (object-release evicted-string)
3697  surf)
3698</enscript>
3699
3700
3701<procedure>(rw-close! rwops)</procedure>
3702
3703See [[https://wiki.libsdl.org/SDL_RWclose|SDL_RWclose]].
3704
3705Close and clean up the given sdl2:rwops. This frees the memory used by
3706the SDL_RWops struct itself, but does not free or release the pointer,
3707blob, or string that the sdl2:rwops was reading/writing from. (It does
3708close files opened with {{rw-from-file}}, though.)
3709
3710Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3711
3712
3713==== sdl2:rwops
3714
3715sdl2:rwops is a record type that wraps a pointer to an
3716[[https://wiki.libsdl.org/SDL_RWops|SDL_RWops]] struct.
3717
3718
3719<procedure>(rwops? obj) → boolean</procedure>
3720
3721Returns #t if {{obj}} is an sdl2:rwops.
3722
3723
3724<procedure>(rwops-type rwops) → symbol</procedure>
3725<procedure>(rwops-type-raw rwops) → integer</procedure>
3726
3727Get the sdl2:rwops' "type" field, indicating the data source type.
3728
3729* {{rwops-type}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#rwops-types|RWops type symbol]]:
3730** {{'unknown}}
3731** {{'win-file}}
3732** {{'std-file}}
3733** {{'jni-file}}
3734** {{'memory}}
3735** {{'memory-ro}}
3736* {{rwops-type-raw}} returns an integer.
3737
3738
3739
3740=== Surface
3741
3742==== Surface Functions
3743
3744<procedure>(create-rgb-surface* flags width height depth rmask gmask bmask amask) → sdl2:surface</procedure>
3745
3746See [[https://wiki.libsdl.org/SDL_CreateRGBSurface|SDL_CreateRGBSurface]].
3747
3748Returns a new '''unmanaged''' sdl2:surface with the given properties.
3749You must call {{free-surface!}} when you are done with it.
3750
3751See {{make-surface}} for a more convenient interface.
3752
3753Signals an exception of kind {{(exn sdl2)}} if the surface cannot be created.
3754
3755
3756<procedure>(create-rgb-surface-from* pixels width height depth pitch rmask gmask bmask amask) → sdl2:surface</procedure>
3757
3758Returns a new '''unmanaged''' sdl2:surface with the given properties,
3759using existing pixel data (a pointer, e.g. from {{surface-pixels-raw}}).
3760You must call {{free-surface!}} when you are done with it.
3761
3762See [[https://wiki.libsdl.org/SDL_CreateRGBSurfaceFrom|SDL_CreateRGBSurfaceFrom]].
3763
3764Signals an exception of kind {{(exn sdl2)}} if the surface cannot be created.
3765
3766
3767<procedure>(convert-surface surface pixel-format) → sdl2:surface</procedure>
3768<procedure>(convert-surface* surface pixel-format) → sdl2:surface</procedure>
3769
3770Creates a copy of the given sdl2:surface, but converts it to the given sdl2:pixel-format.
3771
3772See [[https://wiki.libsdl.org/SDL_ConvertSurface|SDL_ConvertSurface]].
3773
3774* {{convert-surface}} returns a managed sdl2:surface.
3775* {{convert-surface*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
3776
3777Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3778
3779
3780<procedure>(load-bmp  filepath) → sdl2:surface</procedure>
3781<procedure>(load-bmp* filepath) → sdl2:surface</procedure>
3782
3783See [[https://wiki.libsdl.org/SDL_LoadBMP|SDL_LoadBMP]].
3784
3785Attempts to load a BMP image file.
3786Returns a sdl2:surface containing the image data.
3787Signals an exception of kind {{(exn sdl2)}} if the image could not be loaded.
3788
3789'''NOTE:''' This procedure only supports certain kinds of BMP image.
3790Use the [[/egg/sdl2-image|sdl2-image egg]] for better BMP support,
3791plus support for loading other image formats like JPG, PNG, and GIF.
3792
3793* {{load-bmp}} returns a managed sdl2:surface.
3794* {{load-bmp*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
3795
3796
3797<procedure>(load-bmp-rw  rwops #!optional close?) → sdl2:surface</procedure>
3798<procedure>(load-bmp-rw* rwops #!optional close?) → sdl2:surface</procedure>
3799
3800See [[https://wiki.libsdl.org/SDL_LoadBMP_RW|SDL_LoadBMP_RW]].
3801
3802Attempts to load a BMP image from the given sdl2:rwops.
3803Returns a sdl2:surface containing the image data.
3804Signals an exception of kind {{(exn sdl2)}} if the image could not be loaded.
3805
3806If {{close?}} is #t, {{rwops}} will be automatically closed (see
3807{{rw-close!}}) after the image is loaded. If {{close?}} is #f or
3808omitted, {{rwops}} will not be closed.
3809
3810'''NOTE:''' This procedure only supports certain kinds of BMP image.
3811Use the [[/egg/sdl2-image|sdl2-image egg]] for better BMP support,
3812plus support for loading other image formats like JPG, PNG, and GIF.
3813
3814* {{load-bmp-rw}} returns a managed sdl2:surface.
3815* {{load-bmp-rw*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
3816
3817
3818<procedure>(save-bmp! surface filepath)</procedure>
3819
3820See [[https://wiki.libsdl.org/SDL_SaveBMP|SDL_SaveBMP]].
3821
3822Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3823
3824
3825<procedure>(save-bmp-rw! surface rwops #!optional close?)</procedure>
3826
3827See [[https://wiki.libsdl.org/SDL_SaveBMP_RW|SDL_SaveBMP_RW]].
3828
3829If {{close?}} is #t, {{rwops}} will be automatically closed (see
3830{{rw-close!}}) after the image is loaded. If {{close?}} is #f or
3831omitted, {{rwops}} will not be closed.
3832
3833Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3834
3835
3836<procedure>(lock-surface! surface)</procedure>
3837<procedure>(unlock-surface! surface)</procedure>
3838
3839See [[https://wiki.libsdl.org/SDL_LockSurface|SDL_LockSurface]]
3840and [[https://wiki.libsdl.org/SDL_UnlockSurface|SDL_UnlockSurface]].
3841
3842{{lock-surface!}} signals an exception of kind {{(exn sdl2)}} if an error occurs.
3843
3844
3845<procedure>(must-lock? surface) → boolean</procedure>
3846
3847See [[https://wiki.libsdl.org/SDL_MUSTLOCK|SDL_MUSTLOCK]].
3848
3849
3850<procedure>(blit-surface! src src-rect dest dest-rect)</procedure>
3851
3852See [[https://wiki.libsdl.org/SDL_BlitSurface|SDL_BlitSurface]].
3853
3854May modify dest-rect.
3855
3856Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3857
3858
3859<procedure>(blit-scaled! src src-rect dest dest-rect)</procedure>
3860
3861See [[https://wiki.libsdl.org/SDL_BlitScaled|SDL_BlitScaled]].
3862
3863May modify dest-rect.
3864
3865Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3866
3867
3868<procedure>(fill-rect! surface rect color)</procedure>
3869
3870See [[https://wiki.libsdl.org/SDL_FillRect|SDL_FillRect]].
3871
3872{{rect}} may be an sdl2:rect to fill part of the surface, or #f to fill
3873the entire surface.
3874
3875{{color}} may be an sdl2:color or a mapped color (an integer, like
3876returned by {{map-rgba}}).
3877
3878Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3879
3880
3881<procedure>(fill-rects! surface rects color)</procedure>
3882
3883See [[https://wiki.libsdl.org/SDL_FillRects|SDL_FillRects]].
3884
3885{{rects}} must be a list of sdl2:rects.
3886
3887{{color}} may be an sdl2:color or a mapped color (an integer, like
3888returned by {{map-rgba}}).
3889
3890Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3891
3892
3893<procedure>(surface-ref surface x y) → sdl2:color</procedure>
3894<procedure>(surface-ref-raw surface x y) → integer</procedure>
3895<setter>(set! (surface-ref surface x y) color)</setter>
3896<setter>(surface-set! surface x y color)</setter>
3897
3898Get or set the color of the specified pixel on the surface.
3899
3900* {{surface-ref}} returns an sdl2:color.
3901* {{surface-ref-raw}} returns a mapped color (an integer). You can use {{get-rgba}} to convert the mapped color to color fields.
3902* The setters accept either an sdl2:color or a mapped color.
3903
3904These procedures automatically lock and unlock the surface if needed.
3905They signal an exception of kind {{(exn sdl2)}} if the surface cannot be locked.
3906
3907These procedures signal an exception of kind {{(exn bounds)}} if {{x}} or {{y}} is out of bounds.
3908
3909The setters ignore the surface's clip rect.
3910
3911
3912<procedure>(rotate-surface-90  surface turns) → sdl2:surface</procedure>
3913<procedure>(rotate-surface-90* surface turns) → sdl2:surface</procedure>
3914
3915Return a copy of the given surface rotated by the given number of 90º clockwise turns.
3916{{turns}} must be an integer.
3917For example:
3918
3919* {{turns}} 0 means no rotation
3920* {{turns}} 1 means 90º clockwise rotation
3921* {{turns}} 2 means 180º rotation
3922* {{turns}} 3 (or -1) means 270º clockwise (i.e. 90º counter-clockwise) rotation
3923
3924The new surface will have an equivalent pixel format, color key, blend mode, alpha mod, and color mod as the given surface.
3925If the given surface has a palette, the new surface will share the same palette.
3926The new surface will have no clip rect.
3927
3928Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3929
3930* {{rotate-surface-90}} returns a managed sdl2:surface.
3931* {{rotate-surface-90*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
3932
3933
3934<procedure>(flip-surface  surface flip-x? flip-y?) → sdl2:surface</procedure>
3935<procedure>(flip-surface* surface flip-x? flip-y?) → sdl2:surface</procedure>
3936
3937Return a copy of the given surface flipped on the X (horizontal) and/or Y (vertical) axes.
3938
3939The new surface will have an equivalent pixel format, color key, blend mode, alpha mod, and color mod as the given surface.
3940If the given surface has a palette, the new surface will share the same palette.
3941The new surface will have no clip rect.
3942
3943Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3944
3945* {{flip-surface}} returns a managed sdl2:surface.
3946* {{flip-surface*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
3947
3948
3949
3950==== sdl2:surface
3951
3952sdl2:surface is a record type that wraps a pointer to an
3953[[https://wiki.libsdl.org/SDL_Surface|SDL_Surface]] struct.
3954
3955
3956<procedure>(surface? obj) → boolean</procedure>
3957
3958Returns #t if {{obj}} is an sdl2:surface.
3959
3960
3961<procedure>(make-surface width height depth) → sdl2:surface</procedure>
3962<procedure>(make-surface* width height depth) → sdl2:surface</procedure>
3963
3964Create a new sdl2:surface with the given width, height, and color depth (bits per pixel).
3965This is a more convenient interface for {{create-rgb-surface}}.
3966The sdl2:surface's pixel format and masks will be chosen automatically
3967based on the requested depth and the current platform's byte order (little endian or big endian).
3968
3969These procedures signal an exception of kind {{(exn sdl2)}}
3970if the sdl2:surface could not be created (e.g. because the color depth is unsupported).
3971
3972* {{make-surface}} returns a managed sdl2:surface.
3973* {{make-surface*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
3974
3975
3976<procedure>(free-surface! surface)</procedure>
3977
3978Free the memory of the sdl2:surface's underlying struct. {{surface}}'s
3979pointer will be set to null (see {{struct-null?}}). It is safe to call
3980this procedure with managed or unmanaged sdl2:surfaces. It is safe
3981(but has no effect) to free a struct record multiple times.
3982
3983See [[https://wiki.libsdl.org/SDL_FreeSurface|SDL_FreeSurface]].
3984
3985'''NOTE:''' if {{surface}} was created using
3986{{create-rgb-surface-from}}, then the pixel data is not freed.
3987
3988
3989<procedure>(surface-format surface) → sdl2:pixel-format</procedure>
3990
3991Get the sdl2:surface's "format" field, as a sdl2:pixel-format describing the format of the surface's pixels.
3992
3993
3994<procedure>(surface-w surface) → integer</procedure>
3995
3996Get the sdl2:surface's "w" field, as a nonnegative integer indicating the surface's width in pixels.
3997
3998
3999<procedure>(surface-h surface) → integer</procedure>
4000
4001Get the sdl2:surface's "h" field, as a nonnegative integer indicating the surface's height in pixels.
4002
4003
4004<procedure>(surface-pitch surface) → integer</procedure>
4005
4006Get the sdl2:surface's "pitch" field, as a nonnegative integer indicating how many bytes are used to represent one row of pixel data.
4007
4008
4009<procedure>(surface-pixels-raw surface) → pointer or #f</procedure>
4010
4011Get the sdl2:surface's "pixels" field, as a raw pointer to the sdl2:surface's pixels.
4012Don't use this unless you really know what you are doing!
4013
4014If you want to get or set a pixel, use {{surface-ref}} and {{surface-set!}} instead.
4015They are much safer, more convenient, and more efficient than accessing the pixel data using this pointer.
4016
4017
4018<procedure>(surface-userdata-raw surface) → pointer or #f</procedure>
4019<setter>(set! (surface-userdata-raw surface) val)</setter>
4020<setter>(surface-userdata-raw-set! surface val)</setter>
4021
4022Get or set the sdl2:surface's "userdata" field, as a pointer or #f.
4023
4024If you want to store a pointer to a Scheme object here, be sure to
4025[[/manual/Unit lolevel#object-evict|evict the object]] first. Otherwise
4026the object's location in memory might change, rendering the pointer
4027invalid.
4028
4029
4030<procedure>(surface-refcount surface) → integer</procedure>
4031<setter>(set! (surface-refcount surface) val)</setter>
4032<setter>(surface-refcount-set! surface val)</setter>
4033
4034Get or set the sdl2:surface's "refcount" field, as an integer.
4035
4036
4037<procedure>(surface-clip-rect surface) → sdl2:rect</procedure>
4038<setter>(set! (surface-clip-rect surface) rect) → boolean</setter>
4039<setter>(surface-clip-rect-set! surface rect) → boolean</setter>
4040
4041{{surface-clip-rect}} returns a copy of the surface's clip rect.
4042See [[https://wiki.libsdl.org/SDL_GetClipRect|SDL_GetClipRect]].
4043
4044The setters sets the surface's clip rect to a copy of the given rect.
4045{{rect}} may be #f, which disables clipping.
4046See [[https://wiki.libsdl.org/SDL_SetClipRect|SDL_SetClipRect]].
4047
4048The 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).
4049
4050
4051<procedure>(surface-color-key surface) → sdl2:color or #f</procedure>
4052<procedure>(surface-colour-key surface) → sdl2:color or #f</procedure>
4053<procedure>(surface-color-key-raw surface) → integer or #f</procedure>
4054<procedure>(surface-colour-key-raw surface) → integer or #f</procedure>
4055<setter>(set! (surface-color-key surface) color)</setter>
4056<setter>(set! (surface-colour-key surface) color)</setter>
4057<setter>(surface-color-key-set! surface color)</setter>
4058<setter>(surface-colour-key-set! surface color)</setter>
4059
4060Get or set the sdl2:surface's color key.
4061
4062See [[https://wiki.libsdl.org/SDL_GetColorKey|SDL_GetColorKey]]
4063and [[https://wiki.libsdl.org/SDL_SetColorKey|SDL_SetColorKey]].
4064
4065* {{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.
4066* {{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.
4067* The setters accept either an sdl2:color, a mapped color (an integer), or #f to disable color keying.
4068
4069These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4070
4071
4072<procedure>(surface-alpha-mod surface) → integer</procedure>
4073<setter>(set! (surface-alpha-mod surface) mod)</setter>
4074<setter>(surface-alpha-mod-set! surface mod)</setter>
4075
4076See [[https://wiki.libsdl.org/SDL_GetSurfaceAlphaMod|SDL_GetSurfaceAlphaMod]]
4077and [[https://wiki.libsdl.org/SDL_SetSurfaceAlphaMod|SDL_SetSurfaceAlphaMod]].
4078
4079These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4080
4081
4082<procedure>(surface-blend-mode surface) → symbol</procedure>
4083<procedure>(surface-blend-mode-raw surface) → integer</procedure>
4084<setter>(set! (surface-blend-mode surface) mode)</setter>
4085<setter>(surface-blend-mode-set! surface mode)</setter>
4086
4087See [[https://wiki.libsdl.org/SDL_GetSurfaceBlendMode|SDL_GetSurfaceBlendMode]]
4088and [[https://wiki.libsdl.org/SDL_SetSurfaceBlendMode|SDL_SetSurfaceBlendMode]].
4089
4090* {{surface-blend-mode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-mode|blend mode symbol]]:
4091** {{'none}}
4092** {{'blend}}
4093** {{'add}}
4094** {{'mod}}
4095* {{surface-blend-mode-raw}} returns an integer.
4096* The setters accept either a symbol or integer.
4097
4098These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4099
4100
4101<procedure>(surface-color-mod surface) → [r g b]</procedure>
4102<procedure>(surface-colour-mod surface) → [r g b]</procedure>
4103<setter>(set! (surface-color-mod surface) rgb)</setter>
4104<setter>(set! (surface-colour-mod surface) rgb)</setter>
4105<setter>(surface-color-mod-set! surface rgb)</setter>
4106<setter>(surface-colour-mod-set! surface rgb)</setter>
4107
4108See [[https://wiki.libsdl.org/SDL_GetSurfaceColorMod|SDL_GetSurfaceColorMod]]
4109and [[https://wiki.libsdl.org/SDL_SetSurfaceColorMod|SDL_SetSurfaceColorMod]].
4110
4111{{surface-color-mod}} and {{surface-colour-mod}} return multiple values.
4112
4113The setters accept either a list {{(r g b)}} of color values, or an sdl2:color (the sdl2:color's "a" field will be ignored).
4114
4115These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4116
4117
4118<procedure>(surface-palette surface) → sdl2:palette or #f</procedure>
4119<setter>(set! (surface-palette surface) palette)</setter>
4120<setter>(surface-palette-set! surface palette)</setter>
4121
4122{{surface-palette}} returns the surface's palette, or #f if it has no palette.
4123It is equivalent to {{(compose pixel-format-palette surface-format)}}.
4124
4125The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
4126
4127See [[https://wiki.libsdl.org/SDL_SetSurfacePalette|SDL_SetSurfacePalette]].
4128
4129
4130<setter>(surface-rle-set! surface enable?)</setter>
4131
4132Enable RLE acceleration if {{enable?}} is #t, or disable RLE acceleration if {{enable?}} is #f.
4133See [[https://wiki.libsdl.org/SDL_SetSurfaceRLE|SDL_SetSurfaceRLE]].
4134
4135Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4136
4137
4138
4139=== Texture
4140
4141==== sdl2:texture
4142
4143sdl2:texture is a record type that wraps a pointer to an
4144[[https://wiki.libsdl.org/SDL_Texture|SDL_Texture]] struct.
4145
4146Textures are available in '''sdl2 egg version 0.2.0 and higher'''.
4147
4148
4149<procedure>(texture? obj) → boolean</procedure>
4150
4151Returns #t if {{obj}} is an sdl2:texture.
4152
4153This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4154
4155
4156<procedure>(create-texture renderer format access w h) → sdl2:texture</procedure>
4157<procedure>(create-texture* renderer format access w h) → sdl2:texture</procedure>
4158
4159Create a new sdl2:texture using the given sdl2:renderer and settings.
4160
4161* {{renderer}} must be a sdl2:renderer.
4162* {{format}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format enum symbol]] or equivalent integer.
4163* {{access}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#texture-access|texture access enum symbol]] or equivalent integer:
4164** {{'static}}
4165** {{'streaming}}
4166** {{'target}}
4167* {{w}} must be an integer, specifying the texture's width in pixels.
4168* {{h}} must be an integer, specifying the texture's height in pixels.
4169
4170These procedures signal an exception of kind {{(exn sdl2)}} if the sdl2:texture could not be created.
4171
4172* {{create-texture}} returns a managed sdl2:texture.
4173* {{create-texture*}} returns an unmanaged sdl2:texture,
4174  which must be destroyed with {{destroy-texture!}} when you are done with it.
4175
4176These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4177
4178
4179<procedure>(create-texture-from-surface renderer surface) → sdl2:texture</procedure>
4180<procedure>(create-texture-from-surface* renderer surface) → sdl2:texture</procedure>
4181
4182Create a new sdl2:texture from a sdl2:surface.
4183
4184The texture will contain a copy of the pixel data from the surface.
4185The texture will have the same color mod and alpha mod as the surface.
4186If the surface had a color key, the texture will have {{'blend}} blend mode;
4187otherwise it will have the same blend mode as the surface.
4188
4189* {{create-texture-from-surface}} returns a managed sdl2:texture.
4190* {{create-texture-from-surface*}} returns an unmanaged sdl2:texture,
4191  which must be destroyed with {{destroy-texture!}} when you are done with it.
4192
4193These procedures signal an exception of kind {{(exn sdl2)}} if the sdl2:texture could not be created.
4194
4195These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4196
4197
4198<procedure>(destroy-texture! texture)</procedure>
4199
4200Destroy the sdl2:texture, freeing its underlying struct.
4201{{texture}}'s pointer will be set to null (see {{struct-null?}}).
4202It is safe to call tihs procedure with managed on unmanaged sdl2:textures.
4203It is safe (but has no effect) to destroy an sdl2:texture multiple times.
4204
4205See [[https://wiki.libsdl.org/SDL_DestroyTexture|SDL_DestroyTexture]].
4206
4207This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4208
4209
4210<procedure>(query-texture texture) → [format access w h]</procedure>
4211<procedure>(query-texture-raw texture) → [format-int access-int w h]</procedure>
4212
4213Get multiple pieces of information about the texture.
4214See [[https://wiki.libsdl.org/SDL_QueryTexture|SDL_QueryTexture]].
4215
4216{{query-texture}} returns multiple values:
4217
4218; format : The sdl2:texture's pixel format, as a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format enum symbol]]
4219; access : The sdl2:texture's access mode, as a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#texture-access|texture access enum symbol]]
4220; w : The sdl2:texture's width, as a nonnegative integer measured in pixels
4221; h : The sdl2:texture's height, as a nonnegative integer measured in pixels
4222
4223{{query-texture-raw}} is similar, except it returns raw integer values (not symbols) for format and access.
4224
4225These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4226
4227If you only want one of these pieces of information,
4228it is more convenient and efficient to use one of these procedures instead:
4229
4230* {{texture-format}}
4231* {{texture-access}}
4232* {{texture-w}}
4233* {{texture-h}}
4234
4235
4236<procedure>(texture-format texture) → symbol</procedure>
4237
4238Get the sdl2:texture's pixel format, as a pixel format enum symbol.
4239This is equivalent to {{(nth-value 0 (query-texture texture))}},
4240but more convenient and efficient.
4241
4242This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4243
4244
4245<procedure>(texture-access texture) → symbol</procedure>
4246
4247Get the sdl2:texture's access mode, as a texture access enum symbol.
4248This is equivalent to {{(nth-value 1 (query-texture texture))}},
4249but more convenient and efficient.
4250
4251This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4252
4253
4254<procedure>(texture-w texture) → integer</procedure>
4255
4256Get the sdl2:texture's width, as a nonnegative integer measured in pixels.
4257This is equivalent to {{(nth-value 2 (query-texture texture))}},
4258but more convenient and efficient.
4259
4260This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4261
4262
4263<procedure>(texture-h texture) → integer</procedure>
4264
4265Get the sdl2:texture's height, as a nonnegative integer measured in pixels.
4266This is equivalent to {{(nth-value 3 (query-texture texture))}},
4267but more convenient and efficient.
4268
4269This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4270
4271
4272<procedure>(texture-alpha-mod texture) → integer</procedure>
4273<setter>(set! (texture-alpha-mod texture) mod)</setter>
4274<setter>(texture-alpha-mod-set! texture mod)</setter>
4275
4276See [[https://wiki.libsdl.org/SDL_GetTextureAlphaMod|SDL_GetTextureAlphaMod]]
4277and [[https://wiki.libsdl.org/SDL_SetTextureAlphaMod|SDL_SetTextureAlphaMod]].
4278
4279These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4280
4281These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4282
4283
4284<procedure>(texture-blend-mode texture) → symbol</procedure>
4285<procedure>(texture-blend-mode-raw texture) → integer</procedure>
4286<setter>(set! (texture-blend-mode texture) mode)</setter>
4287<setter>(texture-blend-mode-set! texture mode)</setter>
4288
4289See [[https://wiki.libsdl.org/SDL_GetTextureBlendMode|SDL_GetTextureBlendMode]]
4290and [[https://wiki.libsdl.org/SDL_SetTextureBlendMode|SDL_SetTextureBlendMode]].
4291
4292* {{texture-blend-mode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-mode|blend mode symbol]]:
4293** {{'none}}
4294** {{'blend}}
4295** {{'add}}
4296** {{'mod}}
4297* {{texture-blend-mode-raw}} returns an integer.
4298* The setters accept either a symbol or integer.
4299
4300These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4301
4302These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4303
4304
4305<procedure>(texture-color-mod texture) → [r g b]</procedure>
4306<procedure>(texture-colour-mod texture) → [r g b]</procedure>
4307<setter>(set! (texture-color-mod texture) rgb)</setter>
4308<setter>(set! (texture-colour-mod texture) rgb)</setter>
4309<setter>(texture-color-mod-set! texture rgb)</setter>
4310<setter>(texture-colour-mod-set! texture rgb)</setter>
4311
4312See [[https://wiki.libsdl.org/SDL_GetTextureColorMod|SDL_GetTextureColorMod]]
4313and [[https://wiki.libsdl.org/SDL_SetTextureColorMod|SDL_SetTextureColorMod]].
4314
4315{{texture-color-mod}} and {{texture-colour-mod}} return multiple values.
4316
4317The setters accept either a list {{(r g b)}} of color values, or an sdl2:color (the sdl2:color's "a" field will be ignored).
4318
4319These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4320
4321These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4322
4323
4324<procedure>(lock-texture-raw! texture rect) → [pixels pitch]</procedure>
4325
4326Lock the texture so that its pixel data can be overwritten.
4327This is for advanced users, and must be used with caution.
4328See [[https://wiki.libsdl.org/SDL_LockTexture|SDL_LockTexture]].
4329See also {{unlock-texture!}}.
4330
4331* {{texture}} is the sdl2:texture that you wish to modify
4332* {{rect}} is either an sdl2:rect (to lock part of the texture), or #f (to lock all of the texture).
4333
4334This procedure returns multiple values:
4335
4336; pixels : A raw pointer that you can write pixel data to. Does not necessarily contain the old data.
4337; pitch : An integer indicating the pitch of the pixel data
4338
4339Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4340
4341This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4342
4343
4344<procedure>(unlock-texture! texture)</procedure>
4345
4346Unlock the texture, applying the new pixel data to the texture.
4347This is for advanced users, and must be used with caution.
4348See [[https://wiki.libsdl.org/SDL_UnlockTexture|SDL_UnlockTexture]].
4349See also {{lock-texture-raw!}}.
4350
4351This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4352
4353
4354<procedure>(update-texture-raw! texture rect pixels pitch)</procedure>
4355
4356Overwrite part or all of the texture's pixel data.
4357This is for advanced users, and must be used with caution.
4358See [[https://wiki.libsdl.org/SDL_UpdateTexture|SDL_UpdateTexture]].
4359
4360* {{texture}} is the sdl2:texture that you wish to update
4361* {{rect}} is either an sdl2:rect (to update part of the texture), or #f (to update all of the texture)
4362* {{pixels}} is a pointer or locative to raw pixel data
4363* {{pitch}} is an integer describing the pitch of the pixel data
4364
4365Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4366
4367This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4368
4369
4370<procedure>(update-yuv-texture-raw! texture rect y-plane y-pitch u-plane u-pitch v-plane v-pitch)</procedure>
4371
4372Overwrite part or all of a YV12- or IYUV-formatted texture's pixel data.
4373This is for advanced users, and must be used with caution.
4374See [[https://wiki.libsdl.org/SDL_UpdateYUVTexture|SDL_UpdateYUVTexture]].
4375
4376* {{texture}} is the sdl2:texture that you wish to update
4377* {{rect}} is either an sdl2:rect (to update part of the texture), or #f (to update all of the texture)
4378* {{y-plane}} is a pointer or locative to raw pixel data for the Y plane
4379* {{y-pitch}} is an integer describing the pitch of the Y pixel data
4380* {{u-plane}} is a pointer or locative to raw pixel data for the U plane
4381* {{u-pitch}} is an integer describing the pitch of the U pixel data
4382* {{v-plane}} is a pointer or locative to raw pixel data for the V plane
4383* {{v-pitch}} is an integer describing the pitch of the V pixel data
4384
4385Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4386
4387This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4388It requires '''SDL 2.0.1 or higher'''.
4389It signals an error if the compiled version of SDL is not high enough.
4390Use the [[#version-feature-identifiers|{{libSDL-2.0.1+}} feature identifier]]
4391to check before calling this procedure.
4392
4393
4394
4395=== Timer
4396
4397<procedure>(delay! milliseconds)</procedure>
4398
4399See [[https://wiki.libsdl.org/SDL_Delay|SDL_Delay]].
4400
4401'''CAUTION:''' This procedure is not compatible with [[/manual/Unit srfi-18|SRFI-18]]
4402threads. It will cause '''all threads to sleep''' for the given
4403duration. If you are using multiple threads, you should instead call
4404SRFI-18's {{thread-sleep!}}, which will cause only the current thread
4405to sleep. For example, call {{(thread-sleep! 0.025)}} instead of
4406{{(delay! 25)}}.
4407
4408
4409<procedure>(get-ticks) → integer</procedure>
4410
4411See [[https://wiki.libsdl.org/SDL_GetTicks|SDL_GetTicks]].
4412
4413
4414<procedure>(get-performance-counter) → integer</procedure>
4415
4416See [[https://wiki.libsdl.org/SDL_GetPerformanceCounter|SDL_GetPerformanceCounter]].
4417
4418
4419<procedure>(get-performance-frequency) → integer</procedure>
4420
4421See [[https://wiki.libsdl.org/SDL_GetPerformanceFrequency|SDL_GetPerformanceFrequency]].
4422
4423
4424
4425=== Touch / Gesture
4426
4427==== Touch / Gesture Functions
4428
4429<procedure>(get-num-touch-devices) → integer</procedure>
4430
4431See [[https://wiki.libsdl.org/SDL_GetNumTouchDevices|SDL_GetNumTouchDevices]].
4432
4433
4434<procedure>(get-touch-device device-id) → integer</procedure>
4435
4436See [[https://wiki.libsdl.org/SDL_GetTouchDevice|SDL_GetTouchDevice]].
4437
4438Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4439
4440
4441<procedure>(get-num-touch-fingers touch-id) → integer</procedure>
4442
4443See [[https://wiki.libsdl.org/SDL_GetNumTouchFingers|SDL_GetNumTouchFingers]].
4444
4445
4446<procedure>(get-touch-finger touch-id index) → sdl2:finger</procedure>
4447
4448See [[https://wiki.libsdl.org/SDL_GetTouchFinger|SDL_GetTouchFinger]].
4449
4450Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4451
4452
4453==== sdl2:finger
4454
4455sdl2:finger is a record type that wraps a pointer to an
4456[[https://wiki.libsdl.org/SDL_Finger|SDL_Finger]] struct.
4457
4458
4459<procedure>(finger? obj) → boolean</procedure>
4460
4461Returns #t if {{obj}} is an sdl2:finger.
4462
4463
4464<procedure>(finger-id finger) → integer</procedure>
4465
4466Get the sdl2:finger's "id" field, as an integer.
4467
4468
4469<procedure>(finger-x finger) → float</procedure>
4470
4471Get 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.
4472
4473
4474<procedure>(finger-y finger) → float</procedure>
4475
4476Get 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.
4477
4478
4479<procedure>(finger-pressure finger) → float</procedure>
4480
4481Get 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.
4482
4483
4484
4485=== Version
4486
4487==== Version Feature Identifiers
4488
4489In '''sdl2 egg version 0.2.0 and higher''', the egg automatically registers feature identifiers
4490which can be used to detect the versions of the sdl2 egg and SDL at compile time or run time,
4491for example using the {{cond-expand}} macro, {{#+foo}} syntax, or the {{feature?}} procedure.
4492
4493Some or all of the following feature identifiers will be registered depending on the circumstances:
4494
4495<table>
4496  <tr>
4497    <th>Feature ID</th>
4498    <th>Meaning</th>
4499  </tr>
4500  <tr>
4501    <td>sdl2</td>
4502    <td>Using any version of the sdl2 egg</td>
4503  <tr>
4504  <tr>
4505    <td>sdl2-0.2.0+</td>
4506    <td>Using sdl2 egg 0.2.0 or higher</td>
4507  <tr>
4508  <tr>
4509    <td>libSDL-2.0.0+</td>
4510    <td>The sdl2 egg was compiled with SDL 2.0.0 or higher</td>
4511  <tr>
4512  <tr>
4513    <td>libSDL-2.0.1+</td>
4514    <td>... 2.0.1 or higher</td>
4515  <tr>
4516  <tr>
4517    <td>libSDL-2.0.2+</td>
4518    <td>... 2.0.2 or higher</td>
4519  <tr>
4520  <tr>
4521    <td>libSDL-2.0.3+</td>
4522    <td>... 2.0.3 or higher</td>
4523  <tr>
4524  <tr>
4525    <td>libSDL-2.0.4+</td>
4526    <td>... 2.0.4 or higher</td>
4527  </tr>
4528</table>
4529
4530These are cumulative, so if you are using the latest version of the sdl2 egg and the latest version of SDL, all of the above identifiers will be defined.
4531
4532Here are some examples of how you can use these identifiers:
4533
4534<enscript highlight="scheme">
4535(use (prefix sdl2 sdl2:))
4536
4537;; Compile time check using #+foo reader syntax:
4538#+(not sdl2-0.2.0+)
4539(begin-for-syntax
4540  (error "You need sdl2 egg 0.2.0 or higher to compile this program."))
4541
4542;; Compile-time check using cond-expand macro:
4543(cond-expand
4544 (libSDL-2.0.4+
4545  (include "file-that-needs-SDL-204.scm"))
4546 (else
4547  (include "alternative-file.scm")))
4548
4549;; Run-time check using feature? procedure:
4550(when (feature? 'sdl2)
4551  (print "You are using the sdl2 egg. The future seems bright."))
4552</enscript>
4553
4554
4555==== Version Functions
4556
4557<procedure>(version-at-least? major minor patch) → boolean</procedure>
4558
4559See [[https://wiki.libsdl.org/SDL_VERSION_ATLEAST|SDL_VERSION_ATLEAST]].
4560
4561Returns #t if the sdl2 egg was compiled with a version of SDL at least as high as specified.
4562For example, {{(version-at-least? 2 0 1)}} returns #t if the sdl2 egg was compiled with SDL 2.0.1 or higher.
4563
4564Some SDL features are only available after a certain version, so you can use this procedure to check whether the feature is available.
4565
4566
4567<procedure>(compiled-version) → list of integers</procedure>
4568<procedure>(current-version) → list of integers</procedure>
4569
4570Returns a list of three nonnegative integers, indicating a version number of SDL.
4571For example, the list {{(2 0 3)}} indicates SDL 2.0.3.
4572
4573* {{compiled-version}} returns the version of SDL that the sdl2 egg was compiled with.
4574* {{current-version}} returns the version of SDL that the sdl2 egg is currently using.
4575
4576For 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.
4577In such a case, {{compiled-version}} would return {{(2 0 3)}}, and {{current-version}} would return {{(2 1 0)}}.
4578But, features from the new version would not be available until the user recompiles the sdl2 egg.
4579
4580See [[https://wiki.libsdl.org/SDL_VERSION|SDL_VERSION]]
4581and [[https://wiki.libsdl.org/SDL_GetVersion|SDL_GetVersion]].
4582
4583
4584<constant>(egg-version) → list of integers</constant>
4585
4586Returns a list of three nonnegative integers,
4587indicating the version number of the sdl2 egg itself,
4588which is independent of the version number of SDL.
4589For example, the list {{'(1 2 3)}} means sdl2 egg version 1.2.3.
4590
4591'''NOTE:''' This procedure is available in '''sdl2 egg version 0.2.0 or later'''.
4592If you want to check the egg version,
4593but users of your program might be using earlier than egg version 0.2.0,
4594you can add the following code to your program.
4595It will define the {{egg-version}} procedure only if using an earlier version of the sdl2 egg.
4596
4597<enscript highlight="scheme">
4598(use (prefix sdl2 sdl2:))
4599
4600#+(not sdl2-0.2.0+)
4601(define (sdl2:egg-version) '(0 1 1))
4602
4603;; Usage:
4604(printf "You are using sdl2 egg version ~S.~%" (sdl2:egg-version))
4605</enscript>
4606
4607
4608
4609=== Window / Display Mode
4610
4611==== Window / Display Mode Functions
4612
4613<procedure>(create-window! title x y w h #!optional flags) → sdl2:window</procedure>
4614
4615See [[https://wiki.libsdl.org/SDL_CreateWindow|SDL_CreateWindow]].
4616
4617{{x}} and {{y}} can be integers, the symbol {{'centered}}, or the symbol {{'undefined}}.
4618
4619{{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):
4620
4621* {{'fullscreen}}
4622* {{'fullscreen-desktop}}
4623* {{'opengl}}
4624* {{'shown}}
4625* {{'hidden}}
4626* {{'borderless}}
4627* {{'resizable}}
4628* {{'minimized}}
4629* {{'maximized}}
4630* {{'input-grabbed}}
4631* {{'input-focus}}
4632* {{'mouse-focus}}
4633* {{'foreign}}
4634* {{'allow-high-dpi}} (requires '''sdl2 egg 0.2.0 and SDL 2.0.1 or higher''')
4635* {{'mouse-capture}} (requires '''sdl2 egg 0.2.0 and SDL 2.0.4 or higher''')
4636
4637
4638<procedure>(destroy-window! window)</procedure>
4639
4640See [[https://wiki.libsdl.org/SDL_DestroyWindow|SDL_DestroyWindow]].
4641
4642
4643<procedure>(get-window-from-id id) → sdl2:window</procedure>
4644
4645See [[https://wiki.libsdl.org/SDL_GetWindowFromID|SDL_GetWindowFromID]].
4646
4647'''NOTE:''' The returned window will be a new sdl2:window record pointing to the address of the existing window.
4648It will be {{equal?}} to other sdl2:window records for the same window, but not {{eq?}}.
4649
4650In '''sdl2 egg version 0.2.0 and higher''', this procedure signals an exception
4651of kind {{(exn sdl2)}} if there is no window with the given ID.
4652In earlier egg versions, this procedure returned a null sdl2:window.
4653
4654
4655<procedure>(update-window-surface! window)</procedure>
4656
4657See [[https://wiki.libsdl.org/SDL_UpdateWindowSurface|SDL_UpdateWindowSurface]].
4658
4659Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4660
4661
4662<procedure>(update-window-surface-rects! window rects)</procedure>
4663
4664See [[https://wiki.libsdl.org/SDL_UpdateWindowSurfaceRects|SDL_UpdateWindowSurfaceRects]].
4665
4666{{rects}} must be a list of sdl2:rects.
4667
4668Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4669
4670
4671<procedure>(show-window! window)</procedure>
4672
4673See [[https://wiki.libsdl.org/SDL_ShowWindow|SDL_ShowWindow]].
4674
4675
4676<procedure>(hide-window! window)</procedure>
4677
4678See [[https://wiki.libsdl.org/SDL_HideWindow|SDL_HideWindow]].
4679
4680
4681<procedure>(maximize-window! window)</procedure>
4682
4683See [[https://wiki.libsdl.org/SDL_MaximizeWindow|SDL_MaximizeWindow]].
4684
4685
4686<procedure>(minimize-window! window)</procedure>
4687
4688See [[https://wiki.libsdl.org/SDL_MinimizeWindow|SDL_MinimizeWindow]].
4689
4690
4691<procedure>(raise-window! window)</procedure>
4692
4693See [[https://wiki.libsdl.org/SDL_RaiseWindow|SDL_RaiseWindow]].
4694
4695
4696<procedure>(restore-window! window)</procedure>
4697
4698See [[https://wiki.libsdl.org/SDL_RestoreWindow|SDL_RestoreWindow]].
4699
4700
4701
4702==== sdl2:window
4703
4704sdl2:window is a record type that wraps a pointer to an
4705[[https://wiki.libsdl.org/SDL_CreateWindow|SDL_Window]] struct.
4706
4707
4708<procedure>(window? obj) → boolean</procedure>
4709
4710Returns #t if {{obj}} is an sdl2:window.
4711
4712
4713<procedure>(window-bordered? window) → boolean</procedure>
4714<setter>(set! (window-bordered? window) bordered)</setter>
4715<setter>(window-bordered-set! window bordered)</setter>
4716
4717Get or set whether the window has a border (window decoration).
4718#t means the window has a border, #f means the window is borderless.
4719
4720Setting this to #f has essentially the same effect as passing the {{'borderless}} flag to {{create-window!}} when creating the window.
4721
4722See [[https://wiki.libsdl.org/SDL_SetWindowBordered|SDL_SetWindowBordered]].
4723
4724
4725<procedure>(window-brightness window) → float</procedure>
4726<setter>(set! (window-brightness window) brightness)</setter>
4727<setter>(window-brightness-set! window brightness)</setter>
4728
4729See [[https://wiki.libsdl.org/SDL_GetWindowBrightness|SDL_GetWindowBrightness]]
4730and [[https://wiki.libsdl.org/SDL_SetWindowBrightness|SDL_SetWindowBrightness]].
4731
4732The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
4733
4734
4735<procedure>(window-display-index window) → integer</procedure>
4736
4737See [[https://wiki.libsdl.org/SDL_GetWindowDisplayIndex|SDL_GetWindowDisplayIndex]].
4738
4739Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4740
4741
4742<procedure>(window-display-mode window) → sdl2:display-mode</procedure>
4743<setter>(set! (window-display-mode window) display-mode)</setter>
4744<setter>(window-display-mode-set! window display-mode)</setter>
4745
4746See [[https://wiki.libsdl.org/SDL_GetWindowDisplayMode|SDL_GetWindowDisplayMode]]
4747and [[https://wiki.libsdl.org/SDL_SetWindowDisplayMode|SDL_SetWindowDisplayMode]].
4748
4749These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4750
4751
4752<procedure>(window-flags window) → list of symbols</procedure>
4753<procedure>(window-flags-raw window) → integer</procedure>
4754
4755See [[https://wiki.libsdl.org/SDL_GetWindowFlags|SDL_GetWindowFlags]].
4756
4757* {{window-flags}} returns a list of [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#window-flags|window flag symbols]].
4758* {{window-flags-raw}} returns an integer bitfield.
4759
4760
4761<procedure>(window-fullscreen window) → symbol or #f</procedure>
4762<setter>(set! (window-fullscreen window) mode)</setter>
4763<setter>(window-fullscreen-set! window mode)</setter>
4764
4765Get or set the sdl2:window's fullscreen mode.
4766See [[https://wiki.libsdl.org/SDL_SetWindowFullscreen|SDL_SetWindowFullscreen]].
4767
4768{{window-fullscreen}} returns one of the following values:
4769
4770* {{'fullscreen}} means "real" fullscreen mode
4771* {{'fullscreen-desktop}} means "fake" fullscreen mode that takes the size of the desktop
4772* {{#f}} means windowed (non-fullscreen) mode
4773
4774The setters accept any of the above values, or #t (which means the same as {{'fullscreen}}), or an equivalent integer value.
4775
4776The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
4777
4778
4779<procedure>(window-grab? window) → boolean</procedure>
4780<setter>(set! (window-grab? window) grab?)</setter>
4781<setter>(window-grab-set! window grab?)</setter>
4782
4783See [[https://wiki.libsdl.org/SDL_GetWindowGrab|SDL_GetWindowGrab]]
4784and [[https://wiki.libsdl.org/SDL_SetWindowGrab|SDL_SetWindowGrab]].
4785
4786
4787<procedure>(grabbed-window) → sdl2:window or #f</procedure>
4788
4789Returns the sdl2:window that currently has input grab, or #f if no window has input grab.
4790See [[https://wiki.libsdl.org/SDL_GetGrabbedWindow|SDL_GetGrabbedWindow]].
4791
4792'''NOTE:''' The returned window will be a new sdl2:window record pointing to the address of the existing window.
4793It will be {{equal?}} to other sdl2:window records for the same window, but not {{eq?}}.
4794
4795This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4796It requires '''SDL 2.0.4 or higher'''.
4797It signals an error if the compiled version of SDL is not high enough.
4798Use the [[#version-feature-identifiers|{{libSDL-2.0.4+}} feature identifier]]
4799to check before calling this procedure.
4800
4801
4802<setter>(window-icon-set! window icon-surface)</setter>
4803
4804See [[https://wiki.libsdl.org/SDL_SetWindowIcon|SDL_SetWindowIcon]].
4805
4806
4807<procedure>(window-id window) → integer</procedure>
4808
4809See [[https://wiki.libsdl.org/SDL_GetWindowID|SDL_GetWindowID]].
4810
4811
4812<procedure>(window-maximum-size window) → [width height]</procedure>
4813<setter>(set! (window-maximum-size window) size)</setter>
4814<setter>(window-maximum-size-set! window size)</setter>
4815
4816See [[https://wiki.libsdl.org/SDL_GetWindowMaximumSize|SDL_GetWindowMaximumSize]]
4817and [[https://wiki.libsdl.org/SDL_SetWindowMaximumSize|SDL_SetWindowMaximumSize]].
4818
4819{{window-maximum-size}} returns multiple values.
4820
4821The setters accept a list of integers {{(width height)}}.
4822
4823
4824<procedure>(window-minimum-size window) → [width height]</procedure>
4825<setter>(set! (window-minimum-size window) size)</setter>
4826<setter>(window-minimum-size-set! window size)</setter>
4827
4828See [[https://wiki.libsdl.org/SDL_GetWindowMinimumSize|SDL_GetWindowMinimumSize]]
4829and [[https://wiki.libsdl.org/SDL_SetWindowMinimumSize|SDL_SetWindowMinimumSize]].
4830
4831{{window-minimum-size}} returns multiple values.
4832
4833The setters accept a list of integers {{(width height)}}.
4834
4835
4836<procedure>(window-pixel-format window) → symbol</procedure>
4837<procedure>(window-pixel-format-raw window) → integer</procedure>
4838
4839Returns a symbol or integer indicating the given window's pixel format.
4840See [[https://wiki.libsdl.org/SDL_GetWindowPixelFormat|SDL_GetWindowPixelFormat]].
4841
4842* {{window-pixel-format}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]].
4843* {{window-pixel-format-raw}} returns an integer.
4844
4845
4846<procedure>(window-position window) → [x y]</procedure>
4847<setter>(set! (window-position window) pos)</setter>
4848<setter>(window-position-set! window pos)</setter>
4849
4850See [[https://wiki.libsdl.org/SDL_GetWindowPosition|SDL_GetWindowPosition]]
4851and [[https://wiki.libsdl.org/SDL_SetWindowPosition|SDL_SetWindowPosition]].
4852
4853{{window-position}} returns multiple values.
4854
4855The setters accept a list of integers {{(x y)}}.
4856
4857
4858<procedure>(window-size window) → [width height]</procedure>
4859<setter>(set! (window-size window) size)</setter>
4860<setter>(window-size-set! window size)</setter>
4861
4862See [[https://wiki.libsdl.org/SDL_GetWindowSize|SDL_GetWindowSize]]
4863and [[https://wiki.libsdl.org/SDL_SetWindowSize|SDL_SetWindowSize]].
4864
4865{{window-size}} returns multiple values.
4866
4867The setters accept a list of integers {{(width height)}}.
4868
4869
4870<procedure>(window-surface window) → sdl2:surface</procedure>
4871
4872See [[https://wiki.libsdl.org/SDL_GetWindowSurface|SDL_GetWindowSurface]].
4873
4874Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4875
4876
4877<procedure>(window-title window) → string</procedure>
4878<setter>(set! (window-title window) title)</setter>
4879<setter>(window-title-set! window title)</setter>
4880
4881See [[https://wiki.libsdl.org/SDL_GetWindowTitle|SDL_GetWindowTitle]]
4882and [[https://wiki.libsdl.org/SDL_SetWindowTitle|SDL_SetWindowTitle]].
4883
4884
4885
4886==== sdl2:display-mode
4887
4888sdl2:display-mode is a record type that wraps a pointer to an
4889[[https://wiki.libsdl.org/SDL_DisplayMode|SDL_DisplayMode]] struct.
4890
4891
4892<procedure>(display-mode? obj) → boolean</procedure>
4893
4894Returns #t if {{obj}} is an sdl2:display-mode.
4895
4896
4897<procedure>(make-display-mode #!optional format w h refresh-rate) → sdl2:display-mode</procedure>
4898<procedure>(make-display-mode* #!optional format w h refresh-rate) → sdl2:display-mode</procedure>
4899
4900Allocate and initialize a new sdl2:display-mode.
4901
4902{{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.
4903
4904{{w}}, {{h}}, and {{refresh-rate}} default to 0. They must be integers.
4905
4906* {{make-display-mode}} returns a managed sdl2:display-mode.
4907* {{make-display-mode*}} returns an unmanaged sdl2:display-mode, which must be freed with {{free-display-mode!}} when you are done with it.
4908
4909
4910<procedure>(free-display-mode! display-mode)</procedure>
4911
4912Free the memory of the sdl2:display-mode's underlying struct.
4913{{display-mode}}'s pointer will be set to null (see {{struct-null?}}).
4914It is safe to call this procedure with managed or unmanaged
4915sdl2:display-modes. It is safe (but has no effect) to free a struct
4916record multiple times.
4917
4918
4919<procedure>(display-mode-format display-mode) → symbol</procedure>
4920<procedure>(display-mode-format-raw display-mode) → integer</procedure>
4921<setter>(set! (display-mode-format display-mode) val)</setter>
4922<setter>(display-mode-format-set! display-mode val)</setter>
4923
4924Get or set the sdl2:display-mode's "format" field.
4925
4926* {{display-mode-format}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]].
4927* {{display-mode-format-raw}} returns an integer.
4928* The setters accept either a symbol or an integer.
4929
4930
4931<procedure>(display-mode-w display-mode) → integer</procedure>
4932<setter>(set! (display-mode-w display-mode) val)</setter>
4933<setter>(display-mode-w-set! display-mode val)</setter>
4934
4935Get or set the sdl2:display-mode's "w" field, as an integer.
4936
4937
4938<procedure>(display-mode-h display-mode) → integer</procedure>
4939<setter>(set! (display-mode-h display-mode) val)</setter>
4940<setter>(display-mode-h-set! display-mode val)</setter>
4941
4942Get or set the sdl2:display-mode's "h" field, as an integer.
4943
4944
4945<procedure>(display-mode-refresh-rate display-mode) → integer</procedure>
4946<setter>(set! (display-mode-refresh-rate display-mode) val)</setter>
4947<setter>(display-mode-refresh-rate-set! display-mode val)</setter>
4948
4949Get or set the sdl2:display-mode's "refresh-rate" field, as an integer.
4950
4951
4952
4953=== Miscellaneous
4954
4955<procedure>(clear-error!)</procedure>
4956
4957See [[https://wiki.libsdl.org/SDL_ClearError|SDL_ClearError]].
4958
4959
4960<procedure>(get-error) → string</procedure>
4961
4962See [[https://wiki.libsdl.org/SDL_GetError|SDL_GetError]].
4963
4964
4965<procedure>(set-error! message)</procedure>
4966
4967See [[https://wiki.libsdl.org/SDL_SetError|SDL_SetError]].
4968
4969Unlike SDL_SetError, this procedure only accepts one argument, a
4970string. You can use {{sprintf}} to do string substitution if desired.
4971
4972
4973<procedure>(get-platform) → string</procedure>
4974
4975See [[https://wiki.libsdl.org/SDL_GetPlatform|SDL_GetPlatform]].
4976
4977
4978<procedure>(screen-saver-enabled?) → boolean</procedure>
4979<setter>(set! (screen-saver-enabled?) enabled?)</setter>
4980<setter>(screen-saver-enabled-set! enabled?)</setter>
4981
4982See [[https://wiki.libsdl.org/SDL_IsScreenSaverEnabled|SDL_IsScreenSaverEnabled]],
4983[[https://wiki.libsdl.org/SDL_EnableScreenSaver|SDL_EnableScreenSaver]],
4984and [[https://wiki.libsdl.org/SDL_DisableScreenSaver|SDL_DisableScreenSaver]].
4985
4986
4987<procedure>(has-clipboard-text?) → boolean</procedure>
4988
4989See [[https://wiki.libsdl.org/SDL_HasClipboardText|SDL_HasClipboardText]].
4990
4991
4992<procedure>(get-clipboard-text) → string</procedure>
4993
4994See [[https://wiki.libsdl.org/SDL_GetClipboardText|SDL_GetClipboardText]].
4995
4996Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4997
4998
4999<procedure>(set-clipboard-text! text)</procedure>
5000
5001See [[https://wiki.libsdl.org/SDL_SetClipboardText|SDL_SetClipboardText]].
5002
5003Signals an exception of kind {{(exn sdl2)}} if an error occurs.
Note: See TracBrowser for help on using the repository browser.