chickadee » sdl-base

sdl-base

The sdl-base egg is a successor to the sdl egg (the latter is expected to become deprecated in the future).

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

Related to sdl-version

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

(make-sdl-version pointer) procedure

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.

(sdl-version-major sdl-version) procedure

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

(sdl-version-minor sdl-version) procedure

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

(sdl-version-patch sdl-version) procedure

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

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

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.

(sdl-compiled-version) procedure

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.

(sdl-linked-version) procedure

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.

Related to sdl-rect

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.

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

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

(sdl-rect-buffer sdl-rect) procedure

??? TODO

(sdl-rect? obj) procedure

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

(sdl-rect-x sdl-rect) procedure

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

(sdl-rect-y sdl-rect) procedure

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.

(sdl-rect-w sdl-rect) procedure

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

(sdl-rect-h sdl-rect) procedure

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

Related to sdl-pixel-format

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.

(make-sdl-pixel-format pointer) procedure

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

(sdl-pixel-format? obj) procedure

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

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

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

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

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.

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

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

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

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

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

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

Related to sdl-surface

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.

(make-sdl-surface pointer) procedure

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

(sdl-surface? obj) procedure

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

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

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

(sdl-surface-flags sdl-surface) procedure

Evaluates to flags describing the given surface.

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

Evaluates to pixel format describing the given surface.

(sdl-surface-width sdl-surface) procedure

Evaluates to the width of a given surface.

(sdl-surface-height sdl-surface) procedure

Evaluates to the height of a given surface.

(sdl-surface-pitch sdl-surface) procedure

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

(sdl-surface-pixels sdl-surface) procedure

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

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

Evaluates to the size of pixel data in bytes.

(sdl-free-surface sdl-surface) procedure

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.

Related to sdl-video-info

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.

(make-sdl-video-info pointer) procedure

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.

(sdl-video-info-pointer) procedure

???? TODO

(sdl-get-video-info) procedure

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

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

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

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

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

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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

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

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

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

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

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

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

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

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

Related to sdl-color

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.

(make-sdl-color r g b) procedure

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

(sdl-color-buffer sdl-color) procedure

??? TODO

(sdl-color? obj) procedure

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

(sdl-color-r sdl-color) procedure

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

(sdl-color-g sdl-color) procedure

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

(sdl-color-b sdl-color) procedure

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

Related to sdl-event (TODO)

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.

(make-sdl-event) procedure

Returns a new sdl-event structure.

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

TODO ????

(sdl-event-type sdl-event) procedure

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

  • SDL_ACTIVEEVENT (activation event; occurs when application has gained or recieved focus; gain and state fields are applicable),
  • SDL_KEYDOWN and SDL_KEYUP (keypress event; occurs when a key has been pressed or released; state, sym, mod, scancode and unicode fields are available),
  • SDL_MOUSEMOTION, SDL_MOUSEBUTTONDOWN and SDL_MOUSEBUTTONUP (occurs when mouse is moved or mouse button in clicked or released; state, x, y, xrel and yrel fields are available),
  • SDL_JOYAXISMOTION,
  • SDL_JOYBALLMOTION,
  • SDL_JOYHATMOTION,
  • SDL_JOYBUTTONDOWN and SDL_JOYBUTTONUP,
  • SDL_QUIT,
  • SDL_SYSWMEVENT,
  • SDL_VIDEORESIZE,
  • SDL_VIDEOEXPOSE,
  • SDL_USEREVENT or higher.
(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! ...) procedure

TODO: undocumented functions

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

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.

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

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.

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

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

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

TODO

(sdl-display-format sdl-surface) procedure

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.

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

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.

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

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

(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) procedure

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

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

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

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

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

(sdl-wm-get-caption) procedure

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

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

TODO

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

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.

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

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.

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

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.

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

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

(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) procedure

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.

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

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

(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? ...) procedure

Contents »