sdl2

The sdl2 egg provides bindings to 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 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: John Croisant
License: BSD 2-Clause

Table of Contents

TOC »

sdl2
Help Wanted!
Requirements
Related Libraries
Installation
- Installing on macOS
Usage and Examples
- Ensuring Proper Clean Up
Version History
API

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 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 test egg. Some demos and examples have other dependencies as well.

Related Libraries

The sdl2-image egg provides bindings to SDL_image version 2, which provides the ability to load many image formats. It is built to be compatible with the sdl2 egg.

The sdl2-ttf egg provides bindings to 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 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!)

(Note that this example doesn't work on macOS; the window never shows up.)

The 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 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.1 (2021-10-20): Fixed compile errors when using old versions of SDL2.
0.4.0 (2021-10-15): Added 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 CHANGELOG.

API

About the API

API Stability

The sdl2 egg follows 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 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 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:

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 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 obj2procedure

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 sdl2-image and 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? recordprocedure

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 sdl2-image and 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!procedure

See SDL_SetMainReady.

You should call this soon after your program starts, before calling init!. See Ensuring Proper Clean Up.

init! #!optional flags-listprocedure

Initialize SDL. You should call this soon after your program starts, after calling set-main-ready!. See Ensuring Proper Clean Up.

flags-list defaults to '(everything). It must be a list of one or more init flag symbols.

See SDL_Init.

Signals an exception of kind (exn sdl2) if initialization fails.

init-subsystem! flags-listprocedure

See SDL_InitSubSystem.

flags-list must be a list of one or more init flag symbols.

Signals an exception of kind (exn sdl2) if initialization fails.

quit!procedure

Clean up SDL. You must make sure to call this before your program ends. See Ensuring Proper Clean Up.

See SDL_Quit.

quit-subsystem! flags-listprocedure

See SDL_QuitSubSystem.

flags-list must be a list of one or more init flag symbols.

was-init #!optional flags-listprocedure

See SDL_WasInit.

flags-list defaults to '(everything). It must be a list of one or more init flag symbols.

Color

sdl2:color

sdl2:color is a record type that wraps a pointer to an SDL_Color struct.

color? objprocedure
colour? objprocedure: Returns #t if obj is an sdl2:color.

make-color #!optional r g b aprocedure

make-colour #!optional r g b aprocedure

make-color* #!optional r g b aprocedure

make-colour* #!optional r g b aprocedure

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! colorprocedure
free-colour! colorprocedure: 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 colorprocedure
colour-r colorprocedure
set! (color-r color) valsetter
set! (colour-r color) valsetter
color-r-set! color valsetter
colour-r-set! color valsetter: Get or set the sdl2:color's "r" (red) field, as an integer in the range 0 to 255 (inclusive).

color-g colorprocedure
colour-g colorprocedure
set! (color-g color) valsetter
set! (colour-g color) valsetter
color-g-set! color valsetter
colour-g-set! color valsetter: Get or set the sdl2:color's "g" (green) field, as an integer in the range 0 to 255 (inclusive).

color-b colorprocedure
colour-b colorprocedure
set! (color-b color) valsetter
set! (colour-b color) valsetter
color-b-set! color valsetter
colour-b-set! color valsetter: Get or set the sdl2:color's "b" (blue) field, as an integer in the range 0 to 255 (inclusive).

color-a colorprocedure
colour-a colorprocedure
set! (color-a color) valsetter
set! (colour-a color) valsetter
color-a-set! color valsetter
colour-a-set! color valsetter: 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 asetter
colour-set! color #!optional r g b asetter: 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 colorprocedure
colour->list colorprocedure: Returns a list (r g b a) containing the value of each field of the sdl2:color.

color->values colorprocedure
colour->values colorprocedure: 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 color2procedure
colour=? color1 color2procedure: 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 srcprocedure

colour-copy srcprocedure

color-copy! src destprocedure

colour-copy! src destprocedure

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 factorprocedure

colour-scale color factorprocedure

color-scale! color factor #!optional destprocedure

colour-scale! color factor #!optional destprocedure

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 color2procedure

colour-mult color1 color2procedure

color-mult! color1 color2 #!optional destprocedure

colour-mult! color1 color2 #!optional destprocedure

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 color2procedure

colour-add color1 color2procedure

color-add! color1 color2 #!optional destprocedure

colour-add! color1 color2 #!optional destprocedure

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 destprocedure

colour-sub! color1 color2 #!optional destprocedure

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 tprocedure

color-lerp! color1 color2 t #!optional destprocedure

colour-lerp color1 color2 tprocedure

colour-lerp! color1 color2 t #!optional destprocedure

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-yprocedure

create-cursor* data mask w h hot-x hot-yprocedure

Create a cursor from pixel and mask data. data and mask must be u8vectors, blobs, locatives, or pointers. See 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-yprocedure

create-color-cursor* surface hot-x hot-yprocedure

create-colour-cursor surface hot-x hot-yprocedure

create-colour-cursor* surface hot-x hot-yprocedure

See 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 enumprocedure

create-system-cursor* enumprocedure

enum must be a system cursor symbol or equivalent integer. See 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-cursorprocedure

(set! (get-cursor) cursor)setter

cursor-set! cursorsetter

Get or set the active cursor. You should not call free-cursor! on the cursor returned by get-cursor. See SDL_GetCursor and SDL_SetCursor.

Requires sdl2 egg 0.4.0 or higher.

get-default-cursorprocedure

Get the default cursor. See SDL_GetDefaultCursor.

Requires sdl2 egg 0.4.0 or higher.

show-cursor?procedure

show-cursor! booleanprocedure

(set! (show-cursor?) boolean)setter

See SDL_ShowCursor.

Requires sdl2 egg 0.4.0 or higher.

sdl2:cursor

cursor? objprocedure

Returns #t if obj is an sdl2:cursor.

Requires sdl2 egg 0.4.0 or higher.

free-cursor! cursorprocedure

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-nameprocedure

Initialize video with the given driver. driver-name can be omitted or #f to use the default driver. See SDL_VideoInit.

Requires sdl2 egg 0.4.0 or higher.

video-quit!procedure

See SDL_VideoQuit.

Requires sdl2 egg 0.4.0 or higher.

get-num-video-driversprocedure

See SDL_GetNumVideoDrivers.

Requires sdl2 egg 0.4.0 or higher.

get-video-driver driver-indexprocedure

See SDL_GetVideoDriver.

Requires sdl2 egg 0.4.0 or higher.

get-current-video-driverprocedure

See SDL_GetCurrentVideoDriver.

Requires sdl2 egg 0.4.0 or higher.

get-num-video-displaysprocedure

See SDL_GetNumVideoDisplays.

Requires sdl2 egg 0.4.0 or higher.

get-display-name display-indexprocedure

See SDL_GetDisplayName.

Requires sdl2 egg 0.4.0 or higher.

get-display-dpi display-indexprocedure

Return the diagonal, horizontal, and vertical DPI (dots per inch) of the specified display. This procedure returns multiple values. See SDL_GetDisplayDPI.

Requires SDL 2.0.4 or higher, and sdl2 egg 0.4.0 or higher.

get-display-bounds display-indexprocedure

See SDL_GetDisplayBounds.

Requires sdl2 egg 0.4.0 or higher.

get-display-usable-bounds display-indexprocedure

See SDL_GetDisplayUsableBounds.

Requires SDL 2.0.5 or higher, and sdl2 egg 0.4.0 or higher.

get-display-orientation display-indexprocedure

get-display-orientation-raw display-indexprocedure

See SDL_GetDisplayOrientation.

get-display-orientation returns a 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-indexprocedure

See SDL_GetNumDisplayModes.

Requires sdl2 egg 0.4.0 or higher.

get-display-mode display-index iprocedure

See SDL_GetDisplayMode.

Requires sdl2 egg 0.4.0 or higher.

get-current-display-mode display-indexprocedure

See SDL_GetCurrentDisplayMode.

Requires sdl2 egg 0.4.0 or higher.

get-closest-display-mode display-index target-modeprocedure

See SDL_GetClosestDisplayMode.

Requires sdl2 egg 0.4.0 or higher.

get-desktop-display-mode display-indexprocedure

See 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 SDL_DisplayMode struct.

display-mode? objprocedure: Returns #t if obj is an sdl2:display-mode.

make-display-mode #!optional format w h refresh-rateprocedure

make-display-mode* #!optional format w h refresh-rateprocedure

Allocate and initialize a new sdl2:display-mode.

format defaults to 'unknown. It must be a 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-modeprocedure: 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-modeprocedure

display-mode-format-raw display-modeprocedure

set! (display-mode-format display-mode) valsetter

display-mode-format-set! display-mode valsetter

Get or set the sdl2:display-mode's "format" field.

display-mode-format returns a pixel format symbol.
display-mode-format-raw returns an integer.
The setters accept either a symbol or an integer.

display-mode-w display-modeprocedure
set! (display-mode-w display-mode) valsetter
display-mode-w-set! display-mode valsetter: Get or set the sdl2:display-mode's "w" field, as an integer.

display-mode-h display-modeprocedure
set! (display-mode-h display-mode) valsetter
display-mode-h-set! display-mode valsetter: Get or set the sdl2:display-mode's "h" field, as an integer.

display-mode-refresh-rate display-modeprocedure
set! (display-mode-refresh-rate display-mode) valsetter
display-mode-refresh-rate-set! display-mode valsetter: Get or set the sdl2:display-mode's "refresh-rate" field, as an integer.

Event

Event Functions

event-state typeprocedure

set! (event-state type) statesetter

event-state-set! type statesetter

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 SDL_EventState.

type must be an 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! typeprocedure

flush-events! #!optional min-type max-typeprocedure

Remove all events on the event queue that match the given type or range of types. See SDL_FlushEvent and SDL_FlushEvents.

For flush-event!, type must be an 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 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? typeprocedure

has-events? #!optional min-type max-typeprocedure

Returns #t if the event queue currently has at least one event matching the given type or range of types. See SDL_HasEvent and SDL_HasEvents.

For has-event?, type must be an 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 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?procedure: Returns #t if the event queue currently has at least one event of type 'quit. See SDL_QuitRequested.

get-events! num #!optional min-type max-typeprocedure

peek-events num #!optional min-type max-typeprocedure

Get multiple matching events from the front of the event queue. Returns a list of managed sdl2:events. See 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 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-eventprocedure

Get the next event from the event queue. The returned event is removed from the event queue. See 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!procedure: See SDL_PumpEvents.

push-event! eventprocedure

See 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-fnprocedure

wait-event-timeout! timeout #!optional result-event delay-fnprocedure

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.)

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 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) SDL_WaitEvent and SDL_WaitEventTimeout.

