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

Last change on this file since 33329 was 33329, checked in by wasamasa, 5 years ago

Add missing procedure parameter

File size: 217.2 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 (2016-02-13) : 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 factor) → sdl2:color</procedure>
533<procedure>(colour-scale  color factor) → sdl2:color</procedure>
534<procedure>(color-scale!  color factor #!optional dest) → dest</procedure>
535<procedure>(colour-scale! color factor #!optional dest) → dest</procedure>
536
537Efficiently multiply the RGBA values of {{color}} by {{factor}} (a float or integer).
538E.g. {{factor}} 0.5 halves the RGBA values, {{factor}} 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 factor) → sdl2:rect</procedure>
3362<procedure>(rect-scale! rect factor #!optional dest) → dest</procedure>
3363
3364Efficiently multiply the X, Y, W, and H values of {{rect}} by {{factor}} (a float or integer).
3365E.g. {{factor}} 0.5 halves the values, {{factor}} 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-unscale  rect factor) → sdl2:rect</procedure>
3377<procedure>(rect-unscale! rect factor #!optional dest) → dest</procedure>
3378
3379Efficiently divide the X, Y, W, and H values of {{rect}} by {{factor}} (a float or integer).
3380This is equivalent to {{(rect-scale rect (/ 1 factor))}},
3381but is more convenient and efficient (especially if {{factor}} is an integer).
3382
3383These procedures signal an error if {{factor}} is 0.
3384sdl2:rect can only hold integer values, so the results will be truncated to integers.
3385The results will be clamped to the range -2147483648 to 2147483647.
3386
3387* {{rect-unscale}} returns a new managed sdl2:rect.
3388* {{rect-unscale!}} 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-move  rect dx dy) → sdl2:rect</procedure>
3395<procedure>(rect-move! rect dx dy #!optional dest) → dest</procedure>
3396
3397Efficiently move {{rect}} by adding the given amounts to its X and Y values.
3398{{dx}} and {{dy}} must be integers.
3399The results will be clamped to the range -2147483648 to 2147483647.
3400
3401If {{dx}} and {{dy}} are already stored in an sdl2:point,
3402it is more efficient and convenient to use {{rect-add-point}} or {{rect-sub-point}},
3403instead of extracting the individual fields from the point.
3404
3405* {{rect-move}} returns a new managed sdl2:rect.
3406* {{rect-move!}} modifies and returns {{dest}}.
3407  If {{dest}} is omitted, {{rect}} is modified and returned.
3408
3409These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3410
3411
3412<procedure>(rect-add-point  rect point) → sdl2:rect</procedure>
3413<procedure>(rect-add-point! rect point #!optional dest) → dest</procedure>
3414
3415Efficiently move {{rect}} by adding {{point}} to {{rect}}'s X and Y values.
3416The results will be clamped to the range -2147483648 to 2147483647.
3417
3418If the dx and dy values are already held as separate variables,
3419it is more efficient and convenient to use {{rect-move}},
3420instead of creating an sdl2:point.
3421
3422* {{rect-add-point}} returns a new managed sdl2:rect.
3423* {{rect-add-point!}} modifies and returns {{dest}}.
3424  If {{dest}} is omitted, {{rect}} is modified and returned.
3425
3426These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3427
3428
3429<procedure>(rect-sub-point  rect point) → sdl2:rect</procedure>
3430<procedure>(rect-sub-point! rect point #!optional dest) → dest</procedure>
3431
3432Efficiently move {{rect}} by subtracting {{point}} from {{rect}}'s X and Y values.
3433The results will be clamped to the range -2147483648 to 2147483647.
3434
3435If the dx and dy values are already held as separate variables,
3436it is more efficient and convenient to negate the values and use {{rect-move}},
3437instead of creating an sdl2:point.
3438
3439* {{rect-sub-point}} returns a new managed sdl2:rect.
3440* {{rect-sub-point!}} 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  rect dw dh) → sdl2:rect</procedure>
3447<procedure>(rect-grow! rect dw dh #!optional dest) → dest</procedure>
3448
3449Efficiently increase {{rect}}'s size by adding to its W and H values.
3450The rect's top left corner will stay the same.
3451See also {{rect-grow/center!}}, which keeps the rect's center point the same.
3452The results will be clamped to the range -2147483648 to 2147483647.
3453
3454{{dw}} and {{dh}} must be integers.
3455Negative numbers cause the size to decrease (i.e. shrink).
3456
3457* {{rect-grow}} returns a new managed sdl2:rect.
3458* {{rect-grow!}} modifies and returns {{dest}}.
3459  If {{dest}} is omitted, {{rect}} is modified and returned.
3460
3461These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3462
3463
3464<procedure>(rect-grow/center  rect dw dh) → sdl2:rect</procedure>
3465<procedure>(rect-grow/center! rect dw dh #!optional dest) → dest</procedure>
3466
3467Efficiently increase {{rect}}'s size while trying to keep the same center point.
3468See also {{rect-grow!}}, which keeps the rect's top left corner the same.
3469The results will be clamped to the range -2147483648 to 2147483647.
3470
3471{{dw}} and {{dh}} must be integers.
3472Negative numbers cause the size to decrease (i.e. shrink).
3473
3474For best results, use even numbers for {{dw}} and {{dh}}.
3475If {{dw}} or {{dh}} are odd numbers, the rect's center point will change by half a pixel due to rounding.
3476
3477* {{rect-grow/center}} returns a new managed sdl2:rect.
3478* {{rect-grow/center!}} modifies and returns {{dest}}.
3479  If {{dest}} is omitted, {{rect}} is modified and returned.
3480
3481These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3482
3483
3484<procedure>(rect-lerp  rect1 rect2 t) → sdl2:rect</procedure>
3485<procedure>(rect-lerp! rect1 rect2 t #!optional dest) → dest</procedure>
3486
3487Efficient linear interpolation (or extrapolation) between {{rect1}} and {{rect2}}.
3488sdl2:rect can only hold integer values, so the results will be truncated to integers.
3489The results will be clamped to the range -2147483648 to 2147483647.
3490
3491These procedures affect all values of the rect: X, Y, W, and H.
3492If you only want to interpolate the rect's position (X and Y), use {{rect-lerp-xy}} instead.
3493
3494{{t}} is the interpolation factor (a float).
3495Values of {{t}} between 0 and 1 will interpolate between {{rect1}} and {{rect2}}.
3496Values of {{t}} less that 0 will extrapolate beyond {{rect1}} (moving away from {{rect2}}).
3497Values greater that 1 will extrapolate beyond {{rect2}} (moving away from {{rect1}}).
3498
3499* {{rect-lerp}} returns a new managed sdl2:rect.
3500* {{rect-lerp!}} modifies and returns {{dest}}.
3501  If {{dest}} is omitted, {{rect1}} is modified and returned.
3502
3503These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3504
3505
3506<procedure>(rect-lerp-xy  rect1 rect2 t) → sdl2:rect</procedure>
3507<procedure>(rect-lerp-xy! rect1 rect2 t #!optional dest) → dest</procedure>
3508
3509Efficient linear interpolation (or extrapolation) between {{rect1}} and {{rect2}}.
3510sdl2:rect can only hold integer values, so the results will be truncated to integers.
3511The results will be clamped to the range -2147483648 to 2147483647.
3512
3513These procedures only affect the X and Y values of the rect.
3514The result will have the same W and H as {{rect1}}.
3515If you want interpolate all values (X, Y, W, and H), use {{rect-lerp}} instead.
3516
3517{{t}} is the interpolation factor (a float).
3518Values of {{t}} between 0 and 1 will interpolate between {{rect1}} and {{rect2}}.
3519Values of {{t}} less that 0 will extrapolate beyond {{rect1}} (moving away from {{rect2}}).
3520Values greater that 1 will extrapolate beyond {{rect2}} (moving away from {{rect1}}).
3521
3522* {{rect-lerp-xy}} returns a new managed sdl2:rect.
3523* {{rect-lerp-xy!}} modifies and returns {{dest}}.
3524  If {{dest}} is omitted, {{rect1}} is modified and returned.
3525
3526These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3527
3528
3529
3530==== sdl2:point
3531
3532sdl2:point is a record type that wraps a pointer to an
3533[[https://wiki.libsdl.org/SDL_Point|SDL_Point]] struct.
3534
3535
3536<procedure>(point? obj) → boolean</procedure>
3537
3538Returns #t if {{obj}} is an sdl2:point.
3539
3540
3541<procedure>(make-point #!optional x y) → sdl2:point</procedure>
3542<procedure>(make-point* #!optional x y) → sdl2:point</procedure>
3543
3544Allocate and initialize a new sdl2:point.
3545
3546{{x}} and {{y}} must be integers in the range -2147483648 to 2147483647 (inclusive).
3547They both default to 0.
3548
3549* {{make-point}} returns a managed sdl2:point.
3550* {{make-point*}} returns an unmanaged sdl2:point, which must be freed with {{free-point!}} when you are done with it.
3551
3552
3553<procedure>(free-point! point)</procedure>
3554
3555Free the memory of the sdl2:point's underlying struct. {{point}}'s
3556pointer will be set to null (see {{struct-null?}}). It is safe to call
3557this procedure with managed or unmanaged sdl2:points. It is safe (but
3558has no effect) to free a struct record multiple times.
3559
3560
3561<procedure>(point-x point) → integer</procedure>
3562<setter>(set! (point-x point) val)</setter>
3563<setter>(point-x-set! point val)</setter>
3564
3565Get or set the sdl2:point's "x" field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3566
3567
3568<procedure>(point-y point) → integer</procedure>
3569<setter>(set! (point-y point) val)</setter>
3570<setter>(point-y-set! point val)</setter>
3571
3572Get or set the sdl2:point's "y" field, as an integer in the range -2147483648 to 2147483647 (inclusive).
3573
3574
3575
3576==== sdl2:point Operations
3577
3578These are operations for efficiently and conveniently working with sdl2:points.
3579Many of them are implemented in C for efficiency.
3580
3581
3582<procedure>(point-set! point #!optional x y) → point</procedure>
3583
3584Efficient and convenient way of setting multiple fields of the sdl2:point.
3585Any arguments that are {{#f}} will cause no change to that field.
3586E.g. {{(point-set! my-point 42 #f)}} will set the "x" field to 42, but will not change the "y" field.
3587Returns {{point}} after it is modified.
3588
3589
3590<procedure>(point->list point) → list of integers</procedure>
3591
3592Returns a list {{(x y)}} containing the value of each field of the sdl2:point.
3593
3594
3595<procedure>(point->values point) → [x y]</procedure>
3596
3597Returns multiple values containing the value of each field of the sdl2:point.
3598This is useful for destructuring an sdl2:point using {{receive}} or {{let-values}}.
3599
3600
3601<procedure>(point=? point1 point2) → boolean</procedure>
3602
3603Efficiently compare two sdl2:points.
3604Returns #t if the value of every field in {{point1}} is equal to the value of the corresponding field in {{point2}}.
3605
3606
3607<procedure>(point-copy src) → sdl2:point</procedure>
3608<procedure>(point-copy! src dest) → dest</procedure>
3609
3610{{point-copy}} efficiently copies the values of {{src}} into a new managed sdl2:point.
3611{{point-copy}} is available in '''sdl2 egg version 0.2.0 and higher'''.
3612In earlier versions, it was named {{copy-point}}.
3613
3614{{point-copy!}} efficiently copies the values of {{src}} into {{dest}},
3615and returns the modified {{dest}}.
3616It is safe (but useless) for {{src}} and {{dest}} to be the same object.
3617{{point-copy!}} is available in '''sdl2 egg version 0.2.0 and higher'''.
3618
3619
3620<procedure>(copy-point point) → sdl2:point</procedure>
3621
3622Deprecated alias for {{point-copy}}.
3623This alias was deprecated in sdl2 egg version 0.2.0,
3624and will be removed in a future version.
3625
3626
3627<procedure>(copy-point* point) → sdl2:point</procedure>
3628
3629Deprecated procedure.
3630This procedure was deprecated in sdl2 egg version 0.2.0,
3631and will be removed in a future version.
3632You can achieve the same effect using {{point-copy!}} and {{make-point*}}.
3633
3634
3635<procedure>(point-scale  point factor) → sdl2:point</procedure>
3636<procedure>(point-scale! point factor #!optional dest) → dest</procedure>
3637
3638Efficiently multiply the X and Y values of {{point}} by {{factor}} (a float or integer).
3639E.g. {{factor}} 0.5 halves the values, {{factor}} 2.0 doubles the values.
3640sdl2:point can only hold integer values, so the results will be truncated to integers.
3641The results will be clamped to the range -2147483648 to 2147483647.
3642
3643These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3644
3645* {{point-scale}} returns a new managed sdl2:point.
3646* {{point-scale!}} modifies and returns {{dest}}.
3647  If {{dest}} is omitted, {{point}} is modified and returned.
3648
3649
3650<procedure>(point-unscale  point factor) → sdl2:point</procedure>
3651<procedure>(point-unscale! point factor #!optional dest) → dest</procedure>
3652
3653Efficiently divide the X and Y values of {{point}} by {{factor}} (a float or integer).
3654This is equivalent to {{(point-scale point (/ 1 factor))}},
3655but is more convenient and efficient (especially if {{factor}} is an integer).
3656
3657These procedures signal an error if {{factor}} is 0.
3658sdl2:point can only hold integer values, so the results will be truncated to integers.
3659The results will be clamped to the range -2147483648 to 2147483647.
3660
3661These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3662
3663* {{point-unscale}} returns a new managed sdl2:point.
3664* {{point-unscale!}} modifies and returns {{dest}}.
3665  If {{dest}} is omitted, {{point}} is modified and returned.
3666
3667
3668<procedure>(point-move  point dx dy) → sdl2:point</procedure>
3669<procedure>(point-move! point dx dy #!optional dest) → dest</procedure>
3670
3671Efficiently move {{point}} by adding the given amounts to its X and Y values.
3672{{dx}} and {{dy}} must be integers.
3673The results will be clamped to the range -2147483648 to 2147483647.
3674
3675If {{dx}} and {{dy}} are already stored in an sdl2:point,
3676it is more efficient and convenient to use {{point-add}} or {{point-sub}},
3677instead of extracting the individual fields from the point.
3678
3679* {{point-move}} returns a new managed sdl2:point.
3680* {{point-move!}} modifies and returns {{dest}}.
3681  If {{dest}} is omitted, {{point}} is modified and returned.
3682
3683These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3684
3685
3686<procedure>(point-add  point1 point2) → sdl2:point</procedure>
3687<procedure>(point-add! point1 point2 #!optional dest) → dest</procedure>
3688
3689Efficiently add {{point1}} and {{point2}} (vector addition).
3690The results will be clamped to the range -2147483648 to 2147483647.
3691
3692If the dx and dy values are already held as separate variables,
3693it is more efficient and convenient to use {{point-move}},
3694instead of creating an sdl2:point.
3695
3696* {{point-add}} returns a new managed sdl2:point.
3697* {{point-add!}} 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<procedure>(point-sub  point1 point2) → sdl2:point</procedure>
3704<procedure>(point-sub! point1 point2 #!optional dest) → dest</procedure>
3705
3706Efficiently subtract {{point2}} from {{point1}} (vector subtraction).
3707The results will be clamped to the range -2147483648 to 2147483647.
3708
3709If the dx and dy values are already held as separate variables instead,
3710it is more efficient and convenient to negate the values and use {{point-move}},
3711instead of creating an sdl2:point.
3712
3713* {{point-sub}} returns a new managed sdl2:point.
3714* {{point-sub!}} modifies and returns {{dest}}.
3715  If {{dest}} is omitted, {{point1}} is modified and returned.
3716
3717These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3718
3719
3720<procedure>(point-lerp  point1 point2 t) → sdl2:point</procedure>
3721<procedure>(point-lerp! point1 point2 t #!optional dest) → dest</procedure>
3722
3723Efficient linear interpolation (or extrapolation) between {{point1}} and {{point2}}.
3724sdl2:point can only hold integer values, so the results will be truncated to integers.
3725The results will be clamped to the range -2147483648 to 2147483647.
3726
3727{{t}} is the interpolation factor (a float).
3728Values of {{t}} between 0 and 1 will interpolate between {{point1}} and {{point2}}.
3729Values of {{t}} less that 0 will extrapolate beyond {{point1}} (moving away from {{point2}}).
3730Values greater that 1 will extrapolate beyond {{point2}} (moving away from {{point1}}).
3731
3732* {{point-lerp}} returns a new managed sdl2:point.
3733* {{point-lerp!}} modifies and returns {{dest}}.
3734  If {{dest}} is omitted, {{point1}} is modified and returned.
3735
3736These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3737
3738
3739
3740=== Renderer
3741
3742Renderer is one part of [[https://wiki.libsdl.org/CategoryRender|2D Accelerated Rendering]].
3743See also [[#texture|Texture]].
3744
3745Renderer support is available in '''sdl2 egg 0.2.0 and higher'''.
3746
3747
3748==== Renderer Functions
3749
3750<procedure>(create-renderer! window #!optional index flags) → sdl2:renderer</procedure>
3751
3752Create a new sdl2:renderer associated with the given window.
3753See [[https://wiki.libsdl.org/SDL_CreateRenderer|SDL_CreateRenderer]].
3754This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3755
3756* {{window}} must be a sdl2:window
3757* {{index}} must be an integer specifying the index of the driver to initialize,
3758  or -1 to use the first driver supporting the requested flags.
3759  It defaults to -1.
3760* {{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]].
3761  It defaults to {{'()}}.
3762** {{'software}}
3763** {{'accelerated}}
3764** {{'present-vsync}}
3765** {{'target-texture}}
3766
3767Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3768
3769
3770<procedure>(create-software-renderer! surface) → sdl2:renderer</procedure>
3771
3772Create a sdl2:renderer which renders onto the given sdl2:surface.
3773See [[https://wiki.libsdl.org/SDL_CreateSoftwareRenderer|SDL_CreateSoftwareRenderer]].
3774This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3775
3776Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3777
3778
3779<procedure>(destroy-renderer! renderer)</procedure>
3780
3781See [[https://wiki.libsdl.org/SDL_DestroyRenderer|SDL_DestroyRenderer]].
3782This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3783
3784
3785<procedure>(create-window-and-renderer! width height #!optional window-flags) → [window renderer]</procedure>
3786
3787Create a sdl2:window and a sdl2:renderer that renders to the window.
3788This is more convenient, but less flexible, than using {{create-window!}} and then {{create-renderer!}}.
3789See [[https://wiki.libsdl.org/SDL_CreateWindowAndRenderer|SDL_CreateWindowAndRenderer]].
3790This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3791
3792{{width}} and {{height}} must be inditegers specifying the height of the window and renderer to create.
3793
3794{{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).
3795
3796This procedure returns multiple values:
3797
3798; window   : The sdl2:window that was created.
3799; renderer : The sdl2:renderer that was created.
3800
3801
3802<procedure>(get-renderer window) → sdl2:renderer</procedure>
3803
3804Return the renderer associated with the given sdl2:window.
3805See [[https://wiki.libsdl.org/SDL_GetRenderer|SDL_GetRenderer]].
3806This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3807
3808'''NOTE:''' The returned renderer will be a new sdl2:renderer record pointing to the address of the existing renderer.
3809It will be {{equal?}} to other sdl2:renderer records for the same renderer, but not {{eq?}}.
3810
3811Signals an exception of kind {{(exn sdl2)}} if the window does not have a renderer,
3812or if an error occurs.
3813
3814
3815<procedure>(num-render-drivers) → integer</procedure>
3816
3817See [[https://wiki.libsdl.org/SDL_GetNumRenderDrivers|SDL_GetNumRenderDrivers]].
3818This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3819
3820
3821<procedure>(render-driver-info index) → sdl2:renderer-info</procedure>
3822
3823See [[https://wiki.libsdl.org/SDL_GetRenderDriverInfo|SDL_GetRenderDriverInfo]].
3824This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3825
3826
3827<procedure>(render-present! renderer)</procedure>
3828
3829Update the renderer to show any changes that have occurred.
3830See [[https://wiki.libsdl.org/SDL_RenderPresent|SDL_RenderPresent]].
3831This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3832
3833
3834<procedure>(render-copy! renderer texture #!optional srcrect dstrect) → </procedure>
3835
3836Copy all or part of the given texture onto the renderer.
3837See [[https://wiki.libsdl.org/SDL_RenderCopy|SDL_RenderCopy]].
3838This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3839
3840* {{renderer}} is the sdl2:renderer to copy the texture to.
3841* {{texture}} is the source sdl2:texture.
3842* {{srcrect}} is a sdl2:rect specifying the part of the texture to copy, or #f to copy the whole texture. It defaults to #f.
3843* {{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.
3844
3845Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3846
3847
3848<procedure>(render-copy-ex! renderer texture #!optional srcrect dstrect angle center flip)</procedure>
3849
3850Copy all or part of the given texture onto the renderer,
3851optionally rotating or flipping the texture.
3852See [[https://wiki.libsdl.org/SDL_RenderCopyEx|SDL_RenderCopyEx]].
3853This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3854
3855* {{renderer}} is the sdl2:renderer to copy the texture to.
3856* {{texture}} is the source sdl2:texture.
3857* {{srcrect}} is a sdl2:rect specifying the part of the texture to copy,
3858  or #f to copy the whole texture. It defaults to #f.
3859* {{dstrect}} is a sdl2:rect specifying where on the renderer to copy the texture to,
3860  or #f to copy onto the entire renderer. It defaults to #f.
3861* {{angle}} is a float specifying the angle in degrees to rotate the texture. It defaults to 0.
3862* {{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.
3863* {{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:
3864** {{'horizontal}} = flip the texture horizontally
3865** {{'vertical}} = flip the texture vertically
3866
3867Signals an exception of kind {{(exn sdl2)}} if an error occurs.
3868
3869
3870<procedure>(render-read-pixels-raw renderer rect format pixels-out pitch)</procedure>
3871
3872Read the pixels from some or all of the given renderer.
3873This is for advanced users, and must be used with caution.
3874See [[https://wiki.libsdl.org/SDL_RenderReadPixels|SDL_RenderReadPixels]].
3875This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3876
3877* {{renderer}} is the sdl2:renderer to read from.
3878* {{rect}} is a sdl2:rect specifying the part of the renderer to read, or #f to read the entire renderer.
3879* {{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.
3880* {{pixels-out}} is a pointer or locative where the pixel data will be written.
3881  It must point to a block of memory large enough to hold all the requested pixel data,
3882  or your program may crash or other bad things happen.
3883* {{pitch}} is an integer specifying the pitch of the pixel data.
3884
3885
3886<procedure>(render-clear! renderer)</procedure>
3887
3888Clear the entire renderer, using the renderer's current draw color.
3889See [[https://wiki.libsdl.org/SDL_RenderClear|SDL_RenderClear]].
3890This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3891
3892
3893<procedure>(render-draw-line! renderer x1 y1 x2 y2)</procedure>
3894<procedure>(render-draw-lines! renderer points)</procedure>
3895
3896Draw a line segment or multiple line segments, using the renderer's current draw color and blend mode.
3897See [[https://wiki.libsdl.org/SDL_RenderDrawLine|SDL_RenderDrawLine]]
3898and [[https://wiki.libsdl.org/SDL_RenderDrawLines|SDL_RenderDrawLines]].
3899These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3900
3901* {{render-draw-line!}} draws a single line segment.
3902* {{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.
3903
3904
3905<procedure>(render-draw-point! renderer x y)</procedure>
3906<procedure>(render-draw-points! renderer points)</procedure>
3907
3908Draw one or multiple points, using the renderer's current draw color and blend mode.
3909See [[https://wiki.libsdl.org/SDL_RenderDrawPoint|SDL_RenderDrawPoint]]
3910and [[https://wiki.libsdl.org/SDL_RenderDrawPoints|SDL_RenderDrawPoints]].
3911These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3912
3913* {{render-draw-point!}} draws a single point.
3914* {{render-draw-points!}} draws multiple points. {{points}} must be a list or vector of sdl2:point instances.
3915
3916
3917<procedure>(render-draw-rect! renderer rect)</procedure>
3918<procedure>(render-draw-rects! renderer rects)</procedure>
3919
3920Draw one or multiple outlined rectangles, using the renderer's current draw color and blend mode.
3921See [[https://wiki.libsdl.org/SDL_RenderDrawRect|SDL_RenderDrawRect]]
3922and [[https://wiki.libsdl.org/SDL_RenderDrawRects|SDL_RenderDrawRects]].
3923These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3924
3925* {{render-draw-rect!}} draws a single outlined rect.
3926* {{render-draw-rects!}} draws multiple outlined rects. {{rects}} must be a list or vector of sdl2:rect instances.
3927
3928
3929<procedure>(render-fill-rect! renderer rect)</procedure>
3930<procedure>(render-fill-rects! renderer rects)</procedure>
3931
3932Draw one or multiple filled rectangles, using the renderer's current draw color and blend mode.
3933See [[https://wiki.libsdl.org/SDL_RenderFillRect|SDL_RenderFillRect]]
3934and [[https://wiki.libsdl.org/SDL_RenderFillRects|SDL_RenderFillRects]].
3935These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3936
3937* {{render-draw-rect!}} draws a single filled rect.
3938* {{render-draw-rects!}} draws multiple filled rects. {{rects}} must be a list or vector of sdl2:rect instances.
3939
3940
3941
3942==== sdl2:renderer
3943
3944sdl2:renderer is a record type that wraps a pointer to an SDL_Renderer struct.
3945sdl2:renderer is available in '''sdl2 egg version 0.2.0 and higher'''.
3946
3947
3948<procedure>(renderer? obj) → boolean</procedure>
3949
3950Returns #t if {{obj}} is an sdl2:renderer.
3951This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
3952
3953
3954<procedure>(render-draw-blend-mode renderer) → symbol</procedure>
3955<procedure>(render-draw-blend-mode-raw renderer) → integer</procedure>
3956<setter>(render-draw-blend-mode-set! renderer mode)</setter>
3957<setter>(set! (render-draw-blend-mode renderer) mode)</setter>
3958
3959Get or set the renderer's draw blend mode. This affects future drawing operations.
3960See [[https://wiki.libsdl.org/SDL_GetRenderDrawBlendMode|SDL_GetRenderDrawBlendMode]]
3961and [[https://wiki.libsdl.org/SDL_SetRenderDrawBlendMode|SDL_SetRenderDrawBlendMode]].
3962These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3963
3964* {{render-draw-blend-mode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-mode|blend mode symbol]]:
3965** {{'none}}
3966** {{'blend}}
3967** {{'add}}
3968** {{'mod}}
3969* {{render-draw-blend-mode-raw}} returns an integer.
3970* The setters accept either a symbol or integer.
3971
3972
3973<procedure>(render-draw-color renderer) → sdl2:color</procedure>
3974<procedure>(render-draw-colour renderer) → sdl2:color</procedure>
3975<setter>(render-draw-color-set! renderer color)</setter>
3976<setter>(render-draw-colour-set! renderer color)</setter>
3977<setter>(set! (render-draw-color renderer) color)</setter>
3978<setter>(set! (render-draw-colour renderer) color)</setter>
3979
3980Get or set the renderer's draw color. This affects future drawing operations.
3981See [[https://wiki.libsdl.org/SDL_GetRenderDrawColor|SDL_GetRenderDrawColor]]
3982and [[https://wiki.libsdl.org/SDL_SetRenderDrawColor|SDL_SetRenderDrawColor]].
3983These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3984
3985
3986<procedure>(render-clip-rect renderer) → sdl2:rect</procedure>
3987<setter>(render-clip-rect-set! renderer rect)</setter>
3988<setter>(set! (render-clip-rect renderer) rect)</setter>
3989
3990Get or set the sdl2:renderer's clip rect.
3991See [[https://wiki.libsdl.org/SDL_RenderGetClipRect|SDL_RenderGetClipRect]]
3992and [[https://wiki.libsdl.org/SDL_RenderSetClipRect|SDL_RenderSetClipRect]].
3993These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
3994
3995{{render-clip-rect}} returns a new managed sdl2:rect describing the renderer's clip rect.
3996If clipping is disabled, it returns {{#<sdl2:rect (0 0 0 0)>}}.
3997
3998But, be advised that it also returns {{#<sdl2:rect (0 0 0 0)>}} if that is the current clip rect.
3999So, the meaning of {{#<sdl2:rect (0 0 0 0)>}} is ambiguous.
4000Use {{render-clip-enabled?}} (in SDL 2.0.4 or higher) to unambiguously check whether clipping is enabled or disabled.
4001
4002The setters accept either an sdl2:rect to enable clipping and set the clip rect,
4003or #f to disable clipping.
4004Setting to {{#<sdl2:rect (0 0 0 0)>}} does not disable clipping.
4005
4006
4007<procedure>(render-clip-enabled? renderer) → boolean</procedure>
4008
4009Returns #t if clipping is enabled for the given sdl2:renderer,
4010or #f is clipping is disabled.
4011See [[https://wiki.libsdl.org/SDL_RenderIsClipEnabled|SDL_RenderIsClipEnabled]].
4012This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4013
4014Requires '''SDL 2.0.4 or higher'''.
4015Signals an error if the compiled version of SDL is not high enough.
4016Use the [[#version-feature-identifiers|{{libSDL-2.0.4+}} feature identifier]]
4017to check before calling this procedure.
4018
4019
4020<procedure>(renderer-output-size renderer) → [w h]</procedure>
4021
4022See [[https://wiki.libsdl.org/SDL_GetRendererOutputSize|SDL_GetRendererOutputSize]].
4023This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4024
4025This procedure returns multiple values, the output width and height, as integers.
4026
4027
4028<procedure>(render-logical-size renderer) → [w h]</procedure>
4029<setter>(render-logical-size-set! renderer size)</setter>
4030<setter>(set! (render-logical-size renderer) size)</setter>
4031
4032Get or set the renderer's logical size.
4033See [[https://wiki.libsdl.org/SDL_RenderGetLogicalSize|SDL_RenderGetLogicalSize]]
4034and [[https://wiki.libsdl.org/SDL_RenderSetLogicalSize|SDL_RenderSetLogicalSize]].
4035These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4036
4037* {{render-logical-size}} returns multiple values, the logical width and height, as integers.
4038* The setters accept a list {{(w h)}} containing the new logical width and height, as integers.
4039
4040
4041<procedure>(render-scale renderer) → [x-scale y-scale]</procedure>
4042<setter>(render-scale-set! renderer scales)</setter>
4043<setter>(set! (render-scale-set! renderer) scales)</setter>
4044
4045Get or set the sdl2:renderer's x and y scaling factors.
4046See [[https://wiki.libsdl.org/SDL_RenderGetScale|SDL_RenderGetScale]]
4047and [[https://wiki.libsdl.org/SDL_RenderSetScale|SDL_RenderSetScale]].
4048These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4049
4050* {{render-scale}} returns multiple values, the x and y scaling factors, as integers..
4051* The setters accept a list {{(x-scale y-scale)}} containing the new scaling factors, as integers.
4052
4053
4054<procedure>(render-target-supported? renderer) → boolean</procedure>
4055
4056Returns #t if the given renderer can have a render target.
4057See [[https://wiki.libsdl.org/SDL_RenderTargetSupported|SDL_RenderTargetSupported]].
4058This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4059
4060
4061<procedure>(render-target renderer) → sdl2:texture or #f</procedure>
4062<setter>(render-target-set! renderer target)</setter>
4063<setter>(set! (render-target renderer) target)</setter>
4064
4065Get or set the renderer's render target,
4066i.e. the texture that the renderer will render onto.
4067See [[https://wiki.libsdl.org/SDL_GetRenderTarget|SDL_GetRenderTarget]]
4068and [[https://wiki.libsdl.org/SDL_SetRenderTarget|SDL_SetRenderTarget]].
4069These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4070
4071{{render-target}} returns #f if the renderer has no render target.
4072
4073The setters signal an exception of kind {{(exn sdl2)}} on failure,
4074for example if the renderer does not support a render target.
4075You should use {{render-target-supported?}} to test whether the renderer supports a render target.
4076
4077
4078<procedure>(render-viewport renderer) → sdl2:rect</procedure>
4079<setter>(render-viewport-set! renderer rect)</setter>
4080<setter>(set! (render-viewport renderer) rect)</setter>
4081
4082Get or set the renderer's viewport.
4083See [[https://wiki.libsdl.org/SDL_RenderGetViewport|SDL_RenderGetViewport]]
4084and [[https://wiki.libsdl.org/SDL_RenderSetViewport|SDL_RenderSetViewport]].
4085These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4086
4087
4088
4089==== sdl2:renderer-info
4090
4091sdl2:renderer-info is a record type that wraps a pointer to an
4092[[https://wiki.libsdl.org/SDL_RendererInfo|SDL_RendererInfo]] struct.
4093sdl2:renderer-info is available in '''sdl2 egg version 0.2.0 and higher'''.
4094
4095<procedure>(renderer-info? obj) → boolean</procedure>
4096
4097Returns #t if {{obj}} is an sdl2:renderer-info.
4098This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4099
4100
4101<procedure>(get-renderer-info renderer) → sdl2:renderer-info</procedure>
4102<procedure>(get-renderer-info* renderer) → sdl2:renderer-info</procedure>
4103
4104Return a sdl2:renderer-info with information about the given sdl2:renderer.
4105See [[https://wiki.libsdl.org/SDL_GetRendererInfo|SDL_GetRendererInfo]].
4106These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4107
4108* {{get-renderer-info}} returns a managed sdl2:renderer-info.
4109* {{get-renderer-info*}} returns an unmanaged sdl2:renderer-info, which must be freed using {{free-renderer-info!}} when you are done with it.
4110
4111
4112<procedure>(free-renderer-info! renderer-info)</procedure>
4113
4114Free the memory of the sdl2:renderer-info's underlying struct.
4115{{renderer-info}}'s pointer will be set to null (see {{struct-null?}}).
4116It is safe to call this procedure with managed or unmanaged sdl2:renderer-infos.
4117It is safe (but has no effect) to free a struct record multiple times.
4118This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4119
4120
4121<procedure>(renderer-info-name renderer-info) → string</procedure>
4122
4123Get the sdl2:renderer-info's "name" field, as a string.
4124This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4125
4126
4127<procedure>(renderer-info-flags renderer-info) → list of symbols</procedure>
4128<procedure>(renderer-info-flags-raw renderer-info) → integer</procedure>
4129
4130Get the sdl2:renderer-info's "flags" field, as a list of symbols or an integer.
4131TODO: Link to flags enums.
4132These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4133
4134
4135<procedure>(renderer-info-num-texture-formats renderer-info) → integer</procedure>
4136
4137Get the sdl2:renderer-info's "num-texture-formats" field, as an integer.
4138This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4139
4140
4141<procedure>(renderer-info-texture-formats renderer-info) → list of symbols</procedure>
4142
4143Get the sdl2:renderer-info's "texture-formats" field,
4144as a list of [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbols]].
4145This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4146
4147
4148<procedure>(renderer-info-max-texture-width renderer-info) → integer</procedure>
4149
4150Get the sdl2:renderer-info's "max-texture-width" field, as an integer.
4151This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4152
4153
4154<procedure>(renderer-info-max-texture-height renderer-info) → integer</procedure>
4155
4156Get the sdl2:renderer-info's "max-texture-height" field, as an integer.
4157This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4158
4159
4160
4161=== RWops
4162
4163==== RWops Functions
4164
4165<procedure>(rw-from-file filepath) → sdl2:rwops</procedure>
4166
4167See [[https://wiki.libsdl.org/SDL_RWFromFile|SDL_RWFromFile]].
4168
4169You should close the sdl2:rwops when you are done with it, using
4170{{rw-close!}} or one of the procedures that can automatically close
4171the sdl2:rwops, such as {{load-bmp-rw}}.
4172
4173Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4174
4175
4176<procedure>(rw-from-const-mem pointer) → sdl2:rwops</procedure>
4177
4178See [[https://wiki.libsdl.org/SDL_RWFromConstMem|SDL_RWFromConstMem]].
4179
4180You should close the sdl2:rwops when you are done with it, using
4181{{rw-close!}} or one of the procedures that can automatically close
4182the sdl2:rwops, such as {{load-bmp-rw}}.
4183
4184Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4185
4186
4187<procedure>(rw-from-mem pointer) → sdl2:rwops</procedure>
4188
4189See [[https://wiki.libsdl.org/SDL_RWFromMem|SDL_RWFromMem]].
4190
4191You should close the sdl2:rwops when you are done with it, using
4192{{rw-close!}} or one of the procedures that can automatically close
4193the sdl2:rwops, such as {{load-bmp-rw}}.
4194
4195Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4196
4197
4198<procedure>(rw-from-blob blob) → sdl2:rwops</procedure>
4199
4200Create a new sdl2:rwops that accesses the memory of the given
4201[[http://wiki.call-cc.org/manual/Unit%20library#blobs|blob]]. You
4202should close the sdl2:rwops when you are done with it, using
4203{{rw-close!}} or one of the procedures that can automatically close
4204the sdl2:rwops, such as {{load-bmp-rw}}.
4205
4206Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4207
4208You can also use this procedure to create a sdl2:rwops from a
4209[[/manual/Unit srfi-4|SRFI-4]] numeric vector, by first converting it
4210to a blob using e.g. {{u8vector->blob/shared}}.
4211
4212'''CAUTION:''' Creating a sdl2:rwops from a blob in CHICKEN-managed
4213memory is unstable: the blob might be garbage collected or moved in
4214memory, which would break the sdl2:rwops. To be safe, you should
4215[[/manual/Unit lolevel#object-evict|evict]] the blob and create the
4216sdl2:rwops from the evicted blob (not the original). You may wish to
4217[[/manual/Unit lolevel#object-release|release]] the evicted blob after
4218you have closed the sdl2:rwops. Example:
4219
4220<enscript highlight="scheme">
4221(let* ((evicted-blob (object-evict '#${...}))
4222       (rwops (sdl2:rw-from-blob evicted-blob))
4223       (surf (sdl2:load-bmp-rw rwops #t)))
4224  (object-release evicted-blob)
4225  surf)
4226</enscript>
4227
4228
4229<procedure>(rw-from-string str) → sdl2:rwops</procedure>
4230
4231Create a new sdl2:rwops that accesses the memory of the given CHICKEN
4232Scheme string. You should close the sdl2:rwops when you are done with
4233it, using {{rw-close!}} or one of the procedures that can
4234automatically close the sdl2:rwops, such as {{load-bmp-rw}}.
4235
4236Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4237
4238'''CAUTION:''' Creating a sdl2:rwops from a string in CHICKEN-managed
4239memory is unstable: the string might be garbage collected or moved in
4240memory, which would break the sdl2:rwops. To be safe, you should
4241[[/manual/Unit lolevel#object-evict|evict]] the string and create the
4242sdl2:rwops from the evicted string (not the original). You may wish to
4243[[/manual/Unit lolevel#object-release|release]] the evicted string
4244after you have closed the sdl2:rwops. Example:
4245
4246<enscript highlight="scheme">
4247(let* ((evicted-string (object-evict "..."))
4248       (rwops (sdl2:rw-from-string evicted-string))
4249       (surf (sdl2:load-bmp-rw rwops #t)))
4250  (object-release evicted-string)
4251  surf)
4252</enscript>
4253
4254
4255<procedure>(rw-close! rwops)</procedure>
4256
4257See [[https://wiki.libsdl.org/SDL_RWclose|SDL_RWclose]].
4258
4259Close and clean up the given sdl2:rwops. This frees the memory used by
4260the SDL_RWops struct itself, but does not free or release the pointer,
4261blob, or string that the sdl2:rwops was reading/writing from. (It does
4262close files opened with {{rw-from-file}}, though.)
4263
4264Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4265
4266
4267==== sdl2:rwops
4268
4269sdl2:rwops is a record type that wraps a pointer to an
4270[[https://wiki.libsdl.org/SDL_RWops|SDL_RWops]] struct.
4271
4272
4273<procedure>(rwops? obj) → boolean</procedure>
4274
4275Returns #t if {{obj}} is an sdl2:rwops.
4276
4277
4278<procedure>(rwops-type rwops) → symbol</procedure>
4279<procedure>(rwops-type-raw rwops) → integer</procedure>
4280
4281Get the sdl2:rwops' "type" field, indicating the data source type.
4282
4283* {{rwops-type}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#rwops-types|RWops type symbol]]:
4284** {{'unknown}}
4285** {{'win-file}}
4286** {{'std-file}}
4287** {{'jni-file}}
4288** {{'memory}}
4289** {{'memory-ro}}
4290* {{rwops-type-raw}} returns an integer.
4291
4292
4293
4294=== Surface
4295
4296==== Surface Functions
4297
4298<procedure>(create-rgb-surface* flags width height depth rmask gmask bmask amask) → sdl2:surface</procedure>
4299
4300See [[https://wiki.libsdl.org/SDL_CreateRGBSurface|SDL_CreateRGBSurface]].
4301
4302Returns a new '''unmanaged''' sdl2:surface with the given properties.
4303You must call {{free-surface!}} when you are done with it.
4304
4305See {{make-surface}} for a more convenient interface.
4306
4307Signals an exception of kind {{(exn sdl2)}} if the surface cannot be created.
4308
4309
4310<procedure>(create-rgb-surface-from* pixels width height depth pitch rmask gmask bmask amask) → sdl2:surface</procedure>
4311
4312Returns a new '''unmanaged''' sdl2:surface with the given properties,
4313using existing pixel data (a pointer, e.g. from {{surface-pixels-raw}}).
4314You must call {{free-surface!}} when you are done with it.
4315
4316See [[https://wiki.libsdl.org/SDL_CreateRGBSurfaceFrom|SDL_CreateRGBSurfaceFrom]].
4317
4318Signals an exception of kind {{(exn sdl2)}} if the surface cannot be created.
4319
4320
4321<procedure>(convert-surface surface pixel-format) → sdl2:surface</procedure>
4322<procedure>(convert-surface* surface pixel-format) → sdl2:surface</procedure>
4323
4324Creates a copy of the given sdl2:surface, but converts it to the given sdl2:pixel-format.
4325
4326See [[https://wiki.libsdl.org/SDL_ConvertSurface|SDL_ConvertSurface]].
4327
4328* {{convert-surface}} returns a managed sdl2:surface.
4329* {{convert-surface*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
4330
4331Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4332
4333
4334<procedure>(load-bmp  filepath) → sdl2:surface</procedure>
4335<procedure>(load-bmp* filepath) → sdl2:surface</procedure>
4336
4337See [[https://wiki.libsdl.org/SDL_LoadBMP|SDL_LoadBMP]].
4338
4339Attempts to load a BMP image file.
4340Returns a sdl2:surface containing the image data.
4341Signals an exception of kind {{(exn sdl2)}} if the image could not be loaded.
4342
4343'''NOTE:''' This procedure only supports certain kinds of BMP image.
4344Use the [[/egg/sdl2-image|sdl2-image egg]] for better BMP support,
4345plus support for loading other image formats like JPG, PNG, and GIF.
4346
4347* {{load-bmp}} returns a managed sdl2:surface.
4348* {{load-bmp*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
4349
4350
4351<procedure>(load-bmp-rw  rwops #!optional close?) → sdl2:surface</procedure>
4352<procedure>(load-bmp-rw* rwops #!optional close?) → sdl2:surface</procedure>
4353
4354See [[https://wiki.libsdl.org/SDL_LoadBMP_RW|SDL_LoadBMP_RW]].
4355
4356Attempts to load a BMP image from the given sdl2:rwops.
4357Returns a sdl2:surface containing the image data.
4358Signals an exception of kind {{(exn sdl2)}} if the image could not be loaded.
4359
4360If {{close?}} is #t, {{rwops}} will be automatically closed (see
4361{{rw-close!}}) after the image is loaded. If {{close?}} is #f or
4362omitted, {{rwops}} will not be closed.
4363
4364'''NOTE:''' This procedure only supports certain kinds of BMP image.
4365Use the [[/egg/sdl2-image|sdl2-image egg]] for better BMP support,
4366plus support for loading other image formats like JPG, PNG, and GIF.
4367
4368* {{load-bmp-rw}} returns a managed sdl2:surface.
4369* {{load-bmp-rw*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
4370
4371
4372<procedure>(save-bmp! surface filepath)</procedure>
4373
4374See [[https://wiki.libsdl.org/SDL_SaveBMP|SDL_SaveBMP]].
4375
4376Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4377
4378
4379<procedure>(save-bmp-rw! surface rwops #!optional close?)</procedure>
4380
4381See [[https://wiki.libsdl.org/SDL_SaveBMP_RW|SDL_SaveBMP_RW]].
4382
4383If {{close?}} is #t, {{rwops}} will be automatically closed (see
4384{{rw-close!}}) after the image is loaded. If {{close?}} is #f or
4385omitted, {{rwops}} will not be closed.
4386
4387Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4388
4389
4390<procedure>(lock-surface! surface)</procedure>
4391<procedure>(unlock-surface! surface)</procedure>
4392
4393See [[https://wiki.libsdl.org/SDL_LockSurface|SDL_LockSurface]]
4394and [[https://wiki.libsdl.org/SDL_UnlockSurface|SDL_UnlockSurface]].
4395
4396{{lock-surface!}} signals an exception of kind {{(exn sdl2)}} if an error occurs.
4397
4398
4399<procedure>(must-lock? surface) → boolean</procedure>
4400
4401See [[https://wiki.libsdl.org/SDL_MUSTLOCK|SDL_MUSTLOCK]].
4402
4403
4404<procedure>(blit-surface! src src-rect dest dest-rect)</procedure>
4405
4406See [[https://wiki.libsdl.org/SDL_BlitSurface|SDL_BlitSurface]].
4407
4408May modify dest-rect.
4409
4410Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4411
4412
4413<procedure>(blit-scaled! src src-rect dest dest-rect)</procedure>
4414
4415See [[https://wiki.libsdl.org/SDL_BlitScaled|SDL_BlitScaled]].
4416
4417May modify dest-rect.
4418
4419Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4420
4421
4422<procedure>(fill-rect! surface rect color)</procedure>
4423
4424See [[https://wiki.libsdl.org/SDL_FillRect|SDL_FillRect]].
4425
4426{{rect}} may be an sdl2:rect to fill part of the surface, or #f to fill
4427the entire surface.
4428
4429{{color}} may be an sdl2:color or a mapped color (an integer, like
4430returned by {{map-rgba}}).
4431
4432Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4433
4434
4435<procedure>(fill-rects! surface rects color)</procedure>
4436
4437See [[https://wiki.libsdl.org/SDL_FillRects|SDL_FillRects]].
4438
4439{{rects}} must be a list of sdl2:rects.
4440
4441{{color}} may be an sdl2:color or a mapped color (an integer, like
4442returned by {{map-rgba}}).
4443
4444Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4445
4446
4447<procedure>(surface-ref surface x y) → sdl2:color</procedure>
4448<procedure>(surface-ref-raw surface x y) → integer</procedure>
4449<setter>(set! (surface-ref surface x y) color)</setter>
4450<setter>(surface-set! surface x y color)</setter>
4451
4452Get or set the color of the specified pixel on the surface.
4453
4454* {{surface-ref}} returns an sdl2:color.
4455* {{surface-ref-raw}} returns a mapped color (an integer). You can use {{get-rgba}} to convert the mapped color to color fields.
4456* The setters accept either an sdl2:color or a mapped color.
4457
4458These procedures automatically lock and unlock the surface if needed.
4459They signal an exception of kind {{(exn sdl2)}} if the surface cannot be locked.
4460
4461These procedures signal an exception of kind {{(exn bounds)}} if {{x}} or {{y}} is out of bounds.
4462
4463The setters ignore the surface's clip rect.
4464
4465
4466<procedure>(rotate-surface-90  surface turns) → sdl2:surface</procedure>
4467<procedure>(rotate-surface-90* surface turns) → sdl2:surface</procedure>
4468
4469Return a copy of the given surface rotated by the given number of 90º clockwise turns.
4470{{turns}} must be an integer.
4471For example:
4472
4473* {{turns}} 0 means no rotation
4474* {{turns}} 1 means 90º clockwise rotation
4475* {{turns}} 2 means 180º rotation
4476* {{turns}} 3 (or -1) means 270º clockwise (i.e. 90º counter-clockwise) rotation
4477
4478The new surface will have an equivalent pixel format, color key, blend mode, alpha mod, and color mod as the given surface.
4479If the given surface has a palette, the new surface will share the same palette.
4480The new surface will have no clip rect.
4481
4482Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4483
4484* {{rotate-surface-90}} returns a managed sdl2:surface.
4485* {{rotate-surface-90*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
4486
4487
4488<procedure>(flip-surface  surface flip-x? flip-y?) → sdl2:surface</procedure>
4489<procedure>(flip-surface* surface flip-x? flip-y?) → sdl2:surface</procedure>
4490
4491Return a copy of the given surface flipped on the X (horizontal) and/or Y (vertical) axes.
4492
4493The new surface will have an equivalent pixel format, color key, blend mode, alpha mod, and color mod as the given surface.
4494If the given surface has a palette, the new surface will share the same palette.
4495The new surface will have no clip rect.
4496
4497Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4498
4499* {{flip-surface}} returns a managed sdl2:surface.
4500* {{flip-surface*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
4501
4502
4503
4504==== sdl2:surface
4505
4506sdl2:surface is a record type that wraps a pointer to an
4507[[https://wiki.libsdl.org/SDL_Surface|SDL_Surface]] struct.
4508
4509
4510<procedure>(surface? obj) → boolean</procedure>
4511
4512Returns #t if {{obj}} is an sdl2:surface.
4513
4514
4515<procedure>(make-surface width height depth) → sdl2:surface</procedure>
4516<procedure>(make-surface* width height depth) → sdl2:surface</procedure>
4517
4518Create a new sdl2:surface with the given width, height, and color depth (bits per pixel).
4519This is a more convenient interface for {{create-rgb-surface}}.
4520The sdl2:surface's pixel format and masks will be chosen automatically
4521based on the requested depth and the current platform's byte order (little endian or big endian).
4522
4523These procedures signal an exception of kind {{(exn sdl2)}}
4524if the sdl2:surface could not be created (e.g. because the color depth is unsupported).
4525
4526* {{make-surface}} returns a managed sdl2:surface.
4527* {{make-surface*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
4528
4529
4530<procedure>(free-surface! surface)</procedure>
4531
4532Free the memory of the sdl2:surface's underlying struct. {{surface}}'s
4533pointer will be set to null (see {{struct-null?}}). It is safe to call
4534this procedure with managed or unmanaged sdl2:surfaces. It is safe
4535(but has no effect) to free a struct record multiple times.
4536
4537See [[https://wiki.libsdl.org/SDL_FreeSurface|SDL_FreeSurface]].
4538
4539'''NOTE:''' if {{surface}} was created using
4540{{create-rgb-surface-from}}, then the pixel data is not freed.
4541
4542
4543<procedure>(surface-format surface) → sdl2:pixel-format</procedure>
4544
4545Get the sdl2:surface's "format" field, as a sdl2:pixel-format describing the format of the surface's pixels.
4546
4547
4548<procedure>(surface-w surface) → integer</procedure>
4549
4550Get the sdl2:surface's "w" field, as a nonnegative integer indicating the surface's width in pixels.
4551
4552
4553<procedure>(surface-h surface) → integer</procedure>
4554
4555Get the sdl2:surface's "h" field, as a nonnegative integer indicating the surface's height in pixels.
4556
4557
4558<procedure>(surface-pitch surface) → integer</procedure>
4559
4560Get the sdl2:surface's "pitch" field, as a nonnegative integer indicating how many bytes are used to represent one row of pixel data.
4561
4562
4563<procedure>(surface-pixels-raw surface) → pointer or #f</procedure>
4564
4565Get the sdl2:surface's "pixels" field, as a raw pointer to the sdl2:surface's pixels.
4566Don't use this unless you really know what you are doing!
4567
4568If you want to get or set a pixel, use {{surface-ref}} and {{surface-set!}} instead.
4569They are much safer, more convenient, and more efficient than accessing the pixel data using this pointer.
4570
4571
4572<procedure>(surface-userdata-raw surface) → pointer or #f</procedure>
4573<setter>(set! (surface-userdata-raw surface) val)</setter>
4574<setter>(surface-userdata-raw-set! surface val)</setter>
4575
4576Get or set the sdl2:surface's "userdata" field, as a pointer or #f.
4577
4578If you want to store a pointer to a Scheme object here, be sure to
4579[[/manual/Unit lolevel#object-evict|evict the object]] first. Otherwise
4580the object's location in memory might change, rendering the pointer
4581invalid.
4582
4583
4584<procedure>(surface-refcount surface) → integer</procedure>
4585<setter>(set! (surface-refcount surface) val)</setter>
4586<setter>(surface-refcount-set! surface val)</setter>
4587
4588Get or set the sdl2:surface's "refcount" field, as an integer.
4589
4590
4591<procedure>(surface-clip-rect surface) → sdl2:rect</procedure>
4592<setter>(set! (surface-clip-rect surface) rect) → boolean</setter>
4593<setter>(surface-clip-rect-set! surface rect) → boolean</setter>
4594
4595{{surface-clip-rect}} returns a copy of the surface's clip rect.
4596See [[https://wiki.libsdl.org/SDL_GetClipRect|SDL_GetClipRect]].
4597
4598The setters sets the surface's clip rect to a copy of the given rect.
4599{{rect}} may be #f, which disables clipping.
4600See [[https://wiki.libsdl.org/SDL_SetClipRect|SDL_SetClipRect]].
4601
4602The 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).
4603
4604
4605<procedure>(surface-color-key surface) → sdl2:color or #f</procedure>
4606<procedure>(surface-colour-key surface) → sdl2:color or #f</procedure>
4607<procedure>(surface-color-key-raw surface) → integer or #f</procedure>
4608<procedure>(surface-colour-key-raw surface) → integer or #f</procedure>
4609<setter>(set! (surface-color-key surface) color)</setter>
4610<setter>(set! (surface-colour-key surface) color)</setter>
4611<setter>(surface-color-key-set! surface color)</setter>
4612<setter>(surface-colour-key-set! surface color)</setter>
4613
4614Get or set the sdl2:surface's color key.
4615
4616See [[https://wiki.libsdl.org/SDL_GetColorKey|SDL_GetColorKey]]
4617and [[https://wiki.libsdl.org/SDL_SetColorKey|SDL_SetColorKey]].
4618
4619* {{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.
4620* {{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.
4621* The setters accept either an sdl2:color, a mapped color (an integer), or #f to disable color keying.
4622
4623These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4624
4625
4626<procedure>(surface-alpha-mod surface) → integer</procedure>
4627<setter>(set! (surface-alpha-mod surface) mod)</setter>
4628<setter>(surface-alpha-mod-set! surface mod)</setter>
4629
4630See [[https://wiki.libsdl.org/SDL_GetSurfaceAlphaMod|SDL_GetSurfaceAlphaMod]]
4631and [[https://wiki.libsdl.org/SDL_SetSurfaceAlphaMod|SDL_SetSurfaceAlphaMod]].
4632
4633These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4634
4635
4636<procedure>(surface-blend-mode surface) → symbol</procedure>
4637<procedure>(surface-blend-mode-raw surface) → integer</procedure>
4638<setter>(set! (surface-blend-mode surface) mode)</setter>
4639<setter>(surface-blend-mode-set! surface mode)</setter>
4640
4641See [[https://wiki.libsdl.org/SDL_GetSurfaceBlendMode|SDL_GetSurfaceBlendMode]]
4642and [[https://wiki.libsdl.org/SDL_SetSurfaceBlendMode|SDL_SetSurfaceBlendMode]].
4643
4644* {{surface-blend-mode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-mode|blend mode symbol]]:
4645** {{'none}}
4646** {{'blend}}
4647** {{'add}}
4648** {{'mod}}
4649* {{surface-blend-mode-raw}} returns an integer.
4650* The setters accept either a symbol or integer.
4651
4652These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4653
4654
4655<procedure>(surface-color-mod surface) → [r g b]</procedure>
4656<procedure>(surface-colour-mod surface) → [r g b]</procedure>
4657<setter>(set! (surface-color-mod surface) rgb)</setter>
4658<setter>(set! (surface-colour-mod surface) rgb)</setter>
4659<setter>(surface-color-mod-set! surface rgb)</setter>
4660<setter>(surface-colour-mod-set! surface rgb)</setter>
4661
4662See [[https://wiki.libsdl.org/SDL_GetSurfaceColorMod|SDL_GetSurfaceColorMod]]
4663and [[https://wiki.libsdl.org/SDL_SetSurfaceColorMod|SDL_SetSurfaceColorMod]].
4664
4665{{surface-color-mod}} and {{surface-colour-mod}} return multiple values.
4666
4667The setters accept either a list {{(r g b)}} of color values, or an sdl2:color (the sdl2:color's "a" field will be ignored).
4668
4669These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4670
4671
4672<procedure>(surface-palette surface) → sdl2:palette or #f</procedure>
4673<setter>(set! (surface-palette surface) palette)</setter>
4674<setter>(surface-palette-set! surface palette)</setter>
4675
4676{{surface-palette}} returns the surface's palette, or #f if it has no palette.
4677It is equivalent to {{(compose pixel-format-palette surface-format)}}.
4678
4679The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
4680
4681See [[https://wiki.libsdl.org/SDL_SetSurfacePalette|SDL_SetSurfacePalette]].
4682
4683
4684<setter>(surface-rle-set! surface enable?)</setter>
4685
4686Enable RLE acceleration if {{enable?}} is #t, or disable RLE acceleration if {{enable?}} is #f.
4687See [[https://wiki.libsdl.org/SDL_SetSurfaceRLE|SDL_SetSurfaceRLE]].
4688
4689Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4690
4691
4692
4693=== Texture
4694
4695Texture is one part of [[https://wiki.libsdl.org/CategoryRender|2D Accelerated Rendering]].
4696See also [[#renderer|Renderer]].
4697
4698Renderer support is available in '''sdl2 egg 0.2.0 and higher'''.
4699
4700
4701==== sdl2:texture
4702
4703sdl2:texture is a record type that wraps a pointer to an
4704[[https://wiki.libsdl.org/SDL_Texture|SDL_Texture]] struct.
4705
4706Textures are available in '''sdl2 egg version 0.2.0 and higher'''.
4707
4708
4709<procedure>(texture? obj) → boolean</procedure>
4710
4711Returns #t if {{obj}} is an sdl2:texture.
4712
4713This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4714
4715
4716<procedure>(create-texture renderer format access w h) → sdl2:texture</procedure>
4717<procedure>(create-texture* renderer format access w h) → sdl2:texture</procedure>
4718
4719Create a new sdl2:texture using the given sdl2:renderer and settings.
4720
4721* {{renderer}} must be a sdl2:renderer.
4722* {{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.
4723* {{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:
4724** {{'static}}
4725** {{'streaming}}
4726** {{'target}}
4727* {{w}} must be an integer, specifying the texture's width in pixels.
4728* {{h}} must be an integer, specifying the texture's height in pixels.
4729
4730These procedures signal an exception of kind {{(exn sdl2)}} if the sdl2:texture could not be created.
4731
4732* {{create-texture}} returns a managed sdl2:texture.
4733* {{create-texture*}} returns an unmanaged sdl2:texture,
4734  which must be destroyed with {{destroy-texture!}} when you are done with it.
4735
4736These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4737
4738
4739<procedure>(create-texture-from-surface renderer surface) → sdl2:texture</procedure>
4740<procedure>(create-texture-from-surface* renderer surface) → sdl2:texture</procedure>
4741
4742Create a new sdl2:texture from a sdl2:surface.
4743
4744The texture will contain a copy of the pixel data from the surface.
4745The texture will have the same color mod and alpha mod as the surface.
4746If the surface had a color key, the texture will have {{'blend}} blend mode;
4747otherwise it will have the same blend mode as the surface.
4748
4749* {{create-texture-from-surface}} returns a managed sdl2:texture.
4750* {{create-texture-from-surface*}} returns an unmanaged sdl2:texture,
4751  which must be destroyed with {{destroy-texture!}} when you are done with it.
4752
4753These procedures signal an exception of kind {{(exn sdl2)}} if the sdl2:texture could not be created.
4754
4755These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4756
4757
4758<procedure>(destroy-texture! texture)</procedure>
4759
4760Destroy the sdl2:texture, freeing its underlying struct.
4761{{texture}}'s pointer will be set to null (see {{struct-null?}}).
4762It is safe to call tihs procedure with managed on unmanaged sdl2:textures.
4763It is safe (but has no effect) to destroy an sdl2:texture multiple times.
4764
4765See [[https://wiki.libsdl.org/SDL_DestroyTexture|SDL_DestroyTexture]].
4766
4767This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4768
4769
4770<procedure>(query-texture texture) → [format access w h]</procedure>
4771<procedure>(query-texture-raw texture) → [format-int access-int w h]</procedure>
4772
4773Get multiple pieces of information about the texture.
4774See [[https://wiki.libsdl.org/SDL_QueryTexture|SDL_QueryTexture]].
4775
4776{{query-texture}} returns multiple values:
4777
4778; 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]]
4779; 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]]
4780; w : The sdl2:texture's width, as a nonnegative integer measured in pixels
4781; h : The sdl2:texture's height, as a nonnegative integer measured in pixels
4782
4783{{query-texture-raw}} is similar, except it returns raw integer values (not symbols) for format and access.
4784
4785These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4786
4787If you only want one of these pieces of information,
4788it is more convenient and efficient to use one of these procedures instead:
4789
4790* {{texture-format}}
4791* {{texture-access}}
4792* {{texture-w}}
4793* {{texture-h}}
4794
4795
4796<procedure>(texture-format texture) → symbol</procedure>
4797
4798Get the sdl2:texture's pixel format, as a pixel format enum symbol.
4799This is equivalent to {{(nth-value 0 (query-texture texture))}},
4800but more convenient and efficient.
4801
4802This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4803
4804
4805<procedure>(texture-access texture) → symbol</procedure>
4806
4807Get the sdl2:texture's access mode, as a texture access enum symbol.
4808This is equivalent to {{(nth-value 1 (query-texture texture))}},
4809but more convenient and efficient.
4810
4811This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4812
4813
4814<procedure>(texture-w texture) → integer</procedure>
4815
4816Get the sdl2:texture's width, as a nonnegative integer measured in pixels.
4817This is equivalent to {{(nth-value 2 (query-texture texture))}},
4818but more convenient and efficient.
4819
4820This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4821
4822
4823<procedure>(texture-h texture) → integer</procedure>
4824
4825Get the sdl2:texture's height, as a nonnegative integer measured in pixels.
4826This is equivalent to {{(nth-value 3 (query-texture texture))}},
4827but more convenient and efficient.
4828
4829This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4830
4831
4832<procedure>(texture-alpha-mod texture) → integer</procedure>
4833<setter>(set! (texture-alpha-mod texture) mod)</setter>
4834<setter>(texture-alpha-mod-set! texture mod)</setter>
4835
4836See [[https://wiki.libsdl.org/SDL_GetTextureAlphaMod|SDL_GetTextureAlphaMod]]
4837and [[https://wiki.libsdl.org/SDL_SetTextureAlphaMod|SDL_SetTextureAlphaMod]].
4838
4839These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4840
4841These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4842
4843
4844<procedure>(texture-blend-mode texture) → symbol</procedure>
4845<procedure>(texture-blend-mode-raw texture) → integer</procedure>
4846<setter>(set! (texture-blend-mode texture) mode)</setter>
4847<setter>(texture-blend-mode-set! texture mode)</setter>
4848
4849See [[https://wiki.libsdl.org/SDL_GetTextureBlendMode|SDL_GetTextureBlendMode]]
4850and [[https://wiki.libsdl.org/SDL_SetTextureBlendMode|SDL_SetTextureBlendMode]].
4851
4852* {{texture-blend-mode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-mode|blend mode symbol]]:
4853** {{'none}}
4854** {{'blend}}
4855** {{'add}}
4856** {{'mod}}
4857* {{texture-blend-mode-raw}} returns an integer.
4858* The setters accept either a symbol or integer.
4859
4860These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4861
4862These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4863
4864
4865<procedure>(texture-color-mod texture) → [r g b]</procedure>
4866<procedure>(texture-colour-mod texture) → [r g b]</procedure>
4867<setter>(set! (texture-color-mod texture) rgb)</setter>
4868<setter>(set! (texture-colour-mod texture) rgb)</setter>
4869<setter>(texture-color-mod-set! texture rgb)</setter>
4870<setter>(texture-colour-mod-set! texture rgb)</setter>
4871
4872See [[https://wiki.libsdl.org/SDL_GetTextureColorMod|SDL_GetTextureColorMod]]
4873and [[https://wiki.libsdl.org/SDL_SetTextureColorMod|SDL_SetTextureColorMod]].
4874
4875{{texture-color-mod}} and {{texture-colour-mod}} return multiple values.
4876
4877The setters accept either a list {{(r g b)}} of color values, or an sdl2:color (the sdl2:color's "a" field will be ignored).
4878
4879These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
4880
4881These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
4882
4883
4884<procedure>(lock-texture-raw! texture rect) → [pixels pitch]</procedure>
4885
4886Lock the texture so that its pixel data can be overwritten.
4887This is for advanced users, and must be used with caution.
4888See [[https://wiki.libsdl.org/SDL_LockTexture|SDL_LockTexture]].
4889See also {{unlock-texture!}}.
4890
4891* {{texture}} is the sdl2:texture that you wish to modify
4892* {{rect}} is either an sdl2:rect (to lock part of the texture), or #f (to lock all of the texture).
4893
4894This procedure returns multiple values:
4895
4896; pixels : A raw pointer that you can write pixel data to. Does not necessarily contain the old data.
4897; pitch : An integer indicating the pitch of the pixel data
4898
4899Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4900
4901This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4902
4903
4904<procedure>(unlock-texture! texture)</procedure>
4905
4906Unlock the texture, applying the new pixel data to the texture.
4907This is for advanced users, and must be used with caution.
4908See [[https://wiki.libsdl.org/SDL_UnlockTexture|SDL_UnlockTexture]].
4909See also {{lock-texture-raw!}}.
4910
4911This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4912
4913
4914<procedure>(update-texture-raw! texture rect pixels pitch)</procedure>
4915
4916Overwrite part or all of the texture's pixel data.
4917This is for advanced users, and must be used with caution.
4918See [[https://wiki.libsdl.org/SDL_UpdateTexture|SDL_UpdateTexture]].
4919
4920* {{texture}} is the sdl2:texture that you wish to update
4921* {{rect}} is either an sdl2:rect (to update part of the texture), or #f (to update all of the texture)
4922* {{pixels}} is a pointer or locative to raw pixel data
4923* {{pitch}} is an integer describing the pitch of the pixel data
4924
4925Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4926
4927This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4928
4929
4930<procedure>(update-yuv-texture-raw! texture rect y-plane y-pitch u-plane u-pitch v-plane v-pitch)</procedure>
4931
4932Overwrite part or all of a YV12- or IYUV-formatted texture's pixel data.
4933This is for advanced users, and must be used with caution.
4934See [[https://wiki.libsdl.org/SDL_UpdateYUVTexture|SDL_UpdateYUVTexture]].
4935
4936* {{texture}} is the sdl2:texture that you wish to update
4937* {{rect}} is either an sdl2:rect (to update part of the texture), or #f (to update all of the texture)
4938* {{y-plane}} is a pointer or locative to raw pixel data for the Y plane
4939* {{y-pitch}} is an integer describing the pitch of the Y pixel data
4940* {{u-plane}} is a pointer or locative to raw pixel data for the U plane
4941* {{u-pitch}} is an integer describing the pitch of the U pixel data
4942* {{v-plane}} is a pointer or locative to raw pixel data for the V plane
4943* {{v-pitch}} is an integer describing the pitch of the V pixel data
4944
4945Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4946
4947This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
4948It requires '''SDL 2.0.1 or higher'''.
4949It signals an error if the compiled version of SDL is not high enough.
4950Use the [[#version-feature-identifiers|{{libSDL-2.0.1+}} feature identifier]]
4951to check before calling this procedure.
4952
4953
4954
4955=== Timer
4956
4957<procedure>(delay! milliseconds)</procedure>
4958
4959See [[https://wiki.libsdl.org/SDL_Delay|SDL_Delay]].
4960
4961'''CAUTION:''' This procedure is not compatible with [[/manual/Unit srfi-18|SRFI-18]]
4962threads. It will cause '''all threads to sleep''' for the given
4963duration. If you are using multiple threads, you should instead call
4964SRFI-18's {{thread-sleep!}}, which will cause only the current thread
4965to sleep. For example, call {{(thread-sleep! 0.025)}} instead of
4966{{(delay! 25)}}.
4967
4968
4969<procedure>(get-ticks) → integer</procedure>
4970
4971See [[https://wiki.libsdl.org/SDL_GetTicks|SDL_GetTicks]].
4972
4973
4974<procedure>(get-performance-counter) → integer</procedure>
4975
4976See [[https://wiki.libsdl.org/SDL_GetPerformanceCounter|SDL_GetPerformanceCounter]].
4977
4978
4979<procedure>(get-performance-frequency) → integer</procedure>
4980
4981See [[https://wiki.libsdl.org/SDL_GetPerformanceFrequency|SDL_GetPerformanceFrequency]].
4982
4983
4984
4985=== Touch / Gesture
4986
4987==== Touch / Gesture Functions
4988
4989<procedure>(get-num-touch-devices) → integer</procedure>
4990
4991See [[https://wiki.libsdl.org/SDL_GetNumTouchDevices|SDL_GetNumTouchDevices]].
4992
4993
4994<procedure>(get-touch-device device-id) → integer</procedure>
4995
4996See [[https://wiki.libsdl.org/SDL_GetTouchDevice|SDL_GetTouchDevice]].
4997
4998Signals an exception of kind {{(exn sdl2)}} if an error occurs.
4999
5000
5001<procedure>(get-num-touch-fingers touch-id) → integer</procedure>
5002
5003See [[https://wiki.libsdl.org/SDL_GetNumTouchFingers|SDL_GetNumTouchFingers]].
5004
5005
5006<procedure>(get-touch-finger touch-id index) → sdl2:finger</procedure>
5007
5008See [[https://wiki.libsdl.org/SDL_GetTouchFinger|SDL_GetTouchFinger]].
5009
5010Signals an exception of kind {{(exn sdl2)}} if an error occurs.
5011
5012
5013==== sdl2:finger
5014
5015sdl2:finger is a record type that wraps a pointer to an
5016[[https://wiki.libsdl.org/SDL_Finger|SDL_Finger]] struct.
5017
5018
5019<procedure>(finger? obj) → boolean</procedure>
5020
5021Returns #t if {{obj}} is an sdl2:finger.
5022
5023
5024<procedure>(finger-id finger) → integer</procedure>
5025
5026Get the sdl2:finger's "id" field, as an integer.
5027
5028
5029<procedure>(finger-x finger) → float</procedure>
5030
5031Get 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.
5032
5033
5034<procedure>(finger-y finger) → float</procedure>
5035
5036Get 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.
5037
5038
5039<procedure>(finger-pressure finger) → float</procedure>
5040
5041Get 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.
5042
5043
5044
5045=== Version
5046
5047==== Version Feature Identifiers
5048
5049In '''sdl2 egg version 0.2.0 and higher''', the egg automatically registers feature identifiers
5050which can be used to detect the versions of the sdl2 egg and SDL at compile time or run time,
5051for example using the {{cond-expand}} macro, {{#+foo}} syntax, or the {{feature?}} procedure.
5052
5053Some or all of the following feature identifiers will be registered depending on the circumstances:
5054
5055<table>
5056  <tr>
5057    <th>Feature ID</th>
5058    <th>Meaning</th>
5059  </tr>
5060  <tr>
5061    <td>sdl2</td>
5062    <td>Using any version of the sdl2 egg</td>
5063  <tr>
5064  <tr>
5065    <td>sdl2-0.2.0+</td>
5066    <td>Using sdl2 egg 0.2.0 or higher</td>
5067  <tr>
5068  <tr>
5069    <td>libSDL-2.0.0+</td>
5070    <td>The sdl2 egg was compiled with SDL 2.0.0 or higher</td>
5071  <tr>
5072  <tr>
5073    <td>libSDL-2.0.1+</td>
5074    <td>... 2.0.1 or higher</td>
5075  <tr>
5076  <tr>
5077    <td>libSDL-2.0.2+</td>
5078    <td>... 2.0.2 or higher</td>
5079  <tr>
5080  <tr>
5081    <td>libSDL-2.0.3+</td>
5082    <td>... 2.0.3 or higher</td>
5083  <tr>
5084  <tr>
5085    <td>libSDL-2.0.4+</td>
5086    <td>... 2.0.4 or higher</td>
5087  </tr>
5088</table>
5089
5090These 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.
5091
5092Here are some examples of how you can use these identifiers:
5093
5094<enscript highlight="scheme">
5095(use (prefix sdl2 sdl2:))
5096
5097;; Compile time check using #+foo reader syntax:
5098#+(not sdl2-0.2.0+)
5099(begin-for-syntax
5100  (error "You need sdl2 egg 0.2.0 or higher to compile this program."))
5101
5102;; Compile-time check using cond-expand macro:
5103(cond-expand
5104 (libSDL-2.0.4+
5105  (include "file-that-needs-SDL-204.scm"))
5106 (else
5107  (include "alternative-file.scm")))
5108
5109;; Run-time check using feature? procedure:
5110(when (feature? 'sdl2)
5111  (print "You are using the sdl2 egg. The future seems bright."))
5112</enscript>
5113
5114
5115==== Version Functions
5116
5117<procedure>(version-at-least? major minor patch) → boolean</procedure>
5118
5119See [[https://wiki.libsdl.org/SDL_VERSION_ATLEAST|SDL_VERSION_ATLEAST]].
5120
5121Returns #t if the sdl2 egg was compiled with a version of SDL at least as high as specified.
5122For example, {{(version-at-least? 2 0 1)}} returns #t if the sdl2 egg was compiled with SDL 2.0.1 or higher.
5123
5124Some SDL features are only available after a certain version, so you can use this procedure to check whether the feature is available.
5125
5126
5127<procedure>(compiled-version) → list of integers</procedure>
5128<procedure>(current-version) → list of integers</procedure>
5129
5130Returns a list of three nonnegative integers, indicating a version number of SDL.
5131For example, the list {{(2 0 3)}} indicates SDL 2.0.3.
5132
5133* {{compiled-version}} returns the version of SDL that the sdl2 egg was compiled with.
5134* {{current-version}} returns the version of SDL that the sdl2 egg is currently using.
5135
5136For 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.
5137In such a case, {{compiled-version}} would return {{(2 0 3)}}, and {{current-version}} would return {{(2 1 0)}}.
5138But, features from the new version would not be available until the user recompiles the sdl2 egg.
5139
5140See [[https://wiki.libsdl.org/SDL_VERSION|SDL_VERSION]]
5141and [[https://wiki.libsdl.org/SDL_GetVersion|SDL_GetVersion]].
5142
5143
5144<constant>(egg-version) → list of integers</constant>
5145
5146Returns a list of three nonnegative integers,
5147indicating the version number of the sdl2 egg itself,
5148which is independent of the version number of SDL.
5149For example, the list {{'(1 2 3)}} means sdl2 egg version 1.2.3.
5150
5151'''NOTE:''' This procedure is available in '''sdl2 egg version 0.2.0 or higher'''.
5152If you want to check the egg version,
5153but users of your program might be using earlier than egg version 0.2.0,
5154you can add the following code to your program.
5155It will define the {{egg-version}} procedure only if using an earlier version of the sdl2 egg.
5156
5157<enscript highlight="scheme">
5158(use (prefix sdl2 sdl2:))
5159
5160#+(not sdl2-0.2.0+)
5161(define (sdl2:egg-version) '(0 1 1))
5162
5163;; Usage:
5164(printf "You are using sdl2 egg version ~S.~%" (sdl2:egg-version))
5165</enscript>
5166
5167
5168
5169=== Window / Display Mode
5170
5171==== Window / Display Mode Functions
5172
5173<procedure>(create-window! title x y w h #!optional flags) → sdl2:window</procedure>
5174
5175See [[https://wiki.libsdl.org/SDL_CreateWindow|SDL_CreateWindow]].
5176
5177{{x}} and {{y}} can be integers, the symbol {{'centered}}, or the symbol {{'undefined}}.
5178
5179{{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):
5180
5181* {{'fullscreen}}
5182* {{'fullscreen-desktop}}
5183* {{'opengl}}
5184* {{'shown}}
5185* {{'hidden}}
5186* {{'borderless}}
5187* {{'resizable}}
5188* {{'minimized}}
5189* {{'maximized}}
5190* {{'input-grabbed}}
5191* {{'input-focus}}
5192* {{'mouse-focus}}
5193* {{'foreign}}
5194* {{'allow-high-dpi}} (requires '''sdl2 egg 0.2.0 and SDL 2.0.1 or higher''')
5195* {{'mouse-capture}} (requires '''sdl2 egg 0.2.0 and SDL 2.0.4 or higher''')
5196
5197
5198<procedure>(destroy-window! window)</procedure>
5199
5200See [[https://wiki.libsdl.org/SDL_DestroyWindow|SDL_DestroyWindow]].
5201
5202
5203<procedure>(get-window-from-id id) → sdl2:window</procedure>
5204
5205See [[https://wiki.libsdl.org/SDL_GetWindowFromID|SDL_GetWindowFromID]].
5206
5207'''NOTE:''' The returned window will be a new sdl2:window record pointing to the address of the existing window.
5208It will be {{equal?}} to other sdl2:window records for the same window, but not {{eq?}}.
5209
5210In '''sdl2 egg version 0.2.0 and higher''', this procedure signals an exception
5211of kind {{(exn sdl2)}} if there is no window with the given ID.
5212In earlier egg versions, this procedure returned a null sdl2:window.
5213
5214
5215<procedure>(update-window-surface! window)</procedure>
5216
5217See [[https://wiki.libsdl.org/SDL_UpdateWindowSurface|SDL_UpdateWindowSurface]].
5218
5219Signals an exception of kind {{(exn sdl2)}} if an error occurs.
5220
5221
5222<procedure>(update-window-surface-rects! window rects)</procedure>
5223
5224See [[https://wiki.libsdl.org/SDL_UpdateWindowSurfaceRects|SDL_UpdateWindowSurfaceRects]].
5225
5226{{rects}} must be a list of sdl2:rects.
5227
5228Signals an exception of kind {{(exn sdl2)}} if an error occurs.
5229
5230
5231<procedure>(show-window! window)</procedure>
5232
5233See [[https://wiki.libsdl.org/SDL_ShowWindow|SDL_ShowWindow]].
5234
5235
5236<procedure>(hide-window! window)</procedure>
5237
5238See [[https://wiki.libsdl.org/SDL_HideWindow|SDL_HideWindow]].
5239
5240
5241<procedure>(maximize-window! window)</procedure>
5242
5243See [[https://wiki.libsdl.org/SDL_MaximizeWindow|SDL_MaximizeWindow]].
5244
5245
5246<procedure>(minimize-window! window)</procedure>
5247
5248See [[https://wiki.libsdl.org/SDL_MinimizeWindow|SDL_MinimizeWindow]].
5249
5250
5251<procedure>(raise-window! window)</procedure>
5252
5253See [[https://wiki.libsdl.org/SDL_RaiseWindow|SDL_RaiseWindow]].
5254
5255
5256<procedure>(restore-window! window)</procedure>
5257
5258See [[https://wiki.libsdl.org/SDL_RestoreWindow|SDL_RestoreWindow]].
5259
5260
5261
5262==== sdl2:window
5263
5264sdl2:window is a record type that wraps a pointer to an
5265[[https://wiki.libsdl.org/SDL_CreateWindow|SDL_Window]] struct.
5266
5267
5268<procedure>(window? obj) → boolean</procedure>
5269
5270Returns #t if {{obj}} is an sdl2:window.
5271
5272
5273<procedure>(window-bordered? window) → boolean</procedure>
5274<setter>(set! (window-bordered? window) bordered)</setter>
5275<setter>(window-bordered-set! window bordered)</setter>
5276
5277Get or set whether the window has a border (window decoration).
5278#t means the window has a border, #f means the window is borderless.
5279
5280Setting this to #f has essentially the same effect as passing the {{'borderless}} flag to {{create-window!}} when creating the window.
5281
5282See [[https://wiki.libsdl.org/SDL_SetWindowBordered|SDL_SetWindowBordered]].
5283
5284
5285<procedure>(window-brightness window) → float</procedure>
5286<setter>(set! (window-brightness window) brightness)</setter>
5287<setter>(window-brightness-set! window brightness)</setter>
5288
5289See [[https://wiki.libsdl.org/SDL_GetWindowBrightness|SDL_GetWindowBrightness]]
5290and [[https://wiki.libsdl.org/SDL_SetWindowBrightness|SDL_SetWindowBrightness]].
5291
5292The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
5293
5294
5295<procedure>(window-display-index window) → integer</procedure>
5296
5297See [[https://wiki.libsdl.org/SDL_GetWindowDisplayIndex|SDL_GetWindowDisplayIndex]].
5298
5299Signals an exception of kind {{(exn sdl2)}} if an error occurs.
5300
5301
5302<procedure>(window-display-mode window) → sdl2:display-mode</procedure>
5303<setter>(set! (window-display-mode window) display-mode)</setter>
5304<setter>(window-display-mode-set! window display-mode)</setter>
5305
5306See [[https://wiki.libsdl.org/SDL_GetWindowDisplayMode|SDL_GetWindowDisplayMode]]
5307and [[https://wiki.libsdl.org/SDL_SetWindowDisplayMode|SDL_SetWindowDisplayMode]].
5308
5309These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
5310
5311
5312<procedure>(window-flags window) → list of symbols</procedure>
5313<procedure>(window-flags-raw window) → integer</procedure>
5314
5315See [[https://wiki.libsdl.org/SDL_GetWindowFlags|SDL_GetWindowFlags]].
5316
5317* {{window-flags}} returns a list of [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#window-flags|window flag symbols]].
5318* {{window-flags-raw}} returns an integer bitfield.
5319
5320
5321<procedure>(window-fullscreen window) → symbol or #f</procedure>
5322<setter>(set! (window-fullscreen window) mode)</setter>
5323<setter>(window-fullscreen-set! window mode)</setter>
5324
5325Get or set the sdl2:window's fullscreen mode.
5326See [[https://wiki.libsdl.org/SDL_SetWindowFullscreen|SDL_SetWindowFullscreen]].
5327
5328{{window-fullscreen}} returns one of the following values:
5329
5330* {{'fullscreen}} means "real" fullscreen mode
5331* {{'fullscreen-desktop}} means "fake" fullscreen mode that takes the size of the desktop
5332* {{#f}} means windowed (non-fullscreen) mode
5333
5334The setters accept any of the above values, or #t (which means the same as {{'fullscreen}}), or an equivalent integer value.
5335
5336The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
5337
5338
5339<procedure>(window-grab? window) → boolean</procedure>
5340<setter>(set! (window-grab? window) grab?)</setter>
5341<setter>(window-grab-set! window grab?)</setter>
5342
5343See [[https://wiki.libsdl.org/SDL_GetWindowGrab|SDL_GetWindowGrab]]
5344and [[https://wiki.libsdl.org/SDL_SetWindowGrab|SDL_SetWindowGrab]].
5345
5346
5347<procedure>(grabbed-window) → sdl2:window or #f</procedure>
5348
5349Returns the sdl2:window that currently has input grab, or #f if no window has input grab.
5350See [[https://wiki.libsdl.org/SDL_GetGrabbedWindow|SDL_GetGrabbedWindow]].
5351
5352'''NOTE:''' The returned window will be a new sdl2:window record pointing to the address of the existing window.
5353It will be {{equal?}} to other sdl2:window records for the same window, but not {{eq?}}.
5354
5355This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
5356It requires '''SDL 2.0.4 or higher'''.
5357It signals an error if the compiled version of SDL is not high enough.
5358Use the [[#version-feature-identifiers|{{libSDL-2.0.4+}} feature identifier]]
5359to check before calling this procedure.
5360
5361
5362<setter>(window-icon-set! window icon-surface)</setter>
5363
5364See [[https://wiki.libsdl.org/SDL_SetWindowIcon|SDL_SetWindowIcon]].
5365
5366
5367<procedure>(window-id window) → integer</procedure>
5368
5369See [[https://wiki.libsdl.org/SDL_GetWindowID|SDL_GetWindowID]].
5370
5371
5372<procedure>(window-maximum-size window) → [width height]</procedure>
5373<setter>(set! (window-maximum-size window) size)</setter>
5374<setter>(window-maximum-size-set! window size)</setter>
5375
5376See [[https://wiki.libsdl.org/SDL_GetWindowMaximumSize|SDL_GetWindowMaximumSize]]
5377and [[https://wiki.libsdl.org/SDL_SetWindowMaximumSize|SDL_SetWindowMaximumSize]].
5378
5379{{window-maximum-size}} returns multiple values.
5380
5381The setters accept a list of integers {{(width height)}}.
5382
5383
5384<procedure>(window-minimum-size window) → [width height]</procedure>
5385<setter>(set! (window-minimum-size window) size)</setter>
5386<setter>(window-minimum-size-set! window size)</setter>
5387
5388See [[https://wiki.libsdl.org/SDL_GetWindowMinimumSize|SDL_GetWindowMinimumSize]]
5389and [[https://wiki.libsdl.org/SDL_SetWindowMinimumSize|SDL_SetWindowMinimumSize]].
5390
5391{{window-minimum-size}} returns multiple values.
5392
5393The setters accept a list of integers {{(width height)}}.
5394
5395
5396<procedure>(window-pixel-format window) → symbol</procedure>
5397<procedure>(window-pixel-format-raw window) → integer</procedure>
5398
5399Returns a symbol or integer indicating the given window's pixel format.
5400See [[https://wiki.libsdl.org/SDL_GetWindowPixelFormat|SDL_GetWindowPixelFormat]].
5401
5402* {{window-pixel-format}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]].
5403* {{window-pixel-format-raw}} returns an integer.
5404
5405
5406<procedure>(window-position window) → [x y]</procedure>
5407<setter>(set! (window-position window) pos)</setter>
5408<setter>(window-position-set! window pos)</setter>
5409
5410See [[https://wiki.libsdl.org/SDL_GetWindowPosition|SDL_GetWindowPosition]]
5411and [[https://wiki.libsdl.org/SDL_SetWindowPosition|SDL_SetWindowPosition]].
5412
5413{{window-position}} returns multiple values.
5414
5415The setters accept a list of integers {{(x y)}}.
5416
5417
5418<procedure>(window-size window) → [width height]</procedure>
5419<setter>(set! (window-size window) size)</setter>
5420<setter>(window-size-set! window size)</setter>
5421
5422See [[https://wiki.libsdl.org/SDL_GetWindowSize|SDL_GetWindowSize]]
5423and [[https://wiki.libsdl.org/SDL_SetWindowSize|SDL_SetWindowSize]].
5424
5425{{window-size}} returns multiple values.
5426
5427The setters accept a list of integers {{(width height)}}.
5428
5429
5430<procedure>(window-surface window) → sdl2:surface</procedure>
5431
5432See [[https://wiki.libsdl.org/SDL_GetWindowSurface|SDL_GetWindowSurface]].
5433
5434Signals an exception of kind {{(exn sdl2)}} if an error occurs.
5435
5436
5437<procedure>(window-title window) → string</procedure>
5438<setter>(set! (window-title window) title)</setter>
5439<setter>(window-title-set! window title)</setter>
5440
5441See [[https://wiki.libsdl.org/SDL_GetWindowTitle|SDL_GetWindowTitle]]
5442and [[https://wiki.libsdl.org/SDL_SetWindowTitle|SDL_SetWindowTitle]].
5443
5444
5445
5446==== sdl2:display-mode
5447
5448sdl2:display-mode is a record type that wraps a pointer to an
5449[[https://wiki.libsdl.org/SDL_DisplayMode|SDL_DisplayMode]] struct.
5450
5451
5452<procedure>(display-mode? obj) → boolean</procedure>
5453
5454Returns #t if {{obj}} is an sdl2:display-mode.
5455
5456
5457<procedure>(make-display-mode #!optional format w h refresh-rate) → sdl2:display-mode</procedure>
5458<procedure>(make-display-mode* #!optional format w h refresh-rate) → sdl2:display-mode</procedure>
5459
5460Allocate and initialize a new sdl2:display-mode.
5461
5462{{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.
5463
5464{{w}}, {{h}}, and {{refresh-rate}} default to 0. They must be integers.
5465
5466* {{make-display-mode}} returns a managed sdl2:display-mode.
5467* {{make-display-mode*}} returns an unmanaged sdl2:display-mode, which must be freed with {{free-display-mode!}} when you are done with it.
5468
5469
5470<procedure>(free-display-mode! display-mode)</procedure>
5471
5472Free the memory of the sdl2:display-mode's underlying struct.
5473{{display-mode}}'s pointer will be set to null (see {{struct-null?}}).
5474It is safe to call this procedure with managed or unmanaged
5475sdl2:display-modes. It is safe (but has no effect) to free a struct
5476record multiple times.
5477
5478
5479<procedure>(display-mode-format display-mode) → symbol</procedure>
5480<procedure>(display-mode-format-raw display-mode) → integer</procedure>
5481<setter>(set! (display-mode-format display-mode) val)</setter>
5482<setter>(display-mode-format-set! display-mode val)</setter>
5483
5484Get or set the sdl2:display-mode's "format" field.
5485
5486* {{display-mode-format}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]].
5487* {{display-mode-format-raw}} returns an integer.
5488* The setters accept either a symbol or an integer.
5489
5490
5491<procedure>(display-mode-w display-mode) → integer</procedure>
5492<setter>(set! (display-mode-w display-mode) val)</setter>
5493<setter>(display-mode-w-set! display-mode val)</setter>
5494
5495Get or set the sdl2:display-mode's "w" field, as an integer.
5496
5497
5498<procedure>(display-mode-h display-mode) → integer</procedure>
5499<setter>(set! (display-mode-h display-mode) val)</setter>
5500<setter>(display-mode-h-set! display-mode val)</setter>
5501
5502Get or set the sdl2:display-mode's "h" field, as an integer.
5503
5504
5505<procedure>(display-mode-refresh-rate display-mode) → integer</procedure>
5506<setter>(set! (display-mode-refresh-rate display-mode) val)</setter>
5507<setter>(display-mode-refresh-rate-set! display-mode val)</setter>
5508
5509Get or set the sdl2:display-mode's "refresh-rate" field, as an integer.
5510
5511
5512
5513=== Miscellaneous
5514
5515<procedure>(clear-error!)</procedure>
5516
5517See [[https://wiki.libsdl.org/SDL_ClearError|SDL_ClearError]].
5518
5519
5520<procedure>(get-error) → string</procedure>
5521
5522See [[https://wiki.libsdl.org/SDL_GetError|SDL_GetError]].
5523
5524
5525<procedure>(set-error! message)</procedure>
5526
5527See [[https://wiki.libsdl.org/SDL_SetError|SDL_SetError]].
5528
5529Unlike SDL_SetError, this procedure only accepts one argument, a
5530string. You can use {{sprintf}} to do string substitution if desired.
5531
5532
5533<procedure>(get-platform) → string</procedure>
5534
5535See [[https://wiki.libsdl.org/SDL_GetPlatform|SDL_GetPlatform]].
5536
5537
5538<procedure>(screen-saver-enabled?) → boolean</procedure>
5539<setter>(set! (screen-saver-enabled?) enabled?)</setter>
5540<setter>(screen-saver-enabled-set! enabled?)</setter>
5541
5542See [[https://wiki.libsdl.org/SDL_IsScreenSaverEnabled|SDL_IsScreenSaverEnabled]],
5543[[https://wiki.libsdl.org/SDL_EnableScreenSaver|SDL_EnableScreenSaver]],
5544and [[https://wiki.libsdl.org/SDL_DisableScreenSaver|SDL_DisableScreenSaver]].
5545
5546
5547<procedure>(has-clipboard-text?) → boolean</procedure>
5548
5549See [[https://wiki.libsdl.org/SDL_HasClipboardText|SDL_HasClipboardText]].
5550
5551
5552<procedure>(get-clipboard-text) → string</procedure>
5553
5554See [[https://wiki.libsdl.org/SDL_GetClipboardText|SDL_GetClipboardText]].
5555
5556Signals an exception of kind {{(exn sdl2)}} if an error occurs.
5557
5558
5559<procedure>(set-clipboard-text! text)</procedure>
5560
5561See [[https://wiki.libsdl.org/SDL_SetClipboardText|SDL_SetClipboardText]].
5562
5563Signals an exception of kind {{(exn sdl2)}} if an error occurs.
Note: See TracBrowser for help on using the repository browser.