sdl-base

The sdl-base egg is a successor to the sdl egg (the latter is expected to become deprecated in the future). Note that bindings to sdl2 also exists.

  1. sdl-base
    1. Naming conventions
    2. Procedures
      1. Related to sdl-version
      2. Related to sdl-rect
      3. Related to sdl-pixel-format
      4. Related to sdl-surface
      5. Related to sdl-video-info
      6. Related to sdl-color
      7. Related to sdl-event (TODO)
      8. TODO: undocumented functions
    3. Links
    4. Repository

Unlike sdl, sdl-base has only the binding for the basic SDL library. This allows for a fine-grained control over what gets linked with your program. For bindings to the complementary libraries see their respective eggs: sdl-img for SDL_Image, sdl-mixer for SDL_Mixer and sdl-ttf for SDL_TTF.

Naming conventions

The sdl-base egg uses roughtly the same naming conventions as the sdl egg and as the guile-sdl: SDL_ prefix is replaced with sdl-, and hyphens are used to separate words instead of camel-case.

Procedures

sdl-version is a structure for holding the version of the SDL library. This is a wrapper for SDL_version structure in the C library. SDL_version consists of 3 fields: major version number, minor version number and patch number. You don’t usually need to create new instances of this structure: you obtain the version of SDL program was compiled with or linked with, and then get individual fields or check if the version is not too old with ``sdl-version-at-least``.

[procedure] (make-sdl-version pointer)

Creates a new wrapper over the C’s SDL_version structure. Usually you won’t need to use this function directly. Instead, use (sdl-compiled-version) and (sdl-linked-version) to obtain the version information.

[procedure] (sdl-version-major sdl-version)

Evaluates to the major version number for an SDL version in question.

[procedure] (sdl-version-minor sdl-version)

Evaluates to the minor version number for an SDL version in question.

[procedure] (sdl-version-patch sdl-version)

Evaluates to the patch number for an SDL version in question.

[procedure] (sdl-version-at-least sdl-version major minor patch)

Convenient function to check all the three components at once: evaluates to #t if the version is newer or equal to the version denoted by the major, minor and patch arguments, or to #f otherwise. This is analogous to the SDL_VERSION_ATLEAST in the C interface.

[procedure] (sdl-compiled-version)

Returns the sdl-version structure describing the SDL version number of the SDL library used during the compilation. This is analogous to the SDL_COMPILEDVERSION macro in the C interface.

[procedure] (sdl-linked-version)

Returns the sdl-version structure describing the SDL version number of the SDL library used the program is linked against. This is analogous to the SDL_VERSION macro in the C interface.

sdl-rect is a structure for describing a rectangle. It is widely used in the SDL library. It has two fields, x and y, denoting its position and two fields, w and h denoting width and height respectively. All the values are integers and measured in pixels.

[procedure] (make-sdl-rect x y w h)

Creates a new sdl-rect structure with the values given in the arguments.

[procedure] (sdl-rect-buffer sdl-rect)

??? TODO

[procedure] (sdl-rect? obj)

Evaluates to #t if obj is sdl-rect, or #f otherwise.

[procedure] (sdl-rect-x sdl-rect)

Evaluates to the horizontal position of the leftmost part of a given sdl-rect in pixels.

[procedure] (sdl-rect-y sdl-rect)

Evaluates to the vertical position of the topmost part a given sdl-rect in pixels. Like in many programming libraries, in SDL the y axis runs from top to bottom.

[procedure] (sdl-rect-w sdl-rect)

Evaluates to the width of a given sdl-rect in pixels.

[procedure] (sdl-rect-h sdl-rect)

Evaluates to the height of a given sdl-rect in pixels.

The sdl-pixel-format structure describes the way pixels are stored in the surface. It is a wrapper for the SDL_PixelFormat structure in SDL’s C interface.

Currently the sdl egg exposes no function to work with the SDL_Palette structure.

[procedure] (make-sdl-pixel-format pointer)

Creates a new wrapper over the C’s SDL_PixelFormat structure. Usually you won’t need to use this function directly.

[procedure] (sdl-pixel-format? obj)

Evaluates to #t if obj is sdl-pixel-format, or to #f otherwise.

[procedure] (sdl-pixel-format-bytes-per-pixel sdl-rect)

