render: Add SDL_DestroyTexture binding.
[guile-sdl2.git] / doc / api.texi
CommitLineData
9ec24e3f
DT
1@menu
2* Basics:: Initialization and other basic things.
3* Window Management:: Working with the window system.
4* Input:: Keyboard, mouse, joystick input.
5* Events:: Asynchronous event handling.
bec0030a 6* Rects:: 2D rectangles.
9ec24e3f
DT
7* Surfaces:: Software rendering.
8* Rendering:: Hardware accelerated rendering.
9* Images:: Loading and saving images.
10* Sound:: Sound effects and music.
11* Fonts:: Truetype and bitmap font rendering.
12@end menu
13
14@node Basics
15@section Basics
16
17@example
18(use-modules (sdl2))
19@end example
20
c519f823 21@deffn {Procedure} sdl-init [@var{subsystems}]
9ec24e3f
DT
22Initialize the SDL library. This must be called before using any
23other SDL procedure.
24
25@var{subsystems} is an optional list of symbols that specifies the
26subsystems to initialize. All subsystems are initialized by default.
27The possible flags are @code{timer}, @code{audio}, @code{video},
28@code{haptic}, @code{game-controller}, and @code{events}.
29@end deffn
30
c519f823 31@deffn {Procedure} sdl-quit
9ec24e3f
DT
32Quit all activated SDL subsystems. This procedure should be called
33upon all exit conditions.
34@end deffn
35
c519f823 36@deffn {Procedure} sdl-version
9ec24e3f
DT
37Return a three element list containing the major, minor, and patch
38version of the linked SDL library.
39@end deffn
40
c519f823 41@deffn {Procedure} sdl-ticks
9ec24e3f
DT
42Return the number of milliseconds since the SDL library was
43initialized.
44@end deffn
45
46@node Window Management
47@section Window Management
48
49@menu
50* Windows:: Window manipulation.
51* OpenGL:: OpenGL contexts.
52@end menu
53
54@example
55(use-modules (sdl2 video))
56@end example
57
58@node Windows
59@subsection Windows
60
c519f823 61@deffn {Procedure} make-window [#:title "Guile SDL2 Window"] @
b4f32490
KK
62 [#:position (#f #f)] @
63 [#:size (640 480)] @
64 [#:maximize? #f] @
65 [#:minimize? #f] @
66 [#:opengl? #f] @
67 [#:border? #t] @
68 [#:fullscreen? #f] @
69 [#:fullscreen-desktop? #f] @
70 [#:grab-input? #f] @
71 [#:high-dpi? #f]
72Create a new window named @var{title} with dimensions @var{size} located
73at @var{position} on the display. @var{position} and @var{size} are
74two-element lists in the form @code{(x y)}, where each coordinate is
75measured in pixels. In the case of @var{position}, a coordinate may use
76the special symbol @var{center} to indicate that the window should be
77centered on that axis, or @code{#f} to indicate that it does not matter
78where the window is located on that axis.
79@end deffn
80
c519f823 81@deffn {Procedure} close-window! window
b4f32490
KK
82Close @var{window}.
83@end deffn
84
c519f823 85@deffn {Procedure} call-with-window window proc
b4f32490
KK
86Call @var{proc} with @var{window}, an SDL window object, and close it
87when @var{proc} returns or otherwise exits.
88@end deffn
89
c519f823 90@deffn {Procedure} window-title window
b4f32490
KK
91Return the title for @var{window}.
92@end deffn
93
c519f823 94@deffn {Procedure} window-size window
b4f32490
KK
95Return the dimensions of @var{window}.
96@end deffn
97
c519f823 98@deffn {Procedure} window-position window
b4f32490
KK
99Return the position of @var{window} on the display.
100@end deffn
101
c519f823 102@deffn {Procedure} window-id window
b4f32490
KK
103Return the numeric ID of @var{window}.
104@end deffn
105
c519f823 106@deffn {Procedure} id->window id
b4f32490
KK
107Return the window corresponding to @var{ID}, a positive integer, or
108@code{#f} if there is no such window.
109@end deffn
110
c519f823 111@deffn {Procedure} hide-window! window
b4f32490
KK
112Hide @var{window}.
113@end deffn
114
c519f823 115@deffn {Procedure} show-window! window
b4f32490
KK
116Show @var{window} and focus on it.
117@end deffn
118
c519f823 119@deffn {Procedure} maximize-window! window
b4f32490
KK
120Make @var{window} as large as possible.
121@end deffn
122
c519f823 123@deffn {Procedure} minimize-window! window
b4f32490
KK
124Shrink @var{window} to an iconic representation.
125@end deffn
126
c519f823 127@deffn {Procedure} raise-window! window
b4f32490
KK
128Raise @var{window} above all other windows and set input focus.
129@end deffn
130
c519f823 131@deffn {Procedure} restore-window! window
b4f32490
KK
132Restore the size and position of a minimized or maximized @var{window}.
133@end deffn
134
c519f823 135@deffn {Procedure} set-window-border! window border?
b4f32490
KK
136When @var{border?}, draw the usual border around @var{window}, otherwise
137remove the border.
138@end deffn
139
c519f823 140@deffn {Procedure} set-window-title! window title
b4f32490
KK
141Set the title of @var{window} to the string @var{title}.
142@end deffn
143
c519f823 144@deffn {Procedure} set-window-position! window position
b4f32490
KK
145Set the position of @var{window} to @var{position}, a two-element list
146of (x,y) coordinates measured in pixels.
147@end deffn
148
c519f823 149@deffn {Procedure} set-window-size! window size
b4f32490
KK
150Set the dimensions of @var{window} to @var{size}, a two-element list of
151(width,height) coordinates measured in pixels.
152@end deffn
153
c519f823 154@deffn {Procedure} set-window-fullscreen! window fullscreen? [#:desktop?]
b4f32490
KK
155Toggle fullscreen mode on/off for @var{window}. If @var{fullscreen?},
156fullscreen mode is activated, otherwise it is deactivated. If
157@var{fullscreen?} and @var{desktop?}, a special "fake" fullscreen mode
158is used that takes the size of the desktop.
159@end deffn
160
9ec24e3f
DT
161@node OpenGL
162@subsection OpenGL
163
c519f823 164@deffn {Procedure} make-gl-context window
b4f32490
KK
165Create an OpenGL context for @var{window}.
166@end deffn
167
c519f823 168@deffn {Procedure} delete-gl-context! context
b4f32490
KK
169Delete @var{context}, an OpenGL context object.
170@end deffn
171
c519f823 172@deffn {Procedure} call-with-gl-context window proc
b4f32490
KK
173Call @var{proc} with a new OpenGL context created for @var{window}, and
174close the context when @var{proc} returns or otherwise exits.
175@end deffn
176
c519f823 177@deffn {Procedure} swap-gl-window window
b4f32490
KK
178Update @var{window} with OpenGL rendering.
179@end deffn
180
c519f823 181@deffn {Procedure} set-gl-attribute! attr value
b4f32490
KK
182Set the OpenGL attribute represented by the symbol @var{attr} to
183@var{value}. Possible values for @var{attr} are:
184
185@itemize
186@item @code{red-size}
187@item @code{green-size}
188@item @code{blue-size}
189@item @code{alpha-size}
190@item @code{buffer-size}
191@item @code{double-buffer}
192@item @code{depth-size}
193@item @code{stencil-size}
194@item @code{accum-red-size}
195@item @code{accum-green-size}
196@item @code{accum-blue-size}
197@item @code{stereo}
198@item @code{multisample-buffers}
199@item @code{multisample-samples}
200@item @code{retained-backing}
201@item @code{context-major-version}
202@item @code{context-minor-version}
203@item @code{context-egl}
204@item @code{context-flags}
205@item @code{context-profile-mask}
206@item @code{share-with-current-context}
207@item @code{framebuffer-srgb-capable}
208@end itemize
209
210@end deffn
211
c519f823 212@deffn {Procedure} set-gl-swap-interval! interval
b4f32490
KK
213Set the framebuffer swap interval for the current OpenGL context to the
214type indicated by the symbol @var{interval}. Possible values of
215@var{interval} are:
216
217@itemize
218@item @code{immediate}, for immediate updates
219@item @code{vsync}, for updates synchronized with the screen's vertical retrace
220@item @code{late-swap-tear}, for late swap tearing
221@end itemize
222
223Late swap tearing works the same as vsync, but if the vertical retrace
224has been missed for a given frame, buffers are swapped immediately,
225which might be less jarring for the user during occasional framerate
226drops.
227@end deffn
228
9ec24e3f
DT
229@node Input
230@section Input
231
232@menu
233* Keyboard:: Keyboard input.
234* Mouse:: Mouse input.
235* Joysticks:: Joystick input.
236* Game Controllers:: Game controller input.
237@end menu
238
239@node Keyboard
240@subsection Keyboard
241
b4f32490
KK
242@example
243(use-modules (sdl2 input keyboard))
244@end example
245
c519f823 246@deffn {Procedure} key-pressed? key
b4f32490
KK
247Return @code{#t} if @var{key} is currently being pressed.
248@end deffn
249
c519f823 250@deffn {Procedure} key-released? key
b4f32490
KK
251Return @code{#t} is @var{key} is not currently being pressed.
252@end deffn
253
9ec24e3f
DT
254@node Mouse
255@subsection Mouse
256
b4f32490
KK
257@example
258(use-modules (sdl2 input mouse))
259@end example
260
c519f823 261@deffn {Procedure} mouse-x
b4f32490
KK
262Return the x coordinate of the mouse cursor.
263@end deffn
264
c519f823 265@deffn {Procedure} mouse-y
b4f32490
KK
266Return the y coordinate of the mouse cursor.
267@end deffn
268
c519f823 269@deffn {Procedure} mouse-button-pressed? button
b4f32490
KK
270Return @code{#t} if @var{button} is currently being pressed.
271@end deffn
272
c519f823 273@deffn {Procedure} mouse-button-released? button
b4f32490
KK
274Return @code{#t} if @var{button} is not currently being pressed.
275@end deffn
276
9ec24e3f
DT
277@node Joysticks
278@subsection Joysticks
279
280@example
281(use-modules (sdl2 input joystick))
282@end example
283
c519f823 284@deffn {Procedure} num-joysticks
b4f32490
KK
285Return the current number of connected joystick devices.
286@end deffn
287
c519f823 288@deffn {Procedure} open-joystick device-index
b4f32490
KK
289Return a joystick object for the physical joystick device associated
290with @var{device-index}.
291@end deffn
292
c519f823 293@deffn {Procedure} close-joystick joystick
b4f32490
KK
294Close @var{joystick}.
295@end deffn
296
c519f823 297@deffn {Procedure} joystick-instance-id joystick
b4f32490
KK
298Return the instance id of @var{joystick}.
299@end deffn
300
c519f823 301@deffn {Procedure} joystick-power-level joystick
b4f32490
KK
302Return the symbolic battery power level for @var{joystick}, either
303@code{unknown}, @code{empty}, @code{low}, @code{medium}, @code{full},
304or @code{wired}.
305@end deffn
306
c519f823 307@deffn {Procedure} joystick-num-axes joystick
b4f32490
KK
308Return the number of axes for @var{joystick}.
309@end deffn
310
c519f823 311@deffn {Procedure} joystick-num-balls joystick
b4f32490
KK
312Return the number of balls for @var{joystick}.
313@end deffn
314
c519f823 315@deffn {Procedure} joystick-num-buttons joystick
b4f32490
KK
316Return the number of buttons for @var{joystick}.
317@end deffn
318
c519f823 319@deffn {Procedure} joystick-num-hats joystick
b4f32490
KK
320Return the number of hats for @var{joystick}.
321@end deffn
322
9ec24e3f
DT
323@node Game Controllers
324@subsection Game Controllers
325
326@example
327(use-modules (sdl2 input game-controller))
328@end example
329
c519f823 330@deffn {Procedure} load-game-controller-mappings! file
b4f32490
KK
331Load game controller mapping from @var{file} and return the number of
332mappings added this way.
333
334See @url{https://raw.github.com/gabomdq/SDL_GameControllerDB/master/gamecontrollerdb.txt}
335for a community maintained controller mapping file.
336@end deffn
337
c519f823 338@deffn {Procedure} open-game-controller joystick-index
b4f32490
KK
339Return a game controller object for the physical joystick device associated
340with the @var{joystick-index}.
341@end deffn
342
c519f823 343@deffn {Procedure} close-game-controller controller
b4f32490
KK
344Close @var{controller}.
345@end deffn
346
c519f823 347@deffn {Procedure} game-controller? controller
b4f32490
KK
348Close @var{controller}.
349@end deffn
350
c519f823 351@deffn {Procedure} game-controller-attached? controller
b4f32490
KK
352Return @code{#t} if @var{controller} is currently in use.
353@end deffn
354
c519f823 355@deffn {Procedure} game-controller-joystick controller
b4f32490
KK
356Return the underlying joystick object associated with @var{controller}.
357@end deffn
358
c519f823 359@deffn {Procedure} game-controller-name controller
b4f32490
KK
360Return the human readable name for @var{controller}.
361@end deffn
362
c519f823 363@deffn {Procedure} game-controller-axis controller axis
b4f32490
KK
364Return a number in the range [-32768, 32767] representing the
365current state of @var{axis} on @var{controller}.
366
367@var{axis} may be one of the following symbols:
368@itemize
369@item @code{left-x}
370@item @code{left-y}
371@item @code{right-x}
372@item @code{right-y}
373@item @code{trigger-left}
374@item @code{trigger-right}
375@end itemize
376@end deffn
377
c519f823 378@deffn {Procedure} game-controller-button-pressed? controller button
b4f32490
KK
379Return @code{#t} if @var{button} is pressed on @var{controller}.
380
381@var{button} may be one of the following symbols:
382@itemize
383@item @code{a}
384@item @code{b}
385@item @code{x}
386@item @code{y}
387@item @code{back}
388@item @code{guide}
389@item @code{start}
390@item @code{left-stick}
391@item @code{right-stick}
392@item @code{left-shoulder}
393@item @code{right-shoulder}
394@item @code{dpad-up}
395@item @code{dpad-down}
396@item @code{dpad-left}
397@item @code{dpad-right}
398@end itemize
399@end deffn
400
c519f823 401@deffn {Procedure} game-controller-index? joystick-index
b4f32490
KK
402Return @code{#t} if @var{joystick-index} is a valid game controller index.
403@end deffn
404
9ec24e3f
DT
405@node Events
406@section Events
407
408@example
409(use-modules (sdl2 events))
410@end example
411
c519f823 412@deffn {Procedure} make-quit-event timestamp
b4f32490
KK
413@end deffn
414
c519f823 415@deffn {Procedure} quit-event? e
b4f32490
KK
416Return @code{#t} if @var{e} is a quit event.
417@end deffn
418
c519f823 419@deffn {Procedure} quit-event-timestamp e
b4f32490
KK
420@end deffn
421
c519f823 422@deffn {Procedure} make-window-event timestamp window-id type vector
b4f32490
KK
423@end deffn
424
c519f823 425@deffn {Procedure} window-event? e
b4f32490
KK
426Return @code{#t} if @var{e} is a window event.
427@end deffn
428
c519f823 429@deffn {Procedure} window-shown-event? e
b4f32490
KK
430Return @code{#t} if @var{e} is a window shown event.
431@end deffn
432
c519f823 433@deffn {Procedure} window-hidden-event? e
b4f32490
KK
434Return @code{#t} if @var{e} is a window hidden event.
435@end deffn
436
c519f823 437@deffn {Procedure} window-exposed-event? e
b4f32490
KK
438Return @code{#t} if @var{e} is a window exposed event.
439@end deffn
440
c519f823 441@deffn {Procedure} window-moved-event? e
b4f32490
KK
442Return @code{#t} if @var{e} is a window moved event.
443@end deffn
444
c519f823 445@deffn {Procedure} window-resized-event? e
b4f32490
KK
446Return @code{#t} if @var{e} is a window resized event.
447@end deffn
448
c519f823 449@deffn {Procedure} window-size-changed-event? e
b4f32490
KK
450Return @code{#t} if @var{e} is a window size changed event.
451@end deffn
452
c519f823 453@deffn {Procedure} window-minimized-event? e
b4f32490
KK
454Return @code{#t} if @var{e} is a window minimized event.
455@end deffn
456
c519f823 457@deffn {Procedure} window-maximized-event? e
b4f32490
KK
458Return @code{#t} if @var{e} is a window maximized event.
459@end deffn
460
c519f823 461@deffn {Procedure} window-restored-event? e
b4f32490
KK
462Return @code{#t} if @var{e} is a window restored event.
463@end deffn
464
c519f823 465@deffn {Procedure} window-enter-event? e
b4f32490
KK
466Return @code{#t} if @var{e} is a window enter event.
467@end deffn
468
c519f823 469@deffn {Procedure} window-leave-event? e
b4f32490
KK
470Return @code{#t} if @var{e} is a window leave event.
471@end deffn
472
c519f823 473@deffn {Procedure} window-focus-gained-event? e
b4f32490
KK
474Return @code{#t} if @var{e} is a window focus gained event.
475@end deffn
476
c519f823 477@deffn {Procedure} window-focus-lost-event? e
b4f32490
KK
478Return @code{#t} if @var{e} is a window focus lost event.
479@end deffn
480
c519f823 481@deffn {Procedure} window-closed-event? e
b4f32490
KK
482Return @code{#t} if @var{e} is a window closed event.
483@end deffn
484
c519f823 485@deffn {Procedure} window-event-timestamp e
b4f32490
KK
486@end deffn
487
c519f823 488@deffn {Procedure} window-event-window-id e
b4f32490
KK
489@end deffn
490
c519f823 491@deffn {Procedure} window-event-type e
b4f32490
KK
492@end deffn
493
c519f823 494@deffn {Procedure} window-event-vector e
b4f32490
KK
495@end deffn
496
c519f823 497@deffn {Procedure} make-keyboard-event timestamp @
b4f32490
KK
498 window-id @
499 pressed? @
500 repeat? @
501 key @
502 scancode @
503 modifiers
504@end deffn
505
c519f823 506@deffn {Procedure} keyboard-event? e
b4f32490
KK
507Return @code{#t} if @var{e} is a keyboard event.
508@end deffn
509
c519f823 510@deffn {Procedure} keyboard-down-event? e
b4f32490
KK
511Return @code{#t} if @var{e} is a key press event.
512@end deffn
513
c519f823 514@deffn {Procedure} keyboard-up-event? e
b4f32490
KK
515Return @code{#t} if @var{e} is a key release event.
516@end deffn
517
c519f823 518@deffn {Procedure} keyboard-event-timestamp e
b4f32490
KK
519@end deffn
520
c519f823 521@deffn {Procedure} keyboard-event-window-id e
b4f32490
KK
522@end deffn
523
c519f823 524@deffn {Procedure} keyboard-event-pressed? e
b4f32490
KK
525@end deffn
526
c519f823 527@deffn {Procedure} keyboard-event-repeat? e
b4f32490
KK
528@end deffn
529
c519f823 530@deffn {Procedure} keyboard-event-key e
b4f32490
KK
531@end deffn
532
c519f823 533@deffn {Procedure} keyboard-event-scancode e
b4f32490
KK
534@end deffn
535
c519f823 536@deffn {Procedure} keyboard-event-modifiers e
b4f32490
KK
537@end deffn
538
c519f823 539@deffn {Procedure} make-text-input-event timestamp window-id text
b4f32490
KK
540@end deffn
541
c519f823 542@deffn {Procedure} text-input-event? e
b4f32490
KK
543Return @code{#t} if @var{e} is a text input event.
544@end deffn
545
c519f823 546@deffn {Procedure} text-input-event-timestamp e
b4f32490
KK
547@end deffn
548
c519f823 549@deffn {Procedure} text-input-event-window-id e
b4f32490
KK
550@end deffn
551
c519f823 552@deffn {Procedure} text-input-event-text e
b4f32490
KK
553@end deffn
554
c519f823 555@deffn {Procedure} make-mouse-button-event timestamp @
b4f32490
KK
556 window-id @
557 which @
558 button @
559 pressed? @
560 clicks @
561 x @
562 y
563@end deffn
564
c519f823 565@deffn {Procedure} mouse-button-event? e
b4f32490
KK
566Return @code{#t} if @var{e} is a mouse button event.
567@end deffn
568
c519f823 569@deffn {Procedure} mouse-button-down-event? e
b4f32490
KK
570Return @code{#t} if @var{e} is a mouse button down event.
571@end deffn
572
c519f823 573@deffn {Procedure} mouse-button-up-event? e
b4f32490
KK
574Return @code{#t} if @var{e} is a mouse button up event.
575@end deffn
576
c519f823 577@deffn {Procedure} mouse-button-event-timestamp e
b4f32490
KK
578@end deffn
579
c519f823 580@deffn {Procedure} mouse-button-event-window-id e
b4f32490
KK
581@end deffn
582
c519f823 583@deffn {Procedure} mouse-button-event-which e
b4f32490
KK
584@end deffn
585
c519f823 586@deffn {Procedure} mouse-button-event-button e
b4f32490
KK
587@end deffn
588
c519f823 589@deffn {Procedure} mouse-button-event-pressed? e
b4f32490
KK
590@end deffn
591
c519f823 592@deffn {Procedure} mouse-button-event-clicks e
b4f32490
KK
593@end deffn
594
c519f823 595@deffn {Procedure} mouse-button-event-x e
b4f32490
KK
596@end deffn
597
c519f823 598@deffn {Procedure} mouse-button-event-y e
b4f32490
KK
599@end deffn
600
c519f823 601@deffn {Procedure} make-mouse-motion-event timestamp @
b4f32490
KK
602 window-id @
603 which @
604 buttons @
605 x @
606 y @
607 x-rel @
608 y-rel
609@end deffn
610
c519f823 611@deffn {Procedure} mouse-motion-event? e
b4f32490
KK
612Return @code{#t} if @var{e} is a mouse motion event.
613@end deffn
614
c519f823 615@deffn {Procedure} mouse-motion-event-timestamp e
b4f32490
KK
616@end deffn
617
c519f823 618@deffn {Procedure} mouse-motion-event-window-id e
b4f32490
KK
619@end deffn
620
c519f823 621@deffn {Procedure} mouse-motion-event-which e
b4f32490
KK
622@end deffn
623
c519f823 624@deffn {Procedure} mouse-motion-event-buttons e
b4f32490
KK
625@end deffn
626
c519f823 627@deffn {Procedure} mouse-motion-event-x e
b4f32490
KK
628@end deffn
629
c519f823 630@deffn {Procedure} mouse-motion-event-y e
b4f32490
KK
631@end deffn
632
c519f823 633@deffn {Procedure} mouse-motion-event-x-rel e
b4f32490
KK
634@end deffn
635
c519f823 636@deffn {Procedure} mouse-motion-event-y-rel e
b4f32490
KK
637@end deffn
638
c519f823 639@deffn {Procedure} make-joystick-axis-event timestamp which axis value
b4f32490
KK
640@end deffn
641
c519f823 642@deffn {Procedure} joystick-axis-event? e
b4f32490
KK
643Return @code{#t} if @var{e} is a joystick axis event.
644@end deffn
645
c519f823 646@deffn {Procedure} joystick-axis-event-timestamp e
b4f32490
KK
647@end deffn
648
c519f823 649@deffn {Procedure} joystick-axis-event-which e
b4f32490
KK
650@end deffn
651
c519f823 652@deffn {Procedure} joystick-axis-event-button e
b4f32490
KK
653@end deffn
654
c519f823 655@deffn {Procedure} joystick-axis-event-pressed? e
b4f32490
KK
656@end deffn
657
c519f823 658@deffn {Procedure} make-joystick-ball-event timestamp @
b4f32490
KK
659 which @
660 ball @
661 x-rel @
662 y-rel
663@end deffn
664
c519f823 665@deffn {Procedure} joystick-ball-event? e
b4f32490
KK
666Return @code{#t} if @var{e} is a joystick ball event.
667@end deffn
668
c519f823 669@deffn {Procedure} joystick-ball-event-timestamp e
b4f32490
KK
670@end deffn
671
c519f823 672@deffn {Procedure} joystick-ball-event-which e
b4f32490
KK
673@end deffn
674
c519f823 675@deffn {Procedure} joystick-ball-event-ball e
b4f32490
KK
676@end deffn
677
c519f823 678@deffn {Procedure} joystick-ball-event-x-rel e
b4f32490
KK
679@end deffn
680
c519f823 681@deffn {Procedure} joystick-ball-event-y-rel e
b4f32490
KK
682@end deffn
683
c519f823 684@deffn {Procedure} make-joystick-hat-event timestamp which hat value
b4f32490
KK
685@end deffn
686
c519f823 687@deffn {Procedure} joystick-hat-event? e
b4f32490
KK
688Return @code{#t} if @var{e} is a joystick hat event.
689@end deffn
690
c519f823 691@deffn {Procedure} joystick-hat-event-timestamp e
b4f32490
KK
692@end deffn
693
c519f823 694@deffn {Procedure} joystick-hat-event-which e
b4f32490
KK
695@end deffn
696
c519f823 697@deffn {Procedure} joystick-hat-event-hat e
b4f32490
KK
698@end deffn
699
c519f823 700@deffn {Procedure} joystick-hat-event-value e
b4f32490
KK
701@end deffn
702
c519f823 703@deffn {Procedure} make-joystick-device-event timestamp which action
b4f32490
KK
704@end deffn
705
c519f823 706@deffn {Procedure} joystick-device-event? e
b4f32490
KK
707Return @code{#t} if @var{e} is a joystick device event.
708@end deffn
709
c519f823 710@deffn {Procedure} joystick-device-event-timestamp e
b4f32490
KK
711@end deffn
712
c519f823 713@deffn {Procedure} joystick-device-event-which e
b4f32490
KK
714@end deffn
715
c519f823 716@deffn {Procedure} joystick-device-event-action e
b4f32490
KK
717@end deffn
718
c519f823 719@deffn {Procedure} make-controller-axis-event timestamp which axis value
b4f32490
KK
720@end deffn
721
c519f823 722@deffn {Procedure} controller-axis-event? e
b4f32490
KK
723Return @code{#t} if @var{e} is a game controller axis event.
724@end deffn
725
c519f823 726@deffn {Procedure} controller-axis-event-timestamp e
b4f32490
KK
727@end deffn
728
c519f823 729@deffn {Procedure} controller-axis-event-which e
b4f32490
KK
730@end deffn
731
c519f823 732@deffn {Procedure} controller-axis-event-axis e
b4f32490
KK
733@end deffn
734
c519f823 735@deffn {Procedure} controller-axis-event-value e
b4f32490
KK
736@end deffn
737
c519f823 738@deffn {Procedure} make-controller-button-event timestamp @
b4f32490
KK
739 which @
740 button @
741 pressed?
742@end deffn
743
c519f823 744@deffn {Procedure} controller-button-event? e
b4f32490
KK
745Return @code{#t} if @var{event} is a game controller button event.
746@end deffn
747
c519f823 748@deffn {Procedure} controller-button-down-event? e
b4f32490
KK
749@end deffn
750
c519f823 751@deffn {Procedure} controller-button-up-event? e
b4f32490
KK
752@end deffn
753
c519f823 754@deffn {Procedure} controller-button-event-timestamp e
b4f32490
KK
755@end deffn
756
c519f823 757@deffn {Procedure} controller-button-event-which e
b4f32490
KK
758@end deffn
759
c519f823 760@deffn {Procedure} controller-button-event-button e
b4f32490
KK
761@end deffn
762
c519f823 763@deffn {Procedure} controller-button-event-pressed? e
b4f32490
KK
764@end deffn
765
c519f823 766@deffn {Procedure} make-controller-device-event timestamp which action
b4f32490
KK
767@end deffn
768
c519f823 769@deffn {Procedure} controller-device-event? e
b4f32490
KK
770Return @code{#t} if @var{event} is a game controller device event.
771@end deffn
772
c519f823 773@deffn {Procedure} controller-added-event? e
b4f32490
KK
774Return @code{#t} if @var{event} is a game controller device event with the
775'added' action.
776@end deffn
777
c519f823 778@deffn {Procedure} controller-removed-event? e
b4f32490
KK
779Return @code{#t} if @var{event} is a game controller device event with the
780'removed' action.
781@end deffn
782
c519f823 783@deffn {Procedure} controller-remapped-event? e
b4f32490
KK
784Return @code{#t} if @var{event} is a game controller device event with the
785'remapped' action.
786@end deffn
787
c519f823 788@deffn {Procedure} controller-device-event-timestamp e
b4f32490
KK
789@end deffn
790
c519f823 791@deffn {Procedure} controller-device-event-which e
b4f32490
KK
792@end deffn
793
c519f823 794@deffn {Procedure} controller-device-event-action e
b4f32490
KK
795@end deffn
796
c519f823 797@deffn {Procedure} poll-event
b4f32490
KK
798@end deffn
799
bec0030a
DT
800@node Rects
801@section Rects
802
803@example
804(use-modules (sdl2 rect))
805@end example
806
807@deffn {Procedure} make-rect @var{x} @var{y} @var{width} @var{height}
808Return a new rectangle whose upper-left corner is at (@var{x},
809@var{y}) and is @var{width} pixels wide and @var{height} pixels high.
810@end deffn
811
812@deffn {Procedure} rect-x @var{rect}
813Return the X coordinate of @var{rect}.
814@end deffn
815
816@deffn {Procedure} rect-y @var{rect}
817Return the Y coordinate of @var{rect}.
818@end deffn
819
820@deffn {Procedure} rect-width @var{rect}
821Return the width of @var{rect}.
822@end deffn
823
824@deffn {Procedure} rect-height @var{rect}
825Return the height of @var{rect}.
826@end deffn
827
9ec24e3f
DT
828@node Surfaces
829@section Surfaces
830
831@example
b4f32490 832(use-modules (sdl2 surface))
9ec24e3f
DT
833@end example
834
c519f823 835@deffn {Procedure} color? c
b4f32490
KK
836Return @code{#t} if @var{c} is a color.
837@end deffn
838
c519f823 839@deffn {Procedure} color-r c
b4f32490
KK
840@end deffn
841
c519f823 842@deffn {Procedure} color-g c
b4f32490
KK
843@end deffn
844
c519f823 845@deffn {Procedure} color-b c
b4f32490
KK
846@end deffn
847
c519f823 848@deffn {Procedure} color-a c
b4f32490
KK
849@end deffn
850
c519f823 851@deffn {Procedure} palette? p
b4f32490
KK
852Return @code{#t} if @var{p} is a palette.
853@end deffn
854
c519f823 855@deffn {Procedure} palette-length palette
b4f32490
KK
856Return the number of colors in @var{palette}.
857@end deffn
858
c519f823 859@deffn {Procedure} palette-colors palette
b4f32490
KK
860Return the colors in @var{palette}.
861@end deffn
862
c519f823 863@deffn {Procedure} pixel-format? pf
b4f32490
KK
864Return @code{#t} if @var{pf} is a pixel format.
865@end deffn
866
c519f823 867@deffn {Procedure} pixel-format-name pf
b4f32490
KK
868Return the symbolic name of the pixel format @var{pf}.
869@end deffn
870
c519f823 871@deffn {Procedure} pixel-format-palette pf
b4f32490
KK
872Return the palette for the pixel format @var{pf}.
873@end deffn
874
c519f823 875@deffn {Procedure} pixel-format-bits-per-pixel pf
b4f32490
KK
876Return the number of bits per pixel for the pixel format @var{pf}.
877@end deffn
878
c519f823 879@deffn {Procedure} pixel-format-bytes-per-pixel pf
b4f32490
KK
880Return the number of bytes per pixel for the pixel format @var{pf}.
881@end deffn
882
c519f823 883@deffn {Procedure} pixel-format-red-mask pf
b4f32490
KK
884Return the bitmask for the red component of a pixel in the pixel format
885@var{pf}.
886@end deffn
887
c519f823 888@deffn {Procedure} pixel-format-green-mask pf
b4f32490
KK
889Return the bitmask for the green component of a pixel in the pixel format
890@var{pf}.
891@end deffn
892
c519f823 893@deffn {Procedure} pixel-format-blue-mask pf
b4f32490
KK
894Return the bitmask for the blue component of a pixel in the pixel format
895@var{pf}.
896@end deffn
897
c519f823 898@deffn {Procedure} pixel-format-alpha-mask pf
b4f32490
KK
899Return the bitmask for the alpha component of a pixel in the pixel format
900@var{pf}.
901@end deffn
902
c519f823 903@deffn {Procedure} make-rgb-surface width height depth
b4f32490
KK
904Create a new SDL surface with the dimensions @var{width} and @var{height} and
905@var{depth} bits per pixel.
906@end deffn
907
c519f823 908@deffn {Procedure} bytevector->surface bv width height depth pitch
b4f32490
KK
909Convert @var{bv}, a bytevector of pixel data with dimensions
910@var{width}x@var{height}, to an SDL surface. Each pixel is @var{depth} bits in
911size, and each row of pixels is @var{pitch} bytes in size.
912@end deffn
913
c519f823 914@deffn {Procedure} delete-surface! surface
b4f32490
KK
915Free the memory used by @var{surface}.
916@end deffn
917
c519f823 918@deffn {Procedure} call-with-surface surface proc
b4f32490
KK
919Call @var{proc}, passing it @var{surface} and deleting @var{surface} upon exit
920of @var{proc}.
921@end deffn
922
c519f823 923@deffn {Procedure} load-bmp file
b4f32490
KK
924Create a new surface from the bitmap data in @var{file}.
925@end deffn
926
c519f823 927@deffn {Procedure} surface-width surface
b4f32490
KK
928Return the width of @var{surface} in pixels.
929@end deffn
930
c519f823 931@deffn {Procedure} surface-height surface
b4f32490
KK
932Return the height of @var{surface} in pixels.
933@end deffn
934
c519f823 935@deffn {Procedure} surface-pitch surface
b4f32490
KK
936Return the length of a row of pixels in @var{surface} in bytes.
937@end deffn
938
c519f823 939@deffn {Procedure} surface-pixels surface
b4f32490
KK
940Return a bytevector containing the raw pixel data in @var{surface}.
941@end deffn
942
c519f823 943@deffn {Procedure} surface-pixel-format surface
b4f32490
KK
944Return the pixel format for @var{surface}.
945@end deffn
946
c519f823 947@deffn {Procedure} convert-surface-format surface format
b4f32490
KK
948Convert the pixels in @var{surface} to @var{format}, a symbol representing a
949specific pixel format, and return a new surface object.
950
951Valid format types are:
952
953@itemize
954@item @code{index1lsb}
955@item @code{index1msb}
956@item @code{index4lsb}
957@item @code{index4msb}
958@item @code{index8}
959@item @code{rgb332}
960@item @code{rgb444}
961@item @code{rgb555}
962@item @code{bgr555}
963@item @code{argb4444}
964@item @code{rgba4444}
965@item @code{abgr4444}
966@item @code{bgra4444}
967@item @code{argb1555}
968@item @code{rgba5551}
969@item @code{abgr1555}
970@item @code{bgra5551}
971@item @code{rgb565}
972@item @code{bgr565}
973@item @code{rgb24}
974@item @code{bgr24}
975@item @code{rgb888}
976@item @code{rgbx8888}
977@item @code{bgr888}
978@item @code{bgrx8888}
979@item @code{argb8888}
980@item @code{rgba8888}
981@item @code{abgr8888}
982@item @code{bgra8888}
983@item @code{argb2101010}
984@item @code{yv12}
985@item @code{iyuv}
986@item @code{yuy2}
987@item @code{uyvy}
988@item @code{yvyu}
989@end itemize
990@end deffn
991
f1661d0c
DT
992@deffn {Procedure} blit-surface @var{src} @var{src-rect} @var{dst} @var{dst-rect}
993Blit the rectangle @var{src-rect} from the surface @var{src} to
994@var{dst-rect} of the surface @var{dst}.
995@end deffn
996
5ef8b648
DT
997@deffn {Procedure} blit-scaled @var{src} @var{src-rect} @var{dst} @var{dst-rect}
998Blit the rectangle @var{src-rect} from the surface @var{src} to
999@var{dst-rect} of the surface @var{dst}, scaling the source to fit the
1000destination.
1001@end deffn
1002
4b2c1907
DT
1003@deffn {Procedure} fill-rect @var{dst} @var{rect} @var{color}
1004Fill @var{rect} with @var{color}, a 32-bit color encoded as an integer
1005value, in the surface @var{dst}.
1006@end deffn
5ef8b648 1007
9ec24e3f
DT
1008@node Rendering
1009@section Rendering
1010
1011@example
b4f32490 1012(use-modules (sdl2 render))
9ec24e3f
DT
1013@end example
1014
c519f823 1015@deffn {Procedure} make-renderer window @
b4f32490
KK
1016 [#:optional flags='(accelerated vsync)]
1017Return a new renderer for @var{window} created with the options specified
1018in @var{flags}, a list of symbols. The valid symbols that may appear in
1019@var{flags} are:
1020
1021@itemize
1022@item software, to use a software renderer fallback
1023@item accelerated, to use hardware acceleration
1024@item vsync, to synchronize rendering with the monitor's refresh rate
1025@item texture, for render to texture support
1026@end itemize
1027@end deffn
1028
c519f823 1029@deffn {Procedure} renderer? r
b4f32490
KK
1030Return @code{#t} if @var{r} is a renderer.
1031@end deffn
1032
c519f823 1033@deffn {Procedure} delete-renderer! renderer
b4f32490
KK
1034Delete the rendering context @var{renderer}.
1035@end deffn
1036
c519f823 1037@deffn {Procedure} call-with-renderer renderer proc
b4f32490
KK
1038Call @var{proc}, passing it @var{renderer} and closing @var{renderer} upon exit
1039of @var{proc}.
1040@end deffn
1041
c519f823 1042@deffn {Procedure} clear-renderer renderer
b4f32490
KK
1043Clear the rendering target @var{renderer} with the current drawing color.
1044@end deffn
1045
c519f823 1046@deffn {Procedure} present-renderer renderer
b4f32490
KK
1047Display @var{renderer}.
1048@end deffn
1049
c519f823 1050@deffn {Procedure} render-copy renderer @
b4f32490 1051 texture @
13ed39d6
PAR
1052 [#:angle 0] @
1053 [#:srcrect] @
1054 [#:dstrect] @
1055 [#:center]
b4f32490
KK
1056Copy @var{texture} to the rendering target of @var{renderer}.
1057@end deffn
1058
3d91eb43
PAR
1059@deffn {Procedure} render-draw-line renderer x1 y1 x2 y2
1060Draw a line from (@var{x1}, @var{y1}) to (@var{x2}, @var{y2}) on the
1061current rendering target of @var{renderer}.
1062@end deffn
1063
9ffb8b1f
PAR
1064@deffn {Procedure} render-draw-point renderer x y
1065Draw a point at (@var{x}, @var{y}) on the current rendering target
1066of @var{renderer}.
1067@end deffn
1068
c519f823 1069@deffn {Procedure} surface->texture renderer surface
b4f32490
KK
1070Convert @var{surface} to a texture suitable for @var{renderer}.
1071@end deffn
1072
277d1638
PAR
1073@deffn {Procedure} delete-texture! texture
1074Free the memory used by @var{texture}.
1075@end deffn
1076
9ec24e3f
DT
1077@node Images
1078@section Images
1079
1080@example
b4f32490 1081(use-modules (sdl2 image))
9ec24e3f
DT
1082@end example
1083
c519f823 1084@deffn {Procedure} image-init
b4f32490
KK
1085Initialize dynamically loaded image libraries.
1086@end deffn
1087
c519f823 1088@deffn {Procedure} image-quit
b4f32490
KK
1089Clean up dynamically loaded image libraries.
1090@end deffn
1091
c519f823 1092@deffn {Procedure} load-image file
b4f32490
KK
1093Load the image in @var{file} and return an SDL surface.
1094@end deffn
1095
c519f823 1096@deffn {Procedure} save-png surface file
b4f32490
KK
1097Save @var{surface} to @var{file} as a PNG formatted image.
1098@end deffn
1099
9ec24e3f
DT
1100@node Sound
1101@section Sound
1102
1103@example
b4f32490 1104(use-modules (sdl2 mixer))
9ec24e3f
DT
1105@end example
1106
b4f32490
KK
1107@defvr {Scheme Variable} %default-frequency
1108@end defvr
1109
1110@defvr {Scheme Variable} %default-format
1111@end defvr
1112
1113@defvr {Scheme Variable} %default-chunk-size
1114@end defvr
1115
c519f823 1116@deffn {Procedure} mixer-init [#:optional formats='(flac mod modplug mp3 ogg fluidsynth)]
b4f32490
KK
1117Initialize mixer library with support for @var{formats}, a list of
1118symbols representing audio file formats. Possible formats are:
1119
1120@itemize
1121@item flac
1122@item mod
1123@item modplug
1124@item mp3
1125@item ogg
1126@item fluidsynth
1127@end itemize
1128@end deffn
1129
c519f823 1130@deffn {Procedure} mixer-quit
b4f32490
KK
1131Shutdown mixer library.
1132@end deffn
1133
c519f823 1134@deffn {Procedure} open-audio [#:frequency=%default-frequency] @
b4f32490
KK
1135 [#:format=%default-format] @
1136 [#:stereo?=#t] @
1137 [#:chunk-size=%default-chunk-size]
1138Initialize the mixer API. @var{frequency} specificies the sample rate in
1139hertz. When @var{stereo?} is @code{#t}, two output channels are used, otherwise
1140mono output is used instead. @var{chunk-size} specifies the number of bytes
1141used per output sample. @var{format} is a symbol that specifies the output
1142sample format. Possible values are:
1143
1144@itemize
1145@item u8
1146@item s8
1147@item u16lsb
1148@item s16lsb
1149@item u16msb
1150@item s16msb
1151@item u16
1152@item s16
1153@item s32lsb
1154@item s32msb
1155@item s32
1156@item f32lsb
1157@item f32msb
1158@item f32
1159@end itemize
1160@end deffn
1161
c519f823 1162@deffn {Procedure} close-audio
b4f32490
KK
1163Shut down the mixer API.
1164@end deffn
1165
c519f823 1166@deffn {Procedure} chunk? c
b4f32490
KK
1167Return @code{#t} if @var{c} is a chunk.
1168@end deffn
1169
c519f823 1170@deffn {Procedure} load-chunk file
b4f32490
KK
1171Load the audio data in @var{file} and return an audio chunk.
1172@end deffn
1173
c519f823 1174@deffn {Procedure} delete-chunk! chunk
b4f32490
KK
1175Free the memory used for @var{chunk}.
1176@end deffn
1177
c519f823 1178@deffn {Procedure} set-chunk-volume! chunk volume
b4f32490
KK
1179Set the loudness of @var{chunk} to @var{volume}, an integer in the range
1180[0,128]. Return the previous chunk volume setting.
1181@end deffn
1182
c519f823 1183@deffn {Procedure} play-chunk! chunk @
b4f32490
KK
1184 [#:loops=0] @
1185 [#:channel]
1186Play @var{chunk} on @var{channel}, an integer channel identifier or @code{#f}
1187to use the first unreserved audio channel. @var{chunk} will play @var{loops} +
11881 times. Return the channel identifier that @var{chunk} is played on.
1189@end deffn
1190
c519f823 1191@deffn {Procedure} set-channel-volume! channel volume
b4f32490
KK
1192Set the loudness of @var{channel}, an integer channel identifier or @code{#f}
1193for all channels, to @var{volume}, an integer in the range [0,128]. Return
1194the previous volume of @var{channel}, or the average of all channels if
1195@var{channel} is @code{#f}.
1196@end deffn
1197
c519f823 1198@deffn {Procedure} pause-channel! channel
b4f32490
KK
1199Pause playback on @var{channel}, an integer channel identifier, or @code{#f} to
1200pause all channels.
1201@end deffn
1202
c519f823 1203@deffn {Procedure} resume-channel! channel
b4f32490
KK
1204Resume playback on @var{channel}, an integer channel identifier, or @code{#f} to
1205resume all channels.
1206@end deffn
1207
c519f823 1208@deffn {Procedure} stop-channel! channel
b4f32490
KK
1209Halt playback on @var{channel}, an integer channel identifier, or @code{#f} to
1210halt all channels.
1211@end deffn
1212
c519f823 1213@deffn {Procedure} channel-playing? channel
b4f32490
KK
1214Return @code{#t} if @var{channel} is playing.
1215@end deffn
1216
c519f823 1217@deffn {Procedure} playing-channels-count
b4f32490
KK
1218Return the number of channels currently playing.
1219@end deffn
1220
c519f823 1221@deffn {Procedure} channel-paused? channel
b4f32490
KK
1222Return @code{#t} if @var{channel} is paused.
1223@end deffn
1224
c519f823 1225@deffn {Procedure} paused-channels-count
b4f32490
KK
1226Return the number of channels that are paused.
1227@end deffn
1228
c519f823 1229@deffn {Procedure} music? m
b4f32490
KK
1230Return @code{#t} if @var{m} is music.
1231@end deffn
1232
c519f823 1233@deffn {Procedure} load-music file
b4f32490
KK
1234Load music from @var{file}.
1235@end deffn
1236
c519f823 1237@deffn {Procedure} delete-music! music
b4f32490
KK
1238Delete the memory used for @var{music}.
1239@end deffn
1240
c519f823 1241@deffn {Procedure} play-music! music [#:optional loops=1]
b4f32490
KK
1242Play @var{music}, repeated @var{loops} times. @var{loops} may be @code{#f}, in
1243which case the music loops indefinitely.
1244@end deffn
1245
c519f823 1246@deffn {Procedure} set-music-volume! volume
b4f32490
KK
1247Set music loudness to @var{volume}, an integer in the range [0,128]. Return the
1248previous volume.
1249@end deffn
1250
c519f823 1251@deffn {Procedure} music-volume
b4f32490
KK
1252Return the music volume.
1253@end deffn
1254
c519f823 1255@deffn {Procedure} pause-music!
b4f32490
KK
1256Puase the music.
1257@end deffn
1258
c519f823 1259@deffn {Procedure} resume-music!
b4f32490
KK
1260Resume music playback.
1261@end deffn
1262
c519f823 1263@deffn {Procedure} rewind-music!
b4f32490
KK
1264Start music playback from the beginning. Rewinding is only supported for MOD,
1265OGG, MP3, and native MIDI music.
1266@end deffn
1267
c519f823 1268@deffn {Procedure} stop-music!
b4f32490
KK
1269Halt music playback.
1270@end deffn
1271
c519f823 1272@deffn {Procedure} music-playing?
b4f32490
KK
1273Return @code{#t} if music is currently playing.
1274@end deffn
1275
c519f823 1276@deffn {Procedure} music-paused?
b4f32490
KK
1277Return @code{#t} if music is currently paused.
1278@end deffn
1279
9ec24e3f
DT
1280@node Fonts
1281@section Fonts
1282
1283@example
b4f32490 1284(use-modules (sdl2 ttf))
9ec24e3f 1285@end example
b4f32490 1286
c519f823 1287@deffn {Procedure} ttf-init
b4f32490
KK
1288Initialize the TTF system.
1289@end deffn
1290
c519f823 1291@deffn {Procedure} ttf-quit
b4f32490
KK
1292Shut down and clean up the TTF system.
1293@end deffn
1294
c519f823 1295@deffn {Procedure} load-font file point-size
b4f32490
KK
1296Load TTF font from @var{file} and return a new font object whose glyph size is
1297@var{point-size}.
1298@end deffn
1299
c519f823 1300@deffn {Procedure} delete-font! font
b4f32490
KK
1301Delete the memory allocated for @var{font}.
1302@end deffn
1303
c519f823 1304@deffn {Procedure} font-height font
b4f32490
KK
1305Return the maximum height of @var{font}.
1306@end deffn
1307
c519f823 1308@deffn {Procedure} render-font-solid font text color
b4f32490
KK
1309Render @var{text}, a UTF-8 encoded string, using @var{font} and @var{color}, the
1310foreground color, and return a surface containing the results.
1311@end deffn
1312
c519f823 1313@deffn {Procedure} render-font-blended font text color
b4f32490
KK
1314Render @var{text}, a UTF-8 encoded string, using @var{font} and @var{color}, the
1315foreground color, and return a high-quality alpha-blended surface containing the
1316results.
1317@end deffn