register-events! event-symbolsprocedure

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 SDL_RegisterEvents.

sdl2:event

sdl2:event is a record type that wraps a pointer to an 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 event type symbols.

Variant of sdl2:event	Underlying struct	Event type symbol(s)
sdl2:controller-axis-event	SDL_ControllerAxisEvent	`'controller-axis-motion`
sdl2:controller-button-event	SDL_ControllerButtonEvent	`'controller-button-down` `'controller-button-up`
sdl2:controller-device-event	SDL_ControllerDeviceEvent	`'controller-device-added` `'controller-device-removed` `'controller-device-remapped`
sdl2:display-event	SDL_DisplayEvent	`'display`
sdl2:dollar-gesture-event	SDL_DollarGestureEvent	`'dollar-gesture` `'dollar-record`
sdl2:drop-event	SDL_DropEvent	`'drop-file`
sdl2:joy-axis-event	SDL_JoyAxisEvent	`'joy-axis-motion`
sdl2:joy-ball-event	SDL_JoyBallEvent	`'joy-ball-motion`
sdl2:joy-button-event	SDL_JoyButtonEvent	`'joy-button-down` `'joy-button-up`
sdl2:joy-device-event	SDL_JoyDeviceEvent	`'joy-device-added` `'joy-device-removed`
sdl2:joy-hat-event	SDL_JoyHatEvent	`'joy-hat-motion`
sdl2:keyboard-event	SDL_KeyboardEvent	`'key-down` `'key-up`
sdl2:mouse-button-event	SDL_MouseButtonEvent	`'mouse-button-down` `'mouse-button-up`
sdl2:mouse-motion-event	SDL_MouseMotionEvent	`'mouse-motion`
sdl2:mouse-wheel-event	SDL_MouseWheelEvent	`'mouse-wheel`
sdl2:multi-gesture-event	SDL_MultiGestureEvent	`'multi-gesture`
sdl2:quit-event	SDL_QuitEvent	`'quit`
sdl2:sys-wm-event	SDL_SysWMEvent	`'sys-wm`
sdl2:text-editing-event	SDL_TextEditingEvent	`'text-editing`
sdl2:text-input-event	SDL_TextInputEvent	`'text-input`
sdl2:touch-finger-event	SDL_TouchFingerEvent	`'finger-down` `'finger-up` `'finger-motion`
sdl2:user-event	SDL_UserEvent	(Call `register-events!` to register your own user event type symbols.)
sdl2:window-event	SDL_WindowEvent	`'window`

event? objprocedure: Returns #t if obj is any variant of sdl2:event.

make-event #!optional typeprocedure

make-event* #!optional typeprocedure

Allocate and set the type of a new sdl2:event.

type defaults to 'first. It must be a 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! eventprocedure: 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 eventprocedure

event-type-raw eventprocedure

set! (event-type event) valsetter

event-type-set! event valsetter

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 event type symbol.
event-type-raw returns an integer.
The setters accept either a symbol or an integer.

event-timestamp eventprocedure
set! (event-timestamp event) valsetter
event-timestamp-set! event valsetter: 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 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? objprocedure: Returns #t if obj is an sdl2:controller-axis-event.

controller-axis-event-which eventprocedure
set! (controller-axis-event-which event) valsetter
controller-axis-event-which-set! event valsetter: 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 eventprocedure

controller-axis-event-axis-raw eventprocedure

set! (controller-axis-event-axis event) valsetter

controller-axis-event-axis-set! event valsetter

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 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 eventprocedure
set! (controller-axis-event-value event) valsetter
controller-axis-event-value-set! event valsetter: 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 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? objprocedure: Returns #t if obj is an sdl2:controller-button-event.

controller-button-event-which eventprocedure
set! (controller-button-event-which event) valsetter
controller-button-event-which-set! event valsetter: 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 eventprocedure

controller-button-event-button-raw eventprocedure

set! (controller-button-event-button event) valsetter

controller-button-event-button-set! event valsetter

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 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 eventprocedure
set! (controller-button-event-state event) valsetter
controller-button-event-state-set! event valsetter: 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 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? objprocedure: Returns #t if obj is an sdl2:controller-device-event.

controller-device-event-which eventprocedure
set! (controller-device-event-which event) valsetter
controller-device-event-which-set! event valsetter: 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 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? objprocedure

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 eventprocedure

set! (display-event-display event) display-indexsetter

display-event-display-set! event display-indexsetter

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 eventprocedure

display-event-event-raw eventprocedure

set! (display-event-event event) enumsetter

display-event-event-set! event enumsetter

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 eventprocedure

set! (display-event-data1 event) datasetter

display-event-data1-set! event datasetter

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 eventprocedure

set! (display-event-orientation event) datasetter

display-event-orientation-set! event orientationsetter

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 SDL_DollarGestureEvent.

This event variant occurs when a "$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? objprocedure: Returns #t if obj is an sdl2:dollar-gesture-event.

dollar-gesture-event-touch-id eventprocedure
set! (dollar-gesture-event-touch-id event) valsetter
dollar-gesture-event-touch-id-set! event valsetter: 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 eventprocedure
set! (dollar-gesture-event-gesture-id event) valsetter
dollar-gesture-event-gesture-id-set! event valsetter: 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 eventprocedure
set! (dollar-gesture-event-num-fingers event) valsetter
dollar-gesture-event-num-fingers-set! event valsetter: 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 eventprocedure
set! (dollar-gesture-event-error event) valsetter
dollar-gesture-event-error-set! event valsetter: 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 eventprocedure
set! (dollar-gesture-event-x event) valsetter
dollar-gesture-event-x-set! event valsetter: 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 eventprocedure
set! (dollar-gesture-event-y event) valsetter
dollar-gesture-event-y-set! event valsetter: 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 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? objprocedure: Returns #t if obj is an sdl2:drop-event.

drop-event-file eventprocedure

set! (drop-event-file event) valsetter

drop-event-file-set! event valsetter

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 eventprocedure

set! (drop-event-window-id event) isetter

drop-event-window-id-set! event isetter

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 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? objprocedure: Returns #t if obj is an sdl2:joy-axis-event.

joy-axis-event-which eventprocedure
set! (joy-axis-event-which event) valsetter
joy-axis-event-which-set! event valsetter: 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 eventprocedure
set! (joy-axis-event-axis event) valsetter
joy-axis-event-axis-set! event valsetter: 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 eventprocedure
set! (joy-axis-event-value event) valsetter
joy-axis-event-value-set! event valsetter: 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 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? objprocedure: Returns #t if obj is an sdl2:joy-ball-event.

joy-ball-event-which eventprocedure
set! (joy-ball-event-which event) valsetter
joy-ball-event-which-set! event valsetter: 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 eventprocedure
set! (joy-ball-event-ball event) valsetter
joy-ball-event-ball-set! event valsetter: 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 eventprocedure
set! (joy-ball-event-xrel event) valsetter
joy-ball-event-xrel-set! event valsetter: 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 eventprocedure
set! (joy-ball-event-yrel event) valsetter
joy-ball-event-yrel-set! event valsetter: 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 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? objprocedure: Returns #t if obj is an sdl2:joy-button-event.

joy-button-event-which eventprocedure
set! (joy-button-event-which event) valsetter
joy-button-event-which-set! event valsetter: 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 eventprocedure
set! (joy-button-event-button event) valsetter
joy-button-event-button-set! event valsetter: 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 eventprocedure
set! (joy-button-event-state event) valsetter
joy-button-event-state-set! event valsetter: 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 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? objprocedure: Returns #t if obj is an sdl2:joy-device-event.

joy-device-event-which eventprocedure
set! (joy-device-event-which event) valsetter
joy-device-event-which-set! event valsetter: 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 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? objprocedure: Returns #t if obj is an sdl2:joy-hat-event.

joy-hat-event-which eventprocedure
set! (joy-hat-event-which event) valsetter
joy-hat-event-which-set! event valsetter: 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 eventprocedure
set! (joy-hat-event-hat event) valsetter
joy-hat-event-hat-set! event valsetter: 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 eventprocedure

joy-hat-event-value-raw eventprocedure