Evaluates to the number of bytes used to store one pixel in a given sdl-pixel-format. The result is always an integer value.

[procedure] (sdl-pixel-format-rmask sdl-rect)

Evaluates to the red mask, 32-bit integer number describing the way red-colour component is stored in a given sdl-pixel-format. The result is always an integer value. The red mask is an integer value in which the bits set to 1 represent bits used to store the red value. Red mask is not used for 8-bit (1-byte) pixel formats.

[procedure] (sdl-pixel-format-gmask sdl-rect)

Evaluates to the green mask, 32-bit integer value. Green mask is not used for 8-bit (1-byte) pixel formats.

[procedure] (sdl-pixel-format-bmask sdl-rect)

Evaluates to the blue mask, 32-bit integer value. Blue mask is not used for 8-bit (1-byte) pixel formats.

[procedure] (sdl-pixel-format-amask sdl-rect)

Evaluates to the alpha mask, 32-bit integer value. Alpha mask is not used for 8-bit (1-byte) pixel formats.

The sdl_surface structure represents the object used to store image data. It is characterised by width (w), height (h), pixel format (pixel-format), flags describing additional information, the actual pixel values (pixels) and some other information. It is a wrapper over SDL_Surface structure in SDL’s C interface.

Unlike most other objects, surfaces must be explicitly disposed of after using with the sdl-free-surface function.

[procedure] (make-sdl-surface pointer)

Creates a new wrapper over the C’s SDL_PixelFormat structure. Usually you won’t need to use this function directly, its main purpose is interoperability with foreign C code. To create new empty surfaces, use the sdl-create-rgb-surface function. To create surface from files, use

[procedure] (sdl-surface? obj)

Evaluates to #t if obj is sdl-surface, or to #f otherwise.

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

Creates a RGB(A) surface with the given height, width, rmask, gmask, bmask and amask. This is a wrapper for SDL_CreateRGBSurface function.

Flags can be: SDL_SWSURFACE (store surface in general-purpose memory) or SDL_HWSURFACE (store surface in video memory), SDL_SRCCOLORKEY (turn on colour-keying; use sdl-set-color-key! to change the value of this flag after surface creation), SDL_SRCALPHA (use alpha-channel for surface; this flag is automatically set if amask is non-zero; sdl-set-alpha! allows to change this flag later). Flags can be combined with +.

[procedure] (sdl-surface-flags sdl-surface)

Evaluates to flags describing the given surface.

[procedure] (sdl-surface-pixel-format sdl-surface)

Evaluates to pixel format describing the given surface.

[procedure] (sdl-surface-width sdl-surface)

Evaluates to the width of a given surface.

[procedure] (sdl-surface-height sdl-surface)

Evaluates to the height of a given surface.

[procedure] (sdl-surface-pitch sdl-surface)

Evaluates to the actual number of bytes describing each row of a given surface.

[procedure] (sdl-surface-pixels sdl-surface)

Evaluates to the pixel data (TODO: ??? how is it mapped to Scheme objects???) a given surface.

[procedure] (sdl-surface-pixels-length sdl-surface)

Evaluates to the size of pixel data in bytes.

[procedure] (sdl-free-surface sdl-surface)

Disposes of the unused surface. Surface should not be used after calling this function. Failing to call this function on used surfaces may result in memory leaks.

sdl-video-info is a read-only structure that contains information on the video mode. It is returned by sdl-get-video-info and cointains information either on the best available video mode (if called before sdl-set-video-mode) or on the current video mode.

[procedure] (make-sdl-video-info pointer)

Creates a new Scheme structure from the C’s structure. This function is usually not neccessary in Scheme programs: just use sdl-get-video-mode directly instead of calling it from C code.

[procedure] (sdl-video-info-pointer)

???? TODO

[procedure] (sdl-get-video-info)

Returns a sdl-video-info structure describing either the 'best' video mode (if called before sdl-set-video-mode) or the current video mode.

[procedure] (sdl-video-info-hw-available sdl-video-info)

Evaluates to 1 if it is possible to create hardware-accelerated surfaces according to the data in the sdl-video-info, to 0 otherwise.

[procedure] (sdl-video-info-wm-available sdl-video-info)

Evaluates to 1 if the window manager is available according to the data in the sdl-video-info, to 0 otherwise.

