diff options
| -rw-r--r-- | doc/api.texi | 1133 |
1 files changed, 1128 insertions, 5 deletions
diff --git a/doc/api.texi b/doc/api.texi index 0d66e7d..170fefd 100644 --- a/doc/api.texi +++ b/doc/api.texi @@ -57,9 +57,174 @@ initialized. @node Windows @subsection Windows +@deffn {Scheme Procedure} make-window [#:title "Guile SDL2 Window"] @ + [#:position (#f #f)] @ + [#:size (640 480)] @ + [#:maximize? #f] @ + [#:minimize? #f] @ + [#:opengl? #f] @ + [#:border? #t] @ + [#:fullscreen? #f] @ + [#:fullscreen-desktop? #f] @ + [#:grab-input? #f] @ + [#:high-dpi? #f] +Create a new window named @var{title} with dimensions @var{size} located +at @var{position} on the display. @var{position} and @var{size} are +two-element lists in the form @code{(x y)}, where each coordinate is +measured in pixels. In the case of @var{position}, a coordinate may use +the special symbol @var{center} to indicate that the window should be +centered on that axis, or @code{#f} to indicate that it does not matter +where the window is located on that axis. +@end deffn + +@deffn {Scheme Procedure} close-window! window +Close @var{window}. +@end deffn + +@deffn {Scheme Procedure} call-with-window window proc +Call @var{proc} with @var{window}, an SDL window object, and close it +when @var{proc} returns or otherwise exits. +@end deffn + +@deffn {Scheme Procedure} window-title window +Return the title for @var{window}. +@end deffn + +@deffn {Scheme Procedure} window-size window +Return the dimensions of @var{window}. +@end deffn + +@deffn {Scheme Procedure} window-position window +Return the position of @var{window} on the display. +@end deffn + +@deffn {Scheme Procedure} window-id window +Return the numeric ID of @var{window}. +@end deffn + +@deffn {Scheme Procedure} id->window id +Return the window corresponding to @var{ID}, a positive integer, or +@code{#f} if there is no such window. +@end deffn + +@deffn {Scheme Procedure} hide-window! window +Hide @var{window}. +@end deffn + +@deffn {Scheme Procedure} show-window! window +Show @var{window} and focus on it. +@end deffn + +@deffn {Scheme Procedure} maximize-window! window +Make @var{window} as large as possible. +@end deffn + +@deffn {Scheme Procedure} minimize-window! window +Shrink @var{window} to an iconic representation. +@end deffn + +@deffn {Scheme Procedure} raise-window! window +Raise @var{window} above all other windows and set input focus. +@end deffn + +@deffn {Scheme Procedure} restore-window! window +Restore the size and position of a minimized or maximized @var{window}. +@end deffn + +@deffn {Scheme Procedure} set-window-border! window border? +When @var{border?}, draw the usual border around @var{window}, otherwise +remove the border. +@end deffn + +@deffn {Scheme Procedure} set-window-title! window title +Set the title of @var{window} to the string @var{title}. +@end deffn + +@deffn {Scheme Procedure} set-window-position! window position +Set the position of @var{window} to @var{position}, a two-element list +of (x,y) coordinates measured in pixels. +@end deffn + +@deffn {Scheme Procedure} set-window-size! window size +Set the dimensions of @var{window} to @var{size}, a two-element list of +(width,height) coordinates measured in pixels. +@end deffn + +@deffn {Scheme Procedure} set-window-fullscreen! window fullscreen? [#:desktop?] +Toggle fullscreen mode on/off for @var{window}. If @var{fullscreen?}, +fullscreen mode is activated, otherwise it is deactivated. If +@var{fullscreen?} and @var{desktop?}, a special "fake" fullscreen mode +is used that takes the size of the desktop. +@end deffn + @node OpenGL @subsection OpenGL +@deffn {Scheme Procedure} make-gl-context window +Create an OpenGL context for @var{window}. +@end deffn + +@deffn {Scheme Procedure} delete-gl-context! context +Delete @var{context}, an OpenGL context object. +@end deffn + +@deffn {Scheme Procedure} call-with-gl-context window proc +Call @var{proc} with a new OpenGL context created for @var{window}, and +close the context when @var{proc} returns or otherwise exits. +@end deffn + +@deffn {Scheme Procedure} swap-gl-window window +Update @var{window} with OpenGL rendering. +@end deffn + +@deffn {Scheme Procedure} set-gl-attribute! attr value +Set the OpenGL attribute represented by the symbol @var{attr} to +@var{value}. Possible values for @var{attr} are: + +@itemize +@item @code{red-size} +@item @code{green-size} +@item @code{blue-size} +@item @code{alpha-size} +@item @code{buffer-size} +@item @code{double-buffer} +@item @code{depth-size} +@item @code{stencil-size} +@item @code{accum-red-size} +@item @code{accum-green-size} +@item @code{accum-blue-size} +@item @code{stereo} +@item @code{multisample-buffers} +@item @code{multisample-samples} +@item @code{retained-backing} +@item @code{context-major-version} +@item @code{context-minor-version} +@item @code{context-egl} +@item @code{context-flags} +@item @code{context-profile-mask} +@item @code{share-with-current-context} +@item @code{framebuffer-srgb-capable} +@end itemize + +@end deffn + +@deffn {Scheme Procedure} set-gl-swap-interval! interval +Set the framebuffer swap interval for the current OpenGL context to the +type indicated by the symbol @var{interval}. Possible values of +@var{interval} are: + +@itemize +@item @code{immediate}, for immediate updates +@item @code{vsync}, for updates synchronized with the screen's vertical retrace +@item @code{late-swap-tear}, for late swap tearing +@end itemize + +Late swap tearing works the same as vsync, but if the vertical retrace +has been missed for a given frame, buffers are swapped immediately, +which might be less jarring for the user during occasional framerate +drops. +@end deffn + @node Input @section Input @@ -73,9 +238,41 @@ initialized. @node Keyboard @subsection Keyboard +@example +(use-modules (sdl2 input keyboard)) +@end example + +@deffn {Scheme Procedure} key-pressed? key +Return @code{#t} if @var{key} is currently being pressed. +@end deffn + +@deffn {Scheme Procedure} key-released? key +Return @code{#t} is @var{key} is not currently being pressed. +@end deffn + @node Mouse @subsection Mouse +@example +(use-modules (sdl2 input mouse)) +@end example + +@deffn {Scheme Procedure} mouse-x +Return the x coordinate of the mouse cursor. +@end deffn + +@deffn {Scheme Procedure} mouse-y +Return the y coordinate of the mouse cursor. +@end deffn + +@deffn {Scheme Procedure} mouse-button-pressed? button +Return @code{#t} if @var{button} is currently being pressed. +@end deffn + +@deffn {Scheme Procedure} mouse-button-released? button +Return @code{#t} if @var{button} is not currently being pressed. +@end deffn + @node Joysticks @subsection Joysticks @@ -83,6 +280,45 @@ initialized. (use-modules (sdl2 input joystick)) @end example +@deffn {Scheme Procedure} num-joysticks +Return the current number of connected joystick devices. +@end deffn + +@deffn {Scheme Procedure} open-joystick device-index +Return a joystick object for the physical joystick device associated +with @var{device-index}. +@end deffn + +@deffn {Scheme Procedure} close-joystick joystick +Close @var{joystick}. +@end deffn + +@deffn {Scheme Procedure} joystick-instance-id joystick +Return the instance id of @var{joystick}. +@end deffn + +@deffn {Scheme Procedure} joystick-power-level joystick +Return the symbolic battery power level for @var{joystick}, either +@code{unknown}, @code{empty}, @code{low}, @code{medium}, @code{full}, +or @code{wired}. +@end deffn + +@deffn {Scheme Procedure} joystick-num-axes joystick +Return the number of axes for @var{joystick}. +@end deffn + +@deffn {Scheme Procedure} joystick-num-balls joystick +Return the number of balls for @var{joystick}. +@end deffn + +@deffn {Scheme Procedure} joystick-num-buttons joystick +Return the number of buttons for @var{joystick}. +@end deffn + +@deffn {Scheme Procedure} joystick-num-hats joystick +Return the number of hats for @var{joystick}. +@end deffn + @node Game Controllers @subsection Game Controllers @@ -90,6 +326,81 @@ initialized. (use-modules (sdl2 input game-controller)) @end example +@deffn {Scheme Procedure} load-game-controller-mappings! file +Load game controller mapping from @var{file} and return the number of +mappings added this way. + +See @url{https://raw.github.com/gabomdq/SDL_GameControllerDB/master/gamecontrollerdb.txt} +for a community maintained controller mapping file. +@end deffn + +@deffn {Scheme Procedure} open-game-controller joystick-index +Return a game controller object for the physical joystick device associated +with the @var{joystick-index}. +@end deffn + +@deffn {Scheme Procedure} close-game-controller controller +Close @var{controller}. +@end deffn + +@deffn {Scheme Procedure} game-controller? controller +Close @var{controller}. +@end deffn + +@deffn {Scheme Procedure} game-controller-attached? controller +Return @code{#t} if @var{controller} is currently in use. +@end deffn + +@deffn {Scheme Procedure} game-controller-joystick controller +Return the underlying joystick object associated with @var{controller}. +@end deffn + +@deffn {Scheme Procedure} game-controller-name controller +Return the human readable name for @var{controller}. +@end deffn + +@deffn {Scheme Procedure} game-controller-axis controller axis +Return a number in the range [-32768, 32767] representing the +current state of @var{axis} on @var{controller}. + +@var{axis} may be one of the following symbols: +@itemize +@item @code{left-x} +@item @code{left-y} +@item @code{right-x} +@item @code{right-y} +@item @code{trigger-left} +@item @code{trigger-right} +@end itemize +@end deffn + +@deffn {Scheme Procedure} game-controller-button-pressed? controller button +Return @code{#t} if @var{button} is pressed on @var{controller}. + +@var{button} may be one of the following symbols: +@itemize +@item @code{a} +@item @code{b} +@item @code{x} +@item @code{y} +@item @code{back} +@item @code{guide} +@item @code{start} +@item @code{left-stick} +@item @code{right-stick} +@item @code{left-shoulder} +@item @code{right-shoulder} +@item @code{dpad-up} +@item @code{dpad-down} +@item @code{dpad-left} +@item @code{dpad-right} +@end itemize +@end deffn + +@deffn {Scheme Procedure} game-controller-index? joystick-index +Return @code{#t} if @var{joystick-index} is a valid game controller index. +@end deffn + @node Events @section Events @@ -97,37 +408,849 @@ initialized. (use-modules (sdl2 events)) @end example +@deffn {Scheme Procedure} make-quit-event timestamp +@end deffn + +@deffn {Scheme Procedure} quit-event? e +Return @code{#t} if @var{e} is a quit event. +@end deffn + +@deffn {Scheme Procedure} quit-event-timestamp e +@end deffn + +@deffn {Scheme Procedure} make-window-event timestamp window-id type vector +@end deffn + +@deffn {Scheme Procedure} window-event? e +Return @code{#t} if @var{e} is a window event. +@end deffn + +@deffn {Scheme Procedure} window-shown-event? e +Return @code{#t} if @var{e} is a window shown event. +@end deffn + +@deffn {Scheme Procedure} window-hidden-event? e +Return @code{#t} if @var{e} is a window hidden event. +@end deffn + +@deffn {Scheme Procedure} window-exposed-event? e +Return @code{#t} if @var{e} is a window exposed event. +@end deffn + +@deffn {Scheme Procedure} window-moved-event? e +Return @code{#t} if @var{e} is a window moved event. +@end deffn + +@deffn {Scheme Procedure} window-resized-event? e +Return @code{#t} if @var{e} is a window resized event. +@end deffn + +@deffn {Scheme Procedure} window-size-changed-event? e +Return @code{#t} if @var{e} is a window size changed event. +@end deffn + +@deffn {Scheme Procedure} window-minimized-event? e +Return @code{#t} if @var{e} is a window minimized event. +@end deffn + +@deffn {Scheme Procedure} window-maximized-event? e +Return @code{#t} if @var{e} is a window maximized event. +@end deffn + +@deffn {Scheme Procedure} window-restored-event? e +Return @code{#t} if @var{e} is a window restored event. +@end deffn + +@deffn {Scheme Procedure} window-enter-event? e +Return @code{#t} if @var{e} is a window enter event. +@end deffn + +@deffn {Scheme Procedure} window-leave-event? e +Return @code{#t} if @var{e} is a window leave event. +@end deffn + +@deffn {Scheme Procedure} window-focus-gained-event? e +Return @code{#t} if @var{e} is a window focus gained event. +@end deffn + +@deffn {Scheme Procedure} window-focus-lost-event? e +Return @code{#t} if @var{e} is a window focus lost event. +@end deffn + +@deffn {Scheme Procedure} window-closed-event? e +Return @code{#t} if @var{e} is a window closed event. +@end deffn + +@deffn {Scheme Procedure} window-event-timestamp e +@end deffn + +@deffn {Scheme Procedure} window-event-window-id e +@end deffn + +@deffn {Scheme Procedure} window-event-type e +@end deffn + +@deffn {Scheme Procedure} window-event-vector e +@end deffn + +@deffn {Scheme Procedure} make-keyboard-event timestamp @ + window-id @ + pressed? @ + repeat? @ + key @ + scancode @ + modifiers +@end deffn + +@deffn {Scheme Procedure} keyboard-event? e +Return @code{#t} if @var{e} is a keyboard event. +@end deffn + +@deffn {Scheme Procedure} keyboard-down-event? e +Return @code{#t} if @var{e} is a key press event. +@end deffn + +@deffn {Scheme Procedure} keyboard-up-event? e +Return @code{#t} if @var{e} is a key release event. +@end deffn + +@deffn {Scheme Procedure} keyboard-event-timestamp e +@end deffn + +@deffn {Scheme Procedure} keyboard-event-window-id e +@end deffn + +@deffn {Scheme Procedure} keyboard-event-pressed? e +@end deffn + +@deffn {Scheme Procedure} keyboard-event-repeat? e +@end deffn + +@deffn {Scheme Procedure} keyboard-event-key e +@end deffn + +@deffn {Scheme Procedure} keyboard-event-scancode e +@end deffn + +@deffn {Scheme Procedure} keyboard-event-modifiers e +@end deffn + +@deffn {Scheme Procedure} make-text-input-event timestamp window-id text +@end deffn + +@deffn {Scheme Procedure} text-input-event? e +Return @code{#t} if @var{e} is a text input event. +@end deffn + +@deffn {Scheme Procedure} text-input-event-timestamp e +@end deffn + +@deffn {Scheme Procedure} text-input-event-window-id e +@end deffn + +@deffn {Scheme Procedure} text-input-event-text e +@end deffn + +@deffn {Scheme Procedure} make-mouse-button-event timestamp @ + window-id @ + which @ + button @ + pressed? @ + clicks @ + x @ + y +@end deffn + +@deffn {Scheme Procedure} mouse-button-event? e +Return @code{#t} if @var{e} is a mouse button event. +@end deffn + +@deffn {Scheme Procedure} mouse-button-down-event? e +Return @code{#t} if @var{e} is a mouse button down event. +@end deffn + +@deffn {Scheme Procedure} mouse-button-up-event? e +Return @code{#t} if @var{e} is a mouse button up event. +@end deffn + +@deffn {Scheme Procedure} mouse-button-event-timestamp e +@end deffn + +@deffn {Scheme Procedure} mouse-button-event-window-id e +@end deffn + +@deffn {Scheme Procedure} mouse-button-event-which e +@end deffn + +@deffn {Scheme Procedure} mouse-button-event-button e +@end deffn + +@deffn {Scheme Procedure} mouse-button-event-pressed? e +@end deffn + +@deffn {Scheme Procedure} mouse-button-event-clicks e +@end deffn + +@deffn {Scheme Procedure} mouse-button-event-x e +@end deffn + +@deffn {Scheme Procedure} mouse-button-event-y e +@end deffn + +@deffn {Scheme Procedure} make-mouse-motion-event timestamp @ + window-id @ + which @ + buttons @ + x @ + y @ + x-rel @ + y-rel +@end deffn + +@deffn {Scheme Procedure} mouse-motion-event? e +Return @code{#t} if @var{e} is a mouse motion event. +@end deffn + +@deffn {Scheme Procedure} mouse-motion-event-timestamp e +@end deffn + +@deffn {Scheme Procedure} mouse-motion-event-window-id e +@end deffn + +@deffn {Scheme Procedure} mouse-motion-event-which e +@end deffn + +@deffn {Scheme Procedure} mouse-motion-event-buttons e +@end deffn + +@deffn {Scheme Procedure} mouse-motion-event-x e +@end deffn + +@deffn {Scheme Procedure} mouse-motion-event-y e +@end deffn + +@deffn {Scheme Procedure} mouse-motion-event-x-rel e +@end deffn + +@deffn {Scheme Procedure} mouse-motion-event-y-rel e +@end deffn + +@deffn {Scheme Procedure} make-joystick-axis-event timestamp which axis value +@end deffn + +@deffn {Scheme Procedure} joystick-axis-event? e +Return @code{#t} if @var{e} is a joystick axis event. +@end deffn + +@deffn {Scheme Procedure} joystick-axis-event-timestamp e +@end deffn + +@deffn {Scheme Procedure} joystick-axis-event-which e +@end deffn + +@deffn {Scheme Procedure} joystick-axis-event-button e +@end deffn + +@deffn {Scheme Procedure} joystick-axis-event-pressed? e +@end deffn + +@deffn {Scheme Procedure} make-joystick-ball-event timestamp @ + which @ + ball @ + x-rel @ + y-rel +@end deffn + +@deffn {Scheme Procedure} joystick-ball-event? e +Return @code{#t} if @var{e} is a joystick ball event. +@end deffn + +@deffn {Scheme Procedure} joystick-ball-event-timestamp e +@end deffn + +@deffn {Scheme Procedure} joystick-ball-event-which e +@end deffn + +@deffn {Scheme Procedure} joystick-ball-event-ball e +@end deffn + +@deffn {Scheme Procedure} joystick-ball-event-x-rel e +@end deffn + +@deffn {Scheme Procedure} joystick-ball-event-y-rel e +@end deffn + +@deffn {Scheme Procedure} make-joystick-hat-event timestamp which hat value +@end deffn + +@deffn {Scheme Procedure} joystick-hat-event? e +Return @code{#t} if @var{e} is a joystick hat event. +@end deffn + +@deffn {Scheme Procedure} joystick-hat-event-timestamp e +@end deffn + +@deffn {Scheme Procedure} joystick-hat-event-which e +@end deffn + +@deffn {Scheme Procedure} joystick-hat-event-hat e +@end deffn + +@deffn {Scheme Procedure} joystick-hat-event-value e +@end deffn + +@deffn {Scheme Procedure} make-joystick-device-event timestamp which action +@end deffn + +@deffn {Scheme Procedure} joystick-device-event? e +Return @code{#t} if @var{e} is a joystick device event. +@end deffn + +@deffn {Scheme Procedure} joystick-device-event-timestamp e +@end deffn + +@deffn {Scheme Procedure} joystick-device-event-which e +@end deffn + +@deffn {Scheme Procedure} joystick-device-event-action e +@end deffn + +@deffn {Scheme Procedure} make-controller-axis-event timestamp which axis value +@end deffn + +@deffn {Scheme Procedure} controller-axis-event? e +Return @code{#t} if @var{e} is a game controller axis event. +@end deffn + +@deffn {Scheme Procedure} controller-axis-event-timestamp e +@end deffn + +@deffn {Scheme Procedure} controller-axis-event-which e +@end deffn + +@deffn {Scheme Procedure} controller-axis-event-axis e +@end deffn + +@deffn {Scheme Procedure} controller-axis-event-value e +@end deffn + +@deffn {Scheme Procedure} make-controller-button-event timestamp @ + which @ + button @ + pressed? +@end deffn + +@deffn {Scheme Procedure} controller-button-event? e +Return @code{#t} if @var{event} is a game controller button event. +@end deffn + +@deffn {Scheme Procedure} controller-button-down-event? e +@end deffn + +@deffn {Scheme Procedure} controller-button-up-event? e +@end deffn + +@deffn {Scheme Procedure} controller-button-event-timestamp e +@end deffn + +@deffn {Scheme Procedure} controller-button-event-which e +@end deffn + +@deffn {Scheme Procedure} controller-button-event-button e +@end deffn + +@deffn {Scheme Procedure} controller-button-event-pressed? e +@end deffn + +@deffn {Scheme Procedure} make-controller-device-event timestamp which action +@end deffn + +@deffn {Scheme Procedure} controller-device-event? e +Return @code{#t} if @var{event} is a game controller device event. +@end deffn + +@deffn {Scheme Procedure} controller-added-event? e +Return @code{#t} if @var{event} is a game controller device event with the +'added' action. +@end deffn + +@deffn {Scheme Procedure} controller-removed-event? e +Return @code{#t} if @var{event} is a game controller device event with the +'removed' action. +@end deffn + +@deffn {Scheme Procedure} controller-remapped-event? e +Return @code{#t} if @var{event} is a game controller device event with the +'remapped' action. +@end deffn + +@deffn {Scheme Procedure} controller-device-event-timestamp e +@end deffn + +@deffn {Scheme Procedure} controller-device-event-which e +@end deffn + +@deffn {Scheme Procedure} controller-device-event-action e +@end deffn + +@deffn {Scheme Procedure} poll-event +@end deffn + @node Surfaces @section Surfaces @example -(use-modules (sdl2 input surface)) +(use-modules (sdl2 surface)) @end example +@deffn {Scheme Procedure} color? c +Return @code{#t} if @var{c} is a color. +@end deffn + +@deffn {Scheme Procedure} color-r c +@end deffn + +@deffn {Scheme Procedure} color-g c +@end deffn + +@deffn {Scheme Procedure} color-b c +@end deffn + +@deffn {Scheme Procedure} color-a c +@end deffn + +@deffn {Scheme Procedure} palette? p +Return @code{#t} if @var{p} is a palette. +@end deffn + +@deffn {Scheme Procedure} palette-length palette +Return the number of colors in @var{palette}. +@end deffn + +@deffn {Scheme Procedure} palette-colors palette +Return the colors in @var{palette}. +@end deffn + +@deffn {Scheme Procedure} pixel-format? pf +Return @code{#t} if @var{pf} is a pixel format. +@end deffn + +@deffn {Scheme Procedure} pixel-format-name pf +Return the symbolic name of the pixel format @var{pf}. +@end deffn + +@deffn {Scheme Procedure} pixel-format-palette pf +Return the palette for the pixel format @var{pf}. +@end deffn + +@deffn {Scheme Procedure} pixel-format-bits-per-pixel pf +Return the number of bits per pixel for the pixel format @var{pf}. +@end deffn + +@deffn {Scheme Procedure} pixel-format-bytes-per-pixel pf +Return the number of bytes per pixel for the pixel format @var{pf}. +@end deffn + +@deffn {Scheme Procedure} pixel-format-red-mask pf +Return the bitmask for the red component of a pixel in the pixel format +@var{pf}. +@end deffn + +@deffn {Scheme Procedure} pixel-format-green-mask pf +Return the bitmask for the green component of a pixel in the pixel format +@var{pf}. +@end deffn + +@deffn {Scheme Procedure} pixel-format-blue-mask pf +Return the bitmask for the blue component of a pixel in the pixel format +@var{pf}. +@end deffn + +@deffn {Scheme Procedure} pixel-format-alpha-mask pf +Return the bitmask for the alpha component of a pixel in the pixel format +@var{pf}. +@end deffn + +@deffn {Scheme Procedure} make-rgb-surface width height depth +Create a new SDL surface with the dimensions @var{width} and @var{height} and +@var{depth} bits per pixel. +@end deffn + +@deffn {Scheme Procedure} bytevector->surface bv width height depth pitch +Convert @var{bv}, a bytevector of pixel data with dimensions +@var{width}x@var{height}, to an SDL surface. Each pixel is @var{depth} bits in +size, and each row of pixels is @var{pitch} bytes in size. +@end deffn + +@deffn {Scheme Procedure} delete-surface! surface +Free the memory used by @var{surface}. +@end deffn + +@deffn {Scheme Procedure} call-with-surface surface proc +Call @var{proc}, passing it @var{surface} and deleting @var{surface} upon exit +of @var{proc}. +@end deffn + +@deffn {Scheme Procedure} load-bmp file +Create a new surface from the bitmap data in @var{file}. +@end deffn + +@deffn {Scheme Procedure} surface-width surface +Return the width of @var{surface} in pixels. +@end deffn + +@deffn {Scheme Procedure} surface-height surface +Return the height of @var{surface} in pixels. +@end deffn + +@deffn {Scheme Procedure} surface-pitch surface +Return the length of a row of pixels in @var{surface} in bytes. +@end deffn + +@deffn {Scheme Procedure} surface-pixels surface +Return a bytevector containing the raw pixel data in @var{surface}. +@end deffn + +@deffn {Scheme Procedure} surface-pixel-format surface +Return the pixel format for @var{surface}. +@end deffn + +@deffn {Scheme Procedure} convert-surface-format surface format +Convert the pixels in @var{surface} to @var{format}, a symbol representing a +specific pixel format, and return a new surface object. + +Valid format types are: + +@itemize +@item @code{index1lsb} +@item @code{index1msb} +@item @code{index4lsb} +@item @code{index4msb} +@item @code{index8} +@item @code{rgb332} +@item @code{rgb444} +@item @code{rgb555} +@item @code{bgr555} +@item @code{argb4444} +@item @code{rgba4444} +@item @code{abgr4444} +@item @code{bgra4444} +@item @code{argb1555} +@item @code{rgba5551} +@item @code{abgr1555} +@item @code{bgra5551} +@item @code{rgb565} +@item @code{bgr565} +@item @code{rgb24} +@item @code{bgr24} +@item @code{rgb888} +@item @code{rgbx8888} +@item @code{bgr888} +@item @code{bgrx8888} +@item @code{argb8888} +@item @code{rgba8888} +@item @code{abgr8888} +@item @code{bgra8888} +@item @code{argb2101010} +@item @code{yv12} +@item @code{iyuv} +@item @code{yuy2} +@item @code{uyvy} +@item @code{yvyu} +@end itemize +@end deffn + @node Rendering @section Rendering @example -(use-modules (sdl2 input render)) +(use-modules (sdl2 render)) @end example +@deffn {Scheme Procedure} make-renderer window @ + [#:optional flags='(accelerated vsync)] +Return a new renderer for @var{window} created with the options specified +in @var{flags}, a list of symbols. The valid symbols that may appear in +@var{flags} are: + +@itemize +@item software, to use a software renderer fallback +@item accelerated, to use hardware acceleration +@item vsync, to synchronize rendering with the monitor's refresh rate +@item texture, for render to texture support +@end itemize +@end deffn + +@deffn {Scheme Procedure} renderer? r +Return @code{#t} if @var{r} is a renderer. +@end deffn + +@deffn {Scheme Procedure} delete-renderer! renderer +Delete the rendering context @var{renderer}. +@end deffn + +@deffn {Scheme Procedure} call-with-renderer renderer proc +Call @var{proc}, passing it @var{renderer} and closing @var{renderer} upon exit +of @var{proc}. +@end deffn + +@deffn {Scheme Procedure} clear-renderer renderer +Clear the rendering target @var{renderer} with the current drawing color. +@end deffn + +@deffn {Scheme Procedure} present-renderer renderer +Display @var{renderer}. +@end deffn + +@deffn {Scheme Procedure} render-copy renderer @ + texture @ + [#:srcrect] + [#:dstrect] +Copy @var{texture} to the rendering target of @var{renderer}. +@end deffn + +@deffn {Scheme Procedure} surface->texture renderer surface +Convert @var{surface} to a texture suitable for @var{renderer}. +@end deffn + @node Images @section Images @example -(use-modules (sdl2 input image)) +(use-modules (sdl2 image)) @end example +@deffn {Scheme Procedure} image-init +Initialize dynamically loaded image libraries. +@end deffn + +@deffn {Scheme Procedure} image-quit +Clean up dynamically loaded image libraries. +@end deffn + +@deffn {Scheme Procedure} load-image file +Load the image in @var{file} and return an SDL surface. +@end deffn + +@deffn {Scheme Procedure} save-png surface file +Save @var{surface} to @var{file} as a PNG formatted image. +@end deffn + @node Sound @section Sound @example -(use-modules (sdl2 input mixer)) +(use-modules (sdl2 mixer)) @end example +@defvr {Scheme Variable} %default-frequency +@end defvr + +@defvr {Scheme Variable} %default-format +@end defvr + +@defvr {Scheme Variable} %default-chunk-size +@end defvr + +@deffn {Scheme Procedure} mixer-init [#:optional formats='(flac mod modplug mp3 ogg fluidsynth)] +Initialize mixer library with support for @var{formats}, a list of +symbols representing audio file formats. Possible formats are: + +@itemize +@item flac +@item mod +@item modplug +@item mp3 +@item ogg +@item fluidsynth +@end itemize +@end deffn + +@deffn {Scheme Procedure} mixer-quit +Shutdown mixer library. +@end deffn + +@deffn {Scheme Procedure} open-audio [#:frequency=%default-frequency] @ + [#:format=%default-format] @ + [#:stereo?=#t] @ + [#:chunk-size=%default-chunk-size] +Initialize the mixer API. @var{frequency} specificies the sample rate in +hertz. When @var{stereo?} is @code{#t}, two output channels are used, otherwise +mono output is used instead. @var{chunk-size} specifies the number of bytes +used per output sample. @var{format} is a symbol that specifies the output +sample format. Possible values are: + +@itemize +@item u8 +@item s8 +@item u16lsb +@item s16lsb +@item u16msb +@item s16msb +@item u16 +@item s16 +@item s32lsb +@item s32msb +@item s32 +@item f32lsb +@item f32msb +@item f32 +@end itemize +@end deffn + +@deffn {Scheme Procedure} close-audio +Shut down the mixer API. +@end deffn + +@deffn {Scheme Procedure} chunk? c +Return @code{#t} if @var{c} is a chunk. +@end deffn + +@deffn {Scheme Procedure} load-chunk file +Load the audio data in @var{file} and return an audio chunk. +@end deffn + +@deffn {Scheme Procedure} delete-chunk! chunk +Free the memory used for @var{chunk}. +@end deffn + +@deffn {Scheme Procedure} set-chunk-volume! chunk volume +Set the loudness of @var{chunk} to @var{volume}, an integer in the range +[0,128]. Return the previous chunk volume setting. +@end deffn + +@deffn {Scheme Procedure} play-chunk! chunk @ + [#:loops=0] @ + [#:channel] +Play @var{chunk} on @var{channel}, an integer channel identifier or @code{#f} +to use the first unreserved audio channel. @var{chunk} will play @var{loops} + +1 times. Return the channel identifier that @var{chunk} is played on. +@end deffn + +@deffn {Scheme Procedure} set-channel-volume! channel volume +Set the loudness of @var{channel}, an integer channel identifier or @code{#f} +for all channels, to @var{volume}, an integer in the range [0,128]. Return +the previous volume of @var{channel}, or the average of all channels if +@var{channel} is @code{#f}. +@end deffn + +@deffn {Scheme Procedure} pause-channel! channel +Pause playback on @var{channel}, an integer channel identifier, or @code{#f} to +pause all channels. +@end deffn + +@deffn {Scheme Procedure} resume-channel! channel +Resume playback on @var{channel}, an integer channel identifier, or @code{#f} to +resume all channels. +@end deffn + +@deffn {Scheme Procedure} stop-channel! channel +Halt playback on @var{channel}, an integer channel identifier, or @code{#f} to +halt all channels. +@end deffn + +@deffn {Scheme Procedure} channel-playing? channel +Return @code{#t} if @var{channel} is playing. +@end deffn + +@deffn {Scheme Procedure} playing-channels-count +Return the number of channels currently playing. +@end deffn + +@deffn {Scheme Procedure} channel-paused? channel +Return @code{#t} if @var{channel} is paused. +@end deffn + +@deffn {Scheme Procedure} paused-channels-count +Return the number of channels that are paused. +@end deffn + +@deffn {Scheme Procedure} music? m +Return @code{#t} if @var{m} is music. +@end deffn + +@deffn {Scheme Procedure} load-music file +Load music from @var{file}. +@end deffn + +@deffn {Scheme Procedure} delete-music! music +Delete the memory used for @var{music}. +@end deffn + +@deffn {Scheme Procedure} play-music! music [#:optional loops=1] +Play @var{music}, repeated @var{loops} times. @var{loops} may be @code{#f}, in +which case the music loops indefinitely. +@end deffn + +@deffn {Scheme Procedure} set-music-volume! volume +Set music loudness to @var{volume}, an integer in the range [0,128]. Return the +previous volume. +@end deffn + +@deffn {Scheme Procedure} music-volume +Return the music volume. +@end deffn + +@deffn {Scheme Procedure} pause-music! +Puase the music. +@end deffn + +@deffn {Scheme Procedure} resume-music! +Resume music playback. +@end deffn + +@deffn {Scheme Procedure} rewind-music! +Start music playback from the beginning. Rewinding is only supported for MOD, +OGG, MP3, and native MIDI music. +@end deffn + +@deffn {Scheme Procedure} stop-music! +Halt music playback. +@end deffn + +@deffn {Scheme Procedure} music-playing? +Return @code{#t} if music is currently playing. +@end deffn + +@deffn {Scheme Procedure} music-paused? +Return @code{#t} if music is currently paused. +@end deffn + @node Fonts @section Fonts @example -(use-modules (sdl2 input ttf)) +(use-modules (sdl2 ttf)) @end example + +@deffn {Scheme Procedure} ttf-init +Initialize the TTF system. +@end deffn + +@deffn {Scheme Procedure} ttf-quit +Shut down and clean up the TTF system. +@end deffn + +@deffn {Scheme Procedure} load-font file point-size +Load TTF font from @var{file} and return a new font object whose glyph size is +@var{point-size}. +@end deffn + +@deffn {Scheme Procedure} delete-font! font +Delete the memory allocated for @var{font}. +@end deffn + +@deffn {Scheme Procedure} font-height font +Return the maximum height of @var{font}. +@end deffn + +@deffn {Scheme Procedure} render-font-solid font text color +Render @var{text}, a UTF-8 encoded string, using @var{font} and @var{color}, the +foreground color, and return a surface containing the results. +@end deffn + +@deffn {Scheme Procedure} render-font-blended font text color +Render @var{text}, a UTF-8 encoded string, using @var{font} and @var{color}, the +foreground color, and return a high-quality alpha-blended surface containing the +results. +@end deffn |