set! (joy-hat-event-value event) valsetter

joy-hat-event-value-set! event valsetter

Get or set the event's "value" field, indicating the new position of the hat switch.

joy-hat-event-value returns a 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 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? objprocedure: Returns #t if obj is an sdl2:keyboard-event.

keyboard-event-window-id eventprocedure
set! (keyboard-event-window-id event) valsetter
keyboard-event-window-id-set! event valsetter: 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 eventprocedure
set! (keyboard-event-state event) valsetter
keyboard-event-state-set! event valsetter: 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 eventprocedure
set! (keyboard-event-repeat event) valsetter
keyboard-event-repeat-set! event valsetter: 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 eventprocedure

set! (keyboard-event-keysym event) valsetter

keyboard-event-keysym-set! event valsetter

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 eventprocedure

keyboard-event-scancode-raw eventprocedure

set! (keyboard-event-scancode event) valsetter

keyboard-event-scancode-set! event valsetter

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 keyboard scancode symbol.
keyboard-event-scancode-raw returns an integer.
The setters accept either a symbol or an integer.

keyboard-event-sym eventprocedure

keyboard-event-sym-raw eventprocedure

set! (keyboard-event-sym event) valsetter

keyboard-event-sym-set! event valsetter

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 keyboard keycode symbol
keyboard-event-sym-raw returns an integer.
The setters accept either a symbol or an integer.

keyboard-event-mod eventprocedure

keyboard-event-mod-raw eventprocedure

set! (keyboard-event-mod event) valsetter

keyboard-event-mod-set! event valsetter

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 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 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? objprocedure: Returns #t if obj is an sdl2:mouse-button-event.

mouse-button-event-window-id eventprocedure
set! (mouse-button-event-window-id event) valsetter
mouse-button-event-window-id-set! event valsetter: 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 eventprocedure
set! (mouse-button-event-which event) valsetter
mouse-button-event-which-set! event valsetter: Get or set the event's "which" field, as an integer indicating the mouse instance ID.

mouse-button-event-button eventprocedure

mouse-button-event-button-raw eventprocedure

set! (mouse-button-event-button event) valsetter

mouse-button-event-button-set! event valsetter

Get or set the event's "button" field, indicating the button that the event is related to.

mouse-button-event-button returns a mouse button symbol.
mouse-button-event-button-raw returns an integer.
The setters accept either a symbol or an integer.

mouse-button-event-state eventprocedure
set! (mouse-button-event-state event) valsetter
mouse-button-event-state-set! event valsetter: 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 eventprocedure
set! (mouse-button-event-x event) valsetter
mouse-button-event-x-set! event valsetter: 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 eventprocedure
set! (mouse-button-event-y event) valsetter
mouse-button-event-y-set! event valsetter: 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 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? objprocedure: Returns #t if obj is an sdl2:mouse-motion-event.

mouse-motion-event-window-id eventprocedure
set! (mouse-motion-event-window-id event) valsetter
mouse-motion-event-window-id-set! event valsetter: 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 eventprocedure
set! (mouse-motion-event-which event) valsetter
mouse-motion-event-which-set! event valsetter: Get or set the event's "which" field, as an integer indicating the mouse instance ID.

mouse-motion-event-state eventprocedure

mouse-motion-event-state-raw eventprocedure

set! (mouse-motion-event-state event) valsetter

mouse-motion-event-state-set! event valsetter

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 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 eventprocedure
set! (mouse-motion-event-x event) valsetter
mouse-motion-event-x-set! event valsetter: 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 eventprocedure
set! (mouse-motion-event-y event) valsetter
mouse-motion-event-y-set! event valsetter: 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 eventprocedure
set! (mouse-motion-event-xrel event) valsetter
mouse-motion-event-xrel-set! event valsetter: 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 eventprocedure
set! (mouse-motion-event-yrel event) valsetter
mouse-motion-event-yrel-set! event valsetter: 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 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? objprocedure: Returns #t if obj is an sdl2:mouse-wheel-event.

mouse-wheel-event-window-id eventprocedure
set! (mouse-wheel-event-window-id event) valsetter
mouse-wheel-event-window-id-set! event valsetter: 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 eventprocedure
set! (mouse-wheel-event-which event) valsetter
mouse-wheel-event-which-set! event valsetter: Get or set the event's "which" field, as an integer indicating the mouse instance ID.

mouse-wheel-event-x eventprocedure
set! (mouse-wheel-event-x event) valsetter
mouse-wheel-event-x-set! event valsetter: 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 eventprocedure
set! (mouse-wheel-event-y event) valsetter
mouse-wheel-event-y-set! event valsetter: 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 eventprocedure

set! (mouse-wheel-event-direction event) valsetter

mouse-wheel-event-direction-set! event valsetter

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 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? objprocedure: Returns #t if obj is an sdl2:multi-gesture-event.

multi-gesture-event-touch-id eventprocedure
set! (multi-gesture-event-touch-id event) valsetter
multi-gesture-event-touch-id-set! event valsetter: 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 eventprocedure
set! (multi-gesture-event-dtheta event) valsetter
multi-gesture-event-dtheta-set! event valsetter: 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 eventprocedure
set! (multi-gesture-event-ddist event) valsetter
multi-gesture-event-ddist-set! event valsetter: 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 eventprocedure
set! (multi-gesture-event-x event) valsetter
multi-gesture-event-x-set! event valsetter: 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 eventprocedure
set! (multi-gesture-event-y event) valsetter
multi-gesture-event-y-set! event valsetter: 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 eventprocedure
set! (multi-gesture-event-num-fingers event) valsetter
multi-gesture-event-num-fingers-set! event valsetter: 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 SDL_QuitEvent.

This event variant occurs when the user requests to quit the program. There are 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? objprocedure: 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 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? objprocedure: Returns #t if obj is an sdl2:sys-wm-event.

sys-wm-event-msg-raw eventprocedure
set! (sys-wm-event-msg-raw event) valsetter
sys-wm-event-msg-raw-set! event valsetter: Get or set the event's "msg" field, as a raw pointer to a 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 SDL_TextEditingEvent.

This event occurs when a user is editing (composing) text, e.g. using an Input Method Editor (IME). See the 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? objprocedure: Returns #t if obj is an sdl2:text-editing-event.

text-editing-event-window-id eventprocedure
set! (text-editing-event-window-id event) valsetter
text-editing-event-window-id-set! event valsetter: 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 eventprocedure
set! (text-editing-event-text event) valsetter
text-editing-event-text-set! event valsetter: 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 eventprocedure
set! (text-editing-event-start event) valsetter
text-editing-event-start-set! event valsetter: Get or set the event's "start" field, as an integer indicating the location to begin editing from.

text-editing-event-length eventprocedure
set! (text-editing-event-length event) valsetter
text-editing-event-length-set! event valsetter: 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 SDL_TextInputEvent.

This event occurs when the users enters some text, possibly using an Input Metod Editor (IME). See the 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? objprocedure: Returns #t if obj is an sdl2:text-input-event.

text-input-event-window-id eventprocedure
set! (text-input-event-window-id event) valsetter
text-input-event-window-id-set! event valsetter: 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 eventprocedure
set! (text-input-event-text event) valsetter
text-input-event-text-set! event valsetter: 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 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? objprocedure: Returns #t if obj is an sdl2:touch-finger-event.

touch-finger-event-touch-id eventprocedure
set! (touch-finger-event-touch-id event) valsetter
touch-finger-event-touch-id-set! event valsetter: 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 eventprocedure
set! (touch-finger-event-finger-id event) valsetter
touch-finger-event-finger-id-set! event valsetter: 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 eventprocedure
set! (touch-finger-event-x event) valsetter
touch-finger-event-x-set! event valsetter: 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 eventprocedure
set! (touch-finger-event-y event) valsetter
touch-finger-event-y-set! event valsetter: 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 eventprocedure
set! (touch-finger-event-dx event) valsetter
touch-finger-event-dx-set! event valsetter: 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 eventprocedure
set! (touch-finger-event-dy event) valsetter
touch-finger-event-dy-set! event valsetter: 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 eventprocedure
set! (touch-finger-event-pressure event) valsetter
touch-finger-event-pressure-set! event valsetter: 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 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? objprocedure: Returns #t if obj is an sdl2:user-event.

user-event-window-id eventprocedure
set! (user-event-window-id event) valsetter
user-event-window-id-set! event valsetter: 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 eventprocedure
set! (user-event-code event) valsetter
user-event-code-set! event valsetter: 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 eventprocedure

set! (user-event-data1-raw event) valsetter

user-event-data1-raw-set! event valsetter

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 evict the object first. Otherwise the object's location in memory might change, rendering the pointer invalid.

user-event-data2-raw eventprocedure

set! (user-event-data2-raw event) valsetter

user-event-data2-raw-set! event valsetter

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 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 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? objprocedure: Returns #t if obj is an sdl2:window-event.

window-event-window-id eventprocedure
set! (window-event-window-id event) valsetter
window-event-window-id-set! event valsetter: 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 eventprocedure

window-event-event-raw eventprocedure

set! (window-event-event event) valsetter

window-event-event-set! event valsetter

Get or set the event's "event" field, indicating what happened to the window.

window-event-event returns a window event type symbol.
window-event-event-raw returns an integer.
The setters accept either a symbol or an integer.

