path: root/doc/api.texi

@menu
* Basics::                      Initialization and other basic things.
* Window Management::           Working with the window system.
* Input::                       Keyboard, mouse, joystick input.
* Events::                      Asynchronous event handling.
* Rects::                       2D rectangles.
* Surfaces::                    Software rendering.
* Rendering::                   Hardware accelerated rendering.
* Blend Modes::                 Color blending.
* Images::                      Loading and saving images.
* Sound::                       Sound effects and music.
* Fonts::                       Truetype and bitmap font rendering.
* Hints::                       Getting and setting configuration hints.
@end menu

@node Basics
@section Basics

@example
(use-modules (sdl2))
@end example

@deffn {Procedure} sdl-init [@var{subsystems}]
Initialize the SDL library.  This must be called before using any
other SDL procedure.

@var{subsystems} is an optional list of symbols that specifies the
subsystems to initialize.  All subsystems are initialized by default.
The possible flags are @code{timer}, @code{audio}, @code{video},
@code{haptic}, @code{game-controller}, and @code{events}.
@end deffn

@deffn {Procedure} sdl-quit
Quit all activated SDL subsystems.  This procedure should be called
upon all exit conditions.
@end deffn

@deffn {Procedure} sdl-version
Return a three element list containing the major, minor, and patch
version of the linked SDL library.
@end deffn

@deffn {Procedure} sdl-ticks
Return the number of milliseconds since the SDL library was
initialized.
@end deffn

@deffn {Procedure} sdl-performance-counter
Return the current value of the high resolution counter.
@end deffn

@deffn {Procedure} sdl-performance-frequency
Return the count per second of the high resolution counter.
@end deffn

@node Window Management
@section Window Management

@menu
* Windows::                     Window manipulation.
* OpenGL::                      OpenGL contexts.
@end menu

@example
(use-modules (sdl2 video))
@end example

@node Windows
@subsection Windows

