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

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

sdl2: Version 0.1.1.

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