window-event-data1 eventprocedure
set! (window-event-data1 event) valsetter
window-event-data1-set! event valsetter: 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 eventprocedure
set! (window-event-data2 event) valsetter
window-event-data2-set! event valsetter: 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-indexprocedure

Returns #t if the joystick at the given index is a controller. See SDL_IsGameController.

Requires sdl2 egg 0.4.0 or higher.

game-controller-open! joy-indexprocedure

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 SDL_GameControllerOpen.

Signals an exception of kind (exn sdl2) if an error occurs.

Requires sdl2 egg 0.4.0 or higher.

game-controller-close! controllerprocedure

See SDL_GameControllerClose.

Requires sdl2 egg 0.4.0 or higher.

game-controller-from-instance-id instance-idprocedure

See 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!procedure

See SDL_GameControllerUpdate.

Requires sdl2 egg 0.4.0 or higher.

game-controller-event-state?procedure

(set! (game-controller-event-state?) state)setter

game-controller-event-state-set! statesetter

See SDL_GameControllerEventState.

Requires sdl2 egg 0.4.0 or higher.

game-controller-attached? controllerprocedure

See SDL_GameControllerGetAttached.

Requires sdl2 egg 0.4.0 or higher.

game-controller-get-joystick controllerprocedure

See SDL_GameControllerGetJoystick.

Requires sdl2 egg 0.4.0 or higher.

game-controller-mapping controllerprocedure

See SDL_GameControllerMapping.

Requires sdl2 egg 0.4.0 or higher.

game-controller-mapping-for-guidprocedure

See SDL_GameControllerMappingForGUID.

Requires sdl2 egg 0.4.0 or higher.

game-controller-add-mapping! strprocedure

Returns 1 if a new mapping was added, 0 if an existing mapping was updated. See 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! pathprocedure

See 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?procedure

See 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-mappingsprocedure

See SDL_GameControllerNumMappings.

Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher.

game-controller-mapping-for-index indexprocedure

See SDL_GameControllerMappingForIndex.

Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher.

game-controller-mapping-for-device-index device-indexprocedure

See SDL_GameControllerMappingForDeviceIndex.

Requires SDL 2.0.9 or higher, and sdl2 egg 0.4.0 or higher.

game-controller-name controllerprocedure

See 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-indexprocedure

See 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 axisprocedure

See SDL_GameControllerGetAxis.

axis must be a game controller axis symbol or equivalent integer.

Requires sdl2 egg 0.4.0 or higher.

game-controller-get-axis-from-string strprocedure

game-controller-get-axis-from-string-raw strprocedure

See SDL_GameControllerGetAxisFromString.

game-controller-get-axis-from-string returns a 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 axisprocedure

See SDL_GameControllerGetStringForAxis.

axis must be a game controller axis symbol or equivalent integer.

Requires sdl2 egg 0.4.0 or higher.

game-controller-get-button buttonprocedure

See SDL_GameControllerGetButton.

button must be a game controller button symbol or equivalent integer.

Requires sdl2 egg 0.4.0 or higher.

game-controller-get-button-from-stringprocedure

game-controller-get-button-from-string-rawprocedure

See SDL_GameControllerGetButtonFromString.

game-controller-get-button-from-string returns a 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 buttonprocedure

See SDL_GameControllerGetStringForButton.

button must be a game controller button symbol or equivalent integer.

Requires sdl2 egg 0.4.0 or higher.

game-controller-get-bind-for-axis axisprocedure

See SDL_GameControllerGetBindForAxis.

axis must be a game controller axis symbol or equivalent integer.

Requires sdl2 egg 0.4.0 or higher.

game-controller-get-bind-for-button buttonprocedure

See SDL_GameControllerGetBindForButton.

button must be a game controller button symbol or equivalent integer.

Requires sdl2 egg 0.4.0 or higher.

game-controller-get-player-index controllerprocedure

See SDL_GameControllerGetPlayerIndex.

Requires SDL 2.0.9 or higher, and sdl2 egg 0.4.0 or higher.

game-controller-get-product controllerprocedure

See SDL_GameControllerGetProduct.

Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher.

game-controller-get-product-version controllerprocedure

See SDL_GameControllerGetProductVersion.

Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher.

game-controller-get-vendor controllerprocedure

See 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-msprocedure

See 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 SDL_GameController struct.

game-controller? objprocedure

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 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? objprocedure

Returns #t if obj is an sdl2:game-controller-button-bind.

Requires sdl2 egg 0.4.0 or higher.

game-controller-button-bind-type bindprocedure

game-controller-button-bind-type-raw bindprocedure

Get the sdl2:game-controller-button-bind's "type" field.

game-controller-button-bind-type returns a 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 bindprocedure

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 bindprocedure

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 bindprocedure

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 bindprocedure

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

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 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 nameprocedure

Returns the current value of the hint as a string, or #f if the hint has no value. See SDL_GetHint and SDL_hints.h

name must be a hint symbol or string (same as the environment variable name).

Requires sdl2 egg 0.2.0 or higher.

get-hint-boolean nameprocedure

Returns the current value of the hint as a boolean. See SDL_GetHintBoolean and SDL_hints.h

name must be a 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 priorityprocedure

Sets the value of the hint. See SDL_SetHintWithPriority and SDL_hints.h

name must be a 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!procedure

Removes the values and priorities of all hints. See SDL_ClearHints.

Requires sdl2 egg 0.2.0 or higher.

Joystick

Joystick Functions

num-joysticksprocedure

See SDL_NumJoysticks.

Signals an exception of kind (exn sdl2) if an error occurs.

joystick-open! indexprocedure

See SDL_JoystickOpen.

Signals an exception of kind (exn sdl2) if an error occurs.

joystick-close! joystickprocedure: See SDL_JoystickClose.

joystick-from-instance-id idprocedure

See 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!procedure: See SDL_JoystickUpdate.

joystick-event-stateprocedure

(set! (joystick-event-state) state) → booleansetter

joystick-event-state-set! statesetter

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 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-indexprocedure

See SDL_JoystickNameForIndex.

Returns #f if no name can be found.

joystick-get-device-guid device-indexprocedure

See SDL_JoystickGetDeviceGUID.

Returns a new managed sdl2:joystick-guid.

joystick-get-axis-initial-state joy axisprocedure

See 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-indexprocedure

See SDL_JoystickGetDeviceInstanceID.

Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher.

joystick-get-device-player-index device-indexprocedure

See SDL_JoystickGetDevicePlayerIndex.

Requires SDL 2.0.9 or higher, and sdl2 egg 0.4.0 or higher.

joystick-get-device-product device-indexprocedure

See SDL_JoystickGetDeviceProduct.

Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher.

joystick-get-device-product-version device-indexprocedure

See SDL_JoystickGetDeviceProductVersion.

Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher.

joystick-get-device-type device-indexprocedure

joystick-get-device-type-raw device-indexprocedure

See SDL_JoystickGetDeviceType.

joystick-get-device-type returns a 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-indexprocedure

See SDL_JoystickGetDeviceVendor.

Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher.

joystick-get-player-index joystickprocedure

See SDL_JoystickGetPlayerIndex.

Requires SDL 2.0.9 or higher, and sdl2 egg 0.4.0 or higher.

joystick-get-product joystickprocedure

See SDL_JoystickGetProduct.

Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher.

joystick-get-product-version joystickprocedure

See SDL_JoystickGetProductVersion.

Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher.

joystick-get-type joystickprocedure

joystick-get-type-raw joystickprocedure

See SDL_JoystickGetType.

joystick-get-type returns a 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 joystickprocedure

See SDL_JoystickGetVendor.

Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher.

joystick-rumble! low-freq hi-freq duration-msprocedure

See SDL_JoystickRumble.

Requires SDL 2.0.9 or higher, and sdl2 egg 0.4.0 or higher.

lock-joysticks!procedure

See SDL_LockJoysticks.

Requires SDL 2.0.7 or higher, and sdl2 egg 0.4.0 or higher.

unlock-joysticks!procedure

See 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 SDL_Joystick struct.

joystick? objprocedure: Returns #t if obj is an sdl2:joystick.

joystick-instance-id joystickprocedure

See SDL_JoystickInstanceID.

Signals an exception of kind (exn sdl2) if an error occurs.

joystick-name joystickprocedure

See SDL_JoystickName.

Returns #f if no name can be found.

joystick-get-guid joystickprocedure

See SDL_JoystickGetGUID.

Returns a new managed sdl2:joystick-guid.

joystick-attached? joystickprocedure: See SDL_JoystickGetAttached.

joystick-current-power-level joystickprocedure

See SDL_JoystickCurrentPowerLevel.

Returns a joystick power level symbol.

Requires SDL 2.0.4 or higher, and sdl2 egg 0.2.0 or higher.

joystick-num-axes joystickprocedure

See SDL_JoystickNumAxes.

Signals an exception of kind (exn sdl2) if an error occurs.

joystick-num-balls joystickprocedure

See SDL_JoystickNumBalls.

Signals an exception of kind (exn sdl2) if an error occurs.

joystick-num-buttons joystickprocedure

See SDL_JoystickNumButtons.

Signals an exception of kind (exn sdl2) if an error occurs.

joystick-num-hats joystickprocedure

See SDL_JoystickNumHats.

Signals an exception of kind (exn sdl2) if an error occurs.

joystick-get-axis joystick axis-numprocedure

See 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-numprocedure

See 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-numprocedure

See 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-numprocedure

joystick-get-hat-raw joystick hat-numprocedure