@deffn {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 {Procedure} close-window! window
Close @var{window}.
@end deffn

@deffn {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 {Procedure} window-title window
Return the title for @var{window}.
@end deffn

@deffn {Procedure} window-size window
Return 2 values for the dimensions of @var{window}.
@end deffn

@deffn {Procedure} window-minimum-size window
Return 2 values for the minimal dimensions that @var{window} can be.
Note that SDL does not always enforce this restriction, so you might
end up with a window size that is actually smaller than the value
returned by this procedure.
@end deffn

@deffn {Procedure} window-maximum-size window
Return 2 values for the maximum dimensions that @var{window} can be.
@end deffn

@deffn {Procedure} window-position window
Return 2 values for the position of @var{window} on the display.
@end deffn

@deffn {Procedure} window-id window
Return the numeric ID of @var{window}.
@end deffn

@deffn {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 {Procedure} hide-window! window
Hide @var{window}.
@end deffn

@deffn {Procedure} show-window! window
Show @var{window} and focus on it.
@end deffn

@deffn {Procedure} maximize-window! window
Make @var{window} as large as possible.
@end deffn

@deffn {Procedure} minimize-window! window
Shrink @var{window} to an iconic representation.
@end deffn

@deffn {Procedure} raise-window! window
Raise @var{window} above all other windows and set input focus.
@end deffn

@deffn {Procedure} restore-window! window
Restore the size and position of a minimized or maximized @var{window}.
@end deffn

@deffn {Procedure} set-window-border! window border?
When @var{border?}, draw the usual border around @var{window}, otherwise
remove the border.
@end deffn

@deffn {Procedure} set-window-title! window title
Set the title of @var{window} to the string @var{title}.
@end deffn

@deffn {Procedure} set-window-icon! window icon
Set the icon of @var{window} to the surface @var{icon}.
@end deffn

@deffn {Procedure} set-window-position! window x y
Set the position of @var{window} to (@var{x}, @var{y}).
@end deffn

@deffn {Procedure} set-window-size! window width height
Set the dimensions of @var{window} to @var{width} x @var{height}
pixels.
@end deffn

@deffn {Procedure} set-window-minimum-size! window width height
Set the minimum dimensions of @var{window} to @var{width} x
@var{height} pixels.
@end deffn

@deffn {Procedure} set-window-maximum-size! window width height
Set the maximum dimensions of @var{window} to @var{width} x
@var{height} pixels.
@end deffn

@deffn {Procedure} set-window-resizable! window resizable?
If @var{resizable} is @code{#t}, allow @var{window} to be resized,
otherwise disable resizing.
@end deffn

@deffn {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 {Procedure} make-gl-context window
Create an OpenGL context for @var{window}.
@end deffn

@deffn {Procedure} delete-gl-context! context
Delete @var{context}, an OpenGL context object.
@end deffn

@deffn {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 {Procedure} swap-gl-window window
Update @var{window} with OpenGL rendering.
@end deffn

@deffn {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 {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

@menu
* Keyboard::                    Keyboard input.
* Mouse::                       Mouse input.
* Joysticks::                   Joystick input.
* Game Controllers::            Game controller input.
@end menu

@node Keyboard
@subsection Keyboard

@example
(use-modules (sdl2 input keyboard))
@end example

@deffn {Procedure} key-pressed? key
Return @code{#t} if @var{key} is currently being pressed.
@end deffn

@deffn {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 {Procedure} mouse-x
Return the x coordinate of the mouse cursor.
@end deffn

@deffn {Procedure} mouse-y
Return the y coordinate of the mouse cursor.
@end deffn

@deffn {Procedure} mouse-button-pressed? button
Return @code{#t} if @var{button} is currently being pressed.
@end deffn

@deffn {Procedure} mouse-button-released? button
Return @code{#t} if @var{button} is not currently being pressed.
@end deffn

@deffn {Procedure} make-system-cursor cursor-type
Create a new cursor from the system's available set, chosen by
@var{cursor-type}.  The possible values for @var{cursor-type} are:

@itemize
@item @code{arrow}
@item @code{crosshair}
@item @code{hand}
@item @code{i-beam}
@item @code{size-north-south}
@item @code{size-northwest-southeast}
@item @code{size-northeast-southwest}
@item @code{size-west-east}
@item @code{size-all}
@item @code{no}
@item @code{wait}
@item @code{wait-arrow}
@end itemize

@end deffn

@deffn {Procedure} make-color-cursor surface hot-x hot-y
Create a new cursor from a surface and the given hotspot coordinates
(@var{hot-x}, @var{hot-y}).
@end deffn

@deffn {Procedure} get-cursor
Return the cursor currently in use. The returned cursor object is
internally managed and it's not necessary to call
@code{delete-cursor!} for it.
@end deffn

@deffn {Procedure} set-cursor! cursor
Set the current cursor to @var{cursor}.  If @var{cursor} is @code{#f},
the system default cursor is restored.
@end deffn

@deffn {Procedure} delete-cursor! cursor
Free the memory used by @var{cursor}.  Be careful!
@end deffn

@node Joysticks
@subsection Joysticks

@example
(use-modules (sdl2 input joystick))
@end example

@deffn {Procedure} num-joysticks
Return the current number of connected joystick devices.
@end deffn

@deffn {Procedure} open-joystick device-index
Return a joystick object for the physical joystick device associated
with @var{device-index}.
@end deffn

@deffn {Procedure} close-joystick joystick
Close @var{joystick}.
@end deffn

@deffn {Procedure} joystick-instance-id joystick
Return the instance id of @var{joystick}.
@end deffn

@deffn {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 {Procedure} joystick-num-axes joystick
Return the number of axes for @var{joystick}.
@end deffn

@deffn {Procedure} joystick-num-balls joystick
Return the number of balls for @var{joystick}.
@end deffn

@deffn {Procedure} joystick-num-buttons joystick
Return the number of buttons for @var{joystick}.
@end deffn

@deffn {Procedure} joystick-num-hats joystick
Return the number of hats for @var{joystick}.
@end deffn

@node Game Controllers
@subsection Game Controllers

@example
(use-modules (sdl2 input game-controller))
@end example

@deffn {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 {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 {Procedure} close-game-controller controller
Close @var{controller}.
@end deffn

@deffn {Procedure} game-controller? controller
Close @var{controller}.
@end deffn

@deffn {Procedure} game-controller-attached? controller
Return @code{#t} if @var{controller} is currently in use.
@end deffn

@deffn {Procedure} game-controller-joystick controller
Return the underlying joystick object associated with @var{controller}.
@end deffn

@deffn {Procedure} game-controller-name controller
Return the human readable name for @var{controller}.
@end deffn

@deffn {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 {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 {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

@example
(use-modules (sdl2 events))
@end example

@deffn {Procedure} make-quit-event timestamp
@end deffn

@deffn {Procedure} quit-event? e
Return @code{#t} if @var{e} is a quit event.
@end deffn

@deffn {Procedure} quit-event-timestamp e
@end deffn

@deffn {Procedure} make-window-event timestamp window-id type vector
@end deffn

@deffn {Procedure} window-event? e
Return @code{#t} if @var{e} is a window event.
@end deffn

@deffn {Procedure} window-shown-event? e
Return @code{#t} if @var{e} is a window shown event.
@end deffn

@deffn {Procedure} window-hidden-event? e
Return @code{#t} if @var{e} is a window hidden event.
@end deffn

@deffn {Procedure} window-exposed-event? e
Return @code{#t} if @var{e} is a window exposed event.
@end deffn

@deffn {Procedure} window-moved-event? e
Return @code{#t} if @var{e} is a window moved event.
@end deffn

@deffn {Procedure} window-resized-event? e
Return @code{#t} if @var{e} is a window resized event.
@end deffn

@deffn {Procedure} window-size-changed-event? e
Return @code{#t} if @var{e} is a window size changed event.
@end deffn

@deffn {Procedure} window-minimized-event? e
Return @code{#t} if @var{e} is a window minimized event.
@end deffn

@deffn {Procedure} window-maximized-event? e
Return @code{#t} if @var{e} is a window maximized event.
@end deffn

@deffn {Procedure} window-restored-event? e
Return @code{#t} if @var{e} is a window restored event.
@end deffn

@deffn {Procedure} window-enter-event? e
Return @code{#t} if @var{e} is a window enter event.
@end deffn

@deffn {Procedure} window-leave-event? e
Return @code{#t} if @var{e} is a window leave event.
@end deffn

@deffn {Procedure} window-focus-gained-event? e
Return @code{#t} if @var{e} is a window focus gained event.
@end deffn

@deffn {Procedure} window-focus-lost-event? e
Return @code{#t} if @var{e} is a window focus lost event.
@end deffn

@deffn {Procedure} window-closed-event? e
Return @code{#t} if @var{e} is a window closed event.
@end deffn

@deffn {Procedure} window-event-timestamp e
@end deffn

@deffn {Procedure} window-event-window-id e
@end deffn

@deffn {Procedure} window-event-type e
@end deffn

@deffn {Procedure} window-event-vector e
@end deffn

@deffn {Procedure} make-keyboard-event timestamp @
                                              window-id @
                                              pressed? @
                                              repeat? @
                                              key @
                                              scancode @
                                              modifiers
@end deffn

@deffn {Procedure} keyboard-event? e
Return @code{#t} if @var{e} is a keyboard event.
@end deffn

@deffn {Procedure} keyboard-down-event? e
Return @code{#t} if @var{e} is a key press event.
@end deffn

@deffn {Procedure} keyboard-up-event? e
Return @code{#t} if @var{e} is a key release event.
@end deffn

@deffn {Procedure} keyboard-event-timestamp e
@end deffn

@deffn {Procedure} keyboard-event-window-id e
@end deffn

@deffn {Procedure} keyboard-event-pressed? e
@end deffn

@deffn {Procedure} keyboard-event-repeat? e
@end deffn

@deffn {Procedure} keyboard-event-key e
@end deffn

@deffn {Procedure} keyboard-event-scancode e
@end deffn

@deffn {Procedure} keyboard-event-modifiers e
@end deffn

@deffn {Procedure} make-text-input-event timestamp window-id text
@end deffn

@deffn {Procedure} text-input-event? e
Return @code{#t} if @var{e} is a text input event.
@end deffn

@deffn {Procedure} text-input-event-timestamp e
@end deffn

@deffn {Procedure} text-input-event-window-id e
@end deffn

@deffn {Procedure} text-input-event-text e
@end deffn

@deffn {Procedure} make-mouse-button-event timestamp @
                                                  window-id @
                                                  which @
                                                  button @
                                                  pressed? @
                                                  clicks @
                                                  x @
                                                  y
@end deffn

@deffn {Procedure} mouse-button-event? e
Return @code{#t} if @var{e} is a mouse button event.
@end deffn

@deffn {Procedure} mouse-button-down-event? e
Return @code{#t} if @var{e} is a mouse button down event.
@end deffn

@deffn {Procedure} mouse-button-up-event? e
Return @code{#t} if @var{e} is a mouse button up event.
@end deffn

@deffn {Procedure} mouse-button-event-timestamp e
@end deffn

@deffn {Procedure} mouse-button-event-window-id e
@end deffn

@deffn {Procedure} mouse-button-event-which e
@end deffn

@deffn {Procedure} mouse-button-event-button e
@end deffn

@deffn {Procedure} mouse-button-event-pressed? e
@end deffn

@deffn {Procedure} mouse-button-event-clicks e
@end deffn

@deffn {Procedure} mouse-button-event-x e
@end deffn

@deffn {Procedure} mouse-button-event-y e
@end deffn

@deffn {Procedure} make-mouse-motion-event timestamp @
                                                  window-id @
                                                  which @
                                                  buttons @
                                                  x @
                                                  y @
                                                  x-rel @
                                                  y-rel
@end deffn

@deffn {Procedure} mouse-motion-event? e
Return @code{#t} if @var{e} is a mouse motion event.
@end deffn

@deffn {Procedure} mouse-motion-event-timestamp e
@end deffn

@deffn {Procedure} mouse-motion-event-window-id e
@end deffn

@deffn {Procedure} mouse-motion-event-which e
@end deffn

@deffn {Procedure} mouse-motion-event-buttons e
@end deffn

@deffn {Procedure} mouse-motion-event-x e
@end deffn

@deffn {Procedure} mouse-motion-event-y e
@end deffn

@deffn {Procedure} mouse-motion-event-x-rel e
@end deffn

@deffn {Procedure} mouse-motion-event-y-rel e
@end deffn

@deffn {Procedure} make-joystick-axis-event timestamp which axis value
@end deffn

@deffn {Procedure} joystick-axis-event? e
Return @code{#t} if @var{e} is a joystick axis event.
@end deffn

@deffn {Procedure} joystick-axis-event-timestamp e
@end deffn

@deffn {Procedure} joystick-axis-event-which e
@end deffn

@deffn {Procedure} joystick-axis-event-button e
@end deffn

@deffn {Procedure} joystick-axis-event-pressed? e
@end deffn

@deffn {Procedure} make-joystick-ball-event timestamp @
                                                   which @
                                                   ball @
                                                   x-rel @
                                                   y-rel
@end deffn

@deffn {Procedure} joystick-ball-event? e
Return @code{#t} if @var{e} is a joystick ball event.
@end deffn

@deffn {Procedure} joystick-ball-event-timestamp e
@end deffn

@deffn {Procedure} joystick-ball-event-which e
@end deffn

@deffn {Procedure} joystick-ball-event-ball e
@end deffn

@deffn {Procedure} joystick-ball-event-x-rel e
@end deffn

@deffn {Procedure} joystick-ball-event-y-rel e
@end deffn

@deffn {Procedure} make-joystick-hat-event timestamp which hat value
@end deffn

@deffn {Procedure} joystick-hat-event? e
Return @code{#t} if @var{e} is a joystick hat event.
@end deffn

@deffn {Procedure} joystick-hat-event-timestamp e
@end deffn

@deffn {Procedure} joystick-hat-event-which e
@end deffn

@deffn {Procedure} joystick-hat-event-hat e
@end deffn

@deffn {Procedure} joystick-hat-event-value e
@end deffn

@deffn {Procedure} make-joystick-device-event timestamp which action
@end deffn

@deffn {Procedure} joystick-device-event? e
Return @code{#t} if @var{e} is a joystick device event.
@end deffn

@deffn {Procedure} joystick-device-event-timestamp e
@end deffn

@deffn {Procedure} joystick-device-event-which e
@end deffn

@deffn {Procedure} joystick-device-event-action e
@end deffn

@deffn {Procedure} make-controller-axis-event timestamp which axis value
@end deffn

@deffn {Procedure} controller-axis-event? e
Return @code{#t} if @var{e} is a game controller axis event.
@end deffn

@deffn {Procedure} controller-axis-event-timestamp e
@end deffn

@deffn {Procedure} controller-axis-event-which e
@end deffn

@deffn {Procedure} controller-axis-event-axis e
@end deffn

@deffn {Procedure} controller-axis-event-value e
@end deffn

@deffn {Procedure} make-controller-button-event timestamp @
                                                       which @
                                                       button @
                                                       pressed?
@end deffn

@deffn {Procedure} controller-button-event? e
Return @code{#t} if @var{event} is a game controller button event.
@end deffn

@deffn {Procedure} controller-button-down-event? e
@end deffn

@deffn {Procedure} controller-button-up-event? e
@end deffn

@deffn {Procedure} controller-button-event-timestamp e
@end deffn

@deffn {Procedure} controller-button-event-which e
@end deffn

@deffn {Procedure} controller-button-event-button e
@end deffn

@deffn {Procedure} controller-button-event-pressed? e
@end deffn

@deffn {Procedure} make-controller-device-event timestamp which action
@end deffn

@deffn {Procedure} controller-device-event? e
Return @code{#t} if @var{event} is a game controller device event.
@end deffn

@deffn {Procedure} controller-added-event? e
Return @code{#t} if @var{event} is a game controller device event with the
'added' action.
@end deffn

@deffn {Procedure} controller-removed-event? e
Return @code{#t} if @var{event} is a game controller device event with the
'removed' action.
@end deffn

@deffn {Procedure} controller-remapped-event? e
Return @code{#t} if @var{event} is a game controller device event with the
'remapped' action.
@end deffn

@deffn {Procedure} controller-device-event-timestamp e
@end deffn

@deffn {Procedure} controller-device-event-which e
@end deffn

@deffn {Procedure} controller-device-event-action e
@end deffn

@deffn {Procedure} poll-event
@end deffn

@node Rects
@section Rects

@example
(use-modules (sdl2 rect))
@end example

@deffn {Procedure} make-rect @var{x} @var{y} @var{width} @var{height}
Return a new rectangle whose upper-left corner is at (@var{x},
@var{y}) and is @var{width} pixels wide and @var{height} pixels high.
@end deffn

@deffn {Procedure} rect-x rect
Return the X coordinate of @var{rect}.
@end deffn

@deffn {Procedure} rect-y rect
Return the Y coordinate of @var{rect}.
@end deffn

@deffn {Procedure} rect-width rect
Return the width of @var{rect}.
@end deffn

@deffn {Procedure} rect-height rect
Return the height of @var{rect}.
@end deffn

@deffn {Procedure} set-rect-x! rect x
Set the x coordinate of @var{rect} to @var{x}.
@end deffn

@deffn {Procedure} set-rect-y! rect y
Set the y coordinate of @var{rect} to @var{y}.
@end deffn

@deffn {Procedure} set-rect-width! rect w
Set the width of @var{rect} to @var{w}.
@end deffn

@deffn {Procedure} set-rect-height! rect h
Set the height of @var{rect} to @var{h}.
@end deffn

@node Surfaces
@section Surfaces

@example
(use-modules (sdl2 surface))
@end example

@deffn {Procedure} color? c
Return @code{#t} if @var{c} is a color.
@end deffn

@deffn {Procedure} color-r c
@end deffn

@deffn {Procedure} color-g c
@end deffn

@deffn {Procedure} color-b c
@end deffn

@deffn {Procedure} color-a c
@end deffn

@deffn {Procedure} palette? p
Return @code{#t} if @var{p} is a palette.
@end deffn

@deffn {Procedure} palette-length palette
Return the number of colors in @var{palette}.
@end deffn

@deffn {Procedure} palette-colors palette
Return the colors in @var{palette}.
@end deffn

@deffn {Procedure} pixel-format? pf
Return @code{#t} if @var{pf} is a pixel format.
@end deffn

@deffn {Procedure} pixel-format-name pf
Return the symbolic name of the pixel format @var{pf}.
@end deffn

@deffn {Procedure} pixel-format-palette pf
Return the palette for the pixel format @var{pf}.
@end deffn

@deffn {Procedure} pixel-format-bits-per-pixel pf
Return the number of bits per pixel for the pixel format @var{pf}.
@end deffn

@deffn {Procedure} pixel-format-bytes-per-pixel pf
Return the number of bytes per pixel for the pixel format @var{pf}.
@end deffn

@deffn {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 {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 {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 {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 {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 {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 {Procedure} delete-surface! surface
Free the memory used by @var{surface}.
@end deffn

@deffn {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 {Procedure} load-bmp file
Create a new surface from the bitmap data in @var{file}.
@end deffn

@deffn {Procedure} surface-width surface
Return the width of @var{surface} in pixels.
@end deffn

@deffn {Procedure} surface-height surface
Return the height of @var{surface} in pixels.
@end deffn

@deffn {Procedure} surface-pitch surface
Return the length of a row of pixels in @var{surface} in bytes.
@end deffn

@deffn {Procedure} surface-pixels surface
Return a bytevector containing the raw pixel data in @var{surface}.
@end deffn

@deffn {Procedure} surface-pixel-format surface
Return the pixel format for @var{surface}.
@end deffn

@deffn {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

@deffn {Procedure} blit-surface @var{src} @var{src-rect} @var{dst} @var{dst-rect}
Blit the rectangle @var{src-rect} from the surface @var{src} to
@var{dst-rect} of the surface @var{dst}.
@end deffn

@deffn {Procedure} blit-scaled @var{src} @var{src-rect} @var{dst} @var{dst-rect}
Blit the rectangle @var{src-rect} from the surface @var{src} to
@var{dst-rect} of the surface @var{dst}, scaling the source to fit the
destination.
@end deffn

@deffn {Procedure} fill-rect @var{dst} @var{rect} @var{color}
Fill @var{rect} with @var{color}, a 32-bit color encoded as an integer
value, in the surface @var{dst}.
@end deffn

@node Rendering
@section Rendering

@example
(use-modules (sdl2 render))
@end example

@deffn {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 {Procedure} renderer? r
Return @code{#t} if @var{r} is a renderer.
@end deffn

@deffn {Procedure} delete-renderer! renderer
Delete the rendering context @var{renderer}.
@end deffn

@deffn {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 {Procedure} clear-renderer renderer
Clear the rendering target @var{renderer} with the current drawing color.
@end deffn

@deffn {Procedure} present-renderer renderer
Display @var{renderer}.
@end deffn

@deffn {Procedure} renderer-integer-scale renderer
Returns @code{#t} if @var{renderer} currently uses integer scaling and
@code{#f} otherwise.  Integer scaling can be used together with
logical size to effectively restrict the drawing region to an area
even if the window is larger than that.
@end deffn

@deffn {Procedure} set-renderer-integer-scale! renderer enable?
If @var{enable?} is @code{#t}, enable integer scaling, otherwise
disable it.
@end deffn

@deffn {Procedure} renderer-logical-size renderer
Return the current logical size used by @var{renderer}.
@end deffn

@deffn {Procedure} set-renderer-logical-size! renderer width height
Set the logical size of @var{renderer} to @var{width} x @var{height}.
@end deffn

@deffn {Procedure} renderer-scale renderer
Return the scaling factors @code{(X Y)} used by @var{renderer} to
scale coordinates.
@end deffn

@deffn {Procedure} set-renderer-scale! renderer scale-x scale-y
Set the factors by which @var{renderer} scales coordinates according
to the scaling factors @var{scale-x} and @var{scale-y}.
@end deffn

@deffn {Procedure} renderer-viewport renderer
Return the rectangle that @var{renderer} currently draws on.  If the
entire region is used, all values of that rectangle will be 0.
@end deffn

@deffn {Procedure} set-renderer-viewport! renderer rect
Set the drawing area for @var{renderer} to @var{rect}.
@end deffn

@deffn {Procedure} render-copy renderer @
                                      texture @
                                      [#:angle 0] @
                                      [#:srcrect] @
                                      [#:dstrect] @
                                      [#:center]
Copy @var{texture} to the rendering target of @var{renderer}.
@end deffn

@deffn {Procedure} set-renderer-draw-color! renderer r g b a
Set color of @var{renderer} to the 32-bit color defined by the 8-bit
color channels @var{r}, @var{g}, @var{b}, @var{a}.  Each color channel
value is in the range [0, 255].
@end deffn

@deffn {Procedure} set-renderer-draw-blend-mode! renderer blend-mode
Set blend mode of @var{renderer} to @var{blend-mode}. @xref{Blend
Modes} for more information.
@end deffn

@deffn {Procedure} set-renderer-target! renderer texture
Sets the render target for @var{renderer} to @var{texture}, making all
comming draw requests redirect to @var{texture}.

Pass @code{#f} to reset it to the default target.
@end deffn

@deffn {Procedure} renderer-target renderer
Returns the current render target of @var{renderer} or @code{#f} if
it's a texture.
@end deffn

@deffn {Procedure} draw-line renderer x1 y1 x2 y2
Draw a line from (@var{x1}, @var{y1}) to (@var{x2}, @var{y2}) on the
current rendering target of @var{renderer}.
@end deffn

@deffn {Procedure} draw-lines renderer points
Draw a series of connected lines from @var{points} on the current
rendering target of @var{renderer}.  Optionally, for best performance,
@var{points} may instead be a bytevector packed with signed 32 bit
integers, 2 per point (x and y).
@end deffn

@deffn {Procedure} draw-point renderer x y
Draw a point at (@var{x}, @var{y}) on the current rendering target
of @var{renderer}.
@end deffn

@deffn {Procedure} draw-points renderer points
Draw a multiple points from @var{points} on the current rendering
target of @var{renderer}.  Optionally, for best performance,
@var{points} may instead be a bytevector packed with signed 32 bit
integers, 2 per point (x and y).
@end deffn

@deffn {Procedure} draw-rect renderer rectangle
Draw the outline of @var{rectangle} onto renderer.
@end deffn

@deffn {Procedure} draw-rects renderer rects
Draw the outline of all rects in the list @var{rects} onto
@var{renderer}.  Optionally, for best performance, @var{rects} may
instead be a bytevector packed with signed 32 bit integers, 4 per rect
(x, y, width, height).
@end deffn

@deffn {Procedure} fill-rect renderer rectangle
Fill @var{rectangle} onto @var{renderer}.
@end deffn

@deffn {Procedure} fill-rects renderer rects
Fill the list @var{rects} onto @var{renderer}.  Optionally, for best
performance, @var{rects} may instead be a bytevector packed with
signed 32 bit integers, 4 per rect (x, y, width, height).
@end deffn

@deffn {Procedure} make-texture renderer format access width height
Returns a new texture for @var{renderer} with pixel @var{format}.
@var{access} is one of the symbols:

@itemize
@item static, changes rarely, not lockable
@item streaming, changes frequently, lockable
@item target, can be used as a render target
requires that renderer was created with the @code{texture} flag.
@end itemize
@end deffn

@deffn {Procedure} query-texture texture
Return 4 values for the format, access, width and height of a texture.
@end deffn

@deffn {Procedure} surface->texture renderer surface
Convert @var{surface} to a texture suitable for @var{renderer}.
@end deffn

@deffn {Procedure} delete-texture! texture
Free the memory used by @var{texture}.
@end deffn

@deffn {Procedure} update-texture texture rect pixels pitch
Update the subsection of @var{texture} defined by @var{rect} with new
pixel data in the @var{pixels} bytevector.  @var{pitch} represents the
number of bytes in a row of pixel data, including any padding between
rows.  This is a fairly slow process: Better to use the lock/unlock
mechanism in streaming textures.
@end deffn

@deffn {Procedure} texture-color-mod texture
Get color mod of @var{texture} as a list of the integers.
@end deffn

@deffn {Procedure} texture-alpha-mod texture
Get alpha mod of @var{texture} as a single integer.
@end deffn

@deffn {Procedure} set-texture-color-mod! texture r g b
Set the color mod of @var{texture}.
@end deffn

@deffn {Procedure} set-texture-alpha-mod! texture a
Set the alpha mod of @var{texture}.
@end deffn

@deffn {Procedure} set-texture-blend-mode! texture blend-mode
Set the blend of @var{texture} to @var{blend-mode}.  @xref{Blend
Modes} for more information.
@end deffn

@node Blend Modes
@section Blend Modes

@example
(use-modules (sdl2 blend-mode))
@end example

SDL2 provides several of the most commonly used blend modes:

@defvar none
No blending.
@end defvar

@defvar blend
Alpha blending.
@end defvar

@defvar add
Additive blending.
@end defvar

@defvar mul
Multiplicative blending.
@end defvar

@defvar mod
Color modulation.
@end defvar

Custom blend modes can be created using the @code{make-blend-mode}
procedure.

@deffn {Procedure} make-blend-mode src-color-factor dst-color-factor color-operation src-alpha-factor dst-alpha-factor alpha-operation
Return a new custom blend mode for renderers.

@var{src-color-factor} applies to the red, green, and blue components
of the source pixels.

@var{dst-color-factor} applies to the red, green, and blue components of the
destination pixels.

@var{color-operation} specifies how to combine the red, green, and blue
components of the source and destination pixels.

@var{src-alpha-factor} applies to the alpha component of the source pixels.

@var{dst-alpha-factor} applies to the alpha component of the destination
pixels.

@var{alpha-operation} specifies how to combine the alpha component of the
source and destination pixels.

Possible values for factors are @code{zero}, @code{one},
@code{src-color}, @code{one-minus-src-color}, @code{src-alpha},
@code{one-minus-src-alpha}, @code{dst-color},
@code{one-minus-dst-color}, @code{dst-alpha}, and @code{one-minus-dst
alpha}.

Possible values for operations are @code{add}, @code{subtract},
@code{rev-subtract}, @code{minimum}, and @code{maximum}.
@end deffn

@deffn {Procedure} blend-mode? obj
Return @code{#t} if @var{obj} is a blend mode object.
@end deffn

@deffn {Procedure} blend-mode-src-color-factor blend-mode
Return the source red, green, and blue channel blend factor for
@var{blend-mode}.
@end deffn

@deffn {Procedure} blend-mode-dst-color-factor blend-mode
Return the destination red, green, and blue channel blend factor for
@var{blend-mode}.
@end deffn

@deffn {Procedure} blend-mode-color-operation blend-mode
Return the red, green, and blue channel blend operation for
@var{blend-mode}.
@end deffn

@deffn {Procedure} blend-mode-src-alpha-factor blend-mode
Return the source alpha channel blend factor for @var{blend-mode}.
@end deffn

@deffn {Procedure} blend-mode-dst-alpha-factor blend-mode
Return the destination alpha channel blend factor for
@var{blend-mode}.
@end deffn

@deffn {Procedure} blend-mode-alpha-operation blend-mode
Return the alpha channel blend operation for @var{blend-mode}.
@end deffn

@node Images
@section Images

@example
(use-modules (sdl2 image))
@end example

@deffn {Procedure} image-init
Initialize dynamically loaded image libraries.
@end deffn

@deffn {Procedure} image-quit
Clean up dynamically loaded image libraries.
@end deffn

@deffn {Procedure} load-image file
Load the image in @var{file} and return an SDL surface.
@end deffn

@deffn {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 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 {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 {Procedure} mixer-quit
Shutdown mixer library.
@end deffn

@deffn {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 {Procedure} close-audio
Shut down the mixer API.
@end deffn

@deffn {Procedure} chunk? c
Return @code{#t} if @var{c} is a chunk.
@end deffn

@deffn {Procedure} load-chunk file
Load the audio data in @var{file} and return an audio chunk.
@end deffn

@deffn {Procedure} delete-chunk! chunk
Free the memory used for @var{chunk}.
@end deffn

@deffn {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 {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 {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 {Procedure} pause-channel! channel
Pause playback on @var{channel}, an integer channel identifier, or @code{#f} to
pause all channels.
@end deffn

@deffn {Procedure} resume-channel! channel
Resume playback on @var{channel}, an integer channel identifier, or @code{#f} to
resume all channels.
@end deffn

@deffn {Procedure} stop-channel! channel
Halt playback on @var{channel}, an integer channel identifier, or @code{#f} to
halt all channels.
@end deffn

@deffn {Procedure} channel-playing? channel
Return @code{#t} if @var{channel} is playing.
@end deffn

@deffn {Procedure} playing-channels-count
Return the number of channels currently playing.
@end deffn

@deffn {Procedure} channel-paused? channel
Return @code{#t} if @var{channel} is paused.
@end deffn

@deffn {Procedure} paused-channels-count
Return the number of channels that are paused.
@end deffn

@deffn {Procedure} music? m
Return @code{#t} if @var{m} is music.
@end deffn

@deffn {Procedure} load-music file
Load music from @var{file}.
@end deffn

@deffn {Procedure} delete-music! music
Delete the memory used for @var{music}.
@end deffn

@deffn {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 {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 {Procedure} music-volume
Return the music volume.
@end deffn

@deffn {Procedure} pause-music!
Puase the music.
@end deffn

@deffn {Procedure} resume-music!
Resume music playback.
@end deffn

@deffn {Procedure} rewind-music!
Start music playback from the beginning.  Rewinding is only supported for MOD,
OGG, MP3, and native MIDI music.
@end deffn

@deffn {Procedure} stop-music!
Halt music playback.
@end deffn

@deffn {Procedure} music-playing?
Return @code{#t} if music is currently playing.
@end deffn

@deffn {Procedure} music-paused?
Return @code{#t} if music is currently paused.
@end deffn

@node Fonts
@section Fonts

@example
(use-modules (sdl2 ttf))
@end example

@deffn {Procedure} ttf-init
Initialize the TTF system.
@end deffn

@deffn {Procedure} ttf-quit
Shut down and clean up the TTF system.
@end deffn

@deffn {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 {Procedure} delete-font! font
Delete the memory allocated for @var{font}.
@end deffn

@deffn {Procedure} font-height font
Return the maximum height of @var{font}.
@end deffn

@deffn {Procedure} font-ascent font
Return the maximum pixel ascent of all glyphs in @var{font}.  This can
also be interpreted as the distance from the top of the font to the
baseline.
@end deffn

@deffn {Procedure} font-descent font
Return the maximum pixel descent of all glyphs in @var{font}.  This
can also be interpreted as the distance from the baseline to the
bottom of the font.
@end deffn

@deffn {Procedure} font-line-skip font
Return the recommended pixel height of a line of text using
@var{font}.
@end deffn

@deffn {Procedure} font-size-text font text
Return 2 values for the resulting surface size of the string
@var{text} using @var{font}.
@end deffn

@deffn {Procedure} font-glyph-index font char
Return the index of the glyph for @var{char} in @var{font}, or
@code{#f} if @var{char} is not present.
@end deffn

@deffn {Procedure} font-glyph-metrics font char
Return values for the metrics of @var{char} in @var{font}: min x, max
x, min y, max y, and advance.
@end deffn

@deffn font-style font
Return the rendering style of @var{font} as a list that may contain
any of the following symbols:

@itemize
@item @code{bold}
@item @code{italic}
@item @code{underline}
@item @code{strikethrough}
@end itemize

The empty list is returned if none of the above styles are applied.
@end deffn

@deffn font-set-style! font style
Set the rendering style of @var{font} to @var{style}, a list that may
contain any of the following symbols:

@itemize
@item @code{bold}
@item @code{italic}
@item @code{underline}
@item @code{strikethrough}
@end itemize

The empty list means that none of the above stylings will be used.
@end deffn

@deffn {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 {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

@node Hints
@section Hints

@example
(use-modules (sdl2 hints))
@end example

@deffn {Procedure} get-hint hint
Get the string value of @var{hint} or @code{#f} if if @var{hint} is unset.
@end deffn

@deffn {Procedure} set-hint! hint value [priority]
Set @var{hint} to @var{value} at priority level @var{priority}.
@var{priority} can be one of the symbols @code{default}, @code{normal} or
@code{override} and defaults to @code{normal}.
@var{value} will automatically be converted to a string if it is a boolean
or a number.
@end deffn

Inside SDL2, the macro @code{SDL_HINT_SOME_HINT} corresponds to the
environment variable @env{SDL_SOME_HINT}.  In Guile-SDL2, this hint would be
represented by the symbol @code{some-symbol.}