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

Last change on this file since 33026 was 33026, checked in by John Croisant, 6 years ago

sdl2: Link to sdl2-ttf egg in Related Libraries.

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