See SDL_JoystickGetHat.

joystick-get-hat returns a 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 SDL_JoystickGUID struct.

joystick-guid? objprocedure: Returns #t if obj is an sdl2:joystick-guid.

free-joystick-guid! guidprocedure: 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 strprocedure

See SDL_JoystickGetGUIDFromString.

Returns a new managed sdl2:joystick-guid.

joystick-get-guid-string guidprocedure: See SDL_JoystickGetGUIDString.

Keyboard

Keyboard Functions

get-key-from-name name-strprocedure

get-key-from-name-raw name-strprocedure

See SDL_GetKeyFromName.

get-key-from-name returns a keyboard keycode symbol.
get-key-from-name-raw returns an integer.

get-key-from-scancode scancodeprocedure

get-key-from-scancode-raw scancodeprocedure

See SDL_GetKeyFromScancode.

scancode must be a keyboard scancode symbol or an integer representing a keyboard scancode.

get-key-from-scancode returns a keyboard keycode symbol.
get-key-from-scancode-raw returns an integer.

get-key-name keyprocedure

See SDL_GetKeyName.

key must be a keyboard keycode symbol or an integer representing a keyboard keycode.

get-scancode-from-name name-strprocedure

get-scancode-from-name-raw name-strprocedure

See SDL_GetScancodeFromName.

get-scancode-from-name returns a keyboard scancode symbol.
get-scancode-from-name-raw returns an integer.

get-scancode-from-key keyprocedure

get-scancode-from-key-raw keyprocedure

See SDL_GetScancodeFromKey.

key must be a keyboard keycode symbol or an integer representing a keyboard keycode.

get-scancode-from-key returns a keyboard scancode symbol.
get-scancode-from-key-raw returns an integer.

get-scancode-name scancodeprocedure

See SDL_GetScancodeName.

scancode must be a keyboard scancode symbol or an integer representing a keyboard scancode.

get-keyboard-focusprocedure: See SDL_GetKeyboardFocus.

scancode-pressed? scancodeprocedure

Returns #t if the keyboard key with the given scancode is currently being pressed.

scancode must be either a 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 SDL_GetKeyboardState.

mod-stateprocedure

mod-state-rawprocedure

(set! (mod-state) state)setter

mod-state-set! statesetter

See SDL_GetModState.

mod-state returns a list of zero or more 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! rectsetter

rect can be an sdl2:rect or #f.

See SDL_SetTextInputRect.

start-text-input!procedure: See SDL_StartTextInput.

stop-text-input!procedure: See SDL_StopTextInput.

text-input-active?procedure: See SDL_IsTextInputActive.

screen-keyboard-support?procedure: See SDL_HasScreenKeyboardSupport.

screen-keyboard-shown? windowprocedure: See SDL_IsScreenKeyboardShown.

sdl2:keysym

sdl2:keysym is a record type that wraps a pointer to an SDL_Keysym struct.

keysym? objprocedure: Returns #t if obj is an sdl2:keysym.

make-keysym #!optional scancode sym modprocedure

make-keysym* #!optional scancode sym modprocedure

Allocate and initialize a new sdl2:keysym.

scancode defaults to 'unknown. It must be a keyboard scancode symbol or equivalent integer.

sym defaults to 'unknown. It must be a keyboard keycode symbol or equivalent integer.

mod defaults to '(). It must be a list of zero or more 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! keysymprocedure: 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 keysymprocedure

keysym-scancode-raw keysymprocedure

set! (keysym-scancode keysym) valsetter

keysym-scancode-set! keysym valsetter

Get or set the sdl2:keysym's "scancode" field, indicating the physical key that this keysym describes.

keysym-scancode returns a keyboard scancode symbol.
keysym-scancode-raw returns an integer.
The setters accept either a symbol or an integer.

keysym-sym keysymprocedure

keysym-sym-raw keysymprocedure

set! (keysym-sym keysym) valsetter

keysym-sym-set! keysym valsetter

Get or set the sdl2:keysym's "sym" field, indicating the logical key that this keysym describes.

keysym-sym returns a keyboard keycode symbol.
keysym-sym-raw returns an integer.
The setters accept either a symbol or an integer.

keysym-mod keysymprocedure

keysym-mod-raw keysymprocedure

set! (keysym-mod keysym) valsetter

keysym-mod-set! keysym valsetter

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 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! enabledprocedure

See 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-stateprocedure

get-global-mouse-state-rawprocedure

See SDL_GetGlobalMouseState. These procedures return multiple values:

get-global-mouse-state returns a list of zero or more 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-focusprocedure

See SDL_GetMouseFocus.

Requires sdl2 egg 0.4.0 or higher.

get-mouse-stateprocedure

get-mouse-state-rawprocedure

See SDL_GetMouseState.

get-mouse-state returns a list of zero or more 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-modeprocedure

(set! (get-relative-mouse-mode) boolean)setter

relative-mouse-mode-set! booleansetter

See SDL_GetRelativeMouseMode.

Requires sdl2 egg 0.4.0 or higher.

get-relative-mouse-stateprocedure

get-relative-mouse-state-rawprocedure

See SDL_GetRelativeMouseState.

get-relative-mouse-state returns a list of zero or more 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 yprocedure

See SDL_WarpMouseGlobal.

Requires SDL 2.0.4 or higher, and sdl2 egg 0.4.0 or higher.

warp-mouse-in-window! window x yprocedure

See SDL_WarpMouseInWindow.

Requires sdl2 egg 0.4.0 or higher.

OpenGL

OpenGL Functions

gl-create-context! windowprocedure

See SDL_GL_CreateContext.

Signals an exception of kind (exn sdl2) if an error occurs.

gl-delete-context! gl-contextprocedure: See SDL_GL_DeleteContext.

gl-make-current! window gl-contextprocedure

See SDL_GL_MakeCurrent.

Signals an exception of kind (exn sdl2) if an error occurs.

gl-get-current-windowprocedure

See SDL_GL_GetCurrentWindow.

Signals an exception of kind (exn sdl2) if an error occurs.

gl-get-current-contextprocedure

See SDL_GL_GetCurrentContext.

Signals an exception of kind (exn sdl2) if an error occurs.

gl-attribute attrprocedure

set! (gl-attribute attr) valuesetter

gl-attribute-set! attr valuesetter

See SDL_GL_GetAttribute and SDL_GL_SetAttribute.

attr must be an OpenGL attribute symbol or corresponding integer.

The value's type depends on attr:

If attr is 'context-profile-mask, the value will be an 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 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 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!procedure

See SDL_GL_ResetAttributes.

Requires SDL 2.0.2 or higher.

gl-get-drawable-size windowprocedure

See SDL_GL_GetDrawableSize.

This procedure returns multiple values.

Requires SDL 2.0.1 or higher.

gl-swap-window!procedure: See SDL_GL_SwapWindow.

gl-swap-intervalprocedure

(set! (gl-swap-interval) interval)setter

gl-set-swap-interval! intervalsetter

See SDL_GL_GetSwapInterval and SDL_GL_SetSwapInterval.

The setters signal an exception of kind (exn sdl2) if an error occurs.

gl-extension-supported? name-stringprocedure: See SDL_GL_ExtensionSupported.

gl-bind-texture! textureprocedure

Bind the given sdl2:texture for use with the current OpenGL context. See 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! textureprocedure

Unbind the given sdl2:texture from the OpenGL context. See 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? objprocedure: Returns #t if obj is an sdl2:gl-context.

Palette

sdl2:palette

sdl2:palette is a record type that wraps a pointer to an SDL_Palette struct.

palette? objprocedure: Returns #t if obj is an sdl2:palette.

make-palette #!optional ncolorsprocedure

make-palette* #!optional ncolorsprocedure

Allocate and initialize a new sdl2:palette with the given number of colors. See 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! paletteprocedure

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 SDL_FreePalette.

palette-ncolors paletteprocedure
palette-ncolours paletteprocedure: 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 iprocedure

(set! (palette-ref palette i) color)setter

palette-set! palette i colorsetter

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 paletteprocedure

palette-colours paletteprocedure

set! (palette-colors palette) colors-vecsetter

set! (palette-colours palette) colors-vecsetter

palette-colors-set! colors-vec #!optional firstcolorsetter

palette-colours-set! colors-vec #!optional firstcolorsetter

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 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 bprocedure
map-rgba pixel-format r g b aprocedure: See SDL_MapRGB and SDL_MapRGBA.

get-rgb pixel pixel-formatprocedure

get-rgba pixel pixel-formatprocedure

See SDL_GetRGB and SDL_GetRGBA.

These procedures return multiple values.

pixel-format-enum-to-masks format-enumprocedure

See SDL_PixelFormatEnumToMasks.

format-enum must be a 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 SDL_PixelFormat struct.

pixel-format? objprocedure: Returns #t if obj is an sdl2:pixel-format.

make-pixel-format #!optional formatprocedure

make-pixel-format* #!optional formatprocedure

Allocate and initialize a new sdl2:pixel-format with the given format.

format defaults to 'unknown. It must be a pixel format symbol or equivalent integer. See 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-formatprocedure

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 SDL_FreeFormat.

pixel-format-format pixel-formatprocedure

pixel-format-format-raw pixel-formatprocedure

Get the sdl2:pixel-format's "format" field.

pixel-format-format returns a pixel format symbol.
pixel-format-format-raw returns an integer.

pixel-format-palette pixel-formatprocedure

