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

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

Summary: sdl2: Updated docs.

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