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

sdl2

The sdl2 egg provides bindings to Simple DirectMedia Layer version 2 (SDL2). SDL is a popular library used in games and other media-rich software.

The sdl2 egg provides a programmer-friendly, convenient, and CHICKEN-idiomatic interface to SDL2. It takes care of the annoying low-level C stuff for you, so you can focus on making your game.

If a feature you need is not yet available, please file a feature request or contact a maintainer, so we can prioritize adding it.

Project / Source Code Repository
https://gitlab.com/chicken-sdl2/chicken-sdl2
Issue Tracker
https://gitlab.com/chicken-sdl2/chicken-sdl2/issues
Maintainer
John Croisant (john+chicken at croisant dot net)
License
BSD 2-Clause

Table of Contents:

  1. sdl2
  2. Help Wanted!
  3. Requirements
  4. Related Libraries
  5. Installation
  6. Usage and Examples
    1. Ensuring Proper Clean Up
  7. Version History
  8. API
    1. About the API
      1. API Stability
      2. Conventions
      3. Enums
      4. The sdl2-internals Module
      5. Struct Memory Management
    2. Initialization and Clean Up
    3. Color
      1. sdl2:color
    4. Event
      1. Event Functions
      2. sdl2:event
      3. sdl2:controller-axis-event
      4. sdl2:controller-button-event
      5. sdl2:controller-device-event
      6. sdl2:dollar-gesture-event
      7. sdl2:drop-event
      8. sdl2:joy-axis-event
      9. sdl2:joy-ball-event
      10. sdl2:joy-button-event
      11. sdl2:joy-device-event
      12. sdl2:joy-hat-event
      13. sdl2:keyboard-event
      14. sdl2:mouse-button-event
      15. sdl2:mouse-motion-event
      16. sdl2:mouse-wheel-event
      17. sdl2:multi-gesture-event
      18. sdl2:quit-event
      19. sdl2:sys-wm-event
      20. sdl2:text-editing-event
      21. sdl2:text-input-event
      22. sdl2:touch-finger-event
      23. sdl2:user-event
      24. sdl2:window-event
    5. Hints
      1. Hints in SDL 2.0.0 and higher
      2. Hints in SDL 2.0.1 and higher
      3. Hints in SDL 2.0.2 and higher
      4. Hints in SDL 2.0.3 and higher
      5. Hints in SDL 2.0.4 and higher
      6. Hint Functions
    6. Joystick
      1. Joystick Functions
      2. sdl2:joystick
      3. sdl2:joystick-guid
    7. Keyboard
      1. Keyboard Functions
      2. sdl2:keysym
    8. OpenGL
      1. OpenGL Functions
      2. sdl2:gl-context
    9. Palette
      1. sdl2:palette
    10. Pixel Format
      1. Pixel Format Functions
      2. sdl2:pixel-format
    11. Rect / Point
      1. Rect / Point Functions
      2. sdl2:rect
      3. sdl2:point
    12. Renderer
      1. Renderer Functions
      2. sdl2:renderer
      3. sdl2:renderer-info
    13. RWops
      1. RWops Functions
      2. sdl2:rwops
    14. Surface
      1. Surface Functions
      2. sdl2:surface
    15. Texture
      1. sdl2:texture
    16. Timer
    17. Touch / Gesture
      1. Touch / Gesture Functions
      2. sdl2:finger
    18. Version
      1. Version Feature Identifiers
      2. Version Functions
    19. Window / Display Mode
      1. Window / Display Mode Functions
      2. sdl2:window
      3. sdl2:display-mode
    20. Miscellaneous

Help Wanted!

This egg needs volunteers to help with several things:

If you wish to help in any way, please contact the project maintainer.

Requirements

The sdl2 egg requires Simple DirectMedia Layer version 2.0.0 or higher. It will not work with older versions of SDL.

This egg requires CHICKEN Scheme 4.8 or higher. Please file an issue or contact the maintainer if you need to use this library with an earlier version of CHICKEN Scheme.

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.

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

The sdl2-ttf egg provides bindings to version 2 of the SDL_ttf library, which provides the ability to render text using TTF and FON fonts. It is built to be compatible with sdl2.

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

Installation

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

You only need to set the SDL2_FLAGS environment variable when installing the egg, not when using it.

Usage and Examples

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