set! (pixel-format-palette pixel-format) valsetter

pixel-format-palette-set! pixel-format valsetter

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 SDL_SetPixelFormatPalette.

The setters signal an exception of kind (exn sdl2) if an error occurs.

pixel-format-bits-per-pixel pixel-formatprocedure: 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-formatprocedure: 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-formatprocedure: Get the sdl2:pixel-format's "rmask" (red mask) field, as a nonnegative integer.

pixel-format-gmask pixel-formatprocedure: Get the sdl2:pixel-format's "gmask" (green mask) field, as a nonnegative integer.

pixel-format-bmask pixel-formatprocedure: Get the sdl2:pixel-format's "bmask" (blue mask) field, as a nonnegative integer.

pixel-format-amask pixel-formatprocedure: 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? rectprocedure: Returns #t if rect's width and/or height is less than or equal to zero. See SDL_RectEmpty.

point-in-rect? point rectprocedure

Returns #t if the sdl2:point is inside the sdl2:rect, or #f if it is not. See SDL_PointInRect.

Requires SDL 2.0.4 or higher, and sdl2 egg 0.2.0 or higher.

enclose-points points #!optional clip result-rectprocedure

See 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 rect2procedure: Returns #t if rect1 and rect2 intersect, or #f if they do not. See SDL_HasIntersection.

intersect-rect rect1 rect2 #!optional result-rectprocedure

Calculates the intersection of rect1 and rect2. See 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 y2procedure

Calculates the intersection between rect and the line segment described by x1, y1, x2, and y2. See 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-rectprocedure

See 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 SDL_Rect struct.

rect? objprocedure: Returns #t if obj is an sdl2:rect.

make-rect #!optional x y w hprocedure

make-rect* #!optional x y w hprocedure

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! rectprocedure: 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 rectprocedure
set! (rect-x rect) valsetter
rect-x-set! rect valsetter: Get or set the sdl2:rect's "x" field, as an integer in the range -2147483648 to 2147483647 (inclusive).

rect-y rectprocedure
set! (rect-y rect) valsetter
rect-y-set! rect valsetter: Get or set the sdl2:rect's "y" field, as an integer in the range -2147483648 to 2147483647 (inclusive).

rect-w rectprocedure
set! (rect-w rect) valsetter
rect-w-set! rect valsetter: Get or set the sdl2:rect's "w" (width) field, as an integer in the range -2147483648 to 2147483647 (inclusive).

rect-h rectprocedure
set! (rect-h rect) valsetter
rect-h-set! rect valsetter: 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 hprocedure: 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 rectprocedure: Returns a list (x y w h) containing the value of each field of the sdl2:rect.

rect->values rectprocedure: 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 rect2procedure: 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 SDL_RectEquals.

rect-copy srcprocedure

rect-copy! src destprocedure

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 factorprocedure

rect-scale! rect factor #!optional destprocedure

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 factorprocedure

rect-unscale! rect factor #!optional destprocedure

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 dyprocedure

rect-move! rect dx dy #!optional destprocedure

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 pointprocedure

rect-add-point! rect point #!optional destprocedure

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 pointprocedure

rect-sub-point! rect point #!optional destprocedure

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 dhprocedure

rect-grow! rect dw dh #!optional destprocedure

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 dhprocedure

rect-grow/center! rect dw dh #!optional destprocedure

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 tprocedure

rect-lerp! rect1 rect2 t #!optional destprocedure

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 tprocedure

rect-lerp-xy! rect1 rect2 t #!optional destprocedure

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.

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 SDL_Point struct.

point? objprocedure: Returns #t if obj is an sdl2:point.

make-point #!optional x yprocedure

make-point* #!optional x yprocedure

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! pointprocedure: 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 pointprocedure
set! (point-x point) valsetter
point-x-set! point valsetter: Get or set the sdl2:point's "x" field, as an integer in the range -2147483648 to 2147483647 (inclusive).

point-y pointprocedure
set! (point-y point) valsetter
point-y-set! point valsetter: 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 yprocedure: 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 pointprocedure: Returns a list (x y) containing the value of each field of the sdl2:point.

point->values pointprocedure: 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 point2procedure: 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 srcprocedure

point-copy! src destprocedure

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 factorprocedure

point-scale! point factor #!optional destprocedure

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 factorprocedure

point-unscale! point factor #!optional destprocedure

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 dyprocedure

point-move! point dx dy #!optional destprocedure

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 point2procedure

point-add! point1 point2 #!optional destprocedure

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 point2procedure

point-sub! point1 point2 #!optional destprocedure

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 tprocedure

point-lerp! point1 point2 t #!optional destprocedure

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 2D Accelerated Rendering. See also Texture.

Renderer support is available in sdl2 egg 0.2.0 and higher.

Renderer Functions

create-renderer! window #!optional index flagsprocedure

Create a new sdl2:renderer associated with the given window. See 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 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! surfaceprocedure

Create a sdl2:renderer which renders onto the given sdl2:surface. See SDL_CreateSoftwareRenderer.

Signals an exception of kind (exn sdl2) if an error occurs.

Requires sdl2 egg 0.2.0 or higher.

destroy-renderer! rendererprocedure

See SDL_DestroyRenderer.

Requires sdl2 egg 0.2.0 or higher.

create-window-and-renderer! width height #!optional window-flagsprocedure

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 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 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 windowprocedure

Return the renderer associated with the given sdl2:window. See 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-driversprocedure

See SDL_GetNumRenderDrivers.

Requires sdl2 egg 0.2.0 or higher.

render-driver-info indexprocedure

See SDL_GetRenderDriverInfo.

Requires sdl2 egg 0.2.0 or higher.

render-present! rendererprocedure

Update the renderer to show any changes that have occurred. See SDL_RenderPresent.

Requires sdl2 egg 0.2.0 or higher.

render-copy! renderer texture #!optional srcrect dstrectprocedure

Copy all or part of the given texture onto the renderer. See 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 flipprocedure

Copy all or part of the given texture onto the renderer, optionally rotating or flipping the texture. See 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 pitchprocedure

Read the pixels from some or all of the given renderer. This is for advanced users, and must be used with caution. See 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 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! rendererprocedure

Clear the entire renderer, using the renderer's current draw color. See SDL_RenderClear.

Requires sdl2 egg 0.2.0 or higher.

render-draw-line! renderer x1 y1 x2 y2procedure

render-draw-lines! renderer pointsprocedure

Draw a line segment or multiple line segments, using the renderer's current draw color and blend mode. See SDL_RenderDrawLine and 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 yprocedure

render-draw-points! renderer pointsprocedure

Draw one or multiple points, using the renderer's current draw color and blend mode. See SDL_RenderDrawPoint and 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 rectprocedure

render-draw-rects! renderer rectsprocedure

Draw one or multiple outlined rectangles, using the renderer's current draw color and blend mode. See SDL_RenderDrawRect and 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 rectprocedure

render-fill-rects! renderer rectsprocedure

Draw one or multiple filled rectangles, using the renderer's current draw color and blend mode. See SDL_RenderFillRect and 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? objprocedure

Returns #t if obj is an sdl2:renderer.

Requires sdl2 egg 0.2.0 or higher.

render-draw-blend-mode rendererprocedure

render-draw-blend-mode-raw rendererprocedure

set! (render-draw-blend-mode renderer) modesetter

render-draw-blend-mode-set! renderer modesetter

Get or set the renderer's draw blend mode. This affects future drawing operations. See SDL_GetRenderDrawBlendMode and SDL_SetRenderDrawBlendMode.

render-draw-blend-mode returns a 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 rendererprocedure

render-draw-colour rendererprocedure

set! (render-draw-color renderer) colorsetter

set! (render-draw-colour renderer) colorsetter

render-draw-color-set! renderer colorsetter

render-draw-colour-set! renderer colorsetter

Get or set the renderer's draw color. This affects future drawing operations. See SDL_GetRenderDrawColor and SDL_SetRenderDrawColor.

Requires sdl2 egg 0.2.0 or higher.

render-clip-rect rendererprocedure

set! (render-clip-rect renderer) rectsetter

render-clip-rect-set! renderer rectsetter

Get or set the sdl2:renderer's clip rect. See SDL_RenderGetClipRect and SDL_RenderSetClipRect.

render-clip-rect returns a new managed sdl2:rect describing the renderer's clip rect. If clipping is disabled, it returns #<sdl2:rect (0 0 0 0)>.

But, be advised that it also returns #<sdl2:rect (0 0 0 0)> if that is the current clip rect. So, the meaning of #<sdl2:rect (0 0 0 0)> 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 #<sdl2:rect (0 0 0 0)> does not disable clipping.

Requires sdl2 egg 0.2.0 or higher.

render-clip-enabled? rendererprocedure

Returns #t if clipping is enabled for the given sdl2:renderer, or #f is clipping is disabled. See SDL_RenderIsClipEnabled.

Requires SDL 2.0.4 or higher, and sdl2 egg 0.2.0 or higher.

render-integer-scale? rendererprocedure

set! (render-integer-scale? renderer) booleansetter

render-integer-scale-set! renderer booleansetter

See SDL_RenderIntegerScale.

Requires SDL 2.0.5 or higher, and sdl2 egg 0.4.0 or higher.

renderer-output-size rendererprocedure

See 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 rendererprocedure

set! (render-logical-size renderer) sizesetter

render-logical-size-set! renderer sizesetter

