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

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

sdl2: Docs for struct-eq?

File size: 215.6 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 : [[/users/john-croisant|John Croisant]]
18; License: [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/LICENSE-BSD.txt|BSD 2-Clause]]
19
20
21'''Table of Contents:'''
22[[toc:]]
23
24
25== Help Wanted!
26
27This egg needs volunteers to help with several things:
28
29* Manual testing (installing, running examples) on different platforms
30* Writing unit tests and semi-automated test programs
31* Writing API reference docs, guides, and tutorials
32* Creating detailed installation instructions for different platforms
33* Creating feature demos and example games/programs
34
35If you wish to help in any way, please contact the project maintainer.
36
37
38== Requirements
39
40The sdl2 egg requires [[http://libsdl.org/|Simple DirectMedia Layer]]
41version 2.0.0 or higher. It will not work with older versions of SDL.
42
43This egg requires CHICKEN Scheme 4.8 or higher.
44Please file an issue or contact the maintainer if you need to use this library with an earlier version of CHICKEN Scheme.
45
46The unit tests depend on the [[/egg/test|test]] egg, and many demos
47and examples depend on the [[/egg/miscmacros|miscmacros]] egg. Some
48demos and examples have other dependencies as well.
49
50
51== Related Libraries
52
53The [[/egg/sdl2-image|sdl2-image egg]] provides bindings to version 2 of the SDL_image library, which provides the ability to load many image formats. It is built to be compatible with sdl2.
54
55The [[/egg/sdl2-ttf|sdl2-ttf egg]] provides bindings to version 2 of the SDL_ttf library, which provides the ability to render text using TTF and FON fonts. It is built to be compatible with sdl2.
56
57The [[/egg/sdl-base|sdl-base egg]] provides bindings to older versions of SDL. Its API is not compatible with sdl2.
58
59
60== Installation
61
62When installing the egg, you should set the SDL2_FLAGS environment
63variable to a string of compiler flags to be used when compiling the
64egg. If you have the {{sdl2-config}} helper program installed on your
65system, you can set appropriate flags and install the extension like
66so (notice these are back ticks, not quotes):
67
68 export SDL2_FLAGS=`sdl2-config --cflags --libs`
69 chicken-install sdl2
70
71If you do not have the {{sdl2-config}} helper program installed on your
72computer, you may manually specify SDL-related compiler flags (notice
73these are double quotes, not back ticks):
74
75 export SDL2_FLAGS="-I/usr/local/include/SDL2 -L/usr/local/lib -lSDL2"
76 chicken-install sdl2
77
78You only need to set the SDL2_FLAGS environment variable when installing the egg,
79not when using it.
80
81
82== Usage and Examples
83
84It is recommended that you import the sdl2 module using the prefix
85"sdl2:", like so:
86
87<enscript highlight="scheme">
88(use (prefix sdl2 sdl2:))
89(sdl2:set-main-ready!)
90(sdl2:init! '(video))
91(define window (sdl2:create-window! "Hello, World!" 0 0 600 400))
92(sdl2:fill-rect! (sdl2:window-surface window)
93                 #f
94                 (sdl2:make-color 0 128 255))
95(sdl2:update-window-surface! window)
96(sdl2:delay! 3000)
97(sdl2:quit!)
98</enscript>
99
100The [[https://gitlab.com/chicken-sdl2/chicken-sdl2/tree/master/demos|demos directory]]
101contains small programs demonstrating how to use various features of sdl2.
102E.g. to compile and run the basics demo:
103
104 csc demos/basics.scm
105 demos/basics
106
107The [[https://gitlab.com/chicken-sdl2/chicken-sdl2-examples|chicken-sdl2-examples repository]]
108contains complete example games and programs made with sdl2.
109
110=== Ensuring Proper Clean Up
111
112You must make sure to call {{set-main-ready!}} and {{init!}} (in that order) soon after your program starts, and to call {{quit!}} before your program ends.
113This is especially important if your program enters fullscreen mode, or changes the display brightness or gamma ramp.
114If your program does not perform proper initialization and clean up, those changes can sometimes linger even after your program has ended, which can be very frustrating for your program's users.
115It is even possible for the user's computer to become stuck in fullscreen mode, requiring the user to power off their computer, possibly losing important work that they were doing in other programs!
116
117Here is a simple way to ensure that {{quit!}} is called before your program ends, whether exitting normally or because an exception occurred:
118
119<enscript highlight="scheme">
120(use (prefix sdl2 sdl2:))
121
122;; Initialize SDL
123(sdl2:set-main-ready!)
124(sdl2:init! '(video)) ;; or whatever init flags your program needs
125
126;; Schedule quit! to be automatically called when your program exits normally.
127(on-exit sdl2:quit!)
128
129;; Install a custom exception handler that will call quit! and then
130;; call the original exception handler. This ensures that quit! will
131;; be called even if an unhandled exception reaches the top level.
132(current-exception-handler
133 (let ((original-handler (current-exception-handler)))
134   (lambda (exception)
135     (sdl2:quit!)
136     (original-handler exception))))
137
138;; ...
139;; ... the rest of your program code ...
140;; ...
141</enscript>
142
143
144== Version History
145
146; 0.2.0 (in development) : Added 2D accelerated rendering (renderer and texture). Added hints. Added color, point, and rect operations. Performance improvements. Improved integer type checking. Miscellaneous other changes.
147; 0.1.1 (2015-12-22) : Fixed a compile error when compiling with GCC 4.
148; 0.1.0 (2015-12-19) : Initial release.
149
150For more information about what changed in each version,
151see the [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/CHANGELOG.md|CHANGELOG]].
152
153
154== API
155
156=== About the API
157
158==== API Stability
159
160The sdl2 egg follows "[[http://semver.org/|semantic versioning]]".
161Until version 1.0.0 is released, the API is not guaranteed to be "stable".
162That means the maintainer reserves the right to change the API if needed,
163possibly in ways that break backwards compatibility with previous versions.
164'''Large backwards-incompatible changes are unlikely''',
165but there may be small tweaks and fixes to the API if problems are discovered.
166
167After version 1.0.0 is released, the API is guaranteed to remain stable (no backwards-incompatible changes)
168until the next new major version (e.g. going from version 1.x to 2.0.0, or 2.x to 3.0.0).
169
170==== Conventions
171
172* Procedures names, including function bindings, are Scheme style.
173** All procedure names are lower case and hyphenated, with no "SDL_" prefix.
174** Procedures that ask a "true or false" question (aka predicates) are suffixed with "?".
175   Usually words such as "has" or "is" are removed from predicate names.
176** Procedures that cause a mutation or side effect are suffixed with "!".
177** Procedures that set the value of a field are named like {{TYPE-FIELD-set!}}, e.g. {{rect-x-set!}}.
178   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)}}.
179   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.
180
181* Many procedures signal an exception of kind {{(exn sdl2)}} if an error occurs or the operation fails.
182  This is instead of returning an integer error code or null pointer.
183
184* Procedures return {{#f}} instead of a null struct record or null pointer, in non-error cases.
185
186* Some procedures return multiple values.
187  For example, {{window-size}} returns two values, the width and height.
188  You can use {{receive}}, {{let-values}}, etc. to capture all the return values.
189
190* 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*}}.
191  See the [[#struct-memory-management|Struct Memory Management]] section for more information.
192
193* Some procedures have a "raw" version, which returns a "low level" type, such as an integer constant or memory pointer.
194  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.
195** 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}}.
196** Setters that accept an enum symbol will also accept the corresponding integer value.
197   Setters that accept a list of enum symbols will also accept an integer representing {{bitwise-ior}}'d integer flags or masks.
198
199* Procedures with a name containing the word "color" have an alias spelled as "colour", for the convenience of anyone who spells it that way.
200  Both names refer to exactly the same procedure.
201
202
203==== Enums
204
205The sdl2 egg uses symbols instead of integer constants, for things like event types, keyboard keys, and init flags.
206It uses lists of symbols instead of {{bitwise-ior}}'d integer masks or flags.
207See the [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md|enum tables]] for details.
208
209Many procedures that return an enum symbol or a list of enum symbols, also have a "raw" version that returns the equivalent integer value.
210Setters that accept an enum symbol will also accept the corresponding integer value.
211Setters that accept a list of enum symbols will also accept an integer representing {{bitwise-ior}}'d integer flags or masks.
212
213
214==== The sdl2-internals Module
215
216The 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.
217Most 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.
218
219The {{sdl2-internals}} module is not an official part of the public API, and does not have the same guarantees of API stability.
220But, certain parts of the module are safe to use in your programs.
221For more information, see this guide:
222
223* [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/using-sdl2-internals.md|Using sdl2-internals]]
224
225
226==== Struct Memory Management
227
228The sdl2 egg has many "struct record types",
229which are Scheme record types that wrap a pointer to a certain C struct from SDL.
230For example, the sdl2:surface record type wraps a pointer to an SDL_Surface struct.
231
232Some struct record types have procedures for allocating or freeing an instance of that type.
233Each type that can be allocated has two "make" procedures:
234
235* The normal make procedure (e.g. {{make-event}}) returns a '''managed''' struct record,
236  whose underlying struct memory will be automatically freed when the record is garbage collected.
237
238* The make procedure with an asterisk (e.g. {{make-event*}}) returns an '''unmanaged''' struct record,
239  which must be manually freed when you are done with it (e.g. using {{free-event!}}).
240
241Certain other procedures that return new struct records also follow
242this convention, for example {{load-bmp}} vs. {{load-bmp*}}.
243
244In most cases, it is best to create managed struct records, so that you don't have to worry about manually freeing them.
245However, in certain advanced use cases, you might require that the struct's underlying pointer address never change.
246For example, suppose you are storing the pointer address in another C struct.
247In such cases, you should create an unmanaged struct record, not a managed struct record.
248Unmanaged struct records will keep the same underlying pointer address throughout their life,
249but managed struct records may sometimes be moved in memory by the garbage collector.
250(Most users do not need to worry about this.)
251
252If you create an unmanaged struct record but want to automatically free its memory when it is garbage collected,
253you can use [[/manual/Unit library#set-finalizer|set-finalizer!]] with the appropriate "free" procedure.
254(This is how most, but not all, managed struct records are implemented.)
255For example:
256
257<enscript highlight="scheme">
258;; Allocate an unmanaged sdl2:surface.
259(let ((my-surf (sdl2:make-surface* 800 600 30)))
260  ;; Set a finalizer so it will be automatically freed.
261  (set-finalizer! my-surf sdl2:free-surface!))
262</enscript>
263
264It is safe to manually free managed struct records. In fact, doing so
265can be beneficial to your program's memory footprint and performance,
266because there will be less memory waiting to be freed by the garbage
267collector. For example:
268
269<enscript highlight="scheme">
270(let ((my-surf (sdl2:make-surface 800 600 32)))
271  ;; ... do stuff with my-surf ...
272  ;; Once you are done with my-surf, manually free it.
273  (sdl2:free-surface! my-surf))
274</enscript>
275
276As soon as you free a struct record, its pointer will be set to null,
277and it will no longer be usable for most purposes. You cannot get or
278set its fields, or pass it as an argument to most procedures. So be
279careful not to free struct records that you still want to use!
280
281Some struct record types, such as sdl2:window, are not managed in this
282way. Instead, you use certain SDL functions to work with them, such as
283{{create-window!}} and {{destroy-window!}}.
284
285
286
287=== General Struct Management
288
289<procedure>(struct-eq? obj1 obj2) → boolean</procedure>
290
291Returns #t if both objects refer to the same memory location.
292The objects can be struct record instances, pointers, locatives,
293or the value #f (equivalent to a null pointer).
294
295This procedure can be used with any struct record type provided by this library,
296or related libraries such as [[/egg/sdl2-ttf|sdl2-ttf]].
297
298This procedure is the only reliable way to compare the identities of struct records
299provided by this library or related libraries.
300Other procedures, such as {{eq?}} or {{equal?}}, are not guaranteed to work correctly.
301They may break in the future due to changes in the implementation of struct records.
302
303
304<procedure>(struct-null? record) → boolean</procedure>
305
306Returns #t if the given record is a null struct record,
307i.e. it has a pointer to memory address 0.
308This procedure can be used with any struct record type provided by this library,
309or related libraries such as [[/egg/sdl2-ttf|sdl2-ttf]].
310
311A struct record will be null after you manually free its memory, e.g. using {{free-surface!}}.
312Most procedures, including field getters and setters, will signal an error if you pass a null struct record.
313So, you can use this procedure to check whether it is safe to use the record.
314
315It is possible for a C function to return a null struct record.
316But, if a function binding in this library returns a null struct record, that is a bug and should be reported.
317Function bindings in this library are supposed to return {{#f}} instead of a null struct record.
318
319
320
321=== Initialization and Clean Up
322
323<procedure>(set-main-ready!)</procedure>
324
325See [[https://wiki.libsdl.org/SDL_SetMainReady|SDL_SetMainReady]].
326
327You should call this soon after your program starts, '''before''' calling {{init!}}.
328See [[/egg/sdl2#ensuring-proper-clean-up|Ensuring Proper Clean Up]].
329
330
331<procedure>(init! #!optional flags-list)</procedure>
332
333Initialize SDL.
334You should call this soon after your program starts, '''after''' calling {{set-main-ready!}}.
335See [[/egg/sdl2#ensuring-proper-clean-up|Ensuring Proper Clean Up]].
336
337{{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]]:
338
339* {{'timer}}
340* {{'audio}}
341* {{'video}}
342* {{'joystick}}
343* {{'haptic}}
344* {{'game-controller}}
345* {{'events}}
346* {{'everything}}
347
348See [[https://wiki.libsdl.org/SDL_Init|SDL_Init]].
349
350Signals an exception of kind {{(exn sdl2)}} if initialization fails.
351
352
353<procedure>(init-subsystem! flags-list)</procedure>
354
355See [[https://wiki.libsdl.org/SDL_InitSubSystem|SDL_InitSubSystem]].
356
357{{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.
358
359Signals an exception of kind {{(exn sdl2)}} if initialization fails.
360
361
362<procedure>(quit!)</procedure>
363
364Clean up SDL.
365You must make sure to call this before your program ends.
366See [[/egg/sdl2#ensuring-proper-clean-up|Ensuring Proper Clean Up]].
367
368See [[https://wiki.libsdl.org/SDL_Quit|SDL_Quit]].
369
370
371<procedure>(quit-subsystem! flags-list)</procedure>
372
373See [[https://wiki.libsdl.org/SDL_QuitSubSystem|SDL_QuitSubSystem]].
374
375{{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.
376
377
378<procedure>(was-init #!optional flags-list) → list of symbols</procedure>
379
380See [[https://wiki.libsdl.org/SDL_WasInit|SDL_WasInit]].
381
382{{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.
383
384
385
386=== Color
387
388==== sdl2:color
389
390sdl2:color is a record type that wraps a pointer to an
391[[https://wiki.libsdl.org/SDL_Color|SDL_Color]] struct.
392
393
394<procedure>(color? obj) → boolean</procedure>
395<procedure>(colour? obj) → boolean</procedure>
396
397Returns #t if {{obj}} is an sdl2:color.
398
399
400<procedure>(make-color #!optional r g b a) → sdl2:color</procedure>
401<procedure>(make-colour #!optional r g b a) → sdl2:color</procedure>
402<procedure>(make-color* #!optional r g b a) → sdl2:color</procedure>
403<procedure>(make-colour* #!optional r g b a) → sdl2:color</procedure>
404
405Allocate and initialize a new sdl2:color.
406
407{{r}}, {{g}}, {{b}}, and {{a}} must be integers in the range 0 to 255 (inclusive).
408{{r}}, {{g}}, and {{b}} default to 0.
409{{a}} defaults to 255 (full opacity).
410
411* {{make-color}} and {{make-colour}} return a managed sdl2:color.
412* {{make-color*}} and {{make-colour*}} return an unmanaged sdl2:color, which must be freed using {{free-color!}} when you are done with it.
413
414
415<procedure>(free-color! color)</procedure>
416<procedure>(free-colour! color)</procedure>
417
418Free the memory of the sdl2:color's underlying struct. {{color}}'s
419pointer will be set to null (see {{struct-null?}}). It is safe to call
420this procedure with managed or unmanaged sdl2:colors. It is safe (but
421has no effect) to free a struct record multiple times.
422
423
424<procedure>(color-r color) → integer</procedure>
425<procedure>(colour-r color) → integer</procedure>
426<setter>(set! (color-r color) val)</setter>
427<setter>(set! (colour-r color) val)</setter>
428<setter>(color-r-set! color val)</setter>
429<setter>(colour-r-set! color val)</setter>
430
431Get or set the sdl2:color's "r" (red) field, as an integer in the range 0 to 255 (inclusive).
432
433
434<procedure>(color-g color) → integer</procedure>
435<procedure>(colour-g color) → integer</procedure>
436<setter>(set! (color-g color) val)</setter>
437<setter>(set! (colour-g color) val)</setter>
438<setter>(color-g-set! color val)</setter>
439<setter>(colour-g-set! color val)</setter>
440
441Get or set the sdl2:color's "g" (green) field, as an integer in the range 0 to 255 (inclusive).
442
443
444<procedure>(color-b color) → integer</procedure>
445<procedure>(colour-b color) → integer</procedure>
446<setter>(set! (color-b color) val)</setter>
447<setter>(set! (colour-b color) val)</setter>
448<setter>(color-b-set! color val)</setter>
449<setter>(colour-b-set! color val)</setter>
450
451Get or set the sdl2:color's "b" (blue) field, as an integer in the range 0 to 255 (inclusive).
452
453
454<procedure>(color-a color) → integer</procedure>
455<procedure>(colour-a color) → integer</procedure>
456<setter>(set! (color-a color) val)</setter>
457<setter>(set! (colour-a color) val)</setter>
458<setter>(color-a-set! color val)</setter>
459<setter>(colour-a-set! color val)</setter>
460
461Get or set the sdl2:color's "a" (alpha) field, as an integer in the range 0 to 255 (inclusive).
462
463
464
465==== sdl2:color Operations
466
467These are operations for efficiently and conveniently working with sdl2:colors.
468Many of them are implemented in C for efficiency.
469
470
471<setter>(color-set! color #!optional r g b a) → color</setter>
472<setter>(colour-set! color #!optional r g b a) → color</setter>
473
474Efficient and convenient way of setting multiple fields of the sdl2:color.
475Any arguments that are {{#f}} will cause no change to that field.
476E.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.
477Returns {{color}} after it is modified.
478
479
480<procedure>(color->list color) → list of integers</procedure>
481<procedure>(colour->list color) → list of integers</procedure>
482
483Returns a list {{(r g b a)}} containing the value of each field of the sdl2:color.
484
485
486<procedure>(color->values color) → [r g b a]</procedure>
487<procedure>(colour->values color) → [r g b a]</procedure>
488
489Returns multiple values containing the value of each field of the sdl2:color.
490This is useful for destructuring an sdl2:color using {{receive}} or {{let-values}}.
491
492
493<procedure>(color=? color1 color2) → boolean</procedure>
494<procedure>(colour=? color1 color2) → boolean</procedure>
495
496Efficiently compare two sdl2:colors.
497Returns #t if the value of every field in {{color1}} is equal to the value of the corresponding field in {{color2}}.
498
499
500<procedure>(color-copy   src) → sdl2:color</procedure>
501<procedure>(colour-copy  src) → sdl2:color</procedure>
502<procedure>(color-copy!  src dest) → dest</procedure>
503<procedure>(colour-copy! src dest) → dest</procedure>
504
505{{color-copy}} and {{colour-copy}} efficiently copy the values of {{src}} into a new managed sdl2:color.
506{{color-copy}} and {{colour-copy}} are available in '''sdl2 egg version 0.2.0 and higher'''.
507In earlier versions, they were named {{copy-color}} and {{copy-colour}}.
508
509{{color-copy!}} and {{colour-copy!}} efficiently copy the values of {{src}} into {{dest}},
510and return the modified {{dest}}.
511It is safe (but useless) for {{src}} and {{dest}} to be the same object.
512{{color-copy!}} and {{colour-copy!}} are available in '''sdl2 egg version 0.2.0 and higher'''.
513
514
515<procedure>(copy-color color) → sdl2:color</procedure>
516<procedure>(copy-colour color) → sdl2:color</procedure>
517
518Deprecated aliases for {{color-copy}} and {{colour-copy}}.
519These aliases were deprecated in sdl2 egg version 0.2.0,
520and will be removed in a future version.
521
522
523<procedure>(copy-color* color) → sdl2:color</procedure>
524<procedure>(copy-colour* color) → sdl2:color</procedure>
525
526Deprecated procedures.
527These procedures were deprecated in sdl2 egg version 0.2.0,
528and will be removed in a future version.
529You can achieve the same effect using {{color-copy!}} and {{make-color*}}.
530
531
532<procedure>(color-scale   color scale) → sdl2:color</procedure>
533<procedure>(colour-scale  color scale) → sdl2:color</procedure>
534<procedure>(color-scale!  color scale #!optional dest) → dest</procedure>
535<procedure>(colour-scale! color scale #!optional dest) → dest</procedure>
536
537Efficiently scale (multiply) the RGBA values of {{color}} by {{scale}} (a float or integer).
538E.g. {{scale}} 0.5 halves the RGBA values, {{scale}} 2.0 doubles the values.
539
540* {{color-scale}} and {{colour-scale}} return a new managed sdl2:color.
541* {{color-scale!}} and {{colour-scale!}} modify and return {{dest}}.
542  If {{dest}} is omitted, {{color}} is modified and returned.
543
544These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
545
546The results are clamped to the range [0, 255].
547sdl2:color can only hold integer values, so the results will be truncated to integers.
548
549
550<procedure>(color-mult   color1 color2) → sdl2:color</procedure>
551<procedure>(colour-mult  color1 color2) → sdl2:color</procedure>
552<procedure>(color-mult!  color1 color2 #!optional dest) → dest</procedure>
553<procedure>(colour-mult! color1 color2 #!optional dest) → dest</procedure>
554
555Efficiently multiply-blend {{color1}} by {{color2}}.
556This is equivalent to the "multiply" blend mode of image editors,
557where {{color1}} is the bottom layer and {{color2}} is the top layer.
558
559* {{color-mult}} and {{colour-mult}} return a new managed sdl2:color.
560* {{color-mult!}} and {{colour-mult!}} modify and return {{dest}}.
561  If {{dest}} is omitted, {{color1}} is modified and returned.
562
563These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
564
565The results are clamped to the range [0, 255].
566sdl2:color can only hold integer values, so the results will be truncated to integers.
567
568This operation only affects the R, G, and B values.
569The result's A value will always be the same as {{color1}}'s A value.
570
571{{color2}}'s A value controls the strength of the effect.
572E.g. 255 means full strength, 127 means half strength,
5730 means no effect (the result will have the same values as {{color1}}).
574
575
576<procedure>(color-add   color1 color2) → sdl2:color</procedure>
577<procedure>(colour-add  color1 color2) → sdl2:color</procedure>
578<procedure>(color-add!  color1 color2 #!optional dest) → dest</procedure>
579<procedure>(colour-add! color1 color2 #!optional dest) → dest</procedure>
580
581Efficiently add-blend {{color1}} by {{color2}}.
582This is equivalent to the "addition" blend mode of image editors,
583where {{color1}} is the bottom layer and {{color2}} is the top layer.
584
585* {{color-add}} and {{colour-add}} return a new managed sdl2:color.
586* {{color-add!}} and {{colour-add!}} modify and return {{dest}}.
587  If {{dest}} is omitted, {{color1}} is modified and returned.
588
589These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
590
591The results are clamped to the range [0, 255].
592sdl2:color can only hold integer values, so the results will be truncated to integers.
593
594This operation only affects the R, G, and B values.
595The result's A value will always be the same as {{color1}}'s A value.
596
597{{color2}}'s A value controls the strength of the effect.
598E.g. 255 means full strength, 127 means half strength,
5990 means no effect (the result will have the same values as {{color1}}).
600
601
602<procedure>(color-sub! color1 color2 #!optional dest) → dest</procedure>
603<procedure>(colour-sub! color1 color2 #!optional dest) → dest</procedure>
604
605Efficiently subtract-blend {{color1}} by {{color2}}.
606This is equivalent to the "subtract" blend mode of image editors,
607where {{color1}} is the bottom layer and {{color2}} is the top layer.
608
609* {{color-sub}} and {{colour-sub}} return a new managed sdl2:color.
610* {{color-sub!}} and {{colour-sub!}} modify and return {{dest}}.
611  If {{dest}} is omitted, {{color1}} is modified and returned.
612
613These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
614
615The results are clamped to the range [0, 255].
616sdl2:color can only hold integer values, so the results will be truncated to integers.
617
618This operation only affects the R, G, and B values.
619The result's A value will always be the same as {{color1}}'s A value.
620
621{{color2}}'s A value controls the strength of the effect.
622E.g. 255 means full strength, 127 means half strength,
6230 means no effect (the result will have the same values as {{color1}}).
624
625
626<procedure>(color-lerp  color1 color2 t) → sdl2:color</procedure>
627<procedure>(color-lerp! color1 color2 t #!optional dest) → dest</procedure>
628
629Efficient linear interpolation (or extrapolation) between {{color1}} and {{color2}}.
630sdl2:color can only hold integer values, so the results will be truncated to integers.
631The results will be clamped to the range 0 to 255.
632
633{{t}} is the interpolation factor (a float).
634Values of {{t}} between 0 and 1 will interpolate between {{color1}} and {{color2}}.
635Values of {{t}} less that 0 will extrapolate beyond {{color1}} (moving away from {{color2}}).
636Values greater that 1 will extrapolate beyond {{color2}} (moving away from {{color1}}).
637
638* {{color-lerp}} returns a new managed sdl2:color.
639* {{color-lerp!}} modifies and returns {{dest}}.
640  If {{dest}} is omitted, {{color1}} is modified and returned.
641
642These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
643
644
645
646=== Event
647
648==== Event Functions
649
650<procedure>(event-state type) → boolean</procedure>
651<setter>(set! (event-state type) state) → boolean</setter>
652<setter>(event-state-set! type state) → boolean</setter>
653
654Get or set the state of the given event type.
655#t means the event type is enabled, so events of that type may appear on the event queue.
656#f means the event type is disabled, so events of that type will be automatically discarded.
657It is beneficial to your program's performance to disable event types that your program does not need.
658
659{{type}} must be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbol]] or corresponding integer.
660
661If you set an event type's state to #f, any events of that type already on the event queue will be immediately discarded.
662The setters return the previous state of the given event type.
663
664See [[https://wiki.libsdl.org/SDL_EventState|SDL_EventState]].
665
666
667<procedure>(flush-event! type)</procedure>
668<procedure>(flush-events! #!optional min-type max-type)</procedure>
669
670Remove all events on the event queue that match the given type or range of types.
671See [[https://wiki.libsdl.org/SDL_FlushEvent|SDL_FlushEvent]]
672and [[https://wiki.libsdl.org/SDL_FlushEvents|SDL_FlushEvents]].
673
674For {{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.
675
676For {{flush-events!}}, {{min-type}} and {{max-type}} specify the range of event types to remove.
677Events with a type outside of this range will not be removed.
678{{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.
679{{min-type}} defaults to {{'first}} and {{max-type}} defaults to {{'last}}, which means all event types match by default.
680
681
682<procedure>(has-event? type) → boolean</procedure>
683<procedure>(has-events? #!optional min-type max-type) → boolean</procedure>
684
685Returns #t if the event queue currently has at least one event matching the given type or range of types.
686See [[https://wiki.libsdl.org/SDL_HasEvent|SDL_HasEvent]]
687and [[https://wiki.libsdl.org/SDL_HasEvents|SDL_HasEvents]].
688
689For {{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.
690
691For {{has-events?}}, {{min-type}} and {{max-type}} specify the range of event types to consider.
692Events with a type outside of this range will not be considered.
693{{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.
694{{min-type}} defaults to {{'first}} and {{max-type}} defaults to {{'last}}, which means all event types match by default.
695
696
697<procedure>(quit-requested?) → boolean</procedure>
698
699Returns #t if the event queue currently has at least one event of type {{'quit}}.
700See [[https://wiki.libsdl.org/SDL_QuitRequested|SDL_QuitRequested]].
701
702
703<procedure>(get-events! num #!optional min-type max-type) → list of sdl2:events</procedure>
704<procedure>(peek-events num #!optional min-type max-type) → list of sdl2:events</procedure>
705
706Get multiple matching events from the front of the event queue.
707Returns a list of managed sdl2:events.
708See [[https://wiki.libsdl.org/SDL_PeepEvents|SDL_PeepEvents]].
709
710* {{get-events!}} removes the returned events from the event queue.
711* {{peek-events}} does not remove the returned events from the event queue.
712
713{{num}} specifies the maximum number of events to return.
714May return fewer events if there are not enough matching events on the event queue.
715
716{{min-type}} and {{max-type}} specify the range of event types to return.
717Events with a type outside of this range will not be returned (they will remain on the queue).
718{{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.
719{{min-type}} defaults to {{'first}} and {{max-type}} defaults to {{'last}}, which means all event types match by default.
720
721Both procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
722
723
724<procedure>(poll-event! #!optional result-event) → sdl2:event</procedure>
725
726Get the next event from the event queue.
727The returned event is removed from the event queue.
728See [[https://wiki.libsdl.org/SDL_PollEvent|SDL_PollEvent]].
729
730If {{result-event}} is omitted or #f, a new managed sdl2:event will be returned.
731If {{result-event}} is an sdl2:event, it will be modified and returned.
732This allows you to allocate a single event and reuse it many times in your event loop,
733so that your program does not create as much garbage for the garbage collector.
734
735
736<procedure>(pump-events!)</procedure>
737
738See [[https://wiki.libsdl.org/SDL_PumpEvents|SDL_PumpEvents]].
739
740
741<procedure>(push-event! event) → boolean</procedure>
742
743See [[https://wiki.libsdl.org/SDL_PushEvent|SDL_PushEvent]].
744
745Returns #t if the event was pushed onto the event queue, or #f if the event was discarded,
746e.g. because the event type is disabled (see {{event-state}}).
747
748Signals an exception of kind {{(exn sdl2)}} if an error occurs.
749
750
751<procedure>(wait-event! #!optional result-event) → sdl2:event</procedure>
752<procedure>(wait-event-timeout! timeout #!optional result-event) → sdl2:event or #f</procedure>
753
754Wait for the next event to appear on the event queue, then return it.
755The returned event will be removed from the event queue.
756If there is already an event on the event queue, it will be returned immediately.
757Otherwise, these procedures will block the current thread until the next event appears (or the timeout expires).
758
759* {{wait-event!}} will wait indefinitely for an event to appear.
760* {{wait-event-timeout!}} will stop waiting and return #f if no event appears within {{timeout}} milliseconds.
761  (It may actually wait a few milliseconds longer than specified.
762  You should not rely on its timing being very precise.)
763
764If {{result-event}} is omitted or #f, a new managed sdl2:event will be returned.
765If {{result-event}} is an sdl2:event, it will be modified and returned.
766This allows you to allocate a single event and reuse it many times in your event loop,
767so that your program does not create as much garbage for the garbage collector.
768
769These procedures are compatible with [[/manual/Unit srfi-18|SRFI-18]] multithreading.
770Only the current thread will block while waiting.
771Other threads will continue as normal.
772
773These procedures are inspired by (but do not actually use)
774[[https://wiki.libsdl.org/SDL_WaitEvent|SDL_WaitEvent]] and
775[[https://wiki.libsdl.org/SDL_WaitEventTimeout|SDL_WaitEventTimeout]].
776
777
778<procedure>(register-events! event-symbols) → list of pairs</procedure>
779
780Register zero or more symbols as new user event types.
781After registration, the given symbols may be used as event types, e.g. with {{event-type-set!}}.
782The symbols will be associated with the sdl2:user-event variant of sdl2:event.
783
784{{event-symbols}} must be a list of symbols that are not already being used as event types.
785If any symbol is already being used, or if any member of the list is not a symbol,
786an error will be signalled and none of the new event types will be registered.
787
788There are 32767 user event type numbers available to register.
789Each symbol in {{event-symbols}} will be assigned a sequential number.
790If there are not enough remaining numbers to register all the symbols in {{event-symbols}},
791this procedure will signal an exception of kind {{(exn sdl2)}}, and none of the new event types will be registered.
792
793This 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.
794
795This procedure is based on [[https://wiki.libsdl.org/SDL_RegisterEvents|SDL_RegisterEvents]].
796
797
798==== sdl2:event
799
800sdl2:event is a record type that wraps a pointer to an
801[[https://wiki.libsdl.org/SDL_Event|SDL_Event]]. There are many
802specific event structs in SDL, and the sdl2:event type wraps them all.
803Each event struct has a corresponding variant of sdl2:event, described
804below. Each variant has one or more associated
805[[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbols]].
806
807
808<table>
809  <tr>
810    <th>Variant of sdl2:event</th>
811    <th>Underlying struct</th>
812    <th>Event type symbol(s)</th>
813  </tr>
814  <tr>
815    <td>[[#sdl2controller-axis-event|sdl2:controller-axis-event]]</td>
816    <td>[[https://wiki.libsdl.org/SDL_ControllerAxisEvent|SDL_ControllerAxisEvent]]</td>
817    <td>{{'controller-axis-motion}}</td>
818  </tr>
819  <tr>
820    <td>[[#sdl2controller-button-event|sdl2:controller-button-event]]</td>
821    <td>[[https://wiki.libsdl.org/SDL_ControllerButtonEvent|SDL_ControllerButtonEvent]]</td>
822    <td>{{'controller-button-down}}<br>
823        {{'controller-button-up}}</td>
824  </tr>
825  <tr>
826    <td>[[#sdl2controller-device-event|sdl2:controller-device-event]]</td>
827    <td>[[https://wiki.libsdl.org/SDL_ControllerDeviceEvent|SDL_ControllerDeviceEvent]]</td>
828    <td>{{'controller-device-added}}<br>
829        {{'controller-device-removed}}<br>
830        {{'controller-device-remapped}}</td>
831  </tr>
832  <tr>
833    <td>[[#sdl2dollar-gesture-event|sdl2:dollar-gesture-event]]</td>
834    <td>[[https://wiki.libsdl.org/SDL_DollarGestureEvent|SDL_DollarGestureEvent]]</td>
835    <td>{{'dollar-gesture}}<br>
836        {{'dollar-record}}</td>
837  </tr>
838  <tr>
839    <td>[[#sdl2drop-event|sdl2:drop-event]]</td>
840    <td>[[https://wiki.libsdl.org/SDL_DropEvent|SDL_DropEvent]]</td>
841    <td>{{'drop-file}}</td>
842  </tr>
843  <tr>
844    <td>[[#sdl2joy-axis-event|sdl2:joy-axis-event]]</td>
845    <td>[[https://wiki.libsdl.org/SDL_JoyAxisEvent|SDL_JoyAxisEvent]]</td>
846    <td>{{'joy-axis-motion}}</td>
847  </tr>
848  <tr>
849    <td>[[#sdl2joy-ball-event|sdl2:joy-ball-event]]</td>
850    <td>[[https://wiki.libsdl.org/SDL_JoyBallEvent|SDL_JoyBallEvent]]</td>
851    <td>{{'joy-ball-motion}}</td>
852  </tr>
853  <tr>
854    <td>[[#sdl2joy-button-event|sdl2:joy-button-event]]</td>
855    <td>[[https://wiki.libsdl.org/SDL_JoyButtonEvent|SDL_JoyButtonEvent]]</td>
856    <td>{{'joy-button-down}}<br>
857        {{'joy-button-up}}</td>
858  </tr>
859  <tr>
860    <td>[[#sdl2joy-device-event|sdl2:joy-device-event]]</td>
861    <td>[[https://wiki.libsdl.org/SDL_JoyDeviceEvent|SDL_JoyDeviceEvent]]</td>
862    <td>{{'joy-device-added}}<br>
863        {{'joy-device-removed}}</td>
864  </tr>
865  <tr>
866    <td>[[#sdl2joy-hat-event|sdl2:joy-hat-event]]</td>
867    <td>[[https://wiki.libsdl.org/SDL_JoyHatEvent|SDL_JoyHatEvent]]</td>
868    <td>{{'joy-hat-motion}}</td>
869  </tr>
870  <tr>
871    <td>[[#sdl2keyboard-event|sdl2:keyboard-event]]</td>
872    <td>[[https://wiki.libsdl.org/SDL_KeyboardEvent|SDL_KeyboardEvent]]</td>
873    <td>{{'key-down}}<br>
874        {{'key-up}}</td>
875  </tr>
876  <tr>
877    <td>[[#sdl2mouse-button-event|sdl2:mouse-button-event]]</td>
878    <td>[[https://wiki.libsdl.org/SDL_MouseButtonEvent|SDL_MouseButtonEvent]]</td>
879    <td>{{'mouse-button-down}}<br>
880        {{'mouse-button-up}}</td>
881  </tr>
882  <tr>
883    <td>[[#sdl2mouse-motion-event|sdl2:mouse-motion-event]]</td>
884    <td>[[https://wiki.libsdl.org/SDL_MouseMotionEvent|SDL_MouseMotionEvent]]</td>
885    <td>{{'mouse-motion}}</td>
886  </tr>
887  <tr>
888    <td>[[#sdl2mouse-wheel-event|sdl2:mouse-wheel-event]]</td>
889    <td>[[https://wiki.libsdl.org/SDL_MouseWheelEvent|SDL_MouseWheelEvent]]</td>
890    <td>{{'mouse-wheel}}</td>
891  </tr>
892  <tr>
893    <td>[[#sdl2multi-gesture-event|sdl2:multi-gesture-event]]</td>
894    <td>[[https://wiki.libsdl.org/SDL_MultiGestureEvent|SDL_MultiGestureEvent]]</td>
895    <td>{{'multi-gesture}}</td>
896  </tr>
897  <tr>
898    <td>[[#sdl2quit-event|sdl2:quit-event]]</td>
899    <td>[[https://wiki.libsdl.org/SDL_QuitEvent|SDL_QuitEvent]]</td>
900    <td>{{'quit}}</td>
901  </tr>
902  <tr>
903    <td>[[#sdl2sys-wm-event|sdl2:sys-wm-event]]</td>
904    <td>[[https://wiki.libsdl.org/SDL_SysWMEvent|SDL_SysWMEvent]]</td>
905    <td>{{'sys-wm}}</td>
906  </tr>
907  <tr>
908    <td>[[#sdl2text-editing-event|sdl2:text-editing-event]]</td>
909    <td>[[https://wiki.libsdl.org/SDL_TextEditingEvent|SDL_TextEditingEvent]]</td>
910    <td>{{'text-editing}}</td>
911  </tr>
912  <tr>
913    <td>[[#sdl2text-input-event|sdl2:text-input-event]]</td>
914    <td>[[https://wiki.libsdl.org/SDL_TextInputEvent|SDL_TextInputEvent]]</td>
915    <td>{{'text-input}}</td>
916  </tr>
917  <tr>
918    <td>[[#sdl2touch-finger-event|sdl2:touch-finger-event]]</td>
919    <td>[[https://wiki.libsdl.org/SDL_TouchFingerEvent|SDL_TouchFingerEvent]]</td>
920    <td>{{'finger-down}}<br>
921        {{'finger-up}}<br>
922        {{'finger-motion}}</td>
923  </tr>
924  <tr>
925    <td>[[#sdl2user-event|sdl2:user-event]]</td>
926    <td>[[https://wiki.libsdl.org/SDL_UserEvent|SDL_UserEvent]]</td>
927    <td>(Call {{register-events!}} to register your own user event type symbols.)</td>
928  </tr>
929  <tr>
930    <td>[[#sdl2window-event|sdl2:window-event]]</td>
931    <td>[[https://wiki.libsdl.org/SDL_WindowEvent|SDL_WindowEvent]]</td>
932    <td>{{'window}}</td>
933  </tr>
934</table>
935
936
937
938<procedure>(event? obj) → boolean</procedure>
939
940Returns #t if {{obj}} is any variant of sdl2:event.
941
942
943<procedure>(make-event #!optional type) → sdl2:event</procedure>
944<procedure>(make-event* #!optional type) → sdl2:event</procedure>
945
946Allocate and set the type of a new sdl2:event.
947
948{{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.
949
950* {{make-event}} returns a managed sdl2:event.
951* {{make-event*}} returns an unmanaged sdl2:event, which must be freed with {{free-event!}} when you are done with it.
952
953
954<procedure>(free-event! event)</procedure>
955
956Free the memory of the sdl2:event's underlying struct. You can call
957this procedure with any variant of sdl2:event. {{event}}'s pointer
958will be set to null (see {{struct-null?}}). It is safe to call this
959procedure with managed or unmanaged sdl2:events. It is safe (but has
960no effect) to free a struct record multiple times.
961
962
963<procedure>(event-type event) → symbol</procedure>
964<procedure>(event-type-raw event) → integer</procedure>
965<setter>(set! (event-type event) val)</setter>
966<setter>(event-type-set! event val)</setter>
967
968Get or set the sdl2:event's "type" field.
969You can use these procedures with any variant of sdl2:event.
970Setting this will change what variant of sdl2:event it is.
971E.g. if you set it to {{'key-down}}, the event will become an sdl2:keyboard-event.
972
973* {{event-type}} returns an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbol]].
974* {{event-type-raw}} returns an integer.
975* The setters accept either a symbol or an integer.
976
977
978<procedure>(event-timestamp event) → integer</procedure>
979<setter>(set! (event-timestamp event) val)</setter>
980<setter>(event-timestamp-set! event val)</setter>
981
982Get 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.
983You can use these procedures with any variant of sdl2:event.
984
985
986
987==== sdl2:controller-axis-event
988
989sdl2:controller-axis-event is a variant of sdl2:event that wraps a pointer to an
990[[https://wiki.libsdl.org/SDL_ControllerAxisEvent|SDL_ControllerAxisEvent]].
991
992This event variant occurs when an axis on a controller moves.
993There may be more than one controller, and each controller may have more than one axis.
994You can distinguish them using the {{which}} and {{axis}} fields.
995
996sdl2:controller-axis-event has the following event type symbols:
997
998; {{'controller-axis-motion}} : An axis on a controller moved.
999
1000
1001<procedure>(controller-axis-event? obj) → boolean</procedure>
1002
1003Returns #t if {{obj}} is an sdl2:controller-axis-event.
1004
1005
1006<procedure>(controller-axis-event-which event) → integer</procedure>
1007<setter>(set! (controller-axis-event-which event) val)</setter>
1008<setter>(controller-axis-event-which-set! event val)</setter>
1009
1010Get or set the event's "which" field, as an integer indicating the device index of the controller (joystick) that the event is related to.
1011
1012
1013<procedure>(controller-axis-event-axis event) → integer</procedure>
1014<setter>(set! (controller-axis-event-axis event) val)</setter>
1015<setter>(controller-axis-event-axis-set! event val)</setter>
1016
1017Get or set the event's "axis" field, as an integer indicating the axis that the event is related to.
1018E.g. 0 indicates the first axis on the controller.
1019
1020
1021<procedure>(controller-axis-event-value event) → integer</procedure>
1022<setter>(set! (controller-axis-event-value event) val)</setter>
1023<setter>(controller-axis-event-value-set! event val)</setter>
1024
1025Get or set the event's "value" field, as an integer in the range -32768 to 32767 (inclusive), indicating the new value of the axis.
1026
1027
1028
1029==== sdl2:controller-button-event
1030
1031sdl2:controller-button-event is a variant of sdl2:event that wraps a pointer to an
1032[[https://wiki.libsdl.org/SDL_ControllerButtonEvent|SDL_ControllerButtonEvent]].
1033
1034This event variant occurs when a button on a controller is pressed or released.
1035There may be more than one controller, and each controller may have more than one button.
1036You can distinguish them using the {{which}} and {{button}} fields.
1037
1038sdl2:controller-button-event has the following event type symbols:
1039
1040; {{'controller-button-down}} : A button on a controller was pressed.
1041; {{'controller-button-up}} : A button on a controller was released.
1042
1043<procedure>(controller-button-event? obj) → boolean</procedure>
1044
1045Returns #t if {{obj}} is an sdl2:controller-button-event.
1046
1047
1048<procedure>(controller-button-event-which event) → integer</procedure>
1049<setter>(set! (controller-button-event-which event) val)</setter>
1050<setter>(controller-button-event-which-set! event val)</setter>
1051
1052Get or set the event's "which" field, as an integer indicating the device index of the controller (joystick) that the event is related to.
1053
1054
1055<procedure>(controller-button-event-button event) → integer</procedure>
1056<setter>(set! (controller-button-event-button event) val)</setter>
1057<setter>(controller-button-event-button-set! event val)</setter>
1058
1059Get or set the event's "button" field, as an integer indicating the button that the event is related to.
1060E.g. 0 indicates the first button on the controller.
1061
1062
1063<procedure>(controller-button-event-state event) → boolean</procedure>
1064<setter>(set! (controller-button-event-state event) val)</setter>
1065<setter>(controller-button-event-state-set! event val)</setter>
1066
1067Get or set the event's "state" field, as a boolean indicating whether the button was pressed (#t) or released (#f).
1068You can also find out by checking the event type: {{'controller-button-down}} for pressed, or {{'controller-button-up}} for released.
1069
1070
1071
1072==== sdl2:controller-device-event
1073
1074sdl2:controller-device-event is a variant of sdl2:event that wraps a pointer to an
1075[[https://wiki.libsdl.org/SDL_ControllerDeviceEvent|SDL_ControllerDeviceEvent]].
1076
1077This event variant occurs when a controller is added, removed, or remapped.
1078There may be more than one controller.
1079You can distinguish them using the {{which}}.
1080
1081sdl2:controller-device-event has the following event type symbols:
1082
1083; {{'controller-device-added}} : A controller device was added.
1084; {{'controller-device-removed}} : A controller device was removed.
1085; {{'controller-device-remapped}} : A controller device was remapped.
1086
1087<procedure>(controller-device-event? obj) → boolean</procedure>
1088
1089Returns #t if {{obj}} is an sdl2:controller-device-event.
1090
1091
1092<procedure>(controller-device-event-which event) → integer</procedure>
1093<setter>(set! (controller-device-event-which event) val)</setter>
1094<setter>(controller-device-event-which-set! event val)</setter>
1095
1096Get or set the event's "which" field, as an integer indicating the device index of the controller (joystick) that the event is related to.
1097
1098
1099
1100==== sdl2:dollar-gesture-event
1101
1102sdl2:dollar-gesture-event is a variant of sdl2:event that wraps a pointer to an
1103[[https://wiki.libsdl.org/SDL_DollarGestureEvent|SDL_DollarGestureEvent]].
1104
1105This event variant occurs when a [[http://depts.washington.edu/aimgroup/proj/dollar/index.html|"$1 unistroke" gesture]] is performed or recorded.
1106
1107sdl2:dollar-gesture-event has the following event type symbols:
1108
1109; {{'dollar-gesture}} : A dollar gesture was performed.
1110; {{'dollar-record}} : A dollar gesture was recorded.
1111
1112
1113<procedure>(dollar-gesture-event? obj) → boolean</procedure>
1114
1115Returns #t if {{obj}} is an sdl2:dollar-gesture-event.
1116
1117
1118<procedure>(dollar-gesture-event-touch-id event) → integer</procedure>
1119<setter>(set! (dollar-gesture-event-touch-id event) val)</setter>
1120<setter>(dollar-gesture-event-touch-id-set! event val)</setter>
1121
1122Get or set the event's "touch-id" field, as an integer indicating the ID number of the touch device this event is related to.
1123
1124
1125<procedure>(dollar-gesture-event-gesture-id event) → integer</procedure>
1126<setter>(set! (dollar-gesture-event-gesture-id event) val)</setter>
1127<setter>(dollar-gesture-event-gesture-id-set! event val)</setter>
1128
1129Get or set the event's "gesture-id" field, as an integer indicating the ID number of the closest gesture to the performed stroke.
1130
1131
1132<procedure>(dollar-gesture-event-num-fingers event) → integer</procedure>
1133<setter>(set! (dollar-gesture-event-num-fingers event) val)</setter>
1134<setter>(dollar-gesture-event-num-fingers-set! event val)</setter>
1135
1136Get or set the event's "num-fingers" field, as an integer indicating the number of fingers used to draw the stroke.
1137
1138
1139<procedure>(dollar-gesture-event-error event) → float</procedure>
1140<setter>(set! (dollar-gesture-event-error event) val)</setter>
1141<setter>(dollar-gesture-event-error-set! event val)</setter>
1142
1143Get 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.
1144
1145
1146<procedure>(dollar-gesture-event-x event) → float</procedure>
1147<setter>(set! (dollar-gesture-event-x event) val)</setter>
1148<setter>(dollar-gesture-event-x-set! event val)</setter>
1149
1150Get 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.
1151
1152
1153<procedure>(dollar-gesture-event-y event) → float</procedure>
1154<setter>(set! (dollar-gesture-event-y event) val)</setter>
1155<setter>(dollar-gesture-event-y-set! event val)</setter>
1156
1157Get 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.
1158
1159
1160
1161==== sdl2:drop-event
1162
1163sdl2:drop-event is a variant of sdl2:event that wraps a pointer to an
1164[[https://wiki.libsdl.org/SDL_DropEvent|SDL_DropEvent]].
1165
1166This event variant occurs when the user requests that the program open a file,
1167e.g. by dragging and dropping a file icon onto the program.
1168
1169sdl2:drop-event has the following event type symbols:
1170
1171; {{'drop-file}} : The user requested that a file be opened.
1172
1173
1174<procedure>(drop-event? obj) → boolean</procedure>
1175
1176Returns #t if {{obj}} is an sdl2:drop-event.
1177
1178
1179<procedure>(drop-event-file event) → string</procedure>
1180<setter>(set! (drop-event-file event) val)</setter>
1181<setter>(drop-event-file-set! event val)</setter>
1182
1183Get or set the event's "file" field, as a string indicating the path to a file that the user requested to be opened.
1184
1185
1186
1187==== sdl2:joy-axis-event
1188
1189sdl2:joy-axis-event is a variant of sdl2:event that wraps a pointer to an
1190[[https://wiki.libsdl.org/SDL_JoyAxisEvent|SDL_JoyAxisEvent]].
1191
1192This event variant occurs when an axis on a joystick moves.
1193There may be more than one joystick, and each joystick may have more than one axis.
1194You can distinguish them using the {{which}} and {{axis}} fields.
1195
1196sdl2:joy-axis-event has the following event type symbols:
1197
1198; {{'joy-axis-motion}} : An axis on a joystick moved.
1199
1200
1201<procedure>(joy-axis-event? obj) → boolean</procedure>
1202
1203Returns #t if {{obj}} is an sdl2:joy-axis-event.
1204
1205
1206<procedure>(joy-axis-event-which event) → integer</procedure>
1207<setter>(set! (joy-axis-event-which event) val)</setter>
1208<setter>(joy-axis-event-which-set! event val)</setter>
1209
1210Get or set the event's "which" field, as an integer indicating the device index of the joystick that the event is related to.
1211
1212
1213<procedure>(joy-axis-event-axis event) → integer</procedure>
1214<setter>(set! (joy-axis-event-axis event) val)</setter>
1215<setter>(joy-axis-event-axis-set! event val)</setter>
1216
1217Get or set the event's "axis" field, as an integer indicating the axis that the event is related to.
1218E.g. 0 indicates the first axis on the joystick.
1219
1220
1221<procedure>(joy-axis-event-value event) → integer</procedure>
1222<setter>(set! (joy-axis-event-value event) val)</setter>
1223<setter>(joy-axis-event-value-set! event val)</setter>
1224
1225Get or set the event's "value" field, as an integer in the range -32768 to 32767 (inclusive), indicating the new value of the axis.
1226
1227
1228
1229==== sdl2:joy-ball-event
1230
1231sdl2:joy-ball-event is a variant of sdl2:event that wraps a pointer to an
1232[[https://wiki.libsdl.org/SDL_JoyBallEvent|SDL_JoyBallEvent]].
1233
1234This event variant occurs when a trackball on a joystick moves.
1235There may be more than one joystick, and each joystick may have more than one trackball.
1236You can distinguish them using the {{which}} and {{ball}} fields.
1237
1238sdl2:joy-ball-event has the following event type symbols:
1239
1240; {{'joy-ball-motion}} : A trackball on a joystick moved.
1241
1242
1243<procedure>(joy-ball-event? obj) → boolean</procedure>
1244
1245Returns #t if {{obj}} is an sdl2:joy-ball-event.
1246
1247
1248<procedure>(joy-ball-event-which event) → integer</procedure>
1249<setter>(set! (joy-ball-event-which event) val)</setter>
1250<setter>(joy-ball-event-which-set! event val)</setter>
1251
1252Get or set the event's "which" field, as an integer indicating the device index of the joystick that the event is related to.
1253
1254
1255<procedure>(joy-ball-event-ball event) → integer</procedure>
1256<setter>(set! (joy-ball-event-ball event) val)</setter>
1257<setter>(joy-ball-event-ball-set! event val)</setter>
1258
1259Get 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.
1260
1261
1262<procedure>(joy-ball-event-xrel event) → integer</procedure>
1263<setter>(set! (joy-ball-event-xrel event) val)</setter>
1264<setter>(joy-ball-event-xrel-set! event val)</setter>
1265
1266Get 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.
1267
1268
1269<procedure>(joy-ball-event-yrel event) → integer</procedure>
1270<setter>(set! (joy-ball-event-yrel event) val)</setter>
1271<setter>(joy-ball-event-yrel-set! event val)</setter>
1272
1273Get 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.
1274
1275
1276
1277==== sdl2:joy-button-event
1278
1279sdl2:joy-button-event is a variant of sdl2:event that wraps a pointer to an
1280[[https://wiki.libsdl.org/SDL_JoyButtonEvent|SDL_JoyButtonEvent]].
1281
1282This event variant occurs when a button on a joystick is pressed or released.
1283There may be more than one joystick, and each joystick may have more than one button.
1284You can distinguish them using the {{which}} and {{button}} fields.
1285
1286sdl2:joy-button-event has the following event type symbols:
1287
1288; {{'joy-button-down}} : A button on a joystick was pressed.
1289; {{'joy-button-up}} : A button on a joystick was released.
1290
1291
1292<procedure>(joy-button-event? obj) → boolean</procedure>
1293
1294Returns #t if {{obj}} is an sdl2:joy-button-event.
1295
1296
1297<procedure>(joy-button-event-which event) → integer</procedure>
1298<setter>(set! (joy-button-event-which event) val)</setter>
1299<setter>(joy-button-event-which-set! event val)</setter>
1300
1301Get or set the event's "which" field, as an integer indicating the device index of the joystick that the event is related to.
1302
1303
1304<procedure>(joy-button-event-button event) → integer</procedure>
1305<setter>(set! (joy-button-event-button event) val)</setter>
1306<setter>(joy-button-event-button-set! event val)</setter>
1307
1308Get or set the event's "button" field, as an integer indicating the button that the event is related to.
1309E.g. 0 indicates the first button on the joystick.
1310
1311
1312<procedure>(joy-button-event-state event) → boolean</procedure>
1313<setter>(set! (joy-button-event-state event) val)</setter>
1314<setter>(joy-button-event-state-set! event val)</setter>
1315
1316Get or set the value of the event's "state" field, as a boolean indicating whether the button was pressed (#t) or released (#f).
1317You can also find out by checking the event type: {{'joy-button-down}} for pressed, or {{'joy-button-up}} for released.
1318
1319
1320
1321==== sdl2:joy-device-event
1322
1323sdl2:joy-device-event is a variant of sdl2:event that wraps a pointer to an
1324[[https://wiki.libsdl.org/SDL_JoyDeviceEvent|SDL_JoyDeviceEvent]].
1325
1326This event variant occurs when a joystick device is added or removed.
1327There may be more than one joystick.
1328You can distinguish them using the {{which}} field.
1329
1330sdl2:joy-device-event has the following event type symbols:
1331
1332; {{'joy-device-added}} : A joystick device was added.
1333; {{'joy-device-removed}} : A joystick device was removed.
1334
1335
1336<procedure>(joy-device-event? obj) → boolean</procedure>
1337
1338Returns #t if {{obj}} is an sdl2:joy-device-event.
1339
1340
1341<procedure>(joy-device-event-which event) → integer</procedure>
1342<setter>(set! (joy-device-event-which event) val)</setter>
1343<setter>(joy-device-event-which-set! event val)</setter>
1344
1345Get or set the event's "which" field, as an integer indicating the device index of the joystick that the event is related to.
1346
1347
1348
1349==== sdl2:joy-hat-event
1350
1351sdl2:joy-hat-event is a variant of sdl2:event that wraps a pointer to an
1352[[https://wiki.libsdl.org/SDL_JoyHatEvent|SDL_JoyHatEvent]].
1353
1354This event variant occurs when an 8-directional hat switch on a joystick moves.
1355There may be more than one joystick, and each joystick may have more than one hat switch.
1356You can distinguish them using the {{which}} and {{hat}} fields.
1357
1358sdl2:joy-hat-event has the following event type symbols:
1359
1360; {{'joy-hat-motion}} : A hat switch on a joystick moved.
1361
1362
1363<procedure>(joy-hat-event? obj) → boolean</procedure>
1364
1365Returns #t if {{obj}} is an sdl2:joy-hat-event.
1366
1367
1368<procedure>(joy-hat-event-which event) → integer</procedure>
1369<setter>(set! (joy-hat-event-which event) val)</setter>
1370<setter>(joy-hat-event-which-set! event val)</setter>
1371
1372Get or set the event's "which" field, as an integer indicating the device index of the joystick that the event is related to.
1373
1374
1375<procedure>(joy-hat-event-hat event) → integer</procedure>
1376<setter>(set! (joy-hat-event-hat event) val)</setter>
1377<setter>(joy-hat-event-hat-set! event val)</setter>
1378
1379Get or set the event's "hat" field, as an integer indicating the hat switch that the event is related to.
1380E.g. 0 indicates the first hat switch on the joystick.
1381
1382
1383<procedure>(joy-hat-event-value event) → symbol</procedure>
1384<procedure>(joy-hat-event-value-raw event) → integer</procedure>
1385<setter>(set! (joy-hat-event-value event) val)</setter>
1386<setter>(joy-hat-event-value-set! event val)</setter>
1387
1388Get or set the event's "value" field, indicating the new position of the hat switch.
1389
1390* {{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]].
1391* {{joy-hat-event-value-raw}} returns an integer.
1392* The setters accept either a symbol or an integer.
1393
1394
1395==== sdl2:keyboard-event
1396
1397sdl2:keyboard-event is a variant of sdl2:event that wraps a pointer to an
1398[[https://wiki.libsdl.org/SDL_KeyboardEvent|SDL_KeyboardEvent]].
1399
1400This event variant occurs when a keyboard key is pressed or released.
1401
1402sdl2:keyboard-event has the following event type symbols:
1403
1404; {{'key-down}} : A keyboard key was pressed.
1405; {{'key-up}} : A keyboard key was released.
1406
1407
1408<procedure>(keyboard-event? obj) → boolean</procedure>
1409
1410Returns #t if {{obj}} is an sdl2:keyboard-event.
1411
1412
1413<procedure>(keyboard-event-window-id event) → integer</procedure>
1414<setter>(set! (keyboard-event-window-id event) val)</setter>
1415<setter>(keyboard-event-window-id-set! event val)</setter>
1416
1417Get 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.
1418
1419
1420<procedure>(keyboard-event-state event) → boolean</procedure>
1421<setter>(set! (keyboard-event-state event) val)</setter>
1422<setter>(keyboard-event-state-set! event val)</setter>
1423
1424Get or set the event's "state" field, as a boolean indicating whether the key was pressed (#t) or released (#f).
1425You can also find out by checking the event type: {{'key-down}} for pressed, or {{'key-up}} for released.
1426
1427
1428<procedure>(keyboard-event-repeat event) → integer</procedure>
1429<setter>(set! (keyboard-event-repeat event) val)</setter>
1430<setter>(keyboard-event-repeat-set! event val)</setter>
1431
1432Get or set the event's "repeat" field, as a integer.
1433Non-zero indicates that this is a key repeat, caused by the user pressing and holding the key for some time.
1434Zero indicates this is not a key repeat.
1435
1436
1437<procedure>(keyboard-event-keysym event) → sdl2:keysym</procedure>
1438<setter>(set! (keyboard-event-keysym event) val)</setter>
1439<setter>(keyboard-event-keysym-set! event val)</setter>
1440
1441Get or set the event's "keysym" field, as an sdl2:keysym indicating the key that was pressed or released.
1442The getter returns a copy of the sdl2:keysym stored in the event.
1443Modifying the returned sdl2:keysym will ''not'' modify the event, but setting this field to a sdl2:keysym ''will'' modify the event.
1444
1445Instead of using this procedure, it is more efficient and convenient to directly access the fields of the event's sdl2:keysym, using these procedures:
1446
1447* {{keyboard-event-scancode}}
1448* {{keyboard-event-sym}}
1449* {{keyboard-event-mod}}
1450
1451
1452<procedure>(keyboard-event-scancode event) → symbol</procedure>
1453<procedure>(keyboard-event-scancode-raw event) → integer</procedure>
1454<setter>(set! (keyboard-event-scancode event) val)</setter>
1455<setter>(keyboard-event-scancode-set! event val)</setter>
1456
1457Get or set the "scancode" field of the event's "keysym" field, indicating the physical key that was pressed or released.
1458Setting this will modify the event.
1459
1460* {{keyboard-event-scancode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]].
1461* {{keyboard-event-scancode-raw}} returns an integer.
1462* The setters accept either a symbol or an integer.
1463
1464
1465<procedure>(keyboard-event-sym event) → symbol</procedure>
1466<procedure>(keyboard-event-sym-raw event) → integer</procedure>
1467<setter>(set! (keyboard-event-sym event) val)</setter>
1468<setter>(keyboard-event-sym-set! event val)</setter>
1469
1470Get or set the "sym" field of the event's "keysym" field, indicating the logical key that was pressed or released.
1471Setting this will modify the event.
1472
1473* {{keyboard-event-sym}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]]
1474* {{keyboard-event-sym-raw}} returns an integer.
1475* The setters accept either a symbol or an integer.
1476
1477
1478<procedure>(keyboard-event-mod event) → list of symbols</procedure>
1479<procedure>(keyboard-event-mod-raw event) → integer</procedure>
1480<setter>(set! (keyboard-event-mod event) val)</setter>
1481<setter>(keyboard-event-mod-set! event val)</setter>
1482
1483Get 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.
1484Setting this will modify the event.
1485
1486* {{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]].
1487* {{keyboard-event-mod-raw}} returns an integer.
1488* The setters accept either a list of symbols or an integer.
1489
1490
1491
1492==== sdl2:mouse-button-event
1493
1494sdl2:mouse-button-event is a variant of sdl2:event that wraps a pointer to an
1495[[https://wiki.libsdl.org/SDL_MouseButtonEvent|SDL_MouseButtonEvent]].
1496
1497This event variant occurs when a mouse button was pressed or released.
1498
1499sdl2:mouse-button-event has the following event type symbols:
1500
1501; {{'mouse-button-down}} : A mouse button was pressed.
1502; {{'mouse-button-up}} : A mouse button was released.
1503
1504
1505<procedure>(mouse-button-event? obj) → boolean</procedure>
1506
1507Returns #t if {{obj}} is an sdl2:mouse-button-event.
1508
1509
1510<procedure>(mouse-button-event-window-id event) → integer</procedure>
1511<setter>(set! (mouse-button-event-window-id event) val)</setter>
1512<setter>(mouse-button-event-window-id-set! event val)</setter>
1513
1514Get 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.
1515
1516
1517<procedure>(mouse-button-event-which event) → integer</procedure>
1518<setter>(set! (mouse-button-event-which event) val)</setter>
1519<setter>(mouse-button-event-which-set! event val)</setter>
1520
1521Get or set the event's "which" field, as an integer indicating the mouse instance ID.
1522
1523
1524<procedure>(mouse-button-event-button event) → symbol</procedure>
1525<procedure>(mouse-button-event-button-raw event) → integer</procedure>
1526<setter>(set! (mouse-button-event-button event) val)</setter>
1527<setter>(mouse-button-event-button-set! event val)</setter>
1528
1529Get or set the event's "button" field, indicating the button that the event is related to.
1530
1531* {{mouse-button-event-button}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#mouse-buttons|mouse button symbol]]:
1532** {{'left}}
1533** {{'middle}}
1534** {{'right}}
1535** {{'x1}}
1536** {{'x2}}
1537* {{mouse-button-event-button-raw}} returns an integer.
1538* The setters accept either a symbol or an integer.
1539
1540
1541<procedure>(mouse-button-event-state event) → boolean</procedure>
1542<setter>(set! (mouse-button-event-state event) val)</setter>
1543<setter>(mouse-button-event-state-set! event val)</setter>
1544
1545Get or set the event's "state" field, as a boolean indicating whether the button was pressed (#t) or released (#f).
1546You can also find out by checking the event type: {{'mouse-button-down}} for pressed, or {{'mouse-button-up}} for released.
1547
1548
1549<procedure>(mouse-button-event-x event) → integer</procedure>
1550<setter>(set! (mouse-button-event-x event) val)</setter>
1551<setter>(mouse-button-event-x-set! event val)</setter>
1552
1553Get 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.
1554
1555
1556<procedure>(mouse-button-event-y event) → integer</procedure>
1557<setter>(set! (mouse-button-event-y event) val)</setter>
1558<setter>(mouse-button-event-y-set! event val)</setter>
1559
1560Get 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.
1561
1562
1563
1564==== sdl2:mouse-motion-event
1565
1566sdl2:mouse-motion-event is a variant of sdl2:event that wraps a pointer to an
1567[[https://wiki.libsdl.org/SDL_MouseMotionEvent|SDL_MouseMotionEvent]].
1568
1569This event variant occurs when the mouse cursor moves.
1570
1571sdl2:mouse-motion-event has the following event type symbols:
1572
1573; {{'mouse-motion}} : The mouse cursor moved.
1574
1575
1576<procedure>(mouse-motion-event? obj) → boolean</procedure>
1577
1578Returns #t if {{obj}} is an sdl2:mouse-motion-event.
1579
1580
1581<procedure>(mouse-motion-event-window-id event) → integer</procedure>
1582<setter>(set! (mouse-motion-event-window-id event) val)</setter>
1583<setter>(mouse-motion-event-window-id-set! event val)</setter>
1584
1585Get 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.
1586
1587
1588<procedure>(mouse-motion-event-which event) → integer</procedure>
1589<setter>(set! (mouse-motion-event-which event) val)</setter>
1590<setter>(mouse-motion-event-which-set! event val)</setter>
1591
1592Get or set the event's "which" field, as an integer indicating the mouse instance ID.
1593
1594
1595<procedure>(mouse-motion-event-state event) → list of symbols</procedure>
1596<procedure>(mouse-motion-event-state-raw event) → integer</procedure>
1597<setter>(set! (mouse-motion-event-state event) val)</setter>
1598<setter>(mouse-motion-event-state-set! event val)</setter>
1599
1600Get or set the event's "state" field, indicating the mouse buttons that were being pressed at the time this event occurred.
1601
1602* {{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]]:
1603** {{'left}}
1604** {{'middle}}
1605** {{'right}}
1606** {{'x1}}
1607** {{'x2}}
1608* {{mouse-motion-event-state-raw}} returns an integer.
1609* The setters accept either a list of zero or more symbols, or an integer.
1610
1611
1612<procedure>(mouse-motion-event-x event) → integer</procedure>
1613<setter>(set! (mouse-motion-event-x event) val)</setter>
1614<setter>(mouse-motion-event-x-set! event val)</setter>
1615
1616Get 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.
1617
1618
1619<procedure>(mouse-motion-event-y event) → integer</procedure>
1620<setter>(set! (mouse-motion-event-y event) val)</setter>
1621<setter>(mouse-motion-event-y-set! event val)</setter>
1622
1623Get 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.
1624
1625
1626<procedure>(mouse-motion-event-xrel event) → integer</procedure>
1627<setter>(set! (mouse-motion-event-xrel event) val)</setter>
1628<setter>(mouse-motion-event-xrel-set! event val)</setter>
1629
1630Get 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.
1631
1632
1633<procedure>(mouse-motion-event-yrel event) → integer</procedure>
1634<setter>(set! (mouse-motion-event-yrel event) val)</setter>
1635<setter>(mouse-motion-event-yrel-set! event val)</setter>
1636
1637Get 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.
1638
1639
1640
1641==== sdl2:mouse-wheel-event
1642
1643sdl2:mouse-wheel-event is a variant of sdl2:event that wraps a pointer to an
1644[[https://wiki.libsdl.org/SDL_MouseWheelEvent|SDL_MouseWheelEvent]].
1645
1646This event variant occurs when a mouse wheel moves.
1647
1648sdl2:mouse-wheel-event has the following event type symbols:
1649
1650; {{'mouse-wheel}} : A mouse wheel moved.
1651
1652
1653<procedure>(mouse-wheel-event? obj) → boolean</procedure>
1654
1655Returns #t if {{obj}} is an sdl2:mouse-wheel-event.
1656
1657
1658<procedure>(mouse-wheel-event-window-id event) → integer</procedure>
1659<setter>(set! (mouse-wheel-event-window-id event) val)</setter>
1660<setter>(mouse-wheel-event-window-id-set! event val)</setter>
1661
1662Get 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.
1663
1664
1665<procedure>(mouse-wheel-event-which event) → integer</procedure>
1666<setter>(set! (mouse-wheel-event-which event) val)</setter>
1667<setter>(mouse-wheel-event-which-set! event val)</setter>
1668
1669Get or set the event's "which" field, as an integer indicating the mouse instance ID.
1670
1671
1672<procedure>(mouse-wheel-event-x event) → integer</procedure>
1673<setter>(set! (mouse-wheel-event-x event) val)</setter>
1674<setter>(mouse-wheel-event-x-set! event val)</setter>
1675
1676Get or set the event's "x" field, as an integer (possibly negative) indicating the amount the wheel scrolled horizontally.
1677Positive numbers normally indicate scrolling to the right,
1678negative numbers indicate scrolling to the left.
1679But if the "direction" field is set to {{'flipped}} in SDL 2.0.4 or higher,
1680the meaning of this field is reversed.
1681
1682
1683<procedure>(mouse-wheel-event-y event) → integer</procedure>
1684<setter>(set! (mouse-wheel-event-y event) val)</setter>
1685<setter>(mouse-wheel-event-y-set! event val)</setter>
1686
1687Get or set the event's "y" field, as an integer (possibly negative) indicating the amount the wheel scrolled vertically.
1688Positive numbers normally indicate scrolling away from the user,
1689negative numbers indicate scrolling toward the user.
1690But if the "direction" field is set to {{'flipped}} in SDL 2.0.4 or higher,
1691the meaning of this field is reversed.
1692
1693
1694<procedure>(mouse-wheel-event-direction event) → symbol</procedure>
1695<setter>(set! (mouse-wheel-event-direction event) val)</setter>
1696<setter>(mouse-wheel-event-direction-set! event val)</setter>
1697
1698Get or set the event's "direction" field, as one of the following symbols:
1699
1700; {{'normal}} : "Normal" scrolling mode.
1701; {{'flipped}} : "Flipped" or "natural" scrolling mode. You can multiple the "x" and "y" field values by -1 to get the "normal" values.
1702
1703This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
1704It requires '''SDL 2.0.4 or higher'''.
1705It signals an error if the compiled version of SDL is not high enough.
1706Use the [[#version-feature-identifiers|{{libSDL-2.0.4+}} feature identifier]]
1707to check before calling this procedure.
1708
1709
1710==== sdl2:multi-gesture-event
1711
1712sdl2:multi-gesture-event is a variant of sdl2:event that wraps a pointer to an
1713[[https://wiki.libsdl.org/SDL_MultiGestureEvent|SDL_MultiGestureEvent]].
1714
1715This event variant occurs when a multi-finger gesture is performed on a touch device.
1716This is useful for recognizing common gestures that involve multiple fingers, e.g. pinching or rotating.
1717
1718sdl2:multi-gesture-event has the following event type symbols:
1719
1720; {{'multi-gesture}} : A multi-finger gesture was performed.
1721
1722
1723<procedure>(multi-gesture-event? obj) → boolean</procedure>
1724
1725Returns #t if {{obj}} is an sdl2:multi-gesture-event.
1726
1727
1728<procedure>(multi-gesture-event-touch-id event) → integer</procedure>
1729<setter>(set! (multi-gesture-event-touch-id event) val)</setter>
1730<setter>(multi-gesture-event-touch-id-set! event val)</setter>
1731
1732Get or set the event's "touch-id" field, as an integer indicating the ID number of the touch device this event is related to.
1733
1734
1735<procedure>(multi-gesture-event-dtheta event) → float</procedure>
1736<setter>(set! (multi-gesture-event-dtheta event) val)</setter>
1737<setter>(multi-gesture-event-dtheta-set! event val)</setter>
1738
1739Get or set the event's "dtheta" field, as a float indicating the amount that the fingers rotated during this motion.
1740
1741
1742<procedure>(multi-gesture-event-ddist event) → float</procedure>
1743<setter>(set! (multi-gesture-event-ddist event) val)</setter>
1744<setter>(multi-gesture-event-ddist-set! event val)</setter>
1745
1746Get or set the event's "ddist" field, as a float indicating the amount that the fingers pinched during this motion.
1747
1748
1749<procedure>(multi-gesture-event-x event) → float</procedure>
1750<setter>(set! (multi-gesture-event-x event) val)</setter>
1751<setter>(multi-gesture-event-x-set! event val)</setter>
1752
1753Get or set the event's "x" field, as a float indicating the normalized X coordinate of the center of the gesture.
1754
1755
1756<procedure>(multi-gesture-event-y event) → float</procedure>
1757<setter>(set! (multi-gesture-event-y event) val)</setter>
1758<setter>(multi-gesture-event-y-set! event val)</setter>
1759
1760Get or set the event's "y" field, as a float indicating the normalized Y coordinate of the center of the gesture.
1761
1762
1763<procedure>(multi-gesture-event-num-fingers event) → integer</procedure>
1764<setter>(set! (multi-gesture-event-num-fingers event) val)</setter>
1765<setter>(multi-gesture-event-num-fingers-set! event val)</setter>
1766
1767Get or set the event's "num-fingers" field, as an integer indicating the number of fingers used in the gesture.
1768
1769
1770
1771==== sdl2:quit-event
1772
1773sdl2:quit-event is a variant of sdl2:event that wraps a pointer to an
1774[[https://wiki.libsdl.org/SDL_QuitEvent|SDL_QuitEvent]].
1775
1776This event variant occurs when the user requests to quit the program.
1777There are [[https://wiki.libsdl.org/SDL_EventType#SDL_QUIT|various ways this might happen]], depending on the platform.
1778
1779sdl2:quit-event has the following event type symbols:
1780
1781; {{'quit}} : The user requested to quit the program.
1782
1783
1784<procedure>(quit-event? obj) → boolean</procedure>
1785
1786Returns #t if {{obj}} is an sdl2:quit-event.
1787
1788
1789
1790==== sdl2:sys-wm-event
1791
1792sdl2:sys-wm-event is a variant of sdl2:event that wraps a pointer to an
1793[[https://wiki.libsdl.org/SDL_SysWMEvent|SDL_SysWMEvent]].
1794
1795This event variant is for very advanced use cases. Most people can ignore it.
1796
1797sdl2:sys-wm-event has the following event type symbols:
1798
1799; {{'sys-wm}} : A platform-specific event occurred.
1800
1801
1802<procedure>(sys-wm-event? obj) → boolean</procedure>
1803
1804Returns #t if {{obj}} is an sdl2:sys-wm-event.
1805
1806
1807<procedure>(sys-wm-event-msg-raw event) → pointer</procedure>
1808<setter>(set! (sys-wm-event-msg-raw event) val)</setter>
1809<setter>(sys-wm-event-msg-raw-set! event val)</setter>
1810
1811Get 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.
1812This is for very advanced use cases. Most people can ignore it.
1813
1814
1815
1816==== sdl2:text-editing-event
1817
1818sdl2:text-editing-event is a variant of sdl2:event that wraps a pointer to an
1819[[https://wiki.libsdl.org/SDL_TextEditingEvent|SDL_TextEditingEvent]].
1820
1821This event occurs when a user is editing (composing) text, e.g. using an Input Method Editor (IME).
1822See the [[https://wiki.libsdl.org/Tutorials/TextInput|Text Input tutorial for SDL]].
1823
1824sdl2:text-editing-event has the following event type symbols:
1825
1826; {{'text-editing}} : The user editted some text being composed.
1827
1828
1829<procedure>(text-editing-event? obj) → boolean</procedure>
1830
1831Returns #t if {{obj}} is an sdl2:text-editing-event.
1832
1833
1834<procedure>(text-editing-event-window-id event) → integer</procedure>
1835<setter>(set! (text-editing-event-window-id event) val)</setter>
1836<setter>(text-editing-event-window-id-set! event val)</setter>
1837
1838Get 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.
1839
1840
1841<procedure>(text-editing-event-text event) → string</procedure>
1842<setter>(set! (text-editing-event-text event) val)</setter>
1843<setter>(text-editing-event-text-set! event val)</setter>
1844
1845Get 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.
1846
1847
1848<procedure>(text-editing-event-start event) → integer</procedure>
1849<setter>(set! (text-editing-event-start event) val)</setter>
1850<setter>(text-editing-event-start-set! event val)</setter>
1851
1852Get or set the event's "start" field, as an integer indicating the location to begin editing from.
1853
1854
1855<procedure>(text-editing-event-length event) → integer</procedure>
1856<setter>(set! (text-editing-event-length event) val)</setter>
1857<setter>(text-editing-event-length-set! event val)</setter>
1858
1859Get or set the event's "length" field, as an integer indicating the number of characters to edit from the start point.
1860
1861
1862
1863==== sdl2:text-input-event
1864
1865sdl2:text-input-event is a variant of sdl2:event that wraps a pointer to an
1866[[https://wiki.libsdl.org/SDL_TextInputEvent|SDL_TextInputEvent]].
1867
1868This event occurs when the users enters some text, possibly using an Input Metod Editor (IME).
1869See the [[https://wiki.libsdl.org/Tutorials/TextInput|Text Input tutorial for SDL]].
1870
1871sdl2:text-input-event has the following event type symbols:
1872
1873; {{'text-input}} : The use inputted some text.
1874
1875
1876<procedure>(text-input-event? obj) → boolean</procedure>
1877
1878Returns #t if {{obj}} is an sdl2:text-input-event.
1879
1880
1881<procedure>(text-input-event-window-id event) → integer</procedure>
1882<setter>(set! (text-input-event-window-id event) val)</setter>
1883<setter>(text-input-event-window-id-set! event val)</setter>
1884
1885Get 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.
1886
1887
1888<procedure>(text-input-event-text event) → string</procedure>
1889<setter>(set! (text-input-event-text event) val)</setter>
1890<setter>(text-input-event-text-set! event val)</setter>
1891
1892Get 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.
1893
1894
1895
1896==== sdl2:touch-finger-event
1897
1898sdl2:touch-finger-event is a variant of sdl2:event that wraps a pointer to an
1899[[https://wiki.libsdl.org/SDL_TouchFingerEvent|SDL_TouchFingerEvent]].
1900
1901This event variant occurs when the user presses, lifts, or moves a finger (or stylus, etc.) on a supported touch device,
1902e.g. the touch screen of a mobile phone or tablet device, or certain laptop trackpads.
1903There may be more than one finger touching at the same time;
1904you can distinguish the fingers by the {{finger-id}} number.
1905
1906sdl2:touch-finger-event has the following event type symbols:
1907
1908; {{'finger-down}} : A finger started touching a touch device (i.e. was pressed down).
1909; {{'finger-up}} : A finger stopped touching a touch device (i.e. was lifted up).
1910; {{'finger-motion}} : A finger moved while touching a touch device.
1911
1912
1913<procedure>(touch-finger-event? obj) → boolean</procedure>
1914
1915Returns #t if {{obj}} is an sdl2:touch-finger-event.
1916
1917
1918<procedure>(touch-finger-event-touch-id event) → integer</procedure>
1919<setter>(set! (touch-finger-event-touch-id event) val)</setter>
1920<setter>(touch-finger-event-touch-id-set! event val)</setter>
1921
1922Get or set the event's "touch-id" field, as an integer indicating the ID number of the touch device this event is related to.
1923
1924
1925<procedure>(touch-finger-event-finger-id event) → integer</procedure>
1926<setter>(set! (touch-finger-event-finger-id event) val)</setter>
1927<setter>(touch-finger-event-finger-id-set! event val)</setter>
1928
1929Get or set the event's "finger-id" field, as an integer indicating the ID number of the finger this event is related to.
1930
1931
1932<procedure>(touch-finger-event-x event) → float</procedure>
1933<setter>(set! (touch-finger-event-x event) val)</setter>
1934<setter>(touch-finger-event-x-set! event val)</setter>
1935
1936Get 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.
1937
1938
1939<procedure>(touch-finger-event-y event) → float</procedure>
1940<setter>(set! (touch-finger-event-y event) val)</setter>
1941<setter>(touch-finger-event-y-set! event val)</setter>
1942
1943Get 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.
1944
1945
1946<procedure>(touch-finger-event-dx event) → float</procedure>
1947<setter>(set! (touch-finger-event-dx event) val)</setter>
1948<setter>(touch-finger-event-dx-set! event val)</setter>
1949
1950Get 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.
1951
1952
1953<procedure>(touch-finger-event-dy event) → float</procedure>
1954<setter>(set! (touch-finger-event-dy event) val)</setter>
1955<setter>(touch-finger-event-dy-set! event val)</setter>
1956
1957Get 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.
1958
1959
1960<procedure>(touch-finger-event-pressure event) → float</procedure>
1961<setter>(set! (touch-finger-event-pressure event) val)</setter>
1962<setter>(touch-finger-event-pressure-set! event val)</setter>
1963
1964Get or set the event's "pressure" field, as a float in the range 0.0 to 1.0 (inclusive), indicating the pressure being applied.
1965
1966
1967
1968==== sdl2:user-event
1969
1970sdl2:user-event is a variant of sdl2:event that wraps a pointer to an
1971[[https://wiki.libsdl.org/SDL_UserEvent|SDL_UserEvent]].
1972
1973This event variant does not occur normally.
1974Instead, you can make instances of this event variant and push them to the event queue using {{push-event!}}.
1975The meaning of this event variant is entirely up for you to decide.
1976For example, you can use it to create custom event types related to your gameplay.
1977
1978sdl2:user-event does not have any event type symbols by default.
1979Call {{register-events!}} to register your own custom event type symbols for sdl2:user-event.
1980
1981
1982<procedure>(user-event? obj) → boolean</procedure>
1983
1984Returns #t if {{obj}} is an sdl2:user-event.
1985
1986
1987<procedure>(user-event-window-id event) → integer</procedure>
1988<setter>(set! (user-event-window-id event) val)</setter>
1989<setter>(user-event-window-id-set! event val)</setter>
1990
1991Get or set the event's "window-id" field, as an integer indicating the ID number of the sdl2:window associated with this event.
1992
1993
1994<procedure>(user-event-code event) → integer</procedure>
1995<setter>(set! (user-event-code event) val)</setter>
1996<setter>(user-event-code-set! event val)</setter>
1997
1998Get or set the event's "code" field, as an integer in the range -32768 to 32767 (inclusive).
1999The meaning of this field is for you to decide.
2000
2001
2002<procedure>(user-event-data1-raw event) → pointer or #f</procedure>
2003<setter>(set! (user-event-data1-raw event) val)</setter>
2004<setter>(user-event-data1-raw-set! event val)</setter>
2005
2006Get or set the event's "data1" field, as a raw pointer or #f.
2007The meaning of this field is for you to decide.
2008
2009If you want to store a pointer to a Scheme object here, be sure to
2010[[/manual/Unit lolevel#object-evict|evict the object]] first. Otherwise
2011the object's location in memory might change, rendering the pointer
2012invalid.
2013
2014
2015<procedure>(user-event-data2-raw event) → pointer or #f</procedure>
2016<setter>(set! (user-event-data2-raw event) val)</setter>
2017<setter>(user-event-data2-raw-set! event val)</setter>
2018
2019Get or set the event's "data2" field, as a raw pointer or #f.
2020The meaning of this field is for you to decide.
2021
2022If you want to store a pointer to a Scheme object here, be sure to
2023[[/manual/Unit lolevel#object-evict|evict the object]] first. Otherwise
2024the object's location in memory might change, rendering the pointer
2025invalid.
2026
2027
2028
2029==== sdl2:window-event
2030
2031sdl2:window-event is a variant of sdl2:event that wraps a pointer to an
2032[[https://wiki.libsdl.org/SDL_WindowEvent|SDL_WindowEvent]].
2033
2034This event variant occurs when various changes occur to a window,
2035e.g. when a window is moved, resized, minimized, closed, etc.
2036
2037sdl2:window-event has the following event type symbols:
2038
2039; {{'window}} : A window-related event occurred.
2040
2041
2042<procedure>(window-event? obj) → boolean</procedure>
2043
2044Returns #t if {{obj}} is an sdl2:window-event.
2045
2046
2047<procedure>(window-event-window-id event) → integer</procedure>
2048<setter>(set! (window-event-window-id event) val)</setter>
2049<setter>(window-event-window-id-set! event val)</setter>
2050
2051Get or set the event's "window-id" field, as an integer indicating the ID of the sdl2:window that the event is related to.
2052
2053
2054<procedure>(window-event-event event) → symbol</procedure>
2055<procedure>(window-event-event-raw event) → integer</procedure>
2056<setter>(set! (window-event-event event) val)</setter>
2057<setter>(window-event-event-set! event val)</setter>
2058
2059Get or set the event's "event" field, indicating what happened to the window.
2060
2061* {{window-event-event}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#window-event-types|window event type symbol]].
2062* {{window-event-event-raw}} returns an integer.
2063* The setters accept either a symbol or an integer.
2064
2065
2066<procedure>(window-event-data1 event) → integer</procedure>
2067<setter>(set! (window-event-data1 event) val)</setter>
2068<setter>(window-event-data1-set! event val)</setter>
2069
2070Get or set the sdl2:window-event's "data1" field, as an integer.
2071The meaning of this value depends on what kind of window event it was (see {{window-event-event}}).
2072E.g. if the window was resized, this will hold the new window width;
2073if the window was moved, this will hold the new x position.
2074
2075
2076<procedure>(window-event-data2 event) → integer</procedure>
2077<setter>(set! (window-event-data2 event) val)</setter>
2078<setter>(window-event-data2-set! event val)</setter>
2079
2080Get or set the sdl2:window-event's "data2" field, as an integer.
2081The meaning of this value depends on what kind of window event it was (see {{window-event-event}}).
2082E.g. if the window was resized, this will hold the new window height;
2083if the window was moved, this will hold the new y position.
2084
2085
2086
2087=== Hints
2088
2089[[https://wiki.libsdl.org/CategoryHints|Hints (aka Configuration Variables)]]
2090are a way for you to give hints to the SDL library about how you would like it to behave.
2091Most hints affect platform-specific behavior.
2092Hints are merely suggestions, and SDL may or may not obey them.
2093
2094Hints can also be specified or overriden by environment variables.
2095This allows the user to configure SDL to work best on their system.
2096Usually the environment variable is similar to the SDL constant name,
2097but prefixed with "SDL_" instead of "SDL_HINT_".
2098For more information see [[https://hg.libsdl.org/SDL/file/default/include/SDL_hints.h|SDL_hints.h]].
2099
2100Procedures for getting and setting hints are available in '''sdl2 egg version 0.2.0 and higher'''.
2101But, SDL will notice environment variables even if you are using an earlier version of the sdl2 egg.
2102
2103The tables below list the hint name symbol,
2104which you can pass to {{get-hint}} and {{set-hint!}},
2105and the corresponding SDL constant.
2106See the linked documentation for more information about what the hint does,
2107and valid values for the hint.
2108
2109Some hints are only effective after a certain version of SDL.
2110You may safely set the hint with any version of SDL,
2111but it will have no effect on older versions of SDL.
2112
2113==== Hints in SDL 2.0.0 and higher
2114
2115<table>
2116  <tr>
2117    <th>Hint name symbol</th>
2118    <th>SDL constant name</th>
2119  </tr>
2120  <tr>
2121    <td>framebuffer-acceleration</td>
2122    <td>[[https://wiki.libsdl.org/SDL_HINT_FRAMEBUFFER_ACCELERATION|SDL_HINT_FRAMEBUFFER_ACCELERATION]]</td>
2123  </tr>
2124  <tr>
2125    <td>gamecontrollerconfig</td>
2126    <td>[[https://wiki.libsdl.org/SDL_HINT_GAMECONTROLLERCONFIG|SDL_HINT_GAMECONTROLLERCONFIG]]</td>
2127  </tr>
2128  <tr>
2129    <td>grab-keyboard</td>
2130    <td>[[https://wiki.libsdl.org/SDL_HINT_GRAB_KEYBOARD|SDL_HINT_GRAB_KEYBOARD]]</td>
2131  </tr>
2132  <tr>
2133    <td>idle-timer-disabled</td>
2134    <td>[[https://wiki.libsdl.org/SDL_HINT_IDLE_TIMER_DISABLED|SDL_HINT_IDLE_TIMER_DISABLED]]</td>
2135  </tr>
2136  <tr>
2137    <td>joystick-allow-background-events</td>
2138    <td>[[https://wiki.libsdl.org/SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS|SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS]]</td>
2139  </tr>
2140  <tr>
2141    <td>orientations</td>
2142    <td>[[https://wiki.libsdl.org/SDL_HINT_ORIENTATIONS|SDL_HINT_ORIENTATIONS]]</td>
2143  </tr>
2144  <tr>
2145    <td>render-driver</td>
2146    <td>[[https://wiki.libsdl.org/SDL_HINT_RENDER_DRIVER|SDL_HINT_RENDER_DRIVER]]</td>
2147  </tr>
2148  <tr>
2149    <td>render-opengl-shaders</td>
2150    <td>[[https://wiki.libsdl.org/SDL_HINT_RENDER_OPENGL_SHADERS|SDL_HINT_RENDER_OPENGL_SHADERS]]</td>
2151  </tr>
2152  <tr>
2153    <td>render-scale-quality</td>
2154    <td>[[https://wiki.libsdl.org/SDL_HINT_RENDER_SCALE_QUALITY|SDL_HINT_RENDER_SCALE_QUALITY]]</td>
2155  </tr>
2156  <tr>
2157    <td>render-vsync</td>
2158    <td>[[https://wiki.libsdl.org/SDL_HINT_RENDER_VSYNC|SDL_HINT_RENDER_VSYNC]]</td>
2159  </tr>
2160  <tr>
2161    <td>timer-resolution</td>
2162    <td>[[https://wiki.libsdl.org/SDL_HINT_TIMER_RESOLUTION|SDL_HINT_TIMER_RESOLUTION]]</td>
2163  </tr>
2164  <tr>
2165    <td>video-minimize-on-focus-loss</td>
2166    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS|SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS]]</td>
2167  </tr>
2168  <tr>
2169    <td>video-x11-xinerama</td>
2170    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_X11_XINERAMA|SDL_HINT_VIDEO_X11_XINERAMA]]</td>
2171  </tr>
2172  <tr>
2173    <td>video-x11-xrandr</td>
2174    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_X11_XRANDR|SDL_HINT_VIDEO_X11_XRANDR]]</td>
2175  </tr>
2176  <tr>
2177    <td>video-x11-xvidmode</td>
2178    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_X11_XVIDMODE|SDL_HINT_VIDEO_X11_XVIDMODE]]</td>
2179  </tr>
2180  <tr>
2181    <td>xinput-enabled</td>
2182    <td>[[https://wiki.libsdl.org/SDL_HINT_XINPUT_ENABLED|SDL_HINT_XINPUT_ENABLED]]</td>
2183  </tr>
2184</table>
2185
2186==== Hints in SDL 2.0.1 and higher
2187
2188<table>
2189  <tr>
2190    <th>Hint name symbol</th>
2191    <th>SDL constant name</th>
2192  </tr>
2193  <tr>
2194    <td>render-direct3d-threadsafe</td>
2195    <td>[[https://wiki.libsdl.org/SDL_HINT_RENDER_DIRECT3D_THREADSAFE|SDL_HINT_RENDER_DIRECT3D_THREADSAFE]]</td>
2196  </tr>
2197  <tr>
2198    <td>video-highdpi-disabled</td>
2199    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_HIGHDPI_DISABLED|SDL_HINT_VIDEO_HIGHDPI_DISABLED]]</td>
2200  </tr>
2201</table>
2202
2203
2204==== Hints in SDL 2.0.2 and higher
2205
2206<table>
2207  <tr>
2208    <th>Hint name symbol</th>
2209    <th>SDL constant name</th>
2210  </tr>
2211  <tr>
2212    <td>accelerometer-as-joystick</td>
2213    <td>[[https://wiki.libsdl.org/SDL_HINT_ACCELEROMETER_AS_JOYSTICK|SDL_HINT_ACCELEROMETER_AS_JOYSTICK]]</td>
2214  </tr>
2215  <tr>
2216    <td>mac-ctrl-click-emulate-right-click</td>
2217    <td>[[https://wiki.libsdl.org/SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK|SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK]]</td>
2218  </tr>
2219  <tr>
2220    <td>mouse-relative-mode-warp</td>
2221    <td>[[https://wiki.libsdl.org/SDL_HINT_MOUSE_RELATIVE_MODE_WARP|SDL_HINT_MOUSE_RELATIVE_MODE_WARP]]</td>
2222  </tr>
2223  <tr>
2224    <td>video-allow-screensaver</td>
2225    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_ALLOW_SCREENSAVER|SDL_HINT_VIDEO_ALLOW_SCREENSAVER]]</td>
2226  </tr>
2227  <tr>
2228    <td>video-mac-fullscreen-spaces</td>
2229    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES|SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES]]</td>
2230  </tr>
2231  <tr>
2232    <td>video-window-share-pixel-format</td>
2233    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT|SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT]]</td>
2234  </tr>
2235  <tr>
2236    <td>video-win-d3dcompiler</td>
2237    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_WIN_D3DCOMPILER|SDL_HINT_VIDEO_WIN_D3DCOMPILER]]</td>
2238  </tr>
2239</table>
2240
2241
2242==== Hints in SDL 2.0.3 and higher
2243
2244<table>
2245  <tr>
2246    <th>Hint name symbol</th>
2247    <th>SDL constant name</th>
2248  </tr>
2249  <tr>
2250    <td>render-direct3d11-debug</td>
2251    <td>[[https://wiki.libsdl.org/SDL_HINT_RENDER_DIRECT3D11_DEBUG|SDL_HINT_RENDER_DIRECT3D11_DEBUG]]</td>
2252  </tr>
2253  <tr>
2254    <td>winrt-handle-back-button</td>
2255    <td>[[https://wiki.libsdl.org/SDL_HINT_WINRT_HANDLE_BACK_BUTTON|SDL_HINT_WINRT_HANDLE_BACK_BUTTON]]</td>
2256  </tr>
2257  <tr>
2258    <td>winrt-privacy-policy-label</td>
2259    <td>[[https://wiki.libsdl.org/SDL_HINT_WINRT_PRIVACY_POLICY_LABEL|SDL_HINT_WINRT_PRIVACY_POLICY_LABEL]]</td>
2260  </tr>
2261  <tr>
2262    <td>winrt-privacy-policy-url</td>
2263    <td>[[https://wiki.libsdl.org/SDL_HINT_WINRT_PRIVACY_POLICY_URL|SDL_HINT_WINRT_PRIVACY_POLICY_URL]]</td>
2264  </tr>
2265</table>
2266
2267
2268==== Hints in SDL 2.0.4 and higher
2269
2270<table>
2271  <tr>
2272    <th>Hint name symbol</th>
2273    <th>SDL constant name</th>
2274  </tr>
2275  <tr>
2276    <td>android-apk-expansion-main-file-version</td>
2277    <td>[[https://wiki.libsdl.org/SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION|SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION]]</td>
2278  </tr>
2279  <tr>
2280    <td>android-apk-expansion-patch-file-version</td>
2281    <td>[[https://wiki.libsdl.org/SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION|SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION]]</td>
2282  </tr>
2283  <tr>
2284    <td>android-separate-mouse-and-touch</td>
2285    <td>[[https://wiki.libsdl.org/SDL_HINT_ANDROID_SEPARATE_MOUSE_AND_TOUCH|SDL_HINT_ANDROID_SEPARATE_MOUSE_AND_TOUCH]]</td>
2286  </tr>
2287  <tr>
2288    <td>emscripten-keyboard-element</td>
2289    <td>[[https://wiki.libsdl.org/SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT|SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT]]</td>
2290  </tr>
2291  <tr>
2292    <td>ime-internal-editing</td>
2293    <td>[[https://wiki.libsdl.org/SDL_HINT_IME_INTERNAL_EDITING|SDL_HINT_IME_INTERNAL_EDITING]]</td>
2294  </tr>
2295  <tr>
2296    <td>mac-background-app</td>
2297    <td>[[https://wiki.libsdl.org/SDL_HINT_MAC_BACKGROUND_APP|SDL_HINT_MAC_BACKGROUND_APP]]</td>
2298  </tr>
2299  <tr>
2300    <td>no-signal-handlers</td>
2301    <td>[[https://wiki.libsdl.org/SDL_HINT_NO_SIGNAL_HANDLERS|SDL_HINT_NO_SIGNAL_HANDLERS]]</td>
2302  </tr>
2303  <tr>
2304    <td>thread-stack-size</td>
2305    <td>[[https://wiki.libsdl.org/SDL_HINT_THREAD_STACK_SIZE|SDL_HINT_THREAD_STACK_SIZE]]</td>
2306  </tr>
2307  <tr>
2308    <td>video-x11-net-wm-ping</td>
2309    <td>[[https://wiki.libsdl.org/SDL_HINT_VIDEO_X11_NET_WM_PING|SDL_HINT_VIDEO_X11_NET_WM_PING]]</td>
2310  </tr>
2311  <tr>
2312    <td>windows-enable-messageloop</td>
2313    <td>[[https://wiki.libsdl.org/SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP|SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP]]</td>
2314  </tr>
2315  <tr>
2316    <td>windows-no-close-on-alt-f4</td>
2317    <td>[[https://wiki.libsdl.org/SDL_HINT_WINDOWS_NO_CLOSE_ON_ALT_F4|SDL_HINT_WINDOWS_NO_CLOSE_ON_ALT_F4]]</td>
2318  </tr>
2319  <tr>
2320    <td>window-frame-usable-while-cursor-hidden</td>
2321    <td>[[https://wiki.libsdl.org/SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN|SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN]]</td>
2322  </tr>
2323  <tr>
2324    <td>xinput-use-old-joystick-mapping</td>
2325    <td>[[https://wiki.libsdl.org/SDL_HINT_XINPUT_USE_OLD_JOYSTICK_MAPPING|SDL_HINT_XINPUT_USE_OLD_JOYSTICK_MAPPING]]</td>
2326  </tr>
2327</table>
2328
2329==== Hint Functions
2330
2331<procedure>(get-hint name) → string or #f</procedure>
2332
2333Returns the current value of the hint as a string, or #f if the hint has no value.
2334See [[https://wiki.libsdl.org/SDL_GetHint|SDL_GetHint]].
2335This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
2336
2337
2338<procedure>(set-hint! name value #!optional priority) → boolean</procedure>
2339
2340Sets the value of the hint.
2341See [[https://wiki.libsdl.org/SDL_SetHintWithPriority|SDL_SetHintWithPriority]].
2342This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
2343
2344{{name}} specifies which hint to change.
2345It must be a symbol from the tables above, or a string.
2346This procedure signals an exception if {{name}} is an unrecognized symbol
2347(i.e. is not listed in any of the tables above).
2348This procedures accepts any string name, even if it is not recognized.
2349
2350{{value}} specifies the new value of the hint. It must be a string.
2351
2352{{priority}} specifies the priorily level for setting the hint.
2353If it is omitted, the priority will be {{'normal}}.
2354It must be one of these symbols:
2355
2356* {{'default}}
2357* {{'normal}}
2358* {{'override}}
2359
2360Returns #t if the hint's value was set, or #f if it was not set
2361(e.g. because the hint was already set with a higher priority).
2362
2363
2364<procedure>(clear-hints!)</procedure>
2365
2366Removes the values and priorities of all hints.
2367See [[https://wiki.libsdl.org/SDL_ClearHints|SDL_ClearHints]].
2368This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
2369
2370
2371
2372=== Joystick
2373
2374==== Joystick Functions
2375
2376<procedure>(num-joysticks) → integer</procedure>
2377
2378See [[https://wiki.libsdl.org/SDL_NumJoysticks|SDL_NumJoysticks]].
2379
2380Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2381
2382
2383<procedure>(joystick-open! index) → sdl2:joystick</procedure>
2384
2385See [[https://wiki.libsdl.org/SDL_JoystickOpen|SDL_JoystickOpen]].
2386
2387Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2388
2389
2390<procedure>(joystick-close! joystick)</procedure>
2391
2392See [[https://wiki.libsdl.org/SDL_JoystickClose|SDL_JoystickClose]].
2393
2394
2395<procedure>(joystick-from-instance-id id) → sdl2:joystick</procedure>
2396
2397See [[https://wiki.libsdl.org/SDL_JoystickFromInstanceID|SDL_JoystickFromInstanceID]].
2398
2399'''NOTE:''' The returned joystick will be a new sdl2:joystick record pointing to the address of the existing joystick.
2400It will be {{equal?}} to other sdl2:joystick records for the same joystick, but not {{eq?}}.
2401
2402This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
2403It requires '''SDL 2.0.4 or higher'''.
2404It signals an error if the compiled version of SDL is not high enough.
2405Use the [[#version-feature-identifiers|{{libSDL-2.0.4+}} feature identifier]]
2406to check before calling this procedure.
2407
2408
2409<procedure>(joystick-update!)</procedure>
2410
2411See [[https://wiki.libsdl.org/SDL_JoystickUpdate|SDL_JoystickUpdate]].
2412
2413
2414<procedure>(joystick-event-state) → boolean</procedure>
2415<setter>(set! (joystick-event-state) state) → boolean</setter>
2416<setter>(joystick-event-state-set! state) → boolean</setter>
2417
2418{{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).
2419
2420The setters enable (if {{state}} is #t) or disable (if {{state}} is #f) joytsick events.
2421'''WARNING:''' Calling the setters may delete all events currently in the event queue.
2422
2423These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
2424
2425See [[https://wiki.libsdl.org/SDL_JoystickEventState|SDL_JoystickEventState]].
2426
2427
2428<procedure>(joystick-name-for-index device-index) → string or #f</procedure>
2429
2430See [[https://wiki.libsdl.org/SDL_JoystickNameForIndex|SDL_JoystickNameForIndex]].
2431
2432Returns #f if no name can be found.
2433
2434
2435<procedure>(joystick-get-device-guid device-index) → sdl2:joystick-guid</procedure>
2436
2437See [[https://wiki.libsdl.org/SDL_JoystickGetDeviceGUID|SDL_JoystickGetDeviceGUID]].
2438
2439Returns a new managed sdl2:joystick-guid.
2440
2441
2442==== sdl2:joystick
2443
2444sdl2:joystick is a record type that wraps a pointer to an
2445[[https://wiki.libsdl.org/SDL_Joystick|SDL_Joystick]] struct.
2446
2447
2448<procedure>(joystick? obj) → boolean</procedure>
2449
2450Returns #t if {{obj}} is an sdl2:joystick.
2451
2452
2453<procedure>(joystick-instance-id joystick) → integer</procedure>
2454
2455See [[https://wiki.libsdl.org/SDL_JoystickInstanceID|SDL_JoystickInstanceID]].
2456
2457Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2458
2459
2460<procedure>(joystick-name joystick) → string or #f</procedure>
2461
2462See [[https://wiki.libsdl.org/SDL_JoystickName|SDL_JoystickName]].
2463
2464Returns #f if no name can be found.
2465
2466
2467<procedure>(joystick-get-guid joystick) → sdl2:joystick-guid</procedure>
2468
2469See [[https://wiki.libsdl.org/SDL_JoystickGetGUID|SDL_JoystickGetGUID]].
2470
2471Returns a new managed sdl2:joystick-guid.
2472
2473
2474<procedure>(joystick-attached? joystick) → boolean</procedure>
2475
2476See [[https://wiki.libsdl.org/SDL_JoystickGetAttached|SDL_JoystickGetAttached]].
2477
2478
2479<procedure>(joystick-current-power-level joystick) → symbol</procedure>
2480
2481See [[https://wiki.libsdl.org/SDL_JoystickCurrentPowerLevel|SDL_JoystickCurrentPowerLevel]].
2482
2483Returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#joystick-power-level|joystick power level enum symbol]]:
2484
2485* {{'unknown}}
2486* {{'empty}}
2487* {{'low}}
2488* {{'medium}}
2489* {{'full}}
2490* {{'wired}}
2491* {{'max}}
2492
2493This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
2494It requires '''SDL 2.0.4 or higher'''.
2495It signals an error if the compiled version of SDL is not high enough.
2496Use the [[#version-feature-identifiers|{{libSDL-2.0.4+}} feature identifier]]
2497to check before calling this procedure.
2498
2499
2500<procedure>(joystick-num-axes joystick) → integer</procedure>
2501
2502See [[https://wiki.libsdl.org/SDL_JoystickNumAxes|SDL_JoystickNumAxes]].
2503
2504Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2505
2506
2507<procedure>(joystick-num-balls joystick) → integer</procedure>
2508
2509See [[https://wiki.libsdl.org/SDL_JoystickNumBalls|SDL_JoystickNumBalls]].
2510
2511Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2512
2513
2514<procedure>(joystick-num-buttons joystick) → integer</procedure>
2515
2516See [[https://wiki.libsdl.org/SDL_JoystickNumButtons|SDL_JoystickNumButtons]].
2517
2518Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2519
2520
2521<procedure>(joystick-num-hats joystick) → integer</procedure>
2522
2523See [[https://wiki.libsdl.org/SDL_JoystickNumHats|SDL_JoystickNumHats]].
2524
2525Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2526
2527
2528<procedure>(joystick-get-axis joystick axis-num) → integer</procedure>
2529
2530See [[https://wiki.libsdl.org/SDL_JoystickGetAxis|SDL_JoystickGetAxis]].
2531
2532Signals 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}}).
2533
2534
2535<procedure>(joystick-get-ball joystick ball-num) → [dx dy]</procedure>
2536
2537See [[https://wiki.libsdl.org/SDL_JoystickGetBall|SDL_JoystickGetBall]].
2538
2539This procedure returns multiple values.
2540
2541Signals 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}}).
2542Signals an exception of kind {{(exn sdl2)}} if some other error occurs.
2543
2544
2545<procedure>(joystick-get-button joystick button-num) → boolean</procedure>
2546
2547See [[https://wiki.libsdl.org/SDL_JoystickGetButton|SDL_JoystickGetButton]].
2548
2549Signals 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}}).
2550
2551
2552<procedure>(joystick-get-hat joystick hat-num) → symbol</procedure>
2553<procedure>(joystick-get-hat-raw joystick hat-num) → integer</procedure>
2554
2555See [[https://wiki.libsdl.org/SDL_JoystickGetHat|SDL_JoystickGetHat]].
2556
2557* {{joystick-get-hat}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#joystick-hat-position|joystick hat position symbol]].
2558* {{joystick-get-hat-raw}} returns an integer.
2559
2560Both 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}}).
2561
2562
2563
2564==== sdl2:joystick-guid
2565
2566sdl2:joystick-guid is a record type that wraps a pointer to an
2567[[https://wiki.libsdl.org/SDL_JoystickGetGUID|SDL_JoystickGUID]]
2568struct.
2569
2570
2571<procedure>(joystick-guid? obj) → boolean</procedure>
2572
2573Returns #t if {{obj}} is an sdl2:joystick-guid.
2574
2575
2576<procedure>(free-joystick-guid! guid)</procedure>
2577
2578Free the memory of the sdl2:joystick-guid's underlying struct.
2579{{guid}}'s pointer will be set to null (see {{struct-null?}}). It is
2580safe to call this procedure with managed or unmanaged
2581sdl2:joystick-guids. It is safe (but has no effect) to free a struct
2582record multiple times.
2583
2584
2585<procedure>(joystick-get-guid-from-string str) → sdl2:joystick-guid</procedure>
2586
2587See [[https://wiki.libsdl.org/SDL_JoystickGetGUIDFromString|SDL_JoystickGetGUIDFromString]].
2588
2589Returns a new managed sdl2:joystick-guid.
2590
2591
2592<procedure>(joystick-get-guid-string guid) → string</procedure>
2593
2594See [[https://wiki.libsdl.org/SDL_JoystickGetGUIDString|SDL_JoystickGetGUIDString]].
2595
2596
2597
2598=== Keyboard
2599
2600==== Keyboard Functions
2601
2602<procedure>(get-key-from-name name-str) → symbol</procedure>
2603<procedure>(get-key-from-name-raw name-str) → integer</procedure>
2604
2605See [[https://wiki.libsdl.org/SDL_GetKeyFromName|SDL_GetKeyFromName]].
2606
2607* {{get-key-from-name}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]].
2608* {{get-key-from-name-raw}} returns an integer.
2609
2610
2611<procedure>(get-key-from-scancode scancode) → symbol</procedure>
2612<procedure>(get-key-from-scancode-raw scancode) → integer</procedure>
2613
2614See [[https://wiki.libsdl.org/SDL_GetKeyFromScancode|SDL_GetKeyFromScancode]].
2615
2616{{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.
2617
2618* {{get-key-from-scancode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]].
2619* {{get-key-from-scancode-raw}} returns an integer.
2620
2621
2622<procedure>(get-key-name key) → string</procedure>
2623
2624See [[https://wiki.libsdl.org/SDL_GetKeyName|SDL_GetKeyName]].
2625
2626{{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.
2627
2628
2629<procedure>(get-scancode-from-name name-str) → symbol</procedure>
2630<procedure>(get-scancode-from-name-raw name-str) → integer</procedure>
2631
2632See [[https://wiki.libsdl.org/SDL_GetScancodeFromName|SDL_GetScancodeFromName]].
2633
2634* {{get-scancode-from-name}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]].
2635* {{get-scancode-from-name-raw}} returns an integer.
2636
2637
2638<procedure>(get-scancode-from-key key) → symbol</procedure>
2639<procedure>(get-scancode-from-key-raw key) → integer</procedure>
2640
2641See [[https://wiki.libsdl.org/SDL_GetScancodeFromKey|SDL_GetScancodeFromKey]].
2642
2643{{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.
2644
2645* {{get-scancode-from-key}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]].
2646* {{get-scancode-from-key-raw}} returns an integer.
2647
2648
2649<procedure>(get-scancode-name scancode) → string</procedure>
2650
2651See [[https://wiki.libsdl.org/SDL_GetScancodeName|SDL_GetScancodeName]].
2652
2653{{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.
2654
2655
2656<procedure>(get-keyboard-focus) → sdl2:window</procedure>
2657
2658See [[https://wiki.libsdl.org/SDL_GetKeyboardFocus|SDL_GetKeyboardFocus]].
2659
2660
2661<procedure>(scancode-pressed? scancode) → boolean</procedure>
2662
2663Returns #t if the keyboard key with the given scancode is currently
2664being pressed.
2665
2666{{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.
2667
2668This procedure queries SDL's internal keyboard state, which is tied to
2669the event system. Call {{pump-events!}} to update the keyboard state.
2670
2671This procedure is based on
2672[[https://wiki.libsdl.org/SDL_GetKeyboardState|SDL_GetKeyboardState]].
2673
2674
2675<procedure>(mod-state) → list of symbols </procedure>
2676<procedure>(mod-state-raw) → integer</procedure>
2677<setter>(set! (mod-state) state)</setter>
2678<setter>(mod-state-set! state)</setter>
2679
2680See [[https://wiki.libsdl.org/SDL_GetModState|SDL_GetModState]].
2681
2682* {{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]].
2683* {{mod-state-raw}} returns an integer representing a bitfield of keyboard modifiers.
2684* The setters accept either a list of zero or more symbols, or an integer.
2685
2686
2687<setter>(text-input-rect-set! rect)</setter>
2688
2689{{rect}} can be an sdl2:rect or #f.
2690
2691See [[https://wiki.libsdl.org/SDL_SetTextInputRect|SDL_SetTextInputRect]].
2692
2693
2694<procedure>(start-text-input!)</procedure>
2695
2696See [[https://wiki.libsdl.org/SDL_StartTextInput|SDL_StartTextInput]].
2697
2698
2699<procedure>(stop-text-input!)</procedure>
2700
2701See [[https://wiki.libsdl.org/SDL_StopTextInput|SDL_StopTextInput]].
2702
2703
2704<procedure>(text-input-active?) → boolean</procedure>
2705
2706See [[https://wiki.libsdl.org/SDL_IsTextInputActive|SDL_IsTextInputActive]].
2707
2708
2709<procedure>(screen-keyboard-support?) → boolean</procedure>
2710
2711See [[https://wiki.libsdl.org/SDL_HasScreenKeyboardSupport|SDL_HasScreenKeyboardSupport]].
2712
2713
2714<procedure>(screen-keyboard-shown? window) → boolean</procedure>
2715
2716See [[https://wiki.libsdl.org/SDL_IsScreenKeyboardShown|SDL_IsScreenKeyboardShown]].
2717
2718
2719==== sdl2:keysym
2720
2721sdl2:keysym is a record type that wraps a pointer to an
2722[[https://wiki.libsdl.org/SDL_Keysym|SDL_Keysym]] struct.
2723
2724
2725<procedure>(keysym? obj) → boolean</procedure>
2726
2727Returns #t if {{obj}} is an sdl2:keysym.
2728
2729
2730<procedure>(make-keysym #!optional scancode sym mod) → sdl2:keysym</procedure>
2731<procedure>(make-keysym* #!optional scancode sym mod) → sdl2:keysym</procedure>
2732
2733Allocate and initialize a new sdl2:keysym.
2734
2735{{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.
2736
2737{{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.
2738
2739{{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.
2740
2741* {{make-keysym}} returns a managed sdl2:keysym.
2742* {{make-keysym*}} returns an unmanaged sdl2:keysym, which must be freed with {{free-keysym!}} when you are done with it.
2743
2744
2745<procedure>(free-keysym! keysym)</procedure>
2746
2747Free the memory of the sdl2:keysym's underlying struct. {{keysym}}'s
2748pointer will be set to null (see {{struct-null?}}). It is safe to call
2749this procedure with managed or unmanaged sdl2:keysyms. It is safe (but
2750has no effect) to free a struct record multiple times.
2751
2752
2753<procedure>(keysym-scancode keysym) → symbol</procedure>
2754<procedure>(keysym-scancode-raw keysym) → integer</procedure>
2755<setter>(set! (keysym-scancode keysym) val)</setter>
2756<setter>(keysym-scancode-set! keysym val)</setter>
2757
2758Get or set the sdl2:keysym's "scancode" field, indicating the physical key that this keysym describes.
2759
2760* {{keysym-scancode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]].
2761* {{keysym-scancode-raw}} returns an integer.
2762* The setters accept either a symbol or an integer.
2763
2764
2765<procedure>(keysym-sym keysym) → symbol</procedure>
2766<procedure>(keysym-sym-raw keysym) → integer</procedure>
2767<setter>(set! (keysym-sym keysym) val)</setter>
2768<setter>(keysym-sym-set! keysym val)</setter>
2769
2770Get or set the sdl2:keysym's "sym" field, indicating the logical key that this keysym describes.
2771
2772* {{keysym-sym}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]].
2773* {{keysym-sym-raw}} returns an integer.
2774* The setters accept either a symbol or an integer.
2775
2776
2777<procedure>(keysym-mod keysym) → list of symbols</procedure>
2778<procedure>(keysym-mod-raw keysym) → integer</procedure>
2779<setter>(set! (keysym-mod keysym) val)</setter>
2780<setter>(keysym-mod-set! keysym val)</setter>
2781
2782Get or set the sdl2:keysym's "mod" field, indicating the modifier keys that this keysym describes.
2783
2784* {{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]].
2785* {{keysym-mod-raw}} returns an integer.
2786* The setters accept either a list of zero or more symbols, or an integer.
2787
2788
2789
2790=== OpenGL
2791
2792==== OpenGL Functions
2793
2794<procedure>(gl-create-context! window) → sdl2:gl-context</procedure>
2795
2796See [[https://wiki.libsdl.org/SDL_GL_CreateContext|SDL_GL_CreateContext]].
2797
2798Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2799
2800
2801<procedure>(gl-delete-context! gl-context)</procedure>
2802
2803See [[https://wiki.libsdl.org/SDL_GL_DeleteContext|SDL_GL_DeleteContext]].
2804
2805
2806<procedure>(gl-make-current! window gl-context)</procedure>
2807
2808See [[https://wiki.libsdl.org/SDL_GL_MakeCurrent|SDL_GL_MakeCurrent]].
2809
2810Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2811
2812
2813<procedure>(gl-get-current-window) → sdl2:window</procedure>
2814
2815See [[https://wiki.libsdl.org/SDL_GL_GetCurrentWindow|SDL_GL_GetCurrentWindow]].
2816
2817Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2818
2819
2820<procedure>(gl-get-current-context) → sdl2:gl-context</procedure>
2821
2822See [[https://wiki.libsdl.org/SDL_GL_GetCurrentContext|SDL_GL_GetCurrentContext]].
2823
2824Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2825
2826
2827<procedure>(gl-attribute attr) → value</procedure>
2828<setter>(set! (gl-attribute attr) value)</setter>
2829<setter>(gl-attribute-set! attr value)</setter>
2830
2831See [[https://wiki.libsdl.org/SDL_GL_GetAttribute|SDL_GL_GetAttribute]]
2832and [[https://wiki.libsdl.org/SDL_GL_SetAttribute|SDL_GL_SetAttribute]].
2833
2834{{attr}} must be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#opengl-attributes|OpenGL attribute symbol]] or corresponding integer.
2835
2836The value's type depends on {{attr}}:
2837
2838* 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.)
2839
2840* 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.)
2841
2842* If {{attr}} is {{'context-release-flags}}, the value will be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#opengl-context-release-flags|OpenGL context release flag symbol]]: {{'none}} or {{'flush}}. (This attribute requires '''SDL 2.0.4 and higher''' and '''sdl2 egg version 0.2.0 or higher'''.)
2843
2844* Otherwise, the value is an integer.
2845
2846The getter and the setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
2847
2848
2849<procedure>(gl-reset-attributes!)</procedure>
2850
2851See [[https://wiki.libsdl.org/SDL_GL_ResetAttributes|SDL_GL_ResetAttributes]].
2852
2853Requires '''SDL 2.0.2 or higher'''.
2854Signals an error if the compiled version of SDL is not high enough.
2855Use the [[#version-feature-identifiers|{{libSDL-2.0.2+}} feature identifier]]
2856to check before calling this procedure.
2857
2858
2859<procedure>(gl-get-drawable-size window) → [width height]</procedure>
2860
2861See [[https://wiki.libsdl.org/SDL_GL_GetDrawableSize|SDL_GL_GetDrawableSize]].
2862
2863This procedure returns multiple values.
2864
2865Requires '''SDL 2.0.1 or higher'''.
2866Signals an error if the compiled version of SDL is not high enough.
2867Use the [[#version-feature-identifiers|{{libSDL-2.0.1+}} feature identifier]]
2868to check before calling this procedure.
2869
2870
2871<procedure>(gl-swap-window!)</procedure>
2872
2873See [[https://wiki.libsdl.org/SDL_GL_SwapWindow|SDL_GL_SwapWindow]].
2874
2875
2876<procedure>(gl-swap-interval) → integer</procedure>
2877<setter>(set! (gl-swap-interval) interval)</setter>
2878<setter>(gl-set-swap-interval! interval)</setter>
2879
2880See [[https://wiki.libsdl.org/SDL_GL_GetSwapInterval|SDL_GL_GetSwapInterval]]
2881and [[https://wiki.libsdl.org/SDL_GL_SetSwapInterval|SDL_GL_SetSwapInterval]].
2882
2883The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
2884
2885
2886<procedure>(gl-extension-supported? name-string) → boolean</procedure>
2887
2888See [[https://wiki.libsdl.org/SDL_GL_ExtensionSupported|SDL_GL_ExtensionSupported]].
2889
2890
2891<procedure>(gl-bind-texture! texture) → [tex-w tex-h]</procedure>
2892
2893Bind the given sdl2:texture for use with the current OpenGL context.
2894See [[https://wiki.libsdl.org/SDL_GL_BindTexture|SDL_GL_BindTexture]].
2895
2896Returns multiple values:
2897
2898; tex-w : The bound OpenGL texture's width, as a float (usually 1.0)
2899; tex-h : The bound OpenGL texture's height, as a float (usually 1.0)
2900
2901Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2902
2903This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
2904
2905
2906<procedure>(gl-unbind-texture! texture)</procedure>
2907
2908Unbind the given sdl2:texture from the OpenGL context.
2909See [[https://wiki.libsdl.org/SDL_GL_UnbindTexture|SDL_GL_UnbindTexture]].
2910
2911Signals an exception of kind {{(exn sdl2)}} if an error occurs.
2912
2913This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
2914
2915
2916
2917==== sdl2:gl-context
2918
2919sdl2:gl-context is a record type that wraps a pointer to an SDL_GLContext struct.
2920
2921<procedure>(gl-context? obj) → boolean</procedure>
2922
2923Returns #t if {{obj}} is an sdl2:gl-context.
2924
2925
2926
2927=== Palette
2928
2929==== sdl2:palette
2930
2931sdl2:palette is a record type that wraps a pointer to an
2932[[https://wiki.libsdl.org/SDL_Palette|SDL_Palette]] struct.
2933
2934
2935<procedure>(palette? obj) → boolean</procedure>
2936
2937Returns #t if {{obj}} is an sdl2:palette.
2938
2939
2940<procedure>(make-palette #!optional ncolors) → sdl2:palette</procedure>
2941<procedure>(make-palette* #!optional ncolors) → sdl2:palette</procedure>
2942
2943Allocate and initialize a new sdl2:palette with the given number of colors.
2944See [[https://wiki.libsdl.org/SDL_AllocPalette|SDL_AllocPalette]].
2945
2946{{ncolors}} defaults to 256.
2947Common values are 2 (for a 1-bit surface), 16 (for a 4-bit surface), and 256 (for an 8-bit surface).
2948
2949'''NOTE:''' Usually you do not need to manually allocate a palette. A
2950palette will be created for you when you create a surface with a depth
2951of 8 or lower, and the palette will be automatically freed when the
2952surface is freed (unless the palette is still being used by other
2953surfaces).
2954
2955* {{make-palette}} returns a managed sdl2:palette.
2956* {{make-palette*}} returns an unmanaged sdl2:palette, which must be freed with {{free-palette!}} when you are done with it.
2957
2958Both procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
2959
2960
2961<procedure>(free-palette! palette)</procedure>
2962
2963Free the memory of the sdl2:palette's underlying struct. {{palette}}'s
2964pointer will be set to null (see {{struct-null?}}). It is safe to call
2965this procedure with managed or unmanaged sdl2:palettes. It is safe
2966(but has no effect) to free a struct record multiple times.
2967
2968See [[https://wiki.libsdl.org/SDL_FreePalette|SDL_FreePalette]].
2969
2970
2971<procedure>(palette-ncolors palette) → integer</procedure>
2972<procedure>(palette-ncolours palette) → integer</procedure>
2973
2974Returns the number of colors in the palette.
2975Common values are 2 (for a 1-bit surface), 16 (for a 4-bit surface), and 256 (for an 8-bit surface).
2976
2977
2978<procedure>(palette-ref palette i) → sdl2:color</procedure>
2979<setter>(set! (palette-ref palette i) color)</setter>
2980<setter>(palette-set! palette i color)</setter>
2981
2982{{palette-ref}} returns a copy of the color at the given index of the palette, as a managed sdl2:color.
2983
2984The setters set the given index of the palette to a copy of the given sdl2:color.
2985
2986These procedures signal an exception of kind {{(exn bounds)}} if the given index is out of bounds.
2987
2988
2989<procedure>(palette-colors palette) → vector of sdl2:colors </procedure>
2990<procedure>(palette-colours palette) → vector of sdl2:colors </procedure>
2991<setter>(set! (palette-colors palette) colors-vec) → boolean</setter>
2992<setter>(set! (palette-colours palette) colors-vec) → boolean</setter>
2993<setter>(palette-colors-set! colors-vec #!optional firstcolor) → boolean</setter>
2994<setter>(palette-colours-set! colors-vec #!optional firstcolor) → boolean</setter>
2995
2996{{palette-colors}} and {{palette-colours}} return copies of all colors in the palette, as a Scheme vector of managed sdl2:colors.
2997
2998The setters set multiple colors in the palette to copies of the given colors.
2999See [[https://wiki.libsdl.org/SDL_SetPaletteColors|SDL_SetPaletteColors]].
3000
3001{{colors-vec}} must be a Scheme vector of sdl2:colors.
3002
3003{{firstcolor}} specifies the first index of the palette to set.
3004I.e., palette index {{firstcolor}} will be set to the first color in {{colors-vec}},
3005palette index {{firstcolor + 1}} will be set to the second color, and so on.
3006{{firstcolor}} defaults to 0.
3007Signals an exception of kind {{(exn bounds)}} if {{firstcolor}} is out of bounds.
3008
3009The {{set!}} form cannot accept the {{firstcolor}} argument.
3010
3011The setters return #t if every color in {{colors-vec}} was used, or #f if some colors were not used,
3012e.g. because there were more colors in the vector than could fit in the palette.
3013
3014
3015
3016=== Pixel Format
3017
3018==== Pixel Format Functions
3019
3020<procedure>(map-rgb pixel-format r g b) → integer</procedure>
3021<procedure>(map-rgba pixel-format r g b a) → integer</procedure>
3022
3023See [[https://wiki.libsdl.org/SDL_MapRGB|SDL_MapRGB]]
3024and [[https://wiki.libsdl.org/SDL_MapRGBA|SDL_MapRGBA]].
3025
3026
3027<procedure>(get-rgb pixel pixel-format) → [r g b]</procedure>
3028<procedure>(get-rgba pixel pixel-format) → [r g b a]</procedure>
3029
3030See [[https://wiki.libsdl.org/SDL_GetRGB|SDL_GetRGB]]
3031and [[https://wiki.libsdl.org/SDL_GetRGBA|SDL_GetRGBA]].
3032
3033These procedures return multiple values.
3034
3035
3036<procedure>(pixel-format-enum-to-masks format-enum) → [bpp rmask gmask bmask amask]</procedure>
3037
3038See [[https://wiki.libsdl.org/SDL_PixelFormatEnumToMasks|SDL_PixelFormatEnumToMasks]].
3039
3040{{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.
3041
3042This procedure returns multiple values:
3043
3044; bpp   : The color depth (bits per pixel) of the format.
3045; rmask : The red mask of the format.
3046; gmask : The green mask of the format.
3047; bmask : The blue mask of the format.
3048; amask : The alpha mask of the format.
3049
3050Signals an exception of kind {{(exn sdl2)}} if conversion was not possible.
3051
3052
3053==== sdl2:pixel-format
3054
3055sdl2:pixel-format is a record type that wraps a pointer to an
3056[[https://wiki.libsdl.org/SDL_PixelFormat|SDL_PixelFormat]] struct.
3057
3058
3059<procedure>(pixel-format? obj) → boolean</procedure>
3060
3061Returns #t if {{obj}} is an sdl2:pixel-format.
3062
3063
3064<procedure>(make-pixel-format #!optional format) → sdl2:pixel-format</procedure>
3065<procedure>(make-pixel-format* #!optional format) → sdl2:pixel-format</procedure>
3066
3067Allocate and initialize a new sdl2:pixel-format with the given format.
3068
3069{{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.
3070See [[https://wiki.libsdl.org/SDL_AllocFormat|SDL_AllocFormat]].
3071
3072* {{make-pixel-format}} returns a managed sdl2:pixel-format.
3073* {{make-pixel-format*}} returns an unmanaged sdl2:pixel-format, which must be freed with {{free-pixel-format!}} when you are done with it.
3074
3075Both procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
3076
3077
3078<procedure>(free-pixel-format! pixel-format)</procedure>
3079
3080Free the memory of the sdl2:pixel-format's underlying struct.
3081{{pixel-format}}'s pointer will be set to null (see {{struct-null?}}).
3082It is safe to call this procedure with managed or unmanaged
3083sdl2:pixel-formats. It is safe (but has no effect) to free a struct
3084record multiple times.
3085
3086See [[https://wiki.libsdl.org/SDL_FreeFormat|SDL_FreeFormat]].
3087
3088
3089<procedure>(pixel-format-format pixel-format) → symbol</procedure>
3090<procedure>(pixel-format-format-raw pixel-format) → integer</procedure>
3091
3092Get the sdl2:pixel-format's "format" field.
3093
3094* {{pixel-format-format}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]].
3095* {{pixel-format-format-raw}} returns an integer.
3096
3097
3098<procedure>(pixel-format-palette pixel-format) → sdl2:palette or #f</procedure>
3099<setter>(set! (pixel-format-palette pixel-format) val)</setter>
3100<setter>(pixel-format-palette-set! pixel-format val)</setter>
3101
3102Get or set the sdl2:pixel-format's "palette" field, as an sdl2:palette, or #f if it does not have a palette.
3103Only sdl2:pixel-formats with bits-per-pixel of 8 or less can have a palette.
3104
3105See [[https://wiki.libsdl.org/SDL_SetPixelFormatPalette|SDL_SetPixelFormatPalette]].
3106
3107The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
3108
3109
3110<procedure>(pixel-format-bits-per-pixel pixel-format) → integer</procedure>
3111
3112Get the sdl2:pixel-format's "bits-per-pixel" field, as an integer.
3113Common values are 32, 24, 16, 15, 8, 4, and 1.
3114
3115
3116<procedure>(pixel-format-bytes-per-pixel pixel-format) → integer</procedure>
3117
3118Get the sdl2:pixel-format's "bits-per-pixel" field, as an integer.
3119Possible values are 4, 3, 2, and 1.
3120
3121
3122<procedure>(pixel-format-rmask pixel-format) → integer</procedure>
3123
3124Get the sdl2:pixel-format's "rmask" (red mask) field, as a nonnegative integer.
3125
3126
3127<procedure>(pixel-format-gmask pixel-format) → integer</procedure>
3128
3129Get the sdl2:pixel-format's "gmask" (green mask) field, as a nonnegative integer.
3130
3131
3132<procedure>(pixel-format-bmask pixel-format) → integer</procedure>
3133
3134Get the sdl2:pixel-format's "bmask" (blue mask) field, as a nonnegative integer.
3135
3136
3137<procedure>(pixel-format-amask pixel-format) → integer</procedure>
3138
3139Get the sdl2:pixel-format's "amask" (alpha mask) field, as a nonnegative integer.
3140It will be 0 if there is no alpha channel.
3141
3142
3143
3144=== Rect / Point
3145
3146==== Rect / Point Functions
3147
3148<procedure>(rect-empty? rect) → boolean</procedure>
3149
3150Returns #t if {{rect}}'s width and/or height is less than or equal to zero.
3151See [[https://wiki.libsdl.org/SDL_RectEmpty|SDL_RectEmpty]].
3152
3153
3154<procedure>(point-in-rect? point rect) → boolean</procedure>
3155
3156Returns #t if the sdl2:point is inside the sdl2:rect, or #f if it is not.
3157See [[https://wiki.libsdl.org/SDL_PointInRects|SDL_PointInRect]].
3158
3159This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3160It requires '''SDL 2.0.4 or higher'''.
3161It signals an error if the compiled version of SDL is not high enough.
3162Use the [[#version-feature-identifiers|{{libSDL-2.0.4+}} feature identifier]]
3163to check before calling this procedure.
3164
3165
3166<procedure>(enclose-points points #!optional clip result-rect) → [rect any-enclosed?]</procedure>
3167
3168See [[https://wiki.libsdl.org/SDL_EnclosePoints|SDL_EnclosePoints]].
3169
3170{{points}} must be a list of sdl2:points.
3171
3172{{clip}} must be either an sdl2:rect or #f (the default).
3173If {{clip}} is an sdl2:rect, points outside the clip rect will be ignored.
3174
3175If {{result-rect}} is omitted or #f, a new managed sdl2:rect will be returned.
3176If {{result-rect}} is an sdl2:rect, it will be modified and returned.
3177It is safe for {{result-rect}} to be the same object as {{clip}},
3178in which case {{clip}} will be modified and returned.
3179
3180This procedure returns multiple values:
3181
3182; rect : An sdl2:rect that encloses all matching points. This will be the same object as {{result-rect}}, if {{result-rect}} was specified.
3183; any-enclosed? : #t if any points were enclosed, or #f if all points were clipped
3184
3185
3186<procedure>(has-intersection? rect1 rect2) → boolean</procedure>
3187
3188Returns #t if {{rect1}} and {{rect2}} intersect, or #f if they do not.
3189See [[https://wiki.libsdl.org/SDL_HasIntersection|SDL_HasIntersection]].
3190
3191
3192<procedure>(intersect-rect rect1 rect2 #!optional result-rect) → [rect intersect?]</procedure>
3193
3194Calculates the intersection of {{rect1}} and {{rect2}}.
3195See [[https://wiki.libsdl.org/SDL_IntersectRect|SDL_IntersectRect]].
3196
3197If {{result-rect}} is omitted or #f, a new managed sdl2:rect will be returned.
3198If {{result-rect}} is an sdl2:rect, it will be modified and returned.
3199It is safe for {{result-rect}} to be the same object as {{rect1}} or {{rect2}},
3200in which case {{rect1}} or {{rect2}} will be modified and returned.
3201It is safe (but useless) for {{rect1}} and {{rect2}} to be the same object.
3202
3203This procedure returns multiple values:
3204
3205; rect : An sdl2:rect of the intersection of {{rect1}} and {{rect2}}. This will be the same object as {{result-rect}}, if {{result-rect}} was specified.
3206; intersect? : #t if {{rect1}} and {{rect2}} intersect, otherwise #f
3207
3208
3209<procedure>(intersect-rect-and-line rect x1 y1 x2 y2) → [intersect? x1-new y1-new x2-new y2-new]</procedure>
3210
3211Calculates the intersection between {{rect}} and the line segment described by {{x1}}, {{y1}}, {{x2}}, and {{y2}}.
3212See [[https://wiki.libsdl.org/SDL_IntersectRectAndLine|SDL_IntersectRectAndLine]].
3213
3214{{rect}} must be an sdl2:rect.
3215{{x1}}, {{y1}}, {{x2}}, and {{y2}} should be integers.
3216
3217This procedure returns multiple values:
3218
3219; intersect? : #t if the line segment intersects with the rect, otherwise #f
3220; x1-new : integer x1 of the new line segment
3221; y1-new : integer y1 of the new line segment
3222; x2-new : integer x2 of the new line segment
3223; y2-new : integer y2 of the new line segment
3224
3225If the line segment does not intersect the rect, then {{intersect?}} will be #f,
3226and {{x1-new}}, {{y1-new}}, {{x2-new}}, and {{y2-new}} will be the same as the original arguments.
3227
3228
3229<procedure>(union-rect rect1 rect2 #!optional result-rect) → rect</procedure>
3230
3231See [[https://wiki.libsdl.org/SDL_UnionRect|SDL_UnionRect]].
3232
3233If {{result-rect}} is omitted or #f, a new managed sdl2:rect will be returned.
3234If {{result-rect}} is an sdl2:rect, it will be modified and returned.
3235It is safe for {{result-rect}} to be the same object as {{rect1}} or {{rect2}},
3236in which case {{rect1}} or {{rect2}} will be modified and returned.
3237It is safe (but useless) for {{rect1}} and {{rect2}} to be the same object.
3238
3239
3240
3241==== sdl2:rect
3242
3243sdl2:rect is a record type that wraps a pointer to an
3244[[https://wiki.libsdl.org/SDL_Rect|SDL_Rect]] struct.
3245
3246
3247<procedure>(rect? obj) → boolean</procedure>
3248
3249Returns #t if {{obj}} is an sdl2:rect.
3250
3251
3252<procedure>(make-rect #!optional x y w h) → sdl2:rect</procedure>
3253<procedure>(make-rect* #!optional x y w h) → sdl2:rect</procedure>
3254
3255Allocate and initialize a new sdl2:rect.
3256
3257{{x}}, {{y}}, {{w}}, and {{h}} must be integers in the range -2147483648 to 2147483647 (inclusive).
3258They all default to 0.
3259
3260* {{make-rect}} returns a managed sdl2:rect.
3261* {{make-rect*}} returns an unmanaged sdl2:rect, which must be freed with {{free-rect!}} when you are done with it.
3262
3263
3264<procedure>(free-rect! rect)</procedure>
3265
3266Free the memory of the sdl2:rect's underlying struct. {{rect}}'s
3267pointer will be set to null (see {{struct-null?}}). It is safe to call
3268this procedure with managed or unmanaged sdl2:rects. It is safe (but
3269has no effect) to free a struct record multiple times.
3270
3271
3272<procedure>(rect-x rect) → integer</procedure>
3273<setter>(set! (rect-x rect) val)</setter>
3274<setter>(rect-x-set! rect val)</setter>
3275
3276Get or set the sdl2:rect's "x" field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3277
3278
3279<procedure>(rect-y rect) → integer</procedure>
3280<setter>(set! (rect-y rect) val)</setter>
3281<setter>(rect-y-set! rect val)</setter>
3282
3283Get or set the sdl2:rect's "y" field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3284
3285
3286<procedure>(rect-w rect) → integer</procedure>
3287<setter>(set! (rect-w rect) val)</setter>
3288<setter>(rect-w-set! rect val)</setter>
3289
3290Get or set the sdl2:rect's "w" (width) field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3291
3292
3293<procedure>(rect-h rect) → integer</procedure>
3294<setter>(set! (rect-h rect) val)</setter>
3295<setter>(rect-h-set! rect val)</setter>
3296
3297Get or set the sdl2:rect's "h" (height) field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3298
3299
3300
3301==== sdl2:rect Operations
3302
3303These are operations for efficiently and conveniently working with sdl2:rects.
3304Many of them are implemented in C for efficiency.
3305
3306
3307<procedure>(rect-set! rect #!optional x y w h) → rect</procedure>
3308
3309Efficient and convenient way of setting multiple fields of the sdl2:rect.
3310Any arguments that are {{#f}} will cause no change to that field.
3311E.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.
3312Returns {{rect}} after it is modified.
3313
3314
3315<procedure>(rect->list rect) → list of integers</procedure>
3316
3317Returns a list {{(x y w h)}} containing the value of each field of the sdl2:rect.
3318
3319
3320<procedure>(rect->values rect) → [x y w h]</procedure>
3321
3322Returns multiple values containing the value of each field of the sdl2:rect.
3323This is useful for destructuring an sdl2:rect using {{receive}} or {{let-values}}.
3324
3325
3326<procedure>(rect=? rect1 rect2) → boolean</procedure>
3327
3328Efficiently compare two sdl2:rects.
3329Returns #t if the value of every field in {{rect1}} is equal to the value of the corresponding field in {{rect2}}.
3330See [[https://wiki.libsdl.org/SDL_RectEquals|SDL_RectEquals]].
3331
3332
3333<procedure>(rect-copy src) → sdl2:rect</procedure>
3334<procedure>(rect-copy! src dest) → dest</procedure>
3335
3336{{rect-copy}} efficiently copies the values of {{src}} into a new managed sdl2:rect.
3337{{rect-copy}} is available in '''sdl2 egg version 0.2.0 and higher'''.
3338In earlier versions, it was named {{copy-rect}}.
3339
3340{{rect-copy!}} efficiently copies the values of {{src}} into {{dest}},
3341and returns the modified {{dest}}.
3342It is safe (but useless) for {{src}} and {{dest}} to be the same object.
3343{{rect-copy!}} is available in '''sdl2 egg version 0.2.0 and higher'''.
3344
3345
3346<procedure>(copy-rect rect) → sdl2:rect</procedure>
3347
3348Deprecated alias for {{rect-copy}}.
3349This alias was deprecated in sdl2 egg version 0.2.0,
3350and will be removed in a future version.
3351
3352
3353<procedure>(copy-rect* rect) → sdl2:rect</procedure>
3354
3355Deprecated procedure.
3356This procedure was deprecated in sdl2 egg version 0.2.0,
3357and will be removed in a future version.
3358You can achieve the same effect using {{rect-copy!}} and {{make-rect*}}.
3359
3360
3361<procedure>(rect-scale  rect scale) → sdl2:rect</procedure>
3362<procedure>(rect-scale! rect scale #!optional dest) → dest</procedure>
3363
3364Efficiently scale (multiply) the X, Y, W, and H values of {{rect}} by {{scale}} (a float or integer).
3365E.g. {{scale}} 0.5 halves the values, {{scale}} 2.0 doubles the values.
3366sdl2:rect can only hold integer values, so the results will be truncated to integers.
3367The results will be clamped to the range -2147483648 to 2147483647.
3368
3369* {{rect-scale}} returns a new managed sdl2:rect.
3370* {{rect-scale!}} modifies and returns {{dest}}.
3371  If {{dest}} is omitted, {{rect}} is modified and returned.
3372
3373These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3374
3375
3376<procedure>(rect-move  rect dx dy) → sdl2:rect</procedure>
3377<procedure>(rect-move! rect dx dy #!optional dest) → dest</procedure>
3378
3379Efficiently move {{rect}} by adding the given amounts to its X and Y values.
3380{{dx}} and {{dy}} must be integers.
3381The results will be clamped to the range -2147483648 to 2147483647.
3382
3383If {{dx}} and {{dy}} are already stored in an sdl2:point,
3384it is more efficient and convenient to use {{rect-add-point}} or {{rect-sub-point}},
3385instead of extracting the individual fields from the point.
3386
3387* {{rect-move}} returns a new managed sdl2:rect.
3388* {{rect-move!}} modifies and returns {{dest}}.
3389  If {{dest}} is omitted, {{rect}} is modified and returned.
3390
3391These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3392
3393
3394<procedure>(rect-add-point  rect point) → sdl2:rect</procedure>
3395<procedure>(rect-add-point! rect point #!optional dest) → dest</procedure>
3396
3397Efficiently move {{rect}} by adding {{point}} to {{rect}}'s X and Y values.
3398The results will be clamped to the range -2147483648 to 2147483647.
3399
3400If the dx and dy values are already held as separate variables,
3401it is more efficient and convenient to use {{rect-move}},
3402instead of creating an sdl2:point.
3403
3404* {{rect-add-point}} returns a new managed sdl2:rect.
3405* {{rect-add-point!}} modifies and returns {{dest}}.
3406  If {{dest}} is omitted, {{rect}} is modified and returned.
3407
3408These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3409
3410
3411<procedure>(rect-sub-point  rect point) → sdl2:rect</procedure>
3412<procedure>(rect-sub-point! rect point #!optional dest) → dest</procedure>
3413
3414Efficiently move {{rect}} by subtracting {{point}} from {{rect}}'s X and Y values.
3415The results will be clamped to the range -2147483648 to 2147483647.
3416
3417If the dx and dy values are already held as separate variables,
3418it is more efficient and convenient to negate the values and use {{rect-move}},
3419instead of creating an sdl2:point.
3420
3421* {{rect-sub-point}} returns a new managed sdl2:rect.
3422* {{rect-sub-point!}} modifies and returns {{dest}}.
3423  If {{dest}} is omitted, {{rect}} is modified and returned.
3424
3425These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3426
3427
3428<procedure>(rect-grow  rect dw dh) → sdl2:rect</procedure>
3429<procedure>(rect-grow! rect dw dh #!optional dest) → dest</procedure>
3430
3431Efficiently increase {{rect}}'s size by adding to its W and H values.
3432The rect's top left corner will stay the same.
3433See also {{rect-grow/center!}}, which keeps the rect's center point the same.
3434The results will be clamped to the range -2147483648 to 2147483647.
3435
3436{{dw}} and {{dh}} must be integers.
3437Negative numbers cause the size to decrease (i.e. shrink).
3438
3439* {{rect-grow}} returns a new managed sdl2:rect.
3440* {{rect-grow!}} modifies and returns {{dest}}.
3441  If {{dest}} is omitted, {{rect}} is modified and returned.
3442
3443These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3444
3445
3446<procedure>(rect-grow/center  rect dw dh) → sdl2:rect</procedure>
3447<procedure>(rect-grow/center! rect dw dh #!optional dest) → dest</procedure>
3448
3449Efficiently increase {{rect}}'s size while trying to keep the same center point.
3450See also {{rect-grow!}}, which keeps the rect's top left corner the same.
3451The results will be clamped to the range -2147483648 to 2147483647.
3452
3453{{dw}} and {{dh}} must be integers.
3454Negative numbers cause the size to decrease (i.e. shrink).
3455
3456For best results, use even numbers for {{dw}} and {{dh}}.
3457If {{dw}} or {{dh}} are odd numbers, the rect's center point will change by half a pixel due to rounding.
3458
3459* {{rect-grow/center}} returns a new managed sdl2:rect.
3460* {{rect-grow/center!}} modifies and returns {{dest}}.
3461  If {{dest}} is omitted, {{rect}} is modified and returned.
3462
3463These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3464
3465
3466<procedure>(rect-lerp  rect1 rect2 t) → sdl2:rect</procedure>
3467<procedure>(rect-lerp! rect1 rect2 t #!optional dest) → dest</procedure>
3468
3469Efficient linear interpolation (or extrapolation) between {{rect1}} and {{rect2}}.
3470sdl2:rect can only hold integer values, so the results will be truncated to integers.
3471The results will be clamped to the range -2147483648 to 2147483647.
3472
3473These procedures affect all values of the rect: X, Y, W, and H.
3474If you only want to interpolate the rect's position (X and Y), use {{rect-lerp-xy}} instead.
3475
3476{{t}} is the interpolation factor (a float).
3477Values of {{t}} between 0 and 1 will interpolate between {{rect1}} and {{rect2}}.
3478Values of {{t}} less that 0 will extrapolate beyond {{rect1}} (moving away from {{rect2}}).
3479Values greater that 1 will extrapolate beyond {{rect2}} (moving away from {{rect1}}).
3480
3481* {{rect-lerp}} returns a new managed sdl2:rect.
3482* {{rect-lerp!}} modifies and returns {{dest}}.
3483  If {{dest}} is omitted, {{rect1}} is modified and returned.
3484
3485These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3486
3487
3488<procedure>(rect-lerp-xy  rect1 rect2 t) → sdl2:rect</procedure>
3489<procedure>(rect-lerp-xy! rect1 rect2 t #!optional dest) → dest</procedure>
3490
3491Efficient linear interpolation (or extrapolation) between {{rect1}} and {{rect2}}.
3492sdl2:rect can only hold integer values, so the results will be truncated to integers.
3493The results will be clamped to the range -2147483648 to 2147483647.
3494
3495These procedures only affect the X and Y values of the rect.
3496The result will have the same W and H as {{rect1}}.
3497If you want interpolate all values (X, Y, W, and H), use {{rect-lerp}} instead.
3498
3499{{t}} is the interpolation factor (a float).
3500Values of {{t}} between 0 and 1 will interpolate between {{rect1}} and {{rect2}}.
3501Values of {{t}} less that 0 will extrapolate beyond {{rect1}} (moving away from {{rect2}}).
3502Values greater that 1 will extrapolate beyond {{rect2}} (moving away from {{rect1}}).
3503
3504* {{rect-lerp-xy}} returns a new managed sdl2:rect.
3505* {{rect-lerp-xy!}} modifies and returns {{dest}}.
3506  If {{dest}} is omitted, {{rect1}} is modified and returned.
3507
3508These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3509
3510
3511
3512==== sdl2:point
3513
3514sdl2:point is a record type that wraps a pointer to an
3515[[https://wiki.libsdl.org/SDL_Point|SDL_Point]] struct.
3516
3517
3518<procedure>(point? obj) → boolean</procedure>
3519
3520Returns #t if {{obj}} is an sdl2:point.
3521
3522
3523<procedure>(make-point #!optional x y) → sdl2:point</procedure>
3524<procedure>(make-point* #!optional x y) → sdl2:point</procedure>
3525
3526Allocate and initialize a new sdl2:point.
3527
3528{{x}} and {{y}} must be integers in the range -2147483648 to 2147483647 (inclusive).
3529They both default to 0.
3530
3531* {{make-point}} returns a managed sdl2:point.
3532* {{make-point*}} returns an unmanaged sdl2:point, which must be freed with {{free-point!}} when you are done with it.
3533
3534
3535<procedure>(free-point! point)</procedure>
3536
3537Free the memory of the sdl2:point's underlying struct. {{point}}'s
3538pointer will be set to null (see {{struct-null?}}). It is safe to call
3539this procedure with managed or unmanaged sdl2:points. It is safe (but
3540has no effect) to free a struct record multiple times.
3541
3542
3543<procedure>(point-x point) → integer</procedure>
3544<setter>(set! (point-x point) val)</setter>
3545<setter>(point-x-set! point val)</setter>
3546
3547Get or set the sdl2:point's "x" field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3548
3549
3550<procedure>(point-y point) → integer</procedure>
3551<setter>(set! (point-y point) val)</setter>
3552<setter>(point-y-set! point val)</setter>
3553
3554Get or set the sdl2:point's "y" field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3555
3556
3557
3558==== sdl2:point Operations
3559
3560These are operations for efficiently and conveniently working with sdl2:points.
3561Many of them are implemented in C for efficiency.
3562
3563
3564<procedure>(point-set! point #!optional x y) → point</procedure>
3565
3566Efficient and convenient way of setting multiple fields of the sdl2:point.
3567Any arguments that are {{#f}} will cause no change to that field.
3568E.g. {{(point-set! my-point 42 #f)}} will set the "x" field to 42, but will not change the "y" field.
3569Returns {{point}} after it is modified.
3570
3571
3572<procedure>(point->list point) → list of integers</procedure>
3573
3574Returns a list {{(x y)}} containing the value of each field of the sdl2:point.
3575
3576
3577<procedure>(point->values point) → [x y]</procedure>
3578
3579Returns multiple values containing the value of each field of the sdl2:point.
3580This is useful for destructuring an sdl2:point using {{receive}} or {{let-values}}.
3581
3582
3583<procedure>(point=? point1 point2) → boolean</procedure>
3584
3585Efficiently compare two sdl2:points.
3586Returns #t if the value of every field in {{point1}} is equal to the value of the corresponding field in {{point2}}.
3587
3588
3589<procedure>(point-copy src) → sdl2:point</procedure>
3590<procedure>(point-copy! src dest) → dest</procedure>
3591
3592{{point-copy}} efficiently copies the values of {{src}} into a new managed sdl2:point.
3593{{point-copy}} is available in '''sdl2 egg version 0.2.0 and higher'''.
3594In earlier versions, it was named {{copy-point}}.
3595
3596{{point-copy!}} efficiently copies the values of {{src}} into {{dest}},
3597and returns the modified {{dest}}.
3598It is safe (but useless) for {{src}} and {{dest}} to be the same object.
3599{{point-copy!}} is available in '''sdl2 egg version 0.2.0 and higher'''.
3600
3601
3602<procedure>(copy-point point) → sdl2:point</procedure>
3603
3604Deprecated alias for {{point-copy}}.
3605This alias was deprecated in sdl2 egg version 0.2.0,
3606and will be removed in a future version.
3607
3608
3609<procedure>(copy-point* point) → sdl2:point</procedure>
3610
3611Deprecated procedure.
3612This procedure was deprecated in sdl2 egg version 0.2.0,
3613and will be removed in a future version.
3614You can achieve the same effect using {{point-copy!}} and {{make-point*}}.
3615
3616
3617<procedure>(point-scale  point scale) → sdl2:point</procedure>
3618<procedure>(point-scale! point scale #!optional dest) → dest</procedure>
3619
3620Efficiently scale (multiply) the X and Y values of {{point}} by {{scale}} (a float or integer).
3621E.g. {{scale}} 0.5 halves the values, {{scale}} 2.0 doubles the values.
3622sdl2:point can only hold integer values, so the results will be truncated to integers.
3623The results will be clamped to the range -2147483648 to 2147483647.
3624
3625These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3626
3627* {{point-scale}} returns a new managed sdl2:point.
3628* {{point-scale!}} modifies and returns {{dest}}.
3629  If {{dest}} is omitted, {{point}} is modified and returned.
3630
3631
3632<procedure>(point-move  point dx dy) → sdl2:point</procedure>
3633<procedure>(point-move! point dx dy #!optional dest) → dest</procedure>
3634
3635Efficiently move {{point}} by adding the given amounts to its X and Y values.
3636{{dx}} and {{dy}} must be integers.
3637The results will be clamped to the range -2147483648 to 2147483647.
3638
3639If {{dx}} and {{dy}} are already stored in an sdl2:point,
3640it is more efficient and convenient to use {{point-add}} or {{point-sub}},
3641instead of extracting the individual fields from the point.
3642
3643* {{point-move}} returns a new managed sdl2:point.
3644* {{point-move!}} modifies and returns {{dest}}.
3645  If {{dest}} is omitted, {{point}} is modified and returned.
3646
3647These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3648
3649
3650<procedure>(point-add  point1 point2) → sdl2:point</procedure>
3651<procedure>(point-add! point1 point2 #!optional dest) → dest</procedure>
3652
3653Efficiently add {{point1}} and {{point2}} (vector addition).
3654The results will be clamped to the range -2147483648 to 2147483647.
3655
3656If the dx and dy values are already held as separate variables,
3657it is more efficient and convenient to use {{point-move}},
3658instead of creating an sdl2:point.
3659
3660* {{point-add}} returns a new managed sdl2:point.
3661* {{point-add!}} modifies and returns {{dest}}.
3662  If {{dest}} is omitted, {{point1}} is modified and returned.
3663
3664These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3665
3666
3667<procedure>(point-sub  point1 point2) → sdl2:point</procedure>
3668<procedure>(point-sub! point1 point2 #!optional dest) → dest</procedure>
3669
3670Efficiently subtract {{point2}} from {{point1}} (vector subtraction).
3671The results will be clamped to the range -2147483648 to 2147483647.
3672
3673If the dx and dy values are already held as separate variables instead,
3674it is more efficient and convenient to negate the values and use {{point-move}},
3675instead of creating an sdl2:point.
3676
3677* {{point-sub}} returns a new managed sdl2:point.
3678* {{point-sub!}} modifies and returns {{dest}}.
3679  If {{dest}} is omitted, {{point1}} is modified and returned.
3680
3681These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3682
3683
3684<procedure>(point-lerp  point1 point2 t) → sdl2:point</procedure>
3685<procedure>(point-lerp! point1 point2 t #!optional dest) → dest</procedure>
3686
3687Efficient linear interpolation (or extrapolation) between {{point1}} and {{point2}}.
3688sdl2:point can only hold integer values, so the results will be truncated to integers.
3689The results will be clamped to the range -2147483648 to 2147483647.
3690
3691{{t}} is the interpolation factor (a float).
3692Values of {{t}} between 0 and 1 will interpolate between {{point1}} and {{point2}}.
3693Values of {{t}} less that 0 will extrapolate beyond {{point1}} (moving away from {{point2}}).
3694Values greater that 1 will extrapolate beyond {{point2}} (moving away from {{point1}}).
3695
3696* {{point-lerp}} returns a new managed sdl2:point.
3697* {{point-lerp!}} modifies and returns {{dest}}.
3698  If {{dest}} is omitted, {{point1}} is modified and returned.
3699
3700These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3701
3702
3703
3704=== Renderer
3705
3706Renderer is one part of [[https://wiki.libsdl.org/CategoryRender|2D Accelerated Rendering]].
3707See also [[#texture|Texture]].
3708
3709Renderer support is available in '''sdl2 egg 0.2.0 and higher'''.
3710
3711
3712==== Renderer Functions
3713
3714<procedure>(create-renderer! window #!optional index flags) → sdl2:renderer</procedure>
3715
3716Create a new sdl2:renderer associated with the given window.
3717See [[https://wiki.libsdl.org/SDL_CreateRenderer|SDL_CreateRenderer]].
3718This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3719
3720* {{window}} must be a sdl2:window
3721* {{index}} must be an integer specifying the index of the driver to initialize,
3722  or -1 to use the first driver supporting the requested flags.
3723  It defaults to -1.
3724* {{flags}} must be a list of zero or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#renderer-flags|renderer flag symbols]].
3725  It defaults to {{'()}}.
3726** {{'software}}
3727** {{'accelerated}}
3728** {{'present-vsync}}
3729** {{'target-texture}}
3730
3731Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3732
3733
3734<procedure>(create-software-renderer! surface) → sdl2:renderer</procedure>
3735
3736Create a sdl2:renderer which renders onto the given sdl2:surface.
3737See [[https://wiki.libsdl.org/SDL_CreateSoftwareRenderer|SDL_CreateSoftwareRenderer]].
3738This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3739
3740Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3741
3742
3743<procedure>(destroy-renderer! renderer)</procedure>
3744
3745See [[https://wiki.libsdl.org/SDL_DestroyRenderer|SDL_DestroyRenderer]].
3746This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3747
3748
3749<procedure>(create-window-and-renderer! width height #!optional window-flags) → [window renderer]</procedure>
3750
3751Create a sdl2:window and a sdl2:renderer that renders to the window.
3752This is more convenient, but less flexible, than using {{create-window!}} and then {{create-renderer!}}.
3753See [[https://wiki.libsdl.org/SDL_CreateWindowAndRenderer|SDL_CreateWindowAndRenderer]].
3754This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3755
3756{{width}} and {{height}} must be inditegers specifying the height of the window and renderer to create.
3757
3758{{window-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).
3759
3760This procedure returns multiple values:
3761
3762; window   : The sdl2:window that was created.
3763; renderer : The sdl2:renderer that was created.
3764
3765
3766<procedure>(get-renderer window) → sdl2:renderer</procedure>
3767
3768Return the renderer associated with the given sdl2:window.
3769See [[https://wiki.libsdl.org/SDL_GetRenderer|SDL_GetRenderer]].
3770This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3771
3772'''NOTE:''' The returned renderer will be a new sdl2:renderer record pointing to the address of the existing renderer.
3773It will be {{equal?}} to other sdl2:renderer records for the same renderer, but not {{eq?}}.
3774
3775Signals an exception of kind {{(exn sdl2)}} if the window does not have a renderer,
3776or if an error occurs.
3777
3778
3779<procedure>(num-render-drivers) → integer</procedure>
3780
3781See [[https://wiki.libsdl.org/SDL_GetNumRenderDrivers|SDL_GetNumRenderDrivers]].
3782This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3783
3784
3785<procedure>(render-driver-info index) → sdl2:renderer-info</procedure>
3786
3787See [[https://wiki.libsdl.org/SDL_GetRenderDriverInfo|SDL_GetRenderDriverInfo]].
3788This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3789
3790
3791<procedure>(render-present!)</procedure>
3792
3793Update the renderer to show any changes that have occurred.
3794See [[https://wiki.libsdl.org/SDL_RenderPresent|SDL_RenderPresent]].
3795This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3796
3797
3798<procedure>(render-copy! renderer texture #!optional srcrect dstrect) → </procedure>
3799
3800Copy all or part of the given texture onto the renderer.
3801See [[https://wiki.libsdl.org/SDL_RenderCopy|SDL_RenderCopy]].
3802This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3803
3804* {{renderer}} is the sdl2:renderer to copy the texture to.
3805* {{texture}} is the source sdl2:texture.
3806* {{srcrect}} is a sdl2:rect specifying the part of the texture to copy, or #f to copy the whole texture. It defaults to #f.
3807* {{dstrect}} is a sdl2:rect specifying where on the renderer to copy the texture to, or #f to copy onto the entire renderer. It defaults to #f.
3808
3809Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3810
3811
3812<procedure>(render-copy-ex! renderer texture #!optional srcrect dstrect angle center flip)</procedure>
3813
3814Copy all or part of the given texture onto the renderer,
3815optionally rotating or flipping the texture.
3816See [[https://wiki.libsdl.org/SDL_RenderCopyEx|SDL_RenderCopyEx]].
3817This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3818
3819* {{renderer}} is the sdl2:renderer to copy the texture to.
3820* {{texture}} is the source sdl2:texture.
3821* {{srcrect}} is a sdl2:rect specifying the part of the texture to copy,
3822  or #f to copy the whole texture. It defaults to #f.
3823* {{dstrect}} is a sdl2:rect specifying where on the renderer to copy the texture to,
3824  or #f to copy onto the entire renderer. It defaults to #f.
3825* {{angle}} is a float specifying the angle in degrees to rotate the texture. It defaults to 0.
3826* {{center}} is an sdl2:point specifying the center (pivot) of rotation, relative to the top left corner of {{dstrect}}, or #f to rotate around the center of {{dstrect}}. It defaults to #f.
3827* {{flip}} is a list of zero, one, or two symbols indicating how to flip the texture. It defaults to {{'()}}, meaning no flipping. Supported symbols are:
3828** {{'horizontal}} = flip the texture horizontally
3829** {{'vertical}} = flip the texture vertically
3830
3831Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3832
3833
3834<procedure>(render-read-pixels-raw renderer rect format pixels-out pitch)</procedure>
3835
3836Read the pixels from some or all of the given renderer.
3837This is for advanced users, and must be used with caution.
3838See [[https://wiki.libsdl.org/SDL_RenderReadPixels|SDL_RenderReadPixels]].
3839This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3840
3841* {{renderer}} is the sdl2:renderer to read from.
3842* {{rect}} is a sdl2:rect specifying the part of the renderer to read, or #f to read the entire renderer.
3843* {{format}} is a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]] or equivalent integer, specifying the desired format of the pixel data.
3844* {{pixels-out}} is a pointer or locative where the pixel data will be written.
3845  It must point to a block of memory large enough to hold all the requested pixel data,
3846  or your program may crash or other bad things happen.
3847* {{pitch}} is an integer specifying the pitch of the pixel data.
3848
3849
3850<procedure>(render-clear! renderer)</procedure>
3851
3852Clear the entire renderer, using the renderer's current draw color.
3853See [[https://wiki.libsdl.org/SDL_RenderClear|SDL_RenderClear]].
3854This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3855
3856
3857<procedure>(render-draw-line! renderer x1 y1 x2 y2)</procedure>
3858<procedure>(render-draw-lines! renderer points)</procedure>
3859
3860Draw a line segment or multiple line segments, using the renderer's current draw color and blend mode.
3861See [[https://wiki.libsdl.org/SDL_RenderDrawLine|SDL_RenderDrawLine]]
3862and [[https://wiki.libsdl.org/SDL_RenderDrawLines|SDL_RenderDrawLines]].
3863These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3864
3865* {{render-draw-line!}} draws a single line segment.
3866* {{render-draw-lines!}} draws multiple line segments (from point 0 to point 1, point 1 to point 2, etc.). {{points}} must be a list or vector of sdl2:point instances.
3867
3868
3869<procedure>(render-draw-point! renderer x y)</procedure>
3870<procedure>(render-draw-points! renderer points)</procedure>
3871
3872Draw one or multiple points, using the renderer's current draw color and blend mode.
3873See [[https://wiki.libsdl.org/SDL_RenderDrawPoint|SDL_RenderDrawPoint]]
3874and [[https://wiki.libsdl.org/SDL_RenderDrawPoints|SDL_RenderDrawPoints]].
3875These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3876
3877* {{render-draw-point!}} draws a single point.
3878* {{render-draw-points!}} draws multiple points. {{points}} must be a list or vector of sdl2:point instances.
3879
3880
3881<procedure>(render-draw-rect! renderer rect)</procedure>
3882<procedure>(render-draw-rects! renderer rects)</procedure>
3883
3884Draw one or multiple outlined rectangles, using the renderer's current draw color and blend mode.
3885See [[https://wiki.libsdl.org/SDL_RenderDrawRect|SDL_RenderDrawRect]]
3886and [[https://wiki.libsdl.org/SDL_RenderDrawRects|SDL_RenderDrawRects]].
3887These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3888
3889* {{render-draw-rect!}} draws a single outlined rect.
3890* {{render-draw-rects!}} draws multiple outlined rects. {{rects}} must be a list or vector of sdl2:rect instances.
3891
3892
3893<procedure>(render-fill-rect! renderer rect)</procedure>
3894<procedure>(render-fill-rects! renderer rects)</procedure>
3895
3896Draw one or multiple filled rectangles, using the renderer's current draw color and blend mode.
3897See [[https://wiki.libsdl.org/SDL_RenderFillRect|SDL_RenderFillRect]]
3898and [[https://wiki.libsdl.org/SDL_RenderFillRects|SDL_RenderFillRects]].
3899These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3900
3901* {{render-draw-rect!}} draws a single filled rect.
3902* {{render-draw-rects!}} draws multiple filled rects. {{rects}} must be a list or vector of sdl2:rect instances.
3903
3904
3905
3906==== sdl2:renderer
3907
3908sdl2:renderer is a record type that wraps a pointer to an SDL_Renderer struct.
3909sdl2:renderer is available in '''sdl2 egg version 0.2.0 and higher'''.
3910
3911
3912<procedure>(renderer? obj) → boolean</procedure>
3913
3914Returns #t if {{obj}} is an sdl2:renderer.
3915This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3916
3917
3918<procedure>(render-draw-blend-mode renderer) → symbol</procedure>
3919<procedure>(render-draw-blend-mode-raw renderer) → integer</procedure>
3920<setter>(render-draw-blend-mode-set! renderer mode)</setter>
3921<setter>(set! (render-draw-blend-mode renderer) mode)</setter>
3922
3923Get or set the renderer's draw blend mode. This affects future drawing operations.
3924See [[https://wiki.libsdl.org/SDL_GetRenderDrawBlendMode|SDL_GetRenderDrawBlendMode]]
3925and [[https://wiki.libsdl.org/SDL_SetRenderDrawBlendMode|SDL_SetRenderDrawBlendMode]].
3926These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3927
3928* {{render-draw-blend-mode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-mode|blend mode symbol]]:
3929** {{'none}}
3930** {{'blend}}
3931** {{'add}}
3932** {{'mod}}
3933* {{render-draw-blend-mode-raw}} returns an integer.
3934* The setters accept either a symbol or integer.
3935
3936
3937<procedure>(render-draw-color renderer) → sdl2:color</procedure>
3938<procedure>(render-draw-colour renderer) → sdl2:color</procedure>
3939<setter>(render-draw-color-set! renderer color)</setter>
3940<setter>(render-draw-colour-set! renderer color)</setter>
3941<setter>(set! (render-draw-color renderer) color)</setter>
3942<setter>(set! (render-draw-colour renderer) color)</setter>
3943
3944Get or set the renderer's draw color. This affects future drawing operations.
3945See [[https://wiki.libsdl.org/SDL_GetRenderDrawColor|SDL_GetRenderDrawColor]]
3946and [[https://wiki.libsdl.org/SDL_SetRenderDrawColor|SDL_SetRenderDrawColor]].
3947These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3948
3949
3950<procedure>(render-clip-rect renderer) → sdl2:rect</procedure>
3951<setter>(render-clip-rect-set! renderer rect)</setter>
3952<setter>(set! (render-clip-rect renderer) rect)</setter>
3953
3954Get or set the sdl2:renderer's clip rect.
3955See [[https://wiki.libsdl.org/SDL_RenderGetClipRect|SDL_RenderGetClipRect]]
3956and [[https://wiki.libsdl.org/SDL_RenderSetClipRect|SDL_RenderSetClipRect]].
3957These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3958
3959{{render-clip-rect}} returns a new managed sdl2:rect describing the renderer's clip rect.
3960If clipping is disabled, it returns {{#<sdl2:rect (0 0 0 0)>}}.
3961
3962But, be advised that it also returns {{#<sdl2:rect (0 0 0 0)>}} if that is the current clip rect.
3963So, the meaning of {{#<sdl2:rect (0 0 0 0)>}} is ambiguous.
3964Use {{render-clip-enabled?}} (in SDL 2.0.4 or higher) to unambiguously check whether clipping is enabled or disabled.
3965
3966The setters accept either an sdl2:rect to enable clipping and set the clip rect,
3967or #f to disable clipping.
3968Setting to {{#<sdl2:rect (0 0 0 0)>}} does not disable clipping.
3969
3970
3971<procedure>(render-clip-enabled? renderer) → boolean</procedure>
3972
3973Returns #t if clipping is enabled for the given sdl2:renderer,
3974or #f is clipping is disabled.
3975See [[https://wiki.libsdl.org/SDL_RenderIsClipEnabled|SDL_RenderIsClipEnabled]].
3976This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3977
3978Requires '''SDL 2.0.4 or higher'''.
3979Signals an error if the compiled version of SDL is not high enough.
3980Use the [[#version-feature-identifiers|{{libSDL-2.0.4+}} feature identifier]]
3981to check before calling this procedure.
3982
3983
3984<procedure>(renderer-output-size renderer) → [w h]</procedure>
3985
3986See [[https://wiki.libsdl.org/SDL_GetRendererOutputSize|SDL_GetRendererOutputSize]].
3987This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3988
3989This procedure returns multiple values, the output width and height, as integers.
3990
3991
3992<procedure>(render-logical-size renderer) → [w h]</procedure>
3993<setter>(render-logical-size-set! renderer size)</setter>
3994<setter>(set! (render-logical-size renderer) size)</setter>
3995
3996Get or set the renderer's logical size.
3997See [[https://wiki.libsdl.org/SDL_RenderGetLogicalSize|SDL_RenderGetLogicalSize]]
3998and [[https://wiki.libsdl.org/SDL_RenderSetLogicalSize|SDL_RenderSetLogicalSize]].
3999These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4000
4001* {{render-logical-size}} returns multiple values, the logical width and height, as integers.
4002* The setters accept a list {{(w h)}} containing the new logical width and height, as integers.
4003
4004
4005<procedure>(render-scale renderer) → [x-scale y-scale]</procedure>
4006<setter>(render-scale-set! renderer scales)</setter>
4007<setter>(set! (render-scale-set! renderer) scales)</setter>
4008
4009Get or set the sdl2:renderer's x and y scaling factors.
4010See [[https://wiki.libsdl.org/SDL_RenderGetScale|SDL_RenderGetScale]]
4011and [[https://wiki.libsdl.org/SDL_RenderSetScale|SDL_RenderSetScale]].
4012These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4013
4014* {{render-scale}} returns multiple values, the x and y scaling factors, as integers..
4015* The setters accept a list {{(x-scale y-scale)}} containing the new scaling factors, as integers.
4016
4017
4018<procedure>(render-target-supported? renderer) → boolean</procedure>
4019
4020Returns #t if the given renderer can have a render target.
4021See [[https://wiki.libsdl.org/SDL_RenderTargetSupported|SDL_RenderTargetSupported]].
4022This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4023
4024
4025<procedure>(render-target renderer) → sdl2:texture or #f</procedure>
4026<setter>(render-target-set! renderer target)</setter>
4027<setter>(set! (render-target renderer) target)</setter>
4028
4029Get or set the renderer's render target,
4030i.e. the texture that the renderer will render onto.
4031See [[https://wiki.libsdl.org/SDL_GetRenderTarget|SDL_GetRenderTarget]]
4032and [[https://wiki.libsdl.org/SDL_SetRenderTarget|SDL_SetRenderTarget]].
4033These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4034
4035{{render-target}} returns #f if the renderer has no render target.
4036
4037The setters signal an exception of kind {{(exn sdl2)}} on failure,
4038for example if the renderer does not support a render target.
4039You should use {{render-target-supported?}} to test whether the renderer supports a render target.
4040
4041
4042<procedure>(render-viewport renderer) → sdl2:rect</procedure>
4043<setter>(render-viewport-set! renderer rect)</setter>
4044<setter>(set! (render-viewport renderer) rect)</setter>
4045
4046Get or set the renderer's viewport.
4047See [[https://wiki.libsdl.org/SDL_RenderGetViewport|SDL_RenderGetViewport]]
4048and [[https://wiki.libsdl.org/SDL_RenderSetViewport|SDL_RenderSetViewport]].
4049These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4050
4051
4052
4053==== sdl2:renderer-info
4054
4055sdl2:renderer-info is a record type that wraps a pointer to an
4056[[https://wiki.libsdl.org/SDL_RendererInfo|SDL_RendererInfo]] struct.
4057sdl2:renderer-info is available in '''sdl2 egg version 0.2.0 and higher'''.
4058
4059<procedure>(renderer-info? obj) → boolean</procedure>
4060
4061Returns #t if {{obj}} is an sdl2:renderer-info.
4062This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4063
4064
4065<procedure>(get-renderer-info renderer) → sdl2:renderer-info</procedure>
4066<procedure>(get-renderer-info* renderer) → sdl2:renderer-info</procedure>
4067
4068Return a sdl2:renderer-info with information about the given sdl2:renderer.
4069See [[https://wiki.libsdl.org/SDL_GetRendererInfo|SDL_GetRendererInfo]].
4070These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4071
4072* {{get-renderer-info}} returns a managed sdl2:renderer-info.
4073* {{get-renderer-info*}} returns an unmanaged sdl2:renderer-info, which must be freed using {{free-renderer-info!}} when you are done with it.
4074
4075
4076<procedure>(free-renderer-info! renderer-info)</procedure>
4077
4078Free the memory of the sdl2:renderer-info's underlying struct.
4079{{renderer-info}}'s pointer will be set to null (see {{struct-null?}}).
4080It is safe to call this procedure with managed or unmanaged sdl2:renderer-infos.
4081It is safe (but has no effect) to free a struct record multiple times.
4082This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4083
4084
4085<procedure>(renderer-info-name renderer-info) → string</procedure>
4086
4087Get the sdl2:renderer-info's "name" field, as a string.
4088This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4089
4090
4091<procedure>(renderer-info-flags renderer-info) → list of symbols</procedure>
4092<procedure>(renderer-info-flags-raw renderer-info) → integer</procedure>
4093
4094Get the sdl2:renderer-info's "flags" field, as a list of symbols or an integer.
4095TODO: Link to flags enums.
4096These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4097
4098
4099<procedure>(renderer-info-num-texture-formats renderer-info) → integer</procedure>
4100
4101Get the sdl2:renderer-info's "num-texture-formats" field, as an integer.
4102This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4103
4104
4105<procedure>(renderer-info-texture-formats renderer-info) → list of symbols</procedure>
4106
4107Get the sdl2:renderer-info's "texture-formats" field,
4108as a list of [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbols]].
4109This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4110
4111
4112<procedure>(renderer-info-max-texture-width renderer-info) → integer</procedure>
4113
4114Get the sdl2:renderer-info's "max-texture-width" field, as an integer.
4115This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4116
4117
4118<procedure>(renderer-info-max-texture-height renderer-info) → integer</procedure>
4119
4120Get the sdl2:renderer-info's "max-texture-height" field, as an integer.
4121This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4122
4123
4124
4125=== RWops
4126
4127==== RWops Functions
4128
4129<procedure>(rw-from-file filepath) → sdl2:rwops</procedure>
4130
4131See [[https://wiki.libsdl.org/SDL_RWFromFile|SDL_RWFromFile]].
4132
4133You should close the sdl2:rwops when you are done with it, using
4134{{rw-close!}} or one of the procedures that can automatically close
4135the sdl2:rwops, such as {{load-bmp-rw}}.
4136
4137Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4138
4139
4140<procedure>(rw-from-const-mem pointer) → sdl2:rwops</procedure>
4141
4142See [[https://wiki.libsdl.org/SDL_RWFromConstMem|SDL_RWFromConstMem]].
4143
4144You should close the sdl2:rwops when you are done with it, using
4145{{rw-close!}} or one of the procedures that can automatically close
4146the sdl2:rwops, such as {{load-bmp-rw}}.
4147
4148Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4149
4150
4151<procedure>(rw-from-mem pointer) → sdl2:rwops</procedure>
4152
4153See [[https://wiki.libsdl.org/SDL_RWFromMem|SDL_RWFromMem]].
4154
4155You should close the sdl2:rwops when you are done with it, using
4156{{rw-close!}} or one of the procedures that can automatically close
4157the sdl2:rwops, such as {{load-bmp-rw}}.
4158
4159Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4160
4161
4162<procedure>(rw-from-blob blob) → sdl2:rwops</procedure>
4163
4164Create a new sdl2:rwops that accesses the memory of the given
4165[[http://wiki.call-cc.org/manual/Unit%20library#blobs|blob]]. You
4166should close the sdl2:rwops when you are done with it, using
4167{{rw-close!}} or one of the procedures that can automatically close
4168the sdl2:rwops, such as {{load-bmp-rw}}.
4169
4170Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4171
4172You can also use this procedure to create a sdl2:rwops from a
4173[[/manual/Unit srfi-4|SRFI-4]] numeric vector, by first converting it
4174to a blob using e.g. {{u8vector->blob/shared}}.
4175
4176'''CAUTION:''' Creating a sdl2:rwops from a blob in CHICKEN-managed
4177memory is unstable: the blob might be garbage collected or moved in
4178memory, which would break the sdl2:rwops. To be safe, you should
4179[[/manual/Unit lolevel#object-evict|evict]] the blob and create the
4180sdl2:rwops from the evicted blob (not the original). You may wish to
4181[[/manual/Unit lolevel#object-release|release]] the evicted blob after
4182you have closed the sdl2:rwops. Example:
4183
4184<enscript highlight="scheme">
4185(let* ((evicted-blob (object-evict '#${...}))
4186       (rwops (sdl2:rw-from-blob evicted-blob))
4187       (surf (sdl2:load-bmp-rw rwops #t)))
4188  (object-release evicted-blob)
4189  surf)
4190</enscript>
4191
4192
4193<procedure>(rw-from-string str) → sdl2:rwops</procedure>
4194
4195Create a new sdl2:rwops that accesses the memory of the given CHICKEN
4196Scheme string. You should close the sdl2:rwops when you are done with
4197it, using {{rw-close!}} or one of the procedures that can
4198automatically close the sdl2:rwops, such as {{load-bmp-rw}}.
4199
4200Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4201
4202'''CAUTION:''' Creating a sdl2:rwops from a string in CHICKEN-managed
4203memory is unstable: the string might be garbage collected or moved in
4204memory, which would break the sdl2:rwops. To be safe, you should
4205[[/manual/Unit lolevel#object-evict|evict]] the string and create the
4206sdl2:rwops from the evicted string (not the original). You may wish to
4207[[/manual/Unit lolevel#object-release|release]] the evicted string
4208after you have closed the sdl2:rwops. Example:
4209
4210<enscript highlight="scheme">
4211(let* ((evicted-string (object-evict "..."))
4212       (rwops (sdl2:rw-from-string evicted-string))
4213       (surf (sdl2:load-bmp-rw rwops #t)))
4214  (object-release evicted-string)
4215  surf)
4216</enscript>
4217
4218
4219<procedure>(rw-close! rwops)</procedure>
4220
4221See [[https://wiki.libsdl.org/SDL_RWclose|SDL_RWclose]].
4222
4223Close and clean up the given sdl2:rwops. This frees the memory used by
4224the SDL_RWops struct itself, but does not free or release the pointer,
4225blob, or string that the sdl2:rwops was reading/writing from. (It does
4226close files opened with {{rw-from-file}}, though.)
4227
4228Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4229
4230
4231==== sdl2:rwops
4232
4233sdl2:rwops is a record type that wraps a pointer to an
4234[[https://wiki.libsdl.org/SDL_RWops|SDL_RWops]] struct.
4235
4236
4237<procedure>(rwops? obj) → boolean</procedure>
4238
4239Returns #t if {{obj}} is an sdl2:rwops.
4240
4241
4242<procedure>(rwops-type rwops) → symbol</procedure>
4243<procedure>(rwops-type-raw rwops) → integer</procedure>
4244
4245Get the sdl2:rwops' "type" field, indicating the data source type.
4246
4247* {{rwops-type}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#rwops-types|RWops type symbol]]:
4248** {{'unknown}}
4249** {{'win-file}}
4250** {{'std-file}}
4251** {{'jni-file}}
4252** {{'memory}}
4253** {{'memory-ro}}
4254* {{rwops-type-raw}} returns an integer.
4255
4256
4257
4258=== Surface
4259
4260==== Surface Functions
4261
4262<procedure>(create-rgb-surface* flags width height depth rmask gmask bmask amask) → sdl2:surface</procedure>
4263
4264See [[https://wiki.libsdl.org/SDL_CreateRGBSurface|SDL_CreateRGBSurface]].
4265
4266Returns a new '''unmanaged''' sdl2:surface with the given properties.
4267You must call {{free-surface!}} when you are done with it.
4268
4269See {{make-surface}} for a more convenient interface.
4270
4271Signals an exception of kind {{(exn sdl2)}} if the surface cannot be created.
4272
4273
4274<procedure>(create-rgb-surface-from* pixels width height depth pitch rmask gmask bmask amask) → sdl2:surface</procedure>
4275
4276Returns a new '''unmanaged''' sdl2:surface with the given properties,
4277using existing pixel data (a pointer, e.g. from {{surface-pixels-raw}}).
4278You must call {{free-surface!}} when you are done with it.
4279
4280See [[https://wiki.libsdl.org/SDL_CreateRGBSurfaceFrom|SDL_CreateRGBSurfaceFrom]].
4281
4282Signals an exception of kind {{(exn sdl2)}} if the surface cannot be created.
4283
4284
4285<procedure>(convert-surface surface pixel-format) → sdl2:surface</procedure>
4286<procedure>(convert-surface* surface pixel-format) → sdl2:surface</procedure>
4287
4288Creates a copy of the given sdl2:surface, but converts it to the given sdl2:pixel-format.
4289
4290See [[https://wiki.libsdl.org/SDL_ConvertSurface|SDL_ConvertSurface]].
4291
4292* {{convert-surface}} returns a managed sdl2:surface.
4293* {{convert-surface*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
4294
4295Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4296
4297
4298<procedure>(load-bmp  filepath) → sdl2:surface</procedure>
4299<procedure>(load-bmp* filepath) → sdl2:surface</procedure>
4300
4301See [[https://wiki.libsdl.org/SDL_LoadBMP|SDL_LoadBMP]].
4302
4303Attempts to load a BMP image file.
4304Returns a sdl2:surface containing the image data.
4305Signals an exception of kind {{(exn sdl2)}} if the image could not be loaded.
4306
4307'''NOTE:''' This procedure only supports certain kinds of BMP image.
4308Use the [[/egg/sdl2-image|sdl2-image egg]] for better BMP support,
4309plus support for loading other image formats like JPG, PNG, and GIF.
4310
4311* {{load-bmp}} returns a managed sdl2:surface.
4312* {{load-bmp*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
4313
4314
4315<procedure>(load-bmp-rw  rwops #!optional close?) → sdl2:surface</procedure>
4316<procedure>(load-bmp-rw* rwops #!optional close?) → sdl2:surface</procedure>
4317
4318See [[https://wiki.libsdl.org/SDL_LoadBMP_RW|SDL_LoadBMP_RW]].
4319
4320Attempts to load a BMP image from the given sdl2:rwops.
4321Returns a sdl2:surface containing the image data.
4322Signals an exception of kind {{(exn sdl2)}} if the image could not be loaded.
4323
4324If {{close?}} is #t, {{rwops}} will be automatically closed (see
4325{{rw-close!}}) after the image is loaded. If {{close?}} is #f or
4326omitted, {{rwops}} will not be closed.
4327
4328'''NOTE:''' This procedure only supports certain kinds of BMP image.
4329Use the [[/egg/sdl2-image|sdl2-image egg]] for better BMP support,
4330plus support for loading other image formats like JPG, PNG, and GIF.
4331
4332* {{load-bmp-rw}} returns a managed sdl2:surface.
4333* {{load-bmp-rw*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
4334
4335
4336<procedure>(save-bmp! surface filepath)</procedure>
4337
4338See [[https://wiki.libsdl.org/SDL_SaveBMP|SDL_SaveBMP]].
4339
4340Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4341
4342
4343<procedure>(save-bmp-rw! surface rwops #!optional close?)</procedure>
4344
4345See [[https://wiki.libsdl.org/SDL_SaveBMP_RW|SDL_SaveBMP_RW]].
4346
4347If {{close?}} is #t, {{rwops}} will be automatically closed (see
4348{{rw-close!}}) after the image is loaded. If {{close?}} is #f or
4349omitted, {{rwops}} will not be closed.
4350
4351Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4352
4353
4354<procedure>(lock-surface! surface)</procedure>
4355<procedure>(unlock-surface! surface)</procedure>
4356
4357See [[https://wiki.libsdl.org/SDL_LockSurface|SDL_LockSurface]]
4358and [[https://wiki.libsdl.org/SDL_UnlockSurface|SDL_UnlockSurface]].
4359
4360{{lock-surface!}} signals an exception of kind {{(exn sdl2)}} if an error occurs.
4361
4362
4363<procedure>(must-lock? surface) → boolean</procedure>
4364
4365See [[https://wiki.libsdl.org/SDL_MUSTLOCK|SDL_MUSTLOCK]].
4366
4367
4368<procedure>(blit-surface! src src-rect dest dest-rect)</procedure>
4369
4370See [[https://wiki.libsdl.org/SDL_BlitSurface|SDL_BlitSurface]].
4371
4372May modify dest-rect.
4373
4374Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4375
4376
4377<procedure>(blit-scaled! src src-rect dest dest-rect)</procedure>
4378
4379See [[https://wiki.libsdl.org/SDL_BlitScaled|SDL_BlitScaled]].
4380
4381May modify dest-rect.
4382
4383Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4384
4385
4386<procedure>(fill-rect! surface rect color)</procedure>
4387
4388See [[https://wiki.libsdl.org/SDL_FillRect|SDL_FillRect]].
4389
4390{{rect}} may be an sdl2:rect to fill part of the surface, or #f to fill
4391the entire surface.
4392
4393{{color}} may be an sdl2:color or a mapped color (an integer, like
4394returned by {{map-rgba}}).
4395
4396Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4397
4398
4399<procedure>(fill-rects! surface rects color)</procedure>
4400
4401See [[https://wiki.libsdl.org/SDL_FillRects|SDL_FillRects]].
4402
4403{{rects}} must be a list of sdl2:rects.
4404
4405{{color}} may be an sdl2:color or a mapped color (an integer, like
4406returned by {{map-rgba}}).
4407
4408Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4409
4410
4411<procedure>(surface-ref surface x y) → sdl2:color</procedure>
4412<procedure>(surface-ref-raw surface x y) → integer</procedure>
4413<setter>(set! (surface-ref surface x y) color)</setter>
4414<setter>(surface-set! surface x y color)</setter>
4415
4416Get or set the color of the specified pixel on the surface.
4417
4418* {{surface-ref}} returns an sdl2:color.
4419* {{surface-ref-raw}} returns a mapped color (an integer). You can use {{get-rgba}} to convert the mapped color to color fields.
4420* The setters accept either an sdl2:color or a mapped color.
4421
4422These procedures automatically lock and unlock the surface if needed.
4423They signal an exception of kind {{(exn sdl2)}} if the surface cannot be locked.
4424
4425These procedures signal an exception of kind {{(exn bounds)}} if {{x}} or {{y}} is out of bounds.
4426
4427The setters ignore the surface's clip rect.
4428
4429
4430<procedure>(rotate-surface-90  surface turns) → sdl2:surface</procedure>
4431<procedure>(rotate-surface-90* surface turns) → sdl2:surface</procedure>
4432
4433Return a copy of the given surface rotated by the given number of 90º clockwise turns.
4434{{turns}} must be an integer.
4435For example:
4436
4437* {{turns}} 0 means no rotation
4438* {{turns}} 1 means 90º clockwise rotation
4439* {{turns}} 2 means 180º rotation
4440* {{turns}} 3 (or -1) means 270º clockwise (i.e. 90º counter-clockwise) rotation
4441
4442The new surface will have an equivalent pixel format, color key, blend mode, alpha mod, and color mod as the given surface.
4443If the given surface has a palette, the new surface will share the same palette.
4444The new surface will have no clip rect.
4445
4446Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4447
4448* {{rotate-surface-90}} returns a managed sdl2:surface.
4449* {{rotate-surface-90*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
4450
4451
4452<procedure>(flip-surface  surface flip-x? flip-y?) → sdl2:surface</procedure>
4453<procedure>(flip-surface* surface flip-x? flip-y?) → sdl2:surface</procedure>
4454
4455Return a copy of the given surface flipped on the X (horizontal) and/or Y (vertical) axes.
4456
4457The new surface will have an equivalent pixel format, color key, blend mode, alpha mod, and color mod as the given surface.
4458If the given surface has a palette, the new surface will share the same palette.
4459The new surface will have no clip rect.
4460
4461Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4462
4463* {{flip-surface}} returns a managed sdl2:surface.
4464* {{flip-surface*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
4465
4466
4467
4468==== sdl2:surface
4469
4470sdl2:surface is a record type that wraps a pointer to an
4471[[https://wiki.libsdl.org/SDL_Surface|SDL_Surface]] struct.
4472
4473
4474<procedure>(surface? obj) → boolean</procedure>
4475
4476Returns #t if {{obj}} is an sdl2:surface.
4477
4478
4479<procedure>(make-surface width height depth) → sdl2:surface</procedure>
4480<procedure>(make-surface* width height depth) → sdl2:surface</procedure>
4481
4482Create a new sdl2:surface with the given width, height, and color depth (bits per pixel).
4483This is a more convenient interface for {{create-rgb-surface}}.
4484The sdl2:surface's pixel format and masks will be chosen automatically
4485based on the requested depth and the current platform's byte order (little endian or big endian).
4486
4487These procedures signal an exception of kind {{(exn sdl2)}}
4488if the sdl2:surface could not be created (e.g. because the color depth is unsupported).
4489
4490* {{make-surface}} returns a managed sdl2:surface.
4491* {{make-surface*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
4492
4493
4494<procedure>(free-surface! surface)</procedure>
4495
4496Free the memory of the sdl2:surface's underlying struct. {{surface}}'s
4497pointer will be set to null (see {{struct-null?}}). It is safe to call
4498this procedure with managed or unmanaged sdl2:surfaces. It is safe
4499(but has no effect) to free a struct record multiple times.
4500
4501See [[https://wiki.libsdl.org/SDL_FreeSurface|SDL_FreeSurface]].
4502
4503'''NOTE:''' if {{surface}} was created using
4504{{create-rgb-surface-from}}, then the pixel data is not freed.
4505
4506
4507<procedure>(surface-format surface) → sdl2:pixel-format</procedure>
4508
4509Get the sdl2:surface's "format" field, as a sdl2:pixel-format describing the format of the surface's pixels.
4510
4511
4512<procedure>(surface-w surface) → integer</procedure>
4513
4514Get the sdl2:surface's "w" field, as a nonnegative integer indicating the surface's width in pixels.
4515
4516
4517<procedure>(surface-h surface) → integer</procedure>
4518
4519Get the sdl2:surface's "h" field, as a nonnegative integer indicating the surface's height in pixels.
4520
4521
4522<procedure>(surface-pitch surface) → integer</procedure>
4523
4524Get the sdl2:surface's "pitch" field, as a nonnegative integer indicating how many bytes are used to represent one row of pixel data.
4525
4526
4527<procedure>(surface-pixels-raw surface) → pointer or #f</procedure>
4528
4529Get the sdl2:surface's "pixels" field, as a raw pointer to the sdl2:surface's pixels.
4530Don't use this unless you really know what you are doing!
4531
4532If you want to get or set a pixel, use {{surface-ref}} and {{surface-set!}} instead.
4533They are much safer, more convenient, and more efficient than accessing the pixel data using this pointer.
4534
4535
4536<procedure>(surface-userdata-raw surface) → pointer or #f</procedure>
4537<setter>(set! (surface-userdata-raw surface) val)</setter>
4538<setter>(surface-userdata-raw-set! surface val)</setter>
4539
4540Get or set the sdl2:surface's "userdata" field, as a pointer or #f.
4541
4542If you want to store a pointer to a Scheme object here, be sure to
4543[[/manual/Unit lolevel#object-evict|evict the object]] first. Otherwise
4544the object's location in memory might change, rendering the pointer
4545invalid.
4546
4547
4548<procedure>(surface-refcount surface) → integer</procedure>
4549<setter>(set! (surface-refcount surface) val)</setter>
4550<setter>(surface-refcount-set! surface val)</setter>
4551
4552Get or set the sdl2:surface's "refcount" field, as an integer.
4553
4554
4555<procedure>(surface-clip-rect surface) → sdl2:rect</procedure>
4556<setter>(set! (surface-clip-rect surface) rect) → boolean</setter>
4557<setter>(surface-clip-rect-set! surface rect) → boolean</setter>
4558
4559{{surface-clip-rect}} returns a copy of the surface's clip rect.
4560See [[https://wiki.libsdl.org/SDL_GetClipRect|SDL_GetClipRect]].
4561
4562The setters sets the surface's clip rect to a copy of the given rect.
4563{{rect}} may be #f, which disables clipping.
4564See [[https://wiki.libsdl.org/SDL_SetClipRect|SDL_SetClipRect]].
4565
4566The 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).
4567
4568
4569<procedure>(surface-color-key surface) → sdl2:color or #f</procedure>
4570<procedure>(surface-colour-key surface) → sdl2:color or #f</procedure>
4571<procedure>(surface-color-key-raw surface) → integer or #f</procedure>
4572<procedure>(surface-colour-key-raw surface) → integer or #f</procedure>
4573<setter>(set! (surface-color-key surface) color)</setter>
4574<setter>(set! (surface-colour-key surface) color)</setter>
4575<setter>(surface-color-key-set! surface color)</setter>
4576<setter>(surface-colour-key-set! surface color)</setter>
4577
4578Get or set the sdl2:surface's color key.
4579
4580See [[https://wiki.libsdl.org/SDL_GetColorKey|SDL_GetColorKey]]
4581and [[https://wiki.libsdl.org/SDL_SetColorKey|SDL_SetColorKey]].
4582
4583* {{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.
4584* {{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.
4585* The setters accept either an sdl2:color, a mapped color (an integer), or #f to disable color keying.
4586
4587These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4588
4589
4590<procedure>(surface-alpha-mod surface) → integer</procedure>
4591<setter>(set! (surface-alpha-mod surface) mod)</setter>
4592<setter>(surface-alpha-mod-set! surface mod)</setter>
4593
4594See [[https://wiki.libsdl.org/SDL_GetSurfaceAlphaMod|SDL_GetSurfaceAlphaMod]]
4595and [[https://wiki.libsdl.org/SDL_SetSurfaceAlphaMod|SDL_SetSurfaceAlphaMod]].
4596
4597These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4598
4599
4600<procedure>(surface-blend-mode surface) → symbol</procedure>
4601<procedure>(surface-blend-mode-raw surface) → integer</procedure>
4602<setter>(set! (surface-blend-mode surface) mode)</setter>
4603<setter>(surface-blend-mode-set! surface mode)</setter>
4604
4605See [[https://wiki.libsdl.org/SDL_GetSurfaceBlendMode|SDL_GetSurfaceBlendMode]]
4606and [[https://wiki.libsdl.org/SDL_SetSurfaceBlendMode|SDL_SetSurfaceBlendMode]].
4607
4608* {{surface-blend-mode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-mode|blend mode symbol]]:
4609** {{'none}}
4610** {{'blend}}
4611** {{'add}}
4612** {{'mod}}
4613* {{surface-blend-mode-raw}} returns an integer.
4614* The setters accept either a symbol or integer.
4615
4616These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4617
4618
4619<procedure>(surface-color-mod surface) → [r g b]</procedure>
4620<procedure>(surface-colour-mod surface) → [r g b]</procedure>
4621<setter>(set! (surface-color-mod surface) rgb)</setter>
4622<setter>(set! (surface-colour-mod surface) rgb)</setter>
4623<setter>(surface-color-mod-set! surface rgb)</setter>
4624<setter>(surface-colour-mod-set! surface rgb)</setter>
4625
4626See [[https://wiki.libsdl.org/SDL_GetSurfaceColorMod|SDL_GetSurfaceColorMod]]
4627and [[https://wiki.libsdl.org/SDL_SetSurfaceColorMod|SDL_SetSurfaceColorMod]].
4628
4629{{surface-color-mod}} and {{surface-colour-mod}} return multiple values.
4630
4631The setters accept either a list {{(r g b)}} of color values, or an sdl2:color (the sdl2:color's "a" field will be ignored).
4632
4633These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4634
4635
4636<procedure>(surface-palette surface) → sdl2:palette or #f</procedure>
4637<setter>(set! (surface-palette surface) palette)</setter>
4638<setter>(surface-palette-set! surface palette)</setter>
4639
4640{{surface-palette}} returns the surface's palette, or #f if it has no palette.
4641It is equivalent to {{(compose pixel-format-palette surface-format)}}.
4642
4643The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
4644
4645See [[https://wiki.libsdl.org/SDL_SetSurfacePalette|SDL_SetSurfacePalette]].
4646
4647
4648<setter>(surface-rle-set! surface enable?)</setter>
4649
4650Enable RLE acceleration if {{enable?}} is #t, or disable RLE acceleration if {{enable?}} is #f.
4651See [[https://wiki.libsdl.org/SDL_SetSurfaceRLE|SDL_SetSurfaceRLE]].
4652
4653Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4654
4655
4656
4657=== Texture
4658
4659Texture is one part of [[https://wiki.libsdl.org/CategoryRender|2D Accelerated Rendering]].
4660See also [[#renderer|Renderer]].
4661
4662Renderer support is available in '''sdl2 egg 0.2.0 and higher'''.
4663
4664
4665==== sdl2:texture
4666
4667sdl2:texture is a record type that wraps a pointer to an
4668[[https://wiki.libsdl.org/SDL_Texture|SDL_Texture]] struct.
4669
4670Textures are available in '''sdl2 egg version 0.2.0 and higher'''.
4671
4672
4673<procedure>(texture? obj) → boolean</procedure>
4674
4675Returns #t if {{obj}} is an sdl2:texture.
4676
4677This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4678
4679
4680<procedure>(create-texture renderer format access w h) → sdl2:texture</procedure>
4681<procedure>(create-texture* renderer format access w h) → sdl2:texture</procedure>
4682
4683Create a new sdl2:texture using the given sdl2:renderer and settings.
4684
4685* {{renderer}} must be a sdl2:renderer.
4686* {{format}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format enum symbol]] or equivalent integer.
4687* {{access}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#texture-access|texture access enum symbol]] or equivalent integer:
4688** {{'static}}
4689** {{'streaming}}
4690** {{'target}}
4691* {{w}} must be an integer, specifying the texture's width in pixels.
4692* {{h}} must be an integer, specifying the texture's height in pixels.
4693
4694These procedures signal an exception of kind {{(exn sdl2)}} if the sdl2:texture could not be created.
4695
4696* {{create-texture}} returns a managed sdl2:texture.
4697* {{create-texture*}} returns an unmanaged sdl2:texture,
4698  which must be destroyed with {{destroy-texture!}} when you are done with it.
4699
4700These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4701
4702
4703<procedure>(create-texture-from-surface renderer surface) → sdl2:texture</procedure>
4704<procedure>(create-texture-from-surface* renderer surface) → sdl2:texture</procedure>
4705
4706Create a new sdl2:texture from a sdl2:surface.
4707
4708The texture will contain a copy of the pixel data from the surface.
4709The texture will have the same color mod and alpha mod as the surface.
4710If the surface had a color key, the texture will have {{'blend}} blend mode;
4711otherwise it will have the same blend mode as the surface.
4712
4713* {{create-texture-from-surface}} returns a managed sdl2:texture.
4714* {{create-texture-from-surface*}} returns an unmanaged sdl2:texture,
4715  which must be destroyed with {{destroy-texture!}} when you are done with it.
4716
4717These procedures signal an exception of kind {{(exn sdl2)}} if the sdl2:texture could not be created.
4718
4719These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4720
4721
4722<procedure>(destroy-texture! texture)</procedure>
4723
4724Destroy the sdl2:texture, freeing its underlying struct.
4725{{texture}}'s pointer will be set to null (see {{struct-null?}}).
4726It is safe to call tihs procedure with managed on unmanaged sdl2:textures.
4727It is safe (but has no effect) to destroy an sdl2:texture multiple times.
4728
4729See [[https://wiki.libsdl.org/SDL_DestroyTexture|SDL_DestroyTexture]].
4730
4731This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4732
4733
4734<procedure>(query-texture texture) → [format access w h]</procedure>
4735<procedure>(query-texture-raw texture) → [format-int access-int w h]</procedure>
4736
4737Get multiple pieces of information about the texture.
4738See [[https://wiki.libsdl.org/SDL_QueryTexture|SDL_QueryTexture]].
4739
4740{{query-texture}} returns multiple values:
4741
4742; format : The sdl2:texture's pixel format, as a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format enum symbol]]
4743; access : The sdl2:texture's access mode, as a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#texture-access|texture access enum symbol]]
4744; w : The sdl2:texture's width, as a nonnegative integer measured in pixels
4745; h : The sdl2:texture's height, as a nonnegative integer measured in pixels
4746
4747{{query-texture-raw}} is similar, except it returns raw integer values (not symbols) for format and access.
4748
4749These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4750
4751If you only want one of these pieces of information,
4752it is more convenient and efficient to use one of these procedures instead:
4753
4754* {{texture-format}}
4755* {{texture-access}}
4756* {{texture-w}}
4757* {{texture-h}}
4758
4759
4760<procedure>(texture-format texture) → symbol</procedure>
4761
4762Get the sdl2:texture's pixel format, as a pixel format enum symbol.
4763This is equivalent to {{(nth-value 0 (query-texture texture))}},
4764but more convenient and efficient.
4765
4766This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4767
4768
4769<procedure>(texture-access texture) → symbol</procedure>
4770
4771Get the sdl2:texture's access mode, as a texture access enum symbol.
4772This is equivalent to {{(nth-value 1 (query-texture texture))}},
4773but more convenient and efficient.
4774
4775This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4776
4777
4778<procedure>(texture-w texture) → integer</procedure>
4779
4780Get the sdl2:texture's width, as a nonnegative integer measured in pixels.
4781This is equivalent to {{(nth-value 2 (query-texture texture))}},
4782but more convenient and efficient.
4783
4784This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4785
4786
4787<procedure>(texture-h texture) → integer</procedure>
4788
4789Get the sdl2:texture's height, as a nonnegative integer measured in pixels.
4790This is equivalent to {{(nth-value 3 (query-texture texture))}},
4791but more convenient and efficient.
4792
4793This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4794
4795
4796<procedure>(texture-alpha-mod texture) → integer</procedure>
4797<setter>(set! (texture-alpha-mod texture) mod)</setter>
4798<setter>(texture-alpha-mod-set! texture mod)</setter>
4799
4800See [[https://wiki.libsdl.org/SDL_GetTextureAlphaMod|SDL_GetTextureAlphaMod]]
4801and [[https://wiki.libsdl.org/SDL_SetTextureAlphaMod|SDL_SetTextureAlphaMod]].
4802
4803These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4804
4805These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4806
4807
4808<procedure>(texture-blend-mode texture) → symbol</procedure>
4809<procedure>(texture-blend-mode-raw texture) → integer</procedure>
4810<setter>(set! (texture-blend-mode texture) mode)</setter>
4811<setter>(texture-blend-mode-set! texture mode)</setter>
4812
4813See [[https://wiki.libsdl.org/SDL_GetTextureBlendMode|SDL_GetTextureBlendMode]]
4814and [[https://wiki.libsdl.org/SDL_SetTextureBlendMode|SDL_SetTextureBlendMode]].
4815
4816* {{texture-blend-mode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-mode|blend mode symbol]]:
4817** {{'none}}
4818** {{'blend}}
4819** {{'add}}
4820** {{'mod}}
4821* {{texture-blend-mode-raw}} returns an integer.
4822* The setters accept either a symbol or integer.
4823
4824These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4825
4826These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4827
4828
4829<procedure>(texture-color-mod texture) → [r g b]</procedure>
4830<procedure>(texture-colour-mod texture) → [r g b]</procedure>
4831<setter>(set! (texture-color-mod texture) rgb)</setter>
4832<setter>(set! (texture-colour-mod texture) rgb)</setter>
4833<setter>(texture-color-mod-set! texture rgb)</setter>
4834<setter>(texture-colour-mod-set! texture rgb)</setter>
4835
4836See [[https://wiki.libsdl.org/SDL_GetTextureColorMod|SDL_GetTextureColorMod]]
4837and [[https://wiki.libsdl.org/SDL_SetTextureColorMod|SDL_SetTextureColorMod]].
4838
4839{{texture-color-mod}} and {{texture-colour-mod}} return multiple values.
4840
4841The setters accept either a list {{(r g b)}} of color values, or an sdl2:color (the sdl2:color's "a" field will be ignored).
4842
4843These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4844
4845These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4846
4847
4848<procedure>(lock-texture-raw! texture rect) → [pixels pitch]</procedure>
4849
4850Lock the texture so that its pixel data can be overwritten.
4851This is for advanced users, and must be used with caution.
4852See [[https://wiki.libsdl.org/SDL_LockTexture|SDL_LockTexture]].
4853See also {{unlock-texture!}}.
4854
4855* {{texture}} is the sdl2:texture that you wish to modify
4856* {{rect}} is either an sdl2:rect (to lock part of the texture), or #f (to lock all of the texture).
4857
4858This procedure returns multiple values:
4859
4860; pixels : A raw pointer that you can write pixel data to. Does not necessarily contain the old data.
4861; pitch : An integer indicating the pitch of the pixel data
4862
4863Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4864
4865This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4866
4867
4868<procedure>(unlock-texture! texture)</procedure>
4869
4870Unlock the texture, applying the new pixel data to the texture.
4871This is for advanced users, and must be used with caution.
4872See [[https://wiki.libsdl.org/SDL_UnlockTexture|SDL_UnlockTexture]].
4873See also {{lock-texture-raw!}}.
4874
4875This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4876
4877
4878<procedure>(update-texture-raw! texture rect pixels pitch)</procedure>
4879
4880Overwrite part or all of the texture's pixel data.
4881This is for advanced users, and must be used with caution.
4882See [[https://wiki.libsdl.org/SDL_UpdateTexture|SDL_UpdateTexture]].
4883
4884* {{texture}} is the sdl2:texture that you wish to update
4885* {{rect}} is either an sdl2:rect (to update part of the texture), or #f (to update all of the texture)
4886* {{pixels}} is a pointer or locative to raw pixel data
4887* {{pitch}} is an integer describing the pitch of the pixel data
4888
4889Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4890
4891This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4892
4893
4894<procedure>(update-yuv-texture-raw! texture rect y-plane y-pitch u-plane u-pitch v-plane v-pitch)</procedure>
4895
4896Overwrite part or all of a YV12- or IYUV-formatted texture's pixel data.
4897This is for advanced users, and must be used with caution.
4898See [[https://wiki.libsdl.org/SDL_UpdateYUVTexture|SDL_UpdateYUVTexture]].
4899
4900* {{texture}} is the sdl2:texture that you wish to update
4901* {{rect}} is either an sdl2:rect (to update part of the texture), or #f (to update all of the texture)
4902* {{y-plane}} is a pointer or locative to raw pixel data for the Y plane
4903* {{y-pitch}} is an integer describing the pitch of the Y pixel data
4904* {{u-plane}} is a pointer or locative to raw pixel data for the U plane
4905* {{u-pitch}} is an integer describing the pitch of the U pixel data
4906* {{v-plane}} is a pointer or locative to raw pixel data for the V plane
4907* {{v-pitch}} is an integer describing the pitch of the V pixel data
4908
4909Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4910
4911This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4912It requires '''SDL 2.0.1 or higher'''.
4913It signals an error if the compiled version of SDL is not high enough.
4914Use the [[#version-feature-identifiers|{{libSDL-2.0.1+}} feature identifier]]
4915to check before calling this procedure.
4916
4917
4918
4919=== Timer
4920
4921<procedure>(delay! milliseconds)</procedure>
4922
4923See [[https://wiki.libsdl.org/SDL_Delay|SDL_Delay]].
4924
4925'''CAUTION:''' This procedure is not compatible with [[/manual/Unit srfi-18|SRFI-18]]
4926threads. It will cause '''all threads to sleep''' for the given
4927duration. If you are using multiple threads, you should instead call
4928SRFI-18's {{thread-sleep!}}, which will cause only the current thread
4929to sleep. For example, call {{(thread-sleep! 0.025)}} instead of
4930{{(delay! 25)}}.
4931
4932
4933<procedure>(get-ticks) → integer</procedure>
4934
4935See [[https://wiki.libsdl.org/SDL_GetTicks|SDL_GetTicks]].
4936
4937
4938<procedure>(get-performance-counter) → integer</procedure>
4939
4940See [[https://wiki.libsdl.org/SDL_GetPerformanceCounter|SDL_GetPerformanceCounter]].
4941
4942
4943<procedure>(get-performance-frequency) → integer</procedure>
4944
4945See [[https://wiki.libsdl.org/SDL_GetPerformanceFrequency|SDL_GetPerformanceFrequency]].
4946
4947
4948
4949=== Touch / Gesture
4950
4951==== Touch / Gesture Functions
4952
4953<procedure>(get-num-touch-devices) → integer</procedure>
4954
4955See [[https://wiki.libsdl.org/SDL_GetNumTouchDevices|SDL_GetNumTouchDevices]].
4956
4957
4958<procedure>(get-touch-device device-id) → integer</procedure>
4959
4960See [[https://wiki.libsdl.org/SDL_GetTouchDevice|SDL_GetTouchDevice]].
4961
4962Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4963
4964
4965<procedure>(get-num-touch-fingers touch-id) → integer</procedure>
4966
4967See [[https://wiki.libsdl.org/SDL_GetNumTouchFingers|SDL_GetNumTouchFingers]].
4968
4969
4970<procedure>(get-touch-finger touch-id index) → sdl2:finger</procedure>
4971
4972See [[https://wiki.libsdl.org/SDL_GetTouchFinger|SDL_GetTouchFinger]].
4973
4974Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4975
4976
4977==== sdl2:finger
4978
4979sdl2:finger is a record type that wraps a pointer to an
4980[[https://wiki.libsdl.org/SDL_Finger|SDL_Finger]] struct.
4981
4982
4983<procedure>(finger? obj) → boolean</procedure>
4984
4985Returns #t if {{obj}} is an sdl2:finger.
4986
4987
4988<procedure>(finger-id finger) → integer</procedure>
4989
4990Get the sdl2:finger's "id" field, as an integer.
4991
4992
4993<procedure>(finger-x finger) → float</procedure>
4994
4995Get 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.
4996
4997
4998<procedure>(finger-y finger) → float</procedure>
4999
5000Get 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.
5001
5002
5003<procedure>(finger-pressure finger) → float</procedure>
5004
5005Get 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.
5006
5007
5008
5009=== Version
5010
5011==== Version Feature Identifiers
5012
5013In '''sdl2 egg version 0.2.0 and higher''', the egg automatically registers feature identifiers
5014which can be used to detect the versions of the sdl2 egg and SDL at compile time or run time,
5015for example using the {{cond-expand}} macro, {{#+foo}} syntax, or the {{feature?}} procedure.
5016
5017Some or all of the following feature identifiers will be registered depending on the circumstances:
5018
5019<table>
5020  <tr>
5021    <th>Feature ID</th>
5022    <th>Meaning</th>
5023  </tr>
5024  <tr>
5025    <td>sdl2</td>
5026    <td>Using any version of the sdl2 egg</td>
5027  <tr>
5028  <tr>
5029    <td>sdl2-0.2.0+</td>
5030    <td>Using sdl2 egg 0.2.0 or higher</td>
5031  <tr>
5032  <tr>
5033    <td>libSDL-2.0.0+</td>
5034    <td>The sdl2 egg was compiled with SDL 2.0.0 or higher</td>
5035  <tr>
5036  <tr>
5037    <td>libSDL-2.0.1+</td>
5038    <td>... 2.0.1 or higher</td>
5039  <tr>
5040  <tr>
5041    <td>libSDL-2.0.2+</td>
5042    <td>... 2.0.2 or higher</td>
5043  <tr>
5044  <tr>
5045    <td>libSDL-2.0.3+</td>
5046    <td>... 2.0.3 or higher</td>
5047  <tr>
5048  <tr>
5049    <td>libSDL-2.0.4+</td>
5050    <td>... 2.0.4 or higher</td>
5051  </tr>
5052</table>
5053
5054These are cumulative, so if you are using the latest version of the sdl2 egg and the latest version of SDL, all of the above identifiers will be defined.
5055
5056Here are some examples of how you can use these identifiers:
5057
5058<enscript highlight="scheme">
5059(use (prefix sdl2 sdl2:))
5060
5061;; Compile time check using #+foo reader syntax:
5062#+(not sdl2-0.2.0+)
5063(begin-for-syntax
5064  (error "You need sdl2 egg 0.2.0 or higher to compile this program."))
5065
5066;; Compile-time check using cond-expand macro:
5067(cond-expand
5068 (libSDL-2.0.4+
5069  (include "file-that-needs-SDL-204.scm"))
5070 (else
5071  (include "alternative-file.scm")))
5072
5073;; Run-time check using feature? procedure:
5074(when (feature? 'sdl2)
5075  (print "You are using the sdl2 egg. The future seems bright."))
5076</enscript>
5077
5078
5079==== Version Functions
5080
5081<procedure>(version-at-least? major minor patch) → boolean</procedure>
5082
5083See [[https://wiki.libsdl.org/SDL_VERSION_ATLEAST|SDL_VERSION_ATLEAST]].
5084
5085Returns #t if the sdl2 egg was compiled with a version of SDL at least as high as specified.
5086For example, {{(version-at-least? 2 0 1)}} returns #t if the sdl2 egg was compiled with SDL 2.0.1 or higher.
5087
5088Some SDL features are only available after a certain version, so you can use this procedure to check whether the feature is available.
5089
5090
5091<procedure>(compiled-version) → list of integers</procedure>
5092<procedure>(current-version) → list of integers</procedure>
5093
5094Returns a list of three nonnegative integers, indicating a version number of SDL.
5095For example, the list {{(2 0 3)}} indicates SDL 2.0.3.
5096
5097* {{compiled-version}} returns the version of SDL that the sdl2 egg was compiled with.
5098* {{current-version}} returns the version of SDL that the sdl2 egg is currently using.
5099
5100For 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.
5101In such a case, {{compiled-version}} would return {{(2 0 3)}}, and {{current-version}} would return {{(2 1 0)}}.
5102But, features from the new version would not be available until the user recompiles the sdl2 egg.
5103
5104See [[https://wiki.libsdl.org/SDL_VERSION|SDL_VERSION]]
5105and [[https://wiki.libsdl.org/SDL_GetVersion|SDL_GetVersion]].
5106
5107
5108<constant>(egg-version) → list of integers</constant>
5109
5110Returns a list of three nonnegative integers,
5111indicating the version number of the sdl2 egg itself,
5112which is independent of the version number of SDL.
5113For example, the list {{'(1 2 3)}} means sdl2 egg version 1.2.3.
5114
5115'''NOTE:''' This procedure is available in '''sdl2 egg version 0.2.0 or higher'''.
5116If you want to check the egg version,
5117but users of your program might be using earlier than egg version 0.2.0,
5118you can add the following code to your program.
5119It will define the {{egg-version}} procedure only if using an earlier version of the sdl2 egg.
5120
5121<enscript highlight="scheme">
5122(use (prefix sdl2 sdl2:))
5123
5124#+(not sdl2-0.2.0+)
5125(define (sdl2:egg-version) '(0 1 1))
5126
5127;; Usage:
5128(printf "You are using sdl2 egg version ~S.~%" (sdl2:egg-version))
5129</enscript>
5130
5131
5132
5133=== Window / Display Mode
5134
5135==== Window / Display Mode Functions
5136
5137<procedure>(create-window! title x y w h #!optional flags) → sdl2:window</procedure>
5138
5139See [[https://wiki.libsdl.org/SDL_CreateWindow|SDL_CreateWindow]].
5140
5141{{x}} and {{y}} can be integers, the symbol {{'centered}}, or the symbol {{'undefined}}.
5142
5143{{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):
5144
5145* {{'fullscreen}}
5146* {{'fullscreen-desktop}}
5147* {{'opengl}}
5148* {{'shown}}
5149* {{'hidden}}
5150* {{'borderless}}
5151* {{'resizable}}
5152* {{'minimized}}
5153* {{'maximized}}
5154* {{'input-grabbed}}
5155* {{'input-focus}}
5156* {{'mouse-focus}}
5157* {{'foreign}}
5158* {{'allow-high-dpi}} (requires '''sdl2 egg 0.2.0 and SDL 2.0.1 or higher''')
5159* {{'mouse-capture}} (requires '''sdl2 egg 0.2.0 and SDL 2.0.4 or higher''')
5160
5161
5162<procedure>(destroy-window! window)</procedure>
5163
5164See [[https://wiki.libsdl.org/SDL_DestroyWindow|SDL_DestroyWindow]].
5165
5166
5167<procedure>(get-window-from-id id) → sdl2:window</procedure>
5168
5169See [[https://wiki.libsdl.org/SDL_GetWindowFromID|SDL_GetWindowFromID]].
5170
5171'''NOTE:''' The returned window will be a new sdl2:window record pointing to the address of the existing window.
5172It will be {{equal?}} to other sdl2:window records for the same window, but not {{eq?}}.
5173
5174In '''sdl2 egg version 0.2.0 and higher''', this procedure signals an exception
5175of kind {{(exn sdl2)}} if there is no window with the given ID.
5176In earlier egg versions, this procedure returned a null sdl2:window.
5177
5178
5179<procedure>(update-window-surface! window)</procedure>
5180
5181See [[https://wiki.libsdl.org/SDL_UpdateWindowSurface|SDL_UpdateWindowSurface]].
5182
5183Signals an exception of kind {{(exn sdl2)}} if an error occurs.
5184
5185
5186<procedure>(update-window-surface-rects! window rects)</procedure>
5187
5188See [[https://wiki.libsdl.org/SDL_UpdateWindowSurfaceRects|SDL_UpdateWindowSurfaceRects]].
5189
5190{{rects}} must be a list of sdl2:rects.
5191
5192Signals an exception of kind {{(exn sdl2)}} if an error occurs.
5193
5194
5195<procedure>(show-window! window)</procedure>
5196
5197See [[https://wiki.libsdl.org/SDL_ShowWindow|SDL_ShowWindow]].
5198
5199
5200<procedure>(hide-window! window)</procedure>
5201
5202See [[https://wiki.libsdl.org/SDL_HideWindow|SDL_HideWindow]].
5203
5204
5205<procedure>(maximize-window! window)</procedure>
5206
5207See [[https://wiki.libsdl.org/SDL_MaximizeWindow|SDL_MaximizeWindow]].
5208
5209
5210<procedure>(minimize-window! window)</procedure>
5211
5212See [[https://wiki.libsdl.org/SDL_MinimizeWindow|SDL_MinimizeWindow]].
5213
5214
5215<procedure>(raise-window! window)</procedure>
5216
5217See [[https://wiki.libsdl.org/SDL_RaiseWindow|SDL_RaiseWindow]].
5218
5219
5220<procedure>(restore-window! window)</procedure>
5221
5222See [[https://wiki.libsdl.org/SDL_RestoreWindow|SDL_RestoreWindow]].
5223
5224
5225
5226==== sdl2:window
5227
5228sdl2:window is a record type that wraps a pointer to an
5229[[https://wiki.libsdl.org/SDL_CreateWindow|SDL_Window]] struct.
5230
5231
5232<procedure>(window? obj) → boolean</procedure>
5233
5234Returns #t if {{obj}} is an sdl2:window.
5235
5236
5237<procedure>(window-bordered? window) → boolean</procedure>
5238<setter>(set! (window-bordered? window) bordered)</setter>
5239<setter>(window-bordered-set! window bordered)</setter>
5240
5241Get or set whether the window has a border (window decoration).
5242#t means the window has a border, #f means the window is borderless.
5243
5244Setting this to #f has essentially the same effect as passing the {{'borderless}} flag to {{create-window!}} when creating the window.
5245
5246See [[https://wiki.libsdl.org/SDL_SetWindowBordered|SDL_SetWindowBordered]].
5247
5248
5249<procedure>(window-brightness window) → float</procedure>
5250<setter>(set! (window-brightness window) brightness)</setter>
5251<setter>(window-brightness-set! window brightness)</setter>
5252
5253See [[https://wiki.libsdl.org/SDL_GetWindowBrightness|SDL_GetWindowBrightness]]
5254and [[https://wiki.libsdl.org/SDL_SetWindowBrightness|SDL_SetWindowBrightness]].
5255
5256The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
5257
5258
5259<procedure>(window-display-index window) → integer</procedure>
5260
5261See [[https://wiki.libsdl.org/SDL_GetWindowDisplayIndex|SDL_GetWindowDisplayIndex]].
5262
5263Signals an exception of kind {{(exn sdl2)}} if an error occurs.
5264
5265
5266<procedure>(window-display-mode window) → sdl2:display-mode</procedure>
5267<setter>(set! (window-display-mode window) display-mode)</setter>
5268<setter>(window-display-mode-set! window display-mode)</setter>
5269
5270See [[https://wiki.libsdl.org/SDL_GetWindowDisplayMode|SDL_GetWindowDisplayMode]]
5271and [[https://wiki.libsdl.org/SDL_SetWindowDisplayMode|SDL_SetWindowDisplayMode]].
5272
5273These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
5274
5275
5276<procedure>(window-flags window) → list of symbols</procedure>
5277<procedure>(window-flags-raw window) → integer</procedure>
5278
5279See [[https://wiki.libsdl.org/SDL_GetWindowFlags|SDL_GetWindowFlags]].
5280
5281* {{window-flags}} returns a list of [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#window-flags|window flag symbols]].
5282* {{window-flags-raw}} returns an integer bitfield.
5283
5284
5285<procedure>(window-fullscreen window) → symbol or #f</procedure>
5286<setter>(set! (window-fullscreen window) mode)</setter>
5287<setter>(window-fullscreen-set! window mode)</setter>
5288
5289Get or set the sdl2:window's fullscreen mode.
5290See [[https://wiki.libsdl.org/SDL_SetWindowFullscreen|SDL_SetWindowFullscreen]].
5291
5292{{window-fullscreen}} returns one of the following values:
5293
5294* {{'fullscreen}} means "real" fullscreen mode
5295* {{'fullscreen-desktop}} means "fake" fullscreen mode that takes the size of the desktop
5296* {{#f}} means windowed (non-fullscreen) mode
5297
5298The setters accept any of the above values, or #t (which means the same as {{'fullscreen}}), or an equivalent integer value.
5299
5300The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
5301
5302
5303<procedure>(window-grab? window) → boolean</procedure>
5304<setter>(set! (window-grab? window) grab?)</setter>
5305<setter>(window-grab-set! window grab?)</setter>
5306
5307See [[https://wiki.libsdl.org/SDL_GetWindowGrab|SDL_GetWindowGrab]]
5308and [[https://wiki.libsdl.org/SDL_SetWindowGrab|SDL_SetWindowGrab]].
5309
5310
5311<procedure>(grabbed-window) → sdl2:window or #f</procedure>
5312
5313Returns the sdl2:window that currently has input grab, or #f if no window has input grab.
5314See [[https://wiki.libsdl.org/SDL_GetGrabbedWindow|SDL_GetGrabbedWindow]].
5315
5316'''NOTE:''' The returned window will be a new sdl2:window record pointing to the address of the existing window.
5317It will be {{equal?}} to other sdl2:window records for the same window, but not {{eq?}}.
5318
5319This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
5320It requires '''SDL 2.0.4 or higher'''.
5321It signals an error if the compiled version of SDL is not high enough.
5322Use the [[#version-feature-identifiers|{{libSDL-2.0.4+}} feature identifier]]
5323to check before calling this procedure.
5324
5325
5326<setter>(window-icon-set! window icon-surface)</setter>
5327
5328See [[https://wiki.libsdl.org/SDL_SetWindowIcon|SDL_SetWindowIcon]].
5329
5330
5331<procedure>(window-id window) → integer</procedure>
5332
5333See [[https://wiki.libsdl.org/SDL_GetWindowID|SDL_GetWindowID]].
5334
5335
5336<procedure>(window-maximum-size window) → [width height]</procedure>
5337<setter>(set! (window-maximum-size window) size)</setter>
5338<setter>(window-maximum-size-set! window size)</setter>
5339
5340See [[https://wiki.libsdl.org/SDL_GetWindowMaximumSize|SDL_GetWindowMaximumSize]]
5341and [[https://wiki.libsdl.org/SDL_SetWindowMaximumSize|SDL_SetWindowMaximumSize]].
5342
5343{{window-maximum-size}} returns multiple values.
5344
5345The setters accept a list of integers {{(width height)}}.
5346
5347
5348<procedure>(window-minimum-size window) → [width height]</procedure>
5349<setter>(set! (window-minimum-size window) size)</setter>
5350<setter>(window-minimum-size-set! window size)</setter>
5351
5352See [[https://wiki.libsdl.org/SDL_GetWindowMinimumSize|SDL_GetWindowMinimumSize]]
5353and [[https://wiki.libsdl.org/SDL_SetWindowMinimumSize|SDL_SetWindowMinimumSize]].
5354
5355{{window-minimum-size}} returns multiple values.
5356
5357The setters accept a list of integers {{(width height)}}.
5358
5359
5360<procedure>(window-pixel-format window) → symbol</procedure>
5361<procedure>(window-pixel-format-raw window) → integer</procedure>
5362
5363Returns a symbol or integer indicating the given window's pixel format.
5364See [[https://wiki.libsdl.org/SDL_GetWindowPixelFormat|SDL_GetWindowPixelFormat]].
5365
5366* {{window-pixel-format}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]].
5367* {{window-pixel-format-raw}} returns an integer.
5368
5369
5370<procedure>(window-position window) → [x y]</procedure>
5371<setter>(set! (window-position window) pos)</setter>
5372<setter>(window-position-set! window pos)</setter>
5373
5374See [[https://wiki.libsdl.org/SDL_GetWindowPosition|SDL_GetWindowPosition]]
5375and [[https://wiki.libsdl.org/SDL_SetWindowPosition|SDL_SetWindowPosition]].
5376
5377{{window-position}} returns multiple values.
5378
5379The setters accept a list of integers {{(x y)}}.
5380
5381
5382<procedure>(window-size window) → [width height]</procedure>
5383<setter>(set! (window-size window) size)</setter>
5384<setter>(window-size-set! window size)</setter>
5385
5386See [[https://wiki.libsdl.org/SDL_GetWindowSize|SDL_GetWindowSize]]
5387and [[https://wiki.libsdl.org/SDL_SetWindowSize|SDL_SetWindowSize]].
5388
5389{{window-size}} returns multiple values.
5390
5391The setters accept a list of integers {{(width height)}}.
5392
5393
5394<procedure>(window-surface window) → sdl2:surface</procedure>
5395
5396See [[https://wiki.libsdl.org/SDL_GetWindowSurface|SDL_GetWindowSurface]].
5397
5398Signals an exception of kind {{(exn sdl2)}} if an error occurs.
5399
5400
5401<procedure>(window-title window) → string</procedure>
5402<setter>(set! (window-title window) title)</setter>
5403<setter>(window-title-set! window title)</setter>
5404
5405See [[https://wiki.libsdl.org/SDL_GetWindowTitle|SDL_GetWindowTitle]]
5406and [[https://wiki.libsdl.org/SDL_SetWindowTitle|SDL_SetWindowTitle]].
5407
5408
5409
5410==== sdl2:display-mode
5411
5412sdl2:display-mode is a record type that wraps a pointer to an
5413[[https://wiki.libsdl.org/SDL_DisplayMode|SDL_DisplayMode]] struct.
5414
5415
5416<procedure>(display-mode? obj) → boolean</procedure>
5417
5418Returns #t if {{obj}} is an sdl2:display-mode.
5419
5420
5421<procedure>(make-display-mode #!optional format w h refresh-rate) → sdl2:display-mode</procedure>
5422<procedure>(make-display-mode* #!optional format w h refresh-rate) → sdl2:display-mode</procedure>
5423
5424Allocate and initialize a new sdl2:display-mode.
5425
5426{{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.
5427
5428{{w}}, {{h}}, and {{refresh-rate}} default to 0. They must be integers.
5429
5430* {{make-display-mode}} returns a managed sdl2:display-mode.
5431* {{make-display-mode*}} returns an unmanaged sdl2:display-mode, which must be freed with {{free-display-mode!}} when you are done with it.
5432
5433
5434<procedure>(free-display-mode! display-mode)</procedure>
5435
5436Free the memory of the sdl2:display-mode's underlying struct.
5437{{display-mode}}'s pointer will be set to null (see {{struct-null?}}).
5438It is safe to call this procedure with managed or unmanaged
5439sdl2:display-modes. It is safe (but has no effect) to free a struct
5440record multiple times.
5441
5442
5443<procedure>(display-mode-format display-mode) → symbol</procedure>
5444<procedure>(display-mode-format-raw display-mode) → integer</procedure>
5445<setter>(set! (display-mode-format display-mode) val)</setter>
5446<setter>(display-mode-format-set! display-mode val)</setter>
5447
5448Get or set the sdl2:display-mode's "format" field.
5449
5450* {{display-mode-format}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]].
5451* {{display-mode-format-raw}} returns an integer.
5452* The setters accept either a symbol or an integer.
5453
5454
5455<procedure>(display-mode-w display-mode) → integer</procedure>
5456<setter>(set! (display-mode-w display-mode) val)</setter>
5457<setter>(display-mode-w-set! display-mode val)</setter>
5458
5459Get or set the sdl2:display-mode's "w" field, as an integer.
5460
5461
5462<procedure>(display-mode-h display-mode) → integer</procedure>
5463<setter>(set! (display-mode-h display-mode) val)</setter>
5464<setter>(display-mode-h-set! display-mode val)</setter>
5465
5466Get or set the sdl2:display-mode's "h" field, as an integer.
5467
5468
5469<procedure>(display-mode-refresh-rate display-mode) → integer</procedure>
5470<setter>(set! (display-mode-refresh-rate display-mode) val)</setter>
5471<setter>(display-mode-refresh-rate-set! display-mode val)</setter>
5472
5473Get or set the sdl2:display-mode's "refresh-rate" field, as an integer.
5474
5475
5476
5477=== Miscellaneous
5478
5479<procedure>(clear-error!)</procedure>
5480
5481See [[https://wiki.libsdl.org/SDL_ClearError|SDL_ClearError]].
5482
5483
5484<procedure>(get-error) → string</procedure>
5485
5486See [[https://wiki.libsdl.org/SDL_GetError|SDL_GetError]].
5487
5488
5489<procedure>(set-error! message)</procedure>
5490
5491See [[https://wiki.libsdl.org/SDL_SetError|SDL_SetError]].
5492
5493Unlike SDL_SetError, this procedure only accepts one argument, a
5494string. You can use {{sprintf}} to do string substitution if desired.
5495
5496
5497<procedure>(get-platform) → string</procedure>
5498
5499See [[https://wiki.libsdl.org/SDL_GetPlatform|SDL_GetPlatform]].
5500
5501
5502<procedure>(screen-saver-enabled?) → boolean</procedure>
5503<setter>(set! (screen-saver-enabled?) enabled?)</setter>
5504<setter>(screen-saver-enabled-set! enabled?)</setter>
5505
5506See [[https://wiki.libsdl.org/SDL_IsScreenSaverEnabled|SDL_IsScreenSaverEnabled]],
5507[[https://wiki.libsdl.org/SDL_EnableScreenSaver|SDL_EnableScreenSaver]],
5508and [[https://wiki.libsdl.org/SDL_DisableScreenSaver|SDL_DisableScreenSaver]].
5509
5510
5511<procedure>(has-clipboard-text?) → boolean</procedure>
5512
5513See [[https://wiki.libsdl.org/SDL_HasClipboardText|SDL_HasClipboardText]].
5514
5515
5516<procedure>(get-clipboard-text) → string</procedure>
5517
5518See [[https://wiki.libsdl.org/SDL_GetClipboardText|SDL_GetClipboardText]].
5519
5520Signals an exception of kind {{(exn sdl2)}} if an error occurs.
5521
5522
5523<procedure>(set-clipboard-text! text)</procedure>
5524
5525See [[https://wiki.libsdl.org/SDL_SetClipboardText|SDL_SetClipboardText]].
5526
5527Signals an exception of kind {{(exn sdl2)}} if an error occurs.
Note: See TracBrowser for help on using the repository browser.