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