Get or set the renderer's logical size. See SDL_RenderGetLogicalSize and 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 rendererprocedure

set! (render-scale-set! renderer) scalessetter

render-scale-set! renderer scalessetter

Get or set the sdl2:renderer's x and y scaling factors. See SDL_RenderGetScale and 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? rendererprocedure

Returns #t if the given renderer can have a render target. See SDL_RenderTargetSupported.

Requires sdl2 egg 0.2.0 or higher.

render-target rendererprocedure

set! (render-target renderer) targetsetter

render-target-set! renderer targetsetter

Get or set the renderer's render target, i.e. the texture that the renderer will render onto. See SDL_GetRenderTarget and 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 rendererprocedure

set! (render-viewport renderer) rectsetter

render-viewport-set! renderer rectsetter

Get or set the renderer's viewport. See SDL_RenderGetViewport and 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 SDL_RendererInfo struct. sdl2:renderer-info is available in sdl2 egg 0.2.0 and higher.

renderer-info? objprocedure

Returns #t if obj is an sdl2:renderer-info.

Requires sdl2 egg 0.2.0 or higher.

get-renderer-info rendererprocedure

get-renderer-info* rendererprocedure

Return a sdl2:renderer-info with information about the given sdl2:renderer. See 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-infoprocedure

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-infoprocedure

Get the sdl2:renderer-info's "name" field, as a string.

Requires sdl2 egg 0.2.0 or higher.

renderer-info-flags renderer-infoprocedure

renderer-info-flags-raw renderer-infoprocedure

Get the sdl2:renderer-info's "flags" field.

render-info-flags returns a list of 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-infoprocedure

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-infoprocedure

renderer-info-texture-formats-raw renderer-infoprocedure

Get the sdl2:renderer-info's "texture-formats" field.

renderer-info-texture-formats returns a list of 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-infoprocedure

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-infoprocedure

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 filepathprocedure

See 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 pointerprocedure

See 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 pointerprocedure

See 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 blobprocedure

Create a new sdl2:rwops that accesses the memory of the given 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 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 object-evict the blob and create the sdl2:rwops from the evicted blob (not the original). You may wish to 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 strprocedure

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 object-evict the string and create the sdl2:rwops from the evicted string (not the original). You may wish to 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! rwopsprocedure

See 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 SDL_RWops struct.

rwops? objprocedure: Returns #t if obj is an sdl2:rwops.

rwops-type rwopsprocedure

rwops-type-raw rwopsprocedure

Get the sdl2:rwops' "type" field, indicating the data source type.

rwops-type returns a RWops type symbol.
rwops-type-raw returns an integer.

Surface

Surface Functions

create-rgb-surface* flags width height depth rmask gmask bmask amaskprocedure

Returns a new unmanaged sdl2:surface with the given properties. See 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 amaskprocedure

Returns a new unmanaged sdl2:surface with the given properties, using existing pixel data (a pointer, e.g. from surface-pixels-raw). See SDL_CreateRGBSurfaceFrom.

Signals an exception of kind (exn sdl2) if the surface cannot be created.

create-rgb-surface-with-format* flags width height depth formatprocedure

Returns a new unmanaged sdl2:surface with the given properties. See SDL_CreateRGBSurfaceWithFormat.

See make-surface for a more convenient interface.

format must be a 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 formatprocedure

Returns a new unmanaged sdl2:surface with the given properties, using existing pixel data (a pointer, e.g. from surface-pixels-raw). See SDL_CreateRGBSurfaceWithFormatFrom.

pixels must be a pointer or locative to pixel data in the correct format.
format must be a 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-formatprocedure

convert-surface* surface pixel-formatprocedure

Creates a copy of the given sdl2:surface, but converts it to the given sdl2:pixel-format.

See 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 surfaceprocedure

duplicate-surface* surfaceprocedure

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 SDL_DuplicateSurface. With earlier SDL versions, it uses SDL_ConvertSurface.

Requires sdl2 egg version 0.4.0 or higher.

load-bmp filepathprocedure

load-bmp* filepathprocedure

Attempts to load a BMP image file. Returns a sdl2:surface containing the image data. See SDL_LoadBMP.

Note: This procedure only supports certain kinds of BMP image. Use the 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?procedure

load-bmp-rw* rwops #!optional close?procedure

Attempts to load a BMP image from the given sdl2:rwops. Returns a sdl2:surface containing the image data. See 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 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 filepathprocedure

See SDL_SaveBMP.

Signals an exception of kind (exn sdl2) if an error occurs.

save-bmp-rw! surface rwops #!optional close?procedure

See 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! surfaceprocedure

unlock-surface! surfaceprocedure

See SDL_LockSurface and SDL_UnlockSurface.

lock-surface! signals an exception of kind (exn sdl2) if an error occurs.

must-lock? surfaceprocedure: See SDL_MUSTLOCK.

blit-surface! src src-rect dst dst-rectprocedure

Blit (copy) image data from the src (source) sdl2:surface to the dst (destination) sdl2:surface. See 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-rectprocedure

Blit (copy) image data from the src (source) sdl2:surface to the dst (destination) sdl2:surface, scaling the image if needed. See 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 colorprocedure

See 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 colorprocedure

See 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 yprocedure

surface-ref-raw surface x yprocedure

(set! (surface-ref surface x y) color)setter

surface-set! surface x y colorsetter

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 turnsprocedure

rotate-surface-90* surface turnsprocedure

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?procedure

flip-surface* surface flip-x? flip-y?procedure

Return a copy of the given surface flipped on the X (horizontal) and/or Y (vertical) axes.

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-operationprocedure

See SDL_ComposeCustomBlendMode.

src-color-factor, dst-color-factor, src-alpha-factor, dst-alpha-factor must be blend factor symbols or equivalent integers.
color-operation and alpha-operation must be blend operation symbols or equivalent integers.

Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher.

get-yuv-conversion-modeprocedure

get-yuv-conversion-mode-rawprocedure

(set! (get-yuv-conversion-mode) mode)setter

yuv-conversion-mode-set! modesetter

See SDL_GetYUVConversionMode and SDL_SetYUVConversionMode.

get-yuv-conversion-mode returns a a 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 SDL_Surface struct.

surface? objprocedure: Returns #t if obj is an sdl2:surface.

make-surface width height depth/formatprocedure

make-surface* width height depth/formatprocedure

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 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! surfaceprocedure

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 SDL_FreeSurface.

Note: if surface was created using create-rgb-surface-from, then the pixel data is not freed.

surface-format surfaceprocedure: Get the sdl2:surface's "format" field, as a sdl2:pixel-format describing the format of the surface's pixels.

surface-w surfaceprocedure: Get the sdl2:surface's "w" field, as a nonnegative integer indicating the surface's width in pixels.

surface-h surfaceprocedure: Get the sdl2:surface's "h" field, as a nonnegative integer indicating the surface's height in pixels.

surface-pitch surfaceprocedure: 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 surfaceprocedure

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 surfaceprocedure

set! (surface-userdata-raw surface) valsetter

surface-userdata-raw-set! surface valsetter

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 evict the object first. Otherwise the object's location in memory might change, rendering the pointer invalid.

surface-refcount surfaceprocedure
set! (surface-refcount surface) valsetter
surface-refcount-set! surface valsetter: Get or set the sdl2:surface's "refcount" field, as an integer.

surface-clip-rect surfaceprocedure

set! (surface-clip-rect surface) rectsetter

surface-clip-rect-set! surface rectsetter

surface-clip-rect returns a copy of the surface's clip rect. See 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 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? surfaceprocedure

surface-colour-key? surfaceprocedure

Returns #t if surface has a color key.

With SDL 2.0.9 and higher, this uses SDL_HasColorKey. With earlier SDL versions, this uses SDL_GetColorKey.

Requires sdl2 egg 0.4.0 or higher.

surface-color-key surfaceprocedure

surface-colour-key surfaceprocedure

surface-color-key-raw surfaceprocedure

surface-colour-key-raw surfaceprocedure

set! (surface-color-key surface) colorsetter

set! (surface-colour-key surface) colorsetter

surface-color-key-set! surface colorsetter

surface-colour-key-set! surface colorsetter

Get or set the sdl2:surface's color key.

See SDL_GetColorKey and 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 surfaceprocedure

set! (surface-alpha-mod surface) modsetter

surface-alpha-mod-set! surface modsetter

See SDL_GetSurfaceAlphaMod and SDL_SetSurfaceAlphaMod.

These procedures signal an exception of kind (exn sdl2) if an error occurs.

surface-blend-mode surfaceprocedure

surface-blend-mode-raw surfaceprocedure

set! (surface-blend-mode surface) modesetter

surface-blend-mode-set! surface modesetter

See SDL_GetSurfaceBlendMode and SDL_SetSurfaceBlendMode.

surface-blend-mode returns a 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 surfaceprocedure

surface-colour-mod surfaceprocedure

set! (surface-color-mod surface) rgbsetter

set! (surface-colour-mod surface) rgbsetter

surface-color-mod-set! surface rgbsetter

surface-colour-mod-set! surface rgbsetter

See SDL_GetSurfaceColorMod and 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 surfaceprocedure

set! (surface-palette surface) palettesetter

surface-palette-set! surface palettesetter

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 SDL_SetSurfacePalette.

surface-rle? surfaceprocedure

set! (surface-rle? surface) boolsetter

surface-rle-set! surface boolsetter

