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

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

sdl2: More work on docs.

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