(use (prefix sdl2 sdl2:))
(sdl2:set-main-ready!)
(sdl2:init! '(video))
(define window (sdl2:create-window! "Hello, World!" 0 0 600 400))
(sdl2:fill-rect! (sdl2:window-surface window)
                 #f
                 (sdl2:make-color 0 128 255))
(sdl2:update-window-surface! window)
(sdl2:delay! 3000)
(sdl2:quit!)

The demos directory contains small programs demonstrating how to use various features of sdl2. E.g. to compile and run the basics demo:

csc demos/basics.scm
demos/basics

The chicken-sdl2-examples repository contains complete example games and programs made with sdl2.

Ensuring Proper Clean Up

You must make sure to call set-main-ready! and init! (in that order) soon after your program starts, and to call quit! before your program ends. This is especially important if your program enters fullscreen mode, or changes the display brightness or gamma ramp. If your program does not perform proper initialization and clean up, those changes can sometimes linger even after your program has ended, which can be very frustrating for your program's users. It is even possible for the user's computer to become stuck in fullscreen mode, requiring the user to power off their computer, possibly losing important work that they were doing in other programs!

Here is a simple way to ensure that quit! is called before your program ends, whether exitting normally or because an exception occurred:

(use (prefix sdl2 sdl2:))

;; Initialize SDL
(sdl2:set-main-ready!)
(sdl2:init! '(video)) ;; or whatever init flags your program needs

;; Schedule quit! to be automatically called when your program exits normally.
(on-exit sdl2:quit!)

;; Install a custom exception handler that will call quit! and then
;; call the original exception handler. This ensures that quit! will
;; be called even if an unhandled exception reaches the top level.
(current-exception-handler
 (let ((original-handler (current-exception-handler)))
   (lambda (exception)
     (sdl2:quit!)
     (original-handler exception))))

;; ...
;; ... the rest of your program code ...
;; ...

Version History

0.2.0 (in development)
Improved integer type checking. Added 2D accelerated rendering (renderer and texture). Added hints. Performance improvements. Miscellaneous other changes.
0.1.1 (2015-12-22)
Fixed a compile error when compiling with GCC 4.
0.1.0 (2015-12-19)
Initial release.

For more information about what changed in each version, see the CHANGELOG.

API

About the API

API Stability

The sdl2 egg follows "semantic versioning". Until version 1.0.0 is released, the API is not guaranteed to be "stable". That means the maintainer reserves the right to change the API if needed, possibly in ways that break backwards compatibility with previous versions. Large backwards-incompatible changes are unlikely, but there may be small tweaks and fixes to the API if problems are discovered.

After version 1.0.0 is released, the API is guaranteed to remain stable (no backwards-incompatible changes) until the next new major version (e.g. going from version 1.x to 2.0.0, or 2.x to 3.0.0).

Conventions

Enums

The sdl2 egg uses symbols instead of integer constants, for things like event types, keyboard keys, and init flags. It uses lists of symbols instead of bitwise-ior'd integer masks or flags. See the enum tables for details.

Many procedures that return an enum symbol or a list of enum symbols, also have a "raw" version that returns the equivalent integer value. Setters that accept an enum symbol will also accept the corresponding integer value. Setters that accept a list of enum symbols will also accept an integer representing bitwise-ior'd integer flags or masks.

The sdl2-internals Module

The sdl2 egg has two modules: the sdl2 module, which defines the public interface for the library, and sdl2-internals, which defines the "under the hood" code. Most users will only need to use the sdl2 module, but for advanced use cases you may need or want to import specific parts of the sdl2-internals module into your program.

The sdl2-internals module is not an official part of the public API, and does not have the same guarantees of API stability. But, certain parts of the module are safe to use in your programs. For more information, see this guide:

Struct Memory Management

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

Some struct record types have procedures for allocating or freeing an instance of that type. Each type that can be allocated has two "make" procedures:

Certain other procedures that return new struct records also follow this convention, for example load-bmp vs. load-bmp*.

In most cases, it is best to create managed struct records, so that you don't have to worry about manually freeing them. However, in certain advanced use cases, you might require that the struct's underlying pointer address never change. For example, suppose you are storing the pointer address in another C struct. In such cases, you should create an unmanaged struct record, not a managed struct record. Unmanaged struct records will keep the same underlying pointer address throughout their life, but managed struct records may sometimes be moved in memory by the garbage collector. (Most users do not need to worry about this.)

If you create an unmanaged struct record but want to automatically free its memory when it is garbage collected, you can use set-finalizer! with the appropriate "free" procedure. (This is how most, but not all, managed struct records are implemented.) For example:

;; Allocate an unmanaged sdl2:surface.
(let ((my-surf (sdl2:make-surface* 800 600 30)))
  ;; Set a finalizer so it will be automatically freed.
  (set-finalizer! my-surf sdl2:free-surface!))

It is safe to manually free managed struct records. In fact, doing so can be beneficial to your program's memory footprint and performance, because there will be less memory waiting to be freed by the garbage collector. For example:

(let ((my-surf (sdl2:make-surface 800 600 32)))
  ;; ... do stuff with my-surf ...
  ;; Once you are done with my-surf, manually free it.
  (sdl2:free-surface! my-surf))

As soon as you free a struct record, its pointer will be set to null, and it will no longer be usable for most purposes. You cannot get or set its fields, or pass it as an argument to most procedures. So be careful not to free struct records that you still want to use!

Some struct record types, such as sdl2:window, are not managed in this way. Instead, you use certain SDL functions to work with them, such as create-window! and destroy-window!.

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

Returns #t if the given record is a null struct record, i.e. it has a pointer to memory address 0. This procedure can be used with any struct record type provided by this library, or related libraries such as sdl2-ttf.

A struct record will be null after you manually free its memory, e.g. using free-surface!. Most procedures, including field getters and setters, will signal an error if you pass a null struct record. So, you can use this procedure to check whether it is safe to use the record.

It is possible for a C function to return a null struct record. But, if a function binding in this library returns a null struct record, that is a bug and should be reported. Function bindings in this library are supposed to return #f instead of a null struct record.

Initialization and Clean Up

[procedure] (set-main-ready!)

See SDL_SetMainReady.

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

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

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

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

See SDL_Init.

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

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

See SDL_InitSubSystem.

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

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

[procedure] (quit!)

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

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.

Color

sdl2:color

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

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

r, g, b, and a must be integers in the range 0 to 255 (inclusive). r, g, and b default to 0. a defaults to 255 (full opacity).

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

Free the memory of the sdl2:color's underlying struct. color's pointer will be set to null (see struct-null?). It is safe to call this procedure with managed or unmanaged sdl2:colors. It is safe (but has no effect) to free a struct record multiple times.

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

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

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

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

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

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

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

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

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

Convenient way of setting multiple fields of the sdl2:color. Any arguments that are #f will cause no change to that field. E.g. (color-set! my-color 42 #f 255 #f) will set the "r" field to 42 and the "b" field to 255, but will not change the "g" or "a" fields. Returns color after it is modified.

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

Returns a list (r g b a) containing the value of each field of the sdl2:color.

[procedure] (color->values color) → [r g b a]
[procedure] (colour->values color) → [r g b a]

Returns multiple values containing the value of each field of the sdl2:color. This is useful for destructuring an sdl2:color using receive or let-values.

[procedure] (color=? color1 color2) → boolean
[procedure] (colour=? color1 color2) → boolean

Efficiently compare two sdl2:colors. Returns #t if the value of every field in color1 is equal to the value of the corresponding field in color2.

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

Efficiently copy the given sdl2:color, returning a new sdl2:color with the same values.

Event

Event Functions

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

Get or set the state of the given event type. #t means the event type is enabled, so events of that type may appear on the event queue. #f means the event type is disabled, so events of that type will be automatically discarded. It is beneficial to your program's performance to disable event types that your program does not need.

type must be an event type symbol or corresponding integer.

If you set an event type's state to #f, any events of that type already on the event queue will be immediately discarded. The setters return the previous state of the given event type.

See SDL_EventState.

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

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

For flush-event!, type must be an event type symbol or corresponding integer.

For flush-events!, min-type and max-type specify the range of event types to remove. Events with a type outside of this range will not be removed. min-type and max-type must be event type symbols or corresponding integers. min-type defaults to 'first and max-type defaults to 'last, which means all event types match by default.

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

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

For has-event?, type must be an event type symbol or corresponding integer.

For has-events?, min-type and max-type specify the range of event types to consider. Events with a type outside of this range will not be considered. min-type and max-type must be event type symbols or corresponding integers. min-type defaults to 'first and max-type defaults to 'last, which means all event types match by default.

[procedure] (quit-requested?) → boolean

Returns #t if the event queue currently has at least one event of type 'quit. See SDL_QuitRequested.

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

Get multiple matching events from the front of the event queue. Returns a list of managed sdl2:events. See SDL_PeepEvents.

num specifies the maximum number of events to return. May return fewer events if there are not enough matching events on the event queue.

min-type and max-type specify the range of event types to return. Events with a type outside of this range will not be returned (they will remain on the queue). min-type and max-type must be event type symbols or corresponding integers. min-type defaults to 'first and max-type defaults to 'last, which means all event types match by default.

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

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

Get the next event from the event queue. The returned event is removed from the event queue. See SDL_PollEvent.

If result-event is omitted or #f, a new managed sdl2:event will be returned. If result-event is an sdl2:event, it will be modified and returned. This allows you to allocate a single event and reuse it many times in your event loop, so that your program does not create as much garbage for the garbage collector.

[procedure] (pump-events!)

See SDL_PumpEvents.

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

See SDL_PushEvent.

Returns #t if the event was pushed onto the event queue, or #f if the event was discarded, e.g. because the event type is disabled (see event-state).

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

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

Wait for the next event to appear on the event queue, then return it. The returned event will be removed from the event queue. If there is already an event on the event queue, it will be returned immediately. Otherwise, these procedures will block the current thread until the next event appears (or the timeout expires).

If result-event is omitted or #f, a new managed sdl2:event will be returned. If result-event is an sdl2:event, it will be modified and returned. This allows you to allocate a single event and reuse it many times in your event loop, so that your program does not create as much garbage for the garbage collector.

These procedures are compatible with SRFI-18 multithreading. Only the current thread will block while waiting. Other threads will continue as normal.

These procedures are inspired by (but do not actually use) SDL_WaitEvent and SDL_WaitEventTimeout.

[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 symbol in event-symbols will be assigned a sequential number. If there are not enough remaining numbers to register all the symbols in event-symbols, this procedure will signal an exception of kind (exn sdl2), and none of the new event types will be registered.

This procedure returns a list of pairs, with the car of each pair being a new event type symbol, and the cdr of each pair being that symbol's assigned number.

This procedure is based on SDL_RegisterEvents.

sdl2:event

sdl2:event is a record type that wraps a pointer to an SDL_Event. There are many specific event structs in SDL, and the sdl2:event type wraps them all. Each event struct has a corresponding variant of sdl2:event, described below. Each variant has one or more associated event type symbols.

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

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

[procedure] (make-event #!optional type) → sdl2:event
[procedure] (make-event* #!optional type) → sdl2:event

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

type defaults to 'first. It must be a event type symbol or equivalent integer.

[procedure] (free-event! event)

Free the memory of the sdl2:event's underlying struct. You can call this procedure with any variant of sdl2:event. event's pointer will be set to null (see struct-null?). It is safe to call this procedure with managed or unmanaged sdl2:events. It is safe (but has no effect) to free a struct record multiple times.

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

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

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

Get or set the sdl2:event's "timestamp" field, as a nonnegative integer representing the time that the event occurred, in milliseconds since the SDL timer system was initialized. You can use these procedures with any variant of sdl2:event.

sdl2:controller-axis-event

sdl2:controller-axis-event is a variant of sdl2:event that wraps a pointer to an SDL_ControllerAxisEvent.

This event variant occurs when an axis on a controller moves. There may be more than one controller, and each controller may have more than one axis. You can distinguish them using the which and axis fields.

sdl2:controller-axis-event has the following event type symbols:

'controller-axis-motion
An axis on a controller moved.
[procedure] (controller-axis-event? obj) → boolean

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

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

Get or set the event's "which" field, as an integer indicating the device index of the controller (joystick) that the event is related to.

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

Get or set the event's "axis" field, as an integer indicating the axis that the event is related to. E.g. 0 indicates the first axis on the controller.

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

Get or set the event's "value" field, as an integer in the range -32768 to 32767 (inclusive), indicating the new value of the axis.

sdl2:controller-button-event

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

This event variant occurs when a button on a controller is pressed or released. There may be more than one controller, and each controller may have more than one button. You can distinguish them using the which and button fields.

sdl2:controller-button-event has the following event type symbols:

'controller-button-down
A button on a controller was pressed.
'controller-button-up
A button on a controller was released.
[procedure] (controller-button-event? obj) → boolean

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

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

Get or set the event's "which" field, as an integer indicating the device index of the controller (joystick) that the event is related to.

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

Get or set the event's "button" field, as an integer indicating the button that the event is related to. E.g. 0 indicates the first button on the controller.

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

Get or set the event's "state" field, as a boolean indicating whether the button was pressed (#t) or released (#f). You can also find out by checking the event type: 'controller-button-down for pressed, or 'controller-button-up for released.

sdl2:controller-device-event

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

This event variant occurs when a controller is added, removed, or remapped. There may be more than one controller. You can distinguish them using the which.

sdl2:controller-device-event has the following event type symbols:

'controller-device-added
A controller device was added.
'controller-device-removed
A controller device was removed.
'controller-device-remapped
A controller device was remapped.
[procedure] (controller-device-event? obj) → boolean

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

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

Get or set the event's "which" field, as an integer indicating the device index of the controller (joystick) that the event is related to.

sdl2:dollar-gesture-event

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

This event variant occurs when a "$1 unistroke" gesture is performed or recorded.

sdl2:dollar-gesture-event has the following event type symbols:

'dollar-gesture
A dollar gesture was performed.
'dollar-record
A dollar gesture was recorded.
[procedure] (dollar-gesture-event? obj) → boolean

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

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

Get or set the event's "touch-id" field, as an integer indicating the ID number of the touch device this event is related to.

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

Get or set the event's "gesture-id" field, as an integer indicating the ID number of the closest gesture to the performed stroke.

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

Get or set the event's "num-fingers" field, as an integer indicating the number of fingers used to draw the stroke.

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

Get or set the event's "error" field, as a float indicating the difference between the gesture template and the actual performed gesture. Lower error is a better match.

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

Get or set the event's "x" field, as a float in the range 0.0 to 1.0 (inclusive), indicating the normalized X coordinate of the center of the gesture.

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

Get or set the event's "y" field, as a float in the range 0.0 to 1.0 (inclusive), indicating the normalized Y coordinate of the center of the gesture.

sdl2:drop-event

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

This event variant occurs when the user requests that the program open a file, e.g. by dragging and dropping a file icon onto the program.

sdl2:drop-event has the following event type symbols:

'drop-file
The user requested that a file be opened.
[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)

Get or set the event's "file" field, as a string indicating the path to a file that the user requested to be opened.

sdl2:joy-axis-event

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

This event variant occurs when an axis on a joystick moves. There may be more than one joystick, and each joystick may have more than one axis. You can distinguish them using the which and axis fields.

sdl2:joy-axis-event has the following event type symbols:

'joy-axis-motion
An axis on a joystick moved.
[procedure] (joy-axis-event? obj) → boolean

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

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

Get or set the event's "which" field, as an integer indicating the device index of the joystick that the event is related to.

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

Get or set the event's "axis" field, as an integer indicating the axis that the event is related to. E.g. 0 indicates the first axis on the joystick.

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

Get or set the event's "value" field, as an integer in the range -32768 to 32767 (inclusive), indicating the new value of the axis.

sdl2:joy-ball-event

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

This event variant occurs when a trackball on a joystick moves. There may be more than one joystick, and each joystick may have more than one trackball. You can distinguish them using the which and ball fields.

sdl2:joy-ball-event has the following event type symbols:

'joy-ball-motion
A trackball on a joystick moved.
[procedure] (joy-ball-event? obj) → boolean

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

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

Get or set the event's "which" field, as an integer indicating the device index of the joystick that the event is related to.

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

Get or set the event's "ball" field, as an integer indicating the trackball that the event is related to. E.g. 0 indicates the first trackball on the joystick.

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

Get or set the event's "xrel" field, as an integer (possibly negative) indicating how the trackball's X position changed relative to its previous position.

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

Get or set the event's "yrel" field, as an integer (possibly negative) indicating how the trackball's Y position changed relative to its previous position.

sdl2:joy-button-event

sdl2:joy-button-event is a variant of sdl2:event that wraps a pointer to an SDL_JoyButtonEvent.

This event variant occurs when a button on a joystick is pressed or released. There may be more than one joystick, and each joystick may have more than one button. You can distinguish them using the which and button fields.

sdl2:joy-button-event has the following event type symbols:

'joy-button-down
A button on a joystick was pressed.
'joy-button-up
A button on a joystick was released.
[procedure] (joy-button-event? obj) → boolean

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

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

Get or set the event's "which" field, as an integer indicating the device index of the joystick that the event is related to.

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

Get or set the event's "button" field, as an integer indicating the button that the event is related to. E.g. 0 indicates the first button on the joystick.

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

Get or set the value of the event's "state" field, as a boolean indicating whether the button was pressed (#t) or released (#f). You can also find out by checking the event type: 'joy-button-down for pressed, or 'joy-button-up for released.

sdl2:joy-device-event

sdl2:joy-device-event is a variant of sdl2:event that wraps a pointer to an SDL_JoyDeviceEvent.

This event variant occurs when a joystick device is added or removed. There may be more than one joystick. You can distinguish them using the which field.

sdl2:joy-device-event has the following event type symbols:

'joy-device-added
A joystick device was added.
'joy-device-removed
A joystick device was removed.
[procedure] (joy-device-event? obj) → boolean

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

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

Get or set the event's "which" field, as an integer indicating the device index of the joystick that the event is related to.

sdl2:joy-hat-event

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

This event variant occurs when an 8-directional hat switch on a joystick moves. There may be more than one joystick, and each joystick may have more than one hat switch. You can distinguish them using the which and hat fields.

sdl2:joy-hat-event has the following event type symbols:

'joy-hat-motion
A hat switch on a joystick moved.
[procedure] (joy-hat-event? obj) → boolean

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

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

Get or set the event's "which" field, as an integer indicating the device index of the joystick that the event is related to.

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

Get or set the event's "hat" field, as an integer indicating the hat switch that the event is related to. E.g. 0 indicates the first hat switch on the joystick.

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

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

sdl2:keyboard-event

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

This event variant occurs when a keyboard key is pressed or released.

sdl2:keyboard-event has the following event type symbols:

'key-down
A keyboard key was pressed.
'key-up
A keyboard key was released.
[procedure] (keyboard-event? obj) → boolean

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

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

Get or set the event's "window-id" field, as an integer indicating the ID number of the sdl2:window that had keyboard focus at the time this event occurred, or 0 if no sdl2:window had keyboard focus.

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

Get or set the event's "state" field, as a boolean indicating whether the key was pressed (#t) or released (#f). You can also find out by checking the event type: 'key-down for pressed, or 'key-up for released.

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

Get or set the event's "repeat" field, as a integer. Non-zero indicates that this is a key repeat, caused by the user pressing and holding the key for some time. Zero indicates this is not a key repeat.

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

Get or set the event's "keysym" field, as an sdl2:keysym indicating the key that was pressed or released. The getter returns a copy of the sdl2:keysym stored in the event. Modifying the returned sdl2:keysym will not modify the event, but setting this field to a sdl2:keysym will modify the event.

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

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

Get or set the "scancode" field of the event's "keysym" field, indicating the physical key that was pressed or released. Setting this will modify the event.

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

Get or set the "sym" field of the event's "keysym" field, indicating the logical key that was pressed or released. Setting this will modify the event.

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

Get or set the "sym" field of the event's "keysym" field, indicating the modifier keys that were being pressed at the time the event occurred. Setting this will modify the event.

sdl2:mouse-button-event

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

This event variant occurs when a mouse button was pressed or released.

sdl2:mouse-button-event has the following event type symbols:

'mouse-button-down
A mouse button was pressed.
'mouse-button-up
A mouse button was released.
[procedure] (mouse-button-event? obj) → boolean

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

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

Get or set the event's "window-id" field, as an integer indicating the ID number of the sdl2:window that had mouse focus at the time this event occurred, or 0 if no sdl2:window had mouse focus.

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

Get or set the event's "which" field, as an integer indicating the mouse instance ID.

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

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

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

Get or set the event's "state" field, as a boolean indicating whether the button was pressed (#t) or released (#f). You can also find out by checking the event type: 'mouse-button-down for pressed, or 'mouse-button-up for released.

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

Get or set the event's "x" field, as an integer indicating the X position (in pixels) of the mouse at the time this event occurred.

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

Get or set the event's "y" field, as an integer indicating the Y position (in pixels) of the mouse at the time this event occurred.

sdl2:mouse-motion-event

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

This event variant occurs when the mouse cursor moves.

sdl2:mouse-motion-event has the following event type symbols:

'mouse-motion
The mouse cursor moved.
[procedure] (mouse-motion-event? obj) → boolean

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

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

Get or set the event's "window-id" field, as an integer indicating the ID number of the sdl2:window that had mouse focus at the time this event occurred, or 0 if no sdl2:window had mouse focus.

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

Get or set the event's "which" field, as an integer indicating the mouse instance ID.

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

Get or set the event's "state" field, indicating the mouse buttons that were being pressed at the time this event occurred.

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

Get or set the event's "x" field, as an integer indicating the X position (in pixels) of the mouse at the time this event occurred.

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

Get or set the event's "y" field, as an integer indicating the Y position (in pixels) of the mouse at the time this event occurred.

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

Get or set the event's "xrel" field, as an integer (possibly negative) indicating the amount the mouse's X position changed since its previous position.

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

Get or set the event's "yrel" field, as an integer (possibly negative) indicating the amount the mouse's Y position changed since its previous position.

sdl2:mouse-wheel-event

sdl2:mouse-wheel-event is a variant of sdl2:event that wraps a pointer to an SDL_MouseWheelEvent.

This event variant occurs when a mouse wheel moves.

sdl2:mouse-wheel-event has the following event type symbols:

'mouse-wheel
A mouse wheel moved.
[procedure] (mouse-wheel-event? obj) → boolean

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

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

Get or set the event's "window-id" field, as an integer indicating the ID number of the sdl2:window that had mouse focus at the time this event occurred, or 0 if no sdl2:window had mouse focus.

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

Get or set the event's "which" field, as an integer indicating the mouse instance ID.

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

Get or set the event's "x" field, as an integer (possibly negative) indicating the amount the wheel scrolled horizontally. Positive numbers normally indicate scrolling to the right, negative numbers indicate scrolling to the left. But if the "direction" field is set to 'flipped in SDL 2.0.4 or higher, the meaning of this field is reversed.

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

Get or set the event's "y" field, as an integer (possibly negative) indicating the amount the wheel scrolled vertically. Positive numbers normally indicate scrolling away from the user, negative numbers indicate scrolling toward the user. But if the "direction" field is set to 'flipped in SDL 2.0.4 or higher, the meaning of this field is reversed.

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

Get or set the event's "direction" field, as one of the following symbols:

'normal
"Normal" scrolling mode.
'flipped
"Flipped" or "natural" scrolling mode. You can multiple the "x" and "y" field values by -1 to get the "normal" values.

This procedure is available in sdl2 egg version 0.2.0 and higher. It requires SDL 2.0.4 or higher. It signals an error if the compiled version of SDL is not high enough. Use the libSDL-2.0.4+ feature identifier to check before calling this procedure.

sdl2:multi-gesture-event

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

This event variant occurs when a multi-finger gesture is performed on a touch device. This is useful for recognizing common gestures that involve multiple fingers, e.g. pinching or rotating.

sdl2:multi-gesture-event has the following event type symbols:

'multi-gesture
A multi-finger gesture was performed.
[procedure] (multi-gesture-event? obj) → boolean

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

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

Get or set the event's "touch-id" field, as an integer indicating the ID number of the touch device this event is related to.

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

Get or set the event's "dtheta" field, as a float indicating the amount that the fingers rotated during this motion.

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

Get or set the event's "ddist" field, as a float indicating the amount that the fingers pinched during this motion.

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

Get or set the event's "x" field, as a float indicating the normalized X coordinate of the center of the gesture.

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

Get or set the event's "y" field, as a float indicating the normalized Y coordinate of the center of the gesture.

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

Get or set the event's "num-fingers" field, as an integer indicating the number of fingers used in the gesture.

sdl2:quit-event

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

This event variant occurs when the user requests to quit the program. There are various ways this might happen, depending on the platform.

sdl2:quit-event has the following event type symbols:

'quit
The user requested to quit the program.
[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.

This event variant is for very advanced use cases. Most people can ignore it.

sdl2:sys-wm-event has the following event type symbols:

'sys-wm
A platform-specific event occurred.
[procedure] (sys-wm-event? obj) → boolean

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

[procedure] (sys-wm-event-msg-raw event) → pointer
[setter] (set! (sys-wm-event-msg-raw event) val)
[setter] (sys-wm-event-msg-raw-set! event val)

Get or set the event's "msg" field, as a raw pointer to a SDL_SysWMmsg struct describing the platform-specific event that occurred. This is for very advanced use cases. Most people can ignore it.

sdl2:text-editing-event

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

This event occurs when a user is editing (composing) text, e.g. using an Input Method Editor (IME). See the Text Input tutorial for SDL.

sdl2:text-editing-event has the following event type symbols:

'text-editing
The user editted some text being composed.
[procedure] (text-editing-event? obj) → boolean

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

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

Get or set the event's "window-id" field, as an integer indicating the ID number of the sdl2:window that had keyboard focus at the time this event occurred, or 0 if no sdl2:window had keyboard focus.

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

Get or set the event's text event, as a UTF8 string up to 32 bytes long (including the null byte), holding the text being edited.

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

Get or set the event's "start" field, as an integer indicating the location to begin editing from.

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

Get or set the event's "length" field, as an integer indicating the number of characters to edit from the start point.

sdl2:text-input-event

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

This event occurs when the users enters some text, possibly using an Input Metod Editor (IME). See the Text Input tutorial for SDL.

sdl2:text-input-event has the following event type symbols:

'text-input
The use inputted some text.
[procedure] (text-input-event? obj) → boolean

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

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

Get or set the event's "window-id" field, as an integer indicating the ID number of the sdl2:window that had keyboard focus at the time this event occurred, or 0 if no sdl2:window had keyboard focus.

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

Get or set the event's text event, as a UTF8 string up to 32 bytes long (including the ending null byte), holding the text that was inputted.

sdl2:touch-finger-event

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

This event variant occurs when the user presses, lifts, or moves a finger (or stylus, etc.) on a supported touch device, e.g. the touch screen of a mobile phone or tablet device, or certain laptop trackpads. There may be more than one finger touching at the same time; you can distinguish the fingers by the finger-id number.

sdl2:touch-finger-event has the following event type symbols:

'finger-down
A finger started touching a touch device (i.e. was pressed down).
'finger-up
A finger stopped touching a touch device (i.e. was lifted up).
'finger-motion
A finger moved while touching a touch device.
[procedure] (touch-finger-event? obj) → boolean

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

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

Get or set the event's "touch-id" field, as an integer indicating the ID number of the touch device this event is related to.

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

Get or set the event's "finger-id" field, as an integer indicating the ID number of the finger this event is related to.

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

Get or set the event's "x" field, as a float in the range 0.0 to 1.0 (inclusive), indicating the normalized X coordinate of the touch event.

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

Get or set the event's "y" field, as a float in the range 0.0 to 1.0 (inclusive), indicating the normalized Y coordinate of the touch event.

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

Get or set the event's "dx" field, as a float in the range 0.0 to 1.0 (inclusive), indicating the normalized distance moved on the X axis.

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

Get or set the event's "dy" field, as a float in the range 0.0 to 1.0 (inclusive), indicating the normalized distance moved on the Y axis.

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

Get or set the event's "pressure" field, as a float in the range 0.0 to 1.0 (inclusive), indicating the pressure being applied.

sdl2:user-event

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

This event variant does not occur normally. Instead, you can make instances of this event variant and push them to the event queue using push-event!. The meaning of this event variant is entirely up for you to decide. For example, you can use it to create custom event types related to your gameplay.

sdl2:user-event does not have any event type symbols by default. Call register-events! to register your own custom event type symbols for sdl2:user-event.

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

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

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

Get or set the event's "window-id" field, as an integer indicating the ID number of the sdl2:window associated with this event.

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

Get or set the event's "code" field, as an integer in the range -32768 to 32767 (inclusive). The meaning of this field is for you to decide.

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

Get or set the event's "data1" field, as a raw pointer or #f. The meaning of this field is for you to decide.

If you want to store a pointer to a Scheme object here, be sure to evict the object first. Otherwise the object's location in memory might change, rendering the pointer invalid.

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

Get or set the event's "data2" field, as a raw pointer or #f. The meaning of this field is for you to decide.

If you want to store a pointer to a Scheme object here, be sure to evict the object first. Otherwise the object's location in memory might change, rendering the pointer invalid.

sdl2:window-event

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

This event variant occurs when various changes occur to a window, e.g. when a window is moved, resized, minimized, closed, etc.

sdl2:window-event has the following event type symbols:

'window
A window-related event occurred.
[procedure] (window-event? obj) → boolean

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

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

Get or set the event's "window-id" field, as an integer indicating the ID of the sdl2:window that the event is related to.

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

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

[procedure] (window-event-data1 event) → integer
[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 (see window-event-event). E.g. if the window was resized, this will hold the new window width; if the window was moved, this will hold the new x position.

[procedure] (window-event-data2 event) → integer
[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 (see window-event-event). E.g. if the window was resized, this will hold the new window height; if the window was moved, this will hold the new y position.

Hints

Hints (aka Configuration Variables) are a way for you to give hints to the SDL library about how you would like it to behave. Most hints affect platform-specific behavior. Hints are merely suggestions, and SDL may or may not obey them.

Hints can also be specified or overriden by environment variables. This allows the user to configure SDL to work best on their system. Usually the environment variable is similar to the SDL constant name, but prefixed with "SDL_" instead of "SDL_HINT_". For more information see SDL_hints.h.

Procedures for getting and setting hints are available in sdl2 egg version 0.2.0 and higher. But, SDL will notice environment variables even if you are using an earlier version of the sdl2 egg.

The tables below list the hint name symbol, which you can pass to get-hint and set-hint!, and the corresponding SDL constant. See the linked documentation for more information about what the hint does, and valid values for the hint.

Some hints are only effective after a certain version of SDL. You may safely set the hint with any version of SDL, but it will have no effect on older versions of SDL.

Hints in SDL 2.0.0 and higher

Hint name symbol SDL constant name
framebuffer-acceleration SDL_HINT_FRAMEBUFFER_ACCELERATION
gamecontrollerconfig SDL_HINT_GAMECONTROLLERCONFIG
grab-keyboard SDL_HINT_GRAB_KEYBOARD
idle-timer-disabled SDL_HINT_IDLE_TIMER_DISABLED
joystick-allow-background-events SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS
orientations SDL_HINT_ORIENTATIONS
render-driver SDL_HINT_RENDER_DRIVER
render-opengl-shaders SDL_HINT_RENDER_OPENGL_SHADERS
render-scale-quality SDL_HINT_RENDER_SCALE_QUALITY
render-vsync SDL_HINT_RENDER_VSYNC
timer-resolution SDL_HINT_TIMER_RESOLUTION
video-minimize-on-focus-loss SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS
video-x11-xinerama SDL_HINT_VIDEO_X11_XINERAMA
video-x11-xrandr SDL_HINT_VIDEO_X11_XRANDR
video-x11-xvidmode SDL_HINT_VIDEO_X11_XVIDMODE
xinput-enabled SDL_HINT_XINPUT_ENABLED

Hints in SDL 2.0.1 and higher

Hint name symbol SDL constant name
render-direct3d-threadsafe SDL_HINT_RENDER_DIRECT3D_THREADSAFE
video-highdpi-disabled SDL_HINT_VIDEO_HIGHDPI_DISABLED

Hints in SDL 2.0.2 and higher

Hint name symbol SDL constant name
accelerometer-as-joystick SDL_HINT_ACCELEROMETER_AS_JOYSTICK
mac-ctrl-click-emulate-right-click SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK
mouse-relative-mode-warp SDL_HINT_MOUSE_RELATIVE_MODE_WARP
video-allow-screensaver SDL_HINT_VIDEO_ALLOW_SCREENSAVER
video-mac-fullscreen-spaces SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES
video-window-share-pixel-format SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT
video-win-d3dcompiler SDL_HINT_VIDEO_WIN_D3DCOMPILER

Hints in SDL 2.0.3 and higher

Hint name symbol SDL constant name
render-direct3d11-debug SDL_HINT_RENDER_DIRECT3D11_DEBUG
winrt-handle-back-button SDL_HINT_WINRT_HANDLE_BACK_BUTTON
winrt-privacy-policy-label SDL_HINT_WINRT_PRIVACY_POLICY_LABEL
winrt-privacy-policy-url SDL_HINT_WINRT_PRIVACY_POLICY_URL

Hints in SDL 2.0.4 and higher

Hint name symbol SDL constant name
android-apk-expansion-main-file-version SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION
android-apk-expansion-patch-file-version SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION
android-separate-mouse-and-touch SDL_HINT_ANDROID_SEPARATE_MOUSE_AND_TOUCH
emscripten-keyboard-element SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT
ime-internal-editing SDL_HINT_IME_INTERNAL_EDITING
mac-background-app SDL_HINT_MAC_BACKGROUND_APP
no-signal-handlers SDL_HINT_NO_SIGNAL_HANDLERS
thread-stack-size SDL_HINT_THREAD_STACK_SIZE
video-x11-net-wm-ping SDL_HINT_VIDEO_X11_NET_WM_PING
windows-enable-messageloop SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP
windows-no-close-on-alt-f4 SDL_HINT_WINDOWS_NO_CLOSE_ON_ALT_F4
window-frame-usable-while-cursor-hidden SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN
xinput-use-old-joystick-mapping SDL_HINT_XINPUT_USE_OLD_JOYSTICK_MAPPING

Hint Functions

[procedure] (get-hint name) → string or #f

Returns the current value of the hint as a string, or #f if the hint has no value. See SDL_GetHint. This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (set-hint! name value #!optional priority) → boolean

Sets the value of the hint. See SDL_SetHintWithPriority. This procedure is available in sdl2 egg version 0.2.0 and higher.

name specifies which hint to change. It must be a symbol from the tables above, or a string. This procedure signals an exception if name is an unrecognized symbol (i.e. is not listed in any of the tables above). This procedures accepts any string name, even if it is not recognized.

value specifies the new value of the hint. It must be a string.

priority specifies the priorily level for setting the hint. If it is omitted, the priority will be 'normal. It must be one of these symbols:

Returns #t if the hint's value was set, or #f if it was not set (e.g. because the hint was already set with a higher priority).

[procedure] (clear-hints!)

Removes the values and priorities of all hints. See SDL_ClearHints. This procedure is available in sdl2 egg version 0.2.0 and higher.

Joystick

Joystick Functions

[procedure] (num-joysticks) → integer

See SDL_NumJoysticks.

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

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

See SDL_JoystickOpen.

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

[procedure] (joystick-close! joystick)

See SDL_JoystickClose.

[procedure] (joystick-from-instance-id id) → sdl2:joystick

See SDL_JoystickFromInstanceID.

NOTE: The returned joystick will be a new sdl2:joystick record pointing to the address of the existing joystick. It will be equal? to other sdl2:joystick records for the same joystick, but not eq?.

This procedure is available in sdl2 egg version 0.2.0 and higher. It requires SDL 2.0.4 or higher. It signals an error if the compiled version of SDL is not high enough. Use the libSDL-2.0.4+ feature identifier to check before calling this procedure.

[procedure] (joystick-update!)

See SDL_JoystickUpdate.

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

joystick-event-state returns #t if joystick events are currently enabled, or #f if they are disabled (i.e. all future joystick-related events will be ignored).

The setters enable (if state is #t) or disable (if state is #f) joytsick events. WARNING: Calling the setters may delete all events currently in the event queue.

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

See SDL_JoystickEventState.

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

See SDL_JoystickNameForIndex.

Returns #f if no name can be found.

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

See SDL_JoystickGetDeviceGUID.

Returns a new managed sdl2:joystick-guid.

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.

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

See SDL_JoystickInstanceID.

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

[procedure] (joystick-name joystick) → string or #f

See SDL_JoystickName.

Returns #f if no name can be found.

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

See SDL_JoystickGetGUID.

Returns a new managed sdl2:joystick-guid.

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

See SDL_JoystickGetAttached.

[procedure] (joystick-current-power-level joystick) → symbol

See SDL_JoystickCurrentPowerLevel.

Returns a joystick power level enum symbol:

This procedure is available in sdl2 egg version 0.2.0 and higher. It requires SDL 2.0.4 or higher. It signals an error if the compiled version of SDL is not high enough. Use the libSDL-2.0.4+ feature identifier to check before calling this procedure.

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

See SDL_JoystickNumAxes.

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

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

See SDL_JoystickNumBalls.

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

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

See SDL_JoystickNumButtons.

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

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

See SDL_JoystickNumHats.

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

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

See SDL_JoystickGetAxis.

Signals an exception of kind (exn bounds) if axis-num is less than 0 or greater than the last axis on the joystick (see joystick-num-axiss).

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

See SDL_JoystickGetBall.

This procedure returns multiple values.

Signals an exception of kind (exn bounds) if ball-num is less than 0 or greater than the last trackball on the joystick (see joystick-num-balls). Signals an exception of kind (exn sdl2) if some other error occurs.

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

See SDL_JoystickGetButton.

Signals an exception of kind (exn bounds) if button-num is less than 0 or greater than the last button on the joystick (see joystick-num-buttons).

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

See SDL_JoystickGetHat.

Both procedures signal an exception of kind (exn bounds) if hat-num is less than 0 or greater than the last hat switch on the joystick (see joystick-num-hats).

sdl2:joystick-guid

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

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

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

[procedure] (free-joystick-guid! guid)

Free the memory of the sdl2:joystick-guid's underlying struct. guid's pointer will be set to null (see struct-null?). It is safe to call this procedure with managed or unmanaged sdl2:joystick-guids. It is safe (but has no effect) to free a struct record multiple times.

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

See SDL_JoystickGetGUIDFromString.

Returns a new managed sdl2:joystick-guid.

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

See SDL_JoystickGetGUIDString.

Keyboard

Keyboard Functions

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

See SDL_GetKeyFromName.

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

See SDL_GetKeyFromScancode.

scancode must be a keyboard scancode symbol or an integer representing a keyboard 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
[procedure] (get-scancode-from-name-raw name-str) → integer

See SDL_GetScancodeFromName.

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

See SDL_GetScancodeFromKey.

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

[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) → sdl2:window

See SDL_GetKeyboardFocus.

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

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

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

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

This procedure is based on SDL_GetKeyboardState.

[procedure] (mod-state) → list of symbols
[procedure] (mod-state-raw) → integer
[setter] (set! (mod-state) state)
[setter] (mod-state-set! state)

See SDL_GetModState.

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

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] (make-keysym #!optional scancode sym mod) → sdl2:keysym
[procedure] (make-keysym* #!optional scancode sym mod) → sdl2:keysym

Allocate and initialize a new sdl2:keysym.

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

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

mod defaults to '(). It must be a list of zero or more keyboard modifier symbols or an equivalent integer bitfield.

[procedure] (free-keysym! keysym)

Free the memory of the sdl2:keysym's underlying struct. keysym's pointer will be set to null (see struct-null?). It is safe to call this procedure with managed or unmanaged sdl2:keysyms. It is safe (but has no effect) to free a struct record multiple times.

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

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

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

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

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

Get or set the sdl2:keysym's "mod" field, indicating the modifier keys that this keysym describes.

OpenGL

OpenGL Functions

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

See SDL_GL_CreateContext.

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

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

See SDL_GL_DeleteContext.

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

See SDL_GL_MakeCurrent.

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

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

See SDL_GL_GetCurrentWindow.

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

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

See SDL_GL_GetCurrentContext.

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

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

See SDL_GL_GetAttribute and SDL_GL_SetAttribute.

attr must be an OpenGL attribute symbol or corresponding integer.

The value's type depends on attr:

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

[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 the libSDL-2.0.2+ feature identifier 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 the libSDL-2.0.1+ feature identifier to check before calling this procedure.

[procedure] (gl-swap-window!)

See SDL_GL_SwapWindow.

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

See SDL_GL_GetSwapInterval and SDL_GL_SetSwapInterval.

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

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

See SDL_GL_ExtensionSupported.

[procedure] (gl-bind-texture! texture) → [tex-w tex-h]

Bind the given sdl2:texture for use with the current OpenGL context. See SDL_GL_BindTexture.

Returns multiple values:

tex-w
The bound OpenGL texture's width, as a float (usually 1.0)
tex-h
The bound OpenGL texture's height, as a float (usually 1.0)

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

This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (gl-unbind-texture! texture)

Unbind the given sdl2:texture from the OpenGL context. See SDL_GL_UnbindTexture.

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

This procedure is available in sdl2 egg version 0.2.0 and higher.

sdl2:gl-context

sdl2:gl-context is a record type that wraps a pointer to an SDL_GLContext struct.

[procedure] (gl-context? obj) → boolean

Returns #t if obj is an sdl2:gl-context.

Palette

sdl2:palette

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

[procedure] (palette? obj) → boolean

Returns #t if obj is an sdl2:palette.

[procedure] (make-palette #!optional ncolors) → sdl2:palette
[procedure] (make-palette* #!optional ncolors) → sdl2:palette

Allocate and initialize a new sdl2:palette with the given number of colors. See SDL_AllocPalette.

ncolors defaults to 256. Common values are 2 (for a 1-bit surface), 16 (for a 4-bit surface), and 256 (for an 8-bit surface).

NOTE: Usually you do not need to manually allocate a palette. A palette will be created for you when you create a surface with a depth of 8 or lower, and the palette will be automatically freed when the surface is freed (unless the palette is still being used by other surfaces).

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

[procedure] (free-palette! palette)

Free the memory of the sdl2:palette's underlying struct. palette's pointer will be set to null (see struct-null?). It is safe to call this procedure with managed or unmanaged sdl2:palettes. It is safe (but has no effect) to free a struct record multiple times.

See SDL_FreePalette.

[procedure] (palette-ncolors palette) → integer
[procedure] (palette-ncolours palette) → integer

Returns the number of colors in the palette. Common values are 2 (for a 1-bit surface), 16 (for a 4-bit surface), and 256 (for an 8-bit surface).

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

palette-ref returns a copy of the color at the given index of the palette, as a managed sdl2:color.

The setters set the given index of the palette to a copy of the given sdl2:color.

These procedures signal an exception of kind (exn bounds) if the given index is out of bounds.

[procedure] (palette-colors palette) → vector of sdl2:colors
[procedure] (palette-colours palette) → vector of sdl2:colors
[setter] (set! (palette-colors palette) colors-vec) → boolean
[setter] (set! (palette-colours palette) colors-vec) → boolean
[setter] (palette-colors-set! colors-vec #!optional firstcolor) → boolean
[setter] (palette-colours-set! colors-vec #!optional firstcolor) → boolean

palette-colors and palette-colours return copies of all colors in the palette, as a Scheme vector of managed sdl2:colors.

The setters set multiple colors in the palette to copies of the given colors. See SDL_SetPaletteColors.

colors-vec must be a Scheme vector of sdl2:colors.

firstcolor specifies the first index of the palette to set. I.e., palette index firstcolor will be set to the first color in colors-vec, palette index firstcolor + 1 will be set to the second color, and so on. firstcolor defaults to 0. Signals an exception of kind (exn bounds) if firstcolor is out of bounds.

The set! form cannot accept the firstcolor argument.

The setters return #t if every color in colors-vec was used, or #f if some colors were not used, e.g. because there were more colors in the vector than could fit in the palette.

Pixel Format

Pixel Format Functions

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

See SDL_MapRGB and SDL_MapRGBA.

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

See SDL_GetRGB and SDL_GetRGBA.

These procedures return multiple values.

[procedure] (pixel-format-enum-to-masks format-enum) → [bpp rmask gmask bmask amask]

See SDL_PixelFormatEnumToMasks.

format-enum must be a pixel format symbol or equivalent integer.

This procedure returns multiple values:

bpp
The color depth (bits per pixel) of the format.
rmask
The red mask of the format.
gmask
The green mask of the format.
bmask
The blue mask of the format.
amask
The alpha mask of the format.

Signals an exception of kind (exn sdl2) if conversion was not possible.

sdl2:pixel-format

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

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

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

[procedure] (make-pixel-format #!optional format) → sdl2:pixel-format
[procedure] (make-pixel-format* #!optional format) → sdl2:pixel-format

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

format defaults to 'unknown. It must be a pixel format symbol or equivalent integer. See SDL_AllocFormat.

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

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

Free the memory of the sdl2:pixel-format's underlying struct. pixel-format's pointer will be set to null (see struct-null?). It is safe to call this procedure with managed or unmanaged sdl2:pixel-formats. It is safe (but has no effect) to free a struct record multiple times.

See SDL_FreeFormat.

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

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

[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 val)

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

See SDL_SetPixelFormatPalette.

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

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

Get the sdl2:pixel-format's "bits-per-pixel" field, as an integer. Common values are 32, 24, 16, 15, 8, 4, and 1.

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

Get the sdl2:pixel-format's "bits-per-pixel" field, as an integer. Possible values are 4, 3, 2, and 1.

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

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

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

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

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

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

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

Get the sdl2:pixel-format's "amask" (alpha mask) field, as a nonnegative integer. It will be 0 if there is no alpha channel.

Rect / Point

Rect / Point Functions

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

Returns #t if rect's width and/or height is less than or equal to zero. See SDL_RectEmpty.

[procedure] (point-in-rect? point rect) → boolean

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

This procedure is available in sdl2 egg version 0.2.0 and higher. It requires SDL 2.0.4 or higher. It signals an error if the compiled version of SDL is not high enough. Use the libSDL-2.0.4+ feature identifier to check before calling this procedure.

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

See SDL_EnclosePoints.

points must be a list of sdl2:points.

clip must be either an sdl2:rect or #f (the default). If clip is an sdl2:rect, points outside the clip rect will be ignored.

If result-rect is omitted or #f, a new managed sdl2:rect will be returned. If result-rect is an sdl2:rect, it will be modified and returned. It is safe for result-rect to be the same object as clip, in which case clip will be modified and returned.

This procedure returns multiple values:

rect
An sdl2:rect that encloses all matching points. This will be the same object as result-rect, if result-rect was specified.
any-enclosed?
#t if any points were enclosed, or #f if all points were clipped
[procedure] (has-intersection? rect1 rect2) → boolean

Returns #t if rect1 and rect2 intersect, or #f if they do not. See SDL_HasIntersection.

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

Calculates the intersection of rect1 and rect2. See SDL_IntersectRect.

If result-rect is omitted or #f, a new managed sdl2:rect will be returned. If result-rect is an sdl2:rect, it will be modified and returned. It is safe for result-rect to be the same object as rect1 or rect2, in which case rect1 or rect2 will be modified and returned. It is safe (but useless) for rect1 and rect2 to be the same object.

This procedure returns multiple values:

rect
An sdl2:rect of the intersection of rect1 and rect2. This will be the same object as result-rect, if result-rect was specified.
intersect?
#t if rect1 and rect2 intersect, otherwise #f
[procedure] (intersect-rect-and-line rect x1 y1 x2 y2) → [intersect? x1-new y1-new x2-new y2-new]

Calculates the intersection between rect and the line segment described by x1, y1, x2, and y2. See SDL_IntersectRectAndLine.

rect must be an sdl2:rect. x1, y1, x2, and y2 should be integers.

This procedure returns multiple values:

intersect?
#t if the line segment intersects with the rect, otherwise #f
x1-new
integer x1 of the new line segment
y1-new
integer y1 of the new line segment
x2-new
integer x2 of the new line segment
y2-new
integer y2 of the new line segment

If the line segment does not intersect the rect, then intersect? will be #f, and x1-new, y1-new, x2-new, and y2-new will be the same as the original arguments.

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

See SDL_UnionRect.

If result-rect is omitted or #f, a new managed sdl2:rect will be returned. If result-rect is an sdl2:rect, it will be modified and returned. It is safe for result-rect to be the same object as rect1 or rect2, in which case rect1 or rect2 will be modified and returned. It is safe (but useless) for rect1 and rect2 to be the same object.

sdl2:rect

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

[procedure] (rect? obj) → boolean

Returns #t if obj is an sdl2:rect.

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

Allocate and initialize a new sdl2:rect.

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

[procedure] (free-rect! rect)

Free the memory of the sdl2:rect's underlying struct. rect's pointer will be set to null (see struct-null?). It is safe to call this procedure with managed or unmanaged sdl2:rects. It is safe (but has no effect) to free a struct record multiple times.

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

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

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

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

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

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

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

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

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

Convenient way of setting multiple fields of the sdl2:rect. Any arguments that are #f will cause no change to that field. E.g. (rect-set! my-rect 42 #f 1337 #f) will set the "x" field to 42 and the "w" field to 1337, but will not change the "y" or "h" fields. Returns rect after it is modified.

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

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

[procedure] (rect->values rect) → [x y w h]

Returns multiple values containing the value of each field of the sdl2:rect. This is useful for destructuring an sdl2:rect using receive or let-values.

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

Efficiently compare two sdl2:rects. Returns #t if the value of every field in rect1 is equal to the value of the corresponding field in rect2. See SDL_RectEquals.

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

Efficiently copy the given sdl2:rect, returning a new sdl2:rect with the same values.

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
[procedure] (make-point* #!optional x y) → sdl2:point

Allocate and initialize a new sdl2:point.

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

[procedure] (free-point! point)

Free the memory of the sdl2:point's underlying struct. point's pointer will be set to null (see struct-null?). It is safe to call this procedure with managed or unmanaged sdl2:points. It is safe (but has no effect) to free a struct record multiple times.

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

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

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

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

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

Convenient way of setting multiple fields of the sdl2:point. Any arguments that are #f will cause no change to that field. E.g. (point-set! my-point 42 #f) will set the "x" field to 42, but will not change the "y" field. Returns point after it is modified.

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

Returns a list (x y) containing the value of each field of the sdl2:point.

[procedure] (point->values point) → [x y]

Returns multiple values containing the value of each field of the sdl2:point. This is useful for destructuring an sdl2:point using receive or let-values.

[procedure] (point=? point1 point2) → boolean

Efficiently compare two sdl2:points. Returns #t if the value of every field in point1 is equal to the value of the corresponding field in point2.

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

Efficiently copy the given sdl2:point, returning a new sdl2:point with the same values.

Renderer

Renderer is one part of 2D Accelerated Rendering. See also Texture.

Renderer support is available in sdl2 egg 0.2.0 and higher.

Renderer Functions

[procedure] (create-renderer! window #!optional index flags) → sdl2:renderer

Create a new sdl2:renderer associated with the given window. See SDL_CreateRenderer. This procedure is available in sdl2 egg version 0.2.0 and higher.

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

[procedure] (create-software-renderer! surface) → sdl2:renderer

Create a sdl2:renderer which renders onto the given sdl2:surface. See SDL_CreateSoftwareRenderer. This procedure is available in sdl2 egg version 0.2.0 and higher.

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

[procedure] (destroy-renderer! renderer)

See SDL_DestroyRenderer. This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (create-window-and-renderer! width height #!optional window-flags) → [window renderer]

Create a sdl2:window and a sdl2:renderer that renders to the window. This is more convenient, but less flexible, than using create-window! and then create-renderer!. See SDL_CreateWindowAndRenderer. This procedure is available in sdl2 egg version 0.2.0 and higher.

width and height must be inditegers specifying the height of the window and renderer to create.

window-flags defaults to '(). It must be a list of zero or more window flag symbols (or an equivalent integer bitfield).

This procedure returns multiple values:

window
The sdl2:window that was created.
renderer
The sdl2:renderer that was created.
[procedure] (get-renderer window) → sdl2:renderer

Return the renderer associated with the given sdl2:window. See SDL_GetRenderer. This procedure is available in sdl2 egg version 0.2.0 and higher.

NOTE: The returned renderer will be a new sdl2:renderer record pointing to the address of the existing renderer. It will be equal? to other sdl2:renderer records for the same renderer, but not eq?.

Signals an exception of kind (exn sdl2) if the window does not have a renderer, or if an error occurs.

[procedure] (num-render-drivers) → integer

See SDL_GetNumRenderDrivers. This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (render-driver-info index) → sdl2:renderer-info

See SDL_GetRenderDriverInfo. This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (render-present!)

Update the renderer to show any changes that have occurred. See SDL_RenderPresent. This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (render-copy! renderer texture #!optional srcrect dstrect) →

Copy all or part of the given texture onto the renderer. See SDL_RenderCopy. This procedure is available in sdl2 egg version 0.2.0 and higher.

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

[procedure] (render-copy-ex! renderer texture #!optional srcrect dstrect angle center flip)

Copy all or part of the given texture onto the renderer, optionally rotating or flipping the texture. See SDL_RenderCopyEx. This procedure is available in sdl2 egg version 0.2.0 and higher.

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

[procedure] (render-read-pixels-raw renderer rect format pixels-out pitch)

Read the pixels from some or all of the given renderer. This is for advanced users, and must be used with caution. See SDL_RenderReadPixels. This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (render-clear! renderer)

Clear the entire renderer, using the renderer's current draw color. See SDL_RenderClear. This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (render-draw-line! renderer x1 y1 x2 y2)
[procedure] (render-draw-lines! renderer points)

Draw a line segment or multiple line segments, using the renderer's current draw color and blend mode. See SDL_RenderDrawLine and SDL_RenderDrawLines. These procedures are available in sdl2 egg version 0.2.0 and higher.

[procedure] (render-draw-point! renderer x y)
[procedure] (render-draw-points! renderer points)

Draw one or multiple points, using the renderer's current draw color and blend mode. See SDL_RenderDrawPoint and SDL_RenderDrawPoints. These procedures are available in sdl2 egg version 0.2.0 and higher.

[procedure] (render-draw-rect! renderer rect)
[procedure] (render-draw-rects! renderer rects)

Draw one or multiple outlined rectangles, using the renderer's current draw color and blend mode. See SDL_RenderDrawRect and SDL_RenderDrawRects. These procedures are available in sdl2 egg version 0.2.0 and higher.

[procedure] (render-fill-rect! renderer rect)
[procedure] (render-fill-rects! renderer rects)

Draw one or multiple filled rectangles, using the renderer's current draw color and blend mode. See SDL_RenderFillRect and SDL_RenderFillRects. These procedures are available in sdl2 egg version 0.2.0 and higher.

sdl2:renderer

sdl2:renderer is a record type that wraps a pointer to an SDL_Renderer struct. sdl2:renderer is available in sdl2 egg version 0.2.0 and higher.

[procedure] (renderer? obj) → boolean

Returns #t if obj is an sdl2:renderer. This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (render-draw-blend-mode renderer) → symbol
[procedure] (render-draw-blend-mode-raw renderer) → integer
[setter] (render-draw-blend-mode-set! renderer mode)
[setter] (set! (render-draw-blend-mode renderer) mode)

Get or set the renderer's draw blend mode. This affects future drawing operations. See SDL_GetRenderDrawBlendMode and SDL_SetRenderDrawBlendMode. These procedures are available in sdl2 egg version 0.2.0 and higher.

[procedure] (render-draw-color renderer) → sdl2:color
[procedure] (render-draw-colour renderer) → sdl2:color
[setter] (render-draw-color-set! renderer color)
[setter] (render-draw-colour-set! renderer color)
[setter] (set! (render-draw-color renderer) color)
[setter] (set! (render-draw-colour renderer) color)

Get or set the renderer's draw color. This affects future drawing operations. See SDL_GetRenderDrawColor and SDL_SetRenderDrawColor. These procedures are available in sdl2 egg version 0.2.0 and higher.

[procedure] (render-clip-rect renderer) → sdl2:rect
[setter] (render-clip-rect-set! renderer rect)
[setter] (set! (render-clip-rect renderer) rect)

Get or set the sdl2:renderer's clip rect. See SDL_RenderGetClipRect and SDL_RenderSetClipRect. These procedures are available in sdl2 egg version 0.2.0 and higher.

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

But, be advised that it also returns #<sdl2:rect (0 0 0 0)> if that is the current clip rect. So, the meaning of #<sdl2:rect (0 0 0 0)> is ambiguous. Use render-clip-enabled? (in SDL 2.0.4 or higher) to unambiguously check whether clipping is enabled or disabled.

The setters accept either an sdl2:rect to enable clipping and set the clip rect, or #f to disable clipping. Setting to #<sdl2:rect (0 0 0 0)> does not disable clipping.

[procedure] (render-clip-enabled? renderer) → boolean

Returns #t if clipping is enabled for the given sdl2:renderer, or #f is clipping is disabled. See SDL_RenderIsClipEnabled. This procedure is available in sdl2 egg version 0.2.0 and higher.

Requires SDL 2.0.4 or higher. Signals an error if the compiled version of SDL is not high enough. Use the libSDL-2.0.4+ feature identifier to check before calling this procedure.

[procedure] (renderer-output-size renderer) → [w h]

See SDL_GetRendererOutputSize. This procedure is available in sdl2 egg version 0.2.0 and higher.

This procedure returns multiple values, the output width and height, as integers.

[procedure] (render-logical-size renderer) → [w h]
[setter] (render-logical-size-set! renderer size)
[setter] (set! (render-logical-size renderer) size)

Get or set the renderer's logical size. See SDL_RenderGetLogicalSize and SDL_RenderSetLogicalSize. These procedures are available in sdl2 egg version 0.2.0 and higher.

[procedure] (render-scale renderer) → [x-scale y-scale]
[setter] (render-scale-set! renderer scales)
[setter] (set! (render-scale-set! renderer) scales)

Get or set the sdl2:renderer's x and y scaling factors. See SDL_RenderGetScale and SDL_RenderSetScale. These procedures are available in sdl2 egg version 0.2.0 and higher.

[procedure] (render-target-supported? renderer) → boolean

Returns #t if the given renderer can have a render target. See SDL_RenderTargetSupported. This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (render-target renderer) → sdl2:texture or #f
[setter] (render-target-set! renderer target)
[setter] (set! (render-target renderer) target)

Get or set the renderer's render target, i.e. the texture that the renderer will render onto. See SDL_GetRenderTarget and SDL_SetRenderTarget. These procedures are available in sdl2 egg version 0.2.0 and higher.

render-target returns #f if the renderer has no render target.

The setters signal an exception of kind (exn sdl2) on failure, for example if the renderer does not support a render target. You should use render-target-supported? to test whether the renderer supports a render target.

[procedure] (render-viewport renderer) → sdl2:rect
[setter] (render-viewport-set! renderer rect)
[setter] (set! (render-viewport renderer) rect)

Get or set the renderer's viewport. See SDL_RenderGetViewport and SDL_RenderSetViewport. These procedures are available in sdl2 egg version 0.2.0 and higher.

sdl2:renderer-info

sdl2:renderer-info is a record type that wraps a pointer to an SDL_RendererInfo struct. sdl2:renderer-info is available in sdl2 egg version 0.2.0 and higher.

[procedure] (renderer-info? obj) → boolean

Returns #t if obj is an sdl2:renderer-info. This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (get-renderer-info renderer) → sdl2:renderer-info
[procedure] (get-renderer-info* renderer) → sdl2:renderer-info

Return a sdl2:renderer-info with information about the given sdl2:renderer. See SDL_GetRendererInfo. These procedures are available in sdl2 egg version 0.2.0 and higher.

[procedure] (free-renderer-info! renderer-info)

Free the memory of the sdl2:renderer-info's underlying struct. renderer-info's pointer will be set to null (see struct-null?). It is safe to call this procedure with managed or unmanaged sdl2:renderer-infos. It is safe (but has no effect) to free a struct record multiple times. This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (renderer-info-name renderer-info) → string

Get the sdl2:renderer-info's "name" field, as a string. This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (renderer-info-flags renderer-info) → list of symbols
[procedure] (renderer-info-flags-raw renderer-info) → integer

Get the sdl2:renderer-info's "flags" field, as a list of symbols or an integer. TODO: Link to flags enums. These procedures are available in sdl2 egg version 0.2.0 and higher.

[procedure] (renderer-info-num-texture-formats renderer-info) → integer

Get the sdl2:renderer-info's "num-texture-formats" field, as an integer. This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (renderer-info-texture-formats renderer-info) → list of symbols

Get the sdl2:renderer-info's "texture-formats" field, as a list of pixel format symbols. This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (renderer-info-max-texture-width renderer-info) → integer

Get the sdl2:renderer-info's "max-texture-width" field, as an integer. This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (renderer-info-max-texture-height renderer-info) → integer

Get the sdl2:renderer-info's "max-texture-height" field, as an integer. This procedure is available in sdl2 egg version 0.2.0 and higher.

RWops

RWops Functions

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

See SDL_RWFromFile.

You should close the sdl2:rwops when you are done with it, using rw-close! or one of the procedures that can automatically close the sdl2:rwops, such as load-bmp-rw.

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

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

See SDL_RWFromConstMem.

You should close the sdl2:rwops when you are done with it, using rw-close! or one of the procedures that can automatically close the sdl2:rwops, such as load-bmp-rw.

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

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

See SDL_RWFromMem.

You should close the sdl2:rwops when you are done with it, using rw-close! or one of the procedures that can automatically close the sdl2:rwops, such as load-bmp-rw.

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

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

Create a new sdl2:rwops that accesses the memory of the given blob. You should close the sdl2:rwops when you are done with it, using rw-close! or one of the procedures that can automatically close the sdl2:rwops, such as load-bmp-rw.

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

You can also use this procedure to create a sdl2:rwops from a SRFI-4 numeric vector, by first converting it to a blob using e.g. u8vector->blob/shared.

CAUTION: Creating a sdl2:rwops from a blob in CHICKEN-managed memory is unstable: the blob might be garbage collected or moved in memory, which would break the sdl2:rwops. To be safe, you should evict the blob and create the sdl2:rwops from the evicted blob (not the original). You may wish to release the evicted blob after you have closed the sdl2:rwops. Example:

(let* ((evicted-blob (object-evict '#${...}))
       (rwops (sdl2:rw-from-blob evicted-blob))
       (surf (sdl2:load-bmp-rw rwops #t)))
  (object-release evicted-blob)
  surf)
[procedure] (rw-from-string str) → sdl2:rwops

Create a new sdl2:rwops that accesses the memory of the given CHICKEN Scheme string. You should close the sdl2:rwops when you are done with it, using rw-close! or one of the procedures that can automatically close the sdl2:rwops, such as load-bmp-rw.

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

CAUTION: Creating a sdl2:rwops from a string in CHICKEN-managed memory is unstable: the string might be garbage collected or moved in memory, which would break the sdl2:rwops. To be safe, you should evict the string and create the sdl2:rwops from the evicted string (not the original). You may wish to release the evicted string after you have closed the sdl2:rwops. Example:

(let* ((evicted-string (object-evict "..."))
       (rwops (sdl2:rw-from-string evicted-string))
       (surf (sdl2:load-bmp-rw rwops #t)))
  (object-release evicted-string)
  surf)
[procedure] (rw-close! rwops)

See SDL_RWclose.

Close and clean up the given sdl2:rwops. This frees the memory used by the SDL_RWops struct itself, but does not free or release the pointer, blob, or string that the sdl2:rwops was reading/writing from. (It does close files opened with rw-from-file, though.)

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

sdl2:rwops

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

[procedure] (rwops? obj) → boolean

Returns #t if obj is an sdl2:rwops.

[procedure] (rwops-type rwops) → symbol
[procedure] (rwops-type-raw rwops) → integer

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

Surface

Surface Functions

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

See SDL_CreateRGBSurface.

Returns a new unmanaged sdl2:surface with the given properties. You must call free-surface! when you are done with it.

See make-surface for a more convenient interface.

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

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

Returns a new unmanaged sdl2:surface with the given properties, using existing pixel data (a pointer, e.g. from surface-pixels-raw). You must call free-surface! when you are done with it.

See SDL_CreateRGBSurfaceFrom.

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

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

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

See SDL_ConvertSurface.

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

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

See SDL_LoadBMP.

Attempts to load a BMP image file. Returns a sdl2:surface containing the image data. Signals an exception of kind (exn sdl2) if the image could not be loaded.

NOTE: This procedure only supports certain kinds of BMP image. Use the sdl2-image egg for better BMP support, plus support for loading other image formats like JPG, PNG, and GIF.

[procedure] (load-bmp-rw rwops #!optional close?) → sdl2:surface
[procedure] (load-bmp-rw* rwops #!optional close?) → sdl2:surface

See SDL_LoadBMP_RW.

Attempts to load a BMP image from the given sdl2:rwops. Returns a sdl2:surface containing the image data. Signals an exception of kind (exn sdl2) if the image could not be loaded.

If close? is #t, rwops will be automatically closed (see rw-close!) after the image is loaded. If close? is #f or omitted, rwops will not be closed.

NOTE: This procedure only supports certain kinds of BMP image. Use the sdl2-image egg for better BMP support, plus support for loading other image formats like JPG, PNG, and GIF.

[procedure] (save-bmp! surface filepath)

See SDL_SaveBMP.

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

[procedure] (save-bmp-rw! surface rwops #!optional close?)

See SDL_SaveBMP_RW.

If close? is #t, rwops will be automatically closed (see rw-close!) after the image is loaded. If close? is #f or omitted, rwops will not be closed.

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

[procedure] (lock-surface! surface)
[procedure] (unlock-surface! surface)

See SDL_LockSurface and SDL_UnlockSurface.

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

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

See SDL_MUSTLOCK.

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

See SDL_BlitSurface.

May modify dest-rect.

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

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

See SDL_BlitScaled.

May modify dest-rect.

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

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

See SDL_FillRect.

rect may be an sdl2:rect to fill part of the surface, or #f to fill the entire surface.

color may be an sdl2:color or a mapped color (an integer, like returned by map-rgba).

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

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

See SDL_FillRects.

rects must be a list of sdl2:rects.

color may be an sdl2:color or a mapped color (an integer, like returned by map-rgba).

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

[procedure] (surface-ref surface x y) → sdl2:color
[procedure] (surface-ref-raw surface x y) → integer
[setter] (set! (surface-ref surface x y) color)
[setter] (surface-set! surface x y color)

Get or set the color of the specified pixel on the surface.

These procedures automatically lock and unlock the surface if needed. They signal an exception of kind (exn sdl2) if the surface cannot be locked.

These procedures signal an exception of kind (exn bounds) if x or y is out of bounds.

The setters ignore the surface's clip rect.

[procedure] (rotate-surface-90 surface turns) → sdl2:surface
[procedure] (rotate-surface-90* surface turns) → sdl2:surface

Return a copy of the given surface rotated by the given number of 90º clockwise turns. turns must be an integer. For example:

The new surface will have an equivalent pixel format, color key, blend mode, alpha mod, and color mod as the given surface. If the given surface has a palette, the new surface will share the same palette. The new surface will have no clip rect.

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

[procedure] (flip-surface surface flip-x? flip-y?) → sdl2:surface
[procedure] (flip-surface* surface flip-x? flip-y?) → sdl2:surface

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

The new surface will have an equivalent pixel format, color key, blend mode, alpha mod, and color mod as the given surface. If the given surface has a palette, the new surface will share the same palette. The new surface will have no clip rect.

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

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] (make-surface width height depth) → sdl2:surface
[procedure] (make-surface* width height depth) → sdl2:surface

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

These procedures signal an exception of kind (exn sdl2) if the sdl2:surface could not be created (e.g. because the color depth is unsupported).

[procedure] (free-surface! surface)

Free the memory of the sdl2:surface's underlying struct. surface's pointer will be set to null (see struct-null?). It is safe to call this procedure with managed or unmanaged sdl2:surfaces. It is safe (but has no effect) to free a struct record multiple times.

See SDL_FreeSurface.

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

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

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

[procedure] (surface-w surface) → integer

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

[procedure] (surface-h surface) → integer

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

[procedure] (surface-pitch surface) → integer

Get the sdl2:surface's "pitch" field, as a nonnegative integer indicating how many bytes are used to represent one row of pixel data.

[procedure] (surface-pixels-raw surface) → pointer or #f

Get the sdl2:surface's "pixels" field, as a raw pointer to the sdl2:surface's pixels. Don't use this unless you really know what you are doing!

If you want to get or set a pixel, use surface-ref and surface-set! instead. They are much safer, more convenient, and more efficient than accessing the pixel data using this pointer.

[procedure] (surface-userdata-raw surface) → pointer or #f
[setter] (set! (surface-userdata-raw surface) val)
[setter] (surface-userdata-raw-set! surface val)

Get or set the sdl2:surface's "userdata" field, as a pointer or #f.

If you want to store a pointer to a Scheme object here, be sure to evict the object first. Otherwise the object's location in memory might change, rendering the pointer invalid.

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

Get or set the sdl2:surface's "refcount" field, as an integer.

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

surface-clip-rect returns a copy of the surface's clip rect. See SDL_GetClipRect.

The setters sets the surface's clip rect to a copy of the given rect. rect may be #f, which disables clipping. See SDL_SetClipRect.

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

[procedure] (surface-color-key surface) → sdl2:color or #f
[procedure] (surface-colour-key surface) → sdl2:color or #f
[procedure] (surface-color-key-raw surface) → integer or #f
[procedure] (surface-colour-key-raw surface) → integer or #f
[setter] (set! (surface-color-key surface) color)
[setter] (set! (surface-colour-key surface) color)
[setter] (surface-color-key-set! surface color)
[setter] (surface-colour-key-set! surface color)

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

See SDL_GetColorKey and SDL_SetColorKey.

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

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

See SDL_GetSurfaceAlphaMod and SDL_SetSurfaceAlphaMod.

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

[procedure] (surface-blend-mode surface) → symbol
[procedure] (surface-blend-mode-raw surface) → integer
[setter] (set! (surface-blend-mode surface) mode)
[setter] (surface-blend-mode-set! surface mode)

See SDL_GetSurfaceBlendMode and SDL_SetSurfaceBlendMode.

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

[procedure] (surface-color-mod surface) → [r g b]
[procedure] (surface-colour-mod surface) → [r g b]
[setter] (set! (surface-color-mod surface) rgb)
[setter] (set! (surface-colour-mod surface) rgb)
[setter] (surface-color-mod-set! surface rgb)
[setter] (surface-colour-mod-set! surface rgb)

See SDL_GetSurfaceColorMod and SDL_SetSurfaceColorMod.

surface-color-mod and surface-colour-mod return multiple values.

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

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

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

surface-palette returns the surface's palette, or #f if it has no palette. It is equivalent to (compose pixel-format-palette surface-format).

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

See SDL_SetSurfacePalette.

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

Enable RLE acceleration if enable? is #t, or disable RLE acceleration if enable? is #f. See SDL_SetSurfaceRLE.

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

Texture

Texture is one part of 2D Accelerated Rendering. See also Renderer.

Renderer support is available in sdl2 egg 0.2.0 and higher.

sdl2:texture

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

Textures are available in sdl2 egg version 0.2.0 and higher.

[procedure] (texture? obj) → boolean

Returns #t if obj is an sdl2:texture.

This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (create-texture renderer format access w h) → sdl2:texture
[procedure] (create-texture* renderer format access w h) → sdl2:texture

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

These procedures signal an exception of kind (exn sdl2) if the sdl2:texture could not be created.

These procedures are available in sdl2 egg version 0.2.0 and higher.

[procedure] (create-texture-from-surface renderer surface) → sdl2:texture
[procedure] (create-texture-from-surface* renderer surface) → sdl2:texture

Create a new sdl2:texture from a sdl2:surface.

The texture will contain a copy of the pixel data from the surface. The texture will have the same color mod and alpha mod as the surface. If the surface had a color key, the texture will have 'blend blend mode; otherwise it will have the same blend mode as the surface.

These procedures signal an exception of kind (exn sdl2) if the sdl2:texture could not be created.

These procedures are available in sdl2 egg version 0.2.0 and higher.

[procedure] (destroy-texture! texture)

Destroy the sdl2:texture, freeing its underlying struct. texture's pointer will be set to null (see struct-null?). It is safe to call tihs procedure with managed on unmanaged sdl2:textures. It is safe (but has no effect) to destroy an sdl2:texture multiple times.

See SDL_DestroyTexture.

This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (query-texture texture) → [format access w h]
[procedure] (query-texture-raw texture) → [format-int access-int w h]

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

query-texture returns multiple values:

format
The sdl2:texture's pixel format, as a pixel format enum symbol
access
The sdl2:texture's access mode, as a texture access enum symbol
w
The sdl2:texture's width, as a nonnegative integer measured in pixels
h
The sdl2:texture's height, as a nonnegative integer measured in pixels

query-texture-raw is similar, except it returns raw integer values (not symbols) for format and access.

These procedures are available in sdl2 egg version 0.2.0 and higher.

If you only want one of these pieces of information, it is more convenient and efficient to use one of these procedures instead:

[procedure] (texture-format texture) → symbol

Get the sdl2:texture's pixel format, as a pixel format enum symbol. This is equivalent to (nth-value 0 (query-texture texture)), but more convenient and efficient.

This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (texture-access texture) → symbol

Get the sdl2:texture's access mode, as a texture access enum symbol. This is equivalent to (nth-value 1 (query-texture texture)), but more convenient and efficient.

This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (texture-w texture) → integer

Get the sdl2:texture's width, as a nonnegative integer measured in pixels. This is equivalent to (nth-value 2 (query-texture texture)), but more convenient and efficient.

This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (texture-h texture) → integer

Get the sdl2:texture's height, as a nonnegative integer measured in pixels. This is equivalent to (nth-value 3 (query-texture texture)), but more convenient and efficient.

This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (texture-alpha-mod texture) → integer
[setter] (set! (texture-alpha-mod texture) mod)
[setter] (texture-alpha-mod-set! texture mod)

See SDL_GetTextureAlphaMod and SDL_SetTextureAlphaMod.

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

These procedures are available in sdl2 egg version 0.2.0 and higher.

[procedure] (texture-blend-mode texture) → symbol
[procedure] (texture-blend-mode-raw texture) → integer
[setter] (set! (texture-blend-mode texture) mode)
[setter] (texture-blend-mode-set! texture mode)

See SDL_GetTextureBlendMode and SDL_SetTextureBlendMode.

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

These procedures are available in sdl2 egg version 0.2.0 and higher.

[procedure] (texture-color-mod texture) → [r g b]
[procedure] (texture-colour-mod texture) → [r g b]
[setter] (set! (texture-color-mod texture) rgb)
[setter] (set! (texture-colour-mod texture) rgb)
[setter] (texture-color-mod-set! texture rgb)
[setter] (texture-colour-mod-set! texture rgb)

See SDL_GetTextureColorMod and SDL_SetTextureColorMod.

texture-color-mod and texture-colour-mod return multiple values.

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

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

These procedures are available in sdl2 egg version 0.2.0 and higher.

[procedure] (lock-texture-raw! texture rect) → [pixels pitch]

Lock the texture so that its pixel data can be overwritten. This is for advanced users, and must be used with caution. See SDL_LockTexture. See also unlock-texture!.

This procedure returns multiple values:

pixels
A raw pointer that you can write pixel data to. Does not necessarily contain the old data.
pitch
An integer indicating the pitch of the pixel data

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

This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (unlock-texture! texture)

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

This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (update-texture-raw! texture rect pixels pitch)

Overwrite part or all of the texture's pixel data. This is for advanced users, and must be used with caution. See SDL_UpdateTexture.

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

This procedure is available in sdl2 egg version 0.2.0 and higher.

[procedure] (update-yuv-texture-raw! texture rect y-plane y-pitch u-plane u-pitch v-plane v-pitch)

Overwrite part or all of a YV12- or IYUV-formatted texture's pixel data. This is for advanced users, and must be used with caution. See SDL_UpdateYUVTexture.

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

This procedure is available in sdl2 egg version 0.2.0 and higher. It requires SDL 2.0.1 or higher. It signals an error if the compiled version of SDL is not high enough. Use the libSDL-2.0.1+ feature identifier to check before calling this procedure.

Timer

[procedure] (delay! milliseconds)

See SDL_Delay.

CAUTION: This procedure is not compatible with SRFI-18 threads. It will cause all threads to sleep for the given duration. If you are using multiple threads, you should instead call SRFI-18's thread-sleep!, which will cause only the current thread to sleep. For example, call (thread-sleep! 0.025) instead of (delay! 25).

[procedure] (get-ticks) → integer

See SDL_GetTicks.

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

See SDL_GetPerformanceCounter.

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

See SDL_GetPerformanceFrequency.

Touch / Gesture

Touch / Gesture Functions

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

See SDL_GetNumTouchDevices.

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

See SDL_GetTouchDevice.

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

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

See SDL_GetNumTouchFingers.

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

See SDL_GetTouchFinger.

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

sdl2:finger

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

[procedure] (finger? obj) → boolean

Returns #t if obj is an sdl2:finger.

[procedure] (finger-id finger) → integer

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

[procedure] (finger-x finger) → float

Get the sdl2:finger's "x" field, as a float in the range 0.0 to 1.0 (inclusive), indicating the normalized X position of the finger.

[procedure] (finger-y finger) → float

Get the sdl2:finger's "y" field, as a float in the range 0.0 to 1.0 (inclusive), indicating the normalized Y position of the finger.

[procedure] (finger-pressure finger) → float

Get the sdl2:finger's "pressure" field, as a float in the range 0.0 to 1.0 (inclusive), indicating the normalized pressure of the finger.

Version

Version Feature Identifiers

In sdl2 egg version 0.2.0 and higher, the egg automatically registers feature identifiers which can be used to detect the versions of the sdl2 egg and SDL at compile time or run time, for example using the cond-expand macro, #+foo syntax, or the feature? procedure.

Some or all of the following feature identifiers will be registered depending on the circumstances:

Feature ID Meaning
sdl2 Using any version of the sdl2 egg
sdl2-0.2.0+ Using sdl2 egg 0.2.0 or higher
libSDL-2.0.0+ The sdl2 egg was compiled with SDL 2.0.0 or higher
libSDL-2.0.1+ ... 2.0.1 or higher
libSDL-2.0.2+ ... 2.0.2 or higher
libSDL-2.0.3+ ... 2.0.3 or higher
libSDL-2.0.4+ ... 2.0.4 or higher

These are cumulative, so if you are using the latest version of the sdl2 egg and the latest version of SDL, all of the above identifiers will be defined.

Here are some examples of how you can use these identifiers:

(use (prefix sdl2 sdl2:))

;; Compile time check using #+foo reader syntax:
#+(not sdl2-0.2.0+)
(begin-for-syntax
  (error "You need sdl2 egg 0.2.0 or higher to compile this program."))

;; Compile-time check using cond-expand macro:
(cond-expand
 (libSDL-2.0.4+
  (include "file-that-needs-SDL-204.scm"))
 (else
  (include "alternative-file.scm")))

;; Run-time check using feature? procedure:
(when (feature? 'sdl2)
  (print "You are using the sdl2 egg. The future seems bright."))

Version Functions

[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. For example, (version-at-least? 2 0 1) returns #t if the sdl2 egg was compiled with SDL 2.0.1 or higher.

Some SDL features are only available after a certain version, so you can use this procedure to check whether the feature is available.

[procedure] (compiled-version) → list of integers
[procedure] (current-version) → list of integers

Returns a list of three nonnegative integers, indicating a version number of SDL. For example, the list (2 0 3) indicates SDL 2.0.3.

For example, the user may have compiled the sdl2 egg with SDL 2.0.3, then later upgraded SDL to 2.1.0, but not yet recompiled the sdl2 egg with the new version. In such a case, compiled-version would return (2 0 3), and current-version would return (2 1 0). But, features from the new version would not be available until the user recompiles the sdl2 egg.

See SDL_VERSION and SDL_GetVersion.

[constant] (egg-version) → list of integers

Returns a list of three nonnegative integers, indicating the version number of the sdl2 egg itself, which is independent of the version number of SDL. For example, the list '(1 2 3) means sdl2 egg version 1.2.3.

NOTE: This procedure is available in sdl2 egg version 0.2.0 or higher. If you want to check the egg version, but users of your program might be using earlier than egg version 0.2.0, you can add the following code to your program. It will define the egg-version procedure only if using an earlier version of the sdl2 egg.

(use (prefix sdl2 sdl2:))

#+(not sdl2-0.2.0+)
(define (sdl2:egg-version) '(0 1 1))

;; Usage:
(printf "You are using sdl2 egg version ~S.~%" (sdl2:egg-version))

Window / Display Mode

Window / Display Mode Functions

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

[procedure] (destroy-window! window)

See SDL_DestroyWindow.

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

See SDL_GetWindowFromID.

NOTE: The returned window will be a new sdl2:window record pointing to the address of the existing window. It will be equal? to other sdl2:window records for the same window, but not eq?.

In sdl2 egg version 0.2.0 and higher, this procedure signals an exception of kind (exn sdl2) if there is no window with the given ID. In earlier egg versions, this procedure returned a null sdl2:window.

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

See SDL_UpdateWindowSurface.

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

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

See SDL_UpdateWindowSurfaceRects.

rects must be a list of sdl2:rects.

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

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

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.

[procedure] (window-bordered? window) → boolean
[setter] (set! (window-bordered? window) bordered)
[setter] (window-bordered-set! window bordered)

Get or set whether the window has a border (window decoration). #t means the window has a border, #f means the window is borderless.

Setting this to #f has essentially the same effect as passing the 'borderless flag to create-window! when creating the window.

See SDL_SetWindowBordered.

[procedure] (window-brightness window) → float
[setter] (set! (window-brightness window) brightness)
[setter] (window-brightness-set! window brightness)

See SDL_GetWindowBrightness and SDL_SetWindowBrightness.

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

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

See SDL_GetWindowDisplayIndex.

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

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

See SDL_GetWindowDisplayMode and SDL_SetWindowDisplayMode.

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

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

See SDL_GetWindowFlags.

[procedure] (window-fullscreen window) → symbol or #f
[setter] (set! (window-fullscreen window) mode)
[setter] (window-fullscreen-set! window mode)

Get or set the sdl2:window's fullscreen mode. See SDL_SetWindowFullscreen.

window-fullscreen returns one of the following values:

The setters accept any of the above values, or #t (which means the same as 'fullscreen), or an equivalent integer value.

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

[procedure] (window-grab? window) → boolean
[setter] (set! (window-grab? window) grab?)
[setter] (window-grab-set! window grab?)

See SDL_GetWindowGrab and SDL_SetWindowGrab.

[procedure] (grabbed-window) → sdl2:window or #f

Returns the sdl2:window that currently has input grab, or #f if no window has input grab. See SDL_GetGrabbedWindow.

NOTE: The returned window will be a new sdl2:window record pointing to the address of the existing window. It will be equal? to other sdl2:window records for the same window, but not eq?.

This procedure is available in sdl2 egg version 0.2.0 and higher. It requires SDL 2.0.4 or higher. It signals an error if the compiled version of SDL is not high enough. Use the libSDL-2.0.4+ feature identifier to check before calling this procedure.

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

See SDL_SetWindowIcon.

[procedure] (window-id window) → integer

See SDL_GetWindowID.

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

See SDL_GetWindowMaximumSize and SDL_SetWindowMaximumSize.

window-maximum-size returns multiple values.

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

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

See SDL_GetWindowMinimumSize and SDL_SetWindowMinimumSize.

window-minimum-size returns multiple values.

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

[procedure] (window-pixel-format window) → symbol
[procedure] (window-pixel-format-raw window) → integer

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

[procedure] (window-position window) → [x y]
[setter] (set! (window-position window) pos)
[setter] (window-position-set! window pos)

See SDL_GetWindowPosition and SDL_SetWindowPosition.

window-position returns multiple values.

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

[procedure] (window-size window) → [width height]
[setter] (set! (window-size window) size)
[setter] (window-size-set! window size)

See SDL_GetWindowSize and SDL_SetWindowSize.

window-size returns multiple values.

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

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

See SDL_GetWindowSurface.

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

[procedure] (window-title window) → string
[setter] (set! (window-title window) title)
[setter] (window-title-set! window title)

See SDL_GetWindowTitle and SDL_SetWindowTitle.

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] (make-display-mode #!optional format w h refresh-rate) → sdl2:display-mode
[procedure] (make-display-mode* #!optional format w h refresh-rate) → sdl2:display-mode

Allocate and initialize a new sdl2:display-mode.

format defaults to 'unknown. It must be a pixel format symbol or equivalent integer.

w, h, and refresh-rate default to 0. They must be integers.

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

Free the memory of the sdl2:display-mode's underlying struct. display-mode's pointer will be set to null (see struct-null?). It is safe to call this procedure with managed or unmanaged sdl2:display-modes. It is safe (but has no effect) to free a struct record multiple times.

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

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

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

Get or set the sdl2:display-mode's "w" field, as an integer.

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

Get or set the sdl2:display-mode's "h" field, as an integer.

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

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

Miscellaneous

[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] (screen-saver-enabled?) → boolean
[setter] (set! (screen-saver-enabled?) enabled?)
[setter] (screen-saver-enabled-set! enabled?)

See SDL_IsScreenSaverEnabled, SDL_EnableScreenSaver, and SDL_DisableScreenSaver.

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

See SDL_HasClipboardText.

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

See SDL_GetClipboardText.

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

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

See SDL_SetClipboardText.

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