See SDL_HasSurfaceRLE and 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 2D Accelerated Rendering. See also 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 SDL_Texture struct.

Textures are available in sdl2 egg 0.2.0 and higher.

texture? objprocedure

Returns #t if obj is an sdl2:texture.

Requires sdl2 egg 0.2.0 or higher.

create-texture renderer format access w hprocedure

create-texture* renderer format access w hprocedure

Create a new sdl2:texture using the given sdl2:renderer and settings.

renderer must be a sdl2:renderer.
format must be a pixel format enum symbol or equivalent integer.
access must be a 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 surfaceprocedure

create-texture-from-surface* renderer surfaceprocedure

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! textureprocedure

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 SDL_DestroyTexture.

Requires sdl2 egg 0.2.0 or higher.

query-texture textureprocedure

query-texture-raw textureprocedure

Get multiple pieces of information about the texture. See SDL_QueryTexture.

query-texture returns multiple values:

format: The sdl2:texture's pixel format, as a pixel format enum symbol
access: The sdl2:texture's access mode, as a 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:

Requires sdl2 egg 0.2.0 or higher.

texture-format textureprocedure

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 textureprocedure

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 textureprocedure

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 textureprocedure

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 textureprocedure

set! (texture-alpha-mod texture) modsetter

texture-alpha-mod-set! texture modsetter

See SDL_GetTextureAlphaMod and 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 textureprocedure

texture-blend-mode-raw textureprocedure

set! (texture-blend-mode texture) modesetter

texture-blend-mode-set! texture modesetter

See SDL_GetTextureBlendMode and SDL_SetTextureBlendMode.

texture-blend-mode returns a 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 textureprocedure

texture-colour-mod textureprocedure

set! (texture-color-mod texture) rgbsetter

set! (texture-colour-mod texture) rgbsetter

texture-color-mod-set! texture rgbsetter

texture-colour-mod-set! texture rgbsetter

See SDL_GetTextureColorMod and 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 rectprocedure

Lock the texture so that its pixel data can be overwritten. This is for advanced users, and must be used with caution. See 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! textureprocedure

Unlock the texture, applying the new pixel data to the texture. This is for advanced users, and must be used with caution. See SDL_UnlockTexture. See also lock-texture-raw!.

Requires sdl2 egg 0.2.0 or higher.

update-texture-raw! texture rect pixels pitchprocedure

Overwrite part or all of the texture's pixel data. This is for advanced users, and must be used with caution. See 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-pitchprocedure

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 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! millisecondsprocedure

See SDL_Delay.

Caution: This procedure is not compatible with 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-ticksprocedure: See SDL_GetTicks.

get-performance-counterprocedure: See SDL_GetPerformanceCounter.

get-performance-frequencyprocedure: See SDL_GetPerformanceFrequency.

Touch / Gesture

Touch / Gesture Functions

get-num-touch-devicesprocedure: See SDL_GetNumTouchDevices.

get-touch-device device-idprocedure

See SDL_GetTouchDevice.

Signals an exception of kind (exn sdl2) if an error occurs.

get-touch-device-type touch-idprocedure

get-touch-device-type-raw touch-idprocedure

See SDL_GetTouchDeviceType.

get-touch-device-type returns a 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-idprocedure: See SDL_GetNumTouchFingers.

get-touch-finger touch-id indexprocedure

See 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 SDL_Finger struct.

finger? objprocedure: Returns #t if obj is an sdl2:finger.

finger-id fingerprocedure: Get the sdl2:finger's "id" field, as an integer.

finger-x fingerprocedure: 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 fingerprocedure: 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 fingerprocedure: 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 patchprocedure

See 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-versionprocedure

current-versionprocedure

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 SDL_VERSION and SDL_GetVersion.

egg-versionconstant

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! pathprocedure

See 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!procedure

See SDL_Vulkan_UnloadLibrary.

Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher.

vulkan-get-vk-get-instance-proc-addrprocedure

See SDL_Vulkan_GetVkGetInstanceProcAddr.

Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher.

vulkan-get-instance-extensions windowprocedure

See 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 windowprocedure

This procedure returns multiple values. See SDL_Vulkan_GetDrawableSize.

Requires SDL 2.0.6 or higher, and sdl2 egg 0.4.0 or higher.

vulkan-create-surface window vkinstance vksurface-outprocedure

See 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 flagsprocedure

See 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 window flag symbols or an equivalent integer bitfield.

destroy-window! windowprocedure: See SDL_DestroyWindow.

get-window-from-id idprocedure

See 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! windowprocedure

See SDL_UpdateWindowSurface.

Signals an exception of kind (exn sdl2) if an error occurs.

update-window-surface-rects! window rectsprocedure

See SDL_UpdateWindowSurfaceRects.

rects must be a list of sdl2:rects.

Signals an exception of kind (exn sdl2) if an error occurs.

show-window! windowprocedure: See SDL_ShowWindow.

hide-window! windowprocedure: See SDL_HideWindow.

maximize-window! windowprocedure: See SDL_MaximizeWindow.

minimize-window! windowprocedure: See SDL_MinimizeWindow.

raise-window! windowprocedure: See SDL_RaiseWindow.

restore-window! windowprocedure: See SDL_RestoreWindow.

flash-window! window operationprocedure

See SDL_FlashWindow.

operation must be a 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-windowprocedure

See 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 SDL_Window struct.

window? objprocedure: Returns #t if obj is an sdl2:window.

window-always-on-top? windowprocedure

set! (window-always-on-top? window) boolsetter

window-always-on-top-set! window boolsetter

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 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? windowprocedure

set! (window-bordered? window) borderedsetter

window-bordered-set! window borderedsetter

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 SDL_SetWindowBordered.

window-borders-size windowprocedure

This procedure returns multiple values. See SDL_GetWindowBordersSize.

Requires SDL 2.0.5 or higher, and sdl2 egg 0.4.0 or higher.

window-brightness windowprocedure

set! (window-brightness window) brightnesssetter

window-brightness-set! window brightnesssetter

See SDL_GetWindowBrightness and SDL_SetWindowBrightness.

The setters signal an exception of kind (exn sdl2) if an error occurs.

window-display-index windowprocedure

See SDL_GetWindowDisplayIndex.

Signals an exception of kind (exn sdl2) if an error occurs.

window-display-mode windowprocedure

set! (window-display-mode window) display-modesetter

window-display-mode-set! window display-modesetter

See SDL_GetWindowDisplayMode and SDL_SetWindowDisplayMode.

These procedures signal an exception of kind (exn sdl2) if an error occurs.

window-flags windowprocedure

window-flags-raw windowprocedure

See SDL_GetWindowFlags.

window-flags returns a list of window flag symbols.
window-flags-raw returns an integer bitfield.

window-fullscreen windowprocedure

set! (window-fullscreen window) modesetter

window-fullscreen-set! window modesetter

Get or set the sdl2:window's fullscreen mode. See 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? windowprocedure
set! (window-grab? window) grabbedsetter
window-grab-set! window grabbedsetter: See SDL_GetWindowGrab and SDL_SetWindowGrab.

window-keyboard-grab? windowprocedure

set! (window-keyboard-grab? window) grabbedsetter

window-keyboard-grab-set! window grabbedsetter

See SDL_GetWindowKeyboardGrab and SDL_SetWindowKeyboardGrab.

Requires SDL 2.0.16 or higher, and sdl2 egg 0.4.0 or higher.

window-mouse-grab? windowprocedure

set! (window-mouse-grab? window) grabbedsetter

window-mouse-grab-set! window grabbedsetter

See SDL_GetWindowMouseGrab and SDL_SetWindowMouseGrab.

Requires SDL 2.0.16 or higher, and sdl2 egg 0.4.0 or higher.

grabbed-windowprocedure

Returns the sdl2:window that currently has input grab, or #f if no window has input grab. See 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-surfacesetter: See SDL_SetWindowIcon.

window-id windowprocedure: See SDL_GetWindowID.

window-maximum-size windowprocedure

set! (window-maximum-size window) sizesetter

window-maximum-size-set! window sizesetter

See SDL_GetWindowMaximumSize and SDL_SetWindowMaximumSize.

window-maximum-size returns multiple values.

The setters accept a list of integers (width height).

window-minimum-size windowprocedure

set! (window-minimum-size window) sizesetter

window-minimum-size-set! window sizesetter

See SDL_GetWindowMinimumSize and SDL_SetWindowMinimumSize.

window-minimum-size returns multiple values.

The setters accept a list of integers (width height).

window-opacity windowprocedure

set! (window-opacity window) opacitysetter

window-opacity-set! window opacitysetter

See SDL_GetWindowOpacity and SDL_SetWindowOpacity.

Requires SDL 2.0.5 or higher, and sdl2 egg 0.4.0 or higher.

window-pixel-format windowprocedure

window-pixel-format-raw windowprocedure

Returns a symbol or integer indicating the given window's pixel format. See SDL_GetWindowPixelFormat.

window-pixel-format returns a pixel format symbol.
window-pixel-format-raw returns an integer.

window-position windowprocedure

set! (window-position window) possetter

window-position-set! window possetter

See SDL_GetWindowPosition and SDL_SetWindowPosition.

window-position returns multiple values.

The setters accept a list of integers (x y).

window-resizable? windowprocedure

set! (window-resizable? window) boolsetter

window-resizable-set! window boolsetter

See 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 windowprocedure

set! (window-size window) sizesetter

window-size-set! window sizesetter