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.
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 srfi's
(use-modules ((sdl sdl) #:renamer (symbol-prefix-proc 'SDL:))
(srfi srfi-1)
(srfi srfi-2))
;; initialize the video subsystem
(SDL:init '(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)))
(if (SDL:wait-event e)
(case (SDL:event:type e)
((SDL_KEYDOWN)
(case (SDL:event:key:keysym:sym e)
((SDLK_LEFT SDLK_BACKSPACE)
(show (prev-image)))
((SDLK_RIGHT SDLK_SPACE)
(show (next-image)))
((SDLK_ESCAPE SDLK_q)
(SDL:quit)
(quit))))))
(handle e))
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).
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.
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. All such constant symbols retain their
exact C names.
A particular set of enums is called an enumstash. Likewise flagstash for flags.
Returned by
fading-musicandfading-channel. See Audio. Values areMIX_foo, where foo can be:FADING{IN,OUT} NO_FADING
First arg to
make-eventand toevent-state. See Events. Values areSDL_foo, where foo can be:ACTIVEEVENT JOY{AXIS,BALL,HAT}MOTION JOYBUTTON{DOWN,UP} KEY{DOWN,UP} MOUSEBUTTON{DOWN,UP} MOUSEMOTION QUIT SYSWMEVENT USEREVENT VIDEORESIZE
First arg to
make-keysym. See Events. Values areSDLK_foo, where foo can be: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 0 1 2 3 4 5 6 7 8 9 AMPERSAND BACKQUOTE CAPSLOCK DELETE END ASTERISK BACKSLASH CARET DOLLAR EQUALS AT BACKSPACE CLEAR ESCAPE BREAK COLON EURO COMMA EXCLAIM F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 F13 F14 F15 HASH INSERT HELP HOME KP0 KP1 KP2 KP3 KP4 KP5 KP6 KP7 KP8 KP9 KP_DIVIDE KP_ENTER KP_EQUALS KP_MINUS KP_MULTIPLY KP_PERIOD KP_PLUS LEFT RIGHT UP DOWN LALT RALT LCTRL RCTRL LMETA RMETA LSHIFT RSHIFT LSUPER RSUPER LEFTBRACKET RIGHTBRACKET LEFTPAREN RIGHTPAREN LESS GREATER MENU PAGEDOWN QUESTION SCROLLOCK MINUS PAGEUP QUOTE SEMICOLON MODE PAUSE QUOTEDBL SLASH PERIOD SPACE TAB NUMLOCK PLUS RETURN SYSREQ POWER PRINT UNDERSCORE
Second arg to and return value of
event-state. See Events. Values are:SDL_ENABLE SDL_IGNORE SDL_QUERY
Third arg to
set-alpha!. See Video. Values are:SDL_ALPHA_TRANSPARENT SDL_ALPHA_OPAQUE
You can use enumstash-enums and flagstash-flags to examine the
enums and flags encapsulated by these respectively typed objects. You may
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.
Return a list of all the flags (symbols) in stash, a flagstash object, in unspecified order.
Use stash to convert flags to a number. flags is a list of symbols.
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.
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...
Here is an excerpt of the TODO file:
- 0.3 "coverage"
- (sdl gfx)
+ SDLgfxBlitRGBA
+ SDLgfxSetAlpha
- SDLimageFilter* (many funcs)
+ with C fallback
- assembler only
- interface present but "not yet implemented"
+ peep-event
- set-event-filter
- get-event-filter
+ event-state
+ get-key-state
+ scale-surface (deleted)
- programming practice review
- return values
- smob safety
- 0-means-success
- consistency
- use unsigned long for colors
- /usr/include/SDL/*.h coverage
- mixer
- hooks
- effects
+ panning / position / distance
- opengl?
- 0.4 "control"
- threading system
- signals
- interop w/ other event loops?
- fastevents
- 0.5 "glitches"
- review/revise interfaces (WARNING: disruptive)
- error handling cleanup
- document policy
- cases: NULL, -1, ...
- 0.6 "earth"
- handle pre-installed libSDLgfx
- write configure check for it
- use it if it is featureful enough
- two-level modularization
- many small modules: (sdl modules cdrom)
+ overarching: (sdl sdl)
- finalize interfaces
- 0.7 "water"
- write configure check for guile that can load binary modules
- executable modules: (sdl scripts FOO)
- third-party post-install extension framework
- 0.8 "fire"
- performance tweaking
- user-alloc alternatives (less consing) for event procs
- 0.9 "air"
- you/
- 1.0
- eventually
- port to Mac OSX/BeOS (ignore windoze)
- switch to an automated wrapper generater
Basically, a 1.0 release is still quite far away. But we'll get there
at some point. Another interesting thing to consider is, what happens
if there is another release of SDL after 1.2? What if it is (gasp)
incompatible with SDL 1.2?
SDL_INIT_foo, where foo can be:
VIDEO CDROM JOYSTICK
EVERYTHING EVENTTHREAD AUDIO
NOPARACHUTE
Initialize SDL based on configuration flags sel. sel is a list of symbols whose names all begin with
SDL_INIT_.
Initialize the SDL subsystems represented by sel. sel is a list of flags (symbols) from the same set useful for
init.
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.
SDL_foo, where foo can be:
OPENGL SRCALPHA ASYNCBLIT
OPENGLBLIT NOFRAME RLEACCEL
HWPALETTE RLEACCELOK SRCCOLORKEY
HWACCEL PREALLOC SWSURFACE
HWSURFACE ANYFORMAT FULLSCREEN
RESIZABLE DOUBLEBUF
Return the flagstash object for palette flags. See Enums and Constants.
SDL_LOGPAL SDL_PHYSPAL
Return the flagstash object for overlay flags. (Actually, these are "common overlay formats", not flags.) See Enums and Constants.
SDL_foo_OVERLAY, where foo can be:
YVYU YUY2 IYUV YV12 UYVY
Return a new cursor from data and mask (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 information about the video hardware as an alist. Keys are:
hw-available,wm-available,bit-hw,blit-hw-CC,blit-hw-A,blit-sw,blit-sw-CC,blit-sw-A,blit-fill,video-memandvfmt.
Return a list of available screen dimensions for pixel format and flags. Format defaults to that for the current screen. Flags default to none (see
flagstash:video). 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
flagstash:video). 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
flagstash:video) is supported. Return a new surface.
Return a rectangle object with location x,y and dimensions width by height.
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. The return value is unspecified.
On surface, update the rectangles in ls, a list of rectangles. The return value is unspecified.
Swap double buffers of the default surface, or of surface if specified. The return value is unspecified.
Set a portion of the colormap for the 8-bit surface using colors, a vector of SDL-Colors.
Set the palette of an 8-bit surface using flags (see
flagstash:palette) and colors, a vector of SDL-Colors.
Set the color gamma function for the display using real numbers redgamma, greengamma and bluegamma.
Get the gamma translation lookup tables currently used by the display. Each table is a vector of 256 integer values. Return an alist with keys
redtable,greentableandbluetable, and values the corresponding vectors. Return #f if unsuccessful.
Set the gamma translation lookup tables currently used by the display, for redtable, greentable and bluetable. Each table is an vector of 256 integer values. 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.
Get RGB values from pixel in the specified pixel format. Return an alist with keys
r,gandb, with red, green and blue values (numbers), respectively.
Get RGBA values from pixel in the specified pixel format. Return an alist with keys
r,g,banda, with red, green, blue and alpha values (numbers), respectively.
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. The return value is unspecified.
Set the current mouse cursor to cursor. The return value is unspecified.
Toggle the visibility of the mouse cursor. Return #t if was being displayed before the call, and #f if not. Optional arg query non-#f means to return the current state without toggling.
Set the special SDL/OpenGL attribute to value. Both args are numbers. The return value is unspecified.
Swap OpenGL framebuffers/Update Display. The return value is unspecified.
Unlock the previously locked YUV overlay. The return value is unspecified.
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 an alist with keys
titleandiconand values the title-bar and icon name of the display window, respectively.
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),offoron.Compatibility Note: Presently, mode can also be an integer, one of -1, 0 or 1. Starting with Guile-SDL 0.5.0 an integer mode will result in a wrong-type-arg error.
Return the current state of the application, a list of symbols. The list may include: `mousefocus', `inputfocus', `active'.
Return a new surface of dimensions width by height. Optional third arg flags (see
flagstash:video) 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
flagstash:video), width, height, depth, rmask, gmask, bmask, amask (all numbers).
Unlock previously locked surface. The return value is unspecified.
Return a surface made by loading the image file. If there are problems, return #f.
Return a surface made by loading image data from string s. [WARNING: This procedure is experimental!]
Save surface to file in Windows BMP format. Return #t if successful.
Set surface color key as specified by flag (see
flagstash:video) and key.
Adjust whole-surface alpha as specified by flag (see
flagstash:video) and alpha (one of thealpha-enums, or a number 0-255). See Enums and Constants. If flag is #f, ignore alpha completely.
Set surface clipping rectangle to the whole surface. Optional arg rect, if non-#f, specifies a particular rectangle instead of using the whole surface.
Convert surface to the same format as another surface. Optional third arg flags is a list of flags (symbols) from the set returned by
flagstash:video.
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 the flagstash object for event mod flags. See Enums and Constants.
KMOD_foo, where foo can be:
RALT RMETA RSHIFT NUM
LALT LMETA LSHIFT RESERVED
CAPS RCTRL MODE LCTRL
NONE
Return the flagstash object for event mask flags. See Enums and Constants.
SDL_fooMASK, where foo can be:
ACTIVEEVENT
JOYEVENT ; logior of 5 SDL_JOY*MASK:
JOY{AXIS,BALL,HAT}MOTION
JOYBUTTON{DOWN,UP}
KEYEVENT ; logior of 2 SDL_KEY*MASK:
KEY{DOWN,UP}
MOUSEEVENT ; logior of 3 SDL_MOUSE*MASK:
MOUSEBUTTON{DOWN,UP}
MOUSEMOTION
QUIT SYSWMEVENT
VIDEOEXPOSE VIDEORESIZE
Return a new SDL event. Optional arg type is one of the symbols enumerated in the variable
event-types. If omitted, the default isSDL_NOEVENT. See Enums and Constants.
Return a new keysym. Optional args sym and mod specify one of the
event-keys(see Enums and Constants) and any modifiers (fromflasgstash:event-mod), respectively.
Set
key.keysym.scancodein theSDL_Event *obj to value.
Set
key.keysym.unicodein theSDL_Event *obj to value.
Return #t if buttons specified in mask (an integer) are pressed. Use 1 for left, 2 for middle and 4 for right, combined with
logior, to form mask. For example, a value of 5 specifies both left and right buttons.
Set
jbutton.buttonin theSDL_Event *obj to value.
Gather events from input devices and update the event queue. The return value is unspecified.
Manage the event queue, depending on action:
SDL_ADDEVENT- Add up to numevents (an integer) events from events (a list) to the back of the event queue.
SDL_PEEKEVENT- Return a count (number less than or equal to numevents) of events at the front of the event queue that match mask (see
flagstash:event-mask), without changing the queue.SDL_GETEVENT- Act like for
SDL_PEEKEVENTexcept return a list of matching events instead of a count, removing them from the queue.
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 1 for success, 0 if the queue was full, -1 for other errors.
Query or set event type to state. type should be one elements from
event-types, and likewise state fromevent-states. See Enums and Constants. If state isSDL_QUERY, return the current processing state of the specified event.
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.
Set the current key modifier state to modstate, a list of symbols. This does not change the keyboard state, only the key modifier flags. The return value is unspecified.
Return the current state of the mouse as an alist with symbolic keys:
state,xandy.
Return the current relative state of the mouse as an alist symbolic keys:
state,xandy.
Return #t iff joystick is a NULL joystick. [What does that mean? –ttn]
Return the name of the default joystick. 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.
For joystick, return relative motion of trackball n, as an alist with keys
dxanddy. On error, return #f.
Close a previously opened joystick. The return value is unspecified.
Return a human-readable, system-dependent identifier (a string) for the CDROM. 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, one of:
TRAYEMTPY,STOPPED,PLAYING,PAUSEDorERROR.
For CD in drive cdrom, return info on track n as an alist or #f if there were problems.
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-statusto 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.
Return frames (an integer) computed fr m, second s and frame f. s and f are optional.
Return a minute/second/frames alist made from converting frames (a number).
[todo]
Return the flagstash object for ttf flags. You can pass this object to proc
flagstash-flagsto get a list of its flags. See Enums and Constants.
TTF_STYLE_foo, where foo can be:
BOLD NORMAL UNDERLINE ITALIC
Return the style of font (see
flagstash:ttf). 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
flagstash:ttf). This font style is implemented by modifying the font glyphs, and doesn't reflect any inherent properties of the truetype font file.
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 metrics (dimensions) of a glyph as an alist. The glyph is a font-specific rendering of char ch. Alist keys are:
minx,maxx,miny,maxyandadvance. Values are numbers.
Return an alist with keys
wandhand corresponding values (numbers) representing the width and height of the font-specific rendering of the string text.
Return an alist with keys
wandhand corresponding values (numbers) representing the width and height of the font-specific rendering of the utf8 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.
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 an alist, or #f if the audio has not yet been opened. Keys are
freq(frequency),format, andchannels(the number of allocated channels).
Load a wave or a music (.mod .s3m .it .xm) file. Return a handle to it.
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.
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 default channel. Optional arg which selects which channel to check. See Enums and Constants.
Pause the default channel. Optional arg channel selects which channel to pause. Return value unspecified.
Resume (unpause) the default channel. Optional arg channel selects which channel to resume. Return value unspecified.
Return #t if the default channel is paused. Optional arg channel selects a which channel to check.
Return #t iff the default channel is playing. Optional arg channel selects which channel to check.
Stop music and set external music playback command to command, a string.
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.
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 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 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.