sdl2 (historical revision 32856) - The CHICKEN Scheme wiki

You are looking at historical revision 32856 of this page. It may differ significantly from its current revision.

sdl2

sdl2
Introduction
Help Wanted!
Requirements
Installation
Usage and Examples
Related Libraries
Version History
API

Introduction

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 (john+chicken at croisant dot net)
License: BSD 2-Clause

Help Wanted!

This egg needs volunteers to help with several things:

Writing API reference docs, guides, and tutorials
Writing unit tests and semi-automated test programs
Testing on different platforms and helping create good installation instructions
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.

The unit tests depend on the test egg, and many demos and examples depend on the miscmacros egg. Some demos and examples have other dependencies as well.

Installation

ATTENTION: The sdl2 egg has not been released yet. For now, you must download it from its source code repository and follow the instructions in the README.

When installing the egg, you should set the SDL2_FLAGS environment variable to a string of compiler flags to be used when compiling the egg. If you have the sdl2-config helper program installed on your system, you can set appropriate flags and install the extension like so (notice these are back ticks, not quotes):

export SDL2_FLAGS=`sdl2-config --cflags --libs`
chicken-install sdl2

If you do not have the sdl2-config helper program installed on your computer, you may manually specify SDL-related compiler flags (notice these are double quotes, not back ticks):

export SDL2_FLAGS="-I/usr/local/include/SDL2 -L/usr/local/lib -lSDL2"
chicken-install sdl2

The SDL2_FLAGS environment variable only needs to be set during installation of the egg, not during normal use.

Usage and Examples

It is recommended that you import the sdl2 module using the prefix "sdl2:", like so:

(use (prefix sdl2 sdl2:))
(sdl2:init! '(everything))
(sdl2:create-window! "Test" 0 0 600 400)
(sdl2:delay! 1000)
(sdl2:quit!)

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.

The sdl2-image egg provides bindings to version 2 of the SDL_image library. It is built to be compatible with sdl2.

The sdl-base egg provides bindings to older versions of SDL. Its API is not compatible with sdl2.

Version History

The sdl2 egg has not yet been released. Coming soon!

API

Conventions

Procedure names are lower case and hyphenated, with no "SDL_" prefix.
Procedures that return #t or #f are suffixed with "?".
Procedures that cause a mutation or side effect are suffixed with "!".
Procedures that set the value of an attribute are named like TYPE-ATTR-set!, e.g. rect-x-set!.
- In most cases, it is also possible to use (set! ...) to set the value of attributes, e.g. (set! (rect-x my-rect) 42).
Some procedures return multiple values, e.g. window-size returns two values, the width and height. You can use receive, let-values, etc. to catch all the return values.
Procedures that allocate a new object often have two versions, one without an asterisk and one with an asterisk, e.g. make-surface and make-surface*. See the Struct Record Types section for more information.
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-or'd integer flags or masks.

Enums

The sdl2 egg uses symbols instead of integer constants, for things like event types, keyboard keys, and init flags. See the enum tables for details.

Struct Record Types

The sdl2 egg has many "struct record types", which are record types that wrap a pointer to a certain kind of C structure from SDL. For example, the sdl2:surface record type wraps a pointer to an SDL_Surface struct.

Each struct record type has some associated procedures, which get or set the value of a certain field of the underlying C struct. Some struct record types also have procedures for allocating or freeing an instance of that type. Every type that can be allocated, has two allocator procedures, one without an asterisk and one with an asterisk:

The procedure without an asterisk (e.g. alloc-event) returns a record whose underlying struct will be automatically freed when the record is garbage collected. (This is accomplished using set-finalizer!.) Unless you have a good reason to do manual memory management, you should use this procedure, not the procedure with an asterisk.
The procedure with an asterisk (e.g. alloc-event*) returns a record that must be manually freed when you are done with it, e.g. using free-event!. This is slightly more efficient, especially if you are allocating hundreds or thousands of objects, but your program will leak memory if you forget to free it.

Some struct record types, such as sdl2:window, are not allocated or freed. Instead, you use certain SDL functions to manage them, such as create-window! and destroy-window!.

[procedure] (struct-null? record) → boolean

Returns #t if the given record is wrapping a null pointer (i.e. a pointer with memory address 0). This procedure can be used with any struct record type provided by this library.

There are two common reasons why a record might be wrapping a null pointer:

After you manually free a record (e.g. using free-surface!), its pointer will be set to null.
Certain procedures may return a record with a null pointer if an error occurs or the requested object does not exist.

It is an error to get or set any field of a record that is wrapping a null pointer. And, in is an error to pass null struct records to certain procedures. So, you can use this procedure to check whether it is safe to use the record.

sdl2:audio-cvt

sdl2:audio-cvt is a record type that wraps a pointer to an SDL_AudioCVT struct.

[procedure] (audio-cvt? obj) → boolean

Returns #t if obj is an sdl2:audio-cvt.

[procedure] (audio-cvt-needed audio-cvt) → fixnum

Get the value of the SDL_AudioCVT's "needed" field, as an integer.

[procedure] (audio-cvt-src-format audio-cvt) → symbol

Get the value of the SDL_AudioCVT's "src_format" field, as an audio format symbol.

[procedure] (audio-cvt-src-format-raw audio-cvt) → fixnum

Get the value of the SDL_AudioCVT's "src_format" field, as an integer. See also audio-cvt-src-format.

[procedure] (audio-cvt-dst-format audio-cvt) → symbol

Get the value of the SDL_AudioCVT's "dst_format" field, as an audio format symbol.

[procedure] (audio-cvt-dst-format-raw audio-cvt) → fixnum

Get the value of the SDL_AudioCVT's "dst_format" field, as an integer. See also audio-cvt-dst-format.

[procedure] (audio-cvt-rate-incr audio-cvt) → double

Get the value of the SDL_AudioCVT's "rate_incr" field, as a double precision floating point number.

[procedure] (audio-cvt-buf-raw audio-cvt) → pointer

Get the value of the SDL_AudioCVT's "buf" field, as a pointer to a C array of Uint8 numbers. Use audio-cvt-len to get the length of the array.

[procedure] (audio-cvt-len audio-cvt) → fixnum

Get the value of the SDL_AudioCVT's "len" field, as an integer. This is the length of the array returned by audio-cvt-buf-raw.

[procedure] (audio-cvt-len-cvt audio-cvt) → fixnum

Get the value of the SDL_AudioCVT's "len_cvt" field, as an integer.

[procedure] (audio-cvt-len-mult audio-cvt) → fixnum

Get the value of the SDL_AudioCVT's "len_mult" field, as an integer.

[procedure] (audio-cvt-len-ratio audio-cvt) → double

Get the value of the SDL_AudioCVT's "len_ratio" field, as a double precision floating point number.

sdl2:audio-spec

sdl2:audio-spec is a record type that wraps a pointer to an SDL_AudioSpec struct.

[procedure] (audio-spec? obj) → boolean

Returns #t if obj is an sdl2:audio-spec.

[procedure] (audio-spec-freq audio-spec) → fixnum
[setter] (set! (audio-spec-freq audio-spec) val)
[setter] (audio-spec-freq-set! audio-spec freq)

Get or set the value of the SDL_AudioSpec's "freq" field, as an integer (int).

[procedure] (audio-spec-format audio-spec) → symbol
[setter] (set! (audio-spec-format audio-spec) format)
[setter] (audio-spec-format-set! audio-spec format)

Get or set the value of the SDL_AudioSpec's "format" field, as an audio format symbol. When setting, either a symbol or an integer will be accepted.

[procedure] (audio-spec-format-raw audio-spec) → fixnum
[setter] (set! (audio-spec-format-raw audio-spec) val)

Get or set the value of the SDL_AudioSpec's "format" field, as an integer. See also audio-spec-format.

[procedure] (audio-spec-channels audio-spec) → fixnum
[setter] (set! (audio-spec-channels audio-spec) val)
[setter] (audio-spec-channels-set! audio-spec channels)

Get or set the value of the SDL_AudioSpec's "channels" field, as an integer (Uint8).

[procedure] (audio-spec-silence audio-spec) → fixnum

Returns the value of the SDL_AudioSpec's "silence" field, as an integer (Uint8).

[procedure] (audio-spec-samples audio-spec) → fixnum
[setter] (set! (audio-spec-samples audio-spec) val)
[setter] (audio-spec-samples-set! audio-spec samples)

Get or set the value of the SDL_AudioSpec's "samples" field, as an integer (Uint16).

[procedure] (audio-spec-size audio-spec) → fixnum

Returns the value of the SDL_AudioSpec's "size" field, as an integer (Uint32).

[procedure] (audio-spec-userdata-raw audio-spec) → pointer
[setter] (set! (audio-spec-userdata-raw audio-spec) val)
[setter] (audio-spec-userdata-raw-set! audio-spec userdata)

Get or set the value of the SDL_AudioSpec's "userdata" field, as a pointer.

sdl2:color

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

Procedures related to sdl2:color each have an alias spelled as "colour", for the convenience of anyone who spells it that way. Aside from the name difference, the procedures behave exactly the same.

[procedure] (color? obj) → boolean
[procedure] (colour? obj) → boolean

Returns #t if obj is an sdl2:color.

[procedure] (make-color #!optional r g b a) → sdl2:color
[procedure] (make-colour #!optional r g b a) → sdl2:color

Allocate and initialize a new sdl2:color instance. The instance will have a finalizer, so that the underlying struct's memory will automatically be freed when the record instance is garbage collected. It is not necessary to call free-color!, although it is safe to do so.

r g b and a are the red, green, blue, and alpha (opacity) fields of the color. They must be integers in the range 0 to 255 (inclusive). r g and b default to 0. a defaults to 255 (full opacity).

[procedure] (alloc-color) → sdl2:color
[procedure] (alloc-colour) → sdl2:color

Allocate (but do not initialize) a new sdl2:color instance. You probably want to use make-color instead.

The instance will have a finalizer, so that the underlying struct's memory will automatically be freed when the record instance is garbage collected. It is not necessary to call free-color!, although it is safe (and sometimes useful) to do so.

[procedure] (alloc-color*) → sdl2:color
[procedure] (alloc-colour*) → sdl2:color

Allocate (but do not initialize) a new sdl2:color instance. This is like alloc-color, except that the instance will not have a finalizer, so the underlying struct's memory will not be automatically freed when the instance is garbage collected. You must manually call free-color! on the record instance when you are done with it; otherwise, your program will leak memory.

[procedure] (free-color! color)
[procedure] (free-colour! color)

Manually free the memory of the given sdl2:color instance. The instance's pointer will be set to null (see struct-null?), so you cannot get or set any field of the instance after it has been freed. It is safe to free an instance that has a finalizer. It is safe to free an instance that has already been freed.

[procedure] (color-r color) → fixnum
[procedure] (colour-r color) → fixnum
[setter] (set! (color-r color) r)
[setter] (set! (colour-r color) r)
[setter] (color-r-set! color r)
[setter] (colour-r-set! color r)

Get or set the "r" (red) field of the sdl2:color, as an integer in the range 0 to 255 (inclusive).

[procedure] (color-g color) → fixnum
[procedure] (colour-g color) → fixnum
[setter] (set! (color-g color) g)
[setter] (set! (colour-g color) g)
[setter] (color-g-set! color g)
[setter] (colour-g-set! color g)

Get or set the "g" (green) field of the sdl2:color, as an integer in the range 0 to 255 (inclusive).

[procedure] (color-b color) → fixnum
[procedure] (colour-b color) → fixnum
[setter] (set! (color-b color) b)
[setter] (set! (colour-b color) b)
[setter] (color-b-set! color b)
[setter] (colour-b-set! color b)

Get or set the "b" (blue) field of the sdl2:color, as an integer in the range 0 to 255 (inclusive).

[procedure] (color-a color) → fixnum
[procedure] (colour-a color) → fixnum
[setter] (set! (color-a color) a)
[setter] (set! (colour-a color) a)
[setter] (color-a-set! color a)
[setter] (colour-a-set! color a)

Get or set the "a" (alpha) field of the sdl2:color, as an integer in the range 0 to 255 (inclusive).

[setter] (color-set! color #!optional r g b a) → color
[setter] (colour-set! color #!optional r g b a) → color

Set multiple fields of the sdl2:color. If any of the arguments are not #f, that field of the color will be set. Any arguments that are #f will cause no change to that field of the color. Returns color after it is modified.

[procedure] (color->list color) → list of fixnums
[procedure] (colour->list color) → list of fixnums

Returns a list (r g b a) containing all the fields of the sdl2:color.

sdl2:cursor

sdl2:cursor is a record type that wraps a pointer to an SDL_Cursor struct.

[procedure] (cursor? obj) → boolean

Returns #t if obj is an sdl2:cursor.

sdl2:display-mode

sdl2:display-mode is a record type that wraps a pointer to an SDL_DisplayMode struct.

[procedure] (display-mode? obj) → boolean

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

[procedure] (alloc-display-mode) → sdl2:display-mode

Allocate (but do not initialize) a new sdl2:display-mode instance.

The instance will have a finalizer, so that the underlying struct's memory will automatically be freed when the record instance is garbage collected. It is not necessary to call free-display-mode!, although it is safe (and sometimes useful) to do so.

[procedure] (alloc-display-mode*) → sdl2:display-mode

Like alloc-display-mode, except that the instance will not have a finalizer, so the underlying struct's memory will not be automatically freed when the instance is garbage collected. You must manually call free-display-mode! on the record instance when you are done with it; otherwise, your program will have a memory leak.

[procedure] (free-display-mode! display-mode)

Manually free the memory of the given sdl2:display-mode instance. The instance's pointer will be set to null (see struct-null?), so you cannot get or set any field of the instance after it has been freed. It is safe to free an instance that has a finalizer. It is safe to free an instance that has already been freed.

[procedure] (display-mode-format display-mode) → symbol
[setter] (set! (display-mode-format display-mode) val)
[setter] (display-mode-format-set! display-mode)

TODO: Docs. Returns a pixel format symbol.

[procedure] (display-mode-format-raw display-mode) → fixnum
[setter] (set! (display-mode-format-raw display-mode) val)

TODO: Docs. See also display-mode-format.

[procedure] (display-mode-w display-mode) → fixnum
[setter] (set! (display-mode-w display-mode) val)
[setter] (display-mode-w-set! display-mode)

TODO: Docs.

[procedure] (display-mode-h display-mode) → fixnum
[setter] (set! (display-mode-h display-mode) val)
[setter] (display-mode-h-set! display-mode)

TODO: Docs.

[procedure] (display-mode-refresh-rate display-mode) → fixnum
[setter] (set! (display-mode-refresh-rate display-mode) val)
[setter] (display-mode-refresh-rate-set! display-mode)

TODO: Docs.

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 record 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: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 symbols
sdl2:window-event	SDL_WindowEvent	window

[procedure] (event? obj) → boolean

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

[procedure] (alloc-event) → sdl2:event

Allocate (but do not initialize) a new sdl2:event instance. You can set the event's type with event-type-set! to choose what variant of sdl2:event it should be.

The instance will have a finalizer, so that the underlying struct's memory will automatically be freed when the record instance is garbage collected. It is not necessary to call free-event!, although it is safe (and sometimes useful) to do so.

[procedure] (alloc-event*) → sdl2:event

Like alloc-event, except that the instance will not have a finalizer, so the underlying struct's memory will not be automatically freed when the instance is garbage collected. You must manually call free-event! on the record instance when you are done with it; otherwise, your program will leak memory.

[procedure] (free-event! event)

Manually free the memory of the given sdl2:event. You can use this procedure with any variant of sdl2:event. The instance's pointer will be set to null (see struct-null?), so you cannot get or set any field of the instance after it has been freed. It is safe to free an instance that has a finalizer. It is safe to free an instance that has already been freed.

[procedure] (event-type event) → symbol
[setter] (set! (event-type event) val)
[setter] (event-type-set! event val)

Get or set the sdl2:event's event type, as a event type symbol. You can use this procedure with any variant of sdl2:event. Setting this will change what variant of sdl2:event it is. E.g. if you set it to the symbol 'key-down, the event will become an sdl2:keyboard-event.

[procedure] (event-type-raw event) → fixnum
[setter] (set! (event-type-raw event) val)
[setter] (event-type-raw-set! event val)

Get or set the sdl2:event's event type, as a nonnegative integer. You can use this procedure with any variant of sdl2:event. See also event-type.

[procedure] (event-timestamp event) → fixnum
[setter] (set! (event-timestamp event) val)
[setter] (event-timestamp-set! event val)

Get or set the event timestamp, as a nonnegative integer representing the time that the event occurred, in milliseconds since the SDL timer system was initialized. You can use this procedure 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.

[procedure] (controller-axis-event? obj) → boolean

Returns #t if obj is an sdl2:controller-axis-event.

[procedure] (controller-axis-event-which event) → fixnum
[setter] (set! (controller-axis-event-which event) val)
[setter] (controller-axis-event-which-set! event val)

TODO: Docs.

[procedure] (controller-axis-event-axis event) → fixnum
[setter] (set! (controller-axis-event-axis event) val)
[setter] (controller-axis-event-axis-set! event val)

TODO: Docs.

[procedure] (controller-axis-event-value event) → fixnum
[setter] (set! (controller-axis-event-value event) val)
[setter] (controller-axis-event-value-set! event val)

TODO: Docs.

sdl2:controller-button-event

sdl2:controller-button-event is a variant of sdl2:event that wraps a pointer to an SDL_ControllerButtonEvent.

[procedure] (controller-button-event? obj) → boolean

TODO: Docs.

[procedure] (controller-button-event-which event) → fixnum
[setter] (set! (controller-button-event-which event) val)
[setter] (controller-button-event-which-set! event val)

TODO: Docs.

[procedure] (controller-button-event-button event) → fixnum
[setter] (set! (controller-button-event-button event) val)
[setter] (controller-button-event-button-set! event val)

TODO: Docs.

[procedure] (controller-button-event-state event) → boolean
[setter] (set! (controller-button-event-state event) val)
[setter] (controller-button-event-state-set! event val)

TODO: Docs.

sdl2:controller-device-event

sdl2:controller-device-event is a variant of sdl2:event that wraps a pointer to an SDL_ControllerDeviceEvent.

[procedure] (controller-device-event? obj) → boolean

Returns #t if obj is an sdl2:controller-device-event.

[procedure] (controller-device-event-which event) → fixnum
[setter] (set! (controller-device-event-which event) val)
[setter] (controller-device-event-which-set! event val)

TODO: Docs.

sdl2:dollar-gesture-event

sdl2:dollar-gesture-event is a variant of sdl2:event that wraps a pointer to an SDL_DollarGestureEvent.

[procedure] (dollar-gesture-event? obj) → boolean

Returns #t if obj is an sdl2:dollar-gesture-event.

[procedure] (dollar-gesture-event-touch-id event) → fixnum
[setter] (set! (dollar-gesture-event-touch-id event) val)
[setter] (dollar-gesture-event-touch-id-set! event val)

TODO: Docs.

[procedure] (dollar-gesture-event-gesture-id event) → fixnum
[setter] (set! (dollar-gesture-event-gesture-id event) val)
[setter] (dollar-gesture-event-gesture-id-set! event val)

TODO: Docs.

[procedure] (dollar-gesture-event-num-fingers event) → fixnum
[setter] (set! (dollar-gesture-event-num-fingers event) val)
[setter] (dollar-gesture-event-num-fingers-set! event val)

TODO: Docs.

[procedure] (dollar-gesture-event-error event) → float
[setter] (set! (dollar-gesture-event-error event) val)
[setter] (dollar-gesture-event-error-set! event val)

TODO: Docs.

[procedure] (dollar-gesture-event-x event) → float
[setter] (set! (dollar-gesture-event-x event) val)
[setter] (dollar-gesture-event-x-set! event val)

TODO: Docs.

[procedure] (dollar-gesture-event-y event) → float
[setter] (set! (dollar-gesture-event-y event) val)
[setter] (dollar-gesture-event-y-set! event val)

TODO: Docs.

sdl2:drop-event

sdl2:drop-event is a variant of sdl2:event that wraps a pointer to an SDL_DropEvent.

[procedure] (drop-event? obj) → boolean

Returns #t if obj is an sdl2:drop-event.

[procedure] (drop-event-file event) → string
[setter] (set! (drop-event-file event) val)
[setter] (drop-event-file-set! event val)

TODO: Docs.

sdl2:joy-axis-event

sdl2:joy-axis-event is a variant of sdl2:event that wraps a pointer to an SDL_JoyAxisEvent.

[procedure] (joy-axis-event? obj) → boolean

Returns #t if obj is an sdl2:joy-axis-event.

[procedure] (joy-axis-event-which event) → fixnum
[setter] (set! (joy-axis-event-which event) val)
[setter] (joy-axis-event-which-set! event val)

Returns the joystick ID number of the joystick that caused the event.

[procedure] (joy-axis-event-axis event) → fixnum
[setter] (set! (joy-axis-event-axis event) val)
[setter] (joy-axis-event-axis-set! event val)

Returns the number of the axis that was moved.

[procedure] (joy-axis-event-value event) → fixnum
[setter] (set! (joy-axis-event-value event) val)
[setter] (joy-axis-event-value-set! event val)

Returns the new value of the axis, as an integer in the range -32768 to 32767 (inclusive).

sdl2:joy-ball-event

sdl2:joy-ball-event is a variant of sdl2:event that wraps a pointer to an SDL_JoyBallEvent.

[procedure] (joy-ball-event? obj) → boolean

Returns #t if obj is an sdl2:joy-ball-event.

[procedure] (joy-ball-event-which event) → fixnum
[setter] (set! (joy-ball-event-which event) val)
[setter] (joy-ball-event-which-set! event val)

Returns the joystick ID number of the joystick that caused the event.

[procedure] (joy-ball-event-ball event) → fixnum
[setter] (set! (joy-ball-event-ball event) val)
[setter] (joy-ball-event-ball-set! event val)

Returns the number of the trackball that was moved.

[procedure] (joy-ball-event-xrel event) → fixnum
[setter] (set! (joy-ball-event-xrel event) val)
[setter] (joy-ball-event-xrel-set! event val)

Returns an integer (possibly negative) indicating how the trackball position changed on the X axis, relative to its previous position.

[procedure] (joy-ball-event-yrel event) → fixnum
[setter] (set! (joy-ball-event-yrel event) val)
[setter] (joy-ball-event-yrel-set! event val)

Returns an integer (possibly negative) indicating how the trackball position changed on the Y axis, 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.

[procedure] (joy-button-event? obj) → boolean

Returns #t if obj is an sdl2:joy-button-event.

[procedure] (joy-button-event-which event) → fixnum
[setter] (set! (joy-button-event-which event) val)
[setter] (joy-button-event-which-set! event val)

Returns the joystick ID number of the joystick that caused the event.

[procedure] (joy-button-event-button event) → fixnum
[setter] (set! (joy-button-event-button event) val)
[setter] (joy-button-event-button-set! event val)

Returns the number of the button that was pressed or released.

[procedure] (joy-button-event-state event) → boolean
[setter] (set! (joy-button-event-state event) val)
[setter] (joy-button-event-state-set! event val)

Returns #t if the button was pressed, or #f if the button was released. 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.

[procedure] (joy-device-event? obj) → boolean

Returns #t if obj is an sdl2:joy-device-event.

[procedure] (joy-device-event-which event) → fixnum
[setter] (set! (joy-device-event-which event) val)
[setter] (joy-device-event-which-set! event val)

Returns the joystick ID number of the joystick that caused the event.

sdl2:joy-hat-event

sdl2:joy-hat-event is a variant of sdl2:event that wraps a pointer to an SDL_JoyHatEvent.

[procedure] (joy-hat-event? obj) → boolean

Returns #t if obj is an sdl2:joy-hat-event.

[procedure] (joy-hat-event-which event) → fixnum
[setter] (set! (joy-hat-event-which event) val)
[setter] (joy-hat-event-which-set! event val)

Returns the joystick ID number of the joystick that caused the event.

[procedure] (joy-hat-event-hat event) → fixnum
[setter] (set! (joy-hat-event-hat event) val)
[setter] (joy-hat-event-hat-set! event val)

Returns the number of the hat that was moved.

[procedure] (joy-hat-event-value event) → symbol
[setter] (set! (joy-hat-event-value event) val)
[setter] (joy-hat-event-value-set! event val)

Returns a joystick hat position symbol indicating the new joystick hat position.

[procedure] (joy-hat-event-value-raw event) → fixnum
[setter] (set! (joy-hat-event-value-raw event) val)
[setter] (joy-hat-event-value-raw-set! event val)

Returns an integer indicating the new joystick hat position. See also joy-hat-event-value.

sdl2:keyboard-event

sdl2:keyboard-event is a variant of sdl2:event that wraps a pointer to an SDL_KeyboardEvent.

[procedure] (keyboard-event? obj) → boolean

Returns #t if obj is an sdl2:keyboard-event.

[procedure] (keyboard-event-window-id event) → fixnum
[setter] (set! (keyboard-event-window-id event) val)
[setter] (keyboard-event-window-id-set! event val)

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

[procedure] (keyboard-event-state event) → boolean
[setter] (set! (keyboard-event-state event) val)
[setter] (keyboard-event-state-set! event val)

Returns #t if the key was pressed, or #f if the key was released. You can also find out by checking the event type: 'key-down for pressed, or 'key-up for released.

[procedure] (keyboard-event-repeat event) → fixnum
[setter] (set! (keyboard-event-repeat event) val)
[setter] (keyboard-event-repeat-set! event val)

Returns non-zero if this is a "key repeat" event (caused by the user pressing and holding the key for some time), or zero if this is not a "key repeat" event.

[procedure] (keyboard-event-keysym event) → sdl2:keysym
[setter] (set! (keyboard-event-keysym event) val)
[setter] (keyboard-event-keysym-set! event val)

Returns a copy of the sdl2:keysym representing the key that was pressed or released. Modifying the returned sdl2:keysym will not change the event, but setting this field to a new sdl2:keysym will change the event.

Instead of using this procedure, it is more efficient and convenient to directly access the fields of the event's keysym, using these procedures:

keyboard-event-sym
keyboard-event-scancode
keyboard-event-mod

[procedure] (keyboard-event-sym event) → symbol
[setter] (set! (keyboard-event-sym event) val)
[setter] (keyboard-event-sym-set! event val)

Returns a keyboard keycode symbol representing the key that was pressed or released. Setting this will change the event.

[procedure] (keyboard-event-sym-raw event) → fixnum
[setter] (set! (keyboard-event-sym-raw event) val)
[setter] (keyboard-event-sym-raw-set! event val)

Returns an integer representing a keyboard keycode of the key that was pressed or released. Setting this will change the event. See also keyboard-event-sym.

[procedure] (keyboard-event-scancode event) → symbol
[setter] (set! (keyboard-event-scancode event) val)
[setter] (keyboard-event-scancode-set! event val)

Returns a keyboard scancode symbol representing the key that was pressed or released. Setting this will change the event.

[procedure] (keyboard-event-scancode-raw event) → fixnum
[setter] (set! (keyboard-event-scancode-raw event) val)
[setter] (keyboard-event-scancode-raw-set! event val)

Returns an integer representing a keyboard scancode of the key that was pressed or released. Setting this will change the event. See also keyboard-event-scancode.

[procedure] (keyboard-event-mod event) → list of symbols
[setter] (set! (keyboard-event-mod event) val)
[setter] (keyboard-event-mod-set! event val)

Returns a list of zero or more keyboard modifier symbols, representing the modifier keys that were being pressed at the time the event occurred. Setting this will change the event.

[procedure] (keyboard-event-mod-raw event) → fixnum
[setter] (set! (keyboard-event-mod-raw event) val)
[setter] (keyboard-event-mod-raw-set! event val)

Returns an integer representing a bitfield of keyboard modifiers, representing the modifier keys that were being pressed at the time the event occurred. Setting this will change the event. See also keyboard-event-mod.

sdl2:mouse-button-event

sdl2:mouse-button-event is a variant of sdl2:event that wraps a pointer to an SDL_MouseButtonEvent.

[procedure] (mouse-button-event? obj) → boolean

Returns #t if obj is an sdl2:mouse-button-event.

[procedure] (mouse-button-event-window-id event) → fixnum
[setter] (set! (mouse-button-event-window-id event) val)
[setter] (mouse-button-event-window-id-set! event val)

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

[procedure] (mouse-button-event-which event) → fixnum
[setter] (set! (mouse-button-event-which event) val)
[setter] (mouse-button-event-which-set! event val)

TODO: Docs.

[procedure] (mouse-button-event-button event) → symbol
[setter] (set! (mouse-button-event-button event) val)
[setter] (mouse-button-event-button-set! event val)

Returns a mouse button symbol indicating which button was pressed or released.

[procedure] (mouse-button-event-button-raw event) → fixnum
[setter] (set! (mouse-button-event-button-raw event) val)
[setter] (mouse-button-event-button-raw-set! event val)

Returns an integer indicating which button was pressed or released. See also mouse-button-event-button.

[procedure] (mouse-button-event-state event) → boolean
[setter] (set! (mouse-button-event-state event) val)
[setter] (mouse-button-event-state-set! event val)

Returns #t if the button was pressed, or #f if the button was released. You can also find out by checking the event type: 'mouse-button-down for pressed, or 'mouse-button-up for released.

[procedure] (mouse-button-event-x event) → fixnum
[setter] (set! (mouse-button-event-x event) val)
[setter] (mouse-button-event-x-set! event val)

Returns the X position (in pixels) of the mouse cursor at the time the button was pressed or released.

[procedure] (mouse-button-event-y event) → fixnum
[setter] (set! (mouse-button-event-y event) val)
[setter] (mouse-button-event-y-set! event val)

Returns the Y position (in pixels) of the mouse cursor at the time the button was pressed or released.

sdl2:mouse-motion-event

sdl2:mouse-motion-event is a variant of sdl2:event that wraps a pointer to an SDL_MouseMotionEvent.

[procedure] (mouse-motion-event? obj) → boolean

Returns #t if obj is an sdl2:mouse-motion-event.

[procedure] (mouse-motion-event-window-id event) → fixnum
[setter] (set! (mouse-motion-event-window-id event) val)
[setter] (mouse-motion-event-window-id-set! event val)

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

[procedure] (mouse-motion-event-which event) → fixnum
[setter] (set! (mouse-motion-event-which event) val)
[setter] (mouse-motion-event-which-set! event val)

TODO: Docs.

[procedure] (mouse-motion-event-state event) → list of symbols
[setter] (set! (mouse-motion-event-state event) val)
[setter] (mouse-motion-event-state-set! event val)

Returns a list of zero or more mouse button mask symbols, representing the mouse buttons that were being pressed at the time this event occurred.

[procedure] (mouse-motion-event-state-raw event) → fixnum
[setter] (set! (mouse-motion-event-state-raw event) val)
[setter] (mouse-motion-event-state-raw-set! event val)

Returns an integer representing the mouse buttons that were being pressed at the time this event occurred. See also mouse-motion-event-state

[procedure] (mouse-motion-event-x event) → fixnum
[setter] (set! (mouse-motion-event-x event) val)
[setter] (mouse-motion-event-x-set! event val)

Returns the X coordinate (in pixels) of the mouse cursor at the time the event occurred.

[procedure] (mouse-motion-event-y event) → fixnum
[setter] (set! (mouse-motion-event-y event) val)
[setter] (mouse-motion-event-y-set! event val)

Returns the Y coordinate (in pixels) of the mouse cursor at the time the event occurred.

[procedure] (mouse-motion-event-xrel event) → fixnum
[setter] (set! (mouse-motion-event-xrel event) val)
[setter] (mouse-motion-event-xrel-set! event val)

Returns how much the mouse cursor moved on the X axis (in pixels) since its previous position.

[procedure] (mouse-motion-event-yrel event) → fixnum
[setter] (set! (mouse-motion-event-yrel event) val)
[setter] (mouse-motion-event-yrel-set! event val)

Returns how much the mouse cursor moved on the Y axis (in pixels) 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.

[procedure] (mouse-wheel-event? obj) → boolean

Returns #t if obj is an sdl2:mouse-wheel-event.

[procedure] (mouse-wheel-event-window-id event) → fixnum
[setter] (set! (mouse-wheel-event-window-id event) val)
[setter] (mouse-wheel-event-window-id-set! event val)

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

[procedure] (mouse-wheel-event-which event) → fixnum
[setter] (set! (mouse-wheel-event-which event) val)
[setter] (mouse-wheel-event-which-set! event val)

TODO: Docs.

[procedure] (mouse-wheel-event-x event) → fixnum
[setter] (set! (mouse-wheel-event-x event) val)
[setter] (mouse-wheel-event-x-set! event val)

TODO: Docs.

[procedure] (mouse-wheel-event-y event) → fixnum
[setter] (set! (mouse-wheel-event-y event) val)
[setter] (mouse-wheel-event-y-set! event val)

TODO: Docs.

sdl2:multi-gesture-event

sdl2:multi-gesture-event is a variant of sdl2:event that wraps a pointer to an SDL_MultiGestureEvent.

[procedure] (multi-gesture-event? obj) → boolean

Returns #t if obj is an sdl2:multi-gesture-event.

[procedure] (multi-gesture-event-touch-id event) → fixnum
[setter] (set! (multi-gesture-event-touch-id event) val)
[setter] (multi-gesture-event-touch-id-set! event val)

TODO: Docs.

[procedure] (multi-gesture-event-dtheta event) → float
[setter] (set! (multi-gesture-event-dtheta event) val)
[setter] (multi-gesture-event-dtheta-set! event val)

TODO: Docs.

[procedure] (multi-gesture-event-ddist event) → float
[setter] (set! (multi-gesture-event-ddist event) val)
[setter] (multi-gesture-event-ddist-set! event val)

TODO: Docs.

[procedure] (multi-gesture-event-x event) → float
[setter] (set! (multi-gesture-event-x event) val)
[setter] (multi-gesture-event-x-set! event val)

TODO: Docs.

[procedure] (multi-gesture-event-y event) → float
[setter] (set! (multi-gesture-event-y event) val)
[setter] (multi-gesture-event-y-set! event val)

TODO: Docs.

[procedure] (multi-gesture-event-num-fingers event) → fixnum
[setter] (set! (multi-gesture-event-num-fingers event) val)
[setter] (multi-gesture-event-num-fingers-set! event val)

TODO: Docs.

sdl2:quit-event

sdl2:quit-event is a variant of sdl2:event that wraps a pointer to an SDL_QuitEvent.

[procedure] (quit-event? obj) → boolean

Returns #t if obj is an sdl2:quit-event.

sdl2:sys-wm-event

sdl2:sys-wm-event is a variant of sdl2:event that wraps a pointer to an SDL_SysWMEvent.

[procedure] (sys-wm-event? obj) → boolean

Returns #t if obj is an sdl2:sys-wm-event.

[procedure] (sys-wm-event-msg event) → sdl2:sys-wm-msg
[setter] (set! (sys-wm-event-msg event) val)
[setter] (sys-wm-event-msg-set! event val)

TODO: Docs.

sdl2:text-editing-event

sdl2:text-editing-event is a variant of sdl2:event that wraps a pointer to an SDL_TextEditingEvent.

[procedure] (text-editing-event? obj) → boolean

Returns #t if obj is an sdl2:text-editing-event.

[procedure] (text-editing-event-window-id event) → fixnum
[setter] (set! (text-editing-event-window-id event) val)
[setter] (text-editing-event-window-id-set! event val)

TODO: Docs.

[procedure] (text-editing-event-text event) → string
[setter] (set! (text-editing-event-text event) val)
[setter] (text-editing-event-text-set! event val)

TODO: Docs.

[procedure] (text-editing-event-start event) → fixnum
[setter] (set! (text-editing-event-start event) val)
[setter] (text-editing-event-start-set! event val)

TODO: Docs.

[procedure] (text-editing-event-length event) → fixnum
[setter] (set! (text-editing-event-length event) val)
[setter] (text-editing-event-length-set! event val)

TODO: Docs.

sdl2:text-input-event

sdl2:text-input-event is a variant of sdl2:event that wraps a pointer to an SDL_TextInputEvent.

[procedure] (text-input-event? obj) → boolean

Returns #t if obj is an sdl2:text-input-event.

[procedure] (text-input-event-window-id event) → fixnum
[setter] (set! (text-input-event-window-id event) val)
[setter] (text-input-event-window-id-set! event val)

TODO: Docs.

[procedure] (text-input-event-text event) → string
[setter] (set! (text-input-event-text event) val)
[setter] (text-input-event-text-set! event val)

TODO: Docs.

sdl2:touch-finger-event

sdl2:touch-finger-event is a variant of sdl2:event that wraps a pointer to an SDL_TouchFingerEvent.

[procedure] (touch-finger-event? obj) → boolean

Returns #t if obj is an sdl2:touch-finger-event.

[procedure] (touch-finger-event-touch-id event) → fixnum
[setter] (set! (touch-finger-event-touch-id event) val)
[setter] (touch-finger-event-touch-id-set! event val)

TODO: Docs.

[procedure] (touch-finger-event-finger-id event) → fixnum
[setter] (set! (touch-finger-event-finger-id event) val)
[setter] (touch-finger-event-finger-id-set! event val)

TODO: Docs.

[procedure] (touch-finger-event-x event) → float
[setter] (set! (touch-finger-event-x event) val)
[setter] (touch-finger-event-x-set! event val)

TODO: Docs.

[procedure] (touch-finger-event-y event) → float
[setter] (set! (touch-finger-event-y event) val)
[setter] (touch-finger-event-y-set! event val)

TODO: Docs.

[procedure] (touch-finger-event-dx event) → float
[setter] (set! (touch-finger-event-dx event) val)
[setter] (touch-finger-event-dx-set! event val)

TODO: Docs.

[procedure] (touch-finger-event-dy event) → float
[setter] (set! (touch-finger-event-dy event) val)
[setter] (touch-finger-event-dy-set! event val)

TODO: Docs.

[procedure] (touch-finger-event-pressure event) → float
[setter] (set! (touch-finger-event-pressure event) val)
[setter] (touch-finger-event-pressure-set! event val)

TODO: Docs.

sdl2:user-event

sdl2:user-event is a variant of sdl2:event that wraps a pointer to an SDL_UserEvent.

[procedure] (user-event? obj) → boolean

Returns #t if obj is an sdl2:user-event.

[procedure] (user-event-window-id event) → fixnum
[setter] (set! (user-event-window-id event) val)
[setter] (user-event-window-id-set! event val)

TODO: Docs.

[procedure] (user-event-code event) → fixnum
[setter] (set! (user-event-code event) val)
[setter] (user-event-code-set! event val)

TODO: Docs.

[procedure] (user-event-data1-raw event) → pointer
[setter] (set! (user-event-data1-raw event) val)
[setter] (user-event-data1-rawset! event val)

TODO: Docs.

[procedure] (user-event-data2-raw event) → pointer
[setter] (set! (user-event-data2-raw event) val)
[setter] (user-event-data2-raw-set! event val)

TODO: Docs.

sdl2:window-event

sdl2:window-event is a variant of sdl2:event that wraps a pointer to an SDL_WindowEvent.

[procedure] (window-event? obj) → boolean

Returns #t if obj is an sdl2:window-event.

[procedure] (window-event-window-id event) → fixnum
[setter] (set! (window-event-window-id event) val)
[setter] (window-event-window-id-set! event val)

TODO: Docs.

[procedure] (window-event-event event) → symbol
[setter] (set! (window-event-event event) val)
[setter] (window-event-event-set! event val)

Returns a window event type indicating what happened to the window.

[procedure] (window-event-event-raw event) → fixnum
[setter] (set! (window-event-event-raw event) val)
[setter] (window-event-event-raw-set! event val)

Returns an integer indicating what happened to the window. See also window-event-event.

[procedure] (window-event-data1 event) → fixnum
[setter] (set! (window-event-data1 event) val)
[setter] (window-event-data1-set! event val)

Get or set the sdl2:window-event's "data1" field, as an integer. The meaning of this value depends on what kind of window event it was. 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.

[procedure] (window-event-data2 event) → fixnum
[setter] (set! (window-event-data2 event) val)
[setter] (window-event-data2-set! event val)

Get or set the sdl2:window-event's "data2" field, as an integer. The meaning of this value depends on what kind of window event it was. 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.

sdl2:finger

sdl2:finger is a record type that wraps a pointer to an SDL_Finger struct.

[procedure] (finger? obj) → boolean

Returns #t if obj is an sdl2:finger.

[procedure] (finger-id finger) → fixnum

TODO: Docs.

[procedure] (finger-x finger) → float

TODO: Docs.

[procedure] (finger-y finger) → float

TODO: Docs.

[procedure] (finger-pressure finger) → float

TODO: Docs.

sdl2:joystick

sdl2:joystick is a record type that wraps a pointer to an SDL_Joystick struct.

[procedure] (joystick? obj) → boolean

Returns #t if obj is an sdl2:joystick.

sdl2:joystick-guid?

sdl2:joystick-guid is a record type that wraps a pointer to an SDL_JoystickGUID struct.

[procedure] (joystick-guid? obj) → boolean

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

sdl2:keysym

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

[procedure] (keysym? obj) → boolean

Returns #t if obj is an sdl2:keysym.

[procedure] (alloc-keysym) → sdl2:keysym

Allocate (but do not initialize) a new sdl2:keysym instance.

The instance will have a finalizer, so that the underlying struct's memory will automatically be freed when the record instance is garbage collected. It is not necessary to call free-keysym!, although it is safe (and sometimes useful) to do so.

[procedure] (alloc-keysym*) → sdl2:keysym

Like alloc-keysym, except that the instance will not have a finalizer, so the underlying struct's memory will not be automatically freed when the instance is garbage collected. You must manually call free-keysym! on the record instance when you are done with it; otherwise, your program will leak memory.

[procedure] (free-keysym! keysym)

Manually free the memory of the given sdl2:keysym instance. The instance's pointer will be set to null (see struct-null?), so you cannot get or set any field of the instance after it has been freed. It is safe to free an instance that has a finalizer. It is safe to free an instance that has already been freed.

[procedure] (keysym-scancode keysym) → symbol
[setter] (set! (keysym-scancode keysym) val)
[setter] (keysym-scancode-set! keysym)

TODO: Docs. Returns a keyboard scancode symbol.

[procedure] (keysym-scancode-raw keysym) → fixnum
[setter] (set! (keysym-scancode-raw keysym) val)
[setter] (keysym-scancode-raw-set! keysym)

TODO: Docs. See also keysym-scancode.

[procedure] (keysym-sym keysym) → symbol
[setter] (set! (keysym-sym keysym) val)
[setter] (keysym-sym-set! keysym)

TODO: Docs. Returns a keyboard keycode symbol.

[procedure] (keysym-sym-raw keysym) → fixnum
[setter] (set! (keysym-sym-raw keysym) val)
[setter] (keysym-sym-raw-set! keysym)

TODO: Docs. See also keysym-sym.

[procedure] (keysym-mod keysym) → list of symbols
[setter] (set! (keysym-mod keysym) val)
[setter] (keysym-mod-set! keysym)

TODO: Docs. Returns a list of zero or more keyboard modifier symbols.

[procedure] (keysym-mod-raw keysym) → fixnum
[setter] (set! (keysym-mod-raw keysym) val)
[setter] (keysym-mod-raw-set! keysym)

TODO: Docs. See also keysym-mod.

sdl2:palette

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

[procedure] (palette? obj) → boolean

Returns #t if obj is an sdl2:palette.

[procedure] (alloc-palette ncolors) → sdl2:palette

Allocate a new sdl2:palette instance with the given number of colors.

The instance will have a finalizer, so that the underlying struct's memory will automatically be freed when the record instance is garbage collected. It is not necessary to call free-palette!, although it is safe (and sometimes useful) to do so.

[procedure] (alloc-palette*) → sdl2:palette

Like alloc-palette, except that the instance will not have a finalizer, so the underlying struct's memory will not be automatically freed when the instance is garbage collected. You must manually call free-palette! on the record instance when you are done with it; otherwise, your program will leak memory.

[procedure] (free-palette! palette)

Manually free the memory of the given sdl2:palette instance. The instance's pointer will be set to null (see struct-null?), so you cannot get or set any field of the instance after it has been freed. It is safe to free an instance that has a finalizer. It is safe to free an instance that has already been freed.

[procedure] (palette-ncolors palette) → fixnum

Returns the number of colors in the palette. May be as high as 256.

sdl2:pixel-format

sdl2:pixel-format is a record type that wraps a pointer to an SDL_PixelFormat struct.

[procedure] (pixel-format? obj) → boolean

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

[procedure] (alloc-pixel-format pixel-format-enum) → sdl2:pixel-format

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

The instance will have a finalizer, so that the underlying struct's memory will automatically be freed when the record instance is garbage collected. It is not necessary to call free-pixel-format!, although it is safe (and sometimes useful) to do so.

[procedure] (alloc-pixel-format* pixel-format-enum) → sdl2:pixel-format

Like alloc-pixel-format, except that the instance will not have a finalizer, so the underlying struct's memory will not be automatically freed when the instance is garbage collected. You must manually call free-pixel-format! on the record instance when you are done with it; otherwise, your program will have a memory leak.

[procedure] (free-pixel-format! pixel-format)

Manually free the memory of the given sdl2:pixel-format instance. The instance's pointer will be set to null (see struct-null?), so you cannot get or set any field of the instance after it has been freed. It is safe to free an instance that has a finalizer. It is safe to free an instance that has already been freed.

[procedure] (pixel-format-format pixel-format) → symbol

TODO: Docs. Returns a pixel format symbol.

[procedure] (pixel-format-format-raw pixel-format) → fixnum

TODO: Docs. See also pixel-format-format.

[procedure] (pixel-format-palette pixel-format) → sdl2:palette or #f
[setter] (set! (pixel-format-palette pixel-format) val)
[setter] (pixel-format-palette-set! pixel-format palette)

Returns the pixel format's palette (as an sdl2:palette), or #f if it does not have a palette. Only pixel formats with a bits-per-pixel of 8 or less can have a palette.

[procedure] (pixel-format-bits-per-pixel pixel-format) → fixnum

TODO: Docs

[procedure] (pixel-format-bytes-per-pixel pixel-format) → fixnum

TODO: Docs

[procedure] (pixel-format-rmask pixel-format) → fixnum

TODO: Docs

[procedure] (pixel-format-gmask pixel-format) → fixnum

TODO: Docs

[procedure] (pixel-format-bmask pixel-format) → fixnum

TODO: Docs

[procedure] (pixel-format-amask pixel-format) → fixnum

TODO: Docs.

sdl2:point

sdl2:point is a record type that wraps a pointer to an SDL_Point struct.

[procedure] (point? obj) → boolean

Returns #t if obj is an sdl2:point.

[procedure] (make-point #!optional x y) → sdl2:point

Allocate and initialize a new sdl2:point instance. The instance will have a finalizer, so that the underlying struct's memory will automatically be freed when the record instance is garbage collected. It is not necessary to call free-point!, although it is safe to do so.

x and y are the x and y fields of the point. They must be integers in the range -2147483648 to 2147483647 (inclusive). They both default to 0.

[procedure] (alloc-point) → sdl2:point

Allocate (but do not initialize) a new sdl2:point instance. You probably want to use make-point instead.

The instance will have a finalizer, so that the underlying struct's memory will automatically be freed when the record instance is garbage collected. It is not necessary to call free-point!, although it is safe (and sometimes useful) to do so.

[procedure] (alloc-point*) → sdl2:point

Like alloc-point, except that the instance will not have a finalizer, so the underlying struct's memory will not be automatically freed when the instance is garbage collected. You must manually call free-point! on the record instance when you are done with it; otherwise, your program will leak memory.

[procedure] (free-point! point)

Manually free the memory of the given sdl2:point instance. The instance's pointer will be set to null (see struct-null?), so you cannot get or set any field of the instance after it has been freed. It is safe to free an instance that has a finalizer. It is safe to free an instance that has already been freed.

[procedure] (point-x point) → fixnum
[setter] (set! (point-x point) x)
[setter] (point-x-set! point x)

Get or set the "x" field of the sdl2:point, as an integer in the range -2147483648 to 2147483647 (inclusive).

[procedure] (point-y point) → fixnum
[setter] (set! (point-y point) y)
[setter] (point-y-set! point y)

Get or set the "y" field of the sdl2:point, as an integer in the range -2147483648 to 2147483647 (inclusive).

[procedure] (point-set! point #!optional x y) → point

Set multiple fields of the sdl2:point. If any of the arguments are not #f, that field of the point will be set. Any arguments that are #f will cause no change to that field of the point. Returns point after it is modified.

[procedure] (point->list point) → list of fixnums

Returns a list (x y) containing the fields of the sdl2:point.

sdl2:rect

sdl2:rect is a record type that wraps a pointer to an SDL_Rect struct.

[procedure] (rect? obj) → boolean

Returns #t if obj is an sdl2:rect.

[procedure] (make-rect #!optional x y w h) → sdl2:rect

Allocate and initialize a new sdl2:rect instance. The instance will have a finalizer, so that the underlying struct's memory will automatically be freed when the record instance is garbage collected. It is not necessary to call free-rect!, although it is safe to do so.

x, y, w, and h are the fields of the rect. They must be integers in the range -2147483648 to 2147483647 (inclusive). They all default to 0.

[procedure] (alloc-rect) → sdl2:rect

Allocate (but do not initialize) a new sdl2:rect instance. You probably want to use make-rect instead.

[procedure] (alloc-rect*) → sdl2:rect

Like alloc-rect, except that the instance will not have a finalizer, so the underlying struct's memory will not be automatically freed when the instance is garbage collected. You must manually call free-rect! on the record instance when you are done with it; otherwise, your program will leak memory.

[procedure] (free-rect! rect)

Manually free the memory of the given sdl2:rect instance. The instance's recter will be set to null (see struct-null?), so you cannot get or set any field of the instance after it has been freed. It is safe to free an instance that has a finalizer. It is safe to free an instance that has already been freed.

[procedure] (rect-x rect) → fixnum
[setter] (set! (rect-x rect) x)
[setter] (rect-x-set! rect x)

Get or set the "x" field of the sdl2:rect, as an integer in the range -2147483648 to 2147483647 (inclusive).

[procedure] (rect-y rect) → fixnum
[setter] (set! (rect-y rect) y)
[setter] (rect-y-set! rect y)

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

[procedure] (rect-w rect) → fixnum
[setter] (set! (rect-w rect) w)
[setter] (rect-w-set! rect w)

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

[procedure] (rect-h rect) → fixnum
[setter] (set! (rect-h rect) h)
[setter] (rect-h-set! rect h)

Get or set the "h" (height) field of the sdl2:rect, as an integer in the range -2147483648 to 2147483647 (inclusive).

[procedure] (rect-set! rect #!optional x y w h) → rect

Set multiple fields of the sdl2:rect. If any of the arguments are not #f, that field of the rect will be set. Any arguments that are #f will cause no change to that field of the rect. Returns rect after it is modified.

[procedure] (rect->list rect) → list of fixnums

Returns a list (x y w h) containing the fields of the sdl2:rect.

sdl2:rwops

sdl2:rwops is a record type that wraps a pointer to an SDL_RWops struct.

[procedure] (rwops? obj) → boolean

Returns #t if obj is an sdl2:rwops.

[procedure] (rwops-type rwops) → symbol

TODO: Docs

[procedure] (rwops-type-raw rwops) → fixnum

TODO: Docs.

sdl2:surface

sdl2:surface is a record type that wraps a pointer to an SDL_Surface struct.

[procedure] (surface? obj) → boolean

Returns #t if obj is an sdl2:surface.

[procedure] (free-surface! surface)

See SDL_FreeSurface.

Manually free the memory of the given sdl2:surface instance. The instance's pointer will be set to null (see struct-null?), so you cannot get or set any field of the instance after it has been freed. It is safe to free an instance that has a finalizer. It is safe to free an instance that has already been freed.

[procedure] (surface-format surface) → sdl2:pixel-format

TODO: Docs.

[procedure] (surface-w surface) → fixnum

TODO: Docs.

[procedure] (surface-h surface) → fixnum

TODO: Docs.

[procedure] (surface-pitch surface) → fixnum

TODO: Docs.

[procedure] (surface-refcount surface) → fixnum
[setter] (set! (surface-refcount surface) val)
[setter] (surface-refcount-set! surface)

TODO: Docs.

sdl2:sys-wm-info

sdl2:sys-wm-info is a record type that wraps a pointer to an SDL_SysWMinfo struct.

[procedure] (sys-wm-info? obj) → boolean

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

sdl2:sys-wm-msg

sdl2:sys-wm-msg is a record type that wraps a pointer to an SDL_SysWMmsg struct.

[procedure] (sys-wm-msg? obj) → boolean

Returns #t if obj is an sdl2:sys-wm-msg.

sdl2:texture

sdl2:texture is a record type that wraps a pointer to an SDL_Texture struct.

[procedure] (texture? obj) → boolean

Returns #t if obj is an sdl2:texture.

sdl2:version

sdl2:version is a record type that wraps a pointer to an SDL_version struct.

[procedure] (version? obj) → boolean

Returns #t if obj is an sdl2:version.

[procedure] (make-version #!optional major minor patch) → sdl2:version

Allocate and initialize a new sdl2:version instance. The instance will have a finalizer, so that the underlying struct's memory will automatically be freed when the record instance is garbage collected. It is not necessary to call free-version!, although it is safe to do so.

major, minor, and patch are the fields of the version. They must be integers in the range 0 to 255 (inclusive). They all default to 0.

[procedure] (alloc-version) → sdl2:version

Allocate (but do not initialize) a new sdl2:version instance. You probably want to use make-version instead.

The instance will have a finalizer, so that the underlying struct's memory will automatically be freed when the record instance is garbage collected. It is not necessary to call free-version!, although it is safe (and sometimes useful) to do so.

[procedure] (alloc-version*) → sdl2:version

Like alloc-version, except that the instance will not have a finalizer, so the underlying struct's memory will not be automatically freed when the instance is garbage collected. You must manually call free-version! on the record instance when you are done with it; otherwise, your program will leak memory.

[procedure] (free-version! version)

Manually free the memory of the given sdl2:version instance. The instance's versioner will be set to null (see struct-null?), so you cannot get or set any field of the instance after it has been freed. It is safe to free an instance that has a finalizer. It is safe to free an instance that has already been freed.

[procedure] (version-major version) → fixnum
[setter] (set! (version-major version) major)
[setter] (version-major-set! version major)

Get or set the "major" field of the sdl2:version, as an integer in the range 0 to 255 (inclusive).

[procedure] (version-minor version) → fixnum
[setter] (set! (version-minor version) minor)
[setter] (version-minor-set! version minor)

Get or set the "minor" field of the sdl2:version, as an integer in the range 0 to 255 (inclusive).

[procedure] (version-patch version) → fixnum
[setter] (set! (version-patch version) patch)
[setter] (version-patch-set! version patch)

Get or set the "patch" field of the sdl2:version, as an integer in the range 0 to 255 (inclusive).

[procedure] (version-set! version #!optional major minor patch) → version

Set multiple fields of the sdl2:version. If any of the arguments are not #f, that field of the version will be set. Any arguments that are #f will cause no change to that field of the version. Returns version after it is modified.

[procedure] (version->list version) → list of fixnums

Returns a list (major minor patch) containing the fields of the sdl2:version.

sdl2:window

sdl2:window is a record type that wraps a pointer to an SDL_Window struct.

[procedure] (window? obj) → boolean

Returns #t if obj is an sdl2:window.

Procedures

General / Miscellaneous

[procedure] (init! #!optional flags-list) → fixnum

See SDL_Init. Returns zero if successful.

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

'timer
'audio
'video
'joystick
'haptic
'game-controller
'events
'everything

[procedure] (init-subsystem! flags-list) → fixnum

See SDL_InitSubSystem. Returns zero if successful.

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

[procedure] (quit!)

See SDL_Quit.

[procedure] (quit-subsystem! flags-list)

See SDL_QuitSubSystem.

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

[procedure] (was-init #!optional flags-list) → list of symbols

See SDL_WasInit.

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

[procedure] (set-main-ready!)

See SDL_SetMainReady.

[procedure] (clear-error!)

See SDL_ClearError.

[procedure] (get-error) → string

See SDL_GetError.

[procedure] (set-error! message)

See SDL_SetError.

Unlike SDL_SetError, this procedure only accepts one argument, a string. You can use sprintf to do string substitution if desired.

[procedure] (get-platform) → string

See SDL_GetPlatform.

[procedure] (disable-screen-saver!)

See SDL_DisableScreenSaver.

[procedure] (enable-screen-saver!)

See SDL_EnableScreenSaver.

[procedure] (screen-saver-enabled?) → boolean

See SDL_IsScreenSaverEnabled.

[procedure] (has-clipboard-text?) → boolean

See SDL_HasClipboardText.

[procedure] (get-clipboard-text) → string

See SDL_GetClipboardText.

[procedure] (set-clipboard-text! text) → fixnum

See SDL_SetClipboardText. Returns zero if successful.

[procedure] (get-version) → sdl2:version

See SDL_GetVersion.

Returns an sdl2:version instance containing the version number of SDL that the sdl2 egg is currently using. (This may be different than the version it was compiled with.)

[procedure] (get-compiled-version) → sdl2:version

See SDL_VERSION.

Returns an sdl2:version instance containing the version number of SDL that the sdl2 egg was compiled with. (This may be different than the version it is currently using.)

[procedure] (version-at-least? major minor patch) → boolean

See SDL_VERSION_ATLEAST.

Returns #t if the sdl2 egg was compiled with a version of SDL at least as high as specified. E.g. (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.

Pixel Format / Palette

[procedure] (map-rgb pixel-format r g b) → fixnum

See SDL_MapRGB.

[procedure] (map-rgba pixel-format r g b a) → fixnum

See SDL_MapRGBA.

[procedure] (get-rgb pixel pixel-format) → [r g b]

See SDL_GetRGB.

This procedure returns multiple values.

[procedure] (get-rgba pixel pixel-format) → [r g b a]

See SDL_GetRGBA.

This procedure returns multiple values.

[procedure] (palette-ref palette i) → sdl2:color

Return the sdl2:color at the given index of the palette.

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

Set the given index of the palette to the given sdl2:color.

[procedure] (palette-colors palette) → vector of sdl2:colors

Return all colors in the palette, as a Scheme vector of sdl2:colors.

[setter] (palette-colors-set! colors-vec #!optional start) -> fixnum

See SDL_SetPaletteColors.

Set multiple colors in the palette. colors-vec must be a Scheme vector of sdl2:colors. start defaults to 0.

Returns zero if successful.

Events

[procedure] (event-state type) → boolean

See SDL_EventState.

Like calling SDL_EventState with SDL_QUERY. type must be an event type symbol or corresponding integer.

[setter] (set! (event-state type) state) → boolean
[setter] (event-state-set! type state) → boolean

See SDL_EventState.

Like calling SDL_EventState with SDL_ENABLE or SDL_IGNORE.

Returns the previous state of the given event type.

type must be an event type symbol or corresponding integer.

[procedure] (flush-event! type)

See SDL_FlushEvent.

Note: Contrary to what its name suggests, this procedure will flush ALL events matching the given type, not just a single event.

type must be an event type symbol or corresponding integer.

[procedure] (flush-events! #!optional min-type max-type)

See SDL_FlushEvents.

min-type and max-type must be event type symbols or corresponding integers. If omitted, min-type defaults to 'first and max-type defaults to 'last.

[procedure] (has-event? type) → boolean

See SDL_HasEvent.

type must be an event type symbol or corresponding integer.

[procedure] (has-events? #!optional min-type max-type) → boolean

See SDL_HasEvents.

min-type and max-type must be event type symbols or corresponding integers. If omitted, min-type defaults to 'first and max-type defaults to 'last.

[procedure] (quit-requested?) → boolean

See SDL_QuitRequested.

[procedure] (peek-events num #!optional min-type max-type) → list of sdl2:events

See SDL_PeepEvents.

Like SDL_PeepEvents with SDL_PEEKEVENT

This procedure is similar to get-events!, except that procedure removes the events from the SDL event queue.

min-type and max-type must be event type symbols or corresponding integers. If omitted, min-type defaults to 'first and max-type defaults to 'last.

[procedure] (get-events! num #!optional min-type max-type) → list of sdl2:events

See SDL_PeepEvents.

Like SDL_PeepEvents with SDL_GETEVENT

This procedure is similar to peek-events, except that procedure does not remove the events from the SDL event queue.

min-type and max-type must be an event type symbol or corresponding integer. If omitted, min-type defaults to 'first and max-type defaults to 'last.

[procedure] (poll-event! #!optional result-event) → sdl2:event

See SDL_PollEvent.

If result-event is omitted, a new sdl2:event is allocated and returned. If result-event is an existing sdl2:event instance, 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.)

[procedure] (pump-events!)

See SDL_PumpEvents.

[procedure] (push-event! event) → fixnum

See SDL_PushEvent.

Returns 1 if successful.

[procedure] (wait-event! #!optional result-event) → sdl2:event

See SDL_WaitEvent.

[procedure] (wait-event-timeout! timeout #!optional result-event) → sdl2:event

See SDL_WaitEventTimeout.

Please note that the argument order is reversed compared to SDL_WaitEventTimeout. This is to allow the event argument to be optional.

[procedure] (register-events! event-symbols) → list of pairs

Register zero or more symbols as new user event types. After registration, the given symbols may be used as event types, e.g. with event-type-set!. The symbols will be associated with the sdl2:user-event variant of sdl2:event.

event-symbols must be a list of symbols that are not already being used as event types. If any symbol is already being used, or if any member of the list is not a symbol, an error will be signalled and none of the new event types will be registered.

There are 32767 user event type numbers available to register. Each given symbol will be automatically assigned a distinct number. If registering the given symbols would cause you to run out of available numbers, this procedure will signal an error, and none of the new event types will be registered.

This procedure returns an association list (list of pairs) of each of the new event type symbols (as the pair car) with its assigned number (as the pair cdr).

This procedure is based on SDL_RegisterEvents.

[procedure] (get-num-touch-devices) → fixnum

See SDL_GetNumTouchDevices.

[procedure] (get-num-touch-fingers touch-id) → fixnum

See SDL_GetNumTouchFingers.

[procedure] (get-touch-device device-id) → fixnum

See SDL_GetTouchDevice.

[procedure] (get-touch-finger touch-id index) → sdl2:finger

See SDL_GetTouchFinger.

OpenGL integration

[procedure] (gl-create-context! window) → sdl2:gl-context

See SDL_GL_CreateContext.

[procedure] (gl-delete-context! gl-context)

See SDL_GL_DeleteContext.

[procedure] (gl-make-current! window gl-context) → fixnum

See SDL_GL_MakeCurrent.

[procedure] (gl-get-current-window) → sdl2:window

See SDL_GL_GetCurrentWindow.

[procedure] (gl-get-current-context) → sdl2:gl-context

See SDL_GL_GetCurrentContext.

[procedure] (gl-get-attribute attr) → value

See SDL_GL_GetAttribute.

attr must be an OpenGL attribute symbol or corresponding integer.

The return type varies depending on attr:

If attr is 'context-profile-mask, an OpenGL profile symbol will be returned.
If attr is 'context-flags, a list of zero or more OpenGL context flag symbols will be returned.
Otherwise, an integer will be returned.

[procedure] (gl-set-attribute! attr value) → fixnum

See SDL_GL_SetAttribute. Returns zero if successful.

attr must be an OpenGL attribute symbol or corresponding integer.

value must be one of these types, depending on what attr is:

If attr is 'context-profile-mask, value must be an OpenGL profile symbol or corresponding integer.
If attr is 'context-flags, value must be a list of zero or more OpenGL context flag symbols or an integer bitfield.
Otherwise, value must be an integer.

[procedure] (gl-reset-attributes!)

See SDL_GL_ResetAttributes.

Requires SDL 2.0.2 or higher. Signals an error if the compiled version of SDL is not high enough. Use (version-at-least? 2 0 2) to check before calling this procedure.

[procedure] (gl-get-drawable-size window) → [width height]

See SDL_GL_GetDrawableSize.

This procedure returns multiple values.

Requires SDL 2.0.1 or higher. Signals an error if the compiled version of SDL is not high enough. Use (version-at-least? 2 0 1) to check before calling this procedure.

[procedure] (gl-swap-window!)

See SDL_GL_SwapWindow.

[procedure] (gl-get-swap-interval) → fixnum

See SDL_GL_GetSwapInterval.

[procedure] (gl-set-swap-interval! interval) → fixnum

See SDL_GL_SetSwapInterval.

Returns zero if successful

[procedure] (gl-extension-supported? name-string) → boolean

See SDL_GL_ExtensionSupported.

Joystick

[procedure] (num-joysticks) → fixnum

See SDL_NumJoysticks.

[procedure] (joystick-open! index) → sdl2:joystick

See SDL_JoystickOpen.

[procedure] (joystick-close! joystick)

See SDL_JoystickClose.

[procedure] (joystick-update!)

See SDL_JoystickUpdate.

[procedure] (joystick-event-state) → boolean

See SDL_JoystickEventState.

Like SDL_JoystickEventState with SDL_QUERY.

[setter] (set! (joystick-event-state) state) → boolean
[setter] (joystick-event-state-set! state) → boolean

See SDL_JoystickEventState.

Like SDL_JoystickEventState with SDL_ENABLE or SDL_IGNORE

[procedure] (joystick-attached? joystick) → boolean

See SDL_JoystickGetAttached.

[procedure] (joystick-num-axes joystick) → fixnum

See SDL_JoystickNumAxes.

[procedure] (joystick-num-balls joystick) → fixnum

See SDL_JoystickNumBalls.

[procedure] (joystick-num-buttons joystick) → fixnum

See SDL_JoystickNumButtons.

[procedure] (joystick-num-hats joystick) → fixnum

See SDL_JoystickNumHats.

[procedure] (joystick-get-axis joystick axis-num) → fixnum

See SDL_JoystickGetAxis.

[procedure] (joystick-get-ball joystick ball-num) → [dx dy]

See SDL_JoystickGetBall.

This procedure returns multiple values. Returns #f for both values if the ball values cannot be retrieved (e.g. because ball-num is invalid for the joystick).

[procedure] (joystick-get-button joystick button-num) → boolean

See SDL_JoystickGetButton.

[procedure] (joystick-get-hat joystick hat-num) → symbol

See SDL_JoystickGetHat.

[procedure] (joystick-get-hat-raw joystick hat-num) → fixnum

See SDL_JoystickGetHat. See also joystick-get-hat.

[procedure] (joystick-instance-id joystick) → fixnum

See SDL_JoystickInstanceID.

[procedure] (joystick-name joystick) → string

See SDL_JoystickName.

[procedure] (joystick-name-for-index device-index) → string

See SDL_JoystickNameForIndex.

[procedure] (joystick-get-device-guid device-index) → sdl2:joystick-guid

See SDL_JoystickGetDeviceGUID.

[procedure] (joystick-get-guid joystick) → sdl2:joystick-guid

See SDL_JoystickGetGUID.

[procedure] (joystick-get-guid-from-string str) → sdl2:joystick-guid

See SDL_JoystickGetGUIDFromString.

[procedure] (joystick-get-guid-string guid) → string

See SDL_JoystickGetGUIDString.

Keyboard

[procedure] (get-key-from-name name-str) → symbol

See SDL_GetKeyFromName.

Returns a keyboard keycode symbol.

[procedure] (get-key-from-name-raw name-str) → fixnum

See SDL_GetKeyFromName.

Returns an integer representing a keyboard keycode. See also get-key-from-name.

[procedure] (get-key-from-scancode scancode) → symbol

See SDL_GetKeyFromScancode.

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

Returns a keyboard keycode symbol.

[procedure] (get-key-from-scancode-raw scancode) → fixnum

See SDL_GetKeyFromScancode.

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

Returns an integer representing a keyboard keycode. See also get-key-from-scancode.

[procedure] (get-key-name key) → string

See SDL_GetKeyName.

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

[procedure] (get-scancode-from-name name-str) → symbol

See SDL_GetScancodeFromName.

Returns a keyboard scancode symbol.

[procedure] (get-scancode-from-name-raw name-str) → fixnum

See SDL_GetScancodeFromName.

Returns an integer representing a keyboard scancode. See also get-scancode-from-name.

[procedure] (get-scancode-from-key key) → symbol

See SDL_GetScancodeFromKey.

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

Returns a keyboard scancode symbol.

[procedure] (get-scancode-from-key-raw key) → fixnum

See SDL_GetScancodeFromKey.

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

Returns an integer representing a keyboard scancode. See also get-scancode-from-key.

[procedure] (get-scancode-name scancode) → string

See SDL_GetScancodeName.

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

[procedure] (get-keyboard-focus) → window

See SDL_GetKeyboardFocus.

[procedure] (keyboard-scancode-pressed? scancode) → boolean

Returns #t if the specified key is being pressed on the keyboard.

scancode must be either a keyboard scancode symbol or an integer representing the scancode of a keyboard key.

This procedure queries SDL's internal state, which is tied to the event system. Call pump-events! to update the keyboard state.

This procedure is based on SDL_GetKeyboardState.

[procedure] (mod-state) → list of symbols

See SDL_GetModState.

Returns a list of zero or more keyboard modifier symbols.

[procedure] (mod-state-raw) → fixnum

See SDL_GetModState.

Returns an integer representing a bitfield of keyboard modifiers. See also mod-state.

[setter] (set! (mod-state) state)
[setter] (mod-state-set! state)

See SDL_SetModState.

State can be either a list of keyboard modifier symbols or an integer representing a bitfield of keyboard modifiers.

[setter] (text-input-rect-set! rect)

rect can be an sdl2:rect or #f.

See SDL_SetTextInputRect.

[procedure] (start-text-input!)

See SDL_StartTextInput.

[procedure] (stop-text-input!)

See SDL_StopTextInput.

[procedure] (text-input-active?) → boolean

See SDL_IsTextInputActive.

[procedure] (screen-keyboard-support?) → boolean

See SDL_HasScreenKeyboardSupport.

[procedure] (screen-keyboard-shown? window) → boolean

See SDL_IsScreenKeyboardShown.

Rect / Point

[procedure] (rect-empty? rect) → boolean

See SDL_RectEmpty.

[procedure] (rect=? rect1 rect2) → boolean

See SDL_RectEquals.

[procedure] (enclose-points points #!optional clip result-rect) → [any-enclosed? result-rect]

See SDL_EnclosePoints.

points must be a list of sdl2:points. clip is either an sdl2:rect (to ignore points outside the clip rect) or #f (to consider all points, the default). result-rect is either an sdl2:rect (which will be modified and returned) or #f (a new sdl2:rect will be returned).

This procedure returns multiple values:

any-enclosed?: #t if any points were enclosed, or #f if all points were clipped
result-rect: an sdl2:rect instance that encloses all matching points. If result-rect arg was given, that rect is modified and returned. Otherwise a newly allocated rect is returned.

[procedure] (has-intersection? rect1 rect2) → boolean

See SDL_HasIntersection.

[procedure] (intersect-rect rect1 rect2 #!optional result-rect) → [intersect? result-rect]

See SDL_IntersectRect.

This procedure returns multiple values:

intersect?: #t if rect1 and rect2 intersect, otherwise #f
result-rect: an sdl2:rect of the intersection of the rect1 and rect2. If result-rect arg was given, that sdl2:rect is modified and returned. Otherwise a newly allocated sdl2:rect is returned.

[procedure] (intersect-rect-and-line rect x1 y1 x2 y2) → [intersect? x1-new y1-new x2-new y2-new]

See SDL_IntersectRectAndLine.

This procedure returns multiple values:

intersect?: #t if the given line intersects with the rect
x1-new: the x value of the point within rect that is closest to the first point
y1-new: the y value ...
x2-new: the x value of the point within rect that is closest to the second point
y2-new: the y value ...

[procedure] (union-rect rect1 rect2 #!optional result-rect) → result-rect

See SDL_UnionRect.

If result-rect is given, that rect is modified and returned. Otherwise a newly allocated sdl2:rect is returned.

RWops

[procedure] (rw-from-file filepath) → sdl2:rwops

See SDL_RWFromFile.

[procedure] (rw-from-const-mem pointer) → sdl2:rwops

See SDL_RWFromConstMem.

[procedure] (rw-from-mem pointer) → sdl2:rwops

See SDL_RWFromMem.

[procedure] (rw-from-blob blob) → sdl2:rwops

Create a new sdl2:rwops that accesses the memory of the given CHICKEN Scheme blob.

CAUTION: You must make sure that the blob remains in scope for at least as long as the resulting sdl2:rwops is open. If the blob is garbage collected before the sdl2:rwops, your program may crash if you try to read or write from the sdl2:rwops.

[procedure] (rw-from-string str) → sdl2:rwops

Create a new sdl2:rwops that accesses the memory of the given CHICKEN Scheme string.

CAUTION: You must make sure that the string remains in scope for at least as long as the resulting sdl2:rwops is open. If the string is garbage collected before the sdl2:rwops, your program may crash if you try to read or write from the sdl2:rwops.

[procedure] (rw-from-u8vector u8v) → sdl2:rwops

Create a new sdl2:rwops that accesses the memory of the given SRFI-4 u8vector.

CAUTION: You must make sure that the u8vector remains in scope for at least as long as the resulting sdl2:rwops is open. If the u8vector is garbage collected before the sdl2:rwops, your program may crash if you try to read or write from the sdl2:rwops.

[procedure] (rw-close! rwops) → fixnum

See SDL_RWclose.

Close and clean up the given sdl2:rwops.

Returns zero if successful.

Surface

[procedure] (make-surface width height depth) → sdl2:surface or #f

Create a new sdl2:surface with the given width, height, and color depth (in bits per pixel). This is a more convenient interface for create-rgb-surface. The sdl2:surface's pixel format masks will be chosen automatically based on the requested depth and the current platform's byte order (little endian or big endian). Returns #f if the sdl2:surface could not be created (e.g. because the color depth is unsupported).

The sdl2:surface will have a finalizer, so that the underlying struct's memory will automatically be freed when the record instance is garbage collected. It is not necessary to call free-surface!, although it is safe (and sometimes useful) to do so.

See also make-surface*, which does not set a finalizer.

[procedure] (make-surface* width height depth) → sdl2:surface or #f

Similar to make-surface, except that the sdl2:surface will not have a finalizer. You must call free-surface! when you are done with the surface.

[procedure] (create-rgb-surface flags width height depth rmask gmask bmask amask) → sdl2:surface

See SDL_CreateRGBSurface.

See also make-surface for a more convenient interface.

[procedure] (create-rgb-surface-from pixels width height depth pitch rmask gmask bmask amask) → sdl2:surface

See SDL_CreateRGBSurfaceFrom.

[procedure] (convert-surface surface pixel-format flags) → sdl2:surface

See SDL_ConvertSurface.

[procedure] (load-bmp path-string) → sdl2:surface

See SDL_LoadBMP.

[procedure] (load-bmp* filepath) → sdl2:surface

Similar to load-bmp, except that the sdl2:surface will not have a finalizer. You must call free-surface! when you are done with the surface.

[procedure] (load-bmp-rw rwops) → sdl2:surface

See SDL_LoadBMP_RW.

[procedure] (load-bmp-rw* rwops) → sdl2:surface

Similar to load-bmp-rw, except that the surface will not have a finalizer. You must call free-surface! when you are done with the surface.

[procedure] (save-bmp! surface filepath) → fixnum

See SDL_SaveBMP.

Returns zero if successful.

[procedure] (save-bmp-rw! surface rwops) → fixnum

See SDL_SaveBMP_RW.

Returns zero if successful.

[procedure] (lock-surface! surface) → fixnum

See SDL_LockSurface.

Returns zero if successful.

[procedure] (unlock-surface! surface)

See SDL_UnlockSurface.

[procedure] (must-lock? surface) → boolean

See SDL_MUSTLOCK.

[procedure] (blit-surface! src src-rect dest dest-rect) → fixnum

See SDL_BlitSurface.

Returns zero if successful. May modify dest-rect.

[procedure] (blit-scaled! src src-rect dest dest-rect) → fixnum

See SDL_BlitScaled.

Returns zero if successful. May modify dest-rect.

[procedure] (lower-blit! src src-rect dest dest-rect) → fixnum

See SDL_LowerBlit.

Returns zero if successful. May modify dest-rect.

[procedure] (lower-blit-scaled! src src-rect dest dest-rect) → fixnum

See SDL_LowerBlitScaled.

Returns zero if successful. May modify dest-rect.

[procedure] (fill-rect! surface rect color) → fixnum

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

Returns zero if successful.

[procedure] (fill-rects! surface rects color) → fixnum

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

Returns zero if successful.

[procedure] (surface-ref surface x y) → sdl2:color

Returns the color of the specified pixel on the surface, as an sdl2:color. Signals an error if x or y is out of bounds.

[procedure] (surface-ref-raw surface x y) → fixnum

Like surface-ref, but returns a mapped color (an integer) instead of an sdl2:color. You can use get-rgba to convert the mapped color to color fields.

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

Set the color of the specified pixel on the surface. Automatically locks and unlocks the surface if needed. Signals an error if x or y is out of bounds. color can be either an sdl2:color or a mapped color (an integer). Note: This procedure ignores the surface's clip rect (if any).

[procedure] (surface-clip-rect surface) → sdl2:rect

See SDL_GetClipRect.

Returns a copy of the surface's clip rect.

[setter] (set! (surface-clip-rect surface) rect) → boolean
[setter] (surface-clip-rect-set! surface rect) → boolean

See SDL_SetClipRect.

Sets the surface's clip rect to a copy of the given rect. Or rect can be #f to disable clipping.

Returns #t if the given rect intersects the surface at all, or #f if the rect is out of bounds (completely clips out the surface).

[procedure] (surface-color-key surface) → sdl2:color or #f

See SDL_GetColorKey.

[procedure] (surface-color-key-raw surface) → fixnum or #f

Like surface-color-key, but returns a mapped color (an integer) instead of an sdl2:color.

[setter] (set! (surface-color-key surface) color) → boolean
[setter] (surface-color-key-set! surface color) → boolean

See SDL_SetColorKey.

color can be an sdl2:color, a mapped color (an integer), or #f to disable color keying.

Returns zero if successful.

[procedure] (surface-alpha-mod surface) → fixnum

See SDL_GetSurfaceAlphaMod.

[setter] (set! (surface-alpha-mod surface) mod) → fixnum
[setter] (surface-alpha-mod-set! surface mod) → fixnum

See SDL_SetSurfaceAlphaMod.

Returns zero on success.

[procedure] (surface-blend-mode surface) → symbol

See SDL_GetSurfaceBlendMode.

Returns a blend mode symbol:

'none
'blend
'add
'mod

[setter] (set! (surface-blend-mode surface) mode)
[setter] (surface-blend-mode-set! surface mode)

See SDL_SetSurfaceBlendMode.

mode must be a blend mode symbol or equivalent integer:

'none
'blend
'add
'mod

[procedure] (surface-color-mod surface) → [r g b]

See SDL_GetSurfaceColorMod.

This procedure returns multiple values.

[setter] (set! (surface-color-mod surface) rgb)
[setter] (surface-color-mod-set! surface rgb)

See SDL_SetSurfaceColorMod.

rgb can be a list (r g b) of color values, or an sdl2:color (the sdl2:color's "a" field will be ignored).

[procedure] (surface-palette surface) → sdl2:palette or #f

Returns the surface's palette, or #f if it has no palette. This is equivalent to:

(pixel-format-palette
 (surface-format surface))

[setter] (set! (surface-palette surface) palette)
[setter] (surface-palette-set! surface palette)

See SDL_SetSurfacePalette.

[setter] (surface-rle-set! surface enable)

See SDL_SetSurfaceRLE.

enable is #t to enable RLE acceleration or #f to disable it.

Timer

[procedure] (delay! milliseconds)

See SDL_Delay.

NOTE: This will (probably) cause all CHICKEN threads to pause, not only the thread that this is called from.

[procedure] (get-ticks) → fixnum

See SDL_GetTicks.

[procedure] (get-performance-counter) → fixnum

See SDL_GetPerformanceCounter.

[procedure] (get-performance-frequency) → fixnum

See SDL_GetPerformanceFrequency.

[procedure] (ticks-passed? ticks-a ticks-b) → boolean

See SDL_TICKS_PASSED.

Requires SDL 2.0.1 or higher. Signals an error if the compiled version of SDL is not high enough. Use (version-at-least? 2 0 1) to check before calling this procedure.

Window

[procedure] (create-window! title x y w h #!optional flags) → sdl2:window

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

'fullscreen
'fullscreen-desktop
'opengl
'shown
'hidden
'borderless
'resizable
'minimized
'maximized
'input-grabbed
'input-focus
'mouse-focus
'foreign

[procedure] (get-window-from-id id) → sdl2:window

See SDL_GetWindowFromID.

[procedure] (destroy-window! window)

See SDL_DestroyWindow.

[procedure] (update-window-surface! window) → fixnum

See SDL_UpdateWindowSurface.

Returns zero if successful.

[procedure] (update-window-surface-rects! window rects) → fixnum

See SDL_UpdateWindowSurfaceRects.

rects must be a list of sdl2:rects.

Returns zero if successful.

[procedure] (show-window! window)

See SDL_ShowWindow.

[procedure] (hide-window! window)

See SDL_HideWindow.

[procedure] (maximize-window! window)

See SDL_MaximizeWindow.

[procedure] (minimize-window! window)

See SDL_MinimizeWindow.

[procedure] (raise-window! window)

See SDL_RaiseWindow.

[procedure] (restore-window! window)

See SDL_RestoreWindow.

[setter] (window-bordered-set! window bordered)

See SDL_SetWindowBordered.

bordered is #t to enable window decoration or #f to disable window decoration.

(There is currently no getter.)

[procedure] (window-brightness window) → float

See SDL_GetWindowBrightness.

[setter] (set! (window-brightness window) brightness) → fixnum
[setter] (window-brightness-set! window brightness) → fixnum

See SDL_SetWindowBrightness.

Returns zero if successful.

[procedure] (window-display-index window) → fixnum

See SDL_GetWindowDisplayIndex.

[procedure] (window-display-mode window) → sdl2:display-mode

See SDL_GetWindowDisplayMode.

[setter] (set! (window-display-mode surface) mode) → boolean
[setter] (window-display-mode-set! surface mode) → boolean

TODO: Docs.

[procedure] (window-flags window) → list of symbols

See SDL_GetWindowFlags.

Returns a list of window flag symbols.

[setter] (window-fullscreen-set! window mode)

See SDL_SetWindowFullscreen.

mode can be:

'fullscreen or #t: fullscreen
'fullscreen-desktop: fullscreen desktop
#f: not fullscreen

Returns zero if successful.

[procedure] (window-grab window) → boolean

See SDL_GetWindowGrab.

[setter] (set! (window-grab window) grab?
[setter] (window-grab-set! window grab?)

See SDL_SetWindowGrab.

[setter] (window-icon-set! window icon-surface)

See SDL_SetWindowIcon.

[procedure] (window-id window) → fixnum

See SDL_GetWindowID.

[procedure] (window-maximum-size window) → [width height]

See SDL_GetWindowMaximumSize.

This procedure returns multiple values.

[setter] (set! (window-maximum-size window) size)
[setter] (window-maximum-size-set! window size)

See SDL_SetWindowMaximumSize.

size must be a list of integers (width height).

[procedure] (window-minimum-size window) → [width height]

See SDL_GetWindowMinimumSize.

This procedure returns multiple values.

[setter] (set! (window-minimum-size window) size)
[setter] (window-minimum-size-set! window size)

See SDL_SetWindowMinimumSize.

size must be a list of integers (width height).

[procedure] (window-pixel-format window) → sdl2:pixel-format

See SDL_GetWindowPixelFormat.

[procedure] (window-position window) → [x y]

See SDL_GetWindowPosition.

This procedure returns multiple values.

[setter] (set! (window-position window) pos)
[setter] (window-position-set! window pos)

See SDL_SetWindowPosition.

pos must be a list of integers (x y).

[procedure] (window-size window) → [width height]

See SDL_GetWindowSize.

This procedure returns multiple values.

[setter] (set! (window-size window) size)
[setter] (window-size-set! window size)

See SDL_SetWindowSize.

size must be a list of integers (width height).

[procedure] (window-surface window) → sdl2:surface

See SDL_GetWindowSurface.

[procedure] (window-title window) → string

See SDL_GetWindowTitle.

[setter] (set! (window-title window) title)
[setter] (window-title-set! window title)

See SDL_SetWindowTitle.

sdl2

Introduction

Help Wanted!

Requirements

Installation

Usage and Examples

Related Libraries

Version History

API

Conventions

Enums

Struct Record Types

sdl2:audio-cvt

sdl2:audio-spec

sdl2:color

sdl2:cursor

sdl2:display-mode

sdl2:event

sdl2:controller-axis-event

sdl2:controller-button-event

sdl2:controller-device-event

sdl2:dollar-gesture-event

sdl2:drop-event

sdl2:joy-axis-event

sdl2:joy-ball-event

sdl2:joy-button-event

sdl2:joy-device-event

sdl2:joy-hat-event

sdl2:keyboard-event

sdl2:mouse-button-event

sdl2:mouse-motion-event

sdl2:mouse-wheel-event

sdl2:multi-gesture-event

sdl2:quit-event

sdl2:sys-wm-event

sdl2:text-editing-event

sdl2:text-input-event

sdl2:touch-finger-event

sdl2:user-event

sdl2:window-event

sdl2:finger

sdl2:joystick

sdl2:joystick-guid?

sdl2:keysym

sdl2:palette

sdl2:pixel-format

sdl2:point

sdl2:rect

sdl2:rwops

sdl2:surface

sdl2:sys-wm-info

sdl2:sys-wm-msg

sdl2:texture

sdl2:version

sdl2:window

Procedures

General / Miscellaneous

Pixel Format / Palette

Events

OpenGL integration

Joystick

Keyboard

Rect / Point

RWops

Surface

Timer

Window