This file contains an archive of the sdl2 egg wiki page. The most up-to-date version of these docs is available at: https://wiki.call-cc.org/eggref/5/sdl2 == sdl2 The sdl2 egg provides bindings to [[http://libsdl.org/|Simple DirectMedia Layer]] version 2 (SDL2). SDL is a popular library used in games and other media-rich software. The sdl2 egg provides a programmer-friendly, convenient, and CHICKEN-idiomatic interface to SDL2. It takes care of the annoying low-level C stuff for you, so you can focus on making your game. If a feature you need is not yet available, please [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/CONTRIBUTING.md#filing-feature-requests|file a feature request]] or contact a maintainer, so we can prioritize adding it. ; Project / Source Code Repository : [[https://gitlab.com/chicken-sdl2/chicken-sdl2]] ; Issue Tracker : [[https://gitlab.com/chicken-sdl2/chicken-sdl2/issues]] ; Maintainer : [[/users/john-croisant|John Croisant]] ; License: [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/LICENSE-BSD.txt|BSD 2-Clause]] '''Table of Contents''' [[toc:]] == Help Wanted! This egg needs volunteers to help with several things: * Adding bindings to more SDL features. * Manual testing (installing, running examples) on different platforms * Writing unit tests and semi-automated test programs * Writing API reference docs, guides, and tutorials * Creating detailed installation instructions for different platforms * Creating feature demos and example games/programs If you wish to help in any way, please contact the project maintainer. == Requirements The sdl2 egg requires [[http://libsdl.org/|Simple DirectMedia Layer]] version 2.0.0 or higher. It will not work with older versions of SDL. This egg requires CHICKEN Scheme 4.8 or higher. As of version 0.3.0, this egg is compatible with both CHICKEN 4 and CHICKEN 5. The unit tests depend on the [[/egg/test|test]] egg. Some demos and examples have other dependencies as well. == Related Libraries The [[/egg/sdl2-image|sdl2-image egg]] provides bindings to [[http://www.libsdl.org/projects/SDL_image/|SDL_image]] version 2, which provides the ability to load many image formats. It is built to be compatible with the sdl2 egg. The [[/egg/sdl2-ttf|sdl2-ttf egg]] provides bindings to [[https://www.libsdl.org/projects/SDL_ttf/|SDL_ttf]] version 2, which provides the ability to render text using TTF, OTF, and FON fonts. It is built to be compatible with the sdl2 egg. The [[/egg/sdl-base|sdl-base egg]] provides bindings to older versions of SDL. Its API is not compatible with the sdl2 egg. == Installation In most cases, you can install the sdl2 egg in the usual way: chicken-install sdl2 '''Note:''' it is normal for the sdl2 egg to take several minutes to install. The installer will try to automatically determine the SDL2 compiler and linker flags using the {{sdl2-config}} command. In special cases, you may need to set the {{SDL2_CFLAGS}} and {{SDL2_LDFLAGS}} environment variables to provide the compiler and linker flags (respectively), then try again. For example: export SDL2_CFLAGS="-I/usr/local/include/SDL2" export SDL2_LDFLAGS="-L/usr/local/lib -lSDL2" chicken-install sdl2 These environment variables are needed only when installing the egg itself. They are not needed when compiling or running programs that use the egg. === Installing on macOS On macOS, the sdl2 egg can be compiled using either UNIX-style libraries (e.g. SDL2 compiled from source or installed via Homebrew) or Mac-style frameworks (e.g. downloaded from the SDL website). When automatically determining compiler and linker flags on macOS, the installer will first check to see if {{sdl2-config}} is available. If it is available, the installer will use it to determine the flags. If {{sdl2-config}} is not available, the installer will check to see if {{SDL2.framework}} is available in either the {{/Library/Frameworks}} or {{/System/Library/Frameworks}} directories. If so, the installer will use the framework. If the framework is installed in some other directory, or if you want to force using the framework even when {{sdl2-config}} is available, set the {{SDL2_CFLAGS}} and {{SDL2_LDFLAGS}} enviroment variables to tell the compiler where to find the framework: export SDL2_CFLAGS="-F/path/to/your/frameworks" export SDL2_LDFLAGS="-F/path/to/your/frameworks -framework SDL2" chicken-install sdl2 == Usage and Examples It is recommended that you import the sdl2 module using the prefix "sdl2:", like so: ;; Compatible with both CHICKEN 4 and CHICKEN 5. (cond-expand (chicken-4 (use (prefix sdl2 "sdl2:"))) (chicken-5 (import (prefix sdl2 "sdl2:")))) (sdl2:set-main-ready!) (sdl2:init! '(video)) (define window (sdl2:create-window! "Hello, World!" 0 0 600 400)) (sdl2:fill-rect! (sdl2:window-surface window) #f (sdl2:make-color 0 128 255)) (sdl2:update-window-surface! window) (sdl2:delay! 3000) (sdl2:quit!) The [[https://gitlab.com/chicken-sdl2/chicken-sdl2/tree/master/demos|demos directory]] contains small programs demonstrating how to use various features of sdl2. E.g. to compile and run the basics demo: csc demos/basics.scm demos/basics The [[https://gitlab.com/chicken-sdl2/chicken-sdl2-examples|chicken-sdl2-examples repository]] contains complete example games and programs made with sdl2. === Ensuring Proper Clean Up You 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. This is especially important if your program enters fullscreen mode, or changes the display brightness or gamma ramp. If 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. It 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! Here is a simple way to ensure that {{quit!}} is called before your program ends, whether exitting normally or because an exception occurred: (cond-expand (chicken-4 (use (prefix sdl2 "sdl2:"))) (chicken-5 (import (prefix sdl2 "sdl2:")))) ;; Initialize SDL (sdl2:set-main-ready!) (sdl2:init! '(video)) ;; or whatever init flags your program needs ;; Schedule quit! to be automatically called when your program exits normally. (on-exit sdl2:quit!) ;; Install a custom exception handler that will call quit! and then ;; call the original exception handler. This ensures that quit! will ;; be called even if an unhandled exception reaches the top level. (current-exception-handler (let ((original-handler (current-exception-handler))) (lambda (exception) (sdl2:quit!) (original-handler exception)))) ;; ... ;; ... the rest of your program code ... ;; ... == Version History ; 0.4.0 (2021-10-15) cursor, display mode, game controller, mouse, and many other features. Added type declarations. Backward incompatible changes. ; 0.3.0 (2019-02-13) : Ported to be compatible with both CHICKEN 4 and CHICKEN 5. More user-friendly installation process. Bug fixes. ; 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. ; 0.1.1 (2015-12-22) : Fixed a compile error when compiling with GCC 4. ; 0.1.0 (2015-12-19) : Initial release. For more information about what changed in each version, see the [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/CHANGELOG.md|CHANGELOG]]. == API === About the API ==== API Stability The sdl2 egg follows [[http://semver.org/|semantic versioning]]. Until version 1.0.0 is released, the maintainer reserves the right to change the API if needed, possibly in ways that break compatibility with previous versions. '''Large backward incompatible changes are unlikely''', but there may be small tweaks and fixes to the API if problems are discovered. After version 1.0.0 is released, the API is guaranteed to remain stable (no backward-incompatible changes) until the next new major version (e.g. going from version 1.x to 2.0.0, or 2.x to 3.0.0). ==== Conventions * Procedures names, including function bindings, are Scheme style. ** All procedure names are lower case and hyphenated, with no "SDL_" prefix. ** Procedures that ask a "true or false" question (aka predicates) are suffixed with "?". Usually words such as "has" or "is" are removed from predicate names. ** Procedures that cause a mutation or side effect are suffixed with "!". ** Procedures that set the value of a field are named like {{TYPE-FIELD-set!}}, e.g. {{rect-x-set!}}. 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)}}. 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. * Many procedures signal an exception of kind {{(exn sdl2)}} if an error occurs or the operation fails. This is instead of returning an integer error code or null pointer. * Procedures return {{#f}} instead of a null struct record or null pointer, in non-error cases. * Some procedures return multiple values. For example, {{window-size}} returns two values, the width and height. You can use {{receive}}, {{let-values}}, etc. to capture all the return values. * Procedures that allocate a new struct often have two versions, one that returns a memory managed struct record and one that returns an unmanaged struct record, e.g. {{make-surface}} and {{make-surface*}}. See the [[#struct-memory-management|Struct Memory Management]] section for more information. * Some procedures have a "raw" version, which returns a "low level" type, such as an integer constant or memory pointer. 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. ** 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}}. ** Setters that accept an enum symbol will also accept the corresponding integer value. Setters that accept a list of enum symbols will also accept an integer representing {{bitwise-ior}}'d integer flags or masks. * Procedures with a name containing the word "color" have an alias spelled as "colour", for the convenience of anyone who spells it that way. Both names refer to exactly the same procedure. ==== Enums The sdl2 egg uses symbols instead of integer constants, for things like event types, keyboard keys, and init flags. It uses lists of symbols instead of {{bitwise-ior}}'d integer masks or flags. See the [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md|enum tables]] for details. Many procedures that return an enum symbol or a list of enum symbols, also have a "raw" version that returns the equivalent integer value. Setters that accept an enum symbol will also accept the corresponding integer value. Setters that accept a list of enum symbols will also accept an integer representing {{bitwise-ior}}'d integer flags or masks. ==== The sdl2-internals Module The 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. Most 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. The {{sdl2-internals}} module is not an official part of the public API, and does not have the same guarantees of API stability. But, certain parts of the module are safe to use in your programs. For more information, see this guide: * [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/using-sdl2-internals.md|Using sdl2-internals]] ==== Struct Memory Management The sdl2 egg has many "struct record types", which are Scheme record types that wrap a pointer to a certain C struct from SDL. For example, the sdl2:surface record type wraps a pointer to an SDL_Surface struct. Some struct record types have procedures for allocating or freeing an instance of that type. Each type that can be allocated has two "make" procedures: * The normal make procedure (e.g. {{make-event}}) returns a '''memory-managed''' struct record, whose underlying struct memory will be automatically freed when the record is garbage collected. * The make procedure with an asterisk (e.g. {{make-event*}}) returns an '''unmanaged''' struct record, which should be manually freed when you are done with it (e.g. using {{free-event!}}) to avoid memory leaks. Certain other procedures that return new struct records also follow this convention, for example {{load-bmp}} vs. {{load-bmp*}}. In most cases, it is best to create managed struct records, so that you don't have to worry about manually freeing them. However, in certain advanced use cases, you might require that the struct's underlying pointer address never change. For example, suppose you are storing the pointer address in another C struct. In such cases, you should create an unmanaged struct record, not a memory-managed struct record. Unmanaged struct records will keep the same underlying pointer address throughout their life, but managed struct records may sometimes be moved in memory by the garbage collector. (Most users do not need to worry about this.) If you create an unmanaged struct record but want to automatically free its memory when it is garbage collected, you can use [[/manual/Module (chicken gc)#set-finalizer|set-finalizer!]] with the appropriate "free" procedure. (This is how most, but not all, managed struct records are implemented.) For example: ;; Allocate an unmanaged sdl2:surface. (let ((my-surf (sdl2:make-surface* 800 600 30))) ;; Set a finalizer so it will be automatically freed. (set-finalizer! my-surf sdl2:free-surface!)) It is safe to manually free managed struct records. In fact, doing so can be beneficial to your program's memory footprint and performance, because there will be less memory waiting to be freed by the garbage collector. For example: (let ((my-surf (sdl2:make-surface 800 600 32))) ;; ... do stuff with my-surf ... ;; Once you are done with my-surf, manually free it. (sdl2:free-surface! my-surf)) As soon as you free a struct record, its pointer will be set to null, and it will no longer be usable for most purposes. You cannot get or set its fields, or pass it as an argument to most procedures. So be careful not to free struct records that you still want to use! Some struct record types, such as sdl2:window, are not managed in this way. Instead, you use certain SDL functions to work with them, such as {{create-window!}} and {{destroy-window!}}. === General Struct Management (struct-eq? obj1 obj2) → boolean Returns {{#t}} if both objects refer to the same memory location. The objects can be struct record instances, pointers, locatives, or the value {{#f}} (equivalent to a null pointer). This procedure can be used with any struct record type provided by this library, or related libraries such as [[/egg/sdl2-image|sdl2-image]] and [[/egg/sdl2-ttf|sdl2-ttf]]. This procedure is the only reliable way to compare the identities of struct records provided by this library or related libraries. Other procedures, such as {{eq?}} or {{equal?}}, are not guaranteed to work correctly. They may break in the future due to changes in the implementation of struct records. (struct-null? record) → boolean Returns {{#t}} if the given record is a null struct record, i.e. it has a pointer to memory address 0. This procedure can be used with any struct record type provided by this library, or related libraries such as [[/egg/sdl2-image|sdl2-image]] and [[/egg/sdl2-ttf|sdl2-ttf]]. A struct record will be null after you manually free its memory, e.g. using {{free-surface!}}. Most procedures, including field getters and setters, will signal an exception if you pass a null struct record. So, you can use this procedure to check whether it is safe to use the record. It is possible for a C function to return a null struct record. But, if a function binding in this library returns a null struct record, that is a bug and should be reported. Function bindings in this library are supposed to return {{#f}} instead of a null struct record. === Initialization and Clean Up (set-main-ready!) See [[https://wiki.libsdl.org/SDL_SetMainReady|SDL_SetMainReady]]. You should call this soon after your program starts, '''before''' calling {{init!}}. See [[/egg/sdl2#ensuring-proper-clean-up|Ensuring Proper Clean Up]]. (init! #!optional flags-list) Initialize SDL. You should call this soon after your program starts, '''after''' calling {{set-main-ready!}}. See [[/egg/sdl2#ensuring-proper-clean-up|Ensuring Proper Clean Up]]. {{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]]. See [[https://wiki.libsdl.org/SDL_Init|SDL_Init]]. Signals an exception of kind {{(exn sdl2)}} if initialization fails. (init-subsystem! flags-list) See [[https://wiki.libsdl.org/SDL_InitSubSystem|SDL_InitSubSystem]]. {{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. Signals an exception of kind {{(exn sdl2)}} if initialization fails. (quit!) Clean up SDL. You must make sure to call this before your program ends. See [[/egg/sdl2#ensuring-proper-clean-up|Ensuring Proper Clean Up]]. See [[https://wiki.libsdl.org/SDL_Quit|SDL_Quit]]. (quit-subsystem! flags-list) See [[https://wiki.libsdl.org/SDL_QuitSubSystem|SDL_QuitSubSystem]]. {{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. (was-init #!optional flags-list) → list of symbols See [[https://wiki.libsdl.org/SDL_WasInit|SDL_WasInit]]. {{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. === Color ==== sdl2:color sdl2:color is a record type that wraps a pointer to an [[https://wiki.libsdl.org/SDL_Color|SDL_Color]] struct. (color? obj) → boolean (colour? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:color. (make-color #!optional r g b a) → sdl2:color (make-colour #!optional r g b a) → sdl2:color (make-color* #!optional r g b a) → sdl2:color (make-colour* #!optional r g b a) → sdl2:color Allocate and initialize a new sdl2:color. {{r}}, {{g}}, {{b}}, and {{a}} must be integers in the range 0 to 255 (inclusive). {{r}}, {{g}}, and {{b}} default to 0. {{a}} defaults to 255 (full opacity). * {{make-color}} and {{make-colour}} return a memory-managed sdl2:color. * {{make-color*}} and {{make-colour*}} return an unmanaged sdl2:color, which should be freed using {{free-color!}} when you are done with it. (free-color! color) (free-colour! color) Free the memory of the sdl2:color's underlying struct. {{color}}'s pointer will be set to null (see {{struct-null?}}). It is safe to call this procedure with managed or unmanaged sdl2:colors. It is safe (but has no effect) to free a struct record multiple times. (color-r color) → integer (colour-r color) → integer (set! (color-r color) val) (set! (colour-r color) val) (color-r-set! color val) (colour-r-set! color val) Get or set the sdl2:color's "r" (red) field, as an integer in the range 0 to 255 (inclusive). (color-g color) → integer (colour-g color) → integer (set! (color-g color) val) (set! (colour-g color) val) (color-g-set! color val) (colour-g-set! color val) Get or set the sdl2:color's "g" (green) field, as an integer in the range 0 to 255 (inclusive). (color-b color) → integer (colour-b color) → integer (set! (color-b color) val) (set! (colour-b color) val) (color-b-set! color val) (colour-b-set! color val) Get or set the sdl2:color's "b" (blue) field, as an integer in the range 0 to 255 (inclusive). (color-a color) → integer (colour-a color) → integer (set! (color-a color) val) (set! (colour-a color) val) (color-a-set! color val) (colour-a-set! color val) Get or set the sdl2:color's "a" (alpha) field, as an integer in the range 0 to 255 (inclusive). ==== sdl2:color Operations These are operations for efficiently and conveniently working with sdl2:colors. Many of them are implemented in C for efficiency. (color-set! color #!optional r g b a) → color (colour-set! color #!optional r g b a) → color Efficient and convenient way of setting multiple fields of the sdl2:color. Any arguments that are {{#f}} will cause no change to that field. E.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. Returns {{color}} after it is modified. (color->list color) → list of integers (colour->list color) → list of integers Returns a list {{(r g b a)}} containing the value of each field of the sdl2:color. (color->values color) → [r g b a] (colour->values color) → [r g b a] Returns multiple values containing the value of each field of the sdl2:color. This is useful for destructuring an sdl2:color using {{receive}} or {{let-values}}. (color=? color1 color2) → boolean (colour=? color1 color2) → boolean Efficiently compare two sdl2:colors. Returns {{#t}} if the value of every field in {{color1}} is equal to the value of the corresponding field in {{color2}}. (color-copy src) → sdl2:color (colour-copy src) → sdl2:color (color-copy! src dest) → dest (colour-copy! src dest) → dest {{color-copy}} and {{colour-copy}} efficiently copy the values of {{src}} into a new managed sdl2:color. {{color-copy}} and {{colour-copy}} are available in sdl2 egg 0.2.0 and higher. In earlier versions, they were named {{copy-color}} and {{copy-colour}}. {{color-copy!}} and {{colour-copy!}} efficiently copy the values of {{src}} into {{dest}}, and return the modified {{dest}}. It is safe (but useless) for {{src}} and {{dest}} to be the same object. {{color-copy!}} and {{colour-copy!}} are available in sdl2 egg 0.2.0 and higher. (color-scale color factor) → sdl2:color (colour-scale color factor) → sdl2:color (color-scale! color factor #!optional dest) → dest (colour-scale! color factor #!optional dest) → dest Efficiently multiply the RGBA values of {{color}} by {{factor}} (a float or integer). E.g. {{factor}} 0.5 halves the RGBA values, {{factor}} 2.0 doubles the values. * {{color-scale}} and {{colour-scale}} return a new managed sdl2:color. * {{color-scale!}} and {{colour-scale!}} modify and return {{dest}}. If {{dest}} is omitted, {{color}} is modified and returned. Requires sdl2 egg 0.2.0 or higher. The results are clamped to the range [0, 255]. sdl2:color can only hold integer values, so the results will be truncated to integers. (color-mult color1 color2) → sdl2:color (colour-mult color1 color2) → sdl2:color (color-mult! color1 color2 #!optional dest) → dest (colour-mult! color1 color2 #!optional dest) → dest Efficiently multiply-blend {{color1}} with {{color2}}. This is equivalent to the "multiply" blend mode of image editors, where {{color1}} is the bottom layer and {{color2}} is the top layer. * {{color-mult}} and {{colour-mult}} return a new managed sdl2:color. * {{color-mult!}} and {{colour-mult!}} modify and return {{dest}}. If {{dest}} is omitted, {{color1}} is modified and returned. Requires sdl2 egg 0.2.0 or higher. The results are clamped to the range [0, 255]. sdl2:color can only hold integer values, so the results will be truncated to integers. This operation only affects the R, G, and B values. The result's A value will always be the same as {{color1}}'s A value. {{color2}}'s A value controls the strength of the effect. E.g. 255 means full strength, 127 means half strength, 0 means no effect (the result will have the same values as {{color1}}). (color-add color1 color2) → sdl2:color (colour-add color1 color2) → sdl2:color (color-add! color1 color2 #!optional dest) → dest (colour-add! color1 color2 #!optional dest) → dest Efficiently add-blend {{color1}} with {{color2}}. This is equivalent to the "addition" blend mode of image editors, where {{color1}} is the bottom layer and {{color2}} is the top layer. * {{color-add}} and {{colour-add}} return a new managed sdl2:color. * {{color-add!}} and {{colour-add!}} modify and return {{dest}}. If {{dest}} is omitted, {{color1}} is modified and returned. Requires sdl2 egg 0.2.0 or higher. The results are clamped to the range [0, 255]. sdl2:color can only hold integer values, so the results will be truncated to integers. This operation only affects the R, G, and B values. The result's A value will always be the same as {{color1}}'s A value. {{color2}}'s A value controls the strength of the effect. E.g. 255 means full strength, 127 means half strength, 0 means no effect (the result will have the same values as {{color1}}). (color-sub! color1 color2 #!optional dest) → dest (colour-sub! color1 color2 #!optional dest) → dest Efficiently subtract-blend {{color1}} with {{color2}}. This is equivalent to the "subtract" blend mode of image editors, where {{color1}} is the bottom layer and {{color2}} is the top layer. * {{color-sub}} and {{colour-sub}} return a new managed sdl2:color. * {{color-sub!}} and {{colour-sub!}} modify and return {{dest}}. If {{dest}} is omitted, {{color1}} is modified and returned. Requires sdl2 egg 0.2.0 or higher. The results are clamped to the range [0, 255]. sdl2:color can only hold integer values, so the results will be truncated to integers. This operation only affects the R, G, and B values. The result's A value will always be the same as {{color1}}'s A value. {{color2}}'s A value controls the strength of the effect. E.g. 255 means full strength, 127 means half strength, 0 means no effect (the result will have the same values as {{color1}}). (color-lerp color1 color2 t) → sdl2:color (color-lerp! color1 color2 t #!optional dest) → dest (colour-lerp color1 color2 t) → sdl2:color (colour-lerp! color1 color2 t #!optional dest) → dest Efficient linear interpolation (or extrapolation) between {{color1}} and {{color2}}. sdl2:color can only hold integer values, so the results will be truncated to integers. The results will be clamped to the range 0 to 255. {{t}} is the interpolation factor (a float). Values of {{t}} between 0 and 1 will interpolate between {{color1}} and {{color2}}. Values of {{t}} less that 0 will extrapolate beyond {{color1}} (moving away from {{color2}}). Values greater that 1 will extrapolate beyond {{color2}} (moving away from {{color1}}). * {{color-lerp}} and {{colour-lerp}} return a new managed sdl2:color. * {{color-lerp!}} and {{colour-lerp!}} modify and return {{dest}}. If {{dest}} is omitted, {{color1}} is modified and returned. Requires sdl2 egg 0.2.0 or higher. === Cursor ==== Cursor Functions (create-cursor data mask w h hot-x hot-y) → sdl2:cursor (create-cursor* data mask w h hot-x hot-y) → sdl2:cursor Create a cursor from pixel and mask data. {{data}} and {{mask}} must be u8vectors, blobs, locatives, or pointers. See [[https://wiki.libsdl.org/SDL_CreateCursor|SDL_CreateCursor]]. * {{create-cursor}} returns a memory-managed sdl2:cursor. * {{create-cursor*}} returns an unmanaged sdl2:cursor, which should be freed with {{free-cursor!}} when you are done with it. Requires sdl2 egg 0.4.0 or higher. (create-color-cursor surface hot-x hot-y) → sdl2:cursor (create-color-cursor* surface hot-x hot-y) → sdl2:cursor (create-colour-cursor surface hot-x hot-y) → sdl2:cursor (create-colour-cursor* surface hot-x hot-y) → sdl2:cursor See [[https://wiki.libsdl.org/SDL_CreateColorCursor|SDL_CreateColorCursor]]. * {{create-color-cursor}} and {{create-colour-cursor}} return a memory-managed sdl2:cursor. * {{create-color-cursor*}} and {{create-colour-cursor*}} return an unmanaged sdl2:cursor, which should be freed with {{free-cursor!}} when you are done with it. Requires sdl2 egg 0.4.0 or higher. (create-system-cursor enum) → sdl2:cursor (create-system-cursor* enum) → sdl2:cursor {{enum}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#system-cursors|system cursor symbol]] or equivalent integer. See [[https://wiki.libsdl.org/SDL_CreateSystemCursor|SDL_CreateSystemCursor]]. * {{create-system-cursor}} returns a memory-managed sdl2:cursor. * {{create-system-cursor*}} returns an unmanaged sdl2:cursor, which should be freed with {{free-cursor!}} when you are done with it. Requires sdl2 egg 0.4.0 or higher. (get-cursor) → sdl2:cursor (set! (get-cursor) cursor) (cursor-set! cursor) Get or set the active cursor. You should not call {{free-cursor!}} on the cursor returned by {{get-cursor}}. See [[https://wiki.libsdl.org/SDL_GetCursor|SDL_GetCursor]] and [[https://wiki.libsdl.org/SDL_SetCursor|SDL_SetCursor]]. Requires sdl2 egg 0.4.0 or higher. (get-default-cursor) → sdl2:cursor Get the default cursor. See [[https://wiki.libsdl.org/SDL_GetDefaultCursor|SDL_GetDefaultCursor]]. Requires sdl2 egg 0.4.0 or higher. (show-cursor?) → boolean (show-cursor! boolean) (set! (show-cursor?) boolean) See [[https://wiki.libsdl.org/SDL_ShowCursor|SDL_ShowCursor]]. Requires sdl2 egg 0.4.0 or higher. ==== sdl2:cursor (cursor? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:cursor. Requires sdl2 egg 0.4.0 or higher. (free-cursor! cursor) Free the memory of the sdl2:cursor's underlying struct. {{cursor}}'s pointer will be set to null (see {{struct-null?}}). It is safe to call this procedure with managed or unmanaged sdl2:cursors. It is safe (but has no effect) to free a struct record multiple times. Requires sdl2 egg 0.4.0 or higher. === Display / Video Driver ==== Display / Video Driver functions (video-init! #!optional driver-name) Initialize video with the given driver. {{driver-name}} can be omitted or {{#f}} to use the default driver. See [[https://wiki.libsdl.org/SDL_VideoInit|SDL_VideoInit]]. Requires sdl2 egg 0.4.0 or higher. (video-quit!) See [[https://wiki.libsdl.org/SDL_VideoQuit|SDL_VideoQuit]]. Requires sdl2 egg 0.4.0 or higher. (get-num-video-drivers) → integer See [[https://wiki.libsdl.org/SDL_GetNumVideoDrivers|SDL_GetNumVideoDrivers]]. Requires sdl2 egg 0.4.0 or higher. (get-video-driver driver-index) → string or #f See [[https://wiki.libsdl.org/SDL_GetVideoDriver|SDL_GetVideoDriver]]. Requires sdl2 egg 0.4.0 or higher. (get-current-video-driver) → string or #f See [[https://wiki.libsdl.org/SDL_GetCurrentVideoDriver|SDL_GetCurrentVideoDriver]]. Requires sdl2 egg 0.4.0 or higher. (get-num-video-displays) → integer See [[https://wiki.libsdl.org/SDL_GetNumVideoDisplays|SDL_GetNumVideoDisplays]]. Requires sdl2 egg 0.4.0 or higher. (get-display-name display-index) → string See [[https://wiki.libsdl.org/SDL_GetDisplayName|SDL_GetDisplayName]]. Requires sdl2 egg 0.4.0 or higher. (get-display-dpi display-index) → [ddpi hdpi vdpi] Return the diagonal, horizontal, and vertical DPI (dots per inch) of the specified display. This procedure returns multiple values. See [[https://wiki.libsdl.org/SDL_GetDisplayDPI|SDL_GetDisplayDPI]]. Requires SDL 2.0.4 or higher, and sdl2 egg 0.4.0 or higher. (get-display-bounds display-index) → [w h] See [[https://wiki.libsdl.org/SDL_GetDisplayBounds|SDL_GetDisplayBounds]]. Requires sdl2 egg 0.4.0 or higher. (get-display-usable-bounds display-index) → [w h] See [[https://wiki.libsdl.org/SDL_GetDisplayUsableBounds|SDL_GetDisplayUsableBounds]]. Requires SDL 2.0.5 or higher, and sdl2 egg 0.4.0 or higher. (get-display-orientation display-index) → symbol (get-display-orientation-raw display-index) → integer See [[https://wiki.libsdl.org/SDL_GetDisplayOrientation|SDL_GetDisplayOrientation]]. * {{get-display-orientation}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#display-orientations|display orientation symbol]]. * {{get-display-orientation-raw}} returns an integer. Requires SDL 2.0.9 or higher, and sdl2 egg 0.4.0 or higher. (get-num-display-modes display-index) → integer See [[https://wiki.libsdl.org/SDL_GetNumDisplayModes|SDL_GetNumDisplayModes]]. Requires sdl2 egg 0.4.0 or higher. (get-display-mode display-index i) → sdl2:display-mode See [[https://wiki.libsdl.org/SDL_GetDisplayMode|SDL_GetDisplayMode]]. Requires sdl2 egg 0.4.0 or higher. (get-current-display-mode display-index) → sdl2:display-mode See [[https://wiki.libsdl.org/SDL_GetCurrentDisplayMode|SDL_GetCurrentDisplayMode]]. Requires sdl2 egg 0.4.0 or higher. (get-closest-display-mode display-index target-mode) → sdl2:display-mode See [[https://wiki.libsdl.org/SDL_GetClosestDisplayMode|SDL_GetClosestDisplayMode]]. Requires sdl2 egg 0.4.0 or higher. (get-desktop-display-mode display-index) → sdl2:display-mode See [[https://wiki.libsdl.org/SDL_GetDesktopDisplayMode|SDL_GetDesktopDisplayMode]]. Requires sdl2 egg 0.4.0 or higher. ==== sdl2:display-mode sdl2:display-mode is a record type that wraps a pointer to an [[https://wiki.libsdl.org/SDL_DisplayMode|SDL_DisplayMode]] struct. (display-mode? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:display-mode. (make-display-mode #!optional format w h refresh-rate) → sdl2:display-mode (make-display-mode* #!optional format w h refresh-rate) → sdl2:display-mode Allocate and initialize a new sdl2:display-mode. {{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. {{w}}, {{h}}, and {{refresh-rate}} default to 0. They must be integers. * {{make-display-mode}} returns a memory-managed sdl2:display-mode. * {{make-display-mode*}} returns an unmanaged sdl2:display-mode, which should be freed with {{free-display-mode!}} when you are done with it. (free-display-mode! display-mode) Free the memory of the sdl2:display-mode's underlying struct. {{display-mode}}'s pointer will be set to null (see {{struct-null?}}). It is safe to call this procedure with managed or unmanaged sdl2:display-modes. It is safe (but has no effect) to free a struct record multiple times. (display-mode-format display-mode) → symbol (display-mode-format-raw display-mode) → integer (set! (display-mode-format display-mode) val) (display-mode-format-set! display-mode val) Get or set the sdl2:display-mode's "format" field. * {{display-mode-format}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]]. * {{display-mode-format-raw}} returns an integer. * The setters accept either a symbol or an integer. (display-mode-w display-mode) → integer (set! (display-mode-w display-mode) val) (display-mode-w-set! display-mode val) Get or set the sdl2:display-mode's "w" field, as an integer. (display-mode-h display-mode) → integer (set! (display-mode-h display-mode) val) (display-mode-h-set! display-mode val) Get or set the sdl2:display-mode's "h" field, as an integer. (display-mode-refresh-rate display-mode) → integer (set! (display-mode-refresh-rate display-mode) val) (display-mode-refresh-rate-set! display-mode val) Get or set the sdl2:display-mode's "refresh-rate" field, as an integer. === Event ==== Event Functions (event-state type) → boolean (set! (event-state type) state) (event-state-set! type state) → boolean Get or set the state of the given event type. {{#t}} means the event type is enabled, so events of that type may appear on the event queue. {{#f}} means the event type is disabled, so events of that type will be automatically discarded. It is beneficial to your program's performance to disable event types that your program does not need. See [[https://wiki.libsdl.org/SDL_EventState|SDL_EventState]]. {{type}} must be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbol]] or corresponding integer. If you set an event type's state to {{#f}}, any events of that type already on the event queue will be immediately discarded. {{event-state-set!}} returns the previous state of the given event type. (flush-event! type) (flush-events! #!optional min-type max-type) Remove all events on the event queue that match the given type or range of types. See [[https://wiki.libsdl.org/SDL_FlushEvent|SDL_FlushEvent]] and [[https://wiki.libsdl.org/SDL_FlushEvents|SDL_FlushEvents]]. For {{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. For {{flush-events!}}, {{min-type}} and {{max-type}} specify the range of event types to remove. Events with a type outside of this range will not be removed. {{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. {{min-type}} defaults to {{'first}} and {{max-type}} defaults to {{'last}}, which means all event types match by default. (has-event? type) → boolean (has-events? #!optional min-type max-type) → boolean Returns {{#t}} if the event queue currently has at least one event matching the given type or range of types. See [[https://wiki.libsdl.org/SDL_HasEvent|SDL_HasEvent]] and [[https://wiki.libsdl.org/SDL_HasEvents|SDL_HasEvents]]. For {{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. For {{has-events?}}, {{min-type}} and {{max-type}} specify the range of event types to consider. Events with a type outside of this range will not be considered. {{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. {{min-type}} defaults to {{'first}} and {{max-type}} defaults to {{'last}}, which means all event types match by default. (quit-requested?) → boolean Returns {{#t}} if the event queue currently has at least one event of type {{'quit}}. See [[https://wiki.libsdl.org/SDL_QuitRequested|SDL_QuitRequested]]. (get-events! num #!optional min-type max-type) → list of sdl2:events (peek-events num #!optional min-type max-type) → list of sdl2:events Get multiple matching events from the front of the event queue. Returns a list of managed sdl2:events. See [[https://wiki.libsdl.org/SDL_PeepEvents|SDL_PeepEvents]]. * {{get-events!}} removes the returned events from the event queue. * {{peek-events}} does not remove the returned events from the event queue. {{num}} specifies the maximum number of events to return. May return fewer events if there are not enough matching events on the event queue. {{min-type}} and {{max-type}} specify the range of event types to return. Events with a type outside of this range will not be returned (they will remain on the queue). {{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. {{min-type}} defaults to {{'first}} and {{max-type}} defaults to {{'last}}, which means all event types match by default. Both procedures signal an exception of kind {{(exn sdl2)}} if an error occurs. (poll-event! #!optional result-event) → sdl2:event Get the next event from the event queue. The returned event is removed from the event queue. See [[https://wiki.libsdl.org/SDL_PollEvent|SDL_PollEvent]]. If {{result-event}} is omitted or {{#f}}, a new managed sdl2:event will be returned. If {{result-event}} is an sdl2:event, it will be modified and returned. This allows you to allocate a single event and reuse it many times in your event loop, so that your program does not create as much garbage for the garbage collector. (pump-events!) See [[https://wiki.libsdl.org/SDL_PumpEvents|SDL_PumpEvents]]. (push-event! event) → boolean See [[https://wiki.libsdl.org/SDL_PushEvent|SDL_PushEvent]]. Returns {{#t}} if the event was pushed onto the event queue, or {{#f}} if the event was discarded, e.g. because the event type is disabled (see {{event-state}}). Signals an exception of kind {{(exn sdl2)}} if an error occurs. (wait-event! #!optional result-event delay-fn) → sdl2:event (wait-event-timeout! timeout #!optional result-event delay-fn) → sdl2:event or #f Wait for the next event to appear on the event queue, then return it. The returned event will be removed from the event queue. If there is already an event on the event queue, it will be returned immediately. Otherwise, these procedures will block the current thread until the next event appears (or the timeout expires). * {{wait-event!}} will wait indefinitely for an event to appear. * {{wait-event-timeout!}} will stop waiting and return {{#f}} if no event appears within {{timeout}} milliseconds. (It may actually wait a few milliseconds longer than specified. You should not rely on its timing being very precise.) If {{result-event}} is omitted or {{#f}}, a new managed sdl2:event will be returned. If {{result-event}} is an sdl2:event, it will be modified and returned. This allows you to allocate a single event and reuse it many times in your event loop, so that your program does not create as much garbage for the garbage collector. {{delay-fn}} must be a procedure which accepts a number of milliseconds to sleep. By default it is the {{delay!}} procedure from this egg. If you are using [[/egg/srfi-18|SRFI-18]] multithreading, you should provide a compatible delay procedure instead: (import srfi-18) (define (thread-delay! ms) (thread-sleep! (* ms 0.001))) (sdl2:wait-event! (sdl2:make-event) thread-delay!) These procedures are inspired by (but do not actually use) [[https://wiki.libsdl.org/SDL_WaitEvent|SDL_WaitEvent]] and [[https://wiki.libsdl.org/SDL_WaitEventTimeout|SDL_WaitEventTimeout]]. (register-events! event-symbols) → list of pairs Register zero or more symbols as new user event types. After registration, the given symbols may be used as event types, e.g. with {{event-type-set!}}. The symbols will be associated with the sdl2:user-event variant of sdl2:event. {{event-symbols}} must be a list of symbols that are not already being used as event types. If any symbol is already being used, or if any member of the list is not a symbol, an error will be signalled and none of the new event types will be registered. There are 32767 user event type numbers available to register. Each symbol in {{event-symbols}} will be assigned a sequential number. If there are not enough remaining numbers to register all the symbols in {{event-symbols}}, this procedure will signal an exception of kind {{(exn sdl2)}}, and none of the new event types will be registered. This 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. This procedure is based on [[https://wiki.libsdl.org/SDL_RegisterEvents|SDL_RegisterEvents]]. ==== sdl2:event sdl2:event is a record type that wraps a pointer to an [[https://wiki.libsdl.org/SDL_Event|SDL_Event]]. There are many specific event structs in SDL, and the sdl2:event type wraps them all. Each event struct has a corresponding variant of sdl2:event, described below. Each variant has one or more associated [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbols]].
Variant of sdl2:event Underlying struct Event type symbol(s)
[[#sdl2controller-axis-event|sdl2:controller-axis-event]] [[https://wiki.libsdl.org/SDL_ControllerAxisEvent|SDL_ControllerAxisEvent]] {{'controller-axis-motion}}
[[#sdl2controller-button-event|sdl2:controller-button-event]] [[https://wiki.libsdl.org/SDL_ControllerButtonEvent|SDL_ControllerButtonEvent]] {{'controller-button-down}}
{{'controller-button-up}}
[[#sdl2controller-device-event|sdl2:controller-device-event]] [[https://wiki.libsdl.org/SDL_ControllerDeviceEvent|SDL_ControllerDeviceEvent]] {{'controller-device-added}}
{{'controller-device-removed}}
{{'controller-device-remapped}}
[[#sdl2display-event|sdl2:display-event]] [[https://wiki.libsdl.org/SDL_DisplayEvent|SDL_DisplayEvent]] {{'display}}
[[#sdl2dollar-gesture-event|sdl2:dollar-gesture-event]] [[https://wiki.libsdl.org/SDL_DollarGestureEvent|SDL_DollarGestureEvent]] {{'dollar-gesture}}
{{'dollar-record}}
[[#sdl2drop-event|sdl2:drop-event]] [[https://wiki.libsdl.org/SDL_DropEvent|SDL_DropEvent]] {{'drop-file}}
[[#sdl2joy-axis-event|sdl2:joy-axis-event]] [[https://wiki.libsdl.org/SDL_JoyAxisEvent|SDL_JoyAxisEvent]] {{'joy-axis-motion}}
[[#sdl2joy-ball-event|sdl2:joy-ball-event]] [[https://wiki.libsdl.org/SDL_JoyBallEvent|SDL_JoyBallEvent]] {{'joy-ball-motion}}
[[#sdl2joy-button-event|sdl2:joy-button-event]] [[https://wiki.libsdl.org/SDL_JoyButtonEvent|SDL_JoyButtonEvent]] {{'joy-button-down}}
{{'joy-button-up}}
[[#sdl2joy-device-event|sdl2:joy-device-event]] [[https://wiki.libsdl.org/SDL_JoyDeviceEvent|SDL_JoyDeviceEvent]] {{'joy-device-added}}
{{'joy-device-removed}}
[[#sdl2joy-hat-event|sdl2:joy-hat-event]] [[https://wiki.libsdl.org/SDL_JoyHatEvent|SDL_JoyHatEvent]] {{'joy-hat-motion}}
[[#sdl2keyboard-event|sdl2:keyboard-event]] [[https://wiki.libsdl.org/SDL_KeyboardEvent|SDL_KeyboardEvent]] {{'key-down}}
{{'key-up}}
[[#sdl2mouse-button-event|sdl2:mouse-button-event]] [[https://wiki.libsdl.org/SDL_MouseButtonEvent|SDL_MouseButtonEvent]] {{'mouse-button-down}}
{{'mouse-button-up}}
[[#sdl2mouse-motion-event|sdl2:mouse-motion-event]] [[https://wiki.libsdl.org/SDL_MouseMotionEvent|SDL_MouseMotionEvent]] {{'mouse-motion}}
[[#sdl2mouse-wheel-event|sdl2:mouse-wheel-event]] [[https://wiki.libsdl.org/SDL_MouseWheelEvent|SDL_MouseWheelEvent]] {{'mouse-wheel}}
[[#sdl2multi-gesture-event|sdl2:multi-gesture-event]] [[https://wiki.libsdl.org/SDL_MultiGestureEvent|SDL_MultiGestureEvent]] {{'multi-gesture}}
[[#sdl2quit-event|sdl2:quit-event]] [[https://wiki.libsdl.org/SDL_QuitEvent|SDL_QuitEvent]] {{'quit}}
[[#sdl2sys-wm-event|sdl2:sys-wm-event]] [[https://wiki.libsdl.org/SDL_SysWMEvent|SDL_SysWMEvent]] {{'sys-wm}}
[[#sdl2text-editing-event|sdl2:text-editing-event]] [[https://wiki.libsdl.org/SDL_TextEditingEvent|SDL_TextEditingEvent]] {{'text-editing}}
[[#sdl2text-input-event|sdl2:text-input-event]] [[https://wiki.libsdl.org/SDL_TextInputEvent|SDL_TextInputEvent]] {{'text-input}}
[[#sdl2touch-finger-event|sdl2:touch-finger-event]] [[https://wiki.libsdl.org/SDL_TouchFingerEvent|SDL_TouchFingerEvent]] {{'finger-down}}
{{'finger-up}}
{{'finger-motion}}
[[#sdl2user-event|sdl2:user-event]] [[https://wiki.libsdl.org/SDL_UserEvent|SDL_UserEvent]] (Call {{register-events!}} to register your own user event type symbols.)
[[#sdl2window-event|sdl2:window-event]] [[https://wiki.libsdl.org/SDL_WindowEvent|SDL_WindowEvent]] {{'window}}
(event? obj) → boolean Returns {{#t}} if {{obj}} is any variant of sdl2:event. (make-event #!optional type) → sdl2:event (make-event* #!optional type) → sdl2:event Allocate and set the type of a new sdl2:event. {{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. * {{make-event}} returns a memory-managed sdl2:event. * {{make-event*}} returns an unmanaged sdl2:event, which should be freed with {{free-event!}} when you are done with it. (free-event! event) Free the memory of the sdl2:event's underlying struct. You can call this procedure with any variant of sdl2:event. {{event}}'s pointer will be set to null (see {{struct-null?}}). It is safe to call this procedure with managed or unmanaged sdl2:events. It is safe (but has no effect) to free a struct record multiple times. (event-type event) → symbol (event-type-raw event) → integer (set! (event-type event) val) (event-type-set! event val) Get or set the sdl2:event's "type" field. You can use these procedures with any variant of sdl2:event. Setting this will change what variant of sdl2:event it is. E.g. if you set it to {{'key-down}}, the event will become an sdl2:keyboard-event. * {{event-type}} returns an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbol]]. * {{event-type-raw}} returns an integer. * The setters accept either a symbol or an integer. (event-timestamp event) → integer (set! (event-timestamp event) val) (event-timestamp-set! event val) Get 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. You can use these procedures with any variant of sdl2:event. ==== sdl2:controller-axis-event sdl2:controller-axis-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_ControllerAxisEvent|SDL_ControllerAxisEvent]]. This event variant occurs when an axis on a controller moves. There may be more than one controller, and each controller may have more than one axis. You can distinguish them using the {{which}} and {{axis}} fields. sdl2:controller-axis-event has the following event type symbols: ; {{'controller-axis-motion}} : An axis on a controller moved. (controller-axis-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:controller-axis-event. (controller-axis-event-which event) → integer (set! (controller-axis-event-which event) val) (controller-axis-event-which-set! event val) Get or set the event's "which" field, as an integer indicating the device index of the controller (joystick) that the event is related to. (controller-axis-event-axis event) → symbol (controller-axis-event-axis-raw event) → integer (set! (controller-axis-event-axis event) val) (controller-axis-event-axis-set! event val) Get or set the event's "axis" field, as a symbol indicating the axis that the event is related to. * {{controller-axis-event-axis}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#game-controller-axes|game controller axis symbol]]. * {{controller-axis-event-axis-raw}} returns an integer. * The setters accept either a symbol or an integer. Before sdl2 egg 0.4.0, {{controller-axis-event-axis}} returned an integer. (controller-axis-event-value event) → integer (set! (controller-axis-event-value event) val) (controller-axis-event-value-set! event val) Get or set the event's "value" field, as an integer in the range -32768 to 32767 (inclusive), indicating the new value of the axis. ==== sdl2:controller-button-event sdl2:controller-button-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_ControllerButtonEvent|SDL_ControllerButtonEvent]]. This event variant occurs when a button on a controller is pressed or released. There may be more than one controller, and each controller may have more than one button. You can distinguish them using the {{which}} and {{button}} fields. sdl2:controller-button-event has the following event type symbols: ; {{'controller-button-down}} : A button on a controller was pressed. ; {{'controller-button-up}} : A button on a controller was released. (controller-button-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:controller-button-event. (controller-button-event-which event) → integer (set! (controller-button-event-which event) val) (controller-button-event-which-set! event val) Get or set the event's "which" field, as an integer indicating the device index of the controller (joystick) that the event is related to. (controller-button-event-button event) → symbol (controller-button-event-button-raw event) → integer (set! (controller-button-event-button event) val) (controller-button-event-button-set! event val) Get or set the event's "button" field, as a symbol indicating the button that the event is related to. * {{controller-button-event-button}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#game-controller-buttons|game controller button symbol]]. * {{controller-button-event-button-raw}} returns an integer. * The setters accept either a symbol or an integer. Before sdl2 egg 0.4.0, {{controller-button-event-button}} returned an integer. (controller-button-event-state event) → boolean (set! (controller-button-event-state event) val) (controller-button-event-state-set! event val) Get or set the event's "state" field, as a boolean indicating whether the button was pressed ({{#t}}) or released ({{#f}}). You can also find out by checking the event type: {{'controller-button-down}} for pressed, or {{'controller-button-up}} for released. ==== sdl2:controller-device-event sdl2:controller-device-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_ControllerDeviceEvent|SDL_ControllerDeviceEvent]]. This event variant occurs when a controller is added, removed, or remapped. There may be more than one controller. You can distinguish them using the {{which}}. sdl2:controller-device-event has the following event type symbols: ; {{'controller-device-added}} : A controller device was added. ; {{'controller-device-removed}} : A controller device was removed. ; {{'controller-device-remapped}} : A controller device was remapped. (controller-device-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:controller-device-event. (controller-device-event-which event) → integer (set! (controller-device-event-which event) val) (controller-device-event-which-set! event val) Get or set the event's "which" field, as an integer indicating the device index of the controller (joystick) that the event is related to. ==== sdl2:display-event sdl2:display-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_DisplayEvent|SDL_DisplayEvent]]. This event variant occurs when a display is connected, disconnected, or changes orientation. sdl2:display-event has the following event type symbols: ; {{'display}} : A display changed. (display-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:display-event. Requires SDL 2.0.9 or higher, and sdl2 egg 0.4.0 or higher. (display-event-display event) → integer (set! (display-event-display event) display-index) (display-event-display-set! event display-index) Get or set the event's "display" field, as an integer indicating the index of the display that changed. Requires SDL 2.0.9 or higher, and sdl2 egg 0.4.0 or higher. (display-event-event event) → symbol (display-event-event-raw event) → integer (set! (display-event-event event) enum) (display-event-event-set! event enum) Get or set the event's "display" field, as an integer indicating the index of the display that changed. Requires SDL 2.0.9 or higher, and sdl2 egg 0.4.0 or higher. (display-event-data1 event) → integer (set! (display-event-data1 event) data) (display-event-data1-set! event data) Get or set the event's "data1" field, as an integer of event-dependent data. If the event is a {{orientation}} kind of {{display-event}}, this field contains the new orientation as an integer enum. You can use {{display-event-orientation}} to access it as a symbol. Requires SDL 2.0.9 or higher, and sdl2 egg 0.4.0 or higher. (display-event-orientation event) → symbol (set! (display-event-orientation event) data) (display-event-orientation-set! event orientation) Wrapper for {{display-event-data1}} which returns a symbol. Signals an error if the event is not a {{orientation}} kind of {{display-event}}. Requires SDL 2.0.9 or higher, and sdl2 egg 0.4.0 or higher. ==== sdl2:dollar-gesture-event sdl2:dollar-gesture-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_DollarGestureEvent|SDL_DollarGestureEvent]]. This event variant occurs when a [[https://depts.washington.edu/acelab/proj/dollar/index.html|"$1 unistroke" gesture]] is performed or recorded. sdl2:dollar-gesture-event has the following event type symbols: ; {{'dollar-gesture}} : A dollar gesture was performed. ; {{'dollar-record}} : A dollar gesture was recorded. (dollar-gesture-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:dollar-gesture-event. (dollar-gesture-event-touch-id event) → integer (set! (dollar-gesture-event-touch-id event) val) (dollar-gesture-event-touch-id-set! event val) Get or set the event's "touch-id" field, as an integer indicating the ID number of the touch device this event is related to. (dollar-gesture-event-gesture-id event) → integer (set! (dollar-gesture-event-gesture-id event) val) (dollar-gesture-event-gesture-id-set! event val) Get or set the event's "gesture-id" field, as an integer indicating the ID number of the closest gesture to the performed stroke. (dollar-gesture-event-num-fingers event) → integer (set! (dollar-gesture-event-num-fingers event) val) (dollar-gesture-event-num-fingers-set! event val) Get or set the event's "num-fingers" field, as an integer indicating the number of fingers used to draw the stroke. (dollar-gesture-event-error event) → float (set! (dollar-gesture-event-error event) val) (dollar-gesture-event-error-set! event val) Get 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. (dollar-gesture-event-x event) → float (set! (dollar-gesture-event-x event) val) (dollar-gesture-event-x-set! event val) Get 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. (dollar-gesture-event-y event) → float (set! (dollar-gesture-event-y event) val) (dollar-gesture-event-y-set! event val) Get 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. ==== sdl2:drop-event sdl2:drop-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_DropEvent|SDL_DropEvent]]. This event variant occurs when the user requests that the program open a file, e.g. by dragging and dropping a file icon onto the program. With SDL 2.0.5 or higher, this event also occurs when the user drags and drops some text onto the program. sdl2:drop-event has the following event type symbols: ; {{'drop-file}} : The user dropped a file onto the program. ; {{'drop-text}} : The user dropped some text onto the program. Requires SDL 2.0.5 or higher, and sdl2 egg 0.4.0 or higher. ; {{'drop-begin}} : Occurs at the start of dropping one or more files or lines of text onto the program at the same time. Requires SDL 2.0.5 or higher, and sdl2 egg 0.4.0 or higher. ; {{'drop-complete}} : Occurs at the completion of dropping one or more files or lines of text onto the program at the same time. Requires SDL 2.0.5 or higher, and sdl2 egg 0.4.0 or higher. (drop-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:drop-event. (drop-event-file event) → string or #f (set! (drop-event-file event) val) (drop-event-file-set! event val) Get or set the event's "file" field, as a string whose meaning depends on the event type: * {{drop-file}}: the path to a file that the user requested to be opened * {{drop-text}}: the text that the user dragged and dropped * {{drop-begin}}: {{#f}} * {{drop-complete}}: {{#f}} (drop-event-window-id event) → integer (set! (drop-event-window-id event) i) (drop-event-window-id-set! event i) Get or set the event's "windowID" field, as an integer indicating the ID of the window that the file(s) or text was dropped onto. Requires SDL 2.0.5 or higher, and sdl2 egg 0.4.0 or higher. ==== sdl2:joy-axis-event sdl2:joy-axis-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_JoyAxisEvent|SDL_JoyAxisEvent]]. This event variant occurs when an axis on a joystick moves. There may be more than one joystick, and each joystick may have more than one axis. You can distinguish them using the {{which}} and {{axis}} fields. sdl2:joy-axis-event has the following event type symbols: ; {{'joy-axis-motion}} : An axis on a joystick moved. (joy-axis-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:joy-axis-event. (joy-axis-event-which event) → integer (set! (joy-axis-event-which event) val) (joy-axis-event-which-set! event val) Get or set the event's "which" field, as an integer indicating the device index of the joystick that the event is related to. (joy-axis-event-axis event) → integer (set! (joy-axis-event-axis event) val) (joy-axis-event-axis-set! event val) Get or set the event's "axis" field, as an integer indicating the axis that the event is related to. E.g. 0 indicates the first axis on the joystick. (joy-axis-event-value event) → integer (set! (joy-axis-event-value event) val) (joy-axis-event-value-set! event val) Get or set the event's "value" field, as an integer in the range -32768 to 32767 (inclusive), indicating the new value of the axis. ==== sdl2:joy-ball-event sdl2:joy-ball-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_JoyBallEvent|SDL_JoyBallEvent]]. This event variant occurs when a trackball on a joystick moves. There may be more than one joystick, and each joystick may have more than one trackball. You can distinguish them using the {{which}} and {{ball}} fields. sdl2:joy-ball-event has the following event type symbols: ; {{'joy-ball-motion}} : A trackball on a joystick moved. (joy-ball-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:joy-ball-event. (joy-ball-event-which event) → integer (set! (joy-ball-event-which event) val) (joy-ball-event-which-set! event val) Get or set the event's "which" field, as an integer indicating the device index of the joystick that the event is related to. (joy-ball-event-ball event) → integer (set! (joy-ball-event-ball event) val) (joy-ball-event-ball-set! event val) Get 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. (joy-ball-event-xrel event) → integer (set! (joy-ball-event-xrel event) val) (joy-ball-event-xrel-set! event val) Get 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. (joy-ball-event-yrel event) → integer (set! (joy-ball-event-yrel event) val) (joy-ball-event-yrel-set! event val) Get 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. ==== sdl2:joy-button-event sdl2:joy-button-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_JoyButtonEvent|SDL_JoyButtonEvent]]. This event variant occurs when a button on a joystick is pressed or released. There may be more than one joystick, and each joystick may have more than one button. You can distinguish them using the {{which}} and {{button}} fields. sdl2:joy-button-event has the following event type symbols: ; {{'joy-button-down}} : A button on a joystick was pressed. ; {{'joy-button-up}} : A button on a joystick was released. (joy-button-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:joy-button-event. (joy-button-event-which event) → integer (set! (joy-button-event-which event) val) (joy-button-event-which-set! event val) Get or set the event's "which" field, as an integer indicating the device index of the joystick that the event is related to. (joy-button-event-button event) → integer (set! (joy-button-event-button event) val) (joy-button-event-button-set! event val) Get or set the event's "button" field, as an integer indicating the button that the event is related to. E.g. 0 indicates the first button on the joystick. (joy-button-event-state event) → boolean (set! (joy-button-event-state event) val) (joy-button-event-state-set! event val) Get or set the value of the event's "state" field, as a boolean indicating whether the button was pressed ({{#t}}) or released ({{#f}}). You can also find out by checking the event type: {{'joy-button-down}} for pressed, or {{'joy-button-up}} for released. ==== sdl2:joy-device-event sdl2:joy-device-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_JoyDeviceEvent|SDL_JoyDeviceEvent]]. This event variant occurs when a joystick device is added or removed. There may be more than one joystick. You can distinguish them using the {{which}} field. sdl2:joy-device-event has the following event type symbols: ; {{'joy-device-added}} : A joystick device was added. ; {{'joy-device-removed}} : A joystick device was removed. (joy-device-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:joy-device-event. (joy-device-event-which event) → integer (set! (joy-device-event-which event) val) (joy-device-event-which-set! event val) Get or set the event's "which" field, as an integer indicating the device index of the joystick that the event is related to. ==== sdl2:joy-hat-event sdl2:joy-hat-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_JoyHatEvent|SDL_JoyHatEvent]]. This event variant occurs when an 8-directional hat switch on a joystick moves. There may be more than one joystick, and each joystick may have more than one hat switch. You can distinguish them using the {{which}} and {{hat}} fields. sdl2:joy-hat-event has the following event type symbols: ; {{'joy-hat-motion}} : A hat switch on a joystick moved. (joy-hat-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:joy-hat-event. (joy-hat-event-which event) → integer (set! (joy-hat-event-which event) val) (joy-hat-event-which-set! event val) Get or set the event's "which" field, as an integer indicating the device index of the joystick that the event is related to. (joy-hat-event-hat event) → integer (set! (joy-hat-event-hat event) val) (joy-hat-event-hat-set! event val) Get or set the event's "hat" field, as an integer indicating the hat switch that the event is related to. E.g. 0 indicates the first hat switch on the joystick. (joy-hat-event-value event) → symbol (joy-hat-event-value-raw event) → integer (set! (joy-hat-event-value event) val) (joy-hat-event-value-set! event val) Get or set the event's "value" field, indicating the new position of the hat switch. * {{joy-hat-event-value}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#joystick-hat-positions|joystick hat position symbol]]. * {{joy-hat-event-value-raw}} returns an integer. * The setters accept either a symbol or an integer. ==== sdl2:keyboard-event sdl2:keyboard-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_KeyboardEvent|SDL_KeyboardEvent]]. This event variant occurs when a keyboard key is pressed or released. sdl2:keyboard-event has the following event type symbols: ; {{'key-down}} : A keyboard key was pressed. ; {{'key-up}} : A keyboard key was released. (keyboard-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:keyboard-event. (keyboard-event-window-id event) → integer (set! (keyboard-event-window-id event) val) (keyboard-event-window-id-set! event val) Get 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. (keyboard-event-state event) → boolean (set! (keyboard-event-state event) val) (keyboard-event-state-set! event val) Get or set the event's "state" field, as a boolean indicating whether the key was pressed ({{#t}}) or released ({{#f}}). You can also find out by checking the event type: {{'key-down}} for pressed, or {{'key-up}} for released. (keyboard-event-repeat event) → integer (set! (keyboard-event-repeat event) val) (keyboard-event-repeat-set! event val) Get or set the event's "repeat" field, as a integer. Non-zero indicates that this is a key repeat, caused by the user pressing and holding the key for some time. Zero indicates this is not a key repeat. (keyboard-event-keysym event) → sdl2:keysym (set! (keyboard-event-keysym event) val) (keyboard-event-keysym-set! event val) Get or set the event's "keysym" field, as an sdl2:keysym indicating the key that was pressed or released. The getter returns a copy of the sdl2:keysym stored in the event. Modifying the returned sdl2:keysym will ''not'' modify the event, but setting this field to a sdl2:keysym ''will'' modify the event. Instead of using this procedure, it is more efficient and convenient to directly access the fields of the event's sdl2:keysym, using these procedures: * {{keyboard-event-scancode}} * {{keyboard-event-sym}} * {{keyboard-event-mod}} (keyboard-event-scancode event) → symbol (keyboard-event-scancode-raw event) → integer (set! (keyboard-event-scancode event) val) (keyboard-event-scancode-set! event val) Get or set the "scancode" field of the event's "keysym" field, indicating the physical key that was pressed or released. Setting this will modify the event. * {{keyboard-event-scancode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]]. * {{keyboard-event-scancode-raw}} returns an integer. * The setters accept either a symbol or an integer. (keyboard-event-sym event) → symbol (keyboard-event-sym-raw event) → integer (set! (keyboard-event-sym event) val) (keyboard-event-sym-set! event val) Get or set the "sym" field of the event's "keysym" field, indicating the logical key that was pressed or released. Setting this will modify the event. * {{keyboard-event-sym}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]] * {{keyboard-event-sym-raw}} returns an integer. * The setters accept either a symbol or an integer. (keyboard-event-mod event) → list of symbols (keyboard-event-mod-raw event) → integer (set! (keyboard-event-mod event) val) (keyboard-event-mod-set! event val) Get 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. Setting this will modify the event. * {{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]]. * {{keyboard-event-mod-raw}} returns an integer. * The setters accept either a list of symbols or an integer. ==== sdl2:mouse-button-event sdl2:mouse-button-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_MouseButtonEvent|SDL_MouseButtonEvent]]. This event variant occurs when a mouse button was pressed or released. sdl2:mouse-button-event has the following event type symbols: ; {{'mouse-button-down}} : A mouse button was pressed. ; {{'mouse-button-up}} : A mouse button was released. (mouse-button-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:mouse-button-event. (mouse-button-event-window-id event) → integer (set! (mouse-button-event-window-id event) val) (mouse-button-event-window-id-set! event val) Get 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. (mouse-button-event-which event) → integer (set! (mouse-button-event-which event) val) (mouse-button-event-which-set! event val) Get or set the event's "which" field, as an integer indicating the mouse instance ID. (mouse-button-event-button event) → symbol (mouse-button-event-button-raw event) → integer (set! (mouse-button-event-button event) val) (mouse-button-event-button-set! event val) Get or set the event's "button" field, indicating the button that the event is related to. * {{mouse-button-event-button}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#mouse-buttons|mouse button symbol]]. * {{mouse-button-event-button-raw}} returns an integer. * The setters accept either a symbol or an integer. (mouse-button-event-state event) → boolean (set! (mouse-button-event-state event) val) (mouse-button-event-state-set! event val) Get or set the event's "state" field, as a boolean indicating whether the button was pressed ({{#t}}) or released ({{#f}}). You can also find out by checking the event type: {{'mouse-button-down}} for pressed, or {{'mouse-button-up}} for released. (mouse-button-event-x event) → integer (set! (mouse-button-event-x event) val) (mouse-button-event-x-set! event val) Get 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. (mouse-button-event-y event) → integer (set! (mouse-button-event-y event) val) (mouse-button-event-y-set! event val) Get 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. ==== sdl2:mouse-motion-event sdl2:mouse-motion-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_MouseMotionEvent|SDL_MouseMotionEvent]]. This event variant occurs when the mouse cursor moves. sdl2:mouse-motion-event has the following event type symbols: ; {{'mouse-motion}} : The mouse cursor moved. (mouse-motion-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:mouse-motion-event. (mouse-motion-event-window-id event) → integer (set! (mouse-motion-event-window-id event) val) (mouse-motion-event-window-id-set! event val) Get 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. (mouse-motion-event-which event) → integer (set! (mouse-motion-event-which event) val) (mouse-motion-event-which-set! event val) Get or set the event's "which" field, as an integer indicating the mouse instance ID. (mouse-motion-event-state event) → list of symbols (mouse-motion-event-state-raw event) → integer (set! (mouse-motion-event-state event) val) (mouse-motion-event-state-set! event val) Get or set the event's "state" field, indicating the mouse buttons that were being pressed at the time this event occurred. * {{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]]. * {{mouse-motion-event-state-raw}} returns an integer. * The setters accept either a list of zero or more symbols, or an integer. (mouse-motion-event-x event) → integer (set! (mouse-motion-event-x event) val) (mouse-motion-event-x-set! event val) Get 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. (mouse-motion-event-y event) → integer (set! (mouse-motion-event-y event) val) (mouse-motion-event-y-set! event val) Get 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. (mouse-motion-event-xrel event) → integer (set! (mouse-motion-event-xrel event) val) (mouse-motion-event-xrel-set! event val) Get 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. (mouse-motion-event-yrel event) → integer (set! (mouse-motion-event-yrel event) val) (mouse-motion-event-yrel-set! event val) Get 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. ==== sdl2:mouse-wheel-event sdl2:mouse-wheel-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_MouseWheelEvent|SDL_MouseWheelEvent]]. This event variant occurs when a mouse wheel moves. sdl2:mouse-wheel-event has the following event type symbols: ; {{'mouse-wheel}} : A mouse wheel moved. (mouse-wheel-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:mouse-wheel-event. (mouse-wheel-event-window-id event) → integer (set! (mouse-wheel-event-window-id event) val) (mouse-wheel-event-window-id-set! event val) Get 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. (mouse-wheel-event-which event) → integer (set! (mouse-wheel-event-which event) val) (mouse-wheel-event-which-set! event val) Get or set the event's "which" field, as an integer indicating the mouse instance ID. (mouse-wheel-event-x event) → integer (set! (mouse-wheel-event-x event) val) (mouse-wheel-event-x-set! event val) Get or set the event's "x" field, as an integer (possibly negative) indicating the amount the wheel scrolled horizontally. Positive numbers normally indicate scrolling to the right, negative numbers indicate scrolling to the left. But if the "direction" field is set to {{'flipped}} in SDL 2.0.4 or higher, the meaning of this field is reversed. (mouse-wheel-event-y event) → integer (set! (mouse-wheel-event-y event) val) (mouse-wheel-event-y-set! event val) Get or set the event's "y" field, as an integer (possibly negative) indicating the amount the wheel scrolled vertically. Positive numbers normally indicate scrolling away from the user, negative numbers indicate scrolling toward the user. But if the "direction" field is set to {{'flipped}} in SDL 2.0.4 or higher, the meaning of this field is reversed. (mouse-wheel-event-direction event) → symbol (set! (mouse-wheel-event-direction event) val) (mouse-wheel-event-direction-set! event val) Get or set the event's "direction" field, as one of the following symbols: ; {{'normal}} : "Normal" scrolling mode. ; {{'flipped}} : "Flipped" or "natural" scrolling mode. You can multiple the "x" and "y" field values by -1 to get the "normal" values. Requires SDL 2.0.4 or higher, and sdl2 egg 0.2.0 or higher. ==== sdl2:multi-gesture-event sdl2:multi-gesture-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_MultiGestureEvent|SDL_MultiGestureEvent]]. This event variant occurs when a multi-finger gesture is performed on a touch device. This is useful for recognizing common gestures that involve multiple fingers, e.g. pinching or rotating. sdl2:multi-gesture-event has the following event type symbols: ; {{'multi-gesture}} : A multi-finger gesture was performed. (multi-gesture-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:multi-gesture-event. (multi-gesture-event-touch-id event) → integer (set! (multi-gesture-event-touch-id event) val) (multi-gesture-event-touch-id-set! event val) Get or set the event's "touch-id" field, as an integer indicating the ID number of the touch device this event is related to. (multi-gesture-event-dtheta event) → float (set! (multi-gesture-event-dtheta event) val) (multi-gesture-event-dtheta-set! event val) Get or set the event's "dtheta" field, as a float indicating the amount that the fingers rotated during this motion. (multi-gesture-event-ddist event) → float (set! (multi-gesture-event-ddist event) val) (multi-gesture-event-ddist-set! event val) Get or set the event's "ddist" field, as a float indicating the amount that the fingers pinched during this motion. (multi-gesture-event-x event) → float (set! (multi-gesture-event-x event) val) (multi-gesture-event-x-set! event val) Get or set the event's "x" field, as a float indicating the normalized X coordinate of the center of the gesture. (multi-gesture-event-y event) → float (set! (multi-gesture-event-y event) val) (multi-gesture-event-y-set! event val) Get or set the event's "y" field, as a float indicating the normalized Y coordinate of the center of the gesture. (multi-gesture-event-num-fingers event) → integer (set! (multi-gesture-event-num-fingers event) val) (multi-gesture-event-num-fingers-set! event val) Get or set the event's "num-fingers" field, as an integer indicating the number of fingers used in the gesture. ==== sdl2:quit-event sdl2:quit-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_QuitEvent|SDL_QuitEvent]]. This event variant occurs when the user requests to quit the program. There are [[https://wiki.libsdl.org/SDL_EventType#SDL_QUIT|various ways this might happen]], depending on the platform. sdl2:quit-event has the following event type symbols: ; {{'quit}} : The user requested to quit the program. (quit-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:quit-event. ==== sdl2:sys-wm-event sdl2:sys-wm-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_SysWMEvent|SDL_SysWMEvent]]. This event variant is for very advanced use cases. Most people can ignore it. sdl2:sys-wm-event has the following event type symbols: ; {{'sys-wm}} : A platform-specific event occurred. (sys-wm-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:sys-wm-event. (sys-wm-event-msg-raw event) → pointer (set! (sys-wm-event-msg-raw event) val) (sys-wm-event-msg-raw-set! event val) Get 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. This is for very advanced use cases. Most people can ignore it. ==== sdl2:text-editing-event sdl2:text-editing-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_TextEditingEvent|SDL_TextEditingEvent]]. This event occurs when a user is editing (composing) text, e.g. using an Input Method Editor (IME). See the [[https://wiki.libsdl.org/Tutorials/TextInput|Text Input tutorial for SDL]]. sdl2:text-editing-event has the following event type symbols: ; {{'text-editing}} : The user editted some text being composed. (text-editing-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:text-editing-event. (text-editing-event-window-id event) → integer (set! (text-editing-event-window-id event) val) (text-editing-event-window-id-set! event val) Get 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. (text-editing-event-text event) → string (set! (text-editing-event-text event) val) (text-editing-event-text-set! event val) Get 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. (text-editing-event-start event) → integer (set! (text-editing-event-start event) val) (text-editing-event-start-set! event val) Get or set the event's "start" field, as an integer indicating the location to begin editing from. (text-editing-event-length event) → integer (set! (text-editing-event-length event) val) (text-editing-event-length-set! event val) Get or set the event's "length" field, as an integer indicating the number of characters to edit from the start point. ==== sdl2:text-input-event sdl2:text-input-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_TextInputEvent|SDL_TextInputEvent]]. This event occurs when the users enters some text, possibly using an Input Metod Editor (IME). See the [[https://wiki.libsdl.org/Tutorials/TextInput|Text Input tutorial for SDL]]. sdl2:text-input-event has the following event type symbols: ; {{'text-input}} : The use inputted some text. (text-input-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:text-input-event. (text-input-event-window-id event) → integer (set! (text-input-event-window-id event) val) (text-input-event-window-id-set! event val) Get 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. (text-input-event-text event) → string (set! (text-input-event-text event) val) (text-input-event-text-set! event val) Get 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. ==== sdl2:touch-finger-event sdl2:touch-finger-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_TouchFingerEvent|SDL_TouchFingerEvent]]. This event variant occurs when the user presses, lifts, or moves a finger (or stylus, etc.) on a supported touch device, e.g. the touch screen of a mobile phone or tablet device, or certain laptop trackpads. There may be more than one finger touching at the same time; you can distinguish the fingers by the {{finger-id}} number. sdl2:touch-finger-event has the following event type symbols: ; {{'finger-down}} : A finger started touching a touch device (i.e. was pressed down). ; {{'finger-up}} : A finger stopped touching a touch device (i.e. was lifted up). ; {{'finger-motion}} : A finger moved while touching a touch device. (touch-finger-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:touch-finger-event. (touch-finger-event-touch-id event) → integer (set! (touch-finger-event-touch-id event) val) (touch-finger-event-touch-id-set! event val) Get or set the event's "touch-id" field, as an integer indicating the ID number of the touch device this event is related to. (touch-finger-event-finger-id event) → integer (set! (touch-finger-event-finger-id event) val) (touch-finger-event-finger-id-set! event val) Get or set the event's "finger-id" field, as an integer indicating the ID number of the finger this event is related to. (touch-finger-event-x event) → float (set! (touch-finger-event-x event) val) (touch-finger-event-x-set! event val) Get 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. (touch-finger-event-y event) → float (set! (touch-finger-event-y event) val) (touch-finger-event-y-set! event val) Get 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. (touch-finger-event-dx event) → float (set! (touch-finger-event-dx event) val) (touch-finger-event-dx-set! event val) Get 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. (touch-finger-event-dy event) → float (set! (touch-finger-event-dy event) val) (touch-finger-event-dy-set! event val) Get 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. (touch-finger-event-pressure event) → float (set! (touch-finger-event-pressure event) val) (touch-finger-event-pressure-set! event val) Get or set the event's "pressure" field, as a float in the range 0.0 to 1.0 (inclusive), indicating the pressure being applied. ==== sdl2:user-event sdl2:user-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_UserEvent|SDL_UserEvent]]. This event variant does not occur normally. Instead, you can make instances of this event variant and push them to the event queue using {{push-event!}}. The meaning of this event variant is entirely up for you to decide. For example, you can use it to create custom event types related to your gameplay. sdl2:user-event does not have any event type symbols by default. Call {{register-events!}} to register your own custom event type symbols for sdl2:user-event. (user-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:user-event. (user-event-window-id event) → integer (set! (user-event-window-id event) val) (user-event-window-id-set! event val) Get or set the event's "window-id" field, as an integer indicating the ID number of the sdl2:window associated with this event. (user-event-code event) → integer (set! (user-event-code event) val) (user-event-code-set! event val) Get or set the event's "code" field, as an integer in the range -32768 to 32767 (inclusive). The meaning of this field is for you to decide. (user-event-data1-raw event) → pointer or #f (set! (user-event-data1-raw event) val) (user-event-data1-raw-set! event val) Get or set the event's "data1" field, as a raw pointer or {{#f}}. The meaning of this field is for you to decide. If you want to store a pointer to a Scheme object here, be sure to [[/egg/object-evict|evict the object]] first. Otherwise the object's location in memory might change, rendering the pointer invalid. (user-event-data2-raw event) → pointer or #f (set! (user-event-data2-raw event) val) (user-event-data2-raw-set! event val) Get or set the event's "data2" field, as a raw pointer or {{#f}}. The meaning of this field is for you to decide. If you want to store a pointer to a Scheme object here, be sure to [[/egg/object-evict|evict the object]] first. Otherwise the object's location in memory might change, rendering the pointer invalid. ==== sdl2:window-event sdl2:window-event is a variant of sdl2:event that wraps a pointer to an [[https://wiki.libsdl.org/SDL_WindowEvent|SDL_WindowEvent]]. This event variant occurs when various changes occur to a window, e.g. when a window is moved, resized, minimized, closed, etc. sdl2:window-event has the following event type symbols: ; {{'window}} : A window-related event occurred. (window-event? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:window-event. (window-event-window-id event) → integer (set! (window-event-window-id event) val) (window-event-window-id-set! event val) Get or set the event's "window-id" field, as an integer indicating the ID of the sdl2:window that the event is related to. (window-event-event event) → symbol (window-event-event-raw event) → integer (set! (window-event-event event) val) (window-event-event-set! event val) Get or set the event's "event" field, indicating what happened to the window. * {{window-event-event}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#window-event-types|window event type symbol]]. * {{window-event-event-raw}} returns an integer. * The setters accept either a symbol or an integer. (window-event-data1 event) → integer (set! (window-event-data1 event) val) (window-event-data1-set! event val) Get or set the sdl2:window-event's "data1" field, as an integer. The meaning of this value depends on what kind of window event it was (see {{window-event-event}}). E.g. if the window was resized, this will hold the new window width; if the window was moved, this will hold the new x position. (window-event-data2 event) → integer (set! (window-event-data2 event) val) (window-event-data2-set! event val) Get or set the sdl2:window-event's "data2" field, as an integer. The meaning of this value depends on what kind of window event it was (see {{window-event-event}}). E.g. if the window was resized, this will hold the new window height; if the window was moved, this will hold the new y position. === Game Controller (is-game-controller? joy-index) → boolean Returns {{#t}} if the joystick at the given index is a controller. See [[https://wiki.libsdl.org/SDL_IsGameController|SDL_IsGameController]]. Requires sdl2 egg 0.4.0 or higher. (game-controller-open! joy-index) → sdl2:game-controller Open the game controller wrapping the joystick at the given index. Not all joysticks are controllers; use {{is-game-controller?}} to check before calling this. See [[https://wiki.libsdl.org/SDL_GameControllerOpen|SDL_GameControllerOpen]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires sdl2 egg 0.4.0 or higher. (game-controller-close! controller) See [[https://wiki.libsdl.org/SDL_GameControllerClose|SDL_GameControllerClose]]. Requires sdl2 egg 0.4.0 or higher. (game-controller-from-instance-id instance-id) → sdl2:game-controller See [[https://wiki.libsdl.org/SDL_GameControllerFromInstanceID|SDL_GameControllerFromInstanceID]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires SDL 2.0.4 or higher, and sdl2 egg 0.4.0 or higher. (game-controller-update!) See [[https://wiki.libsdl.org/SDL_GameControllerUpdate|SDL_GameControllerUpdate]]. Requires sdl2 egg 0.4.0 or higher. (game-controller-event-state?) → boolean (set! (game-controller-event-state?) state) (game-controller-event-state-set! state) See [[https://wiki.libsdl.org/SDL_GameControllerEventState|SDL_GameControllerEventState]]. Requires sdl2 egg 0.4.0 or higher. (game-controller-attached? controller) → boolean See [[https://wiki.libsdl.org/SDL_GameControllerGetAttached|SDL_GameControllerGetAttached]]. Requires sdl2 egg 0.4.0 or higher. (game-controller-get-joystick controller) → sdl2:joystick See [[https://wiki.libsdl.org/SDL_GameControllerGetJoystick|SDL_GameControllerGetJoystick]]. Requires sdl2 egg 0.4.0 or higher. (game-controller-mapping controller) → string or #f See [[https://wiki.libsdl.org/SDL_GameControllerMapping|SDL_GameControllerMapping]]. Requires sdl2 egg 0.4.0 or higher. (game-controller-mapping-for-guid) → string or #f See [[https://wiki.libsdl.org/SDL_GameControllerMappingForGUID|SDL_GameControllerMappingForGUID]]. Requires sdl2 egg 0.4.0 or higher. (game-controller-add-mapping! str) → integer Returns 1 if a new mapping was added, 0 if an existing mapping was updated. See [[https://wiki.libsdl.org/SDL_GameControllerAddMapping|SDL_GameControllerAddMapping]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires sdl2 egg 0.4.0 or higher. (game-controller-add-mappings-from-file! path) → integer See [[https://wiki.libsdl.org/SDL_GameControllerAddMappingsFromFile|SDL_GameControllerAddMappingsFromFile]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires SDL 2.0.2 or higher, and sdl2 egg 0.4.0 or higher. (game-controller-add-mappings-from-rw! rwops close?) → integer See [[https://wiki.libsdl.org/SDL_GameControllerAddMappingsFromRW|SDL_GameControllerAddMappingsFromRW]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires SDL 2.0.2 or higher, and sdl2 egg 0.4.0 or higher. (game-controller-num-mappings) → integer See [[https://wiki.libsdl.org/SDL_GameControllerNumMappings|SDL_GameControllerNumMappings]]. Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher. (game-controller-mapping-for-index index) → string or #f See [[https://wiki.libsdl.org/SDL_GameControllerMappingForIndex|SDL_GameControllerMappingForIndex]]. Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher. (game-controller-mapping-for-device-index device-index) → string or #f See [[https://wiki.libsdl.org/SDL_GameControllerMappingForDeviceIndex|SDL_GameControllerMappingForDeviceIndex]]. Requires SDL 2.0.9 or higher, and sdl2 egg 0.4.0 or higher. (game-controller-name controller) → string See [[https://wiki.libsdl.org/SDL_GameControllerName|SDL_GameControllerName]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires sdl2 egg 0.4.0 or higher. (game-controller-name-for-index) → See [[https://wiki.libsdl.org/SDL_GameControllerNameForIndex|SDL_GameControllerNameForIndex]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires sdl2 egg 0.4.0 or higher. (game-controller-get-axis axis) → integer See [[https://wiki.libsdl.org/SDL_GameControllerGetAxis|SDL_GameControllerGetAxis]]. {{axis}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#game-controller-axes|game controller axis symbol]] or equivalent integer. Requires sdl2 egg 0.4.0 or higher. (game-controller-get-axis-from-string str) → symbol (game-controller-get-axis-from-string-raw str) → integer See [[https://wiki.libsdl.org/SDL_GameControllerGetAxisFromString|SDL_GameControllerGetAxisFromString]]. * {{game-controller-get-axis-from-string}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#game-controller-axes|game controller axis symbol]] * {{game-controller-get-axis-from-string}} returns an integer constant Requires sdl2 egg 0.4.0 or higher. (game-controller-get-string-for-axis axis) → See [[https://wiki.libsdl.org/SDL_GameControllerGetStringForAxis|SDL_GameControllerGetStringForAxis]]. {{axis}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#game-controller-axes|game controller axis symbol]] or equivalent integer. Requires sdl2 egg 0.4.0 or higher. (game-controller-get-button button) → boolean See [[https://wiki.libsdl.org/SDL_GameControllerGetButton|SDL_GameControllerGetButton]]. {{button}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#game-controller-buttons|game controller button symbol]] or equivalent integer. Requires sdl2 egg 0.4.0 or higher. (game-controller-get-button-from-string) → (game-controller-get-button-from-string-raw) → See [[https://wiki.libsdl.org/SDL_GameControllerGetButtonFromString|SDL_GameControllerGetButtonFromString]]. * {{game-controller-get-button-from-string}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#game-controller-buttons|game controller button symbol]] * {{game-controller-get-button-from-string}} returns an integer constant Requires sdl2 egg 0.4.0 or higher. (game-controller-get-string-for-button button) → string See [[https://wiki.libsdl.org/SDL_GameControllerGetStringForButton|SDL_GameControllerGetStringForButton]]. {{button}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#game-controller-buttons|game controller button symbol]] or equivalent integer. Requires sdl2 egg 0.4.0 or higher. (game-controller-get-bind-for-axis axis) → sdl2:game-controller-button-bind See [[https://wiki.libsdl.org/SDL_GameControllerGetBindForAxis|SDL_GameControllerGetBindForAxis]]. {{axis}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#game-controller-axes|game controller axis symbol]] or equivalent integer. Requires sdl2 egg 0.4.0 or higher. (game-controller-get-bind-for-button button) → sdl2:game-controller-button-bind See [[https://wiki.libsdl.org/SDL_GameControllerGetBindForButton|SDL_GameControllerGetBindForButton]]. {{button}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#game-controller-buttons|game controller button symbol]] or equivalent integer. Requires sdl2 egg 0.4.0 or higher. (game-controller-get-player-index controller) → integer See [[https://wiki.libsdl.org/SDL_GameControllerGetPlayerIndex|SDL_GameControllerGetPlayerIndex]]. Requires SDL 2.0.9 or higher, and sdl2 egg 0.4.0 or higher. (game-controller-get-product controller) → integer See [[https://wiki.libsdl.org/SDL_GameControllerGetProduct|SDL_GameControllerGetProduct]]. Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher. (game-controller-get-product-version controller) → integer See [[https://wiki.libsdl.org/SDL_GameControllerGetProductVersion|SDL_GameControllerGetProductVersion]]. Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher. (game-controller-get-vendor controller) → integer See [[https://wiki.libsdl.org/SDL_GameControllerGetVendor|SDL_GameControllerGetVendor]]. Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher. (game-controller-rumble! controller low-freq hi-freq duration-ms) → boolean See [[https://wiki.libsdl.org/SDL_GameControllerRumble|SDL_GameControllerRumble]]. Requires SDL 2.0.9 or higher, and sdl2 egg 0.4.0 or higher. ==== sdl2:game-controller sdl2:game-controller is a record type that wraps a pointer to an [[https://wiki.libsdl.org/SDL_GameController|SDL_GameController]] struct. (game-controller? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:game-controller. Requires sdl2 egg 0.4.0 or higher. ==== sdl2:game-controller-button-bind sdl2:game-controller-button-bind is a record type that wraps a pointer to an [[https://wiki.libsdl.org/SDL_GameControllerButtonBind|SDL_GameControllerButtonBind]] struct. Despite the name, this struct is also used for game controller axis bindings. The game controller buttons and axes might be bound to joystick axes, buttons, or hats. (game-controller-button-bind? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:game-controller-button-bind. Requires sdl2 egg 0.4.0 or higher. (game-controller-button-bind-type bind) → symbol (game-controller-button-bind-type-raw bind) → integer Get the sdl2:game-controller-button-bind's "type" field. * {{game-controller-button-bind-type}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#game-controller-bind-types|game controller bind type symbol]]. * {{game-controller-button-bind-type-raw}} returns an integer. Requires sdl2 egg 0.4.0 or higher. (game-controller-button-bind-axis bind) → integer Get the sdl2:game-controller-button-bind's "axis" field, the index of the joystick axis that is bound. This procedure signals an exception if the bind type is not {{axis}}. Check with {{game-controller-button-bind-type}} before calling this. Requires sdl2 egg 0.4.0 or higher. (game-controller-button-bind-button bind) → integer Get the sdl2:game-controller-button-bind's "button" field, the index of the joystick button that is bound. This procedure signals an exception if the bind type is not {{button}}. Check with {{game-controller-button-bind-type}} before calling this. Requires sdl2 egg 0.4.0 or higher. (game-controller-button-bind-hat bind) → integer Get the sdl2:game-controller-button-bind's "hat" field, the index of the joystick hat that is bound. This procedure signals an exception if the bind type is not {{hat}}. Check with {{game-controller-button-bind-type}} before calling this. Requires sdl2 egg 0.4.0 or higher. (game-controller-button-bind-hat-mask-raw bind) → integer Get the sdl2:game-controller-button-bind's "hat" field, the integer bitmask of the joystick hat direction that is bound. This procedure signals an exception if the bind type is not {{hat}}. Check with {{game-controller-button-bind-type}} before calling this. Requires sdl2 egg 0.4.0 or higher. === Hints [[https://wiki.libsdl.org/CategoryHints|Hints (aka Configuration Variables)]] are a way for you to give hints to the SDL library about how you would like it to behave. Most hints affect platform-specific behavior. Hints are merely suggestions, and SDL may or may not obey them. Hints can also be specified or overriden by environment variables. This allows the user to configure SDL to work best on their system. Usually the environment variable is similar to the SDL constant name, but prefixed with "SDL_" instead of "SDL_HINT_". For more information see [[https://hg.libsdl.org/SDL/file/default/include/SDL_hints.h|SDL_hints.h]]. Procedures for getting and setting hints are available in sdl2 egg 0.2.0 and higher. But, SDL will notice environment variables even if you are using an earlier version of the sdl2 egg. Some hints are only effective after a certain version of SDL. You may safely set the hint with any version of SDL, but it will have no effect on older versions of SDL. ==== Hint Functions (get-hint name) → string or #f Returns the current value of the hint as a string, or {{#f}} if the hint has no value. See [[https://wiki.libsdl.org/SDL_GetHint|SDL_GetHint]] and [[https://hg.libsdl.org/SDL/file/default/include/SDL_hints.h|SDL_hints.h]] {{name}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#hints|hint symbol]] or string (same as the environment variable name). Requires sdl2 egg 0.2.0 or higher. (get-hint-boolean name) → boolean Returns the current value of the hint as a boolean. See [[https://wiki.libsdl.org/SDL_GetHintBoolean|SDL_GetHintBoolean]] and [[https://hg.libsdl.org/SDL/file/default/include/SDL_hints.h|SDL_hints.h]] {{name}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#hints|hint symbol]] or string (same as the environment variable name). Requires SDL 2.0.5 or higher, and sdl2 egg 0.4.0 or higher. (set-hint! name value #!optional priority) → boolean Sets the value of the hint. See [[https://wiki.libsdl.org/SDL_SetHintWithPriority|SDL_SetHintWithPriority]] and [[https://hg.libsdl.org/SDL/file/default/include/SDL_hints.h|SDL_hints.h]] {{name}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#hints|hint symbol]] or string (same as the environment variable name). This procedure signals an exception if {{name}} is an unrecognized symbol, but accepts any string, even if it is not recognized. {{value}} specifies the new value of the hint. It must be a string. {{priority}} specifies the priorily level for setting the hint. If it is omitted, the priority will be {{'normal}}. It must be one of these symbols: * {{'default}} * {{'normal}} * {{'override}} Returns {{#t}} if the hint's value was set, or {{#f}} if it was not set (e.g. because the hint was already set with a higher priority). Requires sdl2 egg 0.2.0 or higher. (clear-hints!) Removes the values and priorities of all hints. See [[https://wiki.libsdl.org/SDL_ClearHints|SDL_ClearHints]]. Requires sdl2 egg 0.2.0 or higher. === Joystick ==== Joystick Functions (num-joysticks) → integer See [[https://wiki.libsdl.org/SDL_NumJoysticks|SDL_NumJoysticks]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (joystick-open! index) → sdl2:joystick See [[https://wiki.libsdl.org/SDL_JoystickOpen|SDL_JoystickOpen]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (joystick-close! joystick) See [[https://wiki.libsdl.org/SDL_JoystickClose|SDL_JoystickClose]]. (joystick-from-instance-id id) → sdl2:joystick See [[https://wiki.libsdl.org/SDL_JoystickFromInstanceID|SDL_JoystickFromInstanceID]]. '''Note:''' The returned joystick will be a new sdl2:joystick record pointing to the address of the existing joystick. It will be {{struct-eq?}} to other sdl2:joystick records for the same joystick, but not {{eq?}}. Requires SDL 2.0.4 or higher, and sdl2 egg 0.2.0 or higher. (joystick-update!) See [[https://wiki.libsdl.org/SDL_JoystickUpdate|SDL_JoystickUpdate]]. (joystick-event-state) → boolean (set! (joystick-event-state) state) → boolean (joystick-event-state-set! state) → boolean {{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). See [[https://wiki.libsdl.org/SDL_JoystickEventState|SDL_JoystickEventState]]. The setters enable (if {{state}} is {{#t}}) or disable (if {{state}} is {{#f}}) joytsick events. '''Warning:''' Calling the setters may delete all events currently in the event queue. These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs. (joystick-name-for-index device-index) → string or #f See [[https://wiki.libsdl.org/SDL_JoystickNameForIndex|SDL_JoystickNameForIndex]]. Returns {{#f}} if no name can be found. (joystick-get-device-guid device-index) → sdl2:joystick-guid See [[https://wiki.libsdl.org/SDL_JoystickGetDeviceGUID|SDL_JoystickGetDeviceGUID]]. Returns a new managed sdl2:joystick-guid. (joystick-get-axis-initial-state joy axis) → [state has-initial] See [[https://wiki.libsdl.org/SDL_JoystickGetAxisInitialState|SDL_JoystickGetAxisInitialState]]. This procedure returns multiple values: ; state : Integer value of the initial state. ; has-initial : Boolean indicating whether the joystick axis has an initial state. Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher. (joystick-get-device-instance-id device-index) → integer See [[https://wiki.libsdl.org/SDL_JoystickGetDeviceInstanceID|SDL_JoystickGetDeviceInstanceID]]. Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher. (joystick-get-device-player-index device-index) → integer See [[https://wiki.libsdl.org/SDL_JoystickGetDevicePlayerIndex|SDL_JoystickGetDevicePlayerIndex]]. Requires SDL 2.0.9 or higher, and sdl2 egg 0.4.0 or higher. (joystick-get-device-product device-index) → integer See [[https://wiki.libsdl.org/SDL_JoystickGetDeviceProduct|SDL_JoystickGetDeviceProduct]]. Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher. (joystick-get-device-product-version device-index) → integer See [[https://wiki.libsdl.org/SDL_JoystickGetDeviceProductVersion|SDL_JoystickGetDeviceProductVersion]]. Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher. (joystick-get-device-type device-index) → symbol (joystick-get-device-type-raw device-index) → integer See [[https://wiki.libsdl.org/SDL_JoystickGetDeviceType|SDL_JoystickGetDeviceType]]. * {{joystick-get-device-type}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#joystick-types|joystick type symbol]]. * {{joystick-get-device-type-raw}} returns an integer. Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher. (joystick-get-device-vendor device-index) → See [[https://wiki.libsdl.org/SDL_JoystickGetDeviceVendor|SDL_JoystickGetDeviceVendor]]. Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher. (joystick-get-player-index joystick) → integer See [[https://wiki.libsdl.org/SDL_JoystickGetPlayerIndex|SDL_JoystickGetPlayerIndex]]. Requires SDL 2.0.9 or higher, and sdl2 egg 0.4.0 or higher. (joystick-get-product joystick) → integer See [[https://wiki.libsdl.org/SDL_JoystickGetProduct|SDL_JoystickGetProduct]]. Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher. (joystick-get-product-version joystick) → integer See [[https://wiki.libsdl.org/SDL_JoystickGetProductVersion|SDL_JoystickGetProductVersion]]. Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher. (joystick-get-type joystick) → symbol (joystick-get-type-raw joystick) → integer See [[https://wiki.libsdl.org/SDL_JoystickGetType|SDL_JoystickGetType]]. * {{joystick-get-type}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#joystick-types|joystick type symbol]]. * {{joystick-get-type-raw}} returns an integer. Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher. (joystick-get-vendor joystick) → integer See [[https://wiki.libsdl.org/SDL_JoystickGetVendor|SDL_JoystickGetVendor]]. Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher. (joystick-rumble! low-freq hi-freq duration-ms) → boolean See [[https://wiki.libsdl.org/SDL_JoystickRumble|SDL_JoystickRumble]]. Requires SDL 2.0.9 or higher, and sdl2 egg 0.4.0 or higher. (lock-joysticks!) See [[https://wiki.libsdl.org/SDL_LockJoysticks|SDL_LockJoysticks]]. Requires SDL 2.0.7 or higher, and sdl2 egg 0.4.0 or higher. (unlock-joysticks!) See [[https://wiki.libsdl.org/SDL_UnlockJoysticks|SDL_UnlockJoysticks]]. Requires SDL 2.0.7 or higher, and sdl2 egg 0.4.0 or higher. ==== sdl2:joystick sdl2:joystick is a record type that wraps a pointer to an [[https://wiki.libsdl.org/SDL_Joystick|SDL_Joystick]] struct. (joystick? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:joystick. (joystick-instance-id joystick) → integer See [[https://wiki.libsdl.org/SDL_JoystickInstanceID|SDL_JoystickInstanceID]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (joystick-name joystick) → string or #f See [[https://wiki.libsdl.org/SDL_JoystickName|SDL_JoystickName]]. Returns {{#f}} if no name can be found. (joystick-get-guid joystick) → sdl2:joystick-guid See [[https://wiki.libsdl.org/SDL_JoystickGetGUID|SDL_JoystickGetGUID]]. Returns a new managed sdl2:joystick-guid. (joystick-attached? joystick) → boolean See [[https://wiki.libsdl.org/SDL_JoystickGetAttached|SDL_JoystickGetAttached]]. (joystick-current-power-level joystick) → symbol See [[https://wiki.libsdl.org/SDL_JoystickCurrentPowerLevel|SDL_JoystickCurrentPowerLevel]]. Returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#joystick-power-levels|joystick power level symbol]]. Requires SDL 2.0.4 or higher, and sdl2 egg 0.2.0 or higher. (joystick-num-axes joystick) → integer See [[https://wiki.libsdl.org/SDL_JoystickNumAxes|SDL_JoystickNumAxes]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (joystick-num-balls joystick) → integer See [[https://wiki.libsdl.org/SDL_JoystickNumBalls|SDL_JoystickNumBalls]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (joystick-num-buttons joystick) → integer See [[https://wiki.libsdl.org/SDL_JoystickNumButtons|SDL_JoystickNumButtons]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (joystick-num-hats joystick) → integer See [[https://wiki.libsdl.org/SDL_JoystickNumHats|SDL_JoystickNumHats]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (joystick-get-axis joystick axis-num) → integer See [[https://wiki.libsdl.org/SDL_JoystickGetAxis|SDL_JoystickGetAxis]]. Signals 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}}). (joystick-get-ball joystick ball-num) → [dx dy] See [[https://wiki.libsdl.org/SDL_JoystickGetBall|SDL_JoystickGetBall]]. This procedure returns multiple values. Signals 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}}). Signals an exception of kind {{(exn sdl2)}} if some other error occurs. (joystick-get-button joystick button-num) → boolean See [[https://wiki.libsdl.org/SDL_JoystickGetButton|SDL_JoystickGetButton]]. Signals 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}}). (joystick-get-hat joystick hat-num) → symbol (joystick-get-hat-raw joystick hat-num) → integer See [[https://wiki.libsdl.org/SDL_JoystickGetHat|SDL_JoystickGetHat]]. * {{joystick-get-hat}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#joystick-hat-positions|joystick hat position symbol]]. * {{joystick-get-hat-raw}} returns an integer. Both 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}}). ==== sdl2:joystick-guid sdl2:joystick-guid is a record type that wraps a pointer to an [[https://wiki.libsdl.org/SDL_JoystickGetGUID|SDL_JoystickGUID]] struct. (joystick-guid? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:joystick-guid. (free-joystick-guid! guid) Free the memory of the sdl2:joystick-guid's underlying struct. {{guid}}'s pointer will be set to null (see {{struct-null?}}). It is safe to call this procedure with managed or unmanaged sdl2:joystick-guids. It is safe (but has no effect) to free a struct record multiple times. (joystick-get-guid-from-string str) → sdl2:joystick-guid See [[https://wiki.libsdl.org/SDL_JoystickGetGUIDFromString|SDL_JoystickGetGUIDFromString]]. Returns a new managed sdl2:joystick-guid. (joystick-get-guid-string guid) → string See [[https://wiki.libsdl.org/SDL_JoystickGetGUIDString|SDL_JoystickGetGUIDString]]. === Keyboard ==== Keyboard Functions (get-key-from-name name-str) → symbol (get-key-from-name-raw name-str) → integer See [[https://wiki.libsdl.org/SDL_GetKeyFromName|SDL_GetKeyFromName]]. * {{get-key-from-name}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]]. * {{get-key-from-name-raw}} returns an integer. (get-key-from-scancode scancode) → symbol (get-key-from-scancode-raw scancode) → integer See [[https://wiki.libsdl.org/SDL_GetKeyFromScancode|SDL_GetKeyFromScancode]]. {{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. * {{get-key-from-scancode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]]. * {{get-key-from-scancode-raw}} returns an integer. (get-key-name key) → string See [[https://wiki.libsdl.org/SDL_GetKeyName|SDL_GetKeyName]]. {{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. (get-scancode-from-name name-str) → symbol (get-scancode-from-name-raw name-str) → integer See [[https://wiki.libsdl.org/SDL_GetScancodeFromName|SDL_GetScancodeFromName]]. * {{get-scancode-from-name}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]]. * {{get-scancode-from-name-raw}} returns an integer. (get-scancode-from-key key) → symbol (get-scancode-from-key-raw key) → integer See [[https://wiki.libsdl.org/SDL_GetScancodeFromKey|SDL_GetScancodeFromKey]]. {{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. * {{get-scancode-from-key}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]]. * {{get-scancode-from-key-raw}} returns an integer. (get-scancode-name scancode) → string See [[https://wiki.libsdl.org/SDL_GetScancodeName|SDL_GetScancodeName]]. {{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. (get-keyboard-focus) → sdl2:window See [[https://wiki.libsdl.org/SDL_GetKeyboardFocus|SDL_GetKeyboardFocus]]. (scancode-pressed? scancode) → boolean Returns {{#t}} if the keyboard key with the given scancode is currently being pressed. {{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. This procedure queries SDL's internal keyboard state, which is tied to the event system. Call {{pump-events!}} to update the keyboard state. This procedure is based on [[https://wiki.libsdl.org/SDL_GetKeyboardState|SDL_GetKeyboardState]]. (mod-state) → list of symbols (mod-state-raw) → integer (set! (mod-state) state) (mod-state-set! state) See [[https://wiki.libsdl.org/SDL_GetModState|SDL_GetModState]]. * {{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]]. * {{mod-state-raw}} returns an integer representing a bitfield of keyboard modifiers. * The setters accept either a list of zero or more symbols, or an integer. (text-input-rect-set! rect) {{rect}} can be an sdl2:rect or {{#f}}. See [[https://wiki.libsdl.org/SDL_SetTextInputRect|SDL_SetTextInputRect]]. (start-text-input!) See [[https://wiki.libsdl.org/SDL_StartTextInput|SDL_StartTextInput]]. (stop-text-input!) See [[https://wiki.libsdl.org/SDL_StopTextInput|SDL_StopTextInput]]. (text-input-active?) → boolean See [[https://wiki.libsdl.org/SDL_IsTextInputActive|SDL_IsTextInputActive]]. (screen-keyboard-support?) → boolean See [[https://wiki.libsdl.org/SDL_HasScreenKeyboardSupport|SDL_HasScreenKeyboardSupport]]. (screen-keyboard-shown? window) → boolean See [[https://wiki.libsdl.org/SDL_IsScreenKeyboardShown|SDL_IsScreenKeyboardShown]]. ==== sdl2:keysym sdl2:keysym is a record type that wraps a pointer to an [[https://wiki.libsdl.org/SDL_Keysym|SDL_Keysym]] struct. (keysym? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:keysym. (make-keysym #!optional scancode sym mod) → sdl2:keysym (make-keysym* #!optional scancode sym mod) → sdl2:keysym Allocate and initialize a new sdl2:keysym. {{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. {{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. {{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. * {{make-keysym}} returns a memory-managed sdl2:keysym. * {{make-keysym*}} returns an unmanaged sdl2:keysym, which should be freed with {{free-keysym!}} when you are done with it. (free-keysym! keysym) Free the memory of the sdl2:keysym's underlying struct. {{keysym}}'s pointer will be set to null (see {{struct-null?}}). It is safe to call this procedure with managed or unmanaged sdl2:keysyms. It is safe (but has no effect) to free a struct record multiple times. (keysym-scancode keysym) → symbol (keysym-scancode-raw keysym) → integer (set! (keysym-scancode keysym) val) (keysym-scancode-set! keysym val) Get or set the sdl2:keysym's "scancode" field, indicating the physical key that this keysym describes. * {{keysym-scancode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]]. * {{keysym-scancode-raw}} returns an integer. * The setters accept either a symbol or an integer. (keysym-sym keysym) → symbol (keysym-sym-raw keysym) → integer (set! (keysym-sym keysym) val) (keysym-sym-set! keysym val) Get or set the sdl2:keysym's "sym" field, indicating the logical key that this keysym describes. * {{keysym-sym}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]]. * {{keysym-sym-raw}} returns an integer. * The setters accept either a symbol or an integer. (keysym-mod keysym) → list of symbols (keysym-mod-raw keysym) → integer (set! (keysym-mod keysym) val) (keysym-mod-set! keysym val) Get or set the sdl2:keysym's "mod" field, indicating the modifier keys that this keysym describes. * {{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]]. * {{keysym-mod-raw}} returns an integer. * The setters accept either a list of zero or more symbols, or an integer. === Mouse (capture-mouse! enabled) See [[https://wiki.libsdl.org/SDL_CaptureMouse|SDL_CaptureMouse]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires SDL 2.0.4 or higher, and sdl2 egg 0.4.0 or higher. (get-global-mouse-state) → [list x y] (get-global-mouse-state-raw) → [bitmask x y] See [[https://wiki.libsdl.org/SDL_GetGlobalMouseState|SDL_GetGlobalMouseState]]. These procedures return multiple values: * {{get-global-mouse-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]], an integer x coordinate, and an integer y coordinate. * {{get-global-mouse-state}} returns an integer bitmask, an integer x coordinate, and an integer y coordinate. Requires SDL 2.0.4 or higher, and sdl2 egg 0.4.0 or higher. (get-mouse-focus) → sdl2:window or #f See [[https://wiki.libsdl.org/SDL_GetMouseFocus|SDL_GetMouseFocus]]. Requires sdl2 egg 0.4.0 or higher. (get-mouse-state) → [list x y] (get-mouse-state-raw) → [bitmask x y] See [[https://wiki.libsdl.org/SDL_GetMouseState|SDL_GetMouseState]]. * {{get-mouse-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]], an integer x coordinate, and an integer y coordinate. * {{get-mouse-state}} returns an integer bitmask, an integer x coordinate, and an integer y coordinate. Requires sdl2 egg 0.4.0 or higher. (get-relative-mouse-mode) → boolean (set! (get-relative-mouse-mode) boolean) (relative-mouse-mode-set! boolean) See [[https://wiki.libsdl.org/SDL_GetRelativeMouseMode|SDL_GetRelativeMouseMode]]. Requires sdl2 egg 0.4.0 or higher. (get-relative-mouse-state) → [list x y] (get-relative-mouse-state-raw) → [bitmask x y] See [[https://wiki.libsdl.org/SDL_GetRelativeMouseState|SDL_GetRelativeMouseState]]. * {{get-relative-mouse-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]], an integer x coordinate, and an integer y coordinate. * {{get-relative-mouse-state}} returns an integer bitmask, an integer x coordinate, and an integer y coordinate. Requires sdl2 egg 0.4.0 or higher. (warp-mouse-global! x y) See [[https://wiki.libsdl.org/SDL_WarpMouseGlobal|SDL_WarpMouseGlobal]]. Requires SDL 2.0.4 or higher, and sdl2 egg 0.4.0 or higher. (warp-mouse-in-window! window x y) See [[https://wiki.libsdl.org/SDL_WarpMouseInWindow|SDL_WarpMouseInWindow]]. Requires sdl2 egg 0.4.0 or higher. === OpenGL ==== OpenGL Functions (gl-create-context! window) → sdl2:gl-context See [[https://wiki.libsdl.org/SDL_GL_CreateContext|SDL_GL_CreateContext]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (gl-delete-context! gl-context) See [[https://wiki.libsdl.org/SDL_GL_DeleteContext|SDL_GL_DeleteContext]]. (gl-make-current! window gl-context) See [[https://wiki.libsdl.org/SDL_GL_MakeCurrent|SDL_GL_MakeCurrent]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (gl-get-current-window) → sdl2:window See [[https://wiki.libsdl.org/SDL_GL_GetCurrentWindow|SDL_GL_GetCurrentWindow]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (gl-get-current-context) → sdl2:gl-context See [[https://wiki.libsdl.org/SDL_GL_GetCurrentContext|SDL_GL_GetCurrentContext]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (gl-attribute attr) → value (set! (gl-attribute attr) value) (gl-attribute-set! attr value) See [[https://wiki.libsdl.org/SDL_GL_GetAttribute|SDL_GL_GetAttribute]] and [[https://wiki.libsdl.org/SDL_GL_SetAttribute|SDL_GL_SetAttribute]]. {{attr}} must be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#opengl-attributes|OpenGL attribute symbol]] or corresponding integer. The value's type depends on {{attr}}: * 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.) * 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.) * 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 or higher, and sdl2 egg 0.2.0 or higher.) * Otherwise, the value is an integer. The getter and the setters signal an exception of kind {{(exn sdl2)}} if an error occurs. (gl-reset-attributes!) See [[https://wiki.libsdl.org/SDL_GL_ResetAttributes|SDL_GL_ResetAttributes]]. Requires SDL 2.0.2 or higher. (gl-get-drawable-size window) → [width height] See [[https://wiki.libsdl.org/SDL_GL_GetDrawableSize|SDL_GL_GetDrawableSize]]. This procedure returns multiple values. Requires SDL 2.0.1 or higher. (gl-swap-window!) See [[https://wiki.libsdl.org/SDL_GL_SwapWindow|SDL_GL_SwapWindow]]. (gl-swap-interval) → integer (set! (gl-swap-interval) interval) (gl-set-swap-interval! interval) See [[https://wiki.libsdl.org/SDL_GL_GetSwapInterval|SDL_GL_GetSwapInterval]] and [[https://wiki.libsdl.org/SDL_GL_SetSwapInterval|SDL_GL_SetSwapInterval]]. The setters signal an exception of kind {{(exn sdl2)}} if an error occurs. (gl-extension-supported? name-string) → boolean See [[https://wiki.libsdl.org/SDL_GL_ExtensionSupported|SDL_GL_ExtensionSupported]]. (gl-bind-texture! texture) → [tex-w tex-h] Bind the given sdl2:texture for use with the current OpenGL context. See [[https://wiki.libsdl.org/SDL_GL_BindTexture|SDL_GL_BindTexture]]. Returns multiple values: ; tex-w : The bound OpenGL texture's width, as a float (usually 1.0) ; tex-h : The bound OpenGL texture's height, as a float (usually 1.0) Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires sdl2 egg 0.2.0 or higher. (gl-unbind-texture! texture) Unbind the given sdl2:texture from the OpenGL context. See [[https://wiki.libsdl.org/SDL_GL_UnbindTexture|SDL_GL_UnbindTexture]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires sdl2 egg 0.2.0 or higher. ==== sdl2:gl-context sdl2:gl-context is a record type that wraps a pointer to an SDL_GLContext struct. (gl-context? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:gl-context. === Palette ==== sdl2:palette sdl2:palette is a record type that wraps a pointer to an [[https://wiki.libsdl.org/SDL_Palette|SDL_Palette]] struct. (palette? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:palette. (make-palette #!optional ncolors) → sdl2:palette (make-palette* #!optional ncolors) → sdl2:palette Allocate and initialize a new sdl2:palette with the given number of colors. See [[https://wiki.libsdl.org/SDL_AllocPalette|SDL_AllocPalette]]. {{ncolors}} defaults to 256. Common values are 2 (for a 1-bit surface), 16 (for a 4-bit surface), and 256 (for an 8-bit surface). '''Note:''' Usually you do not need to manually allocate a palette. A palette will be created for you when you create a surface with a depth of 8 or lower, and the palette will be automatically freed when the surface is freed (unless the palette is still being used by other surfaces). * {{make-palette}} returns a memory-managed sdl2:palette. * {{make-palette*}} returns an unmanaged sdl2:palette, which should be freed with {{free-palette!}} when you are done with it. Both procedures signal an exception of kind {{(exn sdl2)}} if an error occurs. (free-palette! palette) Free the memory of the sdl2:palette's underlying struct. {{palette}}'s pointer will be set to null (see {{struct-null?}}). It is safe to call this procedure with managed or unmanaged sdl2:palettes. It is safe (but has no effect) to free a struct record multiple times. See [[https://wiki.libsdl.org/SDL_FreePalette|SDL_FreePalette]]. (palette-ncolors palette) → integer (palette-ncolours palette) → integer Returns the number of colors in the palette. Common values are 2 (for a 1-bit surface), 16 (for a 4-bit surface), and 256 (for an 8-bit surface). (palette-ref palette i) → sdl2:color (set! (palette-ref palette i) color) (palette-set! palette i color) {{palette-ref}} returns a copy of the color at the given index of the palette, as a memory-managed sdl2:color. The setters set the given index of the palette to a copy of the given sdl2:color. These procedures signal an exception of kind {{(exn bounds)}} if the given index is out of bounds. (palette-colors palette) → vector of sdl2:colors (palette-colours palette) → vector of sdl2:colors (set! (palette-colors palette) colors-vec) → boolean (set! (palette-colours palette) colors-vec) → boolean (palette-colors-set! colors-vec #!optional firstcolor) → boolean (palette-colours-set! colors-vec #!optional firstcolor) → boolean {{palette-colors}} and {{palette-colours}} return copies of all colors in the palette, as a Scheme vector of managed sdl2:colors. The setters set multiple colors in the palette to copies of the given colors. See [[https://wiki.libsdl.org/SDL_SetPaletteColors|SDL_SetPaletteColors]]. {{colors-vec}} must be a Scheme vector of sdl2:colors. {{firstcolor}} specifies the first index of the palette to set. I.e., palette index {{firstcolor}} will be set to the first color in {{colors-vec}}, palette index {{firstcolor + 1}} will be set to the second color, and so on. {{firstcolor}} defaults to 0. Signals an exception of kind {{(exn bounds)}} if {{firstcolor}} is out of bounds. The {{set!}} form cannot accept the {{firstcolor}} argument. The setters return {{#t}} if every color in {{colors-vec}} was used, or {{#f}} if some colors were not used, e.g. because there were more colors in the vector than could fit in the palette. === Pixel Format ==== Pixel Format Functions (map-rgb pixel-format r g b) → integer (map-rgba pixel-format r g b a) → integer See [[https://wiki.libsdl.org/SDL_MapRGB|SDL_MapRGB]] and [[https://wiki.libsdl.org/SDL_MapRGBA|SDL_MapRGBA]]. (get-rgb pixel pixel-format) → [r g b] (get-rgba pixel pixel-format) → [r g b a] See [[https://wiki.libsdl.org/SDL_GetRGB|SDL_GetRGB]] and [[https://wiki.libsdl.org/SDL_GetRGBA|SDL_GetRGBA]]. These procedures return multiple values. (pixel-format-enum-to-masks format-enum) → [bpp rmask gmask bmask amask] See [[https://wiki.libsdl.org/SDL_PixelFormatEnumToMasks|SDL_PixelFormatEnumToMasks]]. {{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. This procedure returns multiple values: ; bpp : The color depth (bits per pixel) of the format. ; rmask : The red mask of the format. ; gmask : The green mask of the format. ; bmask : The blue mask of the format. ; amask : The alpha mask of the format. Signals an exception of kind {{(exn sdl2)}} if conversion was not possible. ==== sdl2:pixel-format sdl2:pixel-format is a record type that wraps a pointer to an [[https://wiki.libsdl.org/SDL_PixelFormat|SDL_PixelFormat]] struct. (pixel-format? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:pixel-format. (make-pixel-format #!optional format) → sdl2:pixel-format (make-pixel-format* #!optional format) → sdl2:pixel-format Allocate and initialize a new sdl2:pixel-format with the given format. {{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. See [[https://wiki.libsdl.org/SDL_AllocFormat|SDL_AllocFormat]]. * {{make-pixel-format}} returns a memory-managed sdl2:pixel-format. * {{make-pixel-format*}} returns an unmanaged sdl2:pixel-format, which should be freed with {{free-pixel-format!}} when you are done with it. Both procedures signal an exception of kind {{(exn sdl2)}} if an error occurs. (free-pixel-format! pixel-format) Free the memory of the sdl2:pixel-format's underlying struct. {{pixel-format}}'s pointer will be set to null (see {{struct-null?}}). It is safe to call this procedure with managed or unmanaged sdl2:pixel-formats. It is safe (but has no effect) to free a struct record multiple times. See [[https://wiki.libsdl.org/SDL_FreeFormat|SDL_FreeFormat]]. (pixel-format-format pixel-format) → symbol (pixel-format-format-raw pixel-format) → integer Get the sdl2:pixel-format's "format" field. * {{pixel-format-format}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]]. * {{pixel-format-format-raw}} returns an integer. (pixel-format-palette pixel-format) → sdl2:palette or #f (set! (pixel-format-palette pixel-format) val) (pixel-format-palette-set! pixel-format val) Get or set the sdl2:pixel-format's "palette" field, as an sdl2:palette, or {{#f}} if it does not have a palette. Only sdl2:pixel-formats with bits-per-pixel of 8 or less can have a palette. See [[https://wiki.libsdl.org/SDL_SetPixelFormatPalette|SDL_SetPixelFormatPalette]]. The setters signal an exception of kind {{(exn sdl2)}} if an error occurs. (pixel-format-bits-per-pixel pixel-format) → integer Get the sdl2:pixel-format's "bits-per-pixel" field, as an integer. Common values are 32, 24, 16, 15, 8, 4, and 1. (pixel-format-bytes-per-pixel pixel-format) → integer Get the sdl2:pixel-format's "bits-per-pixel" field, as an integer. Possible values are 4, 3, 2, and 1. (pixel-format-rmask pixel-format) → integer Get the sdl2:pixel-format's "rmask" (red mask) field, as a nonnegative integer. (pixel-format-gmask pixel-format) → integer Get the sdl2:pixel-format's "gmask" (green mask) field, as a nonnegative integer. (pixel-format-bmask pixel-format) → integer Get the sdl2:pixel-format's "bmask" (blue mask) field, as a nonnegative integer. (pixel-format-amask pixel-format) → integer Get the sdl2:pixel-format's "amask" (alpha mask) field, as a nonnegative integer. It will be 0 if there is no alpha channel. === Rect / Point ==== Rect / Point Functions (rect-empty? rect) → boolean Returns {{#t}} if {{rect}}'s width and/or height is less than or equal to zero. See [[https://wiki.libsdl.org/SDL_RectEmpty|SDL_RectEmpty]]. (point-in-rect? point rect) → boolean Returns {{#t}} if the sdl2:point is inside the sdl2:rect, or {{#f}} if it is not. See [[https://wiki.libsdl.org/SDL_PointInRect|SDL_PointInRect]]. Requires SDL 2.0.4 or higher, and sdl2 egg 0.2.0 or higher. (enclose-points points #!optional clip result-rect) → [rect any-enclosed?] See [[https://wiki.libsdl.org/SDL_EnclosePoints|SDL_EnclosePoints]]. {{points}} must be a list of sdl2:points. {{clip}} must be either an sdl2:rect or {{#f}} (the default). If {{clip}} is an sdl2:rect, points outside the clip rect will be ignored. If {{result-rect}} is omitted or {{#f}}, a new managed sdl2:rect will be returned. If {{result-rect}} is an sdl2:rect, it will be modified and returned. It is safe for {{result-rect}} to be the same object as {{clip}}, in which case {{clip}} will be modified and returned. This procedure returns multiple values: ; rect : An sdl2:rect that encloses all matching points. This will be the same object as {{result-rect}}, if {{result-rect}} was specified. ; any-enclosed? : {{#t}} if any points were enclosed, or {{#f}} if all points were clipped (has-intersection? rect1 rect2) → boolean Returns {{#t}} if {{rect1}} and {{rect2}} intersect, or {{#f}} if they do not. See [[https://wiki.libsdl.org/SDL_HasIntersection|SDL_HasIntersection]]. (intersect-rect rect1 rect2 #!optional result-rect) → [rect intersect?] Calculates the intersection of {{rect1}} and {{rect2}}. See [[https://wiki.libsdl.org/SDL_IntersectRect|SDL_IntersectRect]]. If {{result-rect}} is omitted or {{#f}}, a new managed sdl2:rect will be returned. If {{result-rect}} is an sdl2:rect, it will be modified and returned. It is safe for {{result-rect}} to be the same object as {{rect1}} or {{rect2}}, in which case {{rect1}} or {{rect2}} will be modified and returned. It is safe (but useless) for {{rect1}} and {{rect2}} to be the same object. This procedure returns multiple values: ; 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. ; intersect? : {{#t}} if {{rect1}} and {{rect2}} intersect, otherwise #f (intersect-rect-and-line rect x1 y1 x2 y2) → [intersect? x1-new y1-new x2-new y2-new] Calculates the intersection between {{rect}} and the line segment described by {{x1}}, {{y1}}, {{x2}}, and {{y2}}. See [[https://wiki.libsdl.org/SDL_IntersectRectAndLine|SDL_IntersectRectAndLine]]. {{rect}} must be an sdl2:rect. {{x1}}, {{y1}}, {{x2}}, and {{y2}} should be integers. This procedure returns multiple values: ; intersect? : {{#t}} if the line segment intersects with the rect, otherwise #f ; x1-new : integer x1 of the new line segment ; y1-new : integer y1 of the new line segment ; x2-new : integer x2 of the new line segment ; y2-new : integer y2 of the new line segment If the line segment does not intersect the rect, then {{intersect?}} will be {{#f}}, and {{x1-new}}, {{y1-new}}, {{x2-new}}, and {{y2-new}} will be the same as the original arguments. (union-rect rect1 rect2 #!optional result-rect) → rect See [[https://wiki.libsdl.org/SDL_UnionRect|SDL_UnionRect]]. If {{result-rect}} is omitted or {{#f}}, a new managed sdl2:rect will be returned. If {{result-rect}} is an sdl2:rect, it will be modified and returned. It is safe for {{result-rect}} to be the same object as {{rect1}} or {{rect2}}, in which case {{rect1}} or {{rect2}} will be modified and returned. It is safe (but useless) for {{rect1}} and {{rect2}} to be the same object. ==== sdl2:rect sdl2:rect is a record type that wraps a pointer to an [[https://wiki.libsdl.org/SDL_Rect|SDL_Rect]] struct. (rect? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:rect. (make-rect #!optional x y w h) → sdl2:rect (make-rect* #!optional x y w h) → sdl2:rect Allocate and initialize a new sdl2:rect. {{x}}, {{y}}, {{w}}, and {{h}} must be integers in the range -2147483648 to 2147483647 (inclusive). They all default to 0. * {{make-rect}} returns a memory-managed sdl2:rect. * {{make-rect*}} returns an unmanaged sdl2:rect, which should be freed with {{free-rect!}} when you are done with it. (free-rect! rect) Free the memory of the sdl2:rect's underlying struct. {{rect}}'s pointer will be set to null (see {{struct-null?}}). It is safe to call this procedure with managed or unmanaged sdl2:rects. It is safe (but has no effect) to free a struct record multiple times. (rect-x rect) → integer (set! (rect-x rect) val) (rect-x-set! rect val) Get or set the sdl2:rect's "x" field, as an integer in the range -2147483648 to 2147483647 (inclusive). (rect-y rect) → integer (set! (rect-y rect) val) (rect-y-set! rect val) Get or set the sdl2:rect's "y" field, as an integer in the range -2147483648 to 2147483647 (inclusive). (rect-w rect) → integer (set! (rect-w rect) val) (rect-w-set! rect val) Get or set the sdl2:rect's "w" (width) field, as an integer in the range -2147483648 to 2147483647 (inclusive). (rect-h rect) → integer (set! (rect-h rect) val) (rect-h-set! rect val) Get or set the sdl2:rect's "h" (height) field, as an integer in the range -2147483648 to 2147483647 (inclusive). ==== sdl2:rect Operations These are operations for efficiently and conveniently working with sdl2:rects. Many of them are implemented in C for efficiency. (rect-set! rect #!optional x y w h) → rect Efficient and convenient way of setting multiple fields of the sdl2:rect. Any arguments that are {{#f}} will cause no change to that field. E.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. Returns {{rect}} after it is modified. (rect->list rect) → list of integers Returns a list {{(x y w h)}} containing the value of each field of the sdl2:rect. (rect->values rect) → [x y w h] Returns multiple values containing the value of each field of the sdl2:rect. This is useful for destructuring an sdl2:rect using {{receive}} or {{let-values}}. (rect=? rect1 rect2) → boolean Efficiently compare two sdl2:rects. Returns {{#t}} if the value of every field in {{rect1}} is equal to the value of the corresponding field in {{rect2}}. See [[https://wiki.libsdl.org/SDL_RectEquals|SDL_RectEquals]]. (rect-copy src) → sdl2:rect (rect-copy! src dest) → dest {{rect-copy}} efficiently copies the values of {{src}} into a new managed sdl2:rect. {{rect-copy!}} efficiently copies the values of {{src}} into {{dest}}, and returns the modified {{dest}}. It is safe (but useless) for {{src}} and {{dest}} to be the same object. Requires sdl2 egg 0.2.0 or higher. (rect-scale rect factor) → sdl2:rect (rect-scale! rect factor #!optional dest) → dest Efficiently multiply the X, Y, W, and H values of {{rect}} by {{factor}} (a float or integer). E.g. {{factor}} 0.5 halves the values, {{factor}} 2.0 doubles the values. sdl2:rect can only hold integer values, so the results will be truncated to integers. The results will be clamped to the range -2147483648 to 2147483647. * {{rect-scale}} returns a new managed sdl2:rect. * {{rect-scale!}} modifies and returns {{dest}}. If {{dest}} is omitted, {{rect}} is modified and returned. Requires sdl2 egg 0.2.0 or higher. (rect-unscale rect factor) → sdl2:rect (rect-unscale! rect factor #!optional dest) → dest Efficiently divide the X, Y, W, and H values of {{rect}} by {{factor}} (a float or integer). This is equivalent to {{(rect-scale rect (/ 1 factor))}}, but is more convenient and efficient (especially if {{factor}} is an integer). These procedures signal an exception if {{factor}} is 0. sdl2:rect can only hold integer values, so the results will be truncated to integers. The results will be clamped to the range -2147483648 to 2147483647. * {{rect-unscale}} returns a new managed sdl2:rect. * {{rect-unscale!}} modifies and returns {{dest}}. If {{dest}} is omitted, {{rect}} is modified and returned. Requires sdl2 egg 0.2.0 or higher. (rect-move rect dx dy) → sdl2:rect (rect-move! rect dx dy #!optional dest) → dest Efficiently move {{rect}} by adding the given amounts to its X and Y values. {{dx}} and {{dy}} must be integers. The results will be clamped to the range -2147483648 to 2147483647. If {{dx}} and {{dy}} are already stored in an sdl2:point, it is more efficient and convenient to use {{rect-add-point}} or {{rect-sub-point}}, instead of extracting the individual fields from the point. * {{rect-move}} returns a new managed sdl2:rect. * {{rect-move!}} modifies and returns {{dest}}. If {{dest}} is omitted, {{rect}} is modified and returned. Requires sdl2 egg 0.2.0 or higher. (rect-add-point rect point) → sdl2:rect (rect-add-point! rect point #!optional dest) → dest Efficiently move {{rect}} by adding {{point}} to {{rect}}'s X and Y values. The results will be clamped to the range -2147483648 to 2147483647. If the dx and dy values are already held as separate variables, it is more efficient and convenient to use {{rect-move}}, instead of creating an sdl2:point. * {{rect-add-point}} returns a new managed sdl2:rect. * {{rect-add-point!}} modifies and returns {{dest}}. If {{dest}} is omitted, {{rect}} is modified and returned. Requires sdl2 egg 0.2.0 or higher. (rect-sub-point rect point) → sdl2:rect (rect-sub-point! rect point #!optional dest) → dest Efficiently move {{rect}} by subtracting {{point}} from {{rect}}'s X and Y values. The results will be clamped to the range -2147483648 to 2147483647. If the dx and dy values are already held as separate variables, it is more efficient and convenient to negate the values and use {{rect-move}}, instead of creating an sdl2:point. * {{rect-sub-point}} returns a new managed sdl2:rect. * {{rect-sub-point!}} modifies and returns {{dest}}. If {{dest}} is omitted, {{rect}} is modified and returned. Requires sdl2 egg 0.2.0 or higher. (rect-grow rect dw dh) → sdl2:rect (rect-grow! rect dw dh #!optional dest) → dest Efficiently increase {{rect}}'s size by adding to its W and H values. The rect's top left corner will stay the same. See also {{rect-grow/center!}}, which keeps the rect's center point the same. The results will be clamped to the range -2147483648 to 2147483647. {{dw}} and {{dh}} must be integers. Negative numbers cause the size to decrease (i.e. shrink). * {{rect-grow}} returns a new managed sdl2:rect. * {{rect-grow!}} modifies and returns {{dest}}. If {{dest}} is omitted, {{rect}} is modified and returned. Requires sdl2 egg 0.2.0 or higher. (rect-grow/center rect dw dh) → sdl2:rect (rect-grow/center! rect dw dh #!optional dest) → dest Efficiently increase {{rect}}'s size while trying to keep the same center point. See also {{rect-grow!}}, which keeps the rect's top left corner the same. The results will be clamped to the range -2147483648 to 2147483647. {{dw}} and {{dh}} must be integers. Negative numbers cause the size to decrease (i.e. shrink). For best results, use even numbers for {{dw}} and {{dh}}. If {{dw}} or {{dh}} are odd numbers, the rect's center point will change by half a pixel due to rounding. * {{rect-grow/center}} returns a new managed sdl2:rect. * {{rect-grow/center!}} modifies and returns {{dest}}. If {{dest}} is omitted, {{rect}} is modified and returned. Requires sdl2 egg 0.2.0 or higher. (rect-lerp rect1 rect2 t) → sdl2:rect (rect-lerp! rect1 rect2 t #!optional dest) → dest Efficient linear interpolation (or extrapolation) between {{rect1}} and {{rect2}}. sdl2:rect can only hold integer values, so the results will be truncated to integers. The results will be clamped to the range -2147483648 to 2147483647. These procedures affect all values of the rect: X, Y, W, and H. If you only want to interpolate the rect's position (X and Y), use {{rect-lerp-xy}} instead. {{t}} is the interpolation factor (a float). Values of {{t}} between 0 and 1 will interpolate between {{rect1}} and {{rect2}}. Values of {{t}} less that 0 will extrapolate beyond {{rect1}} (moving away from {{rect2}}). Values greater that 1 will extrapolate beyond {{rect2}} (moving away from {{rect1}}). * {{rect-lerp}} returns a new managed sdl2:rect. * {{rect-lerp!}} modifies and returns {{dest}}. If {{dest}} is omitted, {{rect1}} is modified and returned. Requires sdl2 egg 0.2.0 or higher. (rect-lerp-xy rect1 rect2 t) → sdl2:rect (rect-lerp-xy! rect1 rect2 t #!optional dest) → dest Efficient linear interpolation (or extrapolation) between {{rect1}} and {{rect2}}. sdl2:rect can only hold integer values, so the results will be truncated to integers. The results will be clamped to the range -2147483648 to 2147483647. These procedures only affect the X and Y values of the rect. The result will have the same W and H as {{rect1}}. If you want interpolate all values (X, Y, W, and H), use {{rect-lerp}} instead. {{t}} is the interpolation factor (a float). Values of {{t}} between 0 and 1 will interpolate between {{rect1}} and {{rect2}}. Values of {{t}} less that 0 will extrapolate beyond {{rect1}} (moving away from {{rect2}}). Values greater that 1 will extrapolate beyond {{rect2}} (moving away from {{rect1}}). * {{rect-lerp-xy}} returns a new managed sdl2:rect. * {{rect-lerp-xy!}} modifies and returns {{dest}}. If {{dest}} is omitted, {{rect1}} is modified and returned. Requires sdl2 egg 0.2.0 or higher. ==== sdl2:point sdl2:point is a record type that wraps a pointer to an [[https://wiki.libsdl.org/SDL_Point|SDL_Point]] struct. (point? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:point. (make-point #!optional x y) → sdl2:point (make-point* #!optional x y) → sdl2:point Allocate and initialize a new sdl2:point. {{x}} and {{y}} must be integers in the range -2147483648 to 2147483647 (inclusive). They both default to 0. * {{make-point}} returns a memory-managed sdl2:point. * {{make-point*}} returns an unmanaged sdl2:point, which should be freed with {{free-point!}} when you are done with it. (free-point! point) Free the memory of the sdl2:point's underlying struct. {{point}}'s pointer will be set to null (see {{struct-null?}}). It is safe to call this procedure with managed or unmanaged sdl2:points. It is safe (but has no effect) to free a struct record multiple times. (point-x point) → integer (set! (point-x point) val) (point-x-set! point val) Get or set the sdl2:point's "x" field, as an integer in the range -2147483648 to 2147483647 (inclusive). (point-y point) → integer (set! (point-y point) val) (point-y-set! point val) Get or set the sdl2:point's "y" field, as an integer in the range -2147483648 to 2147483647 (inclusive). ==== sdl2:point Operations These are operations for efficiently and conveniently working with sdl2:points. Many of them are implemented in C for efficiency. (point-set! point #!optional x y) → point Efficient and convenient way of setting multiple fields of the sdl2:point. Any arguments that are {{#f}} will cause no change to that field. E.g. {{(point-set! my-point 42 #f)}} will set the "x" field to 42, but will not change the "y" field. Returns {{point}} after it is modified. (point->list point) → list of integers Returns a list {{(x y)}} containing the value of each field of the sdl2:point. (point->values point) → [x y] Returns multiple values containing the value of each field of the sdl2:point. This is useful for destructuring an sdl2:point using {{receive}} or {{let-values}}. (point=? point1 point2) → boolean Efficiently compare two sdl2:points. Returns {{#t}} if the value of every field in {{point1}} is equal to the value of the corresponding field in {{point2}}. (point-copy src) → sdl2:point (point-copy! src dest) → dest {{point-copy}} efficiently copies the values of {{src}} into a new managed sdl2:point. {{point-copy!}} efficiently copies the values of {{src}} into {{dest}}, and returns the modified {{dest}}. It is safe (but useless) for {{src}} and {{dest}} to be the same object. Requires sdl2 egg 0.2.0 or higher. (point-scale point factor) → sdl2:point (point-scale! point factor #!optional dest) → dest Efficiently multiply the X and Y values of {{point}} by {{factor}} (a float or integer). E.g. {{factor}} 0.5 halves the values, {{factor}} 2.0 doubles the values. sdl2:point can only hold integer values, so the results will be truncated to integers. The results will be clamped to the range -2147483648 to 2147483647. * {{point-scale}} returns a new managed sdl2:point. * {{point-scale!}} modifies and returns {{dest}}. If {{dest}} is omitted, {{point}} is modified and returned. Requires sdl2 egg 0.2.0 or higher. (point-unscale point factor) → sdl2:point (point-unscale! point factor #!optional dest) → dest Efficiently divide the X and Y values of {{point}} by {{factor}} (a float or integer). This is equivalent to {{(point-scale point (/ 1 factor))}}, but is more convenient and efficient (especially if {{factor}} is an integer). These procedures signal an exception if {{factor}} is 0. sdl2:point can only hold integer values, so the results will be truncated to integers. The results will be clamped to the range -2147483648 to 2147483647. * {{point-unscale}} returns a new managed sdl2:point. * {{point-unscale!}} modifies and returns {{dest}}. If {{dest}} is omitted, {{point}} is modified and returned. Requires sdl2 egg 0.2.0 or higher. (point-move point dx dy) → sdl2:point (point-move! point dx dy #!optional dest) → dest Efficiently move {{point}} by adding the given amounts to its X and Y values. {{dx}} and {{dy}} must be integers. The results will be clamped to the range -2147483648 to 2147483647. If {{dx}} and {{dy}} are already stored in an sdl2:point, it is more efficient and convenient to use {{point-add}} or {{point-sub}}, instead of extracting the individual fields from the point. * {{point-move}} returns a new managed sdl2:point. * {{point-move!}} modifies and returns {{dest}}. If {{dest}} is omitted, {{point}} is modified and returned. Requires sdl2 egg 0.2.0 or higher. (point-add point1 point2) → sdl2:point (point-add! point1 point2 #!optional dest) → dest Efficiently add {{point1}} and {{point2}} (vector addition). The results will be clamped to the range -2147483648 to 2147483647. If the dx and dy values are already held as separate variables, it is more efficient and convenient to use {{point-move}}, instead of creating an sdl2:point. * {{point-add}} returns a new managed sdl2:point. * {{point-add!}} modifies and returns {{dest}}. If {{dest}} is omitted, {{point1}} is modified and returned. Requires sdl2 egg 0.2.0 or higher. (point-sub point1 point2) → sdl2:point (point-sub! point1 point2 #!optional dest) → dest Efficiently subtract {{point2}} from {{point1}} (vector subtraction). The results will be clamped to the range -2147483648 to 2147483647. If the dx and dy values are already held as separate variables instead, it is more efficient and convenient to negate the values and use {{point-move}}, instead of creating an sdl2:point. * {{point-sub}} returns a new managed sdl2:point. * {{point-sub!}} modifies and returns {{dest}}. If {{dest}} is omitted, {{point1}} is modified and returned. Requires sdl2 egg 0.2.0 or higher. (point-lerp point1 point2 t) → sdl2:point (point-lerp! point1 point2 t #!optional dest) → dest Efficient linear interpolation (or extrapolation) between {{point1}} and {{point2}}. sdl2:point can only hold integer values, so the results will be truncated to integers. The results will be clamped to the range -2147483648 to 2147483647. {{t}} is the interpolation factor (a float). Values of {{t}} between 0 and 1 will interpolate between {{point1}} and {{point2}}. Values of {{t}} less that 0 will extrapolate beyond {{point1}} (moving away from {{point2}}). Values greater that 1 will extrapolate beyond {{point2}} (moving away from {{point1}}). * {{point-lerp}} returns a new managed sdl2:point. * {{point-lerp!}} modifies and returns {{dest}}. If {{dest}} is omitted, {{point1}} is modified and returned. Requires sdl2 egg 0.2.0 or higher. === Renderer Renderer is one part of [[https://wiki.libsdl.org/CategoryRender|2D Accelerated Rendering]]. See also [[#texture|Texture]]. Renderer support is available in sdl2 egg 0.2.0 and higher. ==== Renderer Functions (create-renderer! window #!optional index flags) → sdl2:renderer Create a new sdl2:renderer associated with the given window. See [[https://wiki.libsdl.org/SDL_CreateRenderer|SDL_CreateRenderer]]. * {{window}} must be a sdl2:window * {{index}} must be an integer specifying the index of the driver to initialize, or -1 to use the first driver supporting the requested flags. It defaults to -1. * {{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]]. It defaults to {{'()}}. Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires sdl2 egg 0.2.0 or higher. (create-software-renderer! surface) → sdl2:renderer Create a sdl2:renderer which renders onto the given sdl2:surface. See [[https://wiki.libsdl.org/SDL_CreateSoftwareRenderer|SDL_CreateSoftwareRenderer]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires sdl2 egg 0.2.0 or higher. (destroy-renderer! renderer) See [[https://wiki.libsdl.org/SDL_DestroyRenderer|SDL_DestroyRenderer]]. Requires sdl2 egg 0.2.0 or higher. (create-window-and-renderer! width height #!optional window-flags) → [window renderer] Create a sdl2:window and a sdl2:renderer that renders to the window. This is more convenient, but less flexible, than using {{create-window!}} and then {{create-renderer!}}. See [[https://wiki.libsdl.org/SDL_CreateWindowAndRenderer|SDL_CreateWindowAndRenderer]]. {{width}} and {{height}} must be inditegers specifying the height of the window and renderer to create. {{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). This procedure returns multiple values: ; window : The sdl2:window that was created. ; renderer : The sdl2:renderer that was created. Requires sdl2 egg 0.2.0 or higher. (get-renderer window) → sdl2:renderer Return the renderer associated with the given sdl2:window. See [[https://wiki.libsdl.org/SDL_GetRenderer|SDL_GetRenderer]]. '''Note:''' The returned renderer will be a new sdl2:renderer record pointing to the address of the existing renderer. It will be {{struct-eq?}} to other sdl2:renderer records for the same renderer, but not {{eq?}}. Signals an exception of kind {{(exn sdl2)}} if the window does not have a renderer, or if an error occurs. Requires sdl2 egg 0.2.0 or higher. (num-render-drivers) → integer See [[https://wiki.libsdl.org/SDL_GetNumRenderDrivers|SDL_GetNumRenderDrivers]]. Requires sdl2 egg 0.2.0 or higher. (render-driver-info index) → sdl2:renderer-info See [[https://wiki.libsdl.org/SDL_GetRenderDriverInfo|SDL_GetRenderDriverInfo]]. Requires sdl2 egg 0.2.0 or higher. (render-present! renderer) Update the renderer to show any changes that have occurred. See [[https://wiki.libsdl.org/SDL_RenderPresent|SDL_RenderPresent]]. Requires sdl2 egg 0.2.0 or higher. (render-copy! renderer texture #!optional srcrect dstrect) → Copy all or part of the given texture onto the renderer. See [[https://wiki.libsdl.org/SDL_RenderCopy|SDL_RenderCopy]]. * {{renderer}} is the sdl2:renderer to copy the texture to. * {{texture}} is the source sdl2:texture. * {{srcrect}} is a sdl2:rect specifying the part of the texture to copy, or {{#f}} to copy the whole texture. It defaults to {{#f}}. * {{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}}. Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires sdl2 egg 0.2.0 or higher. (render-copy-ex! renderer texture #!optional srcrect dstrect angle center flip) Copy all or part of the given texture onto the renderer, optionally rotating or flipping the texture. See [[https://wiki.libsdl.org/SDL_RenderCopyEx|SDL_RenderCopyEx]]. * {{renderer}} is the sdl2:renderer to copy the texture to. * {{texture}} is the source sdl2:texture. * {{srcrect}} is a sdl2:rect specifying the part of the texture to copy, or {{#f}} to copy the whole texture. It defaults to {{#f}}. * {{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}}. * {{angle}} is a float specifying the angle in degrees to rotate the texture. It defaults to 0. * {{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}}. * {{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: ** {{'horizontal}} = flip the texture horizontally ** {{'vertical}} = flip the texture vertically Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires sdl2 egg 0.2.0 or higher. (render-read-pixels-raw renderer rect format pixels-out pitch) Read the pixels from some or all of the given renderer. This is for advanced users, and must be used with caution. See [[https://wiki.libsdl.org/SDL_RenderReadPixels|SDL_RenderReadPixels]]. * {{renderer}} is the sdl2:renderer to read from. * {{rect}} is a sdl2:rect specifying the part of the renderer to read, or {{#f}} to read the entire renderer. * {{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. * {{pixels-out}} is a pointer or locative where the pixel data will be written. It must point to a block of memory large enough to hold all the requested pixel data, or your program may crash or other bad things happen. * {{pitch}} is an integer specifying the pitch of the pixel data. Requires sdl2 egg 0.2.0 or higher. (render-clear! renderer) Clear the entire renderer, using the renderer's current draw color. See [[https://wiki.libsdl.org/SDL_RenderClear|SDL_RenderClear]]. Requires sdl2 egg 0.2.0 or higher. (render-draw-line! renderer x1 y1 x2 y2) (render-draw-lines! renderer points) Draw a line segment or multiple line segments, using the renderer's current draw color and blend mode. See [[https://wiki.libsdl.org/SDL_RenderDrawLine|SDL_RenderDrawLine]] and [[https://wiki.libsdl.org/SDL_RenderDrawLines|SDL_RenderDrawLines]]. * {{render-draw-line!}} draws a single line segment. * {{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. Requires sdl2 egg 0.2.0 or higher. (render-draw-point! renderer x y) (render-draw-points! renderer points) Draw one or multiple points, using the renderer's current draw color and blend mode. See [[https://wiki.libsdl.org/SDL_RenderDrawPoint|SDL_RenderDrawPoint]] and [[https://wiki.libsdl.org/SDL_RenderDrawPoints|SDL_RenderDrawPoints]]. * {{render-draw-point!}} draws a single point. * {{render-draw-points!}} draws multiple points. {{points}} must be a list or vector of sdl2:point instances. Requires sdl2 egg 0.2.0 or higher. (render-draw-rect! renderer rect) (render-draw-rects! renderer rects) Draw one or multiple outlined rectangles, using the renderer's current draw color and blend mode. See [[https://wiki.libsdl.org/SDL_RenderDrawRect|SDL_RenderDrawRect]] and [[https://wiki.libsdl.org/SDL_RenderDrawRects|SDL_RenderDrawRects]]. * {{render-draw-rect!}} draws a single outlined rect. * {{render-draw-rects!}} draws multiple outlined rects. {{rects}} must be a list or vector of sdl2:rect instances. Requires sdl2 egg 0.2.0 or higher. (render-fill-rect! renderer rect) (render-fill-rects! renderer rects) Draw one or multiple filled rectangles, using the renderer's current draw color and blend mode. See [[https://wiki.libsdl.org/SDL_RenderFillRect|SDL_RenderFillRect]] and [[https://wiki.libsdl.org/SDL_RenderFillRects|SDL_RenderFillRects]]. * {{render-draw-rect!}} draws a single filled rect. * {{render-draw-rects!}} draws multiple filled rects. {{rects}} must be a list or vector of sdl2:rect instances. Requires sdl2 egg 0.2.0 or higher. ==== sdl2:renderer sdl2:renderer is a record type that wraps a pointer to an SDL_Renderer struct. sdl2:renderer is available in sdl2 egg 0.2.0 and higher. (renderer? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:renderer. Requires sdl2 egg 0.2.0 or higher. (render-draw-blend-mode renderer) → symbol or integer (render-draw-blend-mode-raw renderer) → integer (set! (render-draw-blend-mode renderer) mode) (render-draw-blend-mode-set! renderer mode) Get or set the renderer's draw blend mode. This affects future drawing operations. See [[https://wiki.libsdl.org/SDL_GetRenderDrawBlendMode|SDL_GetRenderDrawBlendMode]] and [[https://wiki.libsdl.org/SDL_SetRenderDrawBlendMode|SDL_SetRenderDrawBlendMode]]. * {{render-draw-blend-mode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-modes|blend mode symbol]] for built-in modes, or an integer for custom blend modes created with {{compose-custom-blend-mode}}. * {{render-draw-blend-mode-raw}} returns an integer. * The setters accept either a symbol or integer. Requires sdl2 egg 0.2.0 or higher. (render-draw-color renderer) → sdl2:color (render-draw-colour renderer) → sdl2:color (set! (render-draw-color renderer) color) (set! (render-draw-colour renderer) color) (render-draw-color-set! renderer color) (render-draw-colour-set! renderer color) Get or set the renderer's draw color. This affects future drawing operations. See [[https://wiki.libsdl.org/SDL_GetRenderDrawColor|SDL_GetRenderDrawColor]] and [[https://wiki.libsdl.org/SDL_SetRenderDrawColor|SDL_SetRenderDrawColor]]. Requires sdl2 egg 0.2.0 or higher. (render-clip-rect renderer) → sdl2:rect (set! (render-clip-rect renderer) rect) (render-clip-rect-set! renderer rect) Get or set the sdl2:renderer's clip rect. See [[https://wiki.libsdl.org/SDL_RenderGetClipRect|SDL_RenderGetClipRect]] and [[https://wiki.libsdl.org/SDL_RenderSetClipRect|SDL_RenderSetClipRect]]. {{render-clip-rect}} returns a new managed sdl2:rect describing the renderer's clip rect. If clipping is disabled, it returns {{#}}. But, be advised that it also returns {{#}} if that is the current clip rect. So, the meaning of {{#}} is ambiguous. Use {{render-clip-enabled?}} (in SDL 2.0.4 or higher) to unambiguously check whether clipping is enabled or disabled. The setters accept either an sdl2:rect to enable clipping and set the clip rect, or {{#f}} to disable clipping. Setting to {{#}} does not disable clipping. Requires sdl2 egg 0.2.0 or higher. (render-clip-enabled? renderer) → boolean Returns {{#t}} if clipping is enabled for the given sdl2:renderer, or {{#f}} is clipping is disabled. See [[https://wiki.libsdl.org/SDL_RenderIsClipEnabled|SDL_RenderIsClipEnabled]]. Requires SDL 2.0.4 or higher, and sdl2 egg 0.2.0 or higher. (render-integer-scale? renderer) → boolean (set! (render-integer-scale? renderer) boolean) (render-integer-scale-set! renderer boolean) See [[https://wiki.libsdl.org/SDL_RenderIntegerScale|SDL_RenderIntegerScale]]. Requires SDL 2.0.5 or higher, and sdl2 egg 0.4.0 or higher. (renderer-output-size renderer) → [w h] See [[https://wiki.libsdl.org/SDL_GetRendererOutputSize|SDL_GetRendererOutputSize]]. This procedure returns multiple values, the output width and height, as integers. Requires sdl2 egg 0.2.0 or higher. (render-logical-size renderer) → [w h] (set! (render-logical-size renderer) size) (render-logical-size-set! renderer size) Get or set the renderer's logical size. See [[https://wiki.libsdl.org/SDL_RenderGetLogicalSize|SDL_RenderGetLogicalSize]] and [[https://wiki.libsdl.org/SDL_RenderSetLogicalSize|SDL_RenderSetLogicalSize]]. * {{render-logical-size}} returns multiple values, the logical width and height, as integers. * The setters accept a list {{(w h)}} containing the new logical width and height, as integers. Requires sdl2 egg 0.2.0 or higher. (render-scale renderer) → [x-scale y-scale] (set! (render-scale-set! renderer) scales) (render-scale-set! renderer scales) Get or set the sdl2:renderer's x and y scaling factors. See [[https://wiki.libsdl.org/SDL_RenderGetScale|SDL_RenderGetScale]] and [[https://wiki.libsdl.org/SDL_RenderSetScale|SDL_RenderSetScale]]. * {{render-scale}} returns multiple values, the x and y scaling factors, as floats. * The setters accept a list {{(x-scale y-scale)}} containing the new scaling factors, as floats. Requires sdl2 egg 0.2.0 or higher. (render-target-supported? renderer) → boolean Returns {{#t}} if the given renderer can have a render target. See [[https://wiki.libsdl.org/SDL_RenderTargetSupported|SDL_RenderTargetSupported]]. Requires sdl2 egg 0.2.0 or higher. (render-target renderer) → sdl2:texture or #f (set! (render-target renderer) target) (render-target-set! renderer target) Get or set the renderer's render target, i.e. the texture that the renderer will render onto. See [[https://wiki.libsdl.org/SDL_GetRenderTarget|SDL_GetRenderTarget]] and [[https://wiki.libsdl.org/SDL_SetRenderTarget|SDL_SetRenderTarget]]. {{render-target}} returns {{#f}} if the renderer has no render target. The setters signal an exception of kind {{(exn sdl2)}} on failure, for example if the renderer does not support a render target. You should use {{render-target-supported?}} to test whether the renderer supports a render target. Requires sdl2 egg 0.2.0 or higher. (render-viewport renderer) → sdl2:rect (set! (render-viewport renderer) rect) (render-viewport-set! renderer rect) Get or set the renderer's viewport. See [[https://wiki.libsdl.org/SDL_RenderGetViewport|SDL_RenderGetViewport]] and [[https://wiki.libsdl.org/SDL_RenderSetViewport|SDL_RenderSetViewport]]. Requires sdl2 egg 0.2.0 or higher. ==== sdl2:renderer-info sdl2:renderer-info is a record type that wraps a pointer to an [[https://wiki.libsdl.org/SDL_RendererInfo|SDL_RendererInfo]] struct. sdl2:renderer-info is available in sdl2 egg 0.2.0 and higher. (renderer-info? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:renderer-info. Requires sdl2 egg 0.2.0 or higher. (get-renderer-info renderer) → sdl2:renderer-info (get-renderer-info* renderer) → sdl2:renderer-info Return a sdl2:renderer-info with information about the given sdl2:renderer. See [[https://wiki.libsdl.org/SDL_GetRendererInfo|SDL_GetRendererInfo]]. * {{get-renderer-info}} returns a memory-managed sdl2:renderer-info. * {{get-renderer-info*}} returns an unmanaged sdl2:renderer-info, which should be freed using {{free-renderer-info!}} when you are done with it. Requires sdl2 egg 0.2.0 or higher. (free-renderer-info! renderer-info) Free the memory of the sdl2:renderer-info's underlying struct. {{renderer-info}}'s pointer will be set to null (see {{struct-null?}}). It is safe to call this procedure with managed or unmanaged sdl2:renderer-infos. It is safe (but has no effect) to free a struct record multiple times. Requires sdl2 egg 0.2.0 or higher. (renderer-info-name renderer-info) → string Get the sdl2:renderer-info's "name" field, as a string. Requires sdl2 egg 0.2.0 or higher. (renderer-info-flags renderer-info) → list of symbols (renderer-info-flags-raw renderer-info) → integer Get the sdl2:renderer-info's "flags" field. * {{render-info-flags}} returns a list of [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#renderer-flags|renderer flag symbols]]. * {{render-info-flags-raw}} returns an integer bitfield. Requires sdl2 egg 0.2.0 or higher. (renderer-info-num-texture-formats renderer-info) → integer Get the sdl2:renderer-info's "num-texture-formats" field, as an integer. Requires sdl2 egg 0.2.0 or higher. (renderer-info-texture-formats renderer-info) → list of symbols (renderer-info-texture-formats-raw renderer-info) → list of integers Get the sdl2:renderer-info's "texture-formats" field. * {{renderer-info-texture-formats}} returns a list of [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbols]]. * {{renderer-info-texture-formats-raw}} returns a list of the equivalent integer constants. Requires sdl2 egg 0.2.0 or higher. Before sdl2 egg 0.4.0, this procedure returned a pointer to a C array. (renderer-info-max-texture-width renderer-info) → integer Get the sdl2:renderer-info's "max-texture-width" field, as an integer. Requires sdl2 egg 0.2.0 or higher. (renderer-info-max-texture-height renderer-info) → integer Get the sdl2:renderer-info's "max-texture-height" field, as an integer. Requires sdl2 egg 0.2.0 or higher. === RWops ==== RWops Functions (rw-from-file filepath) → sdl2:rwops See [[https://wiki.libsdl.org/SDL_RWFromFile|SDL_RWFromFile]]. You should close the sdl2:rwops when you are done with it, using {{rw-close!}} or one of the procedures that can automatically close the sdl2:rwops, such as {{load-bmp-rw}}. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (rw-from-const-mem pointer) → sdl2:rwops See [[https://wiki.libsdl.org/SDL_RWFromConstMem|SDL_RWFromConstMem]]. You should close the sdl2:rwops when you are done with it, using {{rw-close!}} or one of the procedures that can automatically close the sdl2:rwops, such as {{load-bmp-rw}}. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (rw-from-mem pointer) → sdl2:rwops See [[https://wiki.libsdl.org/SDL_RWFromMem|SDL_RWFromMem]]. You should close the sdl2:rwops when you are done with it, using {{rw-close!}} or one of the procedures that can automatically close the sdl2:rwops, such as {{load-bmp-rw}}. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (rw-from-blob blob) → sdl2:rwops Create a new sdl2:rwops that accesses the memory of the given [[/manual/Module (chicken blob)|blob]]. You should close the sdl2:rwops when you are done with it, using {{rw-close!}} or one of the procedures that can automatically close the sdl2:rwops, such as {{load-bmp-rw}}. Signals an exception of kind {{(exn sdl2)}} if an error occurs. You can also use this procedure to create a sdl2:rwops from a [[/manual/Module srfi-4|SRFI-4]] numeric vector, by first converting it to a blob using e.g. {{u8vector->blob/shared}}. '''Caution:''' Creating a sdl2:rwops from a blob in CHICKEN-managed memory is unstable: the blob might be garbage collected or moved in memory, which would break the sdl2:rwops. To be safe, you should [[/egg/object-evict|{{object-evict}}]] the blob and create the sdl2:rwops from the evicted blob (not the original). You may wish to [[/egg/object-evict#object-release|{{object-release}}]] the evicted blob after you have closed the sdl2:rwops. Example: (let* ((evicted-blob (object-evict '#${...})) (rwops (sdl2:rw-from-blob evicted-blob)) (surf (sdl2:load-bmp-rw rwops #t))) (object-release evicted-blob) surf) (rw-from-string str) → sdl2:rwops Create a new sdl2:rwops that accesses the memory of the given CHICKEN Scheme string. You should close the sdl2:rwops when you are done with it, using {{rw-close!}} or one of the procedures that can automatically close the sdl2:rwops, such as {{load-bmp-rw}}. Signals an exception of kind {{(exn sdl2)}} if an error occurs. '''Caution:''' Creating a sdl2:rwops from a string in CHICKEN-managed memory is unstable: the string might be garbage collected or moved in memory, which would break the sdl2:rwops. To be safe, you should [[/egg/object-evict|{{object-evict}}]] the string and create the sdl2:rwops from the evicted string (not the original). You may wish to [[/egg/object-evict#object-release|{{object-release}}]] the evicted string after you have closed the sdl2:rwops. Example: (let* ((evicted-string (object-evict "...")) (rwops (sdl2:rw-from-string evicted-string)) (surf (sdl2:load-bmp-rw rwops #t))) (object-release evicted-string) surf) (rw-close! rwops) See [[https://wiki.libsdl.org/SDL_RWclose|SDL_RWclose]]. Close and clean up the given sdl2:rwops. This frees the memory used by the SDL_RWops struct itself, but does not free or release the pointer, blob, or string that the sdl2:rwops was reading/writing from. (It does close files opened with {{rw-from-file}}, though.) Signals an exception of kind {{(exn sdl2)}} if an error occurs. ==== sdl2:rwops sdl2:rwops is a record type that wraps a pointer to an [[https://wiki.libsdl.org/SDL_RWops|SDL_RWops]] struct. (rwops? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:rwops. (rwops-type rwops) → symbol (rwops-type-raw rwops) → integer Get the sdl2:rwops' "type" field, indicating the data source type. * {{rwops-type}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#rwops-types|RWops type symbol]]. * {{rwops-type-raw}} returns an integer. === Surface ==== Surface Functions (create-rgb-surface* flags width height depth rmask gmask bmask amask) → sdl2:surface Returns a new unmanaged sdl2:surface with the given properties. See [[https://wiki.libsdl.org/SDL_CreateRGBSurface|SDL_CreateRGBSurface]]. See {{make-surface}} for a more convenient interface. Signals an exception of kind {{(exn sdl2)}} if the surface cannot be created. (create-rgb-surface-from* pixels width height depth pitch rmask gmask bmask amask) → sdl2:surface Returns a new unmanaged sdl2:surface with the given properties, using existing pixel data (a pointer, e.g. from {{surface-pixels-raw}}). See [[https://wiki.libsdl.org/SDL_CreateRGBSurfaceFrom|SDL_CreateRGBSurfaceFrom]]. Signals an exception of kind {{(exn sdl2)}} if the surface cannot be created. (create-rgb-surface-with-format* flags width height depth format) → sdl2:surface Returns a new unmanaged sdl2:surface with the given properties. See [[https://wiki.libsdl.org/SDL_CreateRGBSurfaceWithFormat|SDL_CreateRGBSurfaceWithFormat]]. See {{make-surface}} for a more convenient interface. * {{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. Requires SDL 2.0.5 or higher, and sdl2 egg 0.4.0 or higher. (create-rgb-surface-with-format-from* pixels width height depth pitch format) → sdl2:surface Returns a new unmanaged sdl2:surface with the given properties, using existing pixel data (a pointer, e.g. from {{surface-pixels-raw}}). See [[https://wiki.libsdl.org/SDL_CreateRGBSurfaceWithFormatFrom|SDL_CreateRGBSurfaceWithFormatFrom]]. * {{pixels}} must be a pointer or locative to pixel data in the correct format. * {{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. Requires SDL 2.0.5 or higher, and sdl2 egg 0.4.0 or higher. (convert-surface surface pixel-format) → sdl2:surface (convert-surface* surface pixel-format) → sdl2:surface Creates a copy of the given sdl2:surface, but converts it to the given sdl2:pixel-format. See [[https://wiki.libsdl.org/SDL_ConvertSurface|SDL_ConvertSurface]]. * {{convert-surface}} returns a memory-managed sdl2:surface. * {{convert-surface*}} returns an unmanaged sdl2:surface, which should be freed with {{free-surface!}} when you are done with it. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (duplicate-surface surface) → sdl2:surface (duplicate-surface* surface) → sdl2:surface Returns a new surface with the same data and format as the given surface. * {{duplicate-surface}} returns a memory-managed sdl2:surface. * {{duplicate-surface*}} returns an unmanaged sdl2:surface, which should be freed with {{free-surface!}} when you are done with it. With SDL 2.0.6, this uses [[https://wiki.libsdl.org/SDL_DuplicateSurface|SDL_DuplicateSurface]]. With earlier SDL versions, it uses [[https://wiki.libsdl.org/SDL_ConvertSurface|SDL_ConvertSurface]]. Requires sdl2 egg version 0.4.0 or higher. (load-bmp filepath) → sdl2:surface (load-bmp* filepath) → sdl2:surface Attempts to load a BMP image file. Returns a sdl2:surface containing the image data. See [[https://wiki.libsdl.org/SDL_LoadBMP|SDL_LoadBMP]]. '''Note:''' This procedure only supports certain kinds of BMP image. Use the [[/egg/sdl2-image|sdl2-image egg]] for better BMP support, plus support for loading other image formats like JPG, PNG, and GIF. * {{load-bmp}} returns a memory-managed sdl2:surface. * {{load-bmp*}} returns an unmanaged sdl2:surface, which should be freed with {{free-surface!}} when you are done with it. Signals an exception of kind {{(exn sdl2)}} if the image could not be loaded. (load-bmp-rw rwops #!optional close?) → sdl2:surface (load-bmp-rw* rwops #!optional close?) → sdl2:surface Attempts to load a BMP image from the given sdl2:rwops. Returns a sdl2:surface containing the image data. See [[https://wiki.libsdl.org/SDL_LoadBMP_RW|SDL_LoadBMP_RW]]. If {{close?}} is {{#t}}, {{rwops}} will be automatically closed (see {{rw-close!}}) after the image is loaded. If {{close?}} is {{#f}} or omitted, {{rwops}} will not be closed. '''Note:''' This procedure only supports certain kinds of BMP image. Use the [[/egg/sdl2-image|sdl2-image egg]] for better BMP support, plus support for loading other image formats like JPG, PNG, and GIF. * {{load-bmp-rw}} returns a memory-managed sdl2:surface. * {{load-bmp-rw*}} returns an unmanaged sdl2:surface, which should be freed with {{free-surface!}} when you are done with it. Signals an exception of kind {{(exn sdl2)}} if the image could not be loaded. (save-bmp! surface filepath) See [[https://wiki.libsdl.org/SDL_SaveBMP|SDL_SaveBMP]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (save-bmp-rw! surface rwops #!optional close?) See [[https://wiki.libsdl.org/SDL_SaveBMP_RW|SDL_SaveBMP_RW]]. If {{close?}} is {{#t}}, {{rwops}} will be automatically closed (see {{rw-close!}}) after the image is loaded. If {{close?}} is {{#f}} or omitted, {{rwops}} will not be closed. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (lock-surface! surface) (unlock-surface! surface) See [[https://wiki.libsdl.org/SDL_LockSurface|SDL_LockSurface]] and [[https://wiki.libsdl.org/SDL_UnlockSurface|SDL_UnlockSurface]]. {{lock-surface!}} signals an exception of kind {{(exn sdl2)}} if an error occurs. (must-lock? surface) → boolean See [[https://wiki.libsdl.org/SDL_MUSTLOCK|SDL_MUSTLOCK]]. (blit-surface! src src-rect dst dst-rect) Blit (copy) image data from the {{src}} (source) sdl2:surface to the {{dst}} (destination) sdl2:surface. See [[https://wiki.libsdl.org/SDL_BlitSurface|SDL_BlitSurface]]. * {{src-rect}} may be an sdl2:rect to blit part of {{src}}, or {{#f}} to blit all of {{src}}. * {{dst-rect}} may be an sdl2:rect to specify where in {{dst}} the image data should be blitted, or {{#f}} to blit at the top-left corner of {{dst}}. Only the x and y parts of the {{dst-rect}} are used; width and height are ignored. If {{dst-rect}} is a sdl2:rect, it will be modified to save the final blit rectangle after all clipping is performed. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (blit-scaled! src src-rect dest dest-rect) Blit (copy) image data from the {{src}} (source) sdl2:surface to the {{dst}} (destination) sdl2:surface, scaling the image if needed. See [[https://wiki.libsdl.org/SDL_BlitScaled|SDL_BlitScaled]]. * {{src-rect}} may be an sdl2:rect to blit part of {{src}}, or {{#f}} to blit all of {{src}}. * {{dst-rect}} may be an sdl2:rect to specify where in {{dst}} the image data should be blitted, or {{#f}} to copy into the entire {{dst}} surface. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (fill-rect! surface rect color) See [[https://wiki.libsdl.org/SDL_FillRect|SDL_FillRect]]. * {{rect}} may be an sdl2:rect to fill part of the surface, or {{#f}} to fill the entire surface. * {{color}} may be an sdl2:color or a mapped color (an integer, like returned by {{map-rgba}}). Signals an exception of kind {{(exn sdl2)}} if an error occurs. (fill-rects! surface rects color) See [[https://wiki.libsdl.org/SDL_FillRects|SDL_FillRects]]. * {{rects}} must be a list of sdl2:rects. * {{color}} may be an sdl2:color or a mapped color (an integer, like returned by {{map-rgba}}). Signals an exception of kind {{(exn sdl2)}} if an error occurs. (surface-ref surface x y) → sdl2:color (surface-ref-raw surface x y) → integer (set! (surface-ref surface x y) color) (surface-set! surface x y color) Get or set the color of the specified pixel on the surface. * {{surface-ref}} returns an sdl2:color. * {{surface-ref-raw}} returns a mapped color (an integer). You can use {{get-rgba}} to convert the mapped color to color fields. * The setters accept either an sdl2:color or a mapped color. These procedures automatically lock and unlock the surface if needed. They signal an exception of kind {{(exn sdl2)}} if the surface cannot be locked. These procedures signal an exception of kind {{(exn bounds)}} if {{x}} or {{y}} is out of bounds. The setters ignore the surface's clip rect. (rotate-surface-90 surface turns) → sdl2:surface (rotate-surface-90* surface turns) → sdl2:surface Return a copy of the given surface rotated by the given number of 90° clockwise turns. {{turns}} must be an integer. For example: * {{turns}} 0 means no rotation * {{turns}} 1 means 90° clockwise rotation * {{turns}} 2 means 180° rotation * {{turns}} 3 (or -1) means 270° clockwise (i.e. 90° counter-clockwise) rotation The new surface will have an equivalent pixel format, color key, blend mode, alpha mod, and color mod as the given surface. If the given surface has a palette, the new surface will share the same palette. The new surface will have no clip rect. * {{rotate-surface-90}} returns a memory-managed sdl2:surface. * {{rotate-surface-90*}} returns an unmanaged sdl2:surface, which should be freed with {{free-surface!}} when you are done with it. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (flip-surface surface flip-x? flip-y?) → sdl2:surface (flip-surface* surface flip-x? flip-y?) → sdl2:surface Return a copy of the given surface flipped on the X (horizontal) and/or Y (vertical) axes. The new surface will have an equivalent pixel format, color key, blend mode, alpha mod, and color mod as the given surface. If the given surface has a palette, the new surface will share the same palette. The new surface will have no clip rect. * {{flip-surface}} returns a memory-managed sdl2:surface. * {{flip-surface*}} returns an unmanaged sdl2:surface, which should be freed with {{free-surface!}} when you are done with it. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (compose-custom-blend-mode src-color-factor dst-color-factor color-operation src-alpha-factor dst-alpha-factor alpha-operation) → integer See [[https://wiki.libsdl.org/SDL_ComposeCustomBlendMode|SDL_ComposeCustomBlendMode]]. * {{src-color-factor}}, {{dst-color-factor}}, {{src-alpha-factor}}, {{dst-alpha-factor}} must be [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-factors|blend factor symbols]] or equivalent integers. * {{color-operation}} and {{alpha-operation}} must be [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-operations|blend operation symbols]] or equivalent integers. Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher. (get-yuv-conversion-mode) → symbol (get-yuv-conversion-mode-raw) → integer (set! (get-yuv-conversion-mode) mode) (yuv-conversion-mode-set! mode) See [[https://wiki.libsdl.org/SDL_GetYUVConversionMode|SDL_GetYUVConversionMode]] and [[https://wiki.libsdl.org/SDL_SetYUVConversionMode|SDL_SetYUVConversionMode]]. * {{get-yuv-conversion-mode}} returns a a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#yuv-conversion-modes|YUV conversion mode symbol]]. * {{get-yuv-conversion-mode-raw}} returns an integer constant. * The setters accept either a YUV conversion mode symbol or equivalent integer constant. Requires SDL 2.0.8 or higher, and sdl2 egg 0.4.0 or higher. ==== sdl2:surface sdl2:surface is a record type that wraps a pointer to an [[https://wiki.libsdl.org/SDL_Surface|SDL_Surface]] struct. (surface? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:surface. (make-surface width height depth/format) → sdl2:surface (make-surface* width height depth/format) → sdl2:surface Create a new sdl2:surface with the given width, height, and color depth (bits per pixel) or pixel format. This is a more convenient interface for {{create-rgb-surface*}}. If {{depth/format}} is an integer 64 or less, a surface of that color depth is created. The sdl2:surface's pixel format and masks will be chosen automatically based on the requested depth and the current platform's byte order (little endian or big endian). If {{depth/format}} is a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format enum symbol]] or equivalent integer, a surface of that pixel format is created. * {{make-surface}} returns a memory-managed sdl2:surface. * {{make-surface*}} returns an unmanaged sdl2:surface, which should be freed with {{free-surface!}} when you are done with it. These procedures signal an exception of kind {{(exn sdl2)}} if the sdl2:surface could not be created (e.g. because the color depth is unsupported). (free-surface! surface) Free the memory of the sdl2:surface's underlying struct. {{surface}}'s pointer will be set to null (see {{struct-null?}}). It is safe to call this procedure with managed or unmanaged sdl2:surfaces. It is safe (but has no effect) to free a struct record multiple times. See [[https://wiki.libsdl.org/SDL_FreeSurface|SDL_FreeSurface]]. '''Note:''' if {{surface}} was created using {{create-rgb-surface-from}}, then the pixel data is not freed. (surface-format surface) → sdl2:pixel-format Get the sdl2:surface's "format" field, as a sdl2:pixel-format describing the format of the surface's pixels. (surface-w surface) → integer Get the sdl2:surface's "w" field, as a nonnegative integer indicating the surface's width in pixels. (surface-h surface) → integer Get the sdl2:surface's "h" field, as a nonnegative integer indicating the surface's height in pixels. (surface-pitch surface) → integer Get the sdl2:surface's "pitch" field, as a nonnegative integer indicating how many bytes are used to represent one row of pixel data. (surface-pixels-raw surface) → pointer or #f Get the sdl2:surface's "pixels" field, as a raw pointer to the sdl2:surface's pixels. Don't use this unless you really know what you are doing! If you want to get or set a pixel, use {{surface-ref}} and {{surface-set!}} instead. They are much safer, more convenient, and more efficient than accessing the pixel data using this pointer. (surface-userdata-raw surface) → pointer or #f (set! (surface-userdata-raw surface) val) (surface-userdata-raw-set! surface val) Get or set the sdl2:surface's "userdata" field, as a pointer or {{#f}}. If you want to store a pointer to a Scheme object here, be sure to [[/egg/object-evict|evict the object]] first. Otherwise the object's location in memory might change, rendering the pointer invalid. (surface-refcount surface) → integer (set! (surface-refcount surface) val) (surface-refcount-set! surface val) Get or set the sdl2:surface's "refcount" field, as an integer. (surface-clip-rect surface) → sdl2:rect (set! (surface-clip-rect surface) rect) → boolean (surface-clip-rect-set! surface rect) → boolean {{surface-clip-rect}} returns a copy of the surface's clip rect. See [[https://wiki.libsdl.org/SDL_GetClipRect|SDL_GetClipRect]]. The setters sets the surface's clip rect to a copy of the given rect. {{rect}} may be {{#f}}, which disables clipping. See [[https://wiki.libsdl.org/SDL_SetClipRect|SDL_SetClipRect]]. The 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). (surface-color-key? surface) → boolean (surface-colour-key? surface) → boolean Returns {{#t}} if surface has a color key. With SDL 2.0.9 and higher, this uses [[https://wiki.libsdl.org/SDL_HasColorKey|SDL_HasColorKey]]. With earlier SDL versions, this uses [[https://wiki.libsdl.org/SDL_GetColorKey|SDL_GetColorKey]]. Requires sdl2 egg 0.4.0 or higher. (surface-color-key surface) → sdl2:color or #f (surface-colour-key surface) → sdl2:color or #f (surface-color-key-raw surface) → integer or #f (surface-colour-key-raw surface) → integer or #f (set! (surface-color-key surface) color) (set! (surface-colour-key surface) color) (surface-color-key-set! surface color) (surface-colour-key-set! surface color) Get or set the sdl2:surface's color key. See [[https://wiki.libsdl.org/SDL_GetColorKey|SDL_GetColorKey]] and [[https://wiki.libsdl.org/SDL_SetColorKey|SDL_SetColorKey]]. * {{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. * {{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. * The setters accept either an sdl2:color, a mapped color (an integer), or {{#f}} to disable color keying. These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs. (surface-alpha-mod surface) → integer (set! (surface-alpha-mod surface) mod) (surface-alpha-mod-set! surface mod) See [[https://wiki.libsdl.org/SDL_GetSurfaceAlphaMod|SDL_GetSurfaceAlphaMod]] and [[https://wiki.libsdl.org/SDL_SetSurfaceAlphaMod|SDL_SetSurfaceAlphaMod]]. These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs. (surface-blend-mode surface) → symbol (surface-blend-mode-raw surface) → integer (set! (surface-blend-mode surface) mode) (surface-blend-mode-set! surface mode) See [[https://wiki.libsdl.org/SDL_GetSurfaceBlendMode|SDL_GetSurfaceBlendMode]] and [[https://wiki.libsdl.org/SDL_SetSurfaceBlendMode|SDL_SetSurfaceBlendMode]]. * {{surface-blend-mode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-modes|blend mode symbol]] for built-in modes, or an integer for custom blend modes created with {{compose-custom-blend-mode}}. * {{surface-blend-mode-raw}} returns an integer. * The setters accept either a symbol or integer. These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs. (surface-color-mod surface) → [r g b] (surface-colour-mod surface) → [r g b] (set! (surface-color-mod surface) rgb) (set! (surface-colour-mod surface) rgb) (surface-color-mod-set! surface rgb) (surface-colour-mod-set! surface rgb) See [[https://wiki.libsdl.org/SDL_GetSurfaceColorMod|SDL_GetSurfaceColorMod]] and [[https://wiki.libsdl.org/SDL_SetSurfaceColorMod|SDL_SetSurfaceColorMod]]. {{surface-color-mod}} and {{surface-colour-mod}} return multiple values. The setters accept either a list {{(r g b)}} of color values, or an sdl2:color (the sdl2:color's "a" field will be ignored). These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs. (surface-palette surface) → sdl2:palette or #f (set! (surface-palette surface) palette) (surface-palette-set! surface palette) {{surface-palette}} returns the surface's palette, or {{#f}} if it has no palette. It is equivalent to {{(compose pixel-format-palette surface-format)}}. The setters signal an exception of kind {{(exn sdl2)}} if an error occurs. See [[https://wiki.libsdl.org/SDL_SetSurfacePalette|SDL_SetSurfacePalette]]. (surface-rle? surface) → bool (set! (surface-rle? surface) bool) (surface-rle-set! surface bool) See [[https://wiki.libsdl.org/SDL_HasSurfaceRLE|SDL_HasSurfaceRLE]] and [[https://wiki.libsdl.org/SDL_SetSurfaceRLE|SDL_SetSurfaceRLE]]. The setter signals an exception of kind {{(exn sdl2)}} if an error occurs. {{surface-rle?}} requires SDL 2.0.14 or higher, and sdl2 egg 0.4.0 or higher. === Texture Texture is one part of [[https://wiki.libsdl.org/CategoryRender|2D Accelerated Rendering]]. See also [[#renderer|Renderer]]. Renderer support is available in sdl2 egg 0.2.0 and higher. ==== sdl2:texture sdl2:texture is a record type that wraps a pointer to an [[https://wiki.libsdl.org/SDL_Texture|SDL_Texture]] struct. Textures are available in sdl2 egg 0.2.0 and higher. (texture? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:texture. Requires sdl2 egg 0.2.0 or higher. (create-texture renderer format access w h) → sdl2:texture (create-texture* renderer format access w h) → sdl2:texture Create a new sdl2:texture using the given sdl2:renderer and settings. * {{renderer}} must be a sdl2:renderer. * {{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. * {{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. * {{w}} must be an integer, specifying the texture's width in pixels. * {{h}} must be an integer, specifying the texture's height in pixels. These procedures signal an exception of kind {{(exn sdl2)}} if the sdl2:texture could not be created. * {{create-texture}} returns a memory-managed sdl2:texture. * {{create-texture*}} returns an unmanaged sdl2:texture, which should be destroyed with {{destroy-texture!}} when you are done with it. Requires sdl2 egg 0.2.0 or higher. (create-texture-from-surface renderer surface) → sdl2:texture (create-texture-from-surface* renderer surface) → sdl2:texture Create a new sdl2:texture from a sdl2:surface. The texture will contain a copy of the pixel data from the surface. The texture will have the same color mod and alpha mod as the surface. If the surface had a color key, the texture will have {{'blend}} blend mode; otherwise it will have the same blend mode as the surface. * {{create-texture-from-surface}} returns a memory-managed sdl2:texture. * {{create-texture-from-surface*}} returns an unmanaged sdl2:texture, which should be destroyed with {{destroy-texture!}} when you are done with it. These procedures signal an exception of kind {{(exn sdl2)}} if the sdl2:texture could not be created. Requires sdl2 egg 0.2.0 or higher. (destroy-texture! texture) Destroy the sdl2:texture, freeing its underlying struct. {{texture}}'s pointer will be set to null (see {{struct-null?}}). It is safe to call tihs procedure with managed on unmanaged sdl2:textures. It is safe (but has no effect) to destroy an sdl2:texture multiple times. See [[https://wiki.libsdl.org/SDL_DestroyTexture|SDL_DestroyTexture]]. Requires sdl2 egg 0.2.0 or higher. (query-texture texture) → [format access w h] (query-texture-raw texture) → [format-int access-int w h] Get multiple pieces of information about the texture. See [[https://wiki.libsdl.org/SDL_QueryTexture|SDL_QueryTexture]]. {{query-texture}} returns multiple values: ; 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]] ; 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]] ; w : The sdl2:texture's width, as a nonnegative integer measured in pixels ; h : The sdl2:texture's height, as a nonnegative integer measured in pixels {{query-texture-raw}} is similar, except it returns raw integer values (not symbols) for format and access. If you only want one of these pieces of information, it is more convenient and efficient to use one of these procedures instead: * {{texture-format}} * {{texture-access}} * {{texture-w}} * {{texture-h}} Requires sdl2 egg 0.2.0 or higher. (texture-format texture) → symbol Get the sdl2:texture's pixel format, as a pixel format enum symbol. This is equivalent to {{(nth-value 0 (query-texture texture))}}, but more convenient and efficient. Requires sdl2 egg 0.2.0 or higher. (texture-access texture) → symbol Get the sdl2:texture's access mode, as a texture access enum symbol. This is equivalent to {{(nth-value 1 (query-texture texture))}}, but more convenient and efficient. Requires sdl2 egg 0.2.0 or higher. (texture-w texture) → integer Get the sdl2:texture's width, as a nonnegative integer measured in pixels. This is equivalent to {{(nth-value 2 (query-texture texture))}}, but more convenient and efficient. Requires sdl2 egg 0.2.0 or higher. (texture-h texture) → integer Get the sdl2:texture's height, as a nonnegative integer measured in pixels. This is equivalent to {{(nth-value 3 (query-texture texture))}}, but more convenient and efficient. Requires sdl2 egg 0.2.0 or higher. (texture-alpha-mod texture) → integer (set! (texture-alpha-mod texture) mod) (texture-alpha-mod-set! texture mod) See [[https://wiki.libsdl.org/SDL_GetTextureAlphaMod|SDL_GetTextureAlphaMod]] and [[https://wiki.libsdl.org/SDL_SetTextureAlphaMod|SDL_SetTextureAlphaMod]]. These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs. Requires sdl2 egg 0.2.0 or higher. (texture-blend-mode texture) → symbol or integer (texture-blend-mode-raw texture) → integer (set! (texture-blend-mode texture) mode) (texture-blend-mode-set! texture mode) See [[https://wiki.libsdl.org/SDL_GetTextureBlendMode|SDL_GetTextureBlendMode]] and [[https://wiki.libsdl.org/SDL_SetTextureBlendMode|SDL_SetTextureBlendMode]]. * {{texture-blend-mode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-modes|blend mode symbol]] for built-in modes, or an integer for custom blend modes created with {{compose-custom-blend-mode}}. * {{texture-blend-mode-raw}} returns an integer. * The setters accept either a symbol or integer. These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs. Requires sdl2 egg 0.2.0 or higher. (texture-color-mod texture) → [r g b] (texture-colour-mod texture) → [r g b] (set! (texture-color-mod texture) rgb) (set! (texture-colour-mod texture) rgb) (texture-color-mod-set! texture rgb) (texture-colour-mod-set! texture rgb) See [[https://wiki.libsdl.org/SDL_GetTextureColorMod|SDL_GetTextureColorMod]] and [[https://wiki.libsdl.org/SDL_SetTextureColorMod|SDL_SetTextureColorMod]]. {{texture-color-mod}} and {{texture-colour-mod}} return multiple values. The setters accept either a list {{(r g b)}} of color values, or an sdl2:color (the sdl2:color's "a" field will be ignored). These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs. Requires sdl2 egg 0.2.0 or higher. (lock-texture-raw! texture rect) → [pixels pitch] Lock the texture so that its pixel data can be overwritten. This is for advanced users, and must be used with caution. See [[https://wiki.libsdl.org/SDL_LockTexture|SDL_LockTexture]]. See also {{unlock-texture!}}. * {{texture}} is the sdl2:texture that you wish to modify * {{rect}} is either an sdl2:rect (to lock part of the texture), or {{#f}} (to lock all of the texture). This procedure returns multiple values: ; pixels : A raw pointer that you can write pixel data to. Does not necessarily contain the old data. ; pitch : An integer indicating the pitch of the pixel data Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires sdl2 egg 0.2.0 or higher. (unlock-texture! texture) Unlock the texture, applying the new pixel data to the texture. This is for advanced users, and must be used with caution. See [[https://wiki.libsdl.org/SDL_UnlockTexture|SDL_UnlockTexture]]. See also {{lock-texture-raw!}}. Requires sdl2 egg 0.2.0 or higher. (update-texture-raw! texture rect pixels pitch) Overwrite part or all of the texture's pixel data. This is for advanced users, and must be used with caution. See [[https://wiki.libsdl.org/SDL_UpdateTexture|SDL_UpdateTexture]]. * {{texture}} is the sdl2:texture that you wish to update * {{rect}} is either an sdl2:rect (to update part of the texture), or {{#f}} (to update all of the texture) * {{pixels}} is a pointer or locative to raw pixel data * {{pitch}} is an integer describing the pitch of the pixel data Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires sdl2 egg 0.2.0 or higher. (update-yuv-texture-raw! texture rect y-plane y-pitch u-plane u-pitch v-plane v-pitch) Overwrite part or all of a YV12- or IYUV-formatted texture's pixel data. This is for advanced users, and must be used with caution. See [[https://wiki.libsdl.org/SDL_UpdateYUVTexture|SDL_UpdateYUVTexture]]. * {{texture}} is the sdl2:texture that you wish to update * {{rect}} is either an sdl2:rect (to update part of the texture), or {{#f}} (to update all of the texture) * {{y-plane}} is a pointer or locative to raw pixel data for the Y plane * {{y-pitch}} is an integer describing the pitch of the Y pixel data * {{u-plane}} is a pointer or locative to raw pixel data for the U plane * {{u-pitch}} is an integer describing the pitch of the U pixel data * {{v-plane}} is a pointer or locative to raw pixel data for the V plane * {{v-pitch}} is an integer describing the pitch of the V pixel data Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires SDL 2.0.1 or higher, and sdl2 egg 0.2.0 or higher. === Timer (delay! milliseconds) See [[https://wiki.libsdl.org/SDL_Delay|SDL_Delay]]. '''Caution:''' This procedure is not compatible with [[/egg/srfi-18|SRFI-18]] threads. It will cause '''all threads to sleep''' for the given duration. If you are using multiple threads, you should instead call SRFI-18's {{thread-sleep!}}, which will cause only the current thread to sleep. For example, call {{(thread-sleep! 0.025)}} instead of {{(delay! 25)}}. (get-ticks) → integer See [[https://wiki.libsdl.org/SDL_GetTicks|SDL_GetTicks]]. (get-performance-counter) → integer See [[https://wiki.libsdl.org/SDL_GetPerformanceCounter|SDL_GetPerformanceCounter]]. (get-performance-frequency) → integer See [[https://wiki.libsdl.org/SDL_GetPerformanceFrequency|SDL_GetPerformanceFrequency]]. === Touch / Gesture ==== Touch / Gesture Functions (get-num-touch-devices) → integer See [[https://wiki.libsdl.org/SDL_GetNumTouchDevices|SDL_GetNumTouchDevices]]. (get-touch-device device-id) → integer See [[https://wiki.libsdl.org/SDL_GetTouchDevice|SDL_GetTouchDevice]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (get-touch-device-type touch-id) → symbol (get-touch-device-type-raw touch-id) → integer See [[https://wiki.libsdl.org/SDL_GetTouchDeviceType|SDL_GetTouchDeviceType]]. * {{get-touch-device-type}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#touch-device-types|touch device type symbol]]. * {{get-touch-device-type-raw}} returns an integer. Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires SDL 2.0.10 or higher, and sdl2 egg 0.4.0 or higher. (get-num-touch-fingers touch-id) → integer See [[https://wiki.libsdl.org/SDL_GetNumTouchFingers|SDL_GetNumTouchFingers]]. (get-touch-finger touch-id index) → sdl2:finger See [[https://wiki.libsdl.org/SDL_GetTouchFinger|SDL_GetTouchFinger]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. ==== sdl2:finger sdl2:finger is a record type that wraps a pointer to an [[https://wiki.libsdl.org/SDL_Finger|SDL_Finger]] struct. (finger? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:finger. (finger-id finger) → integer Get the sdl2:finger's "id" field, as an integer. (finger-x finger) → float Get 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. (finger-y finger) → float Get 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. (finger-pressure finger) → float Get 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. === Version ==== Version Feature Identifiers In '''sdl2 egg 0.2.0 and higher''', the egg registers feature identifiers which can be used to detect the versions of the sdl2 egg and SDL at run time using the the {{feature?}} procedure, or at compile time using the {{cond-expand}} macro or {{#+foo}} syntax. Some or all of the following feature identifiers will be registered depending on the circumstances:
Feature ID Meaning
sdl2 Using any version of the sdl2 egg
sdl2-0.2.0+ Using sdl2 egg 0.2.0 or higher
sdl2-0.3.0+ ... 0.3.0 or higher
sdl2-0.4.0+ ... 0.4.0 or higher
libSDL-2.0.0+ The sdl2 egg was compiled with SDL 2.0.0 or higher
libSDL-2.0.1+ ... 2.0.1 or higher
libSDL-2.0.2+ ... 2.0.2 or higher
libSDL-2.0.3+ ... 2.0.3 or higher
libSDL-2.0.4+ ... 2.0.4 or higher
libSDL-2.0.5+ ... 2.0.5 or higher
libSDL-2.0.6+ ... 2.0.6 or higher
libSDL-2.0.7+ ... 2.0.7 or higher
libSDL-2.0.8+ ... 2.0.8 or higher
libSDL-2.0.9+ ... 2.0.9 or higher
libSDL-2.0.10+ ... 2.0.10 or higher
libSDL-2.0.12+ ... 2.0.12 or higher
libSDL-2.0.14+ ... 2.0.14 or higher
libSDL-2.0.16+ ... 2.0.16 or higher
These 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. Here are some examples of how you can use these identifiers: ;; use-for-syntax (on CHICKEN 4) or import-for-syntax (on CHICKEN 5) ;; to make the feature identifiers available at compile time. (cond-expand (chicken-4 (use (prefix sdl2 "sdl2:")) (use-for-syntax sdl2)) (chicken-5 (import (prefix sdl2 "sdl2:")) (import-for-syntax sdl2))) ;; Run-time check using feature? procedure: (when (feature? 'sdl2) (print "You are using the sdl2 egg. The future seems bright.")) ;; Compile time check using #+foo reader syntax: #+(not sdl2-0.2.0+) (begin-for-syntax (error "You need sdl2 egg 0.2.0 or higher.")) ;; Compile-time check using cond-expand macro: (cond-expand (libSDL-2.0.4+ (include "file-that-needs-SDL-204.scm")) (else (include "alternative-file.scm"))) ==== Version Functions (version-at-least? major minor patch) → boolean See [[https://wiki.libsdl.org/SDL_VERSION_ATLEAST|SDL_VERSION_ATLEAST]]. Returns {{#t}} if the sdl2 egg was compiled with a version of SDL at least as high as specified. For example, {{(version-at-least? 2 0 1)}} returns {{#t}} if the sdl2 egg was compiled with SDL 2.0.1 or higher. Some SDL features are only available after a certain version, so you can use this procedure to check whether the feature is available. (compiled-version) → list of integers (current-version) → list of integers Returns a list of three nonnegative integers, indicating a version number of SDL. For example, the list {{(2 0 3)}} indicates SDL 2.0.3. * {{compiled-version}} returns the version of SDL that the sdl2 egg was compiled with. * {{current-version}} returns the version of SDL that the sdl2 egg is currently using. For example, the user may have compiled the sdl2 egg with SDL 2.0.3, then later upgraded SDL to 2.0.4, but not yet recompiled the sdl2 egg with the new version. In such a case, {{compiled-version}} would return {{(2 0 3)}}, and {{current-version}} would return {{(2 0 4)}}. But, features from the new version would not be available until the user recompiles the sdl2 egg. See [[https://wiki.libsdl.org/SDL_VERSION|SDL_VERSION]] and [[https://wiki.libsdl.org/SDL_GetVersion|SDL_GetVersion]]. (egg-version) → list of integers Returns a list of three nonnegative integers, indicating the version number of the sdl2 egg itself, which is independent of the version number of SDL. For example, the list {{(1 2 3)}} indicates sdl2 egg version 1.2.3. Requires sdl2 egg 0.2.0 or higher. === Vulkan ==== Vulkan Functions (vulkan-load-library! path) See [[https://wiki.libsdl.org/SDL_Vulkan_LoadLibrary|SDL_Vulkan_LoadLibrary]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher. (vulkan-unload-library!) See [[https://wiki.libsdl.org/SDL_Vulkan_UnloadLibrary|SDL_Vulkan_UnloadLibrary]]. Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher. (vulkan-get-vk-get-instance-proc-addr) → pointer or #f See [[https://wiki.libsdl.org/SDL_Vulkan_GetVkGetInstanceProcAddr|SDL_Vulkan_GetVkGetInstanceProcAddr]]. Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher. (vulkan-get-instance-extensions window) → list of strings See [[https://wiki.libsdl.org/SDL_Vulkan_GetInstanceExtensions|SDL_Vulkan_GetInstanceExtensions]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher. (vulkan-get-drawable-size window) → [w h] This procedure returns multiple values. See [[https://wiki.libsdl.org/SDL_Vulkan_GetDrawableSize|SDL_Vulkan_GetDrawableSize]]. Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher. (vulkan-create-surface window vkinstance vksurface-out) See [[https://wiki.libsdl.org/SDL_Vulkan_CreateSurface|SDL_Vulkan_CreateSurface]]. * {{vkinstance}} must be a pointer to a {{VkInstance}}. * {{vksurface-out}} must be a pointer to a {{VkSurfaceKHR}}, which will be modified. Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher. === Window ==== Window Functions (create-window! title x y w h #!optional flags) → sdl2:window See [[https://wiki.libsdl.org/SDL_CreateWindow|SDL_CreateWindow]]. {{x}} and {{y}} can be integers, the symbol {{'centered}}, or the symbol {{'undefined}}. {{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. (destroy-window! window) See [[https://wiki.libsdl.org/SDL_DestroyWindow|SDL_DestroyWindow]]. (get-window-from-id id) → sdl2:window See [[https://wiki.libsdl.org/SDL_GetWindowFromID|SDL_GetWindowFromID]]. '''Note:''' The returned window will be a new sdl2:window record pointing to the address of the existing window. It will be {{struct-eq?}} to other sdl2:window records for the same window, but not {{eq?}}. In sdl2 egg 0.2.0 and higher, this procedure signals an exception of kind {{(exn sdl2)}} if there is no window with the given ID. In earlier egg versions, this procedure returned a null sdl2:window. (update-window-surface! window) See [[https://wiki.libsdl.org/SDL_UpdateWindowSurface|SDL_UpdateWindowSurface]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (update-window-surface-rects! window rects) See [[https://wiki.libsdl.org/SDL_UpdateWindowSurfaceRects|SDL_UpdateWindowSurfaceRects]]. {{rects}} must be a list of sdl2:rects. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (show-window! window) See [[https://wiki.libsdl.org/SDL_ShowWindow|SDL_ShowWindow]]. (hide-window! window) See [[https://wiki.libsdl.org/SDL_HideWindow|SDL_HideWindow]]. (maximize-window! window) See [[https://wiki.libsdl.org/SDL_MaximizeWindow|SDL_MaximizeWindow]]. (minimize-window! window) See [[https://wiki.libsdl.org/SDL_MinimizeWindow|SDL_MinimizeWindow]]. (raise-window! window) See [[https://wiki.libsdl.org/SDL_RaiseWindow|SDL_RaiseWindow]]. (restore-window! window) See [[https://wiki.libsdl.org/SDL_RestoreWindow|SDL_RestoreWindow]]. (flash-window! window operation) See [[https://wiki.libsdl.org/SDL_FlashWindow|SDL_FlashWindow]]. {{operation}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#window-flash-operation|window flash operation symbol]] or equivalent integer constant. Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires SDL 2.0.16 or higher, and sdl2 egg 0.4.0 or higher. (set-window-modal-for! modal-window parent-window) See [[https://wiki.libsdl.org/SDL_SetWindowModalFor|SDL_SetWindowModalFor]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires SDL 2.0.5 or higher, and sdl2 egg 0.4.0 or higher. ==== sdl2:window sdl2:window is a record type that wraps a pointer to an [[https://wiki.libsdl.org/SDL_CreateWindow|SDL_Window]] struct. (window? obj) → boolean Returns {{#t}} if {{obj}} is an sdl2:window. (window-always-on-top? window) → bool (set! (window-always-on-top? window) bool) (window-always-on-top-set! window bool) Get or set whether the window will always appear in front of other windows. Setting this to {{#t}} has the same effect as passing the {{always-on-top}} flag to {{create-window!}} when creating the window. Note: this has an effect only on some platforms, such as Linux. See [[https://wiki.libsdl.org/SDL_SetWindowAlwaysOnTop|SDL_SetWindowAlwaysOnTop]]. {{window-always-on-top?}} requires SDL 2.0.5 or higher. {{window-always-on-top-set!}} and {{(set! (window-always-on-top? window) ...)}} require SDL 2.0.16 or higher. Requires sdl2 egg 0.4.0 or higher. (window-bordered? window) → boolean (set! (window-bordered? window) bordered) (window-bordered-set! window bordered) Get or set whether the window has a border (window decoration). {{#t}} means the window has a border, {{#f}} means the window is borderless. Setting this to {{#f}} has essentially the same effect as passing the {{borderless}} flag to {{create-window!}} when creating the window. See [[https://wiki.libsdl.org/SDL_SetWindowBordered|SDL_SetWindowBordered]]. (window-borders-size window) → [top left bottom right] This procedure returns multiple values. See [[https://wiki.libsdl.org/SDL_GetWindowBordersSize|SDL_GetWindowBordersSize]]. Requires SDL 2.0.5 or higher, and sdl2 egg 0.4.0 or higher. (window-brightness window) → float (set! (window-brightness window) brightness) (window-brightness-set! window brightness) See [[https://wiki.libsdl.org/SDL_GetWindowBrightness|SDL_GetWindowBrightness]] and [[https://wiki.libsdl.org/SDL_SetWindowBrightness|SDL_SetWindowBrightness]]. The setters signal an exception of kind {{(exn sdl2)}} if an error occurs. (window-display-index window) → integer See [[https://wiki.libsdl.org/SDL_GetWindowDisplayIndex|SDL_GetWindowDisplayIndex]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (window-display-mode window) → sdl2:display-mode (set! (window-display-mode window) display-mode) (window-display-mode-set! window display-mode) See [[https://wiki.libsdl.org/SDL_GetWindowDisplayMode|SDL_GetWindowDisplayMode]] and [[https://wiki.libsdl.org/SDL_SetWindowDisplayMode|SDL_SetWindowDisplayMode]]. These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs. (window-flags window) → list of symbols (window-flags-raw window) → integer See [[https://wiki.libsdl.org/SDL_GetWindowFlags|SDL_GetWindowFlags]]. * {{window-flags}} returns a list of [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#window-flags|window flag symbols]]. * {{window-flags-raw}} returns an integer bitfield. (window-fullscreen window) → symbol or #f (set! (window-fullscreen window) mode) (window-fullscreen-set! window mode) Get or set the sdl2:window's fullscreen mode. See [[https://wiki.libsdl.org/SDL_SetWindowFullscreen|SDL_SetWindowFullscreen]]. {{window-fullscreen}} returns one of the following values: * {{'fullscreen}} means "real" fullscreen mode * {{'fullscreen-desktop}} means "fake" fullscreen mode that takes the size of the desktop * {{#f}} means windowed (non-fullscreen) mode The setters accept any of the above values, or {{#t}} (which means the same as {{'fullscreen}}), or an equivalent integer value. The setters signal an exception of kind {{(exn sdl2)}} if an error occurs. (window-grab? window) → boolean (set! (window-grab? window) grabbed) (window-grab-set! window grabbed) See [[https://wiki.libsdl.org/SDL_GetWindowGrab|SDL_GetWindowGrab]] and [[https://wiki.libsdl.org/SDL_SetWindowGrab|SDL_SetWindowGrab]]. (window-keyboard-grab? window) → boolean (set! (window-keyboard-grab? window) grabbed) (window-keyboard-grab-set! window grabbed) See [[https://wiki.libsdl.org/SDL_GetWindowKeyboardGrab|SDL_GetWindowKeyboardGrab]] and [[https://wiki.libsdl.org/SDL_SetWindowKeyboardGrab|SDL_SetWindowKeyboardGrab]]. Requires SDL 2.0.16 or higher, and sdl2 egg 0.4.0 or higher. (window-mouse-grab? window) → boolean (set! (window-mouse-grab? window) grabbed) (window-mouse-grab-set! window grabbed) See [[https://wiki.libsdl.org/SDL_GetWindowMouseGrab|SDL_GetWindowMouseGrab]] and [[https://wiki.libsdl.org/SDL_SetWindowMouseGrab|SDL_SetWindowMouseGrab]]. Requires SDL 2.0.16 or higher, and sdl2 egg 0.4.0 or higher. (grabbed-window) → sdl2:window or #f Returns the sdl2:window that currently has input grab, or {{#f}} if no window has input grab. See [[https://wiki.libsdl.org/SDL_GetGrabbedWindow|SDL_GetGrabbedWindow]]. '''Note:''' The returned window will be a new sdl2:window record pointing to the address of the existing window. It will be {{struct-eq?}} to other sdl2:window records for the same window, but not {{eq?}}. Requires SDL 2.0.4 or higher, and sdl2 egg 0.2.0 or higher. (window-icon-set! window icon-surface) See [[https://wiki.libsdl.org/SDL_SetWindowIcon|SDL_SetWindowIcon]]. (window-id window) → integer See [[https://wiki.libsdl.org/SDL_GetWindowID|SDL_GetWindowID]]. (window-maximum-size window) → [width height] (set! (window-maximum-size window) size) (window-maximum-size-set! window size) See [[https://wiki.libsdl.org/SDL_GetWindowMaximumSize|SDL_GetWindowMaximumSize]] and [[https://wiki.libsdl.org/SDL_SetWindowMaximumSize|SDL_SetWindowMaximumSize]]. {{window-maximum-size}} returns multiple values. The setters accept a list of integers {{(width height)}}. (window-minimum-size window) → [width height] (set! (window-minimum-size window) size) (window-minimum-size-set! window size) See [[https://wiki.libsdl.org/SDL_GetWindowMinimumSize|SDL_GetWindowMinimumSize]] and [[https://wiki.libsdl.org/SDL_SetWindowMinimumSize|SDL_SetWindowMinimumSize]]. {{window-minimum-size}} returns multiple values. The setters accept a list of integers {{(width height)}}. (window-opacity window) → float (set! (window-opacity window) opacity) (window-opacity-set! window opacity) See [[https://wiki.libsdl.org/SDL_GetWindowOpacity|SDL_GetWindowOpacity]] and [[https://wiki.libsdl.org/SDL_SetWindowOpacity|SDL_SetWindowOpacity]]. Requires SDL 2.0.5 or higher, and sdl2 egg 0.4.0 or higher. (window-pixel-format window) → symbol (window-pixel-format-raw window) → integer Returns a symbol or integer indicating the given window's pixel format. See [[https://wiki.libsdl.org/SDL_GetWindowPixelFormat|SDL_GetWindowPixelFormat]]. * {{window-pixel-format}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]]. * {{window-pixel-format-raw}} returns an integer. (window-position window) → [x y] (set! (window-position window) pos) (window-position-set! window pos) See [[https://wiki.libsdl.org/SDL_GetWindowPosition|SDL_GetWindowPosition]] and [[https://wiki.libsdl.org/SDL_SetWindowPosition|SDL_SetWindowPosition]]. {{window-position}} returns multiple values. The setters accept a list of integers {{(x y)}}. (window-resizable? window) → bool (set! (window-resizable? window) bool) (window-resizable-set! window bool) See [[https://wiki.libsdl.org/SDL_SetWindowResizable|SDL_SetWindowResizable]]. {{window-resizable?}} is available with any SDL version. {{window-resizable-set!}} and {{(set! (window-resizable? window) ...)}} require SDL 2.0.5 or higher. Requires sdl2 egg 0.4.0 or higher. (window-size window) → [width height] (set! (window-size window) size) (window-size-set! window size) See [[https://wiki.libsdl.org/SDL_GetWindowSize|SDL_GetWindowSize]] and [[https://wiki.libsdl.org/SDL_SetWindowSize|SDL_SetWindowSize]]. {{window-size}} returns multiple values. The setters accept a list of integers {{(width height)}}. (window-surface window) → sdl2:surface See [[https://wiki.libsdl.org/SDL_GetWindowSurface|SDL_GetWindowSurface]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (window-title window) → string (set! (window-title window) title) (window-title-set! window title) See [[https://wiki.libsdl.org/SDL_GetWindowTitle|SDL_GetWindowTitle]] and [[https://wiki.libsdl.org/SDL_SetWindowTitle|SDL_SetWindowTitle]]. === Miscellaneous (clear-error!) See [[https://wiki.libsdl.org/SDL_ClearError|SDL_ClearError]]. (get-error) → string See [[https://wiki.libsdl.org/SDL_GetError|SDL_GetError]]. (set-error! message) See [[https://wiki.libsdl.org/SDL_SetError|SDL_SetError]]. Unlike SDL_SetError, this procedure only accepts one argument, a string. You can use {{sprintf}} to do string substitution if desired. (get-platform) → string See [[https://wiki.libsdl.org/SDL_GetPlatform|SDL_GetPlatform]]. (get-base-path) → string See [[https://wiki.libsdl.org/SDL_GetBasePath|SDL_GetBasePath]]. Requires SDL 2.0.1 or higher, and sdl2 egg 0.4.0 or higher. (get-pref-path org app) → string See [[https://wiki.libsdl.org/SDL_GetPrefPath|SDL_GetPrefPath]]. Requires SDL 2.0.1 or higher, and sdl2 egg 0.4.0 or higher. (is-tablet?) → boolean See [[https://wiki.libsdl.org/SDL_IsTablet|SDL_IsTablet]]. Requires SDL 2.0.9 or higher, and sdl2 egg 0.4.0 or higher. (get-power-info) → [secs pct] See [[https://wiki.libsdl.org/SDL_GetPowerInfo|SDL_GetPowerInfo]]. Requires sdl2 egg 0.4.0 or higher. (screen-saver-enabled?) → boolean (set! (screen-saver-enabled?) enabled?) (screen-saver-enabled-set! enabled?) See [[https://wiki.libsdl.org/SDL_IsScreenSaverEnabled|SDL_IsScreenSaverEnabled]], [[https://wiki.libsdl.org/SDL_EnableScreenSaver|SDL_EnableScreenSaver]], and [[https://wiki.libsdl.org/SDL_DisableScreenSaver|SDL_DisableScreenSaver]]. (has-clipboard-text?) → boolean See [[https://wiki.libsdl.org/SDL_HasClipboardText|SDL_HasClipboardText]]. (get-clipboard-text) → string See [[https://wiki.libsdl.org/SDL_GetClipboardText|SDL_GetClipboardText]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (set-clipboard-text! text) See [[https://wiki.libsdl.org/SDL_SetClipboardText|SDL_SetClipboardText]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. (show-simple-message-box flag title message #!optional window) See [[https://wiki.libsdl.org/SDL_ShowSimpleMessageBox|SDL_ShowSimpleMessageBox]]. {{flag}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#message-box-flags|message box flag symbol]] or equivalent integer constant. Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires sdl2 egg 0.4.0 or higher. (open-url url) See [[https://wiki.libsdl.org/SDL_OpenURL|SDL_OpenURL]]. Signals an exception of kind {{(exn sdl2)}} if an error occurs. Requires SDL 2.0.14 or higher, and sdl2 egg 0.4.0 or higher.