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

Last change on this file since 32911 was 32911, checked in by John Croisant, 5 years ago

Summary: sdl2: More work on docs.

File size: 143.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<procedure>(map-rgba pixel-format r g b a) → fixnum</procedure>
805
806See [[https://wiki.libsdl.org/SDL_MapRGB|SDL_MapRGB]]
807and [[https://wiki.libsdl.org/SDL_MapRGBA|SDL_MapRGBA]].
808
809
810<procedure>(get-rgb pixel pixel-format) → [r g b]</procedure>
811<procedure>(get-rgba pixel pixel-format) → [r g b a]</procedure>
812
813See [[https://wiki.libsdl.org/SDL_GetRGB|SDL_GetRGB]]
814and [[https://wiki.libsdl.org/SDL_GetRGBA|SDL_GetRGBA]].
815
816These procedures return multiple values.
817
818
819==== Rect / Point
820
821<procedure>(rect-empty? rect) → boolean</procedure>
822
823See [[https://wiki.libsdl.org/SDL_RectEmpty|SDL_RectEmpty]].
824
825
826<procedure>(enclose-points points #!optional clip result-rect) → [rect any-enclosed?]</procedure>
827
828See [[https://wiki.libsdl.org/SDL_EnclosePoints|SDL_EnclosePoints]].
829
830{{points}} must be a list of sdl2:points.
831
832{{clip}} must be either an sdl2:rect or #f (the default). If {{clip}}
833is an sdl2:rect, points outside the clip rect will be ignored.
834
835If {{result-rect}} is omitted or #f, a new managed sdl2:rect will be
836returned. If {{result-rect}} is an sdl2:rect, it will be modified and
837returned. {{result-rect}} must not be the same object as either
838{{rect1}} or {{rect2}}.
839
840This procedure returns multiple values:
841
842; rect : An sdl2:rect that encloses all matching points. Possibly the same object as {{result-rect}}.
843; any-enclosed? : #t if any points were enclosed, or #f if all points were clipped
844
845
846<procedure>(has-intersection? rect1 rect2) → boolean</procedure>
847
848See [[https://wiki.libsdl.org/SDL_HasIntersection|SDL_HasIntersection]].
849
850
851<procedure>(intersect-rect rect1 rect2 #!optional result-rect) → [rect intersect?]</procedure>
852
853See [[https://wiki.libsdl.org/SDL_IntersectRect|SDL_IntersectRect]].
854
855If {{result-rect}} is omitted or #f, a new managed sdl2:rect will be
856returned. If {{result-rect}} is an sdl2:rect, it will be modified and
857returned. {{result-rect}} must not be the same object as either
858{{rect1}} or {{rect2}}.
859
860This procedure returns multiple values:
861
862; rect : An sdl2:rect of the intersection of {{rect1}} and {{rect2}}. Possibly the same object as {{result-rect}}.
863; intersect? : #t if {{rect1}} and {{rect2}} intersect, otherwise #f
864
865
866<procedure>(intersect-rect-and-line rect x1 y1 x2 y2) → [intersect? x1-new y1-new x2-new y2-new]</procedure>
867
868See [[https://wiki.libsdl.org/SDL_IntersectRectAndLine|SDL_IntersectRectAndLine]].
869
870This procedure returns multiple values:
871
872; intersect? : #t if the given line intersects with the rect
873; x1-new : the x value of the point within rect that is closest to the first point
874; y1-new : the y value ...
875; x2-new : the x value of the point within rect that is closest to the second point
876; y2-new : the y value ...
877
878
879<procedure>(union-rect rect1 rect2 #!optional result-rect) → rect</procedure>
880
881See [[https://wiki.libsdl.org/SDL_UnionRect|SDL_UnionRect]].
882
883If {{result-rect}} is omitted or #f, a new managed sdl2:rect will be
884returned. If {{result-rect}} is an sdl2:rect, it will be modified and
885returned. {{result-rect}} must not be the same object as either
886{{rect1}} or {{rect2}}.
887
888
889
890==== RWops
891
892<procedure>(rw-from-file filepath) → sdl2:rwops</procedure>
893
894See [[https://wiki.libsdl.org/SDL_RWFromFile|SDL_RWFromFile]].
895
896You should close the sdl2:rwops when you are done with it, using
897{{rw-close!}} or one of the procedures that can automatically close
898the sdl2:rwops, such as {{load-bmp-rw}}.
899
900
901<procedure>(rw-from-const-mem pointer) → sdl2:rwops</procedure>
902
903See [[https://wiki.libsdl.org/SDL_RWFromConstMem|SDL_RWFromConstMem]].
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-mem pointer) → sdl2:rwops</procedure>
911
912See [[https://wiki.libsdl.org/SDL_RWFromMem|SDL_RWFromMem]].
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-blob blob) → sdl2:rwops</procedure>
920
921Create a new sdl2:rwops that accesses the memory of the given
922[[http://wiki.call-cc.org/manual/Unit%20library#blobs|blob]]. You
923should 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
927You can also use this procedure to create a sdl2:rwops from a
928[[/manual/Unit srfi-4|SRFI-4]] numeric vector, by first converting it
929to a blob using e.g. {{u8vector->blob/shared}}.
930
931'''CAUTION:''' Creating a sdl2:rwops from a blob in CHICKEN-managed
932memory is unstable: the blob might be garbage collected or moved in
933memory, which would break the sdl2:rwops. To be safe, you should
934[[/manual/Unit lolevel#object-evict|evict]] the blob and create the
935sdl2:rwops from the evicted blob (not the original). You may wish to
936[[/manual/Unit lolevel#object-release|release]] the evicted blob after
937you have closed the sdl2:rwops. Example:
938
939<enscript highlight="scheme">
940(let* ((evicted-blob (object-evict '#${...}))
941       (rwops (sdl2:rw-from-blob evicted-blob))
942       (surf (sdl2:load-bmp-rw rwops #t)))
943  (object-release evicted-blob)
944  surf)
945</enscript>
946
947
948<procedure>(rw-from-string str) → sdl2:rwops</procedure>
949
950Create a new sdl2:rwops that accesses the memory of the given CHICKEN
951Scheme string. You should close the sdl2:rwops when you are done with
952it, using {{rw-close!}} or one of the procedures that can
953automatically close the sdl2:rwops, such as {{load-bmp-rw}}.
954
955'''CAUTION:''' Creating a sdl2:rwops from a string in CHICKEN-managed
956memory is unstable: the string might be garbage collected or moved in
957memory, which would break the sdl2:rwops. To be safe, you should
958[[/manual/Unit lolevel#object-evict|evict]] the string and create the
959sdl2:rwops from the evicted string (not the original). You may wish to
960[[/manual/Unit lolevel#object-release|release]] the evicted string
961after you have closed the sdl2:rwops. Example:
962
963<enscript highlight="scheme">
964(let* ((evicted-string (object-evict "..."))
965       (rwops (sdl2:rw-from-string evicted-string))
966       (surf (sdl2:load-bmp-rw rwops #t)))
967  (object-release evicted-string)
968  surf)
969</enscript>
970
971
972<procedure>(rw-close! rwops) → fixnum</procedure>
973
974See [[https://wiki.libsdl.org/SDL_RWclose|SDL_RWclose]].
975
976Close and clean up the given sdl2:rwops. This frees the memory used by
977the SDL_RWops struct itself, but does not free or release the pointer,
978blob, or string that the sdl2:rwops was reading/writing from. (It does
979close files opened with {{rw-from-file}}, though.)
980
981Returns zero if successful.
982
983
984
985==== Surface
986
987<procedure>(create-rgb-surface* flags width height depth rmask gmask bmask amask) → sdl2:surface</procedure>
988
989See [[https://wiki.libsdl.org/SDL_CreateRGBSurface|SDL_CreateRGBSurface]].
990
991Returns a new '''unmanaged''' sdl2:surface with the given properties.
992You must call {{free-surface!}} when you are done with it.
993
994See {{make-surface}} for a more convenient interface.
995
996
997<procedure>(create-rgb-surface-from* pixels width height depth pitch rmask gmask bmask amask) → sdl2:surface</procedure>
998
999Returns a new '''unmanaged''' sdl2:surface with the given properties,
1000using existing pixel data (a pointer, e.g. from {{surface-pixels-raw}}).
1001You must call {{free-surface!}} when you are done with it.
1002
1003See [[https://wiki.libsdl.org/SDL_CreateRGBSurfaceFrom|SDL_CreateRGBSurfaceFrom]].
1004
1005
1006<procedure>(convert-surface surface pixel-format) → sdl2:surface</procedure>
1007<procedure>(convert-surface* surface pixel-format) → sdl2:surface</procedure>
1008
1009Creates a copy of the given sdl2:surface, but converts it to the given sdl2:pixel-format.
1010
1011See [[https://wiki.libsdl.org/SDL_ConvertSurface|SDL_ConvertSurface]].
1012
1013* {{convert-surface}} returns a managed sdl2:surface.
1014* {{convert-surface*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
1015
1016
1017<procedure>(load-bmp path-string) → sdl2:surface</procedure>
1018<procedure>(load-bmp* filepath) → sdl2:surface</procedure>
1019
1020See [[https://wiki.libsdl.org/SDL_LoadBMP|SDL_LoadBMP]].
1021
1022Attempts to load a BMP image file. Returns a sdl2:surface containing
1023the image data, or #f if the image could not be loaded.
1024
1025'''NOTE:''' This procedure only supports certain kinds of BMP image.
1026Use the [[/egg/sdl2-image|sdl2-image egg]] for better BMP support,
1027plus support for loading other image formats like JPG, PNG, and GIF.
1028
1029* {{load-bmp}} returns a managed sdl2:surface.
1030* {{load-bmp*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
1031
1032
1033<procedure>(load-bmp-rw rwops #!optional close?) → sdl2:surface</procedure>
1034<procedure>(load-bmp-rw* rwops #!optional close?) → sdl2:surface</procedure>
1035
1036See [[https://wiki.libsdl.org/SDL_LoadBMP_RW|SDL_LoadBMP_RW]].
1037
1038Attempts to load a BMP image from the given sdl2:rwops. Returns a
1039sdl2:surface containing the image data, or #f if the image could not
1040be loaded.
1041
1042If {{close?}} is #t, {{rwops}} will be automatically closed (see
1043{{rw-close!}}) after the image is loaded. If {{close?}} is #f or
1044omitted, {{rwops}} will not be closed.
1045
1046'''NOTE:''' This procedure only supports certain kinds of BMP image.
1047Use the [[/egg/sdl2-image|sdl2-image egg]] for better BMP support,
1048plus support for loading other image formats like JPG, PNG, and GIF.
1049
1050* {{load-bmp-rw}} returns a managed sdl2:surface.
1051* {{load-bmp-rw*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
1052
1053
1054<procedure>(save-bmp! surface filepath) → fixnum</procedure>
1055
1056See [[https://wiki.libsdl.org/SDL_SaveBMP|SDL_SaveBMP]].
1057
1058Returns zero if successful.
1059
1060
1061<procedure>(save-bmp-rw! surface rwops #!optional close?) → fixnum</procedure>
1062
1063See [[https://wiki.libsdl.org/SDL_SaveBMP_RW|SDL_SaveBMP_RW]].
1064
1065If {{close?}} is #t, {{rwops}} will be automatically closed (see
1066{{rw-close!}}) after the image is loaded. If {{close?}} is #f or
1067omitted, {{rwops}} will not be closed.
1068
1069Returns zero if successful.
1070
1071
1072<procedure>(lock-surface! surface) → fixnum</procedure>
1073<procedure>(unlock-surface! surface)</procedure>
1074
1075See [[https://wiki.libsdl.org/SDL_LockSurface|SDL_LockSurface]]
1076and [[https://wiki.libsdl.org/SDL_UnlockSurface|SDL_UnlockSurface]].
1077
1078{{lock-surface!}} returns zero if successful.
1079
1080
1081<procedure>(must-lock? surface) → boolean</procedure>
1082
1083See [[https://wiki.libsdl.org/SDL_MUSTLOCK|SDL_MUSTLOCK]].
1084
1085
1086<procedure>(blit-surface! src src-rect dest dest-rect) → fixnum</procedure>
1087
1088See [[https://wiki.libsdl.org/SDL_BlitSurface|SDL_BlitSurface]].
1089
1090Returns zero if successful. May modify dest-rect.
1091
1092
1093<procedure>(blit-scaled! src src-rect dest dest-rect) → fixnum</procedure>
1094
1095See [[https://wiki.libsdl.org/SDL_BlitScaled|SDL_BlitScaled]].
1096
1097Returns zero if successful. May modify dest-rect.
1098
1099
1100<procedure>(fill-rect! surface rect color) → fixnum</procedure>
1101
1102See [[https://wiki.libsdl.org/SDL_FillRect|SDL_FillRect]].
1103
1104{{rect}} may be an sdl2:rect to fill part of the surface, or #f to fill
1105the entire surface.
1106
1107{{color}} may be an sdl2:color or a mapped color (an integer, like
1108returned by {{map-rgba}}).
1109
1110Returns zero if successful.
1111
1112
1113<procedure>(fill-rects! surface rects color) → fixnum</procedure>
1114
1115See [[https://wiki.libsdl.org/SDL_FillRects|SDL_FillRects]].
1116
1117{{rects}} must be a list of sdl2:rects.
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>(surface-ref surface x y) → sdl2:color</procedure>
1126<procedure>(surface-ref-raw surface x y) → fixnum</procedure>
1127<setter>(set! (surface-ref surface x y) color)</setter>
1128<setter>(surface-set! surface x y color)</setter>
1129
1130Get or set the color of the specified pixel on the surface.
1131Signals an error if {{x}} or {{y}} is out of bounds.
1132
1133* {{surface-ref}} returns an sdl2:color.
1134* {{surface-ref-raw}} returns a mapped color (an integer). You can use {{get-rgba}} to convert the mapped color to color fields.
1135* The setters accept either an sdl2:color or a mapped color.
1136
1137The setters automatically lock and unlock the surface if needed.
1138They ignore the surface's clip rect.
1139
1140
1141<procedure>(surface-clip-rect surface) → sdl2:rect</procedure>
1142<setter>(set! (surface-clip-rect surface) rect) → boolean</setter>
1143<setter>(surface-clip-rect-set! surface rect) → boolean</setter>
1144
1145{{surface-clip-rect}} returns a copy of the surface's clip rect.
1146See [[https://wiki.libsdl.org/SDL_GetClipRect|SDL_GetClipRect]].
1147
1148The setters sets the surface's clip rect to a copy of the given rect.
1149{{rect}} may be #f, which disables clipping.
1150See [[https://wiki.libsdl.org/SDL_SetClipRect|SDL_SetClipRect]].
1151
1152The 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).
1153
1154
1155<procedure>(surface-color-key surface) → sdl2:color or #f</procedure>
1156<procedure>(surface-colour-key surface) → sdl2:color or #f</procedure>
1157<procedure>(surface-color-key-raw surface) → fixnum or #f</procedure>
1158<procedure>(surface-colour-key-raw surface) → fixnum or #f</procedure>
1159<setter>(set! (surface-color-key surface) color) → boolean</setter>
1160<setter>(set! (surface-colour-key surface) color) → boolean</setter>
1161<setter>(surface-color-key-set! surface color) → boolean</setter>
1162<setter>(surface-colour-key-set! surface color) → boolean</setter>
1163
1164Get or set the sdl2:surface's color key.
1165
1166See [[https://wiki.libsdl.org/SDL_GetColorKey|SDL_GetColorKey]]
1167and [[https://wiki.libsdl.org/SDL_SetColorKey|SDL_SetColorKey]].
1168
1169* {{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.
1170* {{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.
1171* The setters accept either an sdl2:color, a mapped color (an integer), or #f to disable color keying. The setters return zero if successful.
1172
1173
1174<procedure>(surface-alpha-mod surface) → fixnum</procedure>
1175<setter>(set! (surface-alpha-mod surface) mod) → fixnum</setter>
1176<setter>(surface-alpha-mod-set! surface mod) → fixnum</setter>
1177
1178See [[https://wiki.libsdl.org/SDL_GetSurfaceAlphaMod|SDL_GetSurfaceAlphaMod]]
1179and [[https://wiki.libsdl.org/SDL_SetSurfaceAlphaMod|SDL_SetSurfaceAlphaMod]].
1180
1181The setters return zero if successful.
1182
1183
1184<procedure>(surface-blend-mode surface) → symbol</procedure>
1185<procedure>(surface-blend-mode-raw surface) → fixnum</procedure>
1186<setter>(set! (surface-blend-mode surface) mode) → fixnum</setter>
1187<setter>(surface-blend-mode-set! surface mode) → fixnum</setter>
1188
1189See [[https://wiki.libsdl.org/SDL_GetSurfaceBlendMode|SDL_GetSurfaceBlendMode]]
1190and [[https://wiki.libsdl.org/SDL_SetSurfaceBlendMode|SDL_SetSurfaceBlendMode]].
1191
1192* {{surface-blend-mode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-mode|blend mode symbol]]:
1193** {{'none}}
1194** {{'blend}}
1195** {{'add}}
1196** {{'mod}}
1197* {{surface-blend-mode-raw}} returns an integer.
1198* The setters accept either a symbol or integer.
1199  The setters return zero if successful.
1200
1201
1202<procedure>(surface-color-mod surface) → [r g b]</procedure>
1203<procedure>(surface-colour-mod surface) → [r g b]</procedure>
1204<setter>(set! (surface-color-mod surface) rgb)</setter>
1205<setter>(set! (surface-colour-mod surface) rgb)</setter>
1206<setter>(surface-color-mod-set! surface rgb)</setter>
1207<setter>(surface-colour-mod-set! surface rgb)</setter>
1208
1209See [[https://wiki.libsdl.org/SDL_GetSurfaceColorMod|SDL_GetSurfaceColorMod]]
1210and [[https://wiki.libsdl.org/SDL_SetSurfaceColorMod|SDL_SetSurfaceColorMod]].
1211
1212{{surface-color-mod}} and {{surface-colour-mod}} return multiple values.
1213
1214The setters accept either a list {{(r g b)}} of color values, or an sdl2:color (the sdl2:color's "a" field will be ignored).
1215
1216
1217<procedure>(surface-palette surface) → sdl2:palette or #f</procedure>
1218<setter>(set! (surface-palette surface) palette)</setter>
1219<setter>(surface-palette-set! surface palette)</setter>
1220
1221{{surface-palette}} returns the surface's palette, or #f if it has no palette.
1222It is equivalent to {{(compose pixel-format-palette surface-format)}}.
1223
1224See [[https://wiki.libsdl.org/SDL_SetSurfacePalette|SDL_SetSurfacePalette]].
1225
1226
1227<setter>(surface-rle-set! surface enable)</setter>
1228
1229See [[https://wiki.libsdl.org/SDL_SetSurfaceRLE|SDL_SetSurfaceRLE]].
1230
1231{{enable}} is #t to enable RLE acceleration or #f to disable it.
1232
1233
1234
1235==== Timer
1236
1237<procedure>(delay! milliseconds)</procedure>
1238
1239See [[https://wiki.libsdl.org/SDL_Delay|SDL_Delay]].
1240
1241'''CAUTION:''' This procedure is not compatible with [[/manual/Unit srfi-18|SRFI-18]]
1242threads. It will cause '''all threads to sleep''' for the given
1243duration. If you are using multiple threads, you should instead call
1244SRFI-18's {{thread-sleep!}}, which will cause only the current thread
1245to sleep. For example, call {{(thread-sleep! 0.025)}} instead of
1246{{(delay! 25)}}.
1247
1248
1249<procedure>(get-ticks) → fixnum</procedure>
1250
1251See [[https://wiki.libsdl.org/SDL_GetTicks|SDL_GetTicks]].
1252
1253
1254<procedure>(get-performance-counter) → fixnum</procedure>
1255
1256See [[https://wiki.libsdl.org/SDL_GetPerformanceCounter|SDL_GetPerformanceCounter]].
1257
1258
1259<procedure>(get-performance-frequency) → fixnum</procedure>
1260
1261See [[https://wiki.libsdl.org/SDL_GetPerformanceFrequency|SDL_GetPerformanceFrequency]].
1262
1263
1264
1265==== Version
1266
1267<procedure>(version-at-least? major minor patch) → boolean</procedure>
1268
1269See [[https://wiki.libsdl.org/SDL_VERSION_ATLEAST|SDL_VERSION_ATLEAST]].
1270
1271Returns #t if the sdl2 egg was compiled with a version of SDL at least as high as specified.
1272For example, {{(version-at-least? 2 0 1)}} returns #t if the sdl2 egg was compiled with SDL 2.0.1 or higher.
1273
1274Some SDL features are only available after a certain version, so you can use this procedure to check whether the feature is available.
1275
1276
1277<procedure>(compiled-version) → list of fixnums</procedure>
1278<procedure>(current-version) → list of fixnums</procedure>
1279
1280Returns a list of three nonnegative integers, indicating a version number of SDL.
1281For example, the list {{(2 0 3)}} indicates SDL 2.0.3.
1282
1283* {{compiled-version}} returns the version of SDL that the sdl2 egg was compiled with.
1284* {{current-version}} returns the version of SDL that the sdl2 egg is currently using.
1285
1286For 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.
1287In such a case, {{compiled-version}} would return {{(2 0 3)}}, and {{current-version}} would return {{(2 1 0)}}.
1288But, features from the new version would not be available until the user recompiles the sdl2 egg.
1289
1290See [[https://wiki.libsdl.org/SDL_VERSION|SDL_VERSION]]
1291and [[https://wiki.libsdl.org/SDL_GetVersion|SDL_GetVersion]].
1292
1293
1294
1295==== Window
1296
1297<procedure>(create-window! title x y w h #!optional flags) → sdl2:window</procedure>
1298
1299See [[https://wiki.libsdl.org/SDL_CreateWindow|SDL_CreateWindow]].
1300
1301{{x}} and {{y}} can be integers, the symbol {{'centered}}, or the symbol {{'undefined}}.
1302
1303{{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):
1304
1305* {{'fullscreen}}
1306* {{'fullscreen-desktop}}
1307* {{'opengl}}
1308* {{'shown}}
1309* {{'hidden}}
1310* {{'borderless}}
1311* {{'resizable}}
1312* {{'minimized}}
1313* {{'maximized}}
1314* {{'input-grabbed}}
1315* {{'input-focus}}
1316* {{'mouse-focus}}
1317* {{'foreign}}
1318
1319
1320<procedure>(get-window-from-id id) → sdl2:window</procedure>
1321
1322See [[https://wiki.libsdl.org/SDL_GetWindowFromID|SDL_GetWindowFromID]].
1323
1324
1325<procedure>(destroy-window! window)</procedure>
1326
1327See [[https://wiki.libsdl.org/SDL_DestroyWindow|SDL_DestroyWindow]].
1328
1329
1330<procedure>(update-window-surface! window) → fixnum</procedure>
1331
1332See [[https://wiki.libsdl.org/SDL_UpdateWindowSurface|SDL_UpdateWindowSurface]].
1333
1334Returns zero if successful.
1335
1336
1337<procedure>(update-window-surface-rects! window rects) → fixnum</procedure>
1338
1339See [[https://wiki.libsdl.org/SDL_UpdateWindowSurfaceRects|SDL_UpdateWindowSurfaceRects]].
1340
1341{{rects}} must be a list of sdl2:rects.
1342
1343Returns zero if successful.
1344
1345
1346<procedure>(show-window! window)</procedure>
1347
1348See [[https://wiki.libsdl.org/SDL_ShowWindow|SDL_ShowWindow]].
1349
1350
1351<procedure>(hide-window! window)</procedure>
1352
1353See [[https://wiki.libsdl.org/SDL_HideWindow|SDL_HideWindow]].
1354
1355
1356<procedure>(maximize-window! window)</procedure>
1357
1358See [[https://wiki.libsdl.org/SDL_MaximizeWindow|SDL_MaximizeWindow]].
1359
1360
1361<procedure>(minimize-window! window)</procedure>
1362
1363See [[https://wiki.libsdl.org/SDL_MinimizeWindow|SDL_MinimizeWindow]].
1364
1365
1366<procedure>(raise-window! window)</procedure>
1367
1368See [[https://wiki.libsdl.org/SDL_RaiseWindow|SDL_RaiseWindow]].
1369
1370
1371<procedure>(restore-window! window)</procedure>
1372
1373See [[https://wiki.libsdl.org/SDL_RestoreWindow|SDL_RestoreWindow]].
1374
1375
1376<procedure>(window-bordered? window) → boolean</procedure>
1377<setter>(set! (window-bordered? window) bordered)</setter>
1378<setter>(window-bordered-set! window bordered)</setter>
1379
1380Get or set whether the window has a border (window decoration).
1381#t means the window has a border, #f means the window is borderless.
1382
1383Setting this to #f has essentially the same effect as passing the {{'borderless}} flag to {{create-window!}} when creating the window.
1384
1385See [[https://wiki.libsdl.org/SDL_SetWindowBordered|SDL_SetWindowBordered]].
1386
1387
1388<procedure>(window-brightness window) → float</procedure>
1389<setter>(set! (window-brightness window) brightness) → fixnum</setter>
1390<setter>(window-brightness-set! window brightness) → fixnum</setter>
1391
1392See [[https://wiki.libsdl.org/SDL_GetWindowBrightness|SDL_GetWindowBrightness]]
1393and [[https://wiki.libsdl.org/SDL_SetWindowBrightness|SDL_SetWindowBrightness]].
1394
1395The setters return zero if successful.
1396
1397
1398<procedure>(window-display-index window) → fixnum</procedure>
1399
1400See [[https://wiki.libsdl.org/SDL_GetWindowDisplayIndex|SDL_GetWindowDisplayIndex]].
1401
1402
1403<procedure>(window-display-mode window) → sdl2:display-mode</procedure>
1404<setter>(set! (window-display-mode window) display-mode) → fixnum</setter>
1405<setter>(window-display-mode-set! window display-mode) → fixnum</setter>
1406
1407See [[https://wiki.libsdl.org/SDL_GetWindowDisplayMode|SDL_GetWindowDisplayMode]]
1408and [[https://wiki.libsdl.org/SDL_SetWindowDisplayMode|SDL_SetWindowDisplayMode]].
1409
1410The setters return zero if successful.
1411
1412
1413<procedure>(window-flags window) → list of symbols</procedure>
1414<procedure>(window-flags-raw window) → fixnum</procedure>
1415
1416See [[https://wiki.libsdl.org/SDL_GetWindowFlags|SDL_GetWindowFlags]].
1417
1418* {{window-flags}} returns a list of [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#window-flags|window flag symbols]].
1419* {{window-flags-raw}} returns an integer bitfield.
1420
1421
1422<procedure>(window-fullscreen window) → symbol or #f</procedure>
1423<setter>(set! (window-fullscreen window) mode)</setter>
1424<setter>(window-fullscreen-set! window mode)</setter>
1425
1426Get or set the sdl2:window's fullscreen mode.
1427
1428{{window-fullscreen}} returns one of the following values:
1429
1430* {{'fullscreen}} means "real" fullscreen mode
1431* {{'fullscreen-desktop}} means "fake" fullscreen mode that takes the size of the desktop
1432* {{#f}} means windowed (non-fullscreen) mode
1433
1434The setters accept any of the above values, or #t (which means the same as {{'fullscreen}}), or an equivalent integer value.
1435
1436See [[https://wiki.libsdl.org/SDL_SetWindowFullscreen|SDL_SetWindowFullscreen]].
1437
1438
1439<procedure>(window-grab? window) → boolean</procedure>
1440<setter>(set! (window-grab? window) grab?)</setter>
1441<setter>(window-grab-set! window grab?)</setter>
1442
1443See [[https://wiki.libsdl.org/SDL_GetWindowGrab|SDL_GetWindowGrab]]
1444and [[https://wiki.libsdl.org/SDL_SetWindowGrab|SDL_SetWindowGrab]].
1445
1446
1447<setter>(window-icon-set! window icon-surface)</setter>
1448
1449See [[https://wiki.libsdl.org/SDL_SetWindowIcon|SDL_SetWindowIcon]].
1450
1451
1452<procedure>(window-id window) → fixnum</procedure>
1453
1454See [[https://wiki.libsdl.org/SDL_GetWindowID|SDL_GetWindowID]].
1455
1456
1457<procedure>(window-maximum-size window) → [width height]</procedure>
1458<setter>(set! (window-maximum-size window) size)</setter>
1459<setter>(window-maximum-size-set! window size)</setter>
1460
1461See [[https://wiki.libsdl.org/SDL_GetWindowMaximumSize|SDL_GetWindowMaximumSize]]
1462and [[https://wiki.libsdl.org/SDL_SetWindowMaximumSize|SDL_SetWindowMaximumSize]].
1463
1464{{window-maximum-size}} returns multiple values.
1465
1466The setters accept a list of integers {{(width height)}}.
1467
1468
1469<procedure>(window-minimum-size window) → [width height]</procedure>
1470<setter>(set! (window-minimum-size window) size)</setter>
1471<setter>(window-minimum-size-set! window size)</setter>
1472
1473See [[https://wiki.libsdl.org/SDL_GetWindowMinimumSize|SDL_GetWindowMinimumSize]]
1474and [[https://wiki.libsdl.org/SDL_SetWindowMinimumSize|SDL_SetWindowMinimumSize]].
1475
1476{{window-minimum-size}} returns multiple values.
1477
1478The setters accept a list of integers {{(width height)}}.
1479
1480
1481<procedure>(window-pixel-format window) → sdl2:pixel-format</procedure>
1482
1483See [[https://wiki.libsdl.org/SDL_GetWindowPixelFormat|SDL_GetWindowPixelFormat]].
1484
1485
1486<procedure>(window-position window) → [x y]</procedure>
1487<setter>(set! (window-position window) pos)</setter>
1488<setter>(window-position-set! window pos)</setter>
1489
1490See [[https://wiki.libsdl.org/SDL_GetWindowPosition|SDL_GetWindowPosition]]
1491and [[https://wiki.libsdl.org/SDL_SetWindowPosition|SDL_SetWindowPosition]].
1492
1493{{window-position}} returns multiple values.
1494
1495The setters accept a list of integers {{(x y)}}.
1496
1497
1498<procedure>(window-size window) → [width height]</procedure>
1499<setter>(set! (window-size window) size)</setter>
1500<setter>(window-size-set! window size)</setter>
1501
1502See [[https://wiki.libsdl.org/SDL_GetWindowSize|SDL_GetWindowSize]]
1503and [[https://wiki.libsdl.org/SDL_SetWindowSize|SDL_SetWindowSize]].
1504
1505{{window-size}} returns multiple values.
1506
1507The setters accept a list of integers {{(width height)}}.
1508
1509
1510<procedure>(window-surface window) → sdl2:surface</procedure>
1511
1512See [[https://wiki.libsdl.org/SDL_GetWindowSurface|SDL_GetWindowSurface]].
1513
1514
1515<procedure>(window-title window) → string</procedure>
1516<setter>(set! (window-title window) title)</setter>
1517<setter>(window-title-set! window title)</setter>
1518
1519See [[https://wiki.libsdl.org/SDL_GetWindowTitle|SDL_GetWindowTitle]]
1520and [[https://wiki.libsdl.org/SDL_SetWindowTitle|SDL_SetWindowTitle]].
1521
1522
1523
1524==== Miscellaneous
1525
1526<procedure>(clear-error!)</procedure>
1527
1528See [[https://wiki.libsdl.org/SDL_ClearError|SDL_ClearError]].
1529
1530
1531<procedure>(get-error) → string</procedure>
1532
1533See [[https://wiki.libsdl.org/SDL_GetError|SDL_GetError]].
1534
1535
1536<procedure>(set-error! message)</procedure>
1537
1538See [[https://wiki.libsdl.org/SDL_SetError|SDL_SetError]].
1539
1540Unlike SDL_SetError, this procedure only accepts one argument, a
1541string. You can use {{sprintf}} to do string substitution if desired.
1542
1543
1544<procedure>(get-platform) → string</procedure>
1545
1546See [[https://wiki.libsdl.org/SDL_GetPlatform|SDL_GetPlatform]].
1547
1548
1549<procedure>(screen-saver-enabled?) → boolean</procedure>
1550<setter>(set! (screen-saver-enabled?) enabled?)</setter>
1551<setter>(screen-saver-enabled-set! enabled?)</setter>
1552
1553See [[https://wiki.libsdl.org/SDL_IsScreenSaverEnabled|SDL_IsScreenSaverEnabled]],
1554[[https://wiki.libsdl.org/SDL_EnableScreenSaver|SDL_EnableScreenSaver]],
1555and [[https://wiki.libsdl.org/SDL_DisableScreenSaver|SDL_DisableScreenSaver]].
1556
1557
1558<procedure>(has-clipboard-text?) → boolean</procedure>
1559
1560See [[https://wiki.libsdl.org/SDL_HasClipboardText|SDL_HasClipboardText]].
1561
1562
1563<procedure>(get-clipboard-text) → string</procedure>
1564
1565See [[https://wiki.libsdl.org/SDL_GetClipboardText|SDL_GetClipboardText]].
1566
1567
1568<procedure>(set-clipboard-text! text) → fixnum</procedure>
1569
1570See [[https://wiki.libsdl.org/SDL_SetClipboardText|SDL_SetClipboardText]].
1571Returns zero if successful.
1572
1573
1574
1575
1576=== Struct Bindings
1577
1578The sdl2 egg has many "struct record types", which are record types
1579that wrap a pointer to a certain kind of C structure from SDL. For
1580example, the sdl2:surface record type wraps a pointer to an
1581SDL_Surface struct.
1582
1583Each struct record type has some associated procedures, which get or
1584set the value of a certain field of the underlying C struct.
1585
1586
1587==== Struct Memory Management
1588
1589Some struct record types have procedures for allocating or freeing an
1590instance of that type. Each type that can be allocated has two "make"
1591procedures:
1592
1593* The procedure without an asterisk (e.g. {{make-event}}) returns a
1594  '''managed''' struct record, whose underlying struct will be
1595  automatically freed when the record is garbage collected.
1596
1597* The procedure with an asterisk (e.g. {{make-event*}}) returns an
1598  '''unmanaged''' struct record, which must be manually freed when you
1599  are done with it (e.g. using {{free-event!}}).
1600
1601Certain other procedures that return new struct records also follow
1602this convention, for example {{load-bmp}} vs. {{load-bmp*}}.
1603
1604In general, it is recommended to create managed struct records, so
1605that you don't have to worry about manually freeing them. However,
1606there is a slight performance overhead for each managed struct record,
1607so if you are creating and destroying very many struct records, you
1608can improve performance by creating unmanaged struct records and
1609manually freeing them when you are done with them. (But be careful! If
1610you forget to free them, your program will leak memory.)
1611
1612If you create an unmanaged struct record but later change your mind,
1613you can start managing it by using {{set-finalizer!}} with the
1614appropriate "free" procedure. (Note: it is not currently possible to
1615''stop'' managing a struct record.) For example:
1616
1617<enscript highlight="scheme">
1618;; Allocate an unmanaged sdl2:event.
1619(let ((my-event (sdl2:make-event*)))
1620  ;; Overwrite its data with the next pending event.
1621  (sdl2:wait-event! my-event)
1622
1623  (case (sdl2:event-type my-event)
1624    ;; Put keyboard events in a queue for later processing. We aren't
1625    ;; sure how long it will live, so start managing it, to be safe.
1626    ((key-down key-up)
1627     (set-finalizer! my-event sdl2:free-event!)
1628     (put-in-queue my-event))
1629    ;; If it is any other type of event, perform an immediate action
1630    ;; on it, then free it.
1631    (else
1632     (perform-immediate-action my-event)
1633     (sdl2:free-event! my-event))))
1634</enscript>
1635
1636It is safe to manually free managed struct records. In fact, doing so
1637can be beneficial to your program's memory footprint and performance,
1638because there will be less memory waiting to be freed by the garbage
1639collector. For example:
1640
1641<enscript highlight="scheme">
1642(let ((my-surf (sdl2:make-surface 800 600 32)))
1643  ;; ... do stuff with my-surf ...
1644  ;; Once you are done with my-surf, manually free it.
1645  (sdl2:free-surface! my-surf))
1646</enscript>
1647
1648As soon as you free a struct record, its pointer will be set to null,
1649and it will no longer be usable for most purposes. You cannot get or
1650set its fields, or pass it as an argument to most procedures. So be
1651careful not to free struct records that you still want to use!
1652
1653Some struct record types, such as sdl2:window, are not managed in this
1654way. Instead, you use certain SDL functions to work with them, such as
1655{{create-window!}} and {{destroy-window!}}.
1656
1657
1658<procedure>(struct-null? record) → boolean</procedure>
1659
1660Returns #t if the given record is wrapping a null pointer (i.e. a
1661pointer with memory address 0). This procedure can be used with any
1662struct record type provided by this library.
1663
1664There are two common reasons why a record might be wrapping a null
1665pointer:
1666
1667* After you free a record (e.g. using {{free-surface!}}), its pointer
1668  will be set to null.
1669* Certain procedures may return a record with a null pointer if an
1670  error occurs or the requested object does not exist.
1671
1672It is an error to get or set any field of a record that is wrapping a
1673null pointer. And, it is an error to pass null struct records to many
1674procedures. So, you can use this procedure to check whether it is safe
1675to use the record.
1676
1677
1678
1679==== sdl2:audio-cvt
1680
1681sdl2:audio-cvt is a record type that wraps a pointer to an
1682[[https://wiki.libsdl.org/SDL_AudioCVT|SDL_AudioCVT]] struct.
1683
1684
1685<procedure>(audio-cvt? obj) → boolean</procedure>
1686
1687Returns #t if {{obj}} is an sdl2:audio-cvt.
1688
1689
1690<procedure>(audio-cvt-needed audio-cvt) → fixnum</procedure>
1691
1692Get the sdl2:audio-cvt's "needed" field, as an integer.
1693
1694
1695<procedure>(audio-cvt-src-format audio-cvt) → symbol</procedure>
1696<procedure>(audio-cvt-src-format-raw audio-cvt) → fixnum</procedure>
1697
1698Get the sdl2:audio-cvt's "src-format" field.
1699
1700* {{audio-cvt-src-format}} returns an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#audio-formats|audio format symbol]].
1701* {{audio-cvt-src-format-raw}} returns an integer.
1702
1703
1704<procedure>(audio-cvt-dst-format audio-cvt) → symbol</procedure>
1705<procedure>(audio-cvt-dst-format-raw audio-cvt) → fixnum</procedure>
1706
1707Get the sdl2:audio-cvt's "dst-format" field.
1708
1709* {{audio-cvt-dst-format}} returns an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#audio-formats|audio format symbol]].
1710* {{audio-cvt-dst-format-raw}} returns an integer.
1711
1712
1713<procedure>(audio-cvt-rate-incr audio-cvt) → double</procedure>
1714
1715Get the sdl2:audio-cvt's "rate-incr" field, as a double precision floating point number.
1716
1717
1718<procedure>(audio-cvt-buf-raw audio-cvt) → pointer</procedure>
1719
1720Get the sdl2:audio-cvt's "buf" field, as a pointer to a C array of Uint8 numbers.
1721Use audio-cvt-len to get the length of the array.
1722
1723
1724<procedure>(audio-cvt-len audio-cvt) → fixnum</procedure>
1725
1726Get the sdl2:audio-cvt's "len" field, as an integer.
1727This is the length of the array returned by {{audio-cvt-buf-raw}}.
1728
1729
1730<procedure>(audio-cvt-len-cvt audio-cvt) → fixnum</procedure>
1731
1732Get the sdl2:audio-cvt's "len-cvt" field, as an integer.
1733
1734
1735<procedure>(audio-cvt-len-mult audio-cvt) → fixnum</procedure>
1736
1737Get the sdl2:audio-cvt's "len-mult" field, as an integer.
1738
1739
1740<procedure>(audio-cvt-len-ratio audio-cvt) → double</procedure>
1741
1742Get the sdl2:audio-cvt's "len-ratio" field, as a double precision floating point number.
1743
1744
1745
1746==== sdl2:audio-spec
1747
1748sdl2:audio-spec is a record type that wraps a pointer to an
1749[[https://wiki.libsdl.org/SDL_AudioSpec|SDL_AudioSpec]] struct.
1750
1751
1752<procedure>(audio-spec? obj) → boolean</procedure>
1753
1754Returns #t if {{obj}} is an sdl2:audio-spec.
1755
1756
1757<procedure>(audio-spec-freq audio-spec) → fixnum</procedure>
1758<setter>(set! (audio-spec-freq audio-spec) val)</setter>
1759<setter>(audio-spec-freq-set! audio-spec val)</setter>
1760
1761Get or set the sdl2:audio-spec's "freq" field, as an integer (int).
1762
1763
1764<procedure>(audio-spec-format audio-spec) → symbol</procedure>
1765<procedure>(audio-spec-format-raw audio-spec) → fixnum</procedure>
1766<setter>(set! (audio-spec-format audio-spec) val)</setter>
1767<setter>(audio-spec-format-set! audio-spec val)</setter>
1768
1769Get or set the sdl2:audio-spec's "format" field.
1770
1771* {{audio-spec-format}} returns an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#audio-formats|audio format symbol]].
1772* {{audio-spec-format-raw}} returns an integer.
1773* The setters accept either a symbol or an integer.
1774
1775
1776<procedure>(audio-spec-channels audio-spec) → fixnum</procedure>
1777<setter>(set! (audio-spec-channels audio-spec) val)</setter>
1778<setter>(audio-spec-channels-set! audio-spec val)</setter>
1779
1780Get or set the sdl2:audio-spec's "channels" field, as an integer (Uint8).
1781
1782
1783<procedure>(audio-spec-silence audio-spec) → fixnum</procedure>
1784
1785Get the sdl2:audio-spec's "silence" field, as an integer (Uint8).
1786
1787
1788<procedure>(audio-spec-samples audio-spec) → fixnum</procedure>
1789<setter>(set! (audio-spec-samples audio-spec) val)</setter>
1790<setter>(audio-spec-samples-set! audio-spec val)</setter>
1791
1792Get or set the sdl2:audio-spec's "samples" field, as an integer (Uint16).
1793
1794
1795<procedure>(audio-spec-size audio-spec) → fixnum</procedure>
1796
1797Get the sdl2:audio-spec's "size" field, as an integer (Uint32).
1798
1799
1800<procedure>(audio-spec-userdata-raw audio-spec) → pointer</procedure>
1801<setter>(set! (audio-spec-userdata-raw audio-spec) val)</setter>
1802<setter>(audio-spec-userdata-raw-set! audio-spec val)</setter>
1803
1804Get or set the sdl2:audio-spec's "userdata" field, as a pointer.
1805
1806
1807
1808==== sdl2:color
1809
1810sdl2:color is a record type that wraps a pointer to an
1811[[https://wiki.libsdl.org/SDL_Color|SDL_Color]] struct.
1812
1813
1814<procedure>(color? obj) → boolean</procedure>
1815<procedure>(colour? obj) → boolean</procedure>
1816
1817Returns #t if {{obj}} is an sdl2:color.
1818
1819
1820<procedure>(make-color #!optional r g b a) → sdl2:color</procedure>
1821<procedure>(make-colour #!optional r g b a) → sdl2:color</procedure>
1822<procedure>(make-color* #!optional r g b a) → sdl2:color</procedure>
1823<procedure>(make-colour* #!optional r g b a) → sdl2:color</procedure>
1824
1825Allocate and initialize a new sdl2:color.
1826
1827{{r}}, {{g}}, {{b}}, and {{a}} must be integers in the range 0 to 255 (inclusive).
1828{{r}}, {{g}}, and {{b}} default to 0.
1829{{a}} defaults to 255 (full opacity).
1830
1831* {{make-color}} and {{make-colour}} return a managed sdl2:color.
1832* {{make-color*}} and {{make-colour*}} return an unmanaged sdl2:color, which must be freed using {{free-color!}} when you are done with it.
1833
1834
1835<procedure>(free-color! color)</procedure>
1836<procedure>(free-colour! color)</procedure>
1837
1838Free the memory of the sdl2:color's underlying struct. {{color}}'s
1839pointer will be set to null (see {{struct-null?}}). It is safe to call
1840this procedure with managed or unmanaged sdl2:colors. It is safe (but
1841has no effect) to free a struct record multiple times.
1842
1843
1844<procedure>(color-r color) → fixnum</procedure>
1845<procedure>(colour-r color) → fixnum</procedure>
1846<setter>(set! (color-r color) val)</setter>
1847<setter>(set! (colour-r color) val)</setter>
1848<setter>(color-r-set! color val)</setter>
1849<setter>(colour-r-set! color val)</setter>
1850
1851Get or set the sdl2:color's "r" (red) field, as an integer in the range 0 to 255 (inclusive).
1852
1853
1854<procedure>(color-g color) → fixnum</procedure>
1855<procedure>(colour-g color) → fixnum</procedure>
1856<setter>(set! (color-g color) val)</setter>
1857<setter>(set! (colour-g color) val)</setter>
1858<setter>(color-g-set! color val)</setter>
1859<setter>(colour-g-set! color val)</setter>
1860
1861Get or set the sdl2:color's "g" (green) field, as an integer in the range 0 to 255 (inclusive).
1862
1863
1864<procedure>(color-b color) → fixnum</procedure>
1865<procedure>(colour-b color) → fixnum</procedure>
1866<setter>(set! (color-b color) val)</setter>
1867<setter>(set! (colour-b color) val)</setter>
1868<setter>(color-b-set! color val)</setter>
1869<setter>(colour-b-set! color val)</setter>
1870
1871Get or set the sdl2:color's "b" (blue) field, as an integer in the range 0 to 255 (inclusive).
1872
1873
1874<procedure>(color-a color) → fixnum</procedure>
1875<procedure>(colour-a color) → fixnum</procedure>
1876<setter>(set! (color-a color) val)</setter>
1877<setter>(set! (colour-a color) val)</setter>
1878<setter>(color-a-set! color val)</setter>
1879<setter>(colour-a-set! color val)</setter>
1880
1881Get or set the sdl2:color's "a" (alpha) field, as an integer in the range 0 to 255 (inclusive).
1882
1883
1884<setter>(color-set! color #!optional r g b a) → color</setter>
1885<setter>(colour-set! color #!optional r g b a) → color</setter>
1886
1887Convenient way of setting multiple fields of the sdl2:color.
1888Any arguments that are {{#f}} will cause no change to that field.
1889E.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.
1890Returns {{color}} after it is modified.
1891
1892
1893<procedure>(color->list color) → list of fixnums</procedure>
1894<procedure>(colour->list color) → list of fixnums</procedure>
1895
1896Returns a list {{(r g b a)}} containing the value of each field of the sdl2:color.
1897
1898
1899<procedure>(color=? color1 color2) → boolean</procedure>
1900<procedure>(colour=? color1 color2) → boolean</procedure>
1901
1902Efficiently compare two sdl2:colors.
1903Returns #t if the value of every field in {{color1}} is equal to the value of the corresponding field in {{color2}}.
1904
1905
1906<procedure>(copy-color color) → sdl2:color</procedure>
1907<procedure>(copy-colour color) → sdl2:color</procedure>
1908<procedure>(copy-color* color) → sdl2:color</procedure>
1909<procedure>(copy-colour* color) → sdl2:color</procedure>
1910
1911Efficiently copy the given sdl2:color, returning a new sdl2:color with the same values.
1912
1913* {{copy-color}} and {{copy-colour}} return a managed sdl2:color.
1914* {{copy-color*}} and {{copy-colour*}} return an unmanaged sdl2:color, which must be freed using {{free-color!}} when you are done with it.
1915
1916
1917
1918==== sdl2:cursor
1919
1920sdl2:cursor is a record type that wraps a pointer to an
1921[[https://wiki.libsdl.org/SDL_CreateCursor|SDL_Cursor]] struct.
1922
1923
1924<procedure>(cursor? obj) → boolean</procedure>
1925
1926Returns #t if {{obj}} is an sdl2:cursor.
1927
1928
1929
1930==== sdl2:display-mode
1931
1932sdl2:display-mode is a record type that wraps a pointer to an
1933[[https://wiki.libsdl.org/SDL_DisplayMode|SDL_DisplayMode]] struct.
1934
1935
1936<procedure>(display-mode? obj) → boolean</procedure>
1937
1938Returns #t if {{obj}} is an sdl2:display-mode.
1939
1940
1941<procedure>(make-display-mode #!optional format w h refresh-rate) → sdl2:display-mode</procedure>
1942<procedure>(make-display-mode* #!optional format w h refresh-rate) → sdl2:display-mode</procedure>
1943
1944Allocate and initialize a new sdl2:display-mode.
1945
1946{{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.
1947
1948{{w}}, {{h}}, and {{refresh-rate}} default to 0. They must be integers.
1949
1950* {{make-display-mode}} returns a managed sdl2:display-mode.
1951* {{make-display-mode*}} returns an unmanaged sdl2:display-mode, which must be freed with {{free-display-mode!}} when you are done with it.
1952
1953
1954<procedure>(free-display-mode! display-mode)</procedure>
1955
1956Free the memory of the sdl2:display-mode's underlying struct.
1957{{display-mode}}'s pointer will be set to null (see {{struct-null?}}).
1958It is safe to call this procedure with managed or unmanaged
1959sdl2:display-modes. It is safe (but has no effect) to free a struct
1960record multiple times.
1961
1962
1963<procedure>(display-mode-format display-mode) → symbol</procedure>
1964<procedure>(display-mode-format-raw display-mode) → fixnum</procedure>
1965<setter>(set! (display-mode-format display-mode) val)</setter>
1966<setter>(display-mode-format-set! display-mode val)</setter>
1967
1968Get or set the sdl2:display-mode's "format" field.
1969
1970* {{display-mode-format}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]].
1971* {{display-mode-format-raw}} returns an integer.
1972* The setters accept either a symbol or an integer.
1973
1974
1975<procedure>(display-mode-w display-mode) → fixnum</procedure>
1976<setter>(set! (display-mode-w display-mode) val)</setter>
1977<setter>(display-mode-w-set! display-mode val)</setter>
1978
1979Get or set the sdl2:display-mode's "w" field, as an integer.
1980
1981
1982<procedure>(display-mode-h display-mode) → fixnum</procedure>
1983<setter>(set! (display-mode-h display-mode) val)</setter>
1984<setter>(display-mode-h-set! display-mode val)</setter>
1985
1986Get or set the sdl2:display-mode's "h" field, as an integer.
1987
1988
1989<procedure>(display-mode-refresh-rate display-mode) → fixnum</procedure>
1990<setter>(set! (display-mode-refresh-rate display-mode) val)</setter>
1991<setter>(display-mode-refresh-rate-set! display-mode val)</setter>
1992
1993Get or set the sdl2:display-mode's "refresh-rate" field, as an integer.
1994
1995
1996
1997==== sdl2:event
1998
1999sdl2:event is a record type that wraps a pointer to an
2000[[https://wiki.libsdl.org/SDL_Event|SDL_Event]]. There are many
2001specific event structs in SDL, and the sdl2:event type wraps them all.
2002Each event struct has a corresponding variant of sdl2:event, described
2003below. Each variant has one or more associated
2004[[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbols]].
2005
2006
2007<table>
2008  <tr>
2009    <th>Variant of sdl2:event</th>
2010    <th>Underlying struct</th>
2011    <th>Event type symbol(s)</th>
2012  </tr>
2013  <tr>
2014    <td>[[#sdl2controller-axis-event|sdl2:controller-axis-event]]</td>
2015    <td>[[https://wiki.libsdl.org/SDL_ControllerAxisEvent|SDL_ControllerAxisEvent]]</td>
2016    <td>{{'controller-axis-motion}}</td>
2017  </tr>
2018  <tr>
2019    <td>[[#sdl2controller-button-event|sdl2:controller-button-event]]</td>
2020    <td>[[https://wiki.libsdl.org/SDL_ControllerButtonEvent|SDL_ControllerButtonEvent]]</td>
2021    <td>{{'controller-button-down}}<br>
2022        {{'controller-button-up}}</td>
2023  </tr>
2024  <tr>
2025    <td>[[#sdl2controller-device-event|sdl2:controller-device-event]]</td>
2026    <td>[[https://wiki.libsdl.org/SDL_ControllerDeviceEvent|SDL_ControllerDeviceEvent]]</td>
2027    <td>{{'controller-device-added}}<br>
2028        {{'controller-device-removed}}<br>
2029        {{'controller-device-remapped}}</td>
2030  </tr>
2031  <tr>
2032    <td>[[#sdl2dollar-gesture-event|sdl2:dollar-gesture-event]]</td>
2033    <td>[[https://wiki.libsdl.org/SDL_DollarGestureEvent|SDL_DollarGestureEvent]]</td>
2034    <td>{{'dollar-gesture}}<br>
2035        {{'dollar-record}}</td>
2036  </tr>
2037  <tr>
2038    <td>[[#sdl2drop-event|sdl2:drop-event]]</td>
2039    <td>[[https://wiki.libsdl.org/SDL_DropEvent|SDL_DropEvent]]</td>
2040    <td>{{'drop-file}}</td>
2041  </tr>
2042  <tr>
2043    <td>[[#sdl2joy-axis-event|sdl2:joy-axis-event]]</td>
2044    <td>[[https://wiki.libsdl.org/SDL_JoyAxisEvent|SDL_JoyAxisEvent]]</td>
2045    <td>{{'joy-axis-motion}}</td>
2046  </tr>
2047  <tr>
2048    <td>[[#sdl2joy-ball-event|sdl2:joy-ball-event]]</td>
2049    <td>[[https://wiki.libsdl.org/SDL_JoyBallEvent|SDL_JoyBallEvent]]</td>
2050    <td>{{'joy-ball-motion}}</td>
2051  </tr>
2052  <tr>
2053    <td>[[#sdl2joy-button-event|sdl2:joy-button-event]]</td>
2054    <td>[[https://wiki.libsdl.org/SDL_JoyButtonEvent|SDL_JoyButtonEvent]]</td>
2055    <td>{{'joy-button-down}}<br>
2056        {{'joy-button-up}}</td>
2057  </tr>
2058  <tr>
2059    <td>[[#sdl2joy-device-event|sdl2:joy-device-event]]</td>
2060    <td>[[https://wiki.libsdl.org/SDL_JoyDeviceEvent|SDL_JoyDeviceEvent]]</td>
2061    <td>{{'joy-device-added}}<br>
2062        {{'joy-device-removed}}</td>
2063  </tr>
2064  <tr>
2065    <td>[[#sdl2joy-hat-event|sdl2:joy-hat-event]]</td>
2066    <td>[[https://wiki.libsdl.org/SDL_JoyHatEvent|SDL_JoyHatEvent]]</td>
2067    <td>{{'joy-hat-motion}}</td>
2068  </tr>
2069  <tr>
2070    <td>[[#sdl2keyboard-event|sdl2:keyboard-event]]</td>
2071    <td>[[https://wiki.libsdl.org/SDL_KeyboardEvent|SDL_KeyboardEvent]]</td>
2072    <td>{{'key-down}}<br>
2073        {{'key-up}}</td>
2074  </tr>
2075  <tr>
2076    <td>[[#sdl2mouse-button-event|sdl2:mouse-button-event]]</td>
2077    <td>[[https://wiki.libsdl.org/SDL_MouseButtonEvent|SDL_MouseButtonEvent]]</td>
2078    <td>{{'mouse-button-down}}<br>
2079        {{'mouse-button-up}}</td>
2080  </tr>
2081  <tr>
2082    <td>[[#sdl2mouse-motion-event|sdl2:mouse-motion-event]]</td>
2083    <td>[[https://wiki.libsdl.org/SDL_MouseMotionEvent|SDL_MouseMotionEvent]]</td>
2084    <td>{{'mouse-motion}}</td>
2085  </tr>
2086  <tr>
2087    <td>[[#sdl2mouse-wheel-event|sdl2:mouse-wheel-event]]</td>
2088    <td>[[https://wiki.libsdl.org/SDL_MouseWheelEvent|SDL_MouseWheelEvent]]</td>
2089    <td>{{'mouse-wheel}}</td>
2090  </tr>
2091  <tr>
2092    <td>[[#sdl2multi-gesture-event|sdl2:multi-gesture-event]]</td>
2093    <td>[[https://wiki.libsdl.org/SDL_MultiGestureEvent|SDL_MultiGestureEvent]]</td>
2094    <td>{{'multi-gesture}}</td>
2095  </tr>
2096  <tr>
2097    <td>[[#sdl2quit-event|sdl2:quit-event]]</td>
2098    <td>[[https://wiki.libsdl.org/SDL_QuitEvent|SDL_QuitEvent]]</td>
2099    <td>{{'quit}}</td>
2100  </tr>
2101  <tr>
2102    <td>[[#sdl2sys-wm-event|sdl2:sys-wm-event]]</td>
2103    <td>[[https://wiki.libsdl.org/SDL_SysWMEvent|SDL_SysWMEvent]]</td>
2104    <td>{{'sys-wm}}</td>
2105  </tr>
2106  <tr>
2107    <td>[[#sdl2text-editing-event|sdl2:text-editing-event]]</td>
2108    <td>[[https://wiki.libsdl.org/SDL_TextEditingEvent|SDL_TextEditingEvent]]</td>
2109    <td>{{'text-editing}}</td>
2110  </tr>
2111  <tr>
2112    <td>[[#sdl2text-input-event|sdl2:text-input-event]]</td>
2113    <td>[[https://wiki.libsdl.org/SDL_TextInputEvent|SDL_TextInputEvent]]</td>
2114    <td>{{'text-input}}</td>
2115  </tr>
2116  <tr>
2117    <td>[[#sdl2touch-finger-event|sdl2:touch-finger-event]]</td>
2118    <td>[[https://wiki.libsdl.org/SDL_TouchFingerEvent|SDL_TouchFingerEvent]]</td>
2119    <td>{{'finger-down}}<br>
2120        {{'finger-up}}<br>
2121        {{'finger-motion}}</td>
2122  </tr>
2123  <tr>
2124    <td>[[#sdl2user-event|sdl2:user-event]]</td>
2125    <td>[[https://wiki.libsdl.org/SDL_UserEvent|SDL_UserEvent]]</td>
2126    <td>(Call {{register-events!}} to register your own user event type symbols.)</td>
2127  </tr>
2128  <tr>
2129    <td>[[#sdl2window-event|sdl2:window-event]]</td>
2130    <td>[[https://wiki.libsdl.org/SDL_WindowEvent|SDL_WindowEvent]]</td>
2131    <td>{{'window}}</td>
2132  </tr>
2133</table>
2134
2135
2136
2137<procedure>(event? obj) → boolean</procedure>
2138
2139Returns #t if {{obj}} is any variant of sdl2:event.
2140
2141
2142<procedure>(make-event #!optional type) → sdl2:event</procedure>
2143<procedure>(make-event* #!optional type) → sdl2:event</procedure>
2144
2145Allocate and set the type of a new sdl2:event.
2146
2147{{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.
2148
2149* {{make-event}} returns a managed sdl2:event.
2150* {{make-event*}} returns an unmanaged sdl2:event, which must be freed with {{free-event!}} when you are done with it.
2151
2152
2153<procedure>(free-event! event)</procedure>
2154
2155Free the memory of the sdl2:event's underlying struct. You can call
2156this procedure with any variant of sdl2:event. {{event}}'s pointer
2157will be set to null (see {{struct-null?}}). It is safe to call this
2158procedure with managed or unmanaged sdl2:events. It is safe (but has
2159no effect) to free a struct record multiple times.
2160
2161
2162<procedure>(event-type event) → symbol</procedure>
2163<procedure>(event-type-raw event) → fixnum</procedure>
2164<setter>(set! (event-type event) val)</setter>
2165<setter>(event-type-set! event val)</setter>
2166
2167Get or set the sdl2:event's "type" field.
2168You can use these procedures with any variant of sdl2:event.
2169Setting this will change what variant of sdl2:event it is.
2170E.g. if you set it to {{'key-down}}, the event will become an sdl2:keyboard-event.
2171
2172* {{event-type}} returns an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbol]].
2173* {{event-type-raw}} returns an integer.
2174* The setters accept either a symbol or an integer.
2175
2176
2177<procedure>(event-timestamp event) → fixnum</procedure>
2178<setter>(set! (event-timestamp event) val)</setter>
2179<setter>(event-timestamp-set! event val)</setter>
2180
2181Get 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.
2182You can use these procedures with any variant of sdl2:event.
2183
2184
2185
2186===== sdl2:controller-axis-event
2187
2188sdl2:controller-axis-event is a variant of sdl2:event that wraps a pointer to an
2189[[https://wiki.libsdl.org/SDL_ControllerAxisEvent|SDL_ControllerAxisEvent]].
2190
2191This event variant occurs when an axis on a controller moves.
2192There may be more than one controller, and each controller may have more than one axis.
2193You can distinguish them using the {{which}} and {{axis}} fields.
2194
2195sdl2:controller-axis-event has the following event type symbols:
2196
2197; {{'controller-axis-motion}} : An axis on a controller moved.
2198
2199
2200<procedure>(controller-axis-event? obj) → boolean</procedure>
2201
2202Returns #t if {{obj}} is an sdl2:controller-axis-event.
2203
2204
2205<procedure>(controller-axis-event-which event) → fixnum</procedure>
2206<setter>(set! (controller-axis-event-which event) val)</setter>
2207<setter>(controller-axis-event-which-set! event val)</setter>
2208
2209Get or set the event's "which" field, as an integer indicating the device index of the controller (joystick) that the event is related to.
2210
2211
2212<procedure>(controller-axis-event-axis event) → fixnum</procedure>
2213<setter>(set! (controller-axis-event-axis event) val)</setter>
2214<setter>(controller-axis-event-axis-set! event val)</setter>
2215
2216Get or set the event's "axis" field, as an integer indicating the axis that the event is related to.
2217E.g. 0 indicates the first axis on the controller.
2218
2219
2220<procedure>(controller-axis-event-value event) → fixnum</procedure>
2221<setter>(set! (controller-axis-event-value event) val)</setter>
2222<setter>(controller-axis-event-value-set! event val)</setter>
2223
2224Get or set the event's "value" field, as an integer in the range -32768 to 32767 (inclusive), indicating the new value of the axis.
2225
2226
2227
2228===== sdl2:controller-button-event
2229
2230sdl2:controller-button-event is a variant of sdl2:event that wraps a pointer to an
2231[[https://wiki.libsdl.org/SDL_ControllerButtonEvent|SDL_ControllerButtonEvent]].
2232
2233This event variant occurs when a button on a controller is pressed or released.
2234There may be more than one controller, and each controller may have more than one button.
2235You can distinguish them using the {{which}} and {{button}} fields.
2236
2237sdl2:controller-button-event has the following event type symbols:
2238
2239; {{'controller-button-down}} : A button on a controller was pressed.
2240; {{'controller-button-up}} : A button on a controller was released.
2241
2242<procedure>(controller-button-event? obj) → boolean</procedure>
2243
2244Returns #t if {{obj}} is an sdl2:controller-button-event.
2245
2246
2247<procedure>(controller-button-event-which event) → fixnum</procedure>
2248<setter>(set! (controller-button-event-which event) val)</setter>
2249<setter>(controller-button-event-which-set! event val)</setter>
2250
2251Get or set the event's "which" field, as an integer indicating the device index of the controller (joystick) that the event is related to.
2252
2253
2254<procedure>(controller-button-event-button event) → fixnum</procedure>
2255<setter>(set! (controller-button-event-button event) val)</setter>
2256<setter>(controller-button-event-button-set! event val)</setter>
2257
2258Get or set the event's "button" field, as an integer indicating the button that the event is related to.
2259E.g. 0 indicates the first button on the controller.
2260
2261
2262<procedure>(controller-button-event-state event) → boolean</procedure>
2263<setter>(set! (controller-button-event-state event) val)</setter>
2264<setter>(controller-button-event-state-set! event val)</setter>
2265
2266Get or set the event's "state" field, as a boolean indicating whether the button was pressed (#t) or released (#f).
2267You can also find out by checking the event type: {{'controller-button-down}} for pressed, or {{'controller-button-up}} for released.
2268
2269
2270
2271===== sdl2:controller-device-event
2272
2273sdl2:controller-device-event is a variant of sdl2:event that wraps a pointer to an
2274[[https://wiki.libsdl.org/SDL_ControllerDeviceEvent|SDL_ControllerDeviceEvent]].
2275
2276This event variant occurs when a controller is added, removed, or remapped.
2277There may be more than one controller.
2278You can distinguish them using the {{which}}.
2279
2280sdl2:controller-device-event has the following event type symbols:
2281
2282; {{'controller-device-added}} : A controller device was added.
2283; {{'controller-device-removed}} : A controller device was removed.
2284; {{'controller-device-remapped}} : A controller device was remapped.
2285
2286<procedure>(controller-device-event? obj) → boolean</procedure>
2287
2288Returns #t if {{obj}} is an sdl2:controller-device-event.
2289
2290
2291<procedure>(controller-device-event-which event) → fixnum</procedure>
2292<setter>(set! (controller-device-event-which event) val)</setter>
2293<setter>(controller-device-event-which-set! event val)</setter>
2294
2295Get or set the event's "which" field, as an integer indicating the device index of the controller (joystick) that the event is related to.
2296
2297
2298
2299===== sdl2:dollar-gesture-event
2300
2301sdl2:dollar-gesture-event is a variant of sdl2:event that wraps a pointer to an
2302[[https://wiki.libsdl.org/SDL_DollarGestureEvent|SDL_DollarGestureEvent]].
2303
2304This event variant occurs when a [[http://depts.washington.edu/aimgroup/proj/dollar/index.html|"$1 unistroke" gesture]] is performed or recorded.
2305
2306sdl2:dollar-gesture-event has the following event type symbols:
2307
2308; {{'dollar-gesture}} : A dollar gesture was performed.
2309; {{'dollar-record}} : A dollar gesture was recorded.
2310
2311
2312<procedure>(dollar-gesture-event? obj) → boolean</procedure>
2313
2314Returns #t if {{obj}} is an sdl2:dollar-gesture-event.
2315
2316
2317<procedure>(dollar-gesture-event-touch-id event) → fixnum</procedure>
2318<setter>(set! (dollar-gesture-event-touch-id event) val)</setter>
2319<setter>(dollar-gesture-event-touch-id-set! event val)</setter>
2320
2321Get or set the event's "touch-id" field, as an integer indicating the ID number of the touch device this event is related to.
2322
2323
2324<procedure>(dollar-gesture-event-gesture-id event) → fixnum</procedure>
2325<setter>(set! (dollar-gesture-event-gesture-id event) val)</setter>
2326<setter>(dollar-gesture-event-gesture-id-set! event val)</setter>
2327
2328Get or set the event's "gesture-id" field, as an integer indicating the ID number of the closest gesture to the performed stroke.
2329
2330
2331<procedure>(dollar-gesture-event-num-fingers event) → fixnum</procedure>
2332<setter>(set! (dollar-gesture-event-num-fingers event) val)</setter>
2333<setter>(dollar-gesture-event-num-fingers-set! event val)</setter>
2334
2335Get or set the event's "num-fingers" field, as an integer indicating the number of fingers used to draw the stroke.
2336
2337
2338<procedure>(dollar-gesture-event-error event) → float</procedure>
2339<setter>(set! (dollar-gesture-event-error event) val)</setter>
2340<setter>(dollar-gesture-event-error-set! event val)</setter>
2341
2342Get 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.
2343
2344
2345<procedure>(dollar-gesture-event-x event) → float</procedure>
2346<setter>(set! (dollar-gesture-event-x event) val)</setter>
2347<setter>(dollar-gesture-event-x-set! event val)</setter>
2348
2349Get 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.
2350
2351
2352<procedure>(dollar-gesture-event-y event) → float</procedure>
2353<setter>(set! (dollar-gesture-event-y event) val)</setter>
2354<setter>(dollar-gesture-event-y-set! event val)</setter>
2355
2356Get 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.
2357
2358
2359
2360===== sdl2:drop-event
2361
2362sdl2:drop-event is a variant of sdl2:event that wraps a pointer to an
2363[[https://wiki.libsdl.org/SDL_DropEvent|SDL_DropEvent]].
2364
2365This event variant occurs when the user requests that the program open a file,
2366e.g. by dragging and dropping a file icon onto the program.
2367
2368sdl2:drop-event has the following event type symbols:
2369
2370; {{'drop-file}} : The user requested that a file be opened.
2371
2372
2373<procedure>(drop-event? obj) → boolean</procedure>
2374
2375Returns #t if {{obj}} is an sdl2:drop-event.
2376
2377
2378<procedure>(drop-event-file event) → string</procedure>
2379<setter>(set! (drop-event-file event) val)</setter>
2380<setter>(drop-event-file-set! event val)</setter>
2381
2382Get or set the event's "file" field, as a string indicating the path to a file that the user requested to be opened.
2383
2384
2385
2386===== sdl2:joy-axis-event
2387
2388sdl2:joy-axis-event is a variant of sdl2:event that wraps a pointer to an
2389[[https://wiki.libsdl.org/SDL_JoyAxisEvent|SDL_JoyAxisEvent]].
2390
2391This event variant occurs when an axis on a joystick moves.
2392There may be more than one joystick, and each joystick may have more than one axis.
2393You can distinguish them using the {{which}} and {{axis}} fields.
2394
2395sdl2:joy-axis-event has the following event type symbols:
2396
2397; {{'joy-axis-motion}} : An axis on a joystick moved.
2398
2399
2400<procedure>(joy-axis-event? obj) → boolean</procedure>
2401
2402Returns #t if {{obj}} is an sdl2:joy-axis-event.
2403
2404
2405<procedure>(joy-axis-event-which event) → fixnum</procedure>
2406<setter>(set! (joy-axis-event-which event) val)</setter>
2407<setter>(joy-axis-event-which-set! event val)</setter>
2408
2409Get or set the event's "which" field, as an integer indicating the device index of the joystick that the event is related to.
2410
2411
2412<procedure>(joy-axis-event-axis event) → fixnum</procedure>
2413<setter>(set! (joy-axis-event-axis event) val)</setter>
2414<setter>(joy-axis-event-axis-set! event val)</setter>
2415
2416Get or set the event's "axis" field, as an integer indicating the axis that the event is related to.
2417E.g. 0 indicates the first axis on the joystick.
2418
2419
2420<procedure>(joy-axis-event-value event) → fixnum</procedure>
2421<setter>(set! (joy-axis-event-value event) val)</setter>
2422<setter>(joy-axis-event-value-set! event val)</setter>
2423
2424Get or set the event's "value" field, as an integer in the range -32768 to 32767 (inclusive), indicating the new value of the axis.
2425
2426
2427
2428===== sdl2:joy-ball-event
2429
2430sdl2:joy-ball-event is a variant of sdl2:event that wraps a pointer to an
2431[[https://wiki.libsdl.org/SDL_JoyBallEvent|SDL_JoyBallEvent]].
2432
2433This event variant occurs when a trackball on a joystick moves.
2434There may be more than one joystick, and each joystick may have more than one trackball.
2435You can distinguish them using the {{which}} and {{ball}} fields.
2436
2437sdl2:joy-ball-event has the following event type symbols:
2438
2439; {{'joy-ball-motion}} : A trackball on a joystick moved.
2440
2441
2442<procedure>(joy-ball-event? obj) → boolean</procedure>
2443
2444Returns #t if {{obj}} is an sdl2:joy-ball-event.
2445
2446
2447<procedure>(joy-ball-event-which event) → fixnum</procedure>
2448<setter>(set! (joy-ball-event-which event) val)</setter>
2449<setter>(joy-ball-event-which-set! event val)</setter>
2450
2451Get or set the event's "which" field, as an integer indicating the device index of the joystick that the event is related to.
2452
2453
2454<procedure>(joy-ball-event-ball event) → fixnum</procedure>
2455<setter>(set! (joy-ball-event-ball event) val)</setter>
2456<setter>(joy-ball-event-ball-set! event val)</setter>
2457
2458Get 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.
2459
2460
2461<procedure>(joy-ball-event-xrel event) → fixnum</procedure>
2462<setter>(set! (joy-ball-event-xrel event) val)</setter>
2463<setter>(joy-ball-event-xrel-set! event val)</setter>
2464
2465Get 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.
2466
2467
2468<procedure>(joy-ball-event-yrel event) → fixnum</procedure>
2469<setter>(set! (joy-ball-event-yrel event) val)</setter>
2470<setter>(joy-ball-event-yrel-set! event val)</setter>
2471
2472Get 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.
2473
2474
2475
2476===== sdl2:joy-button-event
2477
2478sdl2:joy-button-event is a variant of sdl2:event that wraps a pointer to an
2479[[https://wiki.libsdl.org/SDL_JoyButtonEvent|SDL_JoyButtonEvent]].
2480
2481This event variant occurs when a button on a joystick is pressed or released.
2482There may be more than one joystick, and each joystick may have more than one button.
2483You can distinguish them using the {{which}} and {{button}} fields.
2484
2485sdl2:joy-button-event has the following event type symbols:
2486
2487; {{'joy-button-down}} : A button on a joystick was pressed.
2488; {{'joy-button-up}} : A button on a joystick was released.
2489
2490
2491<procedure>(joy-button-event? obj) → boolean</procedure>
2492
2493Returns #t if {{obj}} is an sdl2:joy-button-event.
2494
2495
2496<procedure>(joy-button-event-which event) → fixnum</procedure>
2497<setter>(set! (joy-button-event-which event) val)</setter>
2498<setter>(joy-button-event-which-set! event val)</setter>
2499
2500Get or set the event's "which" field, as an integer indicating the device index of the joystick that the event is related to.
2501
2502
2503<procedure>(joy-button-event-button event) → fixnum</procedure>
2504<setter>(set! (joy-button-event-button event) val)</setter>
2505<setter>(joy-button-event-button-set! event val)</setter>
2506
2507Get or set the event's "button" field, as an integer indicating the button that the event is related to.
2508E.g. 0 indicates the first button on the joystick.
2509
2510
2511<procedure>(joy-button-event-state event) → boolean</procedure>
2512<setter>(set! (joy-button-event-state event) val)</setter>
2513<setter>(joy-button-event-state-set! event val)</setter>
2514
2515Get or set the value of the event's "state" field, as a boolean indicating whether the button was pressed (#t) or released (#f).
2516You can also find out by checking the event type: {{'joy-button-down}} for pressed, or {{'joy-button-up}} for released.
2517
2518
2519
2520===== sdl2:joy-device-event
2521
2522sdl2:joy-device-event is a variant of sdl2:event that wraps a pointer to an
2523[[https://wiki.libsdl.org/SDL_JoyDeviceEvent|SDL_JoyDeviceEvent]].
2524
2525This event variant occurs when a joystick device is added or removed.
2526There may be more than one joystick.
2527You can distinguish them using the {{which}} field.
2528
2529sdl2:joy-device-event has the following event type symbols:
2530
2531; {{'joy-device-added}} : A joystick device was added.
2532; {{'joy-device-removed}} : A joystick device was removed.
2533
2534
2535<procedure>(joy-device-event? obj) → boolean</procedure>
2536
2537Returns #t if {{obj}} is an sdl2:joy-device-event.
2538
2539
2540<procedure>(joy-device-event-which event) → fixnum</procedure>
2541<setter>(set! (joy-device-event-which event) val)</setter>
2542<setter>(joy-device-event-which-set! event val)</setter>
2543
2544Get or set the event's "which" field, as an integer indicating the device index of the joystick that the event is related to.
2545
2546
2547
2548===== sdl2:joy-hat-event
2549
2550sdl2:joy-hat-event is a variant of sdl2:event that wraps a pointer to an
2551[[https://wiki.libsdl.org/SDL_JoyHatEvent|SDL_JoyHatEvent]].
2552
2553This event variant occurs when an 8-directional hat switch on a joystick moves.
2554There may be more than one joystick, and each joystick may have more than one hat switch.
2555You can distinguish them using the {{which}} and {{hat}} fields.
2556
2557sdl2:joy-hat-event has the following event type symbols:
2558
2559; {{'joy-hat-motion}} : A hat switch on a joystick moved.
2560
2561
2562<procedure>(joy-hat-event? obj) → boolean</procedure>
2563
2564Returns #t if {{obj}} is an sdl2:joy-hat-event.
2565
2566
2567<procedure>(joy-hat-event-which event) → fixnum</procedure>
2568<setter>(set! (joy-hat-event-which event) val)</setter>
2569<setter>(joy-hat-event-which-set! event val)</setter>
2570
2571Get or set the event's "which" field, as an integer indicating the device index of the joystick that the event is related to.
2572
2573
2574<procedure>(joy-hat-event-hat event) → fixnum</procedure>
2575<setter>(set! (joy-hat-event-hat event) val)</setter>
2576<setter>(joy-hat-event-hat-set! event val)</setter>
2577
2578Get or set the event's "hat" field, as an integer indicating the hat switch that the event is related to.
2579E.g. 0 indicates the first hat switch on the joystick.
2580
2581
2582<procedure>(joy-hat-event-value event) → symbol</procedure>
2583<procedure>(joy-hat-event-value-raw event) → fixnum</procedure>
2584<setter>(set! (joy-hat-event-value event) val)</setter>
2585<setter>(joy-hat-event-value-set! event val)</setter>
2586
2587Get or set the event's "value" field, indicating the new position of the hat switch.
2588
2589* {{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]].
2590* {{joy-hat-event-value-raw}} returns an integer.
2591* The setters accept either a symbol or an integer.
2592
2593
2594===== sdl2:keyboard-event
2595
2596sdl2:keyboard-event is a variant of sdl2:event that wraps a pointer to an
2597[[https://wiki.libsdl.org/SDL_KeyboardEvent|SDL_KeyboardEvent]].
2598
2599This event variant occurs when a keyboard key is pressed or released.
2600
2601sdl2:keyboard-event has the following event type symbols:
2602
2603; {{'key-down}} : A keyboard key was pressed.
2604; {{'key-up}} : A keyboard key was released.
2605
2606
2607<procedure>(keyboard-event? obj) → boolean</procedure>
2608
2609Returns #t if {{obj}} is an sdl2:keyboard-event.
2610
2611
2612<procedure>(keyboard-event-window-id event) → fixnum</procedure>
2613<setter>(set! (keyboard-event-window-id event) val)</setter>
2614<setter>(keyboard-event-window-id-set! event val)</setter>
2615
2616Get 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.
2617
2618
2619<procedure>(keyboard-event-state event) → boolean</procedure>
2620<setter>(set! (keyboard-event-state event) val)</setter>
2621<setter>(keyboard-event-state-set! event val)</setter>
2622
2623Get or set the event's "state" field, as a boolean indicating whether the key was pressed (#t) or released (#f).
2624You can also find out by checking the event type: {{'key-down}} for pressed, or {{'key-up}} for released.
2625
2626
2627<procedure>(keyboard-event-repeat event) → fixnum</procedure>
2628<setter>(set! (keyboard-event-repeat event) val)</setter>
2629<setter>(keyboard-event-repeat-set! event val)</setter>
2630
2631Get or set the event's "repeat" field, as a integer.
2632Non-zero indicates that this is a key repeat, caused by the user pressing and holding the key for some time.
2633Zero indicates this is not a key repeat.
2634
2635
2636<procedure>(keyboard-event-keysym event) → sdl2:keysym</procedure>
2637<setter>(set! (keyboard-event-keysym event) val)</setter>
2638<setter>(keyboard-event-keysym-set! event val)</setter>
2639
2640Get or set the event's "keysym" field, as an sdl2:keysym indicating the key that was pressed or released.
2641The getter returns a copy of the sdl2:keysym stored in the event.
2642Modifying the returned sdl2:keysym will ''not'' modify the event, but setting this field to a sdl2:keysym ''will'' modify the event.
2643
2644Instead of using this procedure, it is more efficient and convenient to directly access the fields of the event's sdl2:keysym, using these procedures:
2645
2646* {{keyboard-event-scancode}}
2647* {{keyboard-event-sym}}
2648* {{keyboard-event-mod}}
2649
2650
2651<procedure>(keyboard-event-scancode event) → symbol</procedure>
2652<procedure>(keyboard-event-scancode-raw event) → fixnum</procedure>
2653<setter>(set! (keyboard-event-scancode event) val)</setter>
2654<setter>(keyboard-event-scancode-set! event val)</setter>
2655
2656Get or set the "scancode" field of the event's "keysym" field, indicating the physical key that was pressed or released.
2657Setting this will modify the event.
2658
2659* {{keyboard-event-scancode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]].
2660* {{keyboard-event-scancode-raw}} returns an integer.
2661* The setters accept either a symbol or an integer.
2662
2663
2664<procedure>(keyboard-event-sym event) → symbol</procedure>
2665<procedure>(keyboard-event-sym-raw event) → fixnum</procedure>
2666<setter>(set! (keyboard-event-sym event) val)</setter>
2667<setter>(keyboard-event-sym-set! event val)</setter>
2668
2669Get or set the "sym" field of the event's "keysym" field, indicating the logical key that was pressed or released.
2670Setting this will modify the event.
2671
2672* {{keyboard-event-sym}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]]
2673* {{keyboard-event-sym-raw}} returns an integer.
2674* The setters accept either a symbol or an integer.
2675
2676
2677<procedure>(keyboard-event-mod event) → list of symbols</procedure>
2678<procedure>(keyboard-event-mod-raw event) → fixnum</procedure>
2679<setter>(set! (keyboard-event-mod event) val)</setter>
2680<setter>(keyboard-event-mod-set! event val)</setter>
2681
2682Get 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.
2683Setting this will modify the event.
2684
2685* {{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]].
2686* {{keyboard-event-mod-raw}} returns an integer.
2687* The setters accept either a list of symbols or an integer.
2688
2689
2690
2691===== sdl2:mouse-button-event
2692
2693sdl2:mouse-button-event is a variant of sdl2:event that wraps a pointer to an
2694[[https://wiki.libsdl.org/SDL_MouseButtonEvent|SDL_MouseButtonEvent]].
2695
2696This event variant occurs when a mouse button was pressed or released.
2697
2698sdl2:mouse-button-event has the following event type symbols:
2699
2700; {{'mouse-button-down}} : A mouse button was pressed.
2701; {{'mouse-button-up}} : A mouse button was released.
2702
2703
2704<procedure>(mouse-button-event? obj) → boolean</procedure>
2705
2706Returns #t if {{obj}} is an sdl2:mouse-button-event.
2707
2708
2709<procedure>(mouse-button-event-window-id event) → fixnum</procedure>
2710<setter>(set! (mouse-button-event-window-id event) val)</setter>
2711<setter>(mouse-button-event-window-id-set! event val)</setter>
2712
2713Get 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.
2714
2715
2716<procedure>(mouse-button-event-which event) → fixnum</procedure>
2717<setter>(set! (mouse-button-event-which event) val)</setter>
2718<setter>(mouse-button-event-which-set! event val)</setter>
2719
2720Get or set the event's "which" field, as an integer indicating the mouse instance ID.
2721
2722
2723<procedure>(mouse-button-event-button event) → symbol</procedure>
2724<procedure>(mouse-button-event-button-raw event) → fixnum</procedure>
2725<setter>(set! (mouse-button-event-button event) val)</setter>
2726<setter>(mouse-button-event-button-set! event val)</setter>
2727
2728Get or set the event's "button" field, indicating the button that the event is related to.
2729
2730* {{mouse-button-event-button}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#mouse-buttons|mouse button symbol]]:
2731** {{'left}}
2732** {{'middle}}
2733** {{'right}}
2734** {{'x1}}
2735** {{'x2}}
2736* {{mouse-button-event-button-raw}} returns an integer.
2737* The setters accept either a symbol or an integer.
2738
2739
2740<procedure>(mouse-button-event-state event) → boolean</procedure>
2741<setter>(set! (mouse-button-event-state event) val)</setter>
2742<setter>(mouse-button-event-state-set! event val)</setter>
2743
2744Get or set the event's "state" field, as a boolean indicating whether the button was pressed (#t) or released (#f).
2745You can also find out by checking the event type: {{'mouse-button-down}} for pressed, or {{'mouse-button-up}} for released.
2746
2747
2748<procedure>(mouse-button-event-x event) → fixnum</procedure>
2749<setter>(set! (mouse-button-event-x event) val)</setter>
2750<setter>(mouse-button-event-x-set! event val)</setter>
2751
2752Get 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.
2753
2754
2755<procedure>(mouse-button-event-y event) → fixnum</procedure>
2756<setter>(set! (mouse-button-event-y event) val)</setter>
2757<setter>(mouse-button-event-y-set! event val)</setter>
2758
2759Get 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.
2760
2761
2762
2763===== sdl2:mouse-motion-event
2764
2765sdl2:mouse-motion-event is a variant of sdl2:event that wraps a pointer to an
2766[[https://wiki.libsdl.org/SDL_MouseMotionEvent|SDL_MouseMotionEvent]].
2767
2768This event variant occurs when the mouse cursor moves.
2769
2770sdl2:mouse-motion-event has the following event type symbols:
2771
2772; {{'mouse-motion}} : The mouse cursor moved.
2773
2774
2775<procedure>(mouse-motion-event? obj) → boolean</procedure>
2776
2777Returns #t if {{obj}} is an sdl2:mouse-motion-event.
2778
2779
2780<procedure>(mouse-motion-event-window-id event) → fixnum</procedure>
2781<setter>(set! (mouse-motion-event-window-id event) val)</setter>
2782<setter>(mouse-motion-event-window-id-set! event val)</setter>
2783
2784Get 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.
2785
2786
2787<procedure>(mouse-motion-event-which event) → fixnum</procedure>
2788<setter>(set! (mouse-motion-event-which event) val)</setter>
2789<setter>(mouse-motion-event-which-set! event val)</setter>
2790
2791Get or set the event's "which" field, as an integer indicating the mouse instance ID.
2792
2793
2794<procedure>(mouse-motion-event-state event) → list of symbols</procedure>
2795<procedure>(mouse-motion-event-state-raw event) → fixnum</procedure>
2796<setter>(set! (mouse-motion-event-state event) val)</setter>
2797<setter>(mouse-motion-event-state-set! event val)</setter>
2798
2799Get or set the event's "state" field, indicating the mouse buttons that were being pressed at the time this event occurred.
2800
2801* {{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]]:
2802** {{'left}}
2803** {{'middle}}
2804** {{'right}}
2805** {{'x1}}
2806** {{'x2}}
2807* {{mouse-motion-event-state-raw}} returns an integer.
2808* The setters accept either a list of zero or more symbols, or an integer.
2809
2810
2811<procedure>(mouse-motion-event-x event) → fixnum</procedure>
2812<setter>(set! (mouse-motion-event-x event) val)</setter>
2813<setter>(mouse-motion-event-x-set! event val)</setter>
2814
2815Get 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.
2816
2817
2818<procedure>(mouse-motion-event-y event) → fixnum</procedure>
2819<setter>(set! (mouse-motion-event-y event) val)</setter>
2820<setter>(mouse-motion-event-y-set! event val)</setter>
2821
2822Get 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.
2823
2824
2825<procedure>(mouse-motion-event-xrel event) → fixnum</procedure>
2826<setter>(set! (mouse-motion-event-xrel event) val)</setter>
2827<setter>(mouse-motion-event-xrel-set! event val)</setter>
2828
2829Get 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.
2830
2831
2832<procedure>(mouse-motion-event-yrel event) → fixnum</procedure>
2833<setter>(set! (mouse-motion-event-yrel event) val)</setter>
2834<setter>(mouse-motion-event-yrel-set! event val)</setter>
2835
2836Get 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.
2837
2838
2839
2840===== sdl2:mouse-wheel-event
2841
2842sdl2:mouse-wheel-event is a variant of sdl2:event that wraps a pointer to an
2843[[https://wiki.libsdl.org/SDL_MouseWheelEvent|SDL_MouseWheelEvent]].
2844
2845This event variant occurs when a mouse wheel moves.
2846
2847sdl2:mouse-wheel-event has the following event type symbols:
2848
2849; {{'mouse-wheel}} : A mouse wheel moved.
2850
2851
2852<procedure>(mouse-wheel-event? obj) → boolean</procedure>
2853
2854Returns #t if {{obj}} is an sdl2:mouse-wheel-event.
2855
2856
2857<procedure>(mouse-wheel-event-window-id event) → fixnum</procedure>
2858<setter>(set! (mouse-wheel-event-window-id event) val)</setter>
2859<setter>(mouse-wheel-event-window-id-set! event val)</setter>
2860
2861Get 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.
2862
2863
2864<procedure>(mouse-wheel-event-which event) → fixnum</procedure>
2865<setter>(set! (mouse-wheel-event-which event) val)</setter>
2866<setter>(mouse-wheel-event-which-set! event val)</setter>
2867
2868Get or set the event's "which" field, as an integer indicating the mouse instance ID.
2869
2870
2871<procedure>(mouse-wheel-event-x event) → fixnum</procedure>
2872<setter>(set! (mouse-wheel-event-x event) val)</setter>
2873<setter>(mouse-wheel-event-x-set! event val)</setter>
2874
2875Get or set the event's "x" field, as an integer (possibly negative) indicating the amount the wheel scrolled horizontally.
2876Positive numbers indicate scrolling to the right, negative numbers indicate scrolling to the left.
2877
2878
2879<procedure>(mouse-wheel-event-y event) → fixnum</procedure>
2880<setter>(set! (mouse-wheel-event-y event) val)</setter>
2881<setter>(mouse-wheel-event-y-set! event val)</setter>
2882
2883Get or set the event's "y" field, as an integer (possibly negative) indicating the amount the wheel scrolled vertically.
2884Positive numbers indicate scrolling away from the user, negative numbers indicate scrolling toward the user.
2885
2886
2887
2888===== sdl2:multi-gesture-event
2889
2890sdl2:multi-gesture-event is a variant of sdl2:event that wraps a pointer to an
2891[[https://wiki.libsdl.org/SDL_MultiGestureEvent|SDL_MultiGestureEvent]].
2892
2893This event variant occurs when a multi-finger gesture is performed on a touch device.
2894This is useful for recognizing common gestures that involve multiple fingers, e.g. pinching or rotating.
2895
2896sdl2:multi-gesture-event has the following event type symbols:
2897
2898; {{'multi-gesture}} : A multi-finger gesture was performed.
2899
2900
2901<procedure>(multi-gesture-event? obj) → boolean</procedure>
2902
2903Returns #t if {{obj}} is an sdl2:multi-gesture-event.
2904
2905
2906<procedure>(multi-gesture-event-touch-id event) → fixnum</procedure>
2907<setter>(set! (multi-gesture-event-touch-id event) val)</setter>
2908<setter>(multi-gesture-event-touch-id-set! event val)</setter>
2909
2910Get or set the event's "touch-id" field, as an integer indicating the ID number of the touch device this event is related to.
2911
2912
2913<procedure>(multi-gesture-event-dtheta event) → float</procedure>
2914<setter>(set! (multi-gesture-event-dtheta event) val)</setter>
2915<setter>(multi-gesture-event-dtheta-set! event val)</setter>
2916
2917Get or set the event's "dtheta" field, as a float indicating the amount that the fingers rotated during this motion.
2918
2919
2920<procedure>(multi-gesture-event-ddist event) → float</procedure>
2921<setter>(set! (multi-gesture-event-ddist event) val)</setter>
2922<setter>(multi-gesture-event-ddist-set! event val)</setter>
2923
2924Get or set the event's "ddist" field, as a float indicating the amount that the fingers pinched during this motion.
2925
2926
2927<procedure>(multi-gesture-event-x event) → float</procedure>
2928<setter>(set! (multi-gesture-event-x event) val)</setter>
2929<setter>(multi-gesture-event-x-set! event val)</setter>
2930
2931Get or set the event's "x" field, as a float indicating the normalized X coordinate of the center of the gesture.
2932
2933
2934<procedure>(multi-gesture-event-y event) → float</procedure>
2935<setter>(set! (multi-gesture-event-y event) val)</setter>
2936<setter>(multi-gesture-event-y-set! event val)</setter>
2937
2938Get or set the event's "y" field, as a float indicating the normalized Y coordinate of the center of the gesture.
2939
2940
2941<procedure>(multi-gesture-event-num-fingers event) → fixnum</procedure>
2942<setter>(set! (multi-gesture-event-num-fingers event) val)</setter>
2943<setter>(multi-gesture-event-num-fingers-set! event val)</setter>
2944
2945Get or set the event's "num-fingers" field, as an integer indicating the number of fingers used in the gesture.
2946
2947
2948
2949===== sdl2:quit-event
2950
2951sdl2:quit-event is a variant of sdl2:event that wraps a pointer to an
2952[[https://wiki.libsdl.org/SDL_QuitEvent|SDL_QuitEvent]].
2953
2954This event variant occurs when the user requests to quit the program.
2955There are [[https://wiki.libsdl.org/SDL_EventType#SDL_QUIT|various ways this might happen]], depending on the platform.
2956
2957sdl2:quit-event has the following event type symbols:
2958
2959; {{'quit}} : The user requested to quit the program.
2960
2961
2962<procedure>(quit-event? obj) → boolean</procedure>
2963
2964Returns #t if {{obj}} is an sdl2:quit-event.
2965
2966
2967
2968===== sdl2:sys-wm-event
2969
2970sdl2:sys-wm-event is a variant of sdl2:event that wraps a pointer to an
2971[[https://wiki.libsdl.org/SDL_SysWMEvent|SDL_SysWMEvent]].
2972
2973This event variant is for very advanced use cases. Most people can ignore it.
2974
2975sdl2:sys-wm-event has the following event type symbols:
2976
2977; {{'sys-wm}} : A platform-specific event occurred.
2978
2979
2980<procedure>(sys-wm-event? obj) → boolean</procedure>
2981
2982Returns #t if {{obj}} is an sdl2:sys-wm-event.
2983
2984
2985<procedure>(sys-wm-event-msg-raw event) → pointer</procedure>
2986<setter>(set! (sys-wm-event-msg-raw event) val)</setter>
2987<setter>(sys-wm-event-msg-raw-set! event val)</setter>
2988
2989Get 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.
2990This is for very advanced use cases. Most people can ignore it.
2991
2992
2993
2994===== sdl2:text-editing-event
2995
2996sdl2:text-editing-event is a variant of sdl2:event that wraps a pointer to an
2997[[https://wiki.libsdl.org/SDL_TextEditingEvent|SDL_TextEditingEvent]].
2998
2999This event occurs when a user is editing (composing) text, e.g. using an Input Method Editor (IME).
3000See the [[https://wiki.libsdl.org/Tutorials/TextInput|Text Input tutorial for SDL]].
3001
3002sdl2:text-editing-event has the following event type symbols:
3003
3004; {{'text-editing}} : The user editted some text being composed.
3005
3006
3007<procedure>(text-editing-event? obj) → boolean</procedure>
3008
3009Returns #t if {{obj}} is an sdl2:text-editing-event.
3010
3011
3012<procedure>(text-editing-event-window-id event) → fixnum</procedure>
3013<setter>(set! (text-editing-event-window-id event) val)</setter>
3014<setter>(text-editing-event-window-id-set! event val)</setter>
3015
3016Get 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.
3017
3018
3019<procedure>(text-editing-event-text event) → string</procedure>
3020<setter>(set! (text-editing-event-text event) val)</setter>
3021<setter>(text-editing-event-text-set! event val)</setter>
3022
3023Get 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.
3024
3025
3026<procedure>(text-editing-event-start event) → fixnum</procedure>
3027<setter>(set! (text-editing-event-start event) val)</setter>
3028<setter>(text-editing-event-start-set! event val)</setter>
3029
3030Get or set the event's "start" field, as an integer indicating the location to begin editing from.
3031
3032
3033<procedure>(text-editing-event-length event) → fixnum</procedure>
3034<setter>(set! (text-editing-event-length event) val)</setter>
3035<setter>(text-editing-event-length-set! event val)</setter>
3036
3037Get or set the event's "length" field, as an integer indicating the number of characters to edit from the start point.
3038
3039
3040
3041===== sdl2:text-input-event
3042
3043sdl2:text-input-event is a variant of sdl2:event that wraps a pointer to an
3044[[https://wiki.libsdl.org/SDL_TextInputEvent|SDL_TextInputEvent]].
3045
3046This event occurs when the users enters some text, possibly using an Input Metod Editor (IME).
3047See the [[https://wiki.libsdl.org/Tutorials/TextInput|Text Input tutorial for SDL]].
3048
3049sdl2:text-input-event has the following event type symbols:
3050
3051; {{'text-input}} : The use inputted some text.
3052
3053
3054<procedure>(text-input-event? obj) → boolean</procedure>
3055
3056Returns #t if {{obj}} is an sdl2:text-input-event.
3057
3058
3059<procedure>(text-input-event-window-id event) → fixnum</procedure>
3060<setter>(set! (text-input-event-window-id event) val)</setter>
3061<setter>(text-input-event-window-id-set! event val)</setter>
3062
3063Get 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.
3064
3065
3066<procedure>(text-input-event-text event) → string</procedure>
3067<setter>(set! (text-input-event-text event) val)</setter>
3068<setter>(text-input-event-text-set! event val)</setter>
3069
3070Get or set the event's {{text}} event, as a UTF8 string up to 32 bytes long (including the ending null byte), holding the text that was inputted.
3071
3072
3073
3074===== sdl2:touch-finger-event
3075
3076sdl2:touch-finger-event is a variant of sdl2:event that wraps a pointer to an
3077[[https://wiki.libsdl.org/SDL_TouchFingerEvent|SDL_TouchFingerEvent]].
3078
3079This event variant occurs when the user presses, lifts, or moves a finger (or stylus, etc.) on a supported touch device,
3080e.g. the touch screen of a mobile phone or tablet device, or certain laptop trackpads.
3081There may be more than one finger touching at the same time;
3082you can distinguish the fingers by the {{finger-id}} number.
3083
3084sdl2:touch-finger-event has the following event type symbols:
3085
3086; {{'finger-down}} : A finger started touching a touch device (i.e. was pressed down).
3087; {{'finger-up}} : A finger stopped touching a touch device (i.e. was lifted up).
3088; {{'finger-motion}} : A finger moved while touching a touch device.
3089
3090
3091<procedure>(touch-finger-event? obj) → boolean</procedure>
3092
3093Returns #t if {{obj}} is an sdl2:touch-finger-event.
3094
3095
3096<procedure>(touch-finger-event-touch-id event) → fixnum</procedure>
3097<setter>(set! (touch-finger-event-touch-id event) val)</setter>
3098<setter>(touch-finger-event-touch-id-set! event val)</setter>
3099
3100Get or set the event's "touch-id" field, as an integer indicating the ID number of the touch device this event is related to.
3101
3102
3103<procedure>(touch-finger-event-finger-id event) → fixnum</procedure>
3104<setter>(set! (touch-finger-event-finger-id event) val)</setter>
3105<setter>(touch-finger-event-finger-id-set! event val)</setter>
3106
3107Get or set the event's "finger-id" field, as an integer indicating the ID number of the finger this event is related to.
3108
3109
3110<procedure>(touch-finger-event-x event) → float</procedure>
3111<setter>(set! (touch-finger-event-x event) val)</setter>
3112<setter>(touch-finger-event-x-set! event val)</setter>
3113
3114Get 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.
3115
3116
3117<procedure>(touch-finger-event-y event) → float</procedure>
3118<setter>(set! (touch-finger-event-y event) val)</setter>
3119<setter>(touch-finger-event-y-set! event val)</setter>
3120
3121Get 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.
3122
3123
3124<procedure>(touch-finger-event-dx event) → float</procedure>
3125<setter>(set! (touch-finger-event-dx event) val)</setter>
3126<setter>(touch-finger-event-dx-set! event val)</setter>
3127
3128Get 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.
3129
3130
3131<procedure>(touch-finger-event-dy event) → float</procedure>
3132<setter>(set! (touch-finger-event-dy event) val)</setter>
3133<setter>(touch-finger-event-dy-set! event val)</setter>
3134
3135Get 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.
3136
3137
3138<procedure>(touch-finger-event-pressure event) → float</procedure>
3139<setter>(set! (touch-finger-event-pressure event) val)</setter>
3140<setter>(touch-finger-event-pressure-set! event val)</setter>
3141
3142Get or set the event's "pressure" field, as a float in the range 0.0 to 1.0 (inclusive), indicating the pressure being applied.
3143
3144
3145
3146===== sdl2:user-event
3147
3148sdl2:user-event is a variant of sdl2:event that wraps a pointer to an
3149[[https://wiki.libsdl.org/SDL_UserEvent|SDL_UserEvent]].
3150
3151This event variant does not occur normally.
3152Instead, you can make instances of this event variant and push them to the event queue using {{push-event!}}.
3153The meaning of this event variant is entirely up for you to decide.
3154For example, you can use it to create custom event types related to your gameplay.
3155
3156sdl2:user-event does not have any event type symbols by default.
3157Call {{register-events!}} to register your own custom event type symbols for sdl2:user-event.
3158
3159
3160<procedure>(user-event? obj) → boolean</procedure>
3161
3162Returns #t if {{obj}} is an sdl2:user-event.
3163
3164
3165<procedure>(user-event-window-id event) → fixnum</procedure>
3166<setter>(set! (user-event-window-id event) val)</setter>
3167<setter>(user-event-window-id-set! event val)</setter>
3168
3169Get or set the event's "window-id" field, as an integer indicating the ID number of the sdl2:window associated with this event.
3170
3171
3172<procedure>(user-event-code event) → fixnum</procedure>
3173<setter>(set! (user-event-code event) val)</setter>
3174<setter>(user-event-code-set! event val)</setter>
3175
3176Get or set the event's "code" field, as an integer in the range -32768 to 32767 (inclusive).
3177The meaning of this field is for you to decide.
3178
3179
3180<procedure>(user-event-data1-raw event) → pointer or #f</procedure>
3181<setter>(set! (user-event-data1-raw event) val)</setter>
3182<setter>(user-event-data1-rawset! event val)</setter>
3183
3184Get or set the event's "data1" field, as a raw pointer or #f.
3185The meaning of this field is for you to decide.
3186
3187If you want to store a pointer to a Scheme object here, be sure to
3188[[/manual/Unit lolevel#object-evict|evict the object]] first. Otherwise
3189the object's location in memory might change, rendering the pointer
3190invalid.
3191
3192
3193<procedure>(user-event-data2-raw event) → pointer or #f</procedure>
3194<setter>(set! (user-event-data2-raw event) val)</setter>
3195<setter>(user-event-data2-raw-set! event val)</setter>
3196
3197Get or set the event's "data2" field, as a raw pointer or #f.
3198The meaning of this field is for you to decide.
3199
3200If you want to store a pointer to a Scheme object here, be sure to
3201[[/manual/Unit lolevel#object-evict|evict the object]] first. Otherwise
3202the object's location in memory might change, rendering the pointer
3203invalid.
3204
3205
3206
3207===== sdl2:window-event
3208
3209sdl2:window-event is a variant of sdl2:event that wraps a pointer to an
3210[[https://wiki.libsdl.org/SDL_WindowEvent|SDL_WindowEvent]].
3211
3212This event variant occurs when various changes occur to a window,
3213e.g. when a window is moved, resized, minimized, closed, etc.
3214
3215sdl2:window-event has the following event type symbols:
3216
3217; {{'window}} : A window-related event occurred.
3218
3219
3220<procedure>(window-event? obj) → boolean</procedure>
3221
3222Returns #t if {{obj}} is an sdl2:window-event.
3223
3224
3225<procedure>(window-event-window-id event) → fixnum</procedure>
3226<setter>(set! (window-event-window-id event) val)</setter>
3227<setter>(window-event-window-id-set! event val)</setter>
3228
3229Get or set the event's "window-id" field, as an integer indicating the ID of the sdl2:window that the event is related to.
3230
3231
3232<procedure>(window-event-event event) → symbol</procedure>
3233<procedure>(window-event-event-raw event) → fixnum</procedure>
3234<setter>(set! (window-event-event event) val)</setter>
3235<setter>(window-event-event-set! event val)</setter>
3236
3237Get or set the event's "event" field, indicating what happened to the window.
3238
3239* {{window-event-event}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#window-event-types|window event type symbol]].
3240* {{window-event-event-raw}} returns an integer.
3241* The setters accept either a symbol or an integer.
3242
3243
3244<procedure>(window-event-data1 event) → fixnum</procedure>
3245<setter>(set! (window-event-data1 event) val)</setter>
3246<setter>(window-event-data1-set! event val)</setter>
3247
3248Get or set the sdl2:window-event's "data1" field, as an integer.
3249The meaning of this value depends on what kind of window event it was (see {{window-event-event}}).
3250E.g. if the window was resized, this will hold the new window width;
3251if the window was moved, this will hold the new x position.
3252
3253
3254<procedure>(window-event-data2 event) → fixnum</procedure>
3255<setter>(set! (window-event-data2 event) val)</setter>
3256<setter>(window-event-data2-set! event val)</setter>
3257
3258Get or set the sdl2:window-event's "data2" field, as an integer.
3259The meaning of this value depends on what kind of window event it was (see {{window-event-event}}).
3260E.g. if the window was resized, this will hold the new window height;
3261if the window was moved, this will hold the new y position.
3262
3263
3264
3265==== sdl2:finger
3266
3267sdl2:finger is a record type that wraps a pointer to an
3268[[https://wiki.libsdl.org/SDL_Finger|SDL_Finger]] struct.
3269
3270
3271<procedure>(finger? obj) → boolean</procedure>
3272
3273Returns #t if {{obj}} is an sdl2:finger.
3274
3275
3276<procedure>(finger-id finger) → fixnum</procedure>
3277
3278Get the sdl2:finger's "id" field, as an integer.
3279
3280
3281<procedure>(finger-x finger) → float</procedure>
3282
3283Get 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.
3284
3285
3286<procedure>(finger-y finger) → float</procedure>
3287
3288Get 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.
3289
3290
3291<procedure>(finger-pressure finger) → float</procedure>
3292
3293Get 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.
3294
3295
3296
3297==== sdl2:joystick
3298
3299sdl2:joystick is a record type that wraps a pointer to an
3300[[https://wiki.libsdl.org/SDL_Joystick|SDL_Joystick]] struct.
3301
3302
3303<procedure>(joystick? obj) → boolean</procedure>
3304
3305Returns #t if {{obj}} is an sdl2:joystick.
3306
3307
3308
3309==== sdl2:joystick-guid
3310
3311sdl2:joystick-guid is a record type that wraps a pointer to an
3312[[https://wiki.libsdl.org/SDL_JoystickGetGUID|SDL_JoystickGUID]]
3313struct.
3314
3315
3316<procedure>(joystick-guid? obj) → boolean</procedure>
3317
3318Returns #t if {{obj}} is an sdl2:joystick-guid.
3319
3320
3321<procedure>(free-joystick-guid! guid)</procedure>
3322
3323Free the memory of the sdl2:joystick-guid's underlying struct.
3324{{guid}}'s pointer will be set to null (see {{struct-null?}}). It is
3325safe to call this procedure with managed or unmanaged
3326sdl2:joystick-guids. It is safe (but has no effect) to free a struct
3327record multiple times.
3328
3329
3330
3331==== sdl2:keysym
3332
3333sdl2:keysym is a record type that wraps a pointer to an
3334[[https://wiki.libsdl.org/SDL_Keysym|SDL_Keysym]] struct.
3335
3336
3337<procedure>(keysym? obj) → boolean</procedure>
3338
3339Returns #t if {{obj}} is an sdl2:keysym.
3340
3341
3342<procedure>(make-keysym #!optional scancode sym mod) → sdl2:keysym</procedure>
3343<procedure>(make-keysym* #!optional scancode sym mod) → sdl2:keysym</procedure>
3344
3345Allocate and initialize a new sdl2:keysym.
3346
3347{{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.
3348
3349{{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.
3350
3351{{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.
3352
3353* {{make-keysym}} returns a managed sdl2:keysym.
3354* {{make-keysym*}} returns an unmanaged sdl2:keysym, which must be freed with {{free-keysym!}} when you are done with it.
3355
3356
3357<procedure>(free-keysym! keysym)</procedure>
3358
3359Free the memory of the sdl2:keysym's underlying struct. {{keysym}}'s
3360pointer will be set to null (see {{struct-null?}}). It is safe to call
3361this procedure with managed or unmanaged sdl2:keysyms. It is safe (but
3362has no effect) to free a struct record multiple times.
3363
3364
3365<procedure>(keysym-scancode keysym) → symbol</procedure>
3366<procedure>(keysym-scancode-raw keysym) → fixnum</procedure>
3367<setter>(set! (keysym-scancode keysym) val)</setter>
3368<setter>(keysym-scancode-set! keysym val)</setter>
3369
3370Get or set the sdl2:keysym's "scancode" field, indicating the physical key that this keysym describes.
3371
3372* {{keysym-scancode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]].
3373* {{keysym-scancode-raw}} returns an integer.
3374* The setters accept either a symbol or an integer.
3375
3376
3377<procedure>(keysym-sym keysym) → symbol</procedure>
3378<procedure>(keysym-sym-raw keysym) → fixnum</procedure>
3379<setter>(set! (keysym-sym keysym) val)</setter>
3380<setter>(keysym-sym-set! keysym val)</setter>
3381
3382Get or set the sdl2:keysym's "sym" field, indicating the logical key that this keysym describes.
3383
3384* {{keysym-sym}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]].
3385* {{keysym-sym-raw}} returns an integer.
3386* The setters accept either a symbol or an integer.
3387
3388
3389<procedure>(keysym-mod keysym) → list of symbols</procedure>
3390<procedure>(keysym-mod-raw keysym) → fixnum</procedure>
3391<setter>(set! (keysym-mod keysym) val)</setter>
3392<setter>(keysym-mod-set! keysym val)</setter>
3393
3394Get or set the sdl2:keysym's "mod" field, indicating the modifier keys that this keysym describes.
3395
3396* {{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]].
3397* {{keysym-mod-raw}} returns an integer.
3398* The setters accept either a list of zero or more symbols, or an integer.
3399
3400
3401
3402==== sdl2:palette
3403
3404sdl2:palette is a record type that wraps a pointer to an
3405[[https://wiki.libsdl.org/SDL_Palette|SDL_Palette]] struct.
3406
3407
3408<procedure>(palette? obj) → boolean</procedure>
3409
3410Returns #t if {{obj}} is an sdl2:palette.
3411
3412
3413<procedure>(make-palette #!optional ncolors) → sdl2:palette</procedure>
3414<procedure>(make-palette* #!optional ncolors) → sdl2:palette</procedure>
3415
3416Allocate and initialize a new sdl2:palette with the given number of colors.
3417See [[https://wiki.libsdl.org/SDL_AllocPalette|SDL_AllocPalette]].
3418
3419{{ncolors}} defaults to 256.
3420Common values are 2 (for a 1-bit surface), 16 (for a 4-bit surface), and 256 (for an 8-bit surface).
3421
3422'''NOTE:''' Usually you do not need to manually allocate a palette. A
3423palette will be created for you when you create a surface with a depth
3424of 8 or lower, and the palette will be automatically freed when the
3425surface is freed (unless the palette is still being used by other
3426surfaces).
3427
3428* {{make-palette}} returns a managed sdl2:palette.
3429* {{make-palette*}} returns an unmanaged sdl2:palette, which must be freed with {{free-palette!}} when you are done with it.
3430
3431
3432<procedure>(free-palette! palette)</procedure>
3433
3434Free the memory of the sdl2:palette's underlying struct. {{palette}}'s
3435pointer will be set to null (see {{struct-null?}}). It is safe to call
3436this procedure with managed or unmanaged sdl2:palettes. It is safe
3437(but has no effect) to free a struct record multiple times.
3438
3439See [[https://wiki.libsdl.org/SDL_FreePalette|SDL_FreePalette]].
3440
3441
3442<procedure>(palette-ncolors palette) → fixnum</procedure>
3443<procedure>(palette-ncolours palette) → fixnum</procedure>
3444
3445Returns the number of colors in the palette.
3446Common values are 2 (for a 1-bit surface), 16 (for a 4-bit surface), and 256 (for an 8-bit surface).
3447
3448
3449
3450==== sdl2:pixel-format
3451
3452sdl2:pixel-format is a record type that wraps a pointer to an
3453[[https://wiki.libsdl.org/SDL_PixelFormat|SDL_PixelFormat]] struct.
3454
3455
3456<procedure>(pixel-format? obj) → boolean</procedure>
3457
3458Returns #t if {{obj}} is an sdl2:pixel-format.
3459
3460
3461<procedure>(make-pixel-format #!optional format) → sdl2:pixel-format</procedure>
3462<procedure>(make-pixel-format* #!optional format) → sdl2:pixel-format</procedure>
3463
3464Allocate and initialize a new sdl2:pixel-format with the given format.
3465
3466{{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.
3467See [[https://wiki.libsdl.org/SDL_AllocFormat|SDL_AllocFormat]].
3468
3469* {{make-pixel-format}} returns a managed sdl2:pixel-format.
3470* {{make-pixel-format*}} returns an unmanaged sdl2:pixel-format, which must be freed with {{free-pixel-format!}} when you are done with it.
3471
3472
3473<procedure>(free-pixel-format! pixel-format)</procedure>
3474
3475Free the memory of the sdl2:pixel-format's underlying struct.
3476{{pixel-format}}'s pointer will be set to null (see {{struct-null?}}).
3477It is safe to call this procedure with managed or unmanaged
3478sdl2:pixel-formats. It is safe (but has no effect) to free a struct
3479record multiple times.
3480
3481See [[https://wiki.libsdl.org/SDL_FreeFormat|SDL_FreeFormat]].
3482
3483
3484<procedure>(pixel-format-format pixel-format) → symbol</procedure>
3485<procedure>(pixel-format-format-raw pixel-format) → fixnum</procedure>
3486
3487Get the sdl2:pixel-format's "format" field.
3488
3489* {{pixel-format-format}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]].
3490* {{pixel-format-format-raw}} returns an integer.
3491
3492
3493<procedure>(pixel-format-palette pixel-format) → sdl2:palette or #f</procedure>
3494<setter>(set! (pixel-format-palette pixel-format) val)</setter>
3495<setter>(pixel-format-palette-set! pixel-format val)</setter>
3496
3497Get or set the sdl2:pixel-format's "palette" field, as an sdl2:palette, or #f if it does not have a palette.
3498Only sdl2:pixel-formats with bits-per-pixel of 8 or less can have a palette.
3499
3500See [[https://wiki.libsdl.org/SDL_SetPixelFormatPalette|SDL_SetPixelFormatPalette]].
3501
3502
3503<procedure>(pixel-format-bits-per-pixel pixel-format) → fixnum</procedure>
3504
3505Get the sdl2:pixel-format's "bits-per-pixel" field, as an integer.
3506Common values are 32, 24, 16, 15, 8, 4, and 1.
3507
3508
3509<procedure>(pixel-format-bytes-per-pixel pixel-format) → fixnum</procedure>
3510
3511Get the sdl2:pixel-format's "bits-per-pixel" field, as an integer.
3512Possible values are 4, 3, 2, and 1.
3513
3514
3515<procedure>(pixel-format-rmask pixel-format) → fixnum</procedure>
3516
3517Get the sdl2:pixel-format's "rmask" (red mask) field, as a nonnegative integer.
3518
3519
3520<procedure>(pixel-format-gmask pixel-format) → fixnum</procedure>
3521
3522Get the sdl2:pixel-format's "gmask" (green mask) field, as a nonnegative integer.
3523
3524
3525<procedure>(pixel-format-bmask pixel-format) → fixnum</procedure>
3526
3527Get the sdl2:pixel-format's "bmask" (blue mask) field, as a nonnegative integer.
3528
3529
3530<procedure>(pixel-format-amask pixel-format) → fixnum</procedure>
3531
3532Get the sdl2:pixel-format's "amask" (alpha mask) field, as a nonnegative integer.
3533It will be 0 if there is no alpha channel.
3534
3535
3536
3537==== sdl2:point
3538
3539sdl2:point is a record type that wraps a pointer to an
3540[[https://wiki.libsdl.org/SDL_Point|SDL_Point]] struct.
3541
3542
3543<procedure>(point? obj) → boolean</procedure>
3544
3545Returns #t if {{obj}} is an sdl2:point.
3546
3547
3548<procedure>(make-point #!optional x y) → sdl2:point</procedure>
3549<procedure>(make-point* #!optional x y) → sdl2:point</procedure>
3550
3551Allocate and initialize a new sdl2:point.
3552
3553{{x}} and {{y}} must be integers in the range -2147483648 to 2147483647 (inclusive).
3554They both default to 0.
3555
3556* {{make-point}} returns a managed sdl2:point.
3557* {{make-point*}} returns an unmanaged sdl2:point, which must be freed with {{free-point!}} when you are done with it.
3558
3559
3560<procedure>(free-point! point)</procedure>
3561
3562Free the memory of the sdl2:point's underlying struct. {{point}}'s
3563pointer will be set to null (see {{struct-null?}}). It is safe to call
3564this procedure with managed or unmanaged sdl2:points. It is safe (but
3565has no effect) to free a struct record multiple times.
3566
3567
3568<procedure>(point-x point) → fixnum</procedure>
3569<setter>(set! (point-x point) val)</setter>
3570<setter>(point-x-set! point val)</setter>
3571
3572Get or set the sdl2:point's "x" field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3573
3574
3575<procedure>(point-y point) → fixnum</procedure>
3576<setter>(set! (point-y point) val)</setter>
3577<setter>(point-y-set! point val)</setter>
3578
3579Get or set the sdl2:point's "y" field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3580
3581
3582<procedure>(point-set! point #!optional x y) → point</procedure>
3583
3584Convenient way of setting multiple fields of the sdl2:point.
3585Any arguments that are {{#f}} will cause no change to that field.
3586E.g. {{(point-set! my-point 42 #f)}} will set the "x" field to 42, but will not change the "y" field.
3587Returns {{point}} after it is modified.
3588
3589
3590<procedure>(point->list point) → list of fixnums</procedure>
3591
3592Returns a list {{(x y)}} containing the value of each field of the sdl2:point.
3593
3594
3595<procedure>(point=? point1 point2) → boolean</procedure>
3596
3597Efficiently compare two sdl2:points.
3598Returns #t if the value of every field in {{point1}} is equal to the value of the corresponding field in {{point2}}.
3599
3600
3601<procedure>(copy-point point) → sdl2:point</procedure>
3602<procedure>(copy-point* point) → sdl2:point</procedure>
3603
3604Efficiently copy the given sdl2:point, returning a new sdl2:point with the same values.
3605
3606* {{copy-point}} returns a managed sdl2:point.
3607* {{copy-point*}} returns an unmanaged sdl2:point, which must be freed with {{free-point!}} when you are done with it.
3608
3609
3610==== sdl2:rect
3611
3612sdl2:rect is a record type that wraps a pointer to an
3613[[https://wiki.libsdl.org/SDL_Rect|SDL_Rect]] struct.
3614
3615
3616<procedure>(rect? obj) → boolean</procedure>
3617
3618Returns #t if {{obj}} is an sdl2:rect.
3619
3620
3621<procedure>(make-rect #!optional x y w h) → sdl2:rect</procedure>
3622<procedure>(make-rect* #!optional x y w h) → sdl2:rect</procedure>
3623
3624Allocate and initialize a new sdl2:rect.
3625
3626{{x}}, {{y}}, {{w}}, and {{h}} must be integers in the range -2147483648 to 2147483647 (inclusive).
3627They all default to 0.
3628
3629* {{make-rect}} returns a managed sdl2:rect.
3630* {{make-rect*}} returns an unmanaged sdl2:rect, which must be freed with {{free-rect!}} when you are done with it.
3631
3632
3633<procedure>(free-rect! rect)</procedure>
3634
3635Free the memory of the sdl2:rect's underlying struct. {{rect}}'s
3636pointer will be set to null (see {{struct-null?}}). It is safe to call
3637this procedure with managed or unmanaged sdl2:rects. It is safe (but
3638has no effect) to free a struct record multiple times.
3639
3640
3641<procedure>(rect-x rect) → fixnum</procedure>
3642<setter>(set! (rect-x rect) val)</setter>
3643<setter>(rect-x-set! rect val)</setter>
3644
3645Get or set the sdl2:rect's "x" field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3646
3647
3648<procedure>(rect-y rect) → fixnum</procedure>
3649<setter>(set! (rect-y rect) val)</setter>
3650<setter>(rect-y-set! rect val)</setter>
3651
3652Get or set the sdl2:rect's "y" field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3653
3654
3655<procedure>(rect-w rect) → fixnum</procedure>
3656<setter>(set! (rect-w rect) val)</setter>
3657<setter>(rect-w-set! rect val)</setter>
3658
3659Get or set the sdl2:rect's "w" (width) field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3660
3661
3662<procedure>(rect-h rect) → fixnum</procedure>
3663<setter>(set! (rect-h rect) val)</setter>
3664<setter>(rect-h-set! rect val)</setter>
3665
3666Get or set the sdl2:rect's "h" (height) field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3667
3668
3669<procedure>(rect-set! rect #!optional x y w h) → rect</procedure>
3670
3671Convenient way of setting multiple fields of the sdl2:rect.
3672Any arguments that are {{#f}} will cause no change to that field.
3673E.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.
3674Returns {{rect}} after it is modified.
3675
3676
3677<procedure>(rect->list rect) → list of fixnums</procedure>
3678
3679Returns a list {{(x y w h)}} containing the value of each field of the sdl2:rect.
3680
3681
3682<procedure>(rect=? rect1 rect2) → boolean</procedure>
3683
3684Efficiently compare two sdl2:rects.
3685Returns #t if the value of every field in {{rect1}} is equal to the value of the corresponding field in {{rect2}}.
3686See [[https://wiki.libsdl.org/SDL_RectEquals|SDL_RectEquals]].
3687
3688
3689<procedure>(copy-rect rect) → sdl2:rect</procedure>
3690<procedure>(copy-rect* rect) → sdl2:rect</procedure>
3691
3692Efficiently copy the given sdl2:rect, returning a new sdl2:rect with the same values.
3693
3694* {{copy-rect}} returns a managed sdl2:rect.
3695* {{copy-rect*}} returns an unmanaged sdl2:rect, which must be freed with {{free-rect!}} when you are done with it.
3696
3697
3698
3699==== sdl2:rwops
3700
3701sdl2:rwops is a record type that wraps a pointer to an
3702[[https://wiki.libsdl.org/SDL_RWops|SDL_RWops]] struct.
3703
3704
3705<procedure>(rwops? obj) → boolean</procedure>
3706
3707Returns #t if {{obj}} is an sdl2:rwops.
3708
3709
3710<procedure>(rwops-type rwops) → symbol</procedure>
3711<procedure>(rwops-type-raw rwops) → fixnum</procedure>
3712
3713Get the sdl2:rwops' "type" field, indicating the data source type.
3714
3715* {{rwops-type}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#rwops-types|RWops type symbol]]:
3716** {{'unknown}}
3717** {{'win-file}}
3718** {{'std-file}}
3719** {{'jni-file}}
3720** {{'memory}}
3721** {{'memory-ro}}
3722* {{rwops-type-raw}} returns an integer.
3723
3724
3725
3726==== sdl2:surface
3727
3728sdl2:surface is a record type that wraps a pointer to an
3729[[https://wiki.libsdl.org/SDL_Surface|SDL_Surface]] struct.
3730
3731
3732<procedure>(surface? obj) → boolean</procedure>
3733
3734Returns #t if {{obj}} is an sdl2:surface.
3735
3736
3737<procedure>(make-surface width height depth) → sdl2:surface or #f</procedure>
3738<procedure>(make-surface* width height depth) → sdl2:surface or #f</procedure>
3739
3740Create a new sdl2:surface with the given width, height, and
3741color depth (bits per pixel). This is a more convenient interface for
3742{{create-rgb-surface}}. The sdl2:surface's pixel format and masks will
3743be chosen automatically based on the requested depth and the current
3744platform's byte order (little endian or big endian). Returns #f if the
3745sdl2:surface could not be created (e.g. because the color depth is
3746unsupported).
3747
3748* {{make-surface}} returns a managed sdl2:surface.
3749* {{make-surface*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
3750
3751
3752<procedure>(free-surface! surface)</procedure>
3753
3754Free the memory of the sdl2:surface's underlying struct. {{surface}}'s
3755pointer will be set to null (see {{struct-null?}}). It is safe to call
3756this procedure with managed or unmanaged sdl2:surfaces. It is safe
3757(but has no effect) to free a struct record multiple times.
3758
3759See [[https://wiki.libsdl.org/SDL_FreeSurface|SDL_FreeSurface]].
3760
3761'''NOTE:''' if {{surface}} was created using
3762{{create-rgb-surface-from}}, then the pixel data is not freed.
3763
3764
3765<procedure>(surface-format surface) → sdl2:pixel-format</procedure>
3766
3767Get the sdl2:surface's "format" field, as a sdl2:pixel-format describing the format of the surface's pixels.
3768
3769
3770<procedure>(surface-w surface) → fixnum</procedure>
3771
3772Get the sdl2:surface's "w" field, as a nonnegative integer indicating the surface's width in pixels.
3773
3774
3775<procedure>(surface-h surface) → fixnum</procedure>
3776
3777Get the sdl2:surface's "h" field, as a nonnegative integer indicating the surface's height in pixels.
3778
3779
3780<procedure>(surface-pitch surface) → fixnum</procedure>
3781
3782Get the sdl2:surface's "pitch" field, as a nonnegative integer indicating how many bytes are used to represent one row of pixel data.
3783
3784
3785<procedure>(surface-pixels-raw surface) → pointer or #f</procedure>
3786
3787Get the sdl2:surface's "pixels" field, as a raw pointer to the sdl2:surface's pixels.
3788Don't use this unless you really know what you are doing!
3789
3790If you want to get or set a pixel, use {{surface-ref}} and {{surface-set!}} instead.
3791They are much safer, more convenient, and more efficient than accessing the pixel data using this pointer.
3792
3793
3794<procedure>(surface-userdata-raw surface) → pointer or #f</procedure>
3795<setter>(set! (surface-userdata-raw surface) val)</setter>
3796<setter>(surface-userdata-raw-set! surface val)</setter>
3797
3798Get or set the sdl2:surface's "userdata" field, as a pointer or #f.
3799
3800If you want to store a pointer to a Scheme object here, be sure to
3801[[/manual/Unit lolevel#object-evict|evict the object]] first. Otherwise
3802the object's location in memory might change, rendering the pointer
3803invalid.
3804
3805
3806<procedure>(surface-refcount surface) → fixnum</procedure>
3807<setter>(set! (surface-refcount surface) val)</setter>
3808<setter>(surface-refcount-set! surface val)</setter>
3809
3810Get or set the sdl2:surface's "refcount" field, as an integer.
3811
3812
3813
3814==== sdl2:texture
3815
3816sdl2:texture is a record type that wraps a pointer to an
3817[[https://wiki.libsdl.org/SDL_Texture|SDL_Texture]] struct.
3818
3819
3820<procedure>(texture? obj) → boolean</procedure>
3821
3822Returns #t if {{obj}} is an sdl2:texture.
3823
3824
3825
3826==== sdl2:window
3827
3828sdl2:window is a record type that wraps a pointer to an
3829[[https://wiki.libsdl.org/SDL_CreateWindow|SDL_Window]] struct.
3830
3831
3832<procedure>(window? obj) → boolean</procedure>
3833
3834Returns #t if {{obj}} is an sdl2:window.
Note: See TracBrowser for help on using the repository browser.