The (sdl *) Modules 1 Introduction 1.1 Quick Start 1.2 Naming Conventions 1.2.1 Renaming C Functions 1.2.2 Enums and Constants 1.2.3 Create and Make 1.3 Uniform Vectors 1.4 Limitations 2 General SDL 3 Video 3.1 Rectangles 3.2 Colors 3.3 Windowing System Interaction 3.4 Surface 3.5 Misc Surface Operations 4 Events 4.1 Activity 4.2 Keys 4.3 Motions 4.4 Buttons 4.5 Joysticks 4.6 Resizes 4.7 Misc 5 Joystick 6 CDROM 7 OpenGL 8 TrueType 9 Audio 10 SDL_gfx by Andreas Schiffler 10.1 Graphics Primitives 10.2 Rotation / Zooming 10.3 Managing Frame Rate 10.4 RGBA Extras 10.5 Image Filtering 11 Miscellaneous Utilities 12 Simple Closures 13 Excuses 13.1 Categories 13.2 Specific Notes Appendix A Stashes Appendix B GNU Free Documentation License Index The (sdl *) Modules ******************* 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 Layer(1) 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”. ---------- Footnotes ---------- (1) The SDL homepage is . 1 Introduction ************** 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. 1.1 Quick Start =============== 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)) 1.2 Naming Conventions ====================== 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). 1.2.1 Renaming C Functions -------------------------- 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. 1.2.2 Enums and Constants ------------------------- 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. -- Procedure: kotk [name] 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’. -- Procedure: enum->number stash symbol Return the number in STASH associated with SYMBOL. -- Procedure: number->enum stash number Return the symbol associated with NUMBER, or ‘#f’ if it does not belong to STASH. -- Procedure: flags->number stash flags 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. -- Procedure: number->flags stash number 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. 1.2.3 Create and Make --------------------- 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. 1.3 Uniform Vectors =================== Some procedures take one or more “uniform vector” arguments, as specified in SRFI 4 (*note Video::, *note SDL_gfx::). 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. 1.4 Limitations =============== There are some known problems with Guile-SDL modules. This section attempts to make them well-known, if not well-liked... • API in flux 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. • no logo How can any self-respecting package of bindings for libsdl not have a flashy, animated logo? Bonus points for suitable accompanying sound blurb. • threading picture unclear 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... • [your gripes here] 2 General SDL ************* The external representation of a Pixel Format object is: # 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. -- Procedure: init sel Initialize SDL and the subsystems/configuration represented by SEL (*note init flags::). -- Procedure: init-subsystem sel Initialize the SDL subsystems represented by SEL. SEL is a list of flags (symbols) from the same set useful for ‘init’. -- Procedure: quit Shut down all SDL subsystems. Return ‘#t’. -- Procedure: quit-subsystem sel Shut down the SDL subsystems represented by SEL. SEL is a list of flags (symbols) from the same set useful for ‘init’. Return ‘#t’. -- Procedure: was-init sel 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. -- Procedure: get-ticks Return the number of milliseconds since the SDL library initialization. -- Procedure: delay ms Wait MS milliseconds. -- Procedure: get-error Return the current SDL error string. 3 Video ******* -- Procedure: create-cursor data mask w h x y Return a new cursor from DATA and MASK (both u8 uniform vectors), sized W by H and with hot pixel located at X,Y. -- Procedure: create-yuv-overlay width height format [display] 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. -- Procedure: get-video-surface Return the current display surface. -- Procedure: video-cmf 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 -- Procedure: video-driver-name Return the name of the video driver. -- Procedure: list-modes [format [flags]] Return a list of available screen dimensions for pixel FORMAT and FLAGS (*note 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. -- Procedure: video-mode-ok width height bpp [flags] Check to see if a particular video mode is supported. Args are WIDTH, HEIGHT, BPP (numbers), and FLAGS (*note 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. -- Procedure: set-video-mode width height bpp [flags] Set the SDL video mode with WIDTH, HEIGHT and bits-per-pixel BPP. Optional arg FLAGS (*note video flags::) is supported. Return a new surface. 3.1 Rectangles ============== The external representation of a Rectangle object is: # 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 ‘-’. -- Procedure: rect? obj Return ‘#t’ iff OBJ is an SDL-rectangle object. -- Procedure: make-rect x y width height Return a rectangle object with location X,Y and dimensions WIDTH by HEIGHT. -- Procedure: rect:x rect Get ‘x’ from RECT. -- Procedure: rect:y rect Get ‘y’ from RECT. -- Procedure: rect:w rect Get ‘w’ from RECT. -- Procedure: rect:h rect Get ‘h’ from RECT. -- Procedure: rect:set-x! rect value Set ‘x’ in RECT to VALUE. -- Procedure: rect:set-y! rect value Set ‘y’ in RECT to VALUE. -- Procedure: rect:set-w! rect value Set ‘w’ in RECT to VALUE. -- Procedure: rect:set-h! rect value Set ‘h’ in RECT to VALUE. -- Procedure: update-rect surface x [y [w [h]]] 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. -- Procedure: update-rects surface ls On SURFACE, update the rectangles in LS, a list of rectangles. -- Procedure: flip [surface] Swap double buffers of the default surface, or of SURFACE if specified. 3.2 Colors ========== The external representation of a Color object is: # where R is the decimal value of the color object’s red component, and G and B the likewise respective green and blue components. -- Procedure: color? obj Return ‘#t’ iff OBJ is an SDL-Color object. -- Procedure: make-color r g b Return a color object with R, G, and B components. -- Procedure: color:r color Get ‘r’ from COLOR. -- Procedure: color:g color Get ‘g’ from COLOR. -- Procedure: color:b color Get ‘b’ from COLOR. -- Procedure: color:set-r! color value Set ‘r’ in COLOR to VALUE. -- Procedure: color:set-g! color value Set ‘g’ in COLOR to VALUE. -- Procedure: color:set-b! color value Set ‘b’ in COLOR to VALUE. -- Procedure: set-colors! surface colors [start] 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. -- Procedure: set-palette surface flags colors [start] Set the palette of an 8-bit SURFACE using FLAGS (*note 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. -- Procedure: set-gamma redgamma greengamma bluegamma Set the color gamma function for the display using real numbers REDGAMMA, GREENGAMMA and BLUEGAMMA. -- Procedure: get-gamma-ramp 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. -- Procedure: set-gamma-ramp r g b 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. -- Procedure: map-rgb format r [g [b]] 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. -- Procedure: map-rgba format r g [b [a]] 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. -- Procedure: pixel-rgb pixel format Return RGB info from PIXEL in the specified pixel FORMAT as three values: ‘r’, ‘g’ and ‘b’ (all integers). -- Procedure: pixel-rgba pixel format Return RGBA info from PIXEL in the specified pixel FORMAT as four values: ‘r’, ‘g’, ‘b’ and ‘a’ (all integers). -- Procedure: fill-rect surface rect color Fill SURFACE RECT with COLOR (a number). If RECT is ‘#f’, fill the entire surface. Return ‘#t’ if successful. -- Procedure: display-format surface Return a new surface made by converting SURFACE to the display format. Return ‘#f’ if not successful. -- Procedure: display-format-alpha surface Return a new surface made by converting SURFACE to the display format, with an alpha channel. Return ‘#f’ if not successful. -- Procedure: warp-mouse x y Set the position of the mouse cursor to X,Y. -- Procedure: set-cursor cursor Set the current mouse cursor to CURSOR. -- Procedure: get-cursor Get the current mouse cursor. -- Procedure: show-cursor [setting] 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). -- Procedure: gl-get-attribute attribute Return the value of a special SDL/OpenGL ATTRIBUTE. -- Procedure: gl-set-attribute attribute value Set the special SDL/OpenGL ATTRIBUTE to VALUE. Both args are numbers. -- Procedure: gl-swap-buffers Swap OpenGL framebuffers/Update Display. -- Procedure: lock-yuv-overlay overlay Lock the given YUV OVERLAY. Return ‘#f’ if successful. -- Procedure: unlock-yuv-overlay overlay Unlock the previously locked YUV OVERLAY. -- Procedure: display-yuv-overlay overlay dstrect Blit the YUV OVERLAY to the display DSTRECT over which it was created. Return ‘#t’ if successful. 3.3 Windowing System Interaction ================================ -- Procedure: get-wm-info 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). -- Procedure: set-caption title [icon] 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. -- Procedure: caption-ti Return display-window caption as two values: ‘title’ and ‘icon’ (both strings, or ‘#f’ if not set). -- Procedure: set-icon icon Set ICON for the display window. -- Procedure: iconify-window Iconify/Minimize the window. Return ‘#t’ if successful. -- Procedure: toggle-full-screen [surface] Toggle the default video surface between windowed and fullscreen mode, if supported. Optional arg SURFACE specifies another surface to toggle. Return ‘#t’ if successful. -- Procedure: grab-input [mode] 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’. -- Procedure: get-app-state Return the current state of the application, a list of symbols. The list may include: ‘mousefocus’, ‘inputfocus’, ‘active’. 3.4 Surface =========== The external representation of a Surface object is: ;; normally: # ;; when the object is not associated with a SDL_Surface: # 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. -- Procedure: make-surface width height [flags] Return a new surface of dimensions WIDTH by HEIGHT. Optional third arg FLAGS (*note video flags::) further specifies the surface. Color depth and masks are those for the current video surface. -- Procedure: create-rgb-surface flags width height depth rmask gmask bmask amask Return an empty surface. The eight arguments, directly analagous to those for SDL_CreateRGBSurface, are: FLAGS (list of symbols, *note video flags::), WIDTH, HEIGHT, DEPTH, RMASK, GMASK, BMASK, AMASK (all numbers). -- Procedure: surface:w surface Get ‘w’ from SURFACE. -- Procedure: surface:h surface Get ‘h’ from SURFACE. -- Procedure: surface:depth surface Get ‘format->BitsPerPixel’ from SURFACE. -- Procedure: surface:flags surface Return ‘flags’ from SURFACE as a (possibly empty) list of symbols. -- Procedure: surface-get-format surface Return a new pixel format, the same used by SURFACE. -- Procedure: surface? obj Return true iff OBJ is a surface. -- Procedure: lock-surface surface Lock SURFACE for direct access. Return ‘#t’ if successful. -- Procedure: unlock-surface surface Unlock previously locked SURFACE. -- Procedure: load-bmp filename Load bitmap data from FILENAME. Return a new surface if successful, otherwise ‘#f’. -- Procedure: load-image filename Load image data from FILENAME. Return a new surface if successful, otherwise ‘#f’. -- Procedure: save-bmp surface filename Save SURFACE to FILENAME in Windows BMP format. Return ‘#t’ if successful. -- Procedure: surface-color-key! surface pixel [rle] 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. -- Procedure: surface-alpha! surface alpha [rle] 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. -- Procedure: set-clip-rect! surface [rect] Set SURFACE clipping rectangle to the whole surface. Optional arg RECT, if non-‘#f’, specifies a particular rectangle instead of using the whole surface. -- Procedure: get-clip-rect surface Return the clipping rectangle for SURFACE. -- Procedure: convert-surface surface format [flags] Convert SURFACE to the same FORMAT as another surface. Optional third arg FLAGS is a list of flags (*note video flags::). -- Procedure: blit-surface src [srcrect [dst [dstrect]]] 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. 3.5 Misc Surface Operations =========================== -- Procedure: vertical-flip-surface surface Return a new surface created by flipping SURFACE vertically. -- Procedure: horizontal-flip-surface surface Return a new surface created by flipping SURFACE horizontally. -- Procedure: vh-flip-surface surface Return a new surface created by flipping SURFACE both vertically and horizontally. -- Procedure: surface-pixels surface [squash] 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. -- Procedure: must-lock? surface Return ‘#t’ if SURFACE needs to be locked before access. Failure to do so may result in a segfault. 4 Events ******** -- Procedure: make-event [type] Return a new SDL event. Optional arg TYPE is a symbol (*note event-type enums::). If omitted, the default is ‘SDL_NOEVENT’. -- Procedure: event:type event Return the symbolic ‘type’ from EVENT. -- Procedure: event:set-type! event value Set ‘type’ in EVENT to VALUE, a symbol or integer. 4.1 Activity ============ 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’. -- Procedure: event:active:gain event Return the symbolic ‘active.gain’ from EVENT. -- Procedure: event:active:state event Return ‘active.state’ from EVENT as a (possibly empty) list of symbols. -- Procedure: event:active:set-gain! event value Set ‘active.gain’ in EVENT to VALUE, a symbol or integer. -- Procedure: event:active:set-state! event value Set ‘active.state’ in EVENT to VALUE, a (possibly empty) list of symbols. 4.2 Keys ======== The value for ‘event:key:state’ and ‘event:key:set-state!’ is a symbol, one of: ‘released’ or ‘pressed’. -- Procedure: event:key:keysym:sym event Return the symbolic ‘key.keysym.sym’ from EVENT. -- Procedure: event:key:keysym:set-sym! event value Set ‘key.keysym.sym’ in EVENT to VALUE, a symbol or integer. -- Procedure: event:key:keysym:mod event Return ‘key.keysym.mod’ from EVENT as a (possibly empty) list of symbols. -- Procedure: event:key:keysym:set-mod! event value Set ‘key.keysym.mod’ in EVENT to VALUE, a (possibly empty) list of symbols. -- Procedure: event:key:state event Return the symbolic ‘key.state’ from EVENT. -- Procedure: event:key:keysym:scancode event Get ‘key.keysym.scancode’ from EVENT. -- Procedure: event:key:keysym:unicode event Get ‘key.keysym.unicode’ from EVENT. -- Procedure: event:key:set-state! event value Set ‘key.state’ in EVENT to VALUE, a symbol or integer. -- Procedure: event:key:keysym:set-scancode! event value Set ‘key.keysym.scancode’ in EVENT to VALUE. -- Procedure: event:key:keysym:set-unicode! event value Set ‘key.keysym.unicode’ in EVENT to VALUE. 4.3 Motions =========== -- Procedure: event:motion:state event Return ‘motion.state’ from EVENT as a (possibly empty) list of symbols. -- Procedure: event:motion:x event Get ‘motion.x’ from EVENT. -- Procedure: event:motion:y event Get ‘motion.y’ from EVENT. -- Procedure: event:motion:xrel event Get ‘motion.xrel’ from EVENT. -- Procedure: event:motion:yrel event Get ‘motion.yrel’ from EVENT. -- Procedure: event:motion:set-state! event value Set ‘motion.state’ in EVENT to VALUE, a (possibly empty) list of symbols. -- Procedure: event:motion:set-x! event value Set ‘motion.x’ in EVENT to VALUE. -- Procedure: event:motion:set-y! event value Set ‘motion.y’ in EVENT to VALUE. -- Procedure: event:motion:set-xrel! event value Set ‘motion.xrel’ in EVENT to VALUE. -- Procedure: event:motion:set-yrel! event value Set ‘motion.yrel’ in EVENT to VALUE. 4.4 Buttons =========== 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’. -- Procedure: event:button:button event Return the symbolic ‘button.button’ from EVENT. -- Procedure: event:button:state event Return the symbolic ‘button.state’ from EVENT. -- Procedure: event:button:x event Get ‘button.x’ from EVENT. -- Procedure: event:button:y event Get ‘button.y’ from EVENT. -- Procedure: event:button:set-button! event value Set ‘button.button’ in EVENT to VALUE, a symbol or integer. -- Procedure: event:button:set-state! event value Set ‘button.state’ in EVENT to VALUE, a symbol or integer. -- Procedure: event:button:set-x! event value Set ‘button.x’ in EVENT to VALUE. -- Procedure: event:button:set-y! event value Set ‘button.y’ in EVENT to VALUE. 4.5 Joysticks ============= 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’. -- Procedure: event:jaxis:which event Get ‘jaxis.which’ from EVENT. -- Procedure: event:jaxis:axis event Get ‘jaxis.axis’ from EVENT. -- Procedure: event:jaxis:value event Get ‘jaxis.value’ from EVENT. -- Procedure: event:jaxis:set-which! event value Set ‘jaxis.which’ in EVENT to VALUE. -- Procedure: event:jaxis:set-axis! event value Set ‘jaxis.axis’ in EVENT to VALUE. -- Procedure: event:jaxis:set-value! event value Set ‘jaxis.value’ in EVENT to VALUE. -- Procedure: event:jbutton:which event Get ‘jbutton.which’ from EVENT. -- Procedure: event:jbutton:button event Get ‘jbutton.button’ from EVENT. -- Procedure: event:jbutton:state event Return the symbolic ‘jbutton.state’ from EVENT. -- Procedure: event:jbutton:set-which! event value Set ‘jbutton.which’ in EVENT to VALUE. -- Procedure: event:jbutton:set-button! event value Set ‘jbutton.button’ in EVENT to VALUE. -- Procedure: event:jbutton:set-state! event value Set ‘jbutton.state’ in EVENT to VALUE, a symbol or integer. -- Procedure: event:jball:which event Get ‘jball.which’ from EVENT. -- Procedure: event:jball:ball event Get ‘jball.ball’ from EVENT. -- Procedure: event:jball:xrel event Get ‘jball.xrel’ from EVENT. -- Procedure: event:jball:yrel event Get ‘jball.yrel’ from EVENT. -- Procedure: event:jball:set-which! event value Set ‘jball.which’ in EVENT to VALUE. -- Procedure: event:jball:set-ball! event value Set ‘jball.ball’ in EVENT to VALUE. -- Procedure: event:jball:set-xrel! event value Set ‘jball.xrel’ in EVENT to VALUE. -- Procedure: event:jball:set-yrel! event value Set ‘jball.yrel’ in EVENT to VALUE. -- Procedure: event:jhat:which event Get ‘jhat.which’ from EVENT. -- Procedure: event:jhat:hat event Get ‘jhat.hat’ from EVENT. -- Procedure: event:jhat:value event Return ‘jhat.value’ from EVENT as a (possibly empty) list of symbols. -- Procedure: event:jhat:set-which! event value Set ‘jhat.which’ in EVENT to VALUE. -- Procedure: event:jhat:set-hat! event value Set ‘jhat.hat’ in EVENT to VALUE. -- Procedure: event:jhat:set-value! event value Set ‘jhat.value’ in EVENT to VALUE, a (possibly empty) list of symbols. 4.6 Resizes =========== -- Procedure: event:resize:w event Get ‘resize.w’ from EVENT. -- Procedure: event:resize:h event Get ‘resize.h’ from EVENT. -- Procedure: event:resize:set-w! event value Set ‘resize.w’ in EVENT to VALUE. -- Procedure: event:resize:set-h! event value Set ‘resize.h’ in EVENT to VALUE. 4.7 Misc ======== -- Procedure: pump-events Gather events from input devices and update the event queue. -- Procedure: evqueue-add [events...] Add ‘events’ to the back of the event queue. Return the count of succesfully added events. -- Procedure: evqueue-peek n mask [accumulate] 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’. *Note event-mask flags::. -- Procedure: evqueue-get n mask 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’. *Note event-mask flags::. -- Procedure: poll-event [event] 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). -- Procedure: wait-event [event] 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. -- Procedure: push-event event Push EVENT onto the queue. Return ‘#t’ on success. -- Procedure: set-event-filter filter full? 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. -- Procedure: get-event-filter 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. -- Procedure: event-type-handling type [setting] Return ‘#t’ if event TYPE (*note 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. -- Procedure: enable-unicode [enable-p] Return ‘#t’ iff UNICODE keyboard translation is enabled. Optional arg ENABLE? if non-‘#f’, enables UNICODE keyboard translation, or disables it if ‘#f’. -- Procedure: enable-key-repeat delay interval 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. -- Procedure: get-key-state Return a list of pressed keys (*note keysym enums::). -- Procedure: get-mod-state Return the current key modifier state as a list of symbols. -- Procedure: set-mod-state modstate Set the current key modifier state to MODSTATE, a list of symbols. This does not change the keyboard state, only the key modifier flags. -- Procedure: button? mask 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)’. -- Procedure: mouse-bxy [relative] 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. 5 Joystick ********** The external representation of a Joystick object is: # where INDEX is a decimal number of the joystick, or ‘-1’ if the object is not associated with a joystick. -- Procedure: num-joysticks Return the number of joysticks. -- Procedure: joystick? obj Return ‘#t’ iff OBJ is a joystick object. -- Procedure: joystick-name [n] Return the (strin