[procedure] (sdl-video-info-blit-hw sdl-video-info)

Evaluates to 1} if blits from hardware memory to hardware memory are hardware-accelerated, according to the data in the {{sdl-video-info, 0 otherwise.

[procedure] (sdl-video-info-blit-hw-cc sdl-video-info)

Evaluates to 1 its from hardware memory to hardware memory with colour key are hardware-accelerated, according to the data in the sdl-video-info, 0 otherwise.

[procedure] (sdl-video-info-blit-hw-a sdl-video-info)

Evaluates to 1 its from hardware memory to hardware memory with alpha channel are hardware-accelerated, according to the data in the sdl-video-info, to 0 otherwise.

[procedure] (sdl-video-info-blit-sw sdl-video-info)

Evaluates to 1 if blits from software memory to hardware memory are hardware-accelerated, according to the data in the sdl-video-info, 0 otherwise.

[procedure] (sdl-video-info-blit-sw-cc sdl-video-info)

Evaluates to 1 if blits from software memory to hardware memory with colour key are hardware-accelerated, according to the data in the sdl-video-info, 0 otherwise.

[procedure] (sdl-video-info-blit-sw-a sdl-video-info)

Evaluates to 1 if blits from software memory to hardware memory with alpha channel are hardware-accelerated, according to the data in the sdl-video-info, 0 otherwise.

[procedure] (sdl-video-info-blit-fill sdl-video-info)

Evaluates to 1 if colour fills are hardware-accelerated, according to the data in the sdl-video-info, or to 0 otherwise.

[procedure] (sdl-video-info-video-mem sdl-video-info)

Evaluates to an integer representing the total amount of video memory in kilobytes, according to sdl-video-info.

[procedure] (sdl-video-info-vfmt sdl-video-info)

Evaluates to sdl-pixel-format structure describing the pixel format of the video mode described by sdl-video-info.

[procedure] (sdl-video-info-current-w sdl-video-info)

Evaluates to the width, in pixels, of the video mode described by sdl-video-info.

[procedure] (sdl-video-info-current-h sdl-video-info)

Evaluates to the height, in pixels, of the video mode described by sdl-video-info.

sdl-color structure describes a colour in a format-independent way. It has 3 fields, r, g and b describing the red, green and blue components of colour according to the RGB model respectively. Corresponds to SDL_Color structure in C API.

[procedure] (make-sdl-color r g b)

Accepts the reg, green and blue components of colour respectively and return a new sdl-color value.

[procedure] (sdl-color-buffer sdl-color)

??? TODO

[procedure] (sdl-color? obj)

Evaluates to #t if obj is of type sdl-color, or to #f otherwise.

[procedure] (sdl-color-r sdl-color)

Returns the red component of the colour denoted by its argument.

[procedure] (sdl-color-g sdl-color)

Returns the green component of the colour denoted by its argument.

[procedure] (sdl-color-b sdl-color)

Returns the blue component of the colour denoted by its argument.

sdl-event is a structure describing the events that occur in an SDL program. These can be of different types, and different fields are applicable for different types. To get the type of event, use sdl-event-type procedure. This structure corresponds to SDL_Event in C API.

[procedure] (make-sdl-event)

Returns a new sdl-event structure.

[procedure] (sdl-event-buffer sdl-event-buffer-set! ...)

TODO ????

[procedure] (sdl-event-type sdl-event)

Returns an integer number denoting the type of event. This number will be equal to one of the following constants:

[procedure] (sdl-event? ...)
[procedure] (sdl-event-gain ...)
[procedure] (set-sdl-event-gain! ...)
[procedure] (sdl-event-which ...)
[procedure] (set-sdl-event-which! ...)
[procedure] (sdl-event-state ...)
[procedure] (set-sdl-event-state! ...)
[procedure] (sdl-event-scancode ...)
[procedure] (set-sdl-event-scancode! ...)
[procedure] (sdl-event-sym ...)
[procedure] (set-sdl-event-sym! ...)
[procedure] (sdl-event-mod ...)
[procedure] (set-sdl-event-mod! ...)
[procedure] (sdl-event-unicode ...)
[procedure] (set-sdl-event-unicode! ...)
[procedure] (sdl-event-x ...)
[procedure] (set-sdl-event-x! ...)
[procedure] (sdl-event-y ...)
[procedure] (set-sdl-event-y! ...)
[procedure] (sdl-event-xrel ...)
[procedure] (set-sdl-event-xrel! ...)
[procedure] (sdl-event-yrel ...)
[procedure] (set-sdl-event-yrel! ...)
[procedure] (sdl-event-axis ...)
[procedure] (set-sdl-event-axis! ...)
[procedure] (sdl-event-ball ...)
[procedure] (set-sdl-event-ball! ...)
[procedure] (sdl-event-hat ...)
[procedure] (set-sdl-event-hat! ...)
[procedure] (sdl-event-value ...)
[procedure] (set-sdl-event-value! ...)
[procedure] (sdl-event-button ...)
[procedure] (set-sdl-event-button! ...)
[procedure] (sdl-event-w ...)
[procedure] (set-sdl-event-w! ...)
[procedure] (sdl-event-h ...)
[procedure] (set-sdl-event-h! ...)

TODO: undocumented functions

[procedure] (sdl-get-clip-rect! sdl-surface sdl-rect)

Retrieves the clipping rectangle for the surface (sdl-surface) and saves it into the object sdl-rect. When something is blitted on the surface, the area outside the blitting rectangle is ignored.

[procedure] (sdl-set-clip-rect! sdl-surface sdl-rect)

Sets the clipping rectangle (sdl-rect) for the surface (sdl-surface). When something is blitted on the surface, the area outside the blitting rectangle is ignored. If the clipping rectangle is larger than surface, it is cropped to surface size. If area is NULL (TODO: how to pass null rect in Scheme?), the clipping rectangle is set to the surface size.

[procedure] (sdl-set-color-key! sdl-surface flags key)

Sets the colour key for the given sdl-surface) and/or turns its RLE acceleration settings on or off. {{flags is an integer that can be SDL_SRCCOLORKEY (if set, key is the new colour key), SDL_RLEACCEL (if set, surface will be stored with RLE acceleration), or a sum of both. key is an integer value representing the colour that will be considered transparent when drawing (you can obtain this value via sdl-map-rgb).

[procedure] (sdl-set-alpha! ...)

TODO

[procedure] (sdl-display-format sdl-surface)

Creates a new surface with the same format as the display format and width and height same as sdl-surface and copies sdl-surface's content into the new surface. If colour key or alpha value are needed, they should be set before calling this procedure. If alpha channel is needed, sdl-display-format-alpha should be used.

[procedure] (sdl-display-format-alpha sdl-display-format-alpha)

Creates a new surface with the same format as the display format, with alpha channel, and with width and height same as sdl-surface, and then copies sdl-surface's content into the new surface. If colour key or alpha value are needed, they should be set before calling this procedure. If colour key is set, it will be converted into alpha channel.

[procedure] (sdl-convert-surface sdl-surface pixel-format flags)

Creates a new the surface with the pixel format given (pixel-format) and copies contents of sdl-surface into it. Flags are the same as for the sdl-create-rgb-surface procedure: SDL_SWSURFACE, SDL_HWSURFACE (surface resides in software or hardware memory respectively), SDL_SRCCOLORKEY (surface has colour key), SDL_SRCALPHA (surface has alpha-channel transparency); flags can be combined with +.

[procedure] (sdl-init ...)
[procedure] (sdl-init-sub-system ...)
[procedure] (sdl-quit-sub-system ...)
[procedure] (sdl-quit ...)
[procedure] (sdl-was-init ...)
[procedure] (sdl-get-error ...)
[procedure] (sdl-clear-error! ...)
[procedure] (sdl-wm-set-caption title icon)

Sets the title and icon caption of the window to the strings passed as its arguments. (TODO: what exactly is icon caption???)

[procedure] (sdl-wm-get-caption-title)

Evaluates to the string representing the current title caption of a window.

[procedure] (sdl-wm-get-caption-icon)

Evaluates to the string representing the current icon caption of a window.

[procedure] (sdl-wm-get-caption)

Returns two string values: the current title and icon caption of a window.

[procedure] (sdl-wm-set-icon icon mask)

TODO

[procedure] (sdl-wm-iconify-window ...)
[procedure] (sdl-wm-toggle-full-screen ...)
[procedure] (sdl-wm-grab-input ...)
[procedure] (sdl-get-ticks ...)
[procedure] (sdl-delay ...)
[procedure] (timer? ...)

This is a type predicate for timers. Since there's no way ATM for you to get a reference to a timer, this will always return #f.

[procedure] (get-time-of-day ...)
[procedure] (get-time-of-day ...)
[procedure] (sdl-add-relative-timer! time callback)

Register callback to be called time seconds in the future. The callback will be called as a side effect of sdl-wait-event!*, so if you don't use sdl-wait-event!* or sdl-wait-event! (e.g. because you use sdl-poll-event! instead) your callbacks will never be invoked.

This doesn't use the SDL timer functionality, so the C SDL_*Timer documentation doesn't apply. In particular, you shouldn't worry about threading issues.

[procedure] (sdl-pump-events ...)
[procedure] (sdl-poll-event! ...)
[procedure] (sdl-wait-event!* delay-function [sdl-event])

Wait for a new SDL Event. delay-function is expected to take a single number and sleep that many milliseconds (call sdl-wait-event! instead if you're unsure what to use). If sdl-event is provided, it will be populated with the event data.

Note that sdl-event blocks other srfi-18 threads. You can use (lambda (ms) (thread-sleep! (/ ms 1000))) as the delay-function for sdl-event processing in a separate srfi-18 thread.

[procedure] (sdl-wait-event! [sdl-event])

Same as (sdl-wait-event!* sdl-delay [sdl-event]).

[procedure] (sdl-push-event ...)
[procedure] (sdl-event-state! ...)
[procedure] (sdl-get-mouse-state ...)
[procedure] (sdl-warp-mouse ...)
[procedure] (sdl-enable-unicode ...)
[procedure] (sdl-get-video-surface ...)
[procedure] (sdl-video-driver-name ...)
[procedure] (sdl-set-video-mode ...)
[procedure] (sdl-video-mode-ok ...)
[procedure] (sdl-show-cursor ...)
[procedure] (sdl-map-rgb sdl-pixel-format r g b)

Returns a 32-bit integer representing the colour with the corresponding values of red (r), green (g) and blue (b) components according to the given sdl-pixel-format. Arguments r, g and b must be integers from 0 to 255 (#xFF). If the colour cannot be represented, the closest match is returned. If the surface supports transparency, fully opaque colour is returned.

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

Returns a 32-bit integer representing the colour with the corresponding values of red (r), green (g), blue (b) and alpha (a) components according to the given sdl-pixel-format. Arguments r, g, b and a must be integers from 0 to 255 (#xFF). If the colour cannot be represented, the closest match is returned. If the surface doesn't support transparency, a is ignored (it's the same as #xFF).

[procedure] (sdl-fill-rect ...)
[procedure] (sdl-flip ...)
[procedure] (sdl-free-surface ...)
[procedure] (sdl-blit-surface ...)
[procedure] (sdl-with-clip-rect ...)
[procedure] (make-sdl-joystick ...)
[procedure] (sdl-joystick-pointer ...)
[procedure] (sdl-joystick? ...)
[procedure] (sdl-joystick-event-state ...)
[procedure] (sdl-joystick-update ...)
[procedure] (sdl-num-joysticks ...)
[procedure] (sdl-joystick-name ...)
[procedure] (sdl-joystick-open ...)
[procedure] (sdl-joystick-opened ...)
[procedure] (sdl-joystick-index ...)
[procedure] (sdl-joystick-num-axes ...)
[procedure] (sdl-joystick-num-balls ...)
[procedure] (sdl-joystick-num-hats ...)
[procedure] (sdl-joystick-num-buttons ...)
[procedure] (sdl-joystick-update ...)
[procedure] (sdl-joystick-get-axis ...)
[procedure] (sdl-joystick-get-hat ...)
[procedure] (sdl-joystick-get-button ...)
[procedure] (sdl-joystick-close ...)
[procedure] (sdl-gl-swap-buffers ...)
[procedure] (sdl-gl-set-attribute ...)
[procedure] (sdl-gl-get-attribute ...)
[procedure] (heap? ...)

Repository

This egg is hosted on the CHICKEN Subversion repository:

https://anonymous@code.call-cc.org/svn/chicken-eggs/release/5/sdl-base

If you want to check out the source code repository of this egg and you are not familiar with Subversion, see this page.