Next: Introduction, Up: (dir) [Contents][Index]
This manual documents Guile-SDL 0.6.1,
a package which provides the modules
(sdl sdl), (sdl gfx), (sdl ttf) and (sdl mixer)
for use in Guile Scheme programs. These modules wrap the Simple Direct Media
Layer1 libraries on
your system. Additionally, experimental abstractions and convenience
procedures are provided in the modules (sdl misc-utils) and
(sdl simple).
This manual is
Copyright © 2003–2015, 2022 Thien-Thi Nguyen
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the appendix entitled “GNU Free Documentation License”.
Next: General SDL, Previous: The (sdl *) Modules, Up: The (sdl *) Modules [Contents][Index]
The (sdl *) modules are an interface to the SDL (Simple Direct Media Layer) library. The goal is to provide both a clean and direct interface to the lowest level SDL, while extending with higher level concepts where useful, such as default arguments and functional-style application of graphics routines. Several SDL add-on libraries have been wrapped and included with Guile-SDL, including SDL_image (for loading multiple image formats), SDL_ttf (for rendering true type fonts), SDL_mixer (for playing/mixing different audio formats), and SDL_rotozoom (for rotating and scaling images). In addition, some low-level 2D graphics primitives have been provided.
Next: Naming Conventions, Up: Introduction [Contents][Index]
To whet your appetite, and hopefully get you excited about the ease and flexibility of programming with Guile-SDL, we begin with a simple example. The following program is a simple image browser. You can cycle through images by using space, n or right to go forward, backspace, p or left to go backwards, and escape or q to quit.
;; load the SDL module and some useful SRFIs
(use-modules ((sdl sdl) #:prefix SDL:)
(srfi srfi-1)
(srfi srfi-2))
;; initialize the video subsystem
(SDL:init 'video)
;; directory to search for images in
(define image-dir "/usr/share/pixmaps/")
;; utility to test if a path is a directory
(define (file? f)
(let* ((stats (stat f))
(type (stat:type stats)))
(eq? type 'regular)))
;; build a ring of image file names
(define image-ring
(let ((dir (opendir image-dir)))
(letrec ((D (lambda (ls)
(let ((file (readdir dir)))
(if (eof-object? file)
(begin (closedir dir) ls)
(D (cons (string-append image-dir file)
ls)))))))
(apply circular-list (reverse (filter file? (D '())))))))
;; functions to cycle through the ring
(define (next-image)
(let ((next (car image-ring)))
(set! image-ring (cdr image-ring))
next))
(define (prev-image)
(let ((orig image-ring))
(while (not (eq? (cddr image-ring) orig))
(set! image-ring (cdr image-ring)))
(let ((image (car image-ring)))
(set! image-ring (cdr image-ring))
image)))
;; display an image given a filename
(define (show file)
(and-let* ((image (SDL:load-image file)))
(SDL:set-video-mode (SDL:surface:w image) (SDL:surface:h image) 24)
(SDL:blit-surface image)
(SDL:flip)))
;; show the first image
(show (next-image))
;; event handler
(let handle ((e (SDL:make-event)))
(and (SDL:wait-event e)
(case (SDL:event:type e)
((key-down)
(case (SDL:event:key:keysym:sym e)
((left backspace)
(show (prev-image)))
((right space)
(show (next-image)))
((escape q)
(SDL:quit)
(quit))))))
(handle e))
Next: Uniform Vectors, Previous: Quick Start, Up: Introduction [Contents][Index]
The most important thing to learning a wrapped library for a programming language, assuming you know the language and the library, is to know the naming conventions. Then you can begin programming without having to look up the exact function reference (available in the rest of this document).
Next: Enums and Constants, Up: Naming Conventions [Contents][Index]
As with standard guile naming conventions, all names are converted to
lower-case, and underscores are replaced with hyphens. Functions that
modify one or more arguments have an exclamation point (!)
appended, and functions which ask a question and return a boolean
value have a question mark (?) appended.
Next: Create and Make, Previous: Renaming C Functions, Up: Naming Conventions [Contents][Index]
SDL enumerated types and constants are passed and returned as symbols,
thus enforcing their "constant" nature and for ease of use in
case statements. Flags, such as the SDL initialization flags
and video surface flags, are treated as lists of symbols, each
constant in the flag group that you would or together in C code
becoming a symbol in the list.
Some of these symbols retain their exact C names, while others are adapted to better fit Scheme (mostly by removing the ‘SDL_’ prefix, changing underscores to hyphens, downcasing, and inserting a hyphen between “words”).
A particular set of enums is called an enumstash. Likewise flagstash for flags.
You can use kotk to examine the enums and flags encapsulated by
these respectively typed objects.
You can
also use integers where enums/flags are expected, and can convert between the
symbol and numeric value with enum->number, number->enum,
flags->number and number->flags.
The conversion procs all take stash as the first argument, a symbol that identifies the particular set of enums/flags. For backward compatibility, stash may also be such an object, but this support will be removed after 2013-12-31, when those objects are to be fully internalized.
Return the contents of stash name (a symbol), as an alist with symbolic keys, integer values. If name is omitted, the keys are the names of the all the enum- and flagstashes, and the values have the form:
(N TYPE)
where n is the count of symbols in that stash,
and type is a symbol: enums or flags.
Return the number in stash associated with symbol.
Return the symbol associated with number, or #f
if it does not belong to stash.
Use stash to convert flags to a number.
flags is a list of symbols;
or #f, which is taken as the empty list;
or #t, which is taken as the list of all
possible symbols in stash.
Use stash to convert number to a list of symbols. If the flags in stash are not sufficient to decode number, the first element of the list is the numeric remainder.
Conversion from symbols to numbers (including enum->number and
flags->number) throws an error with key non-member-symbol
if the specified symbol is not a member of the respective enumstash or
flagstash.
Previous: Enums and Constants, Up: Naming Conventions [Contents][Index]
The standard SDL prefix for creating a new instance of a type is
create. The standard Guile prefix is make. Wherever an
SDL function uses the create prefix we will keep it. Object
creation functions unique to Guile, such as make-rect, will
use make as a prefix. In addition, we will sometimes introduce
higher-level creation functions, such as make-surface,
which is a wrapper to create-rgb-surface which provides
useful default values from the current screen information.
Next: Limitations, Previous: Naming Conventions, Up: Introduction [Contents][Index]
Some procedures take one or more uniform vector arguments,
as specified in SRFI 4 (see Video, see SDL_gfx by Andreas Schiffler).
The specific type of vector is one of u8, u16,
s16, where u or s stands for “unsigned” or
“signed”, respectively, and the rest the number of bits.
Previous: Uniform Vectors, Up: Introduction [Contents][Index]
There are some known problems with Guile-SDL modules. This section attempts to make them well-known, if not well-liked...
Since Guile-SDL is in alpha stage, its interfaces are not stable. Specifically, module names, the contents of modules, procedure names, procedure behavior: all these can change at any time up until the 1.0 release. C’est la vie.
How can any self-respecting package of bindings for libsdl not have a flashy, animated logo? Bonus points for suitable accompanying sound blurb.
Where do threads fit in if at all? Why doesn’t the Guile-SDL maintainer learn all about threads, fix guile-1.4.x to support that and then arrange for Guile-SDL to DTRT? Questions questions...
Next: Video, Previous: Introduction, Up: The (sdl *) Modules [Contents][Index]
The external representation of a Pixel Format object is:
#<SDL-Pixel-Format palette depth ck a chan>
where palette is the number of colors in the palette, or ‘-1’ if no palette is available; depth is the bits per pixel; ck is the hex value of the colorkey; a is the alpha value (0-255, inclusive); and chan is a concatenation of ‘R’ when there is a red mask, ‘G’ when there is a green mask, ‘B’ when there is a blue mask, and ‘A’ when there is an alpha mask.
Initialize SDL and the subsystems/configuration represented by sel (see init flags).
Initialize the SDL subsystems represented by sel.
sel is a list of flags (symbols)
from the same set useful for init.
Shut down all SDL subsystems.
Return #t.
Shut down the SDL subsystems represented by sel.
sel is a list of flags (symbols)
from the same set useful for init.
Return #t.
Check if the SDL subsystems represented by sel have
been initialized. sel is a list of flags (symbols)
from the same set useful for init. Return a list
likewise composed.
Return the number of milliseconds since the SDL library initialization.
Wait ms milliseconds.
Return the current SDL error string.
Next: Events, Previous: General SDL, Up: The (sdl *) Modules [Contents][Index]
Return a new cursor from data and mask (both u8 uniform vectors), sized w by h and with hot pixel located at x,y.
Create a new YUV overlay, sized width by height with overlay format (a symbol or an exact number). Optional arg display specifies a surface to use instead of creating a new one.
Return the current display surface.
Return information about the video hardware as three values:
capabilities (list of symbols), memory (integer),
and format (pixel format object). The capabilities are:
hw-available wm-available blit-hw blit-hw-CC blit-hw-A blit-sw blit-sw-CC blit-sw-A blit-fill
Return the name of the video driver.
Return a list of available screen dimensions for pixel
format and flags (see video flags).
Format defaults to that for
the current screen. Flags default to none.
Return #f if no modes are available, #t if all are available.
Check to see if a particular video mode is supported.
Args are width, height, bpp (numbers),
and flags (see video flags).
Return #f if the mode is not supported, or a number
indicating the bits-per-pixel of the closest available
mode supporting width and height.
Set the SDL video mode with width, height and bits-per-pixel bpp. Optional arg flags (see video flags) is supported. Return a new surface.
The external representation of a Rectangle object is:
#<SDL-Rect wxhsxsy>
where w and h are the width and height of the rectangle, and x and y are its horizontal and vertical coordinates. s may be ‘+’ or ‘-’.
Return #t iff obj is an SDL-rectangle object.
Return a rectangle object with location x,y and dimensions width by height.
Get x from rect.
Get y from rect.
Get w from rect.
Get h from rect.
Set x in rect
to value.
Set y in rect
to value.
Set w in rect
to value.
Set h in rect
to value.
Update surface within a specified rectangle. The second arg can either be an SDL-Rect object, or the second through fifth args are numbers specifying the x, y, width and height of a rectangular area.
On surface, update the rectangles in ls, a list of rectangles.
Swap double buffers of the default surface, or of surface if specified.
The external representation of a Color object is:
#<SDL-Color r g b>
where r is the decimal value of the color object’s red component, and g and b the likewise respective green and blue components.
Return #t iff obj is an SDL-Color object.
Return a color object with r, g, and b components.
Get r from color.
Get g from color.
Get b from color.
Set r in color
to value.
Set g in color
to value.
Set b in color
to value.
Set a portion of the colormap for the 8-bit surface using colors, a vector of SDL-Colors. Optional arg start (an integer in the range [0,255]) specifies the portion to be modified. It defaults to 0.
Set the palette of an 8-bit surface using flags (see palette flags) and colors, a vector of SDL-Colors. Optional arg start (an integer in the range [0,255]) specifies the portion to be modified. It defaults to 0.
Set the color gamma function for the display using real numbers redgamma, greengamma and bluegamma.
Return the gamma translation lookup tables currently used by
the display as a list of three tables, for red, green and blue.
Each table is a u16 uniform vector of length 256.
Return #f if unsuccessful.
Set the gamma translation lookup tables currently
used by the display to tables r, g and b,
each a u16 uniform vector of length 256, or #f,
in which case that particular component is unchanged.
Return #t if successful.
Map a RGB color value to the pixel format. The second arg can be an SDL-Color, otherwise the second through fourth args are red, green and blue values (numbers). Return the mapped components as an unsigned integer.
Map a RGB color value to the pixel format. If the second arg is an SDL-Color, the third is an alpha value (number). Otherwise, the second through fifth args are red, green, blue and alpha values (numbers). Return the mapped components as an unsigned integer.
Return RGB info from pixel in the specified pixel format
as three values: r, g and b (all integers).
Return RGBA info from pixel in the specified pixel format as
four values: r, g, b and a (all integers).
Fill surface rect with color (a number).
If rect is #f, fill the entire surface.
Return #t if successful.
Return a new surface made by converting surface
to the display format. Return #f if not successful.
Return a new surface made by converting surface
to the display format, with an alpha channel. Return #f
if not successful.
Set the position of the mouse cursor to x,y.
Set the current mouse cursor to cursor.
Get the current mouse cursor.
Return the current visibility of the pointer (aka “mouse cursor”) as a boolean. If arg setting (a boolean) is specified, set the visibility to setting (the returned visibility corresponds to that before the call, regardless).
Return the value of a special SDL/OpenGL attribute.
Set the special SDL/OpenGL attribute to value. Both args are numbers.
Swap OpenGL framebuffers/Update Display.
Lock the given YUV overlay.
Return #f if successful.
Unlock the previously locked YUV overlay.
Blit the YUV overlay to the display dstrect
over which it was created. Return #t if successful.
Return information on the window manager, as a list of the
form: (VERSION SUBSYSTEM DISPLAY WINDOW FSWINDOW WMWINDOW).
VERSION is a sub-list of form: (MAJOR MINOR PATCH), where
element is an integer. SUBSYSTEM is either the symbol
x11, or #f. DISPLAY is a pointer (machine address)
of the X11 Display structure, converted to an integer.
WINDOW, FSWINDOW and WMWINDOW are Window identifiers (also
integers).
Set the title-bar and icon name of the display window to title and icon (both strings), respectively. If icon is not specified, use title by default.
Return display-window caption as two values: title
and icon (both strings, or #f if not set).
Set icon for the display window.
Iconify/Minimize the window.
Return #t if successful.
Toggle the default video surface between windowed
and fullscreen mode, if supported. Optional arg
surface specifies another surface to toggle.
Return #t if successful.
Grab mouse and keyboard input. Return new grab state.
Optional arg mode (a symbol) specifies the kind
of grab, one of query (the default),
off or on.
Return the current state of the application, a list of symbols. The list may include: ‘mousefocus’, ‘inputfocus’, ‘active’.
The external representation of a Surface object is:
;; normally: #<SDL-Surface wxh depth bpp lock> ;; when the object is not associated with a SDL_Surface: #<SDL-Surface NULL>
where w and h are the width and height of the surface, and depth is its bit-depth (e.g., ‘32’ for an RGBA surface). If the surface is locked, lock displays as ‘L’, otherwise nothing.
Return a new surface of dimensions width by height. Optional third arg flags (see video flags) further specifies the surface. Color depth and masks are those for the current video surface.
Return an empty surface. The eight arguments, directly analagous to those for SDL_CreateRGBSurface, are: flags (list of symbols, see video flags), width, height, depth, rmask, gmask, bmask, amask (all numbers).
Get w from surface.
Get h from surface.
Get format->BitsPerPixel from surface.
Return flags from surface as a (possibly empty) list of symbols.
Return a new pixel format, the same used by surface.
Return true iff obj is a surface.
Lock surface for direct access.
Return #t if successful.
Unlock previously locked surface.
Load bitmap data from filename.
Return a new surface if successful, otherwise #f.
Load image data from filename.
Return a new surface if successful, otherwise #f.
Save surface to filename in Windows BMP format.
Return #t if successful.
Set the color key for surface to pixel.
If pixel is #f, clear the current color key.
Otherwise, it should be an integer of the appropriate depth
for surface (e.g., in the range [0,65535] for 16 bpp).
If color key processing is enabled, optional arg rle is a
boolean that enables (true) or disables (false, the default)
RLE acceleration.
Return #t if successful.
Set alpha blending for the entire surface to alpha.
If alpha is #f, disable alpha blending.
Otherwise it should be an integer in the range [0,255]
or one of the symbols transparent or opaque.
If alpha blending is enabled, optional arg rle is a
boolean that enables (true) or disables (false, the default)
RLE acceleration.
Return #t if successful.
Set surface clipping rectangle to the whole surface.
Optional arg rect, if non-#f, specifies a particular
rectangle instead of using the whole surface.
Return the clipping rectangle for surface.
Convert surface to the same format as another surface. Optional third arg flags is a list of flags (see video flags).
Perform a fast blit from the src surface srcrect to the dst surface dstrect. srcrect defaults to x=0, y=0, src surface dimensions. If unspecified dst is taken as the default video surface. dstrect likewise defaults to x=0, y=0, dst surface dimensions.
Return a new surface created by flipping surface vertically.
Return a new surface created by flipping surface horizontally.
Return a new surface created by flipping surface both vertically and horizontally.
Return pixel data of surface as a new uniform vector.
The uvec has type u8, u16 or u32, corresponding
to the surface depth, with height x width elements.
A 24bpp surface — depth-in-bytes of 3 — is expanded (per pixel)
to u32, leaving the high byte clear.
Optional arg squash non-#f means to
return a u8vector regardless of surface depth,
with height x width x depth-in-bytes elements.
Return #t if surface needs to be locked before access.
Failure to do so may result in a segfault.
Next: Joystick, Previous: Video, Up: The (sdl *) Modules [Contents][Index]
Return a new SDL event.
Optional arg type is a symbol (see event-type enums).
If omitted, the default is SDL_NOEVENT.
Return the symbolic type from event.
Set type in event to value, a symbol or integer.
The value for event:active:gain and event:active:set-gain!
is a symbol, one of: gained or lost.
The value for event:active:state and event:active:set-state!
is a (possibly empty) list of symbols from the same set used by
get-app-state.
Return the symbolic active.gain from event.
Return active.state from event as a (possibly empty) list of symbols.
Set active.gain in event to value, a symbol or integer.
Set active.state in event to value, a (possibly empty) list of symbols.
The value for event:key:state and event:key:set-state!
is a symbol, one of: released or pressed.
Return the symbolic key.keysym.sym from event.
Set key.keysym.sym in event to value, a symbol or integer.
Return key.keysym.mod from event as a (possibly empty) list of symbols.
Set key.keysym.mod in event to value, a (possibly empty) list of symbols.
Return the symbolic key.state from event.
Get key.keysym.scancode from event.
Get key.keysym.unicode from event.
Set key.state in event to value, a symbol or integer.
Set key.keysym.scancode in event
to value.
Set key.keysym.unicode in event
to value.
Return motion.state from event as a (possibly empty) list of symbols.
Get motion.x from event.
Get motion.y from event.
Get motion.xrel from event.
Get motion.yrel from event.
Set motion.state in event to value, a (possibly empty) list of symbols.
Set motion.x in event
to value.
Set motion.y in event
to value.
Set motion.xrel in event
to value.
Set motion.yrel in event
to value.
The value for event:button:button and event:button:set-button!
is a (possibly empty) list of symbols from the set:
left middle right wheel-up wheel-down x1 x2
The value for event:button:state and event:button:set-state!
is a symbol, one of: released or pressed.
Return the symbolic button.button from event.
Return the symbolic button.state from event.
Get button.x from event.
Get button.y from event.
Set button.button in event to value, a symbol or integer.
Set button.state in event to value, a symbol or integer.
Set button.x in event
to value.
Set button.y in event
to value.
The value for event:jbutton:state and event:jbutton:set-state!
is a symbol, one of: released or pressed.
The value for event:jhat:value and event:jhat:set-value!
is a list of or more symbols from the set:
centered up down left right
Specifying the empty list for event:jhat:set-value! is
effectively the same as specifying centered.
Get jaxis.which from event.
Get jaxis.axis from event.
Get jaxis.value from event.
Set jaxis.which in event
to value.
Set jaxis.axis in event
to value.
Set jaxis.value in event
to value.
Get jbutton.which from event.
Get jbutton.button from event.
Return the symbolic jbutton.state from event.
Set jbutton.which in event
to value.
Set jbutton.button in event
to value.
Set jbutton.state in event to value, a symbol or integer.
Get jball.which from event.
Get jball.ball from event.
Get jball.xrel from event.
Get jball.yrel from event.
Set jball.which in event
to value.
Set jball.ball in event
to value.
Set jball.xrel in event
to value.
Set jball.yrel in event
to value.
Get jhat.which from event.
Get jhat.hat from event.
Return jhat.value from event as a (possibly empty) list of symbols.
Set jhat.which in event
to value.
Set jhat.hat in event
to value.
Set jhat.value in event to value, a (possibly empty) list of symbols.
Get resize.w from event.
Get resize.h from event.
Set resize.w in event
to value.
Set resize.h in event
to value.
Gather events from input devices and update the event queue.
Add events to the back of the event queue.
Return the count of succesfully added events.
Return a count (less than or equal to n) of events at
the front of the event queue that match mask,
without changing the queue. Optional arg accumulate if
non-#f means to return the list of matched events, instead.
If there are errors, return #f.
See event-mask flags.
Return a list (of length at most n) of
events at the front of the event queue that match
mask, removing them from the queue.
If there are errors, return #f.
See event-mask flags.
Poll for events and return #t if there are any pending.
Optional arg event specifies an event object (from
make-event) to be filled in with the next event from
the queue (if available).
Wait indefinitely for and return #f only if there were errors.
Optional arg event specifies an event object (from
make-event) to be filled in with the next event from
the queue.
Push event onto the queue.
Return #t on success.
Set the event filter to filter, or clear it if filter
is #f. This is a procedure called with one arg, and whose
return value, if non-#f, means to keep the event, otherwise
discard it. If full? is #f, the arg the event type (a
symbol), otherwise it is an event object.
Return information on the current event filter, or #f
if none is set. If there is a filter, the value is a pair
with car the filter proc, and cdr #f if the proc takes
an event type, or #t if the proc takes an event object.
Return #t if event type (see event-type enums)
is recognized and queued, or #f if it is ignored.
If setting is specified, set the handling of
type to the truth value of setting first.
Return #t iff UNICODE keyboard translation is enabled.
Optional arg enable? if non-#f, enables UNICODE
keyboard translation, or disables it if #f.
Enable or disable keyboard repeat.
delay is the initial delay in ms between the time
when a key is pressed, and keyboard repeat begins.
interval is the time in ms between keyboard repeat
events. If delay is 0, keyboard repeat is disabled.
Return #t on success.
Return a list of pressed keys (see keysym enums).
Return the current key modifier state as a list of symbols.
Set the current key modifier state to modstate, a list of symbols. This does not change the keyboard state, only the key modifier flags.
Return #t if buttons specified in mask are pressed,
otherwise #f.
mask is a symbol or a list of symbols from the set returned
by get-mouse-state.
For backward compatibility, mask can also be the (integer) logior of the buttons, using mapping:
1 left 2 middle 4 right 8 wheel-up 16 wheel-down 32 x1 64 x2
For example, a value of 5 specifies both left and right buttons,
equivalent to (left right).
Return three values: a (possibly empty) list of symbols
representing pressed mouse buttons (like event:button:button),
and two integer coordinates x and y.
Optional arg relative non-#f means the
coordinates are relative to the last time the underlying
SDL_GetRelativeMouseState was called.
Next: CDROM, Previous: Events, Up: The (sdl *) Modules [Contents][Index]
The external representation of a Joystick object is:
#<SDL-Joystick index>
where index is a decimal number of the joystick, or ‘-1’ if the object is not associated with a joystick.
Return the number of joysticks.
Return #t iff obj is a joystick object.
Return the (string) name of the default joystick, or #f.
Optional arg n specifies which joystick to check.
Return a handle to the default joystick opened for use. Optional arg n specifies which joystick to open.
Return #t iff the default joystick is opened.
Optional arg n specifies which joystick to check.
Return the index of joystick.
Return the number of axes for joystick.
Return the number trackballs for joystick.
Return the number of hats for joystick.
Return number of buttons for joystick.
Update the state of all Joysticks.
Return #t if joystick events are polled and queued (such
that it is unnecessary to “manually” call joystick-update),
otherwise #f.
If setting is specified, set joystick events polling
to the truth value of setting first.
For joystick, return state of axis.
Return relative motion of joystick trackball n
as two values: dx and dy (both integers).
For joystick, return state of hat n.
For joystick, return state of button n,
a symbol, one of: released or pressed.
Close a previously opened joystick.
Next: OpenGL, Previous: Joystick, Up: The (sdl *) Modules [Contents][Index]
The external representation of a CDROM Drive object is:
#<SDL-CD [status]>
where status is one of ‘TRAY EMPTY’, ‘STOPPED’, ‘PLAYING’, ‘PAUSED’, ‘DRIVE ERROR’, or ‘???’. (Normally, the last one should never appear.)
Return #t iff obj is a CDROM drive object.
Return the number of CDROM drives.
Return a human-readable, system-dependent
identifier (a string) for the CDROM, or #f.
Optional arg drive is a number specifying which drive.
Open the CDROM drive for access and return its handle.
If the drive is unavailable, return #f.
Optional arg drive is a number specifying which drive.
Return the current status of the drive cdrom as a symbol (see cdrom-state enums).
Return #t iff there is a CD in drive cdrom.
Return the number of tracks on the CD in drive cdrom.
Return the current track on the CD in drive cdrom.
Return the current frame of the CD in drive cdrom.
For CD in drive cdrom, return four values describing track
n (zero if unspecified): id, type, length
and offset, all integers except for type, which is
a symbol, either audio or data.
Play the given CD tracks in drive cdrom.
Play the CD starting at start-track and
start-frame for ntracks tracks and nframes
frames. If both ntrack and nframe are 0, play
until the end of the CD. This procedure will skip data
tracks, and should only be called after calling
cd-status to get track information about the CD.
Return #t if successful.
Play CD in drive cdrom from start frame for
length frames. Return #t if successful.
Pause the CD in drive cdrom. Return #t if successful.
Resume (unpause) the CD in drive cdrom.
Return #t if successful.
Stop the CD in drive cdrom. Return #t if successful.
Eject the CD from drive cdrom. Return #t if successful.
Close the drive cdrom.
Return frames (an integer) computed fr m, second s and frame f. s and f are optional.
Break down frames (an integer) and return three values:
minute, second and frames (all integers).
Next: Audio, Previous: OpenGL, Up: The (sdl *) Modules [Contents][Index]
Initialize the SDL_ttf subsystem.
Load a font from file with point size ptsize. Return a handle.
Return the style of font (see font-style flags). This font style is implemented by modifying the font glyphs, and doesn’t reflect any inherent properties of the truetype font file.
Set font style to style (see font-style flags). This font style is implemented by modifying the font glyphs, and doesn’t reflect any inherent properties of the truetype font file.
Return the total height of font, usually equal to point size.
Return the offset from the baseline to the top of font. This is a positive number.
Return the offset from the baseline to the bottom of font. This is a negative number.
Return the recommended spacing between lines of text for font.
Return the metrics (dimensions) of a glyph as five values.
The glyph is a font-specific rendering of char ch.
Values are: minx, maxx, miny,
maxy and advance (all integers).
Return two values: width and height (both integers)
representing the dimensions of the font-specific rendering
of the string text.
Return two values: width and height (both integers)
representing the dimensions of the font-specific rendering
of the UTF-8 string text.
Return a new surface containing the font-specific
rendering of the text string.
Third argument is the foreground color;
optional fourth argument is the background color,
or #t if the text is to be blended.
Return a new surface containing a font-specific
rendering of the utf8 string text.
Third argument is the foreground color;
optional fourth argument is the background color,
or #t if the text is to be blended.
Return a new surface containing a font-specific
rendering of the character ch.
Third argument is the foreground color;
optional fourth argument is the background color,
or #t if the text is to be blended.
Quit the SDL_ttf subsystem.
Next: SDL_gfx by Andreas Schiffler, Previous: TrueType, Up: The (sdl *) Modules [Contents][Index]
Open the mixer with a certain audio format.
Optional args freq (number), format (number),
stereo (boolean) and chunksize (number) specify
those aspects of the device. Return #t if successful.
Dynamically change the number of channels managed by the mixer to numchans. If decreasing the number of channels, the upper channels are stopped. Return the new number of allocated channels.
Return audio device parameters as three values: frequency (Hz),
format (number of bits) and channels (number of
allocated channels).
Load music data (.mod .s3m .it .xm) from filename.
Return a new music object if successful, otherwise #f.
Load wave data from filename.
Return a new audio object if succesful, otherwise #f.
Reserve the first num channels (0 through num-1) for the application. In other words don’t allocate them dynamically to the next sample if requested with a -1 value below. Return the number of reserved channels.
Attach to channel a tag.
A tag can be assigned to several mixer channels, to
form groups of channels. If tag is not specified, or
is -1, the tag is removed (actually -1 is the tag used
to represent the group of all the channels). Return
#t if successful.
Assign channels in the range from through to
to the default group. Optional arg tag specifies
the group to use. Return #t if successful.
Return the first available channel in the default group of channels. Optional arg tag specifies the group to check.
Return the number of channels in the default group. Optional arg tag specifies the group to check.
Return the "oldest" sample playing in the default group of channels. Optional arg tag specifies the group to check.
Return the "most recent" (i.e. last) sample playing in the default group of channels. Optional arg tag specifies the group to check.
Play an audio chunk on a specific channel. If the channel is unspecified or is -1, play on the first free channel. If loops is specified and greater than zero, loop the sound that many times. If loops is -1, loop infinitely (~65000 times). If ticks is specified, stop after that number of ticks. If fade is specified, fade in over that number of milliseconds. Return which channel was used to play the sound.
Play a music track.
Optional args loops and fade
are as in play-channel.
Return the current volume on the default channel.
Optional arg volume (a number in the range 0-128) means
set the volume to volume and return the original volume.
Optional second arg which specifies a chunk or
channel to check (or modify) instead of the default.
If volume is non-#f and which is #f, modify all
channels.
[Here is the original (perhaps clearer) docstring. —ttn]
Set the volume in the range of 0-128 of a specific channel or chunk. If the channel is unspecified or is -1, set volume for all channels. Return the original volume. If the volume is unspecified or is -1, just return the current volume.
Return the current volume. Optional arg volume (a number in the range 0-128) means set the volume to volume.
Halt playing of the default channel. Optional arg channel specifies a channel to halt.
Halt playing of the default group. Optional arg tag specifies the group to halt.
Halt playing of the music.
Turn off expiration for the default channel. Optional arg channel specifies a channel to change. Optional arg ticks (a number) means set the expiration delay to that many milliseconds, rather than turning it off.
Halt a channel, fading it out progressively until silent. Optional arg which specifies a channel to halt. Second optional arg ms specifies the number of milliseconds the fading will take (default 0).
Halt a group, fading it out progressively until silent. Optional arg tag specifies a group to halt. Second optional arg ms specifies the number of milliseconds the fading will take (default 0).
Halt the music, fading it out progressively until silent. Optional arg ms specifies the number of milliseconds the fading will take (default 0).
Return the fading status of the music, one of the symbols:
no, out, in.
Return the fading status (a symbol, see fading-music)
of the default channel.
Optional arg which selects which channel to check.
Pause the default channel. Optional arg channel selects which channel to pause.
Resume (unpause) the default channel. Optional arg channel selects which channel to resume.
Return #t if the default channel is paused.
Optional arg channel selects a which channel to check.
Pause the music.
Resume (unpause) the music.
Rewind the music.
Return #t if the music is currently paused.
Return #t iff the default channel is playing.
Optional arg channel selects which channel to check.
Return #t iff the music is currently playing.
Stop music and set external music playback command
to command, a string. As a special case, if command
is #f, arrange to use internal playback, instead.
FWIW, the C header file for the following panning, distance and position procs says:
Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and the panning will be done to the final mixed stream before passing it on to the audio device.
Set panning for (stereo) channel with l and r. Both l and r are integers 0–255, inclusive, where 0 is quietest and 255 is loudest.
To get “true” panning, use (set-panning CH N (- 255 N)).
Set the “distance” of channel to distance (integer, 0–255). This controls the location of the sound with respect to the listener.
Distance 0 is overlapping the listener, and 255 is as far away as possible.
A distance of 255 does not guarantee silence; in such a case, you might
want to try changing the chunk’s volume, or just cull the sample from the
mixing process with halt-channel.
For efficiency, the precision of this effect may be limited (distances 1 through 7 might all produce the same effect, 8 through 15 are equal, etc).
Setting (distance) to 0 unregisters this effect, since the data would be unchanged.
Set the “position” of channel to angle, distance.
In this polar coordinate, angle is in degrees (integer modulo 360),
and distance is an integer 0–255 (and is treated as in proc
set-distance – see notes there).
Angle 0 is due north, and rotates clockwise as the value increases. For efficiency, the precision of this effect may be limited (angles 1 through 7 might all produce the same effect, 8 through 15 are equal, etc).
Setting angle and distance to 0 unregisters this effect, since the data would be unchanged.
Additionally, the C header says:
If the audio device is configured for mono output, then you won’t get any effectiveness from the angle; however, distance attenuation on the channel will still occur. While this effect will function with stereo voices, it makes more sense to use voices with only one channel of sound, so when they are mixed through this effect, the positioning will sound correct. You can convert them to mono through SDL before giving them to the mixer in the first place if you like.
Close the mixer, halting all playing audio.
Next: Miscellaneous Utilities, Previous: Audio, Up: The (sdl *) Modules [Contents][Index]
On surface, draw a point at location x,y with color color.
On surface, draw a horizontal line segment from x1,y to x2,y, with color color.
On surface, draw a vertical line segment from x,y1 to x,y2, with color color.
On surface, draw a rectangle with opposite points x1,y1 and x2,y2, with color color. Optional arg fill means to fill the rectangle as well.
On surface, draw a rectangle with opposite points x1,y1 and x2,y2, with rounded corners radius rad in color color. Optional arg fill means to fill the rectangle as well.
On surface, draw a line segment from x1,y1 to x2,y2, with color color.
On surface, draw an anti-aliased line segment from x1,y1 to x2,y2, with color color.
On surface, draw a line segment from x1,y1 to x2,y2, with thickness width in color color.
On surface, draw arc with center x,y and radius r, going from start to end (degrees), with color color.
If start is greater than end, the effective range of the arc is taken to be end to start (that is, these arguments are internally reversed).
On surface, draw a circle with center x,y and radius r, with color color. Optional arg fill means to fill the circle as well.
On surface, draw an anti-aliased circle with center x,y and radius r, with color color.
On surface, draw an ellipse with center x,y x-radius rx, y-radius ry, with color color. Optional arg fill means to fill the ellipse as well.
On surface, draw an anti-aliased ellipse with center x,y, x-radius rx, y-radius ry, with color color.
On surface, draw a pie slice with center x,y and radius rad, going from start to end (degrees), with color color. Optional arg fill means to fill the slice as well.
On surface, draw a triangle with vertices at x1,y1, x2,y2 and x3,y3, with color color. Optional arg fill means to fill the triangle as well.
On surface, draw an anti-aliased triangle with vertices at x1,y1, x2,y2 and x3,y3, with color color.
On surface, draw a polygon whose points are specified by corresponding pairs from the s16 uniform vectors vx and vy, in color color. Optional arg fill means to fill the polygon as well.
On surface, draw an anti-aliased polygon whose points are specified by corresponding pairs from the s16 uniform vectors vx and vy, in color color.
On surface, draw a polygon whose points are specified by corresponding pairs from the s16 uniform vectors vx and vy, filling from texture (a surface) with offset tdx, tdy.
On surface, draw a bezier curve whose points are specified by corresponding pairs from the s16 uniform vectors vx and vy, with s steps in color color.
On surface at position x,y, draw char c with color (a number).
On surface at position x,y, draw string text with color (a number).
Set the rotation for glyphs drawn by draw-character and
draw-string to rotation (an integer or symbol), one of:
0 none 1 clockwise 2 upside-down 3 counter-clockwise
For roto-zoom-surface and roto-zoom-surface-xy,
a positive angle means counter-clockwise rotation.
Return a new surface made from rotating surface by angle degrees. Optional third arg zoom (default value 1.0) changes the size as well. Optional fourth arg smooth turns on anti-aliasing.
Return a new surface made from rotating surface by angle degrees. Optional third and fourth args zoomx and zoomy (default value 1.0 for both) changes the size as well. Optional fifth arg smooth turns on anti-aliasing.
Return a new scaled copy of surface. zoomx and zoomy specify the scaling factor. If omitted, zoomy defaults to zoomx. Optional fourth arg smooth turns on anti-aliasing.
Return a new shrunken copy of surface. factorx and factory are positive integers specifying the inverse scaling factor. For example, 2 means half size, 3 means one-third size, etc.
The returned surface is antialiased by “averaging the source box RGBA or Y information” and is in 32-bit RGBA format.
The external representation of an FPS Manager object is:
#<FPS-manager rHz>
where r is the decimal framerate that the object manages.
Return a FPS manager object to be passed as the first
arg to fps-manager-set!, fps-manager-get and
fps-manager-delay!.
Optional arg n specifies the value in Hz to
initialize the object (default 30 if not specified).
Arrange for FPS manager mgr to try to maintain a
frame rate of n Hz. Return #f if not successful.
Return the frame rate of FPS manager mgr in Hz,
or #f if unsuccessful.
Return the frame count of FPS manager mgr,
or #f if unsuccessful.
A frame is counted each time fps-manager-delay! is called.
Request an appropriate delay from FPS manager mgr. For some versions of SDL_gfx (not the embedded one, currently), return the number of milliseconds elapsed since the last call. This value may be 0 (zero).
If surface is 32-bit, set each pixel’s alpha value to
alpha, an integer 0-255, inclusive, and return #t.
Otherwise, do nothing and return #f.
Multiply the alpha channel of 32-bit surface by factor,
an integer 0-255, inclusive. The result is scaled back; the effective
factor is factor/256. Return #t if alpha was changed.
Blit from 32-bit surface src rectangle srect
to 32-bit surface dst rectangle drect.
Return #f if there were problems (use get-error
for more info); 1 if a blit was performed; 0 otherwise.
Both srect and drect may be #f to
indicate the entire surface as source or destination.
The image filtering procedures take one or more surfaces — the
“source(s)”, identified by s, s1, s2 — and
perform an operation on them, writing the result to the
“destination” (d) surface.
The sources and destination must all have the same
width, height and pixel format.
(This pixel format requirement may be relaxed in the future.)
The procedures return #t on success, else #f.
With the exception of four procedures: imfi-add-c,
imfi-sub-c, imfi-lshr, and imfi-lshl,
all bytes in a pixel are subject to the same operation.
For imfi-add-c and imfi-sub-c,
if the c (constant) argument value is
more than 255 (does not fit in 8 bits), the constant is interpreted as
a field of four channels and the operation occurs on a per-channel
basis; otherwise (constant fits in 8 bits), a byte-wise operation is
performed as usual.
For imfi-lshr, and imfi-lshl, the operation is done
pixel-wise (on a logical pixel, assumed bit-depth 32). This is
indicated by the ‘(uint)’ cast in their descriptions.
If setting is #t, enable MMX instructions
for the image filter procs (if possible); if #f, disable;
otherwise do nothing. Return the (boolean) value of the setting
afterwards.
D = saturation255 (S1 + S2).
D = S1/2 + S2/2.
D = saturation0 (S1 - S2).
D = | S1 - S2 |.
D = saturation (S1 * S2).
D = S1 * S2 (non-MMX).
D = saturation255 (S1/2 * S2).
D = saturation255 (S1/2 * S2/2).
D = S1 & S2.
D = S1 | S2.
D = S1 / S2 (non-MMX).
D = !S.
D = saturation255 (S + C).
D = saturation255 (S/2 + C).
D = saturation0 (S - C).
D = saturation0 (S >> N).
D = saturation0 ((uint) S >> N).
D = saturation255 (S * C).
D = saturation255 ((S >> N) * C).
D = (S << N).
D = ((uint) S << N).
D = saturation255 (S << N).
D = (S < T ? 0 : 255).
D = (Tmin <= S <= Tmax) ? 255 : 0.
D = saturation255 ((Nmax - Nmin) / (Cmax - Cmin) * (S - Cmin) + Nmin).
Next: Simple Closures, Previous: SDL_gfx by Andreas Schiffler, Up: The (sdl *) Modules [Contents][Index]
These are available in module (sdl misc-utils).
Return the exact truncation (rounding to zero) of number.
This is “safer” than simply inexact->exact
for some Guile versions.
(define scale 0.180281690140845) (inexact->exact scale) ⇒ 3247666210160131/18014398509481984 ; Guile 1.8.7 ⇒ 0 ; Guile 1.4.x (exact-truncate scale) ⇒ 0
Return the exact floor (rounding to negative infinity) of number.
Set default clip rect to rect, call thunk, and restore it. thunk is a procedure that takes no arguments.
Return a new 32bpp RGBA surface with dimensions w by h pixels.
The surface has flag src-alpha set.
The masks are as follows:
red #x000000FF green #x0000FF00 blue #x00FF0000 alpha #xFF000000
Return a new 32bpp RGBA square surface with edge-len sides. (Both width and height are edge-len, an integer.)
Return a new surface made by rotating square by angle degrees.
The square retains its original size.
If the new surface has flag src-alpha set, use
(sdl gfx) blit-rgba, otherwise (sdl sdl) blit-surface,
for the resizing blit.
Optional arg mksquare is a procedure of one arg that creates a
square surface. If unspecified, use create-rgba-square.
See roto-zoom-surface for interpretation of angle.
Return a closure that manages a single rectangle object.
Calling the closure with no args returns the rectangle object.
Otherwise, the messages #:w, #:h, #:x
and #:y return the rectangle’s width, height, horizontal
offset and vertical offset, respectively;
and the messages #:w!, #:h!, #:x!
and #:y!, followed by an integer, update the rectangle’s
width, height, horizontal offset and vertical offset, respectively.
Optional arg rect specifies a rectangle object to manage instead of allocating a new one.
Return a rectangle made from parsing the geometry string spec,
which typically has the form WxH+X+Y, where +X+Y is optional
(defaults to “+0+0”), and W, H, X and Y are
integers. Actually, the + can also be a -. If spec
cannot be parsed, return #f. Examples:
(rectangle<-geometry-string "42x43+44+45") ⇒ #<SDL-Rect 42x43+44+45> (rectangle<-geometry-string "42x43-10-20") ⇒ #<SDL-Rect 42x43+-10+-20> (rectangle<-geometry-string "42x43") ⇒ #<SDL-Rect 42x43+0+0> (rectangle<-geometry-string "42") ⇒ #f
Note that the print representation of a rectangle always has “+”. The
term “geometry string” derives from the X Window System, where many
programs take a --geometry (or -g for short) command-line
option.
Return a procedure P that checks the event queue for timeout
ms, polling every slice ms. If an event arrives during that time,
return #t. Otherwise return #f. Optional arg
get-timeout-events is either a list of events to be pushed on the
queue in the case of timeout, or a thunk to be called that produces such a
list. If get-timeout-events is specified, return the result of
another event queue polling. (This may still be #f if the pushed
events are masked in some way.)
P is called with a single arg, a pre-constructed event object. This
interface is congruent with that of wait-event and poll-event.
See Events.
Return a new rectangle with the same width and height as surface. Optional second and third arg (which must appear together or not at all) specifies the x and y components, respectively, to use instead of the default of 0 (zero).
Return a new rectangle copied from rect.
Optional second arg modify specifies which portions,
if any, to modify using the values in the rest args.
If modify is #:xy, the two args specify
new x and y values. If modify is
#:wh, the two args specify new w and
h values.
rect ⇒ #<SDL-Rect 3x4+1+2> (copy-rectangle rect) ⇒ #<SDL-Rect 3x4+1+2> (copy-rectangle rect #:xy 11 22) ⇒ #<SDL-Rect 3x4+11+22> (copy-rectangle rect #:wh 33 44) ⇒ #<SDL-Rect 33x44+1+2>
Create a new surface and blit surface onto it. The new surface has the same pixel format as surface. Return the new surface.
Optional second arg clip is a rectangle describing the portion of surface to copy (default is the entire surface).
Arrange to ignore all event types except those in types
(see event-type enums). As a special case, if types
is #f, arrange to not ignore any event types (all are enabled).
In the following procs, those named ending with /3p return
three values, each a thunk (unless specified otherwise) handling the
three-phase calling convention, namely init, next, and
done.
(call-with-values (lambda () (foo/3p ...))
(lambda (init! foo! done!)
(init!)
(let loop ((continue? (foo!)))
(and continue? (loop (foo!))))
(done!)))
Note that foo! returns non-#f to indicate that the
looping is not yet complete.
Return three values, each a thunk, that can be used to loop for
sec seconds, blitting onto realized at location (a
rectangle or #f to indicate the origin) the alpha-composition
of image and its replacement (both surfaces), to effect a
fade-in of replacement over image. The alpha value
is directly proportional to the time between the “next!” phase call
and the “init!” phase call.
realized may be either a surface, in which case at the end of each
loop it is shown via update-rect; or a pair whose CAR is
a surface and whose CDR is a thunk that should do the showing.
Note that location is used for blitting, so its width and height should match those of image and replacement.
Return three values, the first a procedure of one arg, the other two
thunks, that can be used to toroidally pan surface by dx
and dy pixels. This means that data disappearing from one side
of the surface (left, right, top, bottom) is rotated to appear at the
other side (right, left, bottom, top). The init! procedure takes
one arg count, the number of pans to do.
Positive dx moves surface data to the left (panning right), and likewise, positive dy, up (panning down).
Optional third arg sub is a rectangle object specifying a subset of the surface. The default is to pan the entire surface.
Optional fourth arg batch? non-#f means to call
update-rect on the (sub)surface after all the panning is done.
The default is to update the surface after each pan. Batch mode is
useful for implementing variable-speed panning, for example:
(define (pan dir)
(call-with-values (lambda ()
(toroidal-panner/3p screen
(* dir 21)
(* dir 12)
#f #t))
(lambda (init! next! done!)
(lambda (count)
(init! count)
(let loop ((continue? (next!)))
(and continue? (loop (next!))))
(done!)))))
(define pan-away (pan 1))
(define pan-back (pan -1))
(define ramp (map 1+ (append (make-list 21 0)
(identity (iota 12))
(reverse! (iota 12))
(make-list 21 0))))
(for-each pan-away ramp)
(for-each pan-back ramp)
Next: Excuses, Previous: Miscellaneous Utilities, Up: The (sdl *) Modules [Contents][Index]
This chapter documents module (sdl simple).
This module provides some simple abstractions to introduce common Guile-SDL programming idioms. Although the interfaces are documented, they are permanently alpha, that is, subject to change w/o notice. Instead of relying on the stability of the interface, you are encouraged to look at the implementation as a model for creating customized abstractions.
Return a canvas closure that accepts a few simple messages.
If init? is non-#f, initalize the SDL video subsystem first.
w, h, and bpp specify the width, height, and
bits-per-pixel, respectively.
flags are symbols to set the video mode. If omitted, the
default is hw-surface and doublebuf.
The closure, if called without arguments, returns the video surface. Otherwise, the following messages are recognized:
#:rectReturn a rectangle the width and height of the canvas.
#:set-bg! r g bSet the background color (used for clearing) to the color specified by r, g and b (integers 0-255), respectively. By default it is black (all values zero).
#:clear!Fill the canvas with the background color.
#:w#:h#:w/hReturn width, height, or a cons of width and height, respectively.
#:resize! new-width new-heightRequest that the canvas dimension be changed to new-width by new-height. Return a rect that reflects the actual dimension.
Return a stylus closure that accepts a few simple messages.
If init? is non-#f, initialize the SDL TTF support first.
filename specifes the .ttf file to load and size the size.
r, g and b are integers (0-255) specifying the color.
The closure recognizes the following messages:
#:set-font! filename size#:set-color! r g bChange the font or color, respectively.
#:set-canvas! surfaceSet the surface on which the #:write! command renders.
#:render text [color [bg]]Return a surface of text rendered using the default
font, size, color and size. Optional second arg color
specifies another color to use. Optional third arg bg
specifies a background mode: #f (default) for “solid”;
#t for “blended”; a color to use that color.
#:write! where text [color [bg]]Similar to #:render, but also blit the surface onto the canvas at the rectangle position specified by where. The width and height components of where are updated by side effect.
Return a vpacked image closure that accepts a few simple messages. "Vpacked" means multiple vertically-abutted images of dimensions NxN (at the top) through Nx1 (at the bottom), stored in a single image file. filename specifies the file and optional arg canvas specifies a surface for blitting. The closure recognizes the following messages:
#:set-canvas! surfaceChange the canvas.
#:rectsReturn the vector of rectangles of length N+1 (the element at index
zero is #f) corresponding to areas on the image representing
the smaller sub-images. The element at index I is a rectangle of
dimension IxI.
#:blit! i rectBlit the sub-image i (an integer 1 <= I <= N), onto the canvas. rect specifies a rectangle to blit to.
Next: Stashes, Previous: Simple Closures, Up: The (sdl *) Modules [Contents][Index]
Here are some notes on interface elements from /usr/include/SDL/*.h that are not yet wrapped by Guile-SDL. As things progress elements will be removed until an irreducible set remains.
Interface elements have zero or more attributes,
some of which indicate irreducibility (such as probably-never).
Following the attribute groupings are specific notes on those
elements that are particular in some way. The presentation order
is not significant.
For brevity, we omit the SDL_ prefix in the groupings.
There are two speical cases: (N) stands for SDLNet_,
and (M) stands for Mix_.
internalThese interface elements are exposed in the C header but should not be exposed to Scheme, for reasons of either safety or inutility.
SoftStretch LowerBlit UpperBlit VideoInit VideoQuit AudioQuit AudioInit (M)GetChunk
probably-neverDon’t expect to see these exposed to Scheme, ever!
SoftStretch SaveBMP_RW LoadBMP_RW VideoInit VideoQuit InitQuickDraw RegisterApp SetModuleHandle getenv putenv ClearError SetError WriteBE64 WriteLE64 WriteBE32 WriteLE32 WriteBE16 WriteLE16 ReadBE64 ReadLE64 ReadBE32 ReadLE32 ReadBE16 ReadLE16 CloseAudio UnlockAudio LockAudio MixAudio ConvertAudio BuildAudioCVT FreeWAV LoadWAV_RW PauseAudio GetAudioStatus OpenAudio AudioDriverName AudioQuit AudioInit (M)GetMusicHookData (M)GetChunk
dozeWindoze support, blech.
SaveBMP_RW LoadBMP_RW RegisterApp SetModuleHandle
threading-implicationsWill (any :–) ttn ever be ready for parallelism?
RemoveTimer AddTimer SetTimer KillThread WaitThread GetThreadID ThreadID CreateThread CondWaitTimeout CondWait CondBroadcast CondSignal DestroyCond CreateCond SemValue SemPost SemWaitTimeout SemTryWait SemWait DestroySemaphore CreateSemaphore DestroyMutex mutexV mutexP CreateMutex
todoTo be completed by Guile-SDL 1.0 (that is, if All Goes Well).
KillThread WaitThread GetThreadID ThreadID CreateThread CondWaitTimeout CondWait CondBroadcast CondSignal DestroyCond CreateCond SemValue SemPost SemWaitTimeout SemTryWait SemWait DestroySemaphore CreateSemaphore DestroyMutex mutexV mutexP CreateMutex (N)Init (N)Quit (N)ResolveHost (N)ResolveIP (N)TCP_Open (N)TCP_Accept (N)TCP_GetPeerAddress (N)TCP_Send (N)TCP_Recv (N)TCP_Close (N)AllocPacket (N)ResizePacket (N)FreePacket (N)AllocPacketV (N)FreePacketV (N)UDP_Open (N)UDP_Bind (N)UDP_Unbind (N)UDP_GetPeerAddress (N)UDP_SendV (N)UDP_Send (N)UDP_RecvV (N)UDP_Recv (N)UDP_Close (N)AllocSocketSet (N)AddSocket (N)DelSocket (N)CheckSockets (N)SocketReady (N)FreeSocketSet (N)Write16 (N)Write32 (N)Read16 (N)Read32 (M)SetPostMix (M)HookMusic (M)HookMusicFinished (M)ChannelFinished (M)RegisterEffect (M)UnregisterEffect (M)UnregisterAllEffects (M)SetReverb (M)SetReverseStereo (M)SetMusicPosition (M)SetSynchroValue (M)GetSynchroValue
rwopsRead-write operations.
FreeRW AllocRW RWFromMem RWFromConstMem RWFromFile
macosMacintosh support, meh.
InitQuickDraw
endianThese concern little- vs. big-endian i/o. Perhaps Guile already provides decent alternatives.
WriteBE64 WriteLE64 WriteBE32 WriteLE32 WriteBE16 WriteLE16 ReadBE64 ReadLE64 ReadBE32 ReadLE32 ReadBE16 ReadLE16
use-mixer-insteadThese elements are obsoleted by the module (sdl mixer).
CloseAudio UnlockAudio LockAudio MixAudio ConvertAudio BuildAudioCVT FreeWAV LoadWAV_RW PauseAudio GetAudioStatus OpenAudio AudioDriverName AudioQuit AudioInit
hookCallback from SDL to Scheme code. Can be tricky to get right...
(M)SetPostMix (M)HookMusic (M)HookMusicFinished (M)ChannelFinished (M)RegisterEffect (M)UnregisterEffect (M)UnregisterAllEffects
SDL_SoftStretchSDL_video.h sez: /* Not in public API at the moment - do not use! */
SDL_CreateRGBSurfaceFromnot sure what this is useful for
SDL_GL_UpdateRectsarglist: (int numrects, SDL_Rect* rects) we can either try to map uniform vectors (of smobs), or introduce a `RectVector' smob.
SDL_VideoInitactually, SDL_video.h sez: /* These functions are used internally, and should not be used unless you * have a specific need to specify the video driver you want to use. * You should normally use SDL_Init() or SDL_InitSubSystem(). * ... */
SDL_VideoQuitsee note for `SDL_VideoInit'
SDL_Linked_VersionSDL_version.h sez: /* This function gets the version of the dynamically linked SDL library. it should NOT be used to fill a version structure, instead you should use the SDL_Version() macro. */
SDL_GetWMInforeturn value for proc `get-wm-info' does not presently include the `lock_func' and `unlock_func' hooks. support for those will be added after i figure out how to "thunkify" them.
SDL_GetKeyNamewhy do we want to know the name of a key?
SDL_AudioQuitSDL_audio.h sez: /* These functions are used internally, and should not be used unless you * have a specific need to specify the audio driver you want to use. * You should normally use SDL_Init() or SDL_InitSubSystem(). */
SDL_AudioInitsee note for `SDL_AudioQuit'
SDLNet_AddSocketthere are also: #define SDLNet_TCP_AddSocket #define SDLNet_UDP_AddSocket
SDLNet_DelSocketthere are also: #define SDLNet_TCP_DelSocket #define SDLNet_UDP_DelSocket
Mix_GetMusicHookDataIf (when) `Mix_HookMusic' is added, it will not support "user data". It's better to use object properties for that.
Next: GNU Free Documentation License, Previous: Excuses, Up: The (sdl *) Modules [Contents][Index]
There are 21 stashes (11 enums, 10 flags).
Distribution of symbols count:
2 5 ========================= min: 2 3 3 =============== max: 231 4 1 ===== mean: 17.0 5 4 ==================== median: 5.0 7 2 ========== 8 1 ===== 11 1 ===== 15 1 ===== 17 1 ===== 18 1 ===== 231 1 =====
Distribution of symbol lengths:
1 26 ============= min: 1 2 19 ========== max: 17 3 23 ============ mean: 6.5126 4 38 =================== median: 7.0 5 28 ============== 6 31 ================ 7 28 ============== 8 103 ==================================================== 9 18 ========= 10 13 ======= 11 4 == 12 10 ===== 13 3 == 14 2 = 15 8 ==== 17 3 ==
lost gained
transparent opaque
mousefocus inputfocus active
audio data
tray-empty playing error stopped paused
Note that these are a proper superset of those in the
event-type enums, below.
active mouse-button-up joy-button-up key-down mouse joy key-up joy-axis-motion quit key joy-ball-motion sys-wm mouse-motion joy-hat-motion video-resize mouse-button-down joy-button-down video-expose
Note that these are a proper subset of those in the
event-mask flags, above.
active mouse-button-up joy-button-up key-down joy-axis-motion quit key-up joy-ball-motion sys-wm mouse-motion joy-hat-motion video-resize mouse-button-down joy-button-down video-expose
no out in
none upside-down clockwise counter-clockwise
normal italic strikethrough bold underline
off on query
timer cdrom no-parachute audio joystick event-thread video everything
centered right left up down
L-shift L-alt num R-shift R-alt caps L-ctrl L-meta mode R-ctrl R-meta
released pressed
Note that digits begin with D- so that they are
unambiguously (to read) symbols.
a b c d e f g h i j k l m n o p q r s t u v w x y z
D-0 … D-9
ampersand backquote capslock delete end
asterisk backslash caret dollar equals
at backspace clear escape
break colon euro
comma exclaim
compose
f1 … f15
hash insert help home
kp-0 … kp-9
kp-plus kp-equals kp-minus kp-period kp-multiply kp-enter kp-divide
left right up down
L-alt L-ctrl L-meta L-shift L-super R-alt R-ctrl R-meta R-shift R-super
L-bracket R-bracket L-paren R-paren
less greater
menu pagedown question scrollock tab
minus pageup quote semicolon
mode pause quotedbl slash underscore
numlock period space undo
plus return sysreq
power
print
world-0 … world-95
left wheel-up x1 middle wheel-down x2 right
left wheel-up x1 middle wheel-down x2 right
Although these should be enums, these are putative flags due to a limitation in the implementation2. Procs that use them enforce enums-ish usage, anyway; a list of symbols results in an error.
YV12 YVYU UYVY YUY2 IYUV
logical physical
sw-surface no-frame prealloc hw-surface hw-accel any-format opengl src-colorkey hw-palette async-blit rle-accel-ok doublebuf opengl-blit rle-accel fullscreen resizable src-alpha
Next: Index, Previous: Stashes, Up: The (sdl *) Modules [Contents][Index]
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. https://fsf.org/ Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.
The “publisher” means any person or entity that distributes copies of the Document to the public.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See https://www.gnu.org/licenses/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document.
“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.
“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.
“Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.
An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C) year your name. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with…Texts.” line with this:
with the Invariant Sections being list their titles, with
the Front-Cover Texts being list, and with the Back-Cover Texts
being list.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.
Previous: GNU Free Documentation License, Up: The (sdl *) Modules [Contents][Index]
| Jump to: | A B C D E F G H I J K L M N O P Q R S T U V W Z |
|---|
| Jump to: | A B C D E F G H I J K L M N O P Q R S T U V W Z |
|---|
The SDL homepage is https://www.libsdl.org.
For
speed, we use immediate integers (aka fixnums)
for enums, but those are not wide enough on a 32-bit
system to hold the overlay values.
Probably this should be rectified prior to release as
it represents a semi-regression.
OTOH, it’s not like anyone is actually using
create-yuv-overlay anyway…