Changeset 32988 in project


Ignore:
Timestamp:
12/17/15 09:30:43 (4 years ago)
Author:
John Croisant
Message:

sdl2: Major reorganization of sections.

Put related function bindings and types together, instead of
separating function bindings and types into separate sections.

I think this is a more natural and reader-friendly way to organize.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/sdl2

    r32987 r32988  
    163163== API
    164164
    165 === Conventions
     165=== About the API
     166
     167==== Conventions
    166168
    167169* Procedures names, including function bindings, are Scheme style.
     
    194196
    195197
    196 
    197 === Enums
     198==== Enums
    198199
    199200The sdl2 egg uses symbols instead of integer constants, for things like event types, keyboard keys, and init flags.
     
    206207
    207208
    208 
    209 === Function Bindings
    210 
    211 ==== Initialization and Clean Up
    212 
    213 <procedure>(set-main-ready!)</procedure>
    214 
    215 See [[https://wiki.libsdl.org/SDL_SetMainReady|SDL_SetMainReady]].
    216 
    217 You should call this soon after your program starts, '''before''' calling {{init!}}.
    218 See [[/egg/sdl2#ensuring-proper-clean-up|Ensuring Proper Clean Up]].
    219 
    220 
    221 <procedure>(init! #!optional flags-list)</procedure>
    222 
    223 Initialize SDL.
    224 You should call this soon after your program starts, '''after''' calling {{set-main-ready!}}.
    225 See [[/egg/sdl2#ensuring-proper-clean-up|Ensuring Proper Clean Up]].
    226 
    227 {{flags-list}} defaults to {{'(everything)}}. It must be a list of one or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#init-flags|init flag symbols]]:
    228 
    229 * {{'timer}}
    230 * {{'audio}}
    231 * {{'video}}
    232 * {{'joystick}}
    233 * {{'haptic}}
    234 * {{'game-controller}}
    235 * {{'events}}
    236 * {{'everything}}
    237 
    238 See [[https://wiki.libsdl.org/SDL_Init|SDL_Init]].
    239 
    240 Signals an exception of kind {{(exn sdl2)}} if initialization fails.
    241 
    242 
    243 <procedure>(init-subsystem! flags-list)</procedure>
    244 
    245 See [[https://wiki.libsdl.org/SDL_InitSubSystem|SDL_InitSubSystem]].
    246 
    247 {{flags-list}} must be a list of one or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#init-flags|init flag]] symbols.
    248 
    249 Signals an exception of kind {{(exn sdl2)}} if initialization fails.
    250 
    251 
    252 <procedure>(quit!)</procedure>
    253 
    254 Clean up SDL.
    255 You must make sure to call this before your program ends.
    256 See [[/egg/sdl2#ensuring-proper-clean-up|Ensuring Proper Clean Up]].
    257 
    258 See [[https://wiki.libsdl.org/SDL_Quit|SDL_Quit]].
    259 
    260 
    261 <procedure>(quit-subsystem! flags-list)</procedure>
    262 
    263 See [[https://wiki.libsdl.org/SDL_QuitSubSystem|SDL_QuitSubSystem]].
    264 
    265 {{flags-list}} must be a list of one or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#init-flags|init flag]] symbols.
    266 
    267 
    268 <procedure>(was-init #!optional flags-list) → list of symbols</procedure>
    269 
    270 See [[https://wiki.libsdl.org/SDL_WasInit|SDL_WasInit]].
    271 
    272 {{flags-list}} defaults to {{'(everything)}}. It must be a list of one or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#init-flags|init flag]] symbols.
    273 
    274 
    275 
    276 ==== Events
    277 
    278 <procedure>(event-state type) → boolean</procedure>
    279 <setter>(set! (event-state type) state) → boolean</setter>
    280 <setter>(event-state-set! type state) → boolean</setter>
    281 
    282 Get or set the state of the given event type.
    283 #t means the event type is enabled, so events of that type may appear on the event queue.
    284 #f means the event type is disabled, so events of that type will be automatically discarded.
    285 It is beneficial to your program's performance to disable event types that your program does not need.
    286 
    287 {{type}} must be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbol]] or corresponding integer.
    288 
    289 If you set an event type's state to #f, any events of that type already on the event queue will be immediately discarded.
    290 The setters return the previous state of the given event type.
    291 
    292 See [[https://wiki.libsdl.org/SDL_EventState|SDL_EventState]].
    293 
    294 
    295 <procedure>(flush-event! type)</procedure>
    296 <procedure>(flush-events! #!optional min-type max-type)</procedure>
    297 
    298 Remove all events on the event queue that match the given type or range of types.
    299 See [[https://wiki.libsdl.org/SDL_FlushEvent|SDL_FlushEvent]]
    300 and [[https://wiki.libsdl.org/SDL_FlushEvents|SDL_FlushEvents]].
    301 
    302 For {{flush-event!}}, {{type}} must be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbol]] or corresponding integer.
    303 
    304 For {{flush-events!}}, {{min-type}} and {{max-type}} specify the range of event types to remove.
    305 Events with a type outside of this range will not be removed.
    306 {{min-type}} and {{max-type}} must be [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbols]] or corresponding integers.
    307 {{min-type}} defaults to {{'first}} and {{max-type}} defaults to {{'last}}, which means all event types match by default.
    308 
    309 
    310 <procedure>(has-event? type) → boolean</procedure>
    311 <procedure>(has-events? #!optional min-type max-type) → boolean</procedure>
    312 
    313 Returns #t if the event queue currently has at least one event matching the given type or range of types.
    314 See [[https://wiki.libsdl.org/SDL_HasEvent|SDL_HasEvent]]
    315 and [[https://wiki.libsdl.org/SDL_HasEvents|SDL_HasEvents]].
    316 
    317 For {{has-event?}}, {{type}} must be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbol]] or corresponding integer.
    318 
    319 For {{has-events?}}, {{min-type}} and {{max-type}} specify the range of event types to consider.
    320 Events with a type outside of this range will not be considered.
    321 {{min-type}} and {{max-type}} must be [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbols]] or corresponding integers.
    322 {{min-type}} defaults to {{'first}} and {{max-type}} defaults to {{'last}}, which means all event types match by default.
    323 
    324 
    325 <procedure>(quit-requested?) → boolean</procedure>
    326 
    327 Returns #t if the event queue currently has at least one event of type {{'quit}}.
    328 See [[https://wiki.libsdl.org/SDL_QuitRequested|SDL_QuitRequested]].
    329 
    330 
    331 <procedure>(get-events! num #!optional min-type max-type) → list of sdl2:events</procedure>
    332 <procedure>(peek-events num #!optional min-type max-type) → list of sdl2:events</procedure>
    333 
    334 Get multiple matching events from the front of the event queue.
    335 Returns a list of managed sdl2:events.
    336 See [[https://wiki.libsdl.org/SDL_PeepEvents|SDL_PeepEvents]].
    337 
    338 * {{get-events!}} removes the returned events from the event queue.
    339 * {{peek-events}} does not remove the returned events from the event queue.
    340 
    341 {{num}} specifies the maximum number of events to return.
    342 This procedure may return fewer events if there are not enough matching events on the event queue.
    343 
    344 {{min-type}} and {{max-type}} specify the range of event types to return.
    345 Events with a type outside of this range will not be returned (they will remain on the queue).
    346 {{min-type}} and {{max-type}} must be [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbols]] or corresponding integers.
    347 {{min-type}} defaults to {{'first}} and {{max-type}} defaults to {{'last}}, which means all event types match by default.
    348 
    349 Both procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
    350 
    351 
    352 <procedure>(poll-event! #!optional result-event) → sdl2:event</procedure>
    353 
    354 Get the next event from the event queue.
    355 The returned event is removed from the event queue.
    356 See [[https://wiki.libsdl.org/SDL_PollEvent|SDL_PollEvent]].
    357 
    358 If {{result-event}} is omitted or #f, a new managed sdl2:event will be returned.
    359 If {{result-event}} is an sdl2:event, it will be modified and returned.
    360 This allows you to allocate a single event and reuse it many times in your event loop,
    361 so that your program does not create as much garbage for the garbage collector.
    362 
    363 
    364 <procedure>(pump-events!)</procedure>
    365 
    366 See [[https://wiki.libsdl.org/SDL_PumpEvents|SDL_PumpEvents]].
    367 
    368 
    369 <procedure>(push-event! event) → boolean</procedure>
    370 
    371 See [[https://wiki.libsdl.org/SDL_PushEvent|SDL_PushEvent]].
    372 
    373 Returns #t if the event was pushed onto the event queue, or #f if the event was discarded,
    374 e.g. because the event type is disabled (see {{event-state}}).
    375 
    376 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    377 
    378 
    379 <procedure>(wait-event! #!optional result-event) → sdl2:event</procedure>
    380 <procedure>(wait-event-timeout! timeout #!optional result-event) → sdl2:event or #f</procedure>
    381 
    382 Wait for the next event to appear on the event queue, then return it.
    383 The returned event will be removed from the event queue.
    384 If there is already an event on the event queue, it will be returned immediately.
    385 Otherwise, these procedures will block the current thread until the next event appears (or the timeout expires).
    386 
    387 * {{wait-event!}} will wait indefinitely for an event to appear.
    388 * {{wait-event-timeout!}} will stop waiting and return #f if no event appears within {{timeout}} milliseconds.
    389   (It may actually wait a few milliseconds longer than specified.
    390   You should not rely on its timing being very precise.)
    391 
    392 If {{result-event}} is omitted or #f, a new managed sdl2:event will be returned.
    393 If {{result-event}} is an sdl2:event, it will be modified and returned.
    394 This allows you to allocate a single event and reuse it many times in your event loop,
    395 so that your program does not create as much garbage for the garbage collector.
    396 
    397 These procedures are compatible with [[/manual/Unit srfi-18|SRFI-18]] multithreading.
    398 Only the current thread will block while waiting.
    399 Other threads will continue as normal.
    400 
    401 These procedures are inspired by (but do not actually use)
    402 [[https://wiki.libsdl.org/SDL_WaitEvent|SDL_WaitEvent]] and
    403 [[https://wiki.libsdl.org/SDL_WaitEventTimeout|SDL_WaitEventTimeout]].
    404 
    405 
    406 <procedure>(register-events! event-symbols) → list of pairs</procedure>
    407 
    408 Register zero or more symbols as new user event types.
    409 After registration, the given symbols may be used as event types, e.g. with {{event-type-set!}}.
    410 The symbols will be associated with the sdl2:user-event variant of sdl2:event.
    411 
    412 {{event-symbols}} must be a list of symbols that are not already being used as event types.
    413 If any symbol is already being used, or if any member of the list is not a symbol,
    414 an error will be signalled and none of the new event types will be registered.
    415 
    416 There are 32767 user event type numbers available to register.
    417 Each symbol in {{event-symbols}} will be assigned a sequential number.
    418 If there are not enough remaining numbers to register all the symbols in {{event-symbols}},
    419 this procedure will signal an exception of kind {{(exn sdl2)}}, and none of the new event types will be registered.
    420 
    421 This procedure returns a list of pairs, with the car of each pair being a new event type symbol, and the cdr of each pair being that symbol's assigned number.
    422 
    423 This procedure is based on [[https://wiki.libsdl.org/SDL_RegisterEvents|SDL_RegisterEvents]].
    424 
    425 
    426 
    427 ==== Joystick
    428 
    429 <procedure>(num-joysticks) → fixnum</procedure>
    430 
    431 See [[https://wiki.libsdl.org/SDL_NumJoysticks|SDL_NumJoysticks]].
    432 
    433 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    434 
    435 
    436 <procedure>(joystick-open! index) → sdl2:joystick</procedure>
    437 
    438 See [[https://wiki.libsdl.org/SDL_JoystickOpen|SDL_JoystickOpen]].
    439 
    440 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    441 
    442 
    443 <procedure>(joystick-close! joystick)</procedure>
    444 
    445 See [[https://wiki.libsdl.org/SDL_JoystickClose|SDL_JoystickClose]].
    446 
    447 
    448 <procedure>(joystick-update!)</procedure>
    449 
    450 See [[https://wiki.libsdl.org/SDL_JoystickUpdate|SDL_JoystickUpdate]].
    451 
    452 
    453 <procedure>(joystick-event-state) → boolean</procedure>
    454 <setter>(set! (joystick-event-state) state) → boolean</setter>
    455 <setter>(joystick-event-state-set! state) → boolean</setter>
    456 
    457 {{joystick-event-state}} returns #t if joystick events are currently enabled, or #f if they are disabled (i.e. all future joystick-related events will be ignored).
    458 
    459 The setters enable (if {{state}} is #t) or disable (if {{state}} is #f) joytsick events.
    460 '''WARNING:''' Calling the setters may delete all events currently in the event queue.
    461 
    462 These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
    463 
    464 See [[https://wiki.libsdl.org/SDL_JoystickEventState|SDL_JoystickEventState]].
    465 
    466 
    467 <procedure>(joystick-attached? joystick) → boolean</procedure>
    468 
    469 See [[https://wiki.libsdl.org/SDL_JoystickGetAttached|SDL_JoystickGetAttached]].
    470 
    471 
    472 <procedure>(joystick-num-axes joystick) → fixnum</procedure>
    473 
    474 See [[https://wiki.libsdl.org/SDL_JoystickNumAxes|SDL_JoystickNumAxes]].
    475 
    476 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    477 
    478 
    479 <procedure>(joystick-num-balls joystick) → fixnum</procedure>
    480 
    481 See [[https://wiki.libsdl.org/SDL_JoystickNumBalls|SDL_JoystickNumBalls]].
    482 
    483 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    484 
    485 
    486 <procedure>(joystick-num-buttons joystick) → fixnum</procedure>
    487 
    488 See [[https://wiki.libsdl.org/SDL_JoystickNumButtons|SDL_JoystickNumButtons]].
    489 
    490 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    491 
    492 
    493 <procedure>(joystick-num-hats joystick) → fixnum</procedure>
    494 
    495 See [[https://wiki.libsdl.org/SDL_JoystickNumHats|SDL_JoystickNumHats]].
    496 
    497 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    498 
    499 
    500 <procedure>(joystick-get-axis joystick axis-num) → fixnum</procedure>
    501 
    502 See [[https://wiki.libsdl.org/SDL_JoystickGetAxis|SDL_JoystickGetAxis]].
    503 
    504 Signals an exception of kind {{(exn bounds)}} if {{axis-num}} is less than 0 or greater than the last axis on the joystick (see {{joystick-num-axiss}}).
    505 
    506 
    507 <procedure>(joystick-get-ball joystick ball-num) → [dx dy]</procedure>
    508 
    509 See [[https://wiki.libsdl.org/SDL_JoystickGetBall|SDL_JoystickGetBall]].
    510 
    511 This procedure returns multiple values.
    512 
    513 Signals an exception of kind {{(exn bounds)}} if {{ball-num}} is less than 0 or greater than the last trackball on the joystick (see {{joystick-num-balls}}).
    514 Signals an exception of kind {{(exn sdl2)}} if some other error occurs.
    515 
    516 
    517 <procedure>(joystick-get-button joystick button-num) → boolean</procedure>
    518 
    519 See [[https://wiki.libsdl.org/SDL_JoystickGetButton|SDL_JoystickGetButton]].
    520 
    521 Signals an exception of kind {{(exn bounds)}} if {{button-num}} is less than 0 or greater than the last button on the joystick (see {{joystick-num-buttons}}).
    522 
    523 <procedure>(joystick-get-hat joystick hat-num) → symbol</procedure>
    524 <procedure>(joystick-get-hat-raw joystick hat-num) → fixnum</procedure>
    525 
    526 See [[https://wiki.libsdl.org/SDL_JoystickGetHat|SDL_JoystickGetHat]].
    527 
    528 * {{joystick-get-hat}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#joystick-hat-position|joystick hat position symbol]].
    529 * {{joystick-get-hat-raw}} returns an integer.
    530 
    531 Both procedures signal an exception of kind {{(exn bounds)}} if {{hat-num}} is less than 0 or greater than the last hat switch on the joystick (see {{joystick-num-hats}}).
    532 
    533 
    534 <procedure>(joystick-instance-id joystick) → fixnum</procedure>
    535 
    536 See [[https://wiki.libsdl.org/SDL_JoystickInstanceID|SDL_JoystickInstanceID]].
    537 
    538 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    539 
    540 
    541 <procedure>(joystick-name joystick) → string or #f</procedure>
    542 
    543 See [[https://wiki.libsdl.org/SDL_JoystickName|SDL_JoystickName]].
    544 
    545 Returns #f if no name can be found.
    546 
    547 
    548 <procedure>(joystick-name-for-index device-index) → string or #f</procedure>
    549 
    550 See [[https://wiki.libsdl.org/SDL_JoystickNameForIndex|SDL_JoystickNameForIndex]].
    551 
    552 Returns #f if no name can be found.
    553 
    554 
    555 <procedure>(joystick-get-device-guid device-index) → sdl2:joystick-guid</procedure>
    556 
    557 See [[https://wiki.libsdl.org/SDL_JoystickGetDeviceGUID|SDL_JoystickGetDeviceGUID]].
    558 
    559 Returns a new managed sdl2:joystick-guid.
    560 
    561 
    562 <procedure>(joystick-get-guid joystick) → sdl2:joystick-guid</procedure>
    563 
    564 See [[https://wiki.libsdl.org/SDL_JoystickGetGUID|SDL_JoystickGetGUID]].
    565 
    566 Returns a new managed sdl2:joystick-guid.
    567 
    568 
    569 <procedure>(joystick-get-guid-from-string str) → sdl2:joystick-guid</procedure>
    570 
    571 See [[https://wiki.libsdl.org/SDL_JoystickGetGUIDFromString|SDL_JoystickGetGUIDFromString]].
    572 
    573 Returns a new managed sdl2:joystick-guid.
    574 
    575 
    576 <procedure>(joystick-get-guid-string guid) → string</procedure>
    577 
    578 See [[https://wiki.libsdl.org/SDL_JoystickGetGUIDString|SDL_JoystickGetGUIDString]].
    579 
    580 
    581 
    582 ==== Keyboard
    583 
    584 <procedure>(get-key-from-name name-str) → symbol</procedure>
    585 <procedure>(get-key-from-name-raw name-str) → fixnum</procedure>
    586 
    587 See [[https://wiki.libsdl.org/SDL_GetKeyFromName|SDL_GetKeyFromName]].
    588 
    589 * {{get-key-from-name}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]].
    590 * {{get-key-from-name-raw}} returns an integer.
    591 
    592 
    593 <procedure>(get-key-from-scancode scancode) → symbol</procedure>
    594 <procedure>(get-key-from-scancode-raw scancode) → fixnum</procedure>
    595 
    596 See [[https://wiki.libsdl.org/SDL_GetKeyFromScancode|SDL_GetKeyFromScancode]].
    597 
    598 {{scancode}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]] or an integer representing a keyboard scancode.
    599 
    600 * {{get-key-from-scancode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]].
    601 * {{get-key-from-scancode-raw}} returns an integer.
    602 
    603 
    604 <procedure>(get-key-name key) → string</procedure>
    605 
    606 See [[https://wiki.libsdl.org/SDL_GetKeyName|SDL_GetKeyName]].
    607 
    608 {{key}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]] or an integer representing a keyboard keycode.
    609 
    610 
    611 <procedure>(get-scancode-from-name name-str) → symbol</procedure>
    612 <procedure>(get-scancode-from-name-raw name-str) → fixnum</procedure>
    613 
    614 See [[https://wiki.libsdl.org/SDL_GetScancodeFromName|SDL_GetScancodeFromName]].
    615 
    616 * {{get-scancode-from-name}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]].
    617 * {{get-scancode-from-name-raw}} returns an integer.
    618 
    619 
    620 <procedure>(get-scancode-from-key key) → symbol</procedure>
    621 <procedure>(get-scancode-from-key-raw key) → fixnum</procedure>
    622 
    623 See [[https://wiki.libsdl.org/SDL_GetScancodeFromKey|SDL_GetScancodeFromKey]].
    624 
    625 {{key}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]] or an integer representing a keyboard keycode.
    626 
    627 * {{get-scancode-from-key}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]].
    628 * {{get-scancode-from-key-raw}} returns an integer.
    629 
    630 
    631 <procedure>(get-scancode-name scancode) → string</procedure>
    632 
    633 See [[https://wiki.libsdl.org/SDL_GetScancodeName|SDL_GetScancodeName]].
    634 
    635 {{scancode}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]] or an integer representing a keyboard scancode.
    636 
    637 
    638 <procedure>(get-keyboard-focus) → sdl2:window</procedure>
    639 
    640 See [[https://wiki.libsdl.org/SDL_GetKeyboardFocus|SDL_GetKeyboardFocus]].
    641 
    642 
    643 <procedure>(scancode-pressed? scancode) → boolean</procedure>
    644 
    645 Returns #t if the keyboard key with the given scancode is currently
    646 being pressed.
    647 
    648 {{scancode}} must be either a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]] or an integer representing a scancode.
    649 
    650 This procedure queries SDL's internal keyboard state, which is tied to
    651 the event system. Call {{pump-events!}} to update the keyboard state.
    652 
    653 This procedure is based on
    654 [[https://wiki.libsdl.org/SDL_GetKeyboardState|SDL_GetKeyboardState]].
    655 
    656 
    657 <procedure>(mod-state) → list of symbols </procedure>
    658 <procedure>(mod-state-raw) → fixnum</procedure>
    659 <setter>(set! (mod-state) state)</setter>
    660 <setter>(mod-state-set! state)</setter>
    661 
    662 See [[https://wiki.libsdl.org/SDL_GetModState|SDL_GetModState]].
    663 
    664 * {{mod-state}} returns a list of zero or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-modifiers|keyboard modifier symbols]].
    665 * {{mod-state-raw}} returns an integer representing a bitfield of keyboard modifiers.
    666 * The setters accept either a list of zero or more symbols, or an integer.
    667 
    668 
    669 <setter>(text-input-rect-set! rect)</setter>
    670 
    671 {{rect}} can be an sdl2:rect or #f.
    672 
    673 See [[https://wiki.libsdl.org/SDL_SetTextInputRect|SDL_SetTextInputRect]].
    674 
    675 
    676 <procedure>(start-text-input!)</procedure>
    677 
    678 See [[https://wiki.libsdl.org/SDL_StartTextInput|SDL_StartTextInput]].
    679 
    680 
    681 <procedure>(stop-text-input!)</procedure>
    682 
    683 See [[https://wiki.libsdl.org/SDL_StopTextInput|SDL_StopTextInput]].
    684 
    685 
    686 <procedure>(text-input-active?) → boolean</procedure>
    687 
    688 See [[https://wiki.libsdl.org/SDL_IsTextInputActive|SDL_IsTextInputActive]].
    689 
    690 
    691 <procedure>(screen-keyboard-support?) → boolean</procedure>
    692 
    693 See [[https://wiki.libsdl.org/SDL_HasScreenKeyboardSupport|SDL_HasScreenKeyboardSupport]].
    694 
    695 
    696 <procedure>(screen-keyboard-shown? window) → boolean</procedure>
    697 
    698 See [[https://wiki.libsdl.org/SDL_IsScreenKeyboardShown|SDL_IsScreenKeyboardShown]].
    699 
    700 
    701 
    702 ==== OpenGL integration
    703 
    704 <procedure>(gl-create-context! window) → sdl2:gl-context</procedure>
    705 
    706 See [[https://wiki.libsdl.org/SDL_GL_CreateContext|SDL_GL_CreateContext]].
    707 
    708 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    709 
    710 
    711 <procedure>(gl-delete-context! gl-context)</procedure>
    712 
    713 See [[https://wiki.libsdl.org/SDL_GL_DeleteContext|SDL_GL_DeleteContext]].
    714 
    715 
    716 <procedure>(gl-make-current! window gl-context)</procedure>
    717 
    718 See [[https://wiki.libsdl.org/SDL_GL_MakeCurrent|SDL_GL_MakeCurrent]].
    719 
    720 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    721 
    722 
    723 <procedure>(gl-get-current-window) → sdl2:window</procedure>
    724 
    725 See [[https://wiki.libsdl.org/SDL_GL_GetCurrentWindow|SDL_GL_GetCurrentWindow]].
    726 
    727 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    728 
    729 
    730 <procedure>(gl-get-current-context) → sdl2:gl-context</procedure>
    731 
    732 See [[https://wiki.libsdl.org/SDL_GL_GetCurrentContext|SDL_GL_GetCurrentContext]].
    733 
    734 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    735 
    736 
    737 <procedure>(gl-attribute attr) → value</procedure>
    738 <setter>(set! (gl-attribute attr) value)</setter>
    739 <setter>(gl-attribute-set! attr value)</setter>
    740 
    741 See [[https://wiki.libsdl.org/SDL_GL_GetAttribute|SDL_GL_GetAttribute]]
    742 and [[https://wiki.libsdl.org/SDL_GL_SetAttribute|SDL_GL_SetAttribute]].
    743 
    744 {{attr}} must be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#opengl-attributes|OpenGL attribute symbol]] or corresponding integer.
    745 
    746 The value's type depends on {{attr}}:
    747 
    748 * If {{attr}} is {{'context-profile-mask}}, the value will be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#opengl-profiles|OpenGL profile symbol]]. (The setter also accepts a corresponding integer.)
    749 
    750 * If {{attr}} is {{'context-flags}}, the value will be a list of zero or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#opengl-context-flags|OpenGL context flag symbols]] will be returned. (The setter also accepts an equivalent integer bitfield.)
    751 
    752 * Otherwise, the value is an integer.
    753 
    754 The getter and the setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
    755 
    756 
    757 <procedure>(gl-reset-attributes!)</procedure>
    758 
    759 See [[https://wiki.libsdl.org/SDL_GL_ResetAttributes|SDL_GL_ResetAttributes]].
    760 
    761 Requires SDL 2.0.2 or higher. Signals an error if the compiled version
    762 of SDL is not high enough. Use {{(version-at-least? 2 0 2)}} to
    763 check before calling this procedure.
    764 
    765 
    766 <procedure>(gl-get-drawable-size window) → [width height]</procedure>
    767 
    768 See [[https://wiki.libsdl.org/SDL_GL_GetDrawableSize|SDL_GL_GetDrawableSize]].
    769 
    770 This procedure returns multiple values.
    771 
    772 Requires SDL 2.0.1 or higher. Signals an error if the compiled version
    773 of SDL is not high enough. Use {{(version-at-least? 2 0 1)}} to
    774 check before calling this procedure.
    775 
    776 
    777 <procedure>(gl-swap-window!)</procedure>
    778 
    779 See [[https://wiki.libsdl.org/SDL_GL_SwapWindow|SDL_GL_SwapWindow]].
    780 
    781 
    782 <procedure>(gl-swap-interval) → fixnum</procedure>
    783 <setter>(set! (gl-swap-interval) interval)</setter>
    784 <setter>(gl-set-swap-interval! interval)</setter>
    785 
    786 See [[https://wiki.libsdl.org/SDL_GL_GetSwapInterval|SDL_GL_GetSwapInterval]]
    787 and [[https://wiki.libsdl.org/SDL_GL_SetSwapInterval|SDL_GL_SetSwapInterval]].
    788 
    789 The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
    790 
    791 
    792 <procedure>(gl-extension-supported? name-string) → boolean</procedure>
    793 
    794 See [[https://wiki.libsdl.org/SDL_GL_ExtensionSupported|SDL_GL_ExtensionSupported]].
    795 
    796 
    797 
    798 ==== Palette
    799 
    800 <procedure>(palette-ref palette i) → sdl2:color</procedure>
    801 <setter>(set! (palette-ref palette i) color)</setter>
    802 <setter>(palette-set! palette i color)</setter>
    803 
    804 {{palette-ref}} returns a copy of the color at the given index of the palette, as a managed sdl2:color.
    805 
    806 The setters set the given index of the palette to a copy of the given sdl2:color.
    807 
    808 These procedures signal an exception of kind {{(exn bounds)}} if the given index is out of bounds.
    809 
    810 
    811 <procedure>(palette-colors palette) → vector of sdl2:colors </procedure>
    812 <procedure>(palette-colours palette) → vector of sdl2:colors </procedure>
    813 <setter>(set! (palette-colors palette) colors-vec) → boolean</setter>
    814 <setter>(set! (palette-colours palette) colors-vec) → boolean</setter>
    815 <setter>(palette-colors-set! colors-vec #!optional firstcolor) → boolean</setter>
    816 <setter>(palette-colours-set! colors-vec #!optional firstcolor) → boolean</setter>
    817 
    818 {{palette-colors}} and {{palette-colours}} return copies of all colors in the palette, as a Scheme vector of managed sdl2:colors.
    819 
    820 The setters set multiple colors in the palette to copies of the given colors.
    821 See [[https://wiki.libsdl.org/SDL_SetPaletteColors|SDL_SetPaletteColors]].
    822 
    823 {{colors-vec}} must be a Scheme vector of sdl2:colors.
    824 
    825 {{firstcolor}} specifies the first index of the palette to set.
    826 I.e., palette index {{firstcolor}} will be set to the first color in {{colors-vec}},
    827 palette index {{firstcolor + 1}} will be set to the second color, and so on.
    828 {{firstcolor}} defaults to 0.
    829 Signals an exception of kind {{(exn bounds)}} if {{firstcolor}} is out of bounds.
    830 
    831 The {{set!}} form cannot accept the {{firstcolor}} argument.
    832 
    833 The setters return #t if every color in {{colors-vec}} was used, or #f if some colors were not used,
    834 e.g. because there were more colors in the vector than could fit in the palette.
    835 
    836 
    837 
    838 ==== Pixel Format
    839 
    840 <procedure>(map-rgb pixel-format r g b) → fixnum</procedure>
    841 <procedure>(map-rgba pixel-format r g b a) → fixnum</procedure>
    842 
    843 See [[https://wiki.libsdl.org/SDL_MapRGB|SDL_MapRGB]]
    844 and [[https://wiki.libsdl.org/SDL_MapRGBA|SDL_MapRGBA]].
    845 
    846 
    847 <procedure>(get-rgb pixel pixel-format) → [r g b]</procedure>
    848 <procedure>(get-rgba pixel pixel-format) → [r g b a]</procedure>
    849 
    850 See [[https://wiki.libsdl.org/SDL_GetRGB|SDL_GetRGB]]
    851 and [[https://wiki.libsdl.org/SDL_GetRGBA|SDL_GetRGBA]].
    852 
    853 These procedures return multiple values.
    854 
    855 
    856 <procedure>(pixel-format-enum-to-masks format-enum) → [bpp rmask gmask bmask amask]</procedure>
    857 
    858 See [[https://wiki.libsdl.org/SDL_PixelFormatEnumToMasks|SDL_PixelFormatEnumToMasks]].
    859 
    860 {{format-enum}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]] or equivalent integer.
    861 
    862 This procedure returns multiple values:
    863 
    864 ; bpp   : The color depth (bits per pixel) of the format.
    865 ; rmask : The red mask of the format.
    866 ; gmask : The green mask of the format.
    867 ; bmask : The blue mask of the format.
    868 ; amask : The alpha mask of the format.
    869 
    870 Signals an exception of kind {{(exn sdl2)}} if conversion was not possible.
    871 
    872 
    873 
    874 ==== Rect / Point
    875 
    876 <procedure>(rect-empty? rect) → boolean</procedure>
    877 
    878 See [[https://wiki.libsdl.org/SDL_RectEmpty|SDL_RectEmpty]].
    879 
    880 
    881 <procedure>(enclose-points points #!optional clip result-rect) → [rect any-enclosed?]</procedure>
    882 
    883 See [[https://wiki.libsdl.org/SDL_EnclosePoints|SDL_EnclosePoints]].
    884 
    885 {{points}} must be a list of sdl2:points.
    886 
    887 {{clip}} must be either an sdl2:rect or #f (the default). If {{clip}}
    888 is an sdl2:rect, points outside the clip rect will be ignored.
    889 
    890 If {{result-rect}} is omitted or #f, a new managed sdl2:rect will be
    891 returned. If {{result-rect}} is an sdl2:rect, it will be modified and
    892 returned. {{result-rect}} must not be the same object as either
    893 {{rect1}} or {{rect2}}.
    894 
    895 This procedure returns multiple values:
    896 
    897 ; rect : An sdl2:rect that encloses all matching points. Possibly the same object as {{result-rect}}.
    898 ; any-enclosed? : #t if any points were enclosed, or #f if all points were clipped
    899 
    900 
    901 <procedure>(has-intersection? rect1 rect2) → boolean</procedure>
    902 
    903 See [[https://wiki.libsdl.org/SDL_HasIntersection|SDL_HasIntersection]].
    904 
    905 
    906 <procedure>(intersect-rect rect1 rect2 #!optional result-rect) → [rect intersect?]</procedure>
    907 
    908 See [[https://wiki.libsdl.org/SDL_IntersectRect|SDL_IntersectRect]].
    909 
    910 If {{result-rect}} is omitted or #f, a new managed sdl2:rect will be
    911 returned. If {{result-rect}} is an sdl2:rect, it will be modified and
    912 returned. {{result-rect}} must not be the same object as either
    913 {{rect1}} or {{rect2}}.
    914 
    915 This procedure returns multiple values:
    916 
    917 ; rect : An sdl2:rect of the intersection of {{rect1}} and {{rect2}}. Possibly the same object as {{result-rect}}.
    918 ; intersect? : #t if {{rect1}} and {{rect2}} intersect, otherwise #f
    919 
    920 
    921 <procedure>(intersect-rect-and-line rect x1 y1 x2 y2) → [intersect? x1-new y1-new x2-new y2-new]</procedure>
    922 
    923 See [[https://wiki.libsdl.org/SDL_IntersectRectAndLine|SDL_IntersectRectAndLine]].
    924 
    925 This procedure returns multiple values:
    926 
    927 ; intersect? : #t if the given line intersects with the rect
    928 ; x1-new : the x value of the point within rect that is closest to the first point
    929 ; y1-new : the y value ...
    930 ; x2-new : the x value of the point within rect that is closest to the second point
    931 ; y2-new : the y value ...
    932 
    933 
    934 <procedure>(union-rect rect1 rect2 #!optional result-rect) → rect</procedure>
    935 
    936 See [[https://wiki.libsdl.org/SDL_UnionRect|SDL_UnionRect]].
    937 
    938 If {{result-rect}} is omitted or #f, a new managed sdl2:rect will be
    939 returned. If {{result-rect}} is an sdl2:rect, it will be modified and
    940 returned. {{result-rect}} must not be the same object as either
    941 {{rect1}} or {{rect2}}.
    942 
    943 
    944 
    945 ==== RWops
    946 
    947 <procedure>(rw-from-file filepath) → sdl2:rwops</procedure>
    948 
    949 See [[https://wiki.libsdl.org/SDL_RWFromFile|SDL_RWFromFile]].
    950 
    951 You should close the sdl2:rwops when you are done with it, using
    952 {{rw-close!}} or one of the procedures that can automatically close
    953 the sdl2:rwops, such as {{load-bmp-rw}}.
    954 
    955 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    956 
    957 
    958 <procedure>(rw-from-const-mem pointer) → sdl2:rwops</procedure>
    959 
    960 See [[https://wiki.libsdl.org/SDL_RWFromConstMem|SDL_RWFromConstMem]].
    961 
    962 You should close the sdl2:rwops when you are done with it, using
    963 {{rw-close!}} or one of the procedures that can automatically close
    964 the sdl2:rwops, such as {{load-bmp-rw}}.
    965 
    966 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    967 
    968 
    969 <procedure>(rw-from-mem pointer) → sdl2:rwops</procedure>
    970 
    971 See [[https://wiki.libsdl.org/SDL_RWFromMem|SDL_RWFromMem]].
    972 
    973 You should close the sdl2:rwops when you are done with it, using
    974 {{rw-close!}} or one of the procedures that can automatically close
    975 the sdl2:rwops, such as {{load-bmp-rw}}.
    976 
    977 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    978 
    979 
    980 <procedure>(rw-from-blob blob) → sdl2:rwops</procedure>
    981 
    982 Create a new sdl2:rwops that accesses the memory of the given
    983 [[http://wiki.call-cc.org/manual/Unit%20library#blobs|blob]]. You
    984 should close the sdl2:rwops when you are done with it, using
    985 {{rw-close!}} or one of the procedures that can automatically close
    986 the sdl2:rwops, such as {{load-bmp-rw}}.
    987 
    988 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    989 
    990 You can also use this procedure to create a sdl2:rwops from a
    991 [[/manual/Unit srfi-4|SRFI-4]] numeric vector, by first converting it
    992 to a blob using e.g. {{u8vector->blob/shared}}.
    993 
    994 '''CAUTION:''' Creating a sdl2:rwops from a blob in CHICKEN-managed
    995 memory is unstable: the blob might be garbage collected or moved in
    996 memory, which would break the sdl2:rwops. To be safe, you should
    997 [[/manual/Unit lolevel#object-evict|evict]] the blob and create the
    998 sdl2:rwops from the evicted blob (not the original). You may wish to
    999 [[/manual/Unit lolevel#object-release|release]] the evicted blob after
    1000 you have closed the sdl2:rwops. Example:
    1001 
    1002 <enscript highlight="scheme">
    1003 (let* ((evicted-blob (object-evict '#${...}))
    1004        (rwops (sdl2:rw-from-blob evicted-blob))
    1005        (surf (sdl2:load-bmp-rw rwops #t)))
    1006   (object-release evicted-blob)
    1007   surf)
    1008 </enscript>
    1009 
    1010 
    1011 <procedure>(rw-from-string str) → sdl2:rwops</procedure>
    1012 
    1013 Create a new sdl2:rwops that accesses the memory of the given CHICKEN
    1014 Scheme string. You should close the sdl2:rwops when you are done with
    1015 it, using {{rw-close!}} or one of the procedures that can
    1016 automatically close the sdl2:rwops, such as {{load-bmp-rw}}.
    1017 
    1018 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    1019 
    1020 '''CAUTION:''' Creating a sdl2:rwops from a string in CHICKEN-managed
    1021 memory is unstable: the string might be garbage collected or moved in
    1022 memory, which would break the sdl2:rwops. To be safe, you should
    1023 [[/manual/Unit lolevel#object-evict|evict]] the string and create the
    1024 sdl2:rwops from the evicted string (not the original). You may wish to
    1025 [[/manual/Unit lolevel#object-release|release]] the evicted string
    1026 after you have closed the sdl2:rwops. Example:
    1027 
    1028 <enscript highlight="scheme">
    1029 (let* ((evicted-string (object-evict "..."))
    1030        (rwops (sdl2:rw-from-string evicted-string))
    1031        (surf (sdl2:load-bmp-rw rwops #t)))
    1032   (object-release evicted-string)
    1033   surf)
    1034 </enscript>
    1035 
    1036 
    1037 <procedure>(rw-close! rwops)</procedure>
    1038 
    1039 See [[https://wiki.libsdl.org/SDL_RWclose|SDL_RWclose]].
    1040 
    1041 Close and clean up the given sdl2:rwops. This frees the memory used by
    1042 the SDL_RWops struct itself, but does not free or release the pointer,
    1043 blob, or string that the sdl2:rwops was reading/writing from. (It does
    1044 close files opened with {{rw-from-file}}, though.)
    1045 
    1046 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    1047 
    1048 
    1049 
    1050 ==== Surface
    1051 
    1052 <procedure>(create-rgb-surface* flags width height depth rmask gmask bmask amask) → sdl2:surface</procedure>
    1053 
    1054 See [[https://wiki.libsdl.org/SDL_CreateRGBSurface|SDL_CreateRGBSurface]].
    1055 
    1056 Returns a new '''unmanaged''' sdl2:surface with the given properties.
    1057 You must call {{free-surface!}} when you are done with it.
    1058 
    1059 See {{make-surface}} for a more convenient interface.
    1060 
    1061 Signals an exception of kind {{(exn sdl2)}} if the surface cannot be created.
    1062 
    1063 
    1064 <procedure>(create-rgb-surface-from* pixels width height depth pitch rmask gmask bmask amask) → sdl2:surface</procedure>
    1065 
    1066 Returns a new '''unmanaged''' sdl2:surface with the given properties,
    1067 using existing pixel data (a pointer, e.g. from {{surface-pixels-raw}}).
    1068 You must call {{free-surface!}} when you are done with it.
    1069 
    1070 See [[https://wiki.libsdl.org/SDL_CreateRGBSurfaceFrom|SDL_CreateRGBSurfaceFrom]].
    1071 
    1072 Signals an exception of kind {{(exn sdl2)}} if the surface cannot be created.
    1073 
    1074 
    1075 <procedure>(convert-surface surface pixel-format) → sdl2:surface</procedure>
    1076 <procedure>(convert-surface* surface pixel-format) → sdl2:surface</procedure>
    1077 
    1078 Creates a copy of the given sdl2:surface, but converts it to the given sdl2:pixel-format.
    1079 
    1080 See [[https://wiki.libsdl.org/SDL_ConvertSurface|SDL_ConvertSurface]].
    1081 
    1082 * {{convert-surface}} returns a managed sdl2:surface.
    1083 * {{convert-surface*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
    1084 
    1085 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    1086 
    1087 
    1088 <procedure>(load-bmp path-string) → sdl2:surface</procedure>
    1089 <procedure>(load-bmp* filepath) → sdl2:surface</procedure>
    1090 
    1091 See [[https://wiki.libsdl.org/SDL_LoadBMP|SDL_LoadBMP]].
    1092 
    1093 Attempts to load a BMP image file. Returns a sdl2:surface containing
    1094 the image data, or #f if the image could not be loaded.
    1095 
    1096 '''NOTE:''' This procedure only supports certain kinds of BMP image.
    1097 Use the [[/egg/sdl2-image|sdl2-image egg]] for better BMP support,
    1098 plus support for loading other image formats like JPG, PNG, and GIF.
    1099 
    1100 * {{load-bmp}} returns a managed sdl2:surface.
    1101 * {{load-bmp*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
    1102 
    1103 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    1104 
    1105 
    1106 <procedure>(load-bmp-rw rwops #!optional close?) → sdl2:surface</procedure>
    1107 <procedure>(load-bmp-rw* rwops #!optional close?) → sdl2:surface</procedure>
    1108 
    1109 See [[https://wiki.libsdl.org/SDL_LoadBMP_RW|SDL_LoadBMP_RW]].
    1110 
    1111 Attempts to load a BMP image from the given sdl2:rwops. Returns a
    1112 sdl2:surface containing the image data, or #f if the image could not
    1113 be loaded.
    1114 
    1115 If {{close?}} is #t, {{rwops}} will be automatically closed (see
    1116 {{rw-close!}}) after the image is loaded. If {{close?}} is #f or
    1117 omitted, {{rwops}} will not be closed.
    1118 
    1119 '''NOTE:''' This procedure only supports certain kinds of BMP image.
    1120 Use the [[/egg/sdl2-image|sdl2-image egg]] for better BMP support,
    1121 plus support for loading other image formats like JPG, PNG, and GIF.
    1122 
    1123 * {{load-bmp-rw}} returns a managed sdl2:surface.
    1124 * {{load-bmp-rw*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
    1125 
    1126 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    1127 
    1128 
    1129 <procedure>(save-bmp! surface filepath) → fixnum</procedure>
    1130 
    1131 See [[https://wiki.libsdl.org/SDL_SaveBMP|SDL_SaveBMP]].
    1132 
    1133 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    1134 
    1135 
    1136 <procedure>(save-bmp-rw! surface rwops #!optional close?) → fixnum</procedure>
    1137 
    1138 See [[https://wiki.libsdl.org/SDL_SaveBMP_RW|SDL_SaveBMP_RW]].
    1139 
    1140 If {{close?}} is #t, {{rwops}} will be automatically closed (see
    1141 {{rw-close!}}) after the image is loaded. If {{close?}} is #f or
    1142 omitted, {{rwops}} will not be closed.
    1143 
    1144 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    1145 
    1146 
    1147 <procedure>(lock-surface! surface) → fixnum</procedure>
    1148 <procedure>(unlock-surface! surface)</procedure>
    1149 
    1150 See [[https://wiki.libsdl.org/SDL_LockSurface|SDL_LockSurface]]
    1151 and [[https://wiki.libsdl.org/SDL_UnlockSurface|SDL_UnlockSurface]].
    1152 
    1153 {{lock-surface!}} signals an exception of kind {{(exn sdl2)}} if an error occurs.
    1154 
    1155 
    1156 <procedure>(must-lock? surface) → boolean</procedure>
    1157 
    1158 See [[https://wiki.libsdl.org/SDL_MUSTLOCK|SDL_MUSTLOCK]].
    1159 
    1160 
    1161 <procedure>(blit-surface! src src-rect dest dest-rect) → fixnum</procedure>
    1162 
    1163 See [[https://wiki.libsdl.org/SDL_BlitSurface|SDL_BlitSurface]].
    1164 
    1165 May modify dest-rect.
    1166 
    1167 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    1168 
    1169 
    1170 <procedure>(blit-scaled! src src-rect dest dest-rect) → fixnum</procedure>
    1171 
    1172 See [[https://wiki.libsdl.org/SDL_BlitScaled|SDL_BlitScaled]].
    1173 
    1174 May modify dest-rect.
    1175 
    1176 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    1177 
    1178 
    1179 <procedure>(fill-rect! surface rect color) → fixnum</procedure>
    1180 
    1181 See [[https://wiki.libsdl.org/SDL_FillRect|SDL_FillRect]].
    1182 
    1183 {{rect}} may be an sdl2:rect to fill part of the surface, or #f to fill
    1184 the entire surface.
    1185 
    1186 {{color}} may be an sdl2:color or a mapped color (an integer, like
    1187 returned by {{map-rgba}}).
    1188 
    1189 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    1190 
    1191 
    1192 <procedure>(fill-rects! surface rects color) → fixnum</procedure>
    1193 
    1194 See [[https://wiki.libsdl.org/SDL_FillRects|SDL_FillRects]].
    1195 
    1196 {{rects}} must be a list of sdl2:rects.
    1197 
    1198 {{color}} may be an sdl2:color or a mapped color (an integer, like
    1199 returned by {{map-rgba}}).
    1200 
    1201 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    1202 
    1203 
    1204 <procedure>(surface-ref surface x y) → sdl2:color</procedure>
    1205 <procedure>(surface-ref-raw surface x y) → fixnum</procedure>
    1206 <setter>(set! (surface-ref surface x y) color)</setter>
    1207 <setter>(surface-set! surface x y color)</setter>
    1208 
    1209 Get or set the color of the specified pixel on the surface.
    1210 
    1211 * {{surface-ref}} returns an sdl2:color.
    1212 * {{surface-ref-raw}} returns a mapped color (an integer). You can use {{get-rgba}} to convert the mapped color to color fields.
    1213 * The setters accept either an sdl2:color or a mapped color.
    1214 
    1215 These procedures automatically lock and unlock the surface if needed.
    1216 They signal an exception of kind {{(exn sdl2)}} if the surface cannot be locked.
    1217 
    1218 These procedures signal an exception of kind {{(exn bounds)}} if {{x}} or {{y}} is out of bounds.
    1219 
    1220 The setters ignore the surface's clip rect.
    1221 
    1222 
    1223 <procedure>(surface-clip-rect surface) → sdl2:rect</procedure>
    1224 <setter>(set! (surface-clip-rect surface) rect) → boolean</setter>
    1225 <setter>(surface-clip-rect-set! surface rect) → boolean</setter>
    1226 
    1227 {{surface-clip-rect}} returns a copy of the surface's clip rect.
    1228 See [[https://wiki.libsdl.org/SDL_GetClipRect|SDL_GetClipRect]].
    1229 
    1230 The setters sets the surface's clip rect to a copy of the given rect.
    1231 {{rect}} may be #f, which disables clipping.
    1232 See [[https://wiki.libsdl.org/SDL_SetClipRect|SDL_SetClipRect]].
    1233 
    1234 The setters return #t if the given rect intersects the surface at all, or #f if the rect is out of bounds (completely clips out the surface).
    1235 
    1236 
    1237 <procedure>(surface-color-key surface) → sdl2:color or #f</procedure>
    1238 <procedure>(surface-colour-key surface) → sdl2:color or #f</procedure>
    1239 <procedure>(surface-color-key-raw surface) → fixnum or #f</procedure>
    1240 <procedure>(surface-colour-key-raw surface) → fixnum or #f</procedure>
    1241 <setter>(set! (surface-color-key surface) color)</setter>
    1242 <setter>(set! (surface-colour-key surface) color)</setter>
    1243 <setter>(surface-color-key-set! surface color)</setter>
    1244 <setter>(surface-colour-key-set! surface color)</setter>
    1245 
    1246 Get or set the sdl2:surface's color key.
    1247 
    1248 See [[https://wiki.libsdl.org/SDL_GetColorKey|SDL_GetColorKey]]
    1249 and [[https://wiki.libsdl.org/SDL_SetColorKey|SDL_SetColorKey]].
    1250 
    1251 * {{surface-color-key}} and {{surface-colour-key}} return an sdl2:color if the surface has a color key, or #f if the surface does not have a color key.
    1252 * {{surface-color-key-raw}} and {{surface-colour-key-raw}} return a mapped color (an integer) if the surface has a color key, or #f if the surface does not have a color key.
    1253 * The setters accept either an sdl2:color, a mapped color (an integer), or #f to disable color keying.
    1254 
    1255 These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
    1256 
    1257 
    1258 <procedure>(surface-alpha-mod surface) → fixnum</procedure>
    1259 <setter>(set! (surface-alpha-mod surface) mod) → fixnum</setter>
    1260 <setter>(surface-alpha-mod-set! surface mod) → fixnum</setter>
    1261 
    1262 See [[https://wiki.libsdl.org/SDL_GetSurfaceAlphaMod|SDL_GetSurfaceAlphaMod]]
    1263 and [[https://wiki.libsdl.org/SDL_SetSurfaceAlphaMod|SDL_SetSurfaceAlphaMod]].
    1264 
    1265 These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
    1266 
    1267 
    1268 <procedure>(surface-blend-mode surface) → symbol</procedure>
    1269 <procedure>(surface-blend-mode-raw surface) → fixnum</procedure>
    1270 <setter>(set! (surface-blend-mode surface) mode)</setter>
    1271 <setter>(surface-blend-mode-set! surface mode)</setter>
    1272 
    1273 See [[https://wiki.libsdl.org/SDL_GetSurfaceBlendMode|SDL_GetSurfaceBlendMode]]
    1274 and [[https://wiki.libsdl.org/SDL_SetSurfaceBlendMode|SDL_SetSurfaceBlendMode]].
    1275 
    1276 * {{surface-blend-mode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-mode|blend mode symbol]]:
    1277 ** {{'none}}
    1278 ** {{'blend}}
    1279 ** {{'add}}
    1280 ** {{'mod}}
    1281 * {{surface-blend-mode-raw}} returns an integer.
    1282 * The setters accept either a symbol or integer.
    1283 
    1284 These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
    1285 
    1286 
    1287 
    1288 <procedure>(surface-color-mod surface) → [r g b]</procedure>
    1289 <procedure>(surface-colour-mod surface) → [r g b]</procedure>
    1290 <setter>(set! (surface-color-mod surface) rgb)</setter>
    1291 <setter>(set! (surface-colour-mod surface) rgb)</setter>
    1292 <setter>(surface-color-mod-set! surface rgb)</setter>
    1293 <setter>(surface-colour-mod-set! surface rgb)</setter>
    1294 
    1295 See [[https://wiki.libsdl.org/SDL_GetSurfaceColorMod|SDL_GetSurfaceColorMod]]
    1296 and [[https://wiki.libsdl.org/SDL_SetSurfaceColorMod|SDL_SetSurfaceColorMod]].
    1297 
    1298 {{surface-color-mod}} and {{surface-colour-mod}} return multiple values.
    1299 
    1300 The setters accept either a list {{(r g b)}} of color values, or an sdl2:color (the sdl2:color's "a" field will be ignored).
    1301 
    1302 These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
    1303 
    1304 
    1305 <procedure>(surface-palette surface) → sdl2:palette or #f</procedure>
    1306 <setter>(set! (surface-palette surface) palette)</setter>
    1307 <setter>(surface-palette-set! surface palette)</setter>
    1308 
    1309 {{surface-palette}} returns the surface's palette, or #f if it has no palette.
    1310 It is equivalent to {{(compose pixel-format-palette surface-format)}}.
    1311 
    1312 The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
    1313 
    1314 See [[https://wiki.libsdl.org/SDL_SetSurfacePalette|SDL_SetSurfacePalette]].
    1315 
    1316 
    1317 <setter>(surface-rle-set! surface enable?)</setter>
    1318 
    1319 Enable RLE acceleration if {{enable?}} is #t, or disable RLE acceleration if {{enable?}} is #f.
    1320 See [[https://wiki.libsdl.org/SDL_SetSurfaceRLE|SDL_SetSurfaceRLE]].
    1321 
    1322 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    1323 
    1324 
    1325 <procedure>(rotate-surface-90 surface turns) → sdl2:surface</procedure>
    1326 
    1327 Return a copy of the given surface rotated by the given number of 90º clockwise turns.
    1328 {{turns}} must be an integer.
    1329 For example:
    1330 
    1331 * {{turns}} 0 means no rotation
    1332 * {{turns}} 1 means 90º clockwise rotation
    1333 * {{turns}} 2 means 180º rotation
    1334 * {{turns}} 3 (or -1) means 270º clockwise (i.e. 90º counter-clockwise) rotation
    1335 
    1336 If the given surface has a palette, the new surface will share the same palette.
    1337 
    1338 All the procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
    1339 
    1340 
    1341 <procedure>(flip-surface surface flip-x? flip-y?) → sdl2:surface</procedure>
    1342 
    1343 Return a copy of the given surface flipped on the X (horizontal) and/or Y (vertical) axes.
    1344 If the given surface has a palette, the new surface will share the same palette.
    1345 
    1346 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    1347 
    1348 
    1349 
    1350 ==== Timer
    1351 
    1352 <procedure>(delay! milliseconds)</procedure>
    1353 
    1354 See [[https://wiki.libsdl.org/SDL_Delay|SDL_Delay]].
    1355 
    1356 '''CAUTION:''' This procedure is not compatible with [[/manual/Unit srfi-18|SRFI-18]]
    1357 threads. It will cause '''all threads to sleep''' for the given
    1358 duration. If you are using multiple threads, you should instead call
    1359 SRFI-18's {{thread-sleep!}}, which will cause only the current thread
    1360 to sleep. For example, call {{(thread-sleep! 0.025)}} instead of
    1361 {{(delay! 25)}}.
    1362 
    1363 
    1364 <procedure>(get-ticks) → fixnum</procedure>
    1365 
    1366 See [[https://wiki.libsdl.org/SDL_GetTicks|SDL_GetTicks]].
    1367 
    1368 
    1369 <procedure>(get-performance-counter) → fixnum</procedure>
    1370 
    1371 See [[https://wiki.libsdl.org/SDL_GetPerformanceCounter|SDL_GetPerformanceCounter]].
    1372 
    1373 
    1374 <procedure>(get-performance-frequency) → fixnum</procedure>
    1375 
    1376 See [[https://wiki.libsdl.org/SDL_GetPerformanceFrequency|SDL_GetPerformanceFrequency]].
    1377 
    1378 
    1379 
    1380 ==== Version
    1381 
    1382 <procedure>(version-at-least? major minor patch) → boolean</procedure>
    1383 
    1384 See [[https://wiki.libsdl.org/SDL_VERSION_ATLEAST|SDL_VERSION_ATLEAST]].
    1385 
    1386 Returns #t if the sdl2 egg was compiled with a version of SDL at least as high as specified.
    1387 For example, {{(version-at-least? 2 0 1)}} returns #t if the sdl2 egg was compiled with SDL 2.0.1 or higher.
    1388 
    1389 Some SDL features are only available after a certain version, so you can use this procedure to check whether the feature is available.
    1390 
    1391 
    1392 <procedure>(compiled-version) → list of fixnums</procedure>
    1393 <procedure>(current-version) → list of fixnums</procedure>
    1394 
    1395 Returns a list of three nonnegative integers, indicating a version number of SDL.
    1396 For example, the list {{(2 0 3)}} indicates SDL 2.0.3.
    1397 
    1398 * {{compiled-version}} returns the version of SDL that the sdl2 egg was compiled with.
    1399 * {{current-version}} returns the version of SDL that the sdl2 egg is currently using.
    1400 
    1401 For example, the user may have compiled the sdl2 egg with SDL 2.0.3, then later upgraded SDL to 2.1.0, but not yet recompiled the sdl2 egg with the new version.
    1402 In such a case, {{compiled-version}} would return {{(2 0 3)}}, and {{current-version}} would return {{(2 1 0)}}.
    1403 But, features from the new version would not be available until the user recompiles the sdl2 egg.
    1404 
    1405 See [[https://wiki.libsdl.org/SDL_VERSION|SDL_VERSION]]
    1406 and [[https://wiki.libsdl.org/SDL_GetVersion|SDL_GetVersion]].
    1407 
    1408 
    1409 
    1410 ==== Touch / Gesture
    1411 
    1412 <procedure>(get-num-touch-devices) → fixnum</procedure>
    1413 
    1414 See [[https://wiki.libsdl.org/SDL_GetNumTouchDevices|SDL_GetNumTouchDevices]].
    1415 
    1416 
    1417 <procedure>(get-touch-device device-id) → fixnum</procedure>
    1418 
    1419 See [[https://wiki.libsdl.org/SDL_GetTouchDevice|SDL_GetTouchDevice]].
    1420 
    1421 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    1422 
    1423 
    1424 <procedure>(get-num-touch-fingers touch-id) → fixnum</procedure>
    1425 
    1426 See [[https://wiki.libsdl.org/SDL_GetNumTouchFingers|SDL_GetNumTouchFingers]].
    1427 
    1428 
    1429 <procedure>(get-touch-finger touch-id index) → sdl2:finger</procedure>
    1430 
    1431 See [[https://wiki.libsdl.org/SDL_GetTouchFinger|SDL_GetTouchFinger]].
    1432 
    1433 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    1434 
    1435 
    1436 
    1437 ==== Window
    1438 
    1439 <procedure>(create-window! title x y w h #!optional flags) → sdl2:window</procedure>
    1440 
    1441 See [[https://wiki.libsdl.org/SDL_CreateWindow|SDL_CreateWindow]].
    1442 
    1443 {{x}} and {{y}} can be integers, the symbol {{'centered}}, or the symbol {{'undefined}}.
    1444 
    1445 {{flags}} defaults to {{'()}}. It must be a list of zero or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#window-flags|window flag symbols]] (or an equivalent integer bitfield):
    1446 
    1447 * {{'fullscreen}}
    1448 * {{'fullscreen-desktop}}
    1449 * {{'opengl}}
    1450 * {{'shown}}
    1451 * {{'hidden}}
    1452 * {{'borderless}}
    1453 * {{'resizable}}
    1454 * {{'minimized}}
    1455 * {{'maximized}}
    1456 * {{'input-grabbed}}
    1457 * {{'input-focus}}
    1458 * {{'mouse-focus}}
    1459 * {{'foreign}}
    1460 
    1461 
    1462 <procedure>(get-window-from-id id) → sdl2:window</procedure>
    1463 
    1464 See [[https://wiki.libsdl.org/SDL_GetWindowFromID|SDL_GetWindowFromID]].
    1465 
    1466 
    1467 <procedure>(destroy-window! window)</procedure>
    1468 
    1469 See [[https://wiki.libsdl.org/SDL_DestroyWindow|SDL_DestroyWindow]].
    1470 
    1471 
    1472 <procedure>(update-window-surface! window)</procedure>
    1473 
    1474 See [[https://wiki.libsdl.org/SDL_UpdateWindowSurface|SDL_UpdateWindowSurface]].
    1475 
    1476 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    1477 
    1478 
    1479 <procedure>(update-window-surface-rects! window rects)</procedure>
    1480 
    1481 See [[https://wiki.libsdl.org/SDL_UpdateWindowSurfaceRects|SDL_UpdateWindowSurfaceRects]].
    1482 
    1483 {{rects}} must be a list of sdl2:rects.
    1484 
    1485 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    1486 
    1487 
    1488 <procedure>(show-window! window)</procedure>
    1489 
    1490 See [[https://wiki.libsdl.org/SDL_ShowWindow|SDL_ShowWindow]].
    1491 
    1492 
    1493 <procedure>(hide-window! window)</procedure>
    1494 
    1495 See [[https://wiki.libsdl.org/SDL_HideWindow|SDL_HideWindow]].
    1496 
    1497 
    1498 <procedure>(maximize-window! window)</procedure>
    1499 
    1500 See [[https://wiki.libsdl.org/SDL_MaximizeWindow|SDL_MaximizeWindow]].
    1501 
    1502 
    1503 <procedure>(minimize-window! window)</procedure>
    1504 
    1505 See [[https://wiki.libsdl.org/SDL_MinimizeWindow|SDL_MinimizeWindow]].
    1506 
    1507 
    1508 <procedure>(raise-window! window)</procedure>
    1509 
    1510 See [[https://wiki.libsdl.org/SDL_RaiseWindow|SDL_RaiseWindow]].
    1511 
    1512 
    1513 <procedure>(restore-window! window)</procedure>
    1514 
    1515 See [[https://wiki.libsdl.org/SDL_RestoreWindow|SDL_RestoreWindow]].
    1516 
    1517 
    1518 <procedure>(window-bordered? window) → boolean</procedure>
    1519 <setter>(set! (window-bordered? window) bordered)</setter>
    1520 <setter>(window-bordered-set! window bordered)</setter>
    1521 
    1522 Get or set whether the window has a border (window decoration).
    1523 #t means the window has a border, #f means the window is borderless.
    1524 
    1525 Setting this to #f has essentially the same effect as passing the {{'borderless}} flag to {{create-window!}} when creating the window.
    1526 
    1527 See [[https://wiki.libsdl.org/SDL_SetWindowBordered|SDL_SetWindowBordered]].
    1528 
    1529 
    1530 <procedure>(window-brightness window) → float</procedure>
    1531 <setter>(set! (window-brightness window) brightness)</setter>
    1532 <setter>(window-brightness-set! window brightness)</setter>
    1533 
    1534 See [[https://wiki.libsdl.org/SDL_GetWindowBrightness|SDL_GetWindowBrightness]]
    1535 and [[https://wiki.libsdl.org/SDL_SetWindowBrightness|SDL_SetWindowBrightness]].
    1536 
    1537 The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
    1538 
    1539 
    1540 <procedure>(window-display-index window) → fixnum</procedure>
    1541 
    1542 See [[https://wiki.libsdl.org/SDL_GetWindowDisplayIndex|SDL_GetWindowDisplayIndex]].
    1543 
    1544 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    1545 
    1546 
    1547 <procedure>(window-display-mode window) → sdl2:display-mode</procedure>
    1548 <setter>(set! (window-display-mode window) display-mode)</setter>
    1549 <setter>(window-display-mode-set! window display-mode)</setter>
    1550 
    1551 See [[https://wiki.libsdl.org/SDL_GetWindowDisplayMode|SDL_GetWindowDisplayMode]]
    1552 and [[https://wiki.libsdl.org/SDL_SetWindowDisplayMode|SDL_SetWindowDisplayMode]].
    1553 
    1554 These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
    1555 
    1556 
    1557 <procedure>(window-flags window) → list of symbols</procedure>
    1558 <procedure>(window-flags-raw window) → fixnum</procedure>
    1559 
    1560 See [[https://wiki.libsdl.org/SDL_GetWindowFlags|SDL_GetWindowFlags]].
    1561 
    1562 * {{window-flags}} returns a list of [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#window-flags|window flag symbols]].
    1563 * {{window-flags-raw}} returns an integer bitfield.
    1564 
    1565 
    1566 <procedure>(window-fullscreen window) → symbol or #f</procedure>
    1567 <setter>(set! (window-fullscreen window) mode)</setter>
    1568 <setter>(window-fullscreen-set! window mode)</setter>
    1569 
    1570 Get or set the sdl2:window's fullscreen mode.
    1571 See [[https://wiki.libsdl.org/SDL_SetWindowFullscreen|SDL_SetWindowFullscreen]].
    1572 
    1573 {{window-fullscreen}} returns one of the following values:
    1574 
    1575 * {{'fullscreen}} means "real" fullscreen mode
    1576 * {{'fullscreen-desktop}} means "fake" fullscreen mode that takes the size of the desktop
    1577 * {{#f}} means windowed (non-fullscreen) mode
    1578 
    1579 The setters accept any of the above values, or #t (which means the same as {{'fullscreen}}), or an equivalent integer value.
    1580 
    1581 The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
    1582 
    1583 
    1584 <procedure>(window-grab? window) → boolean</procedure>
    1585 <setter>(set! (window-grab? window) grab?)</setter>
    1586 <setter>(window-grab-set! window grab?)</setter>
    1587 
    1588 See [[https://wiki.libsdl.org/SDL_GetWindowGrab|SDL_GetWindowGrab]]
    1589 and [[https://wiki.libsdl.org/SDL_SetWindowGrab|SDL_SetWindowGrab]].
    1590 
    1591 
    1592 <setter>(window-icon-set! window icon-surface)</setter>
    1593 
    1594 See [[https://wiki.libsdl.org/SDL_SetWindowIcon|SDL_SetWindowIcon]].
    1595 
    1596 
    1597 <procedure>(window-id window) → fixnum</procedure>
    1598 
    1599 See [[https://wiki.libsdl.org/SDL_GetWindowID|SDL_GetWindowID]].
    1600 
    1601 
    1602 <procedure>(window-maximum-size window) → [width height]</procedure>
    1603 <setter>(set! (window-maximum-size window) size)</setter>
    1604 <setter>(window-maximum-size-set! window size)</setter>
    1605 
    1606 See [[https://wiki.libsdl.org/SDL_GetWindowMaximumSize|SDL_GetWindowMaximumSize]]
    1607 and [[https://wiki.libsdl.org/SDL_SetWindowMaximumSize|SDL_SetWindowMaximumSize]].
    1608 
    1609 {{window-maximum-size}} returns multiple values.
    1610 
    1611 The setters accept a list of integers {{(width height)}}.
    1612 
    1613 
    1614 <procedure>(window-minimum-size window) → [width height]</procedure>
    1615 <setter>(set! (window-minimum-size window) size)</setter>
    1616 <setter>(window-minimum-size-set! window size)</setter>
    1617 
    1618 See [[https://wiki.libsdl.org/SDL_GetWindowMinimumSize|SDL_GetWindowMinimumSize]]
    1619 and [[https://wiki.libsdl.org/SDL_SetWindowMinimumSize|SDL_SetWindowMinimumSize]].
    1620 
    1621 {{window-minimum-size}} returns multiple values.
    1622 
    1623 The setters accept a list of integers {{(width height)}}.
    1624 
    1625 
    1626 <procedure>(window-pixel-format window) → symbol</procedure>
    1627 <procedure>(window-pixel-format-raw window) → fixnum</procedure>
    1628 
    1629 Returns a symbol or integer indicating the given window's pixel format.
    1630 See [[https://wiki.libsdl.org/SDL_GetWindowPixelFormat|SDL_GetWindowPixelFormat]].
    1631 
    1632 * {{window-pixel-format}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]].
    1633 * {{window-pixel-format-raw}} returns an integer.
    1634 
    1635 
    1636 <procedure>(window-position window) → [x y]</procedure>
    1637 <setter>(set! (window-position window) pos)</setter>
    1638 <setter>(window-position-set! window pos)</setter>
    1639 
    1640 See [[https://wiki.libsdl.org/SDL_GetWindowPosition|SDL_GetWindowPosition]]
    1641 and [[https://wiki.libsdl.org/SDL_SetWindowPosition|SDL_SetWindowPosition]].
    1642 
    1643 {{window-position}} returns multiple values.
    1644 
    1645 The setters accept a list of integers {{(x y)}}.
    1646 
    1647 
    1648 <procedure>(window-size window) → [width height]</procedure>
    1649 <setter>(set! (window-size window) size)</setter>
    1650 <setter>(window-size-set! window size)</setter>
    1651 
    1652 See [[https://wiki.libsdl.org/SDL_GetWindowSize|SDL_GetWindowSize]]
    1653 and [[https://wiki.libsdl.org/SDL_SetWindowSize|SDL_SetWindowSize]].
    1654 
    1655 {{window-size}} returns multiple values.
    1656 
    1657 The setters accept a list of integers {{(width height)}}.
    1658 
    1659 
    1660 <procedure>(window-surface window) → sdl2:surface</procedure>
    1661 
    1662 See [[https://wiki.libsdl.org/SDL_GetWindowSurface|SDL_GetWindowSurface]].
    1663 
    1664 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    1665 
    1666 
    1667 <procedure>(window-title window) → string</procedure>
    1668 <setter>(set! (window-title window) title)</setter>
    1669 <setter>(window-title-set! window title)</setter>
    1670 
    1671 See [[https://wiki.libsdl.org/SDL_GetWindowTitle|SDL_GetWindowTitle]]
    1672 and [[https://wiki.libsdl.org/SDL_SetWindowTitle|SDL_SetWindowTitle]].
    1673 
    1674 
    1675 
    1676 ==== Miscellaneous
    1677 
    1678 <procedure>(clear-error!)</procedure>
    1679 
    1680 See [[https://wiki.libsdl.org/SDL_ClearError|SDL_ClearError]].
    1681 
    1682 
    1683 <procedure>(get-error) → string</procedure>
    1684 
    1685 See [[https://wiki.libsdl.org/SDL_GetError|SDL_GetError]].
    1686 
    1687 
    1688 <procedure>(set-error! message)</procedure>
    1689 
    1690 See [[https://wiki.libsdl.org/SDL_SetError|SDL_SetError]].
    1691 
    1692 Unlike SDL_SetError, this procedure only accepts one argument, a
    1693 string. You can use {{sprintf}} to do string substitution if desired.
    1694 
    1695 
    1696 <procedure>(get-platform) → string</procedure>
    1697 
    1698 See [[https://wiki.libsdl.org/SDL_GetPlatform|SDL_GetPlatform]].
    1699 
    1700 
    1701 <procedure>(screen-saver-enabled?) → boolean</procedure>
    1702 <setter>(set! (screen-saver-enabled?) enabled?)</setter>
    1703 <setter>(screen-saver-enabled-set! enabled?)</setter>
    1704 
    1705 See [[https://wiki.libsdl.org/SDL_IsScreenSaverEnabled|SDL_IsScreenSaverEnabled]],
    1706 [[https://wiki.libsdl.org/SDL_EnableScreenSaver|SDL_EnableScreenSaver]],
    1707 and [[https://wiki.libsdl.org/SDL_DisableScreenSaver|SDL_DisableScreenSaver]].
    1708 
    1709 
    1710 <procedure>(has-clipboard-text?) → boolean</procedure>
    1711 
    1712 See [[https://wiki.libsdl.org/SDL_HasClipboardText|SDL_HasClipboardText]].
    1713 
    1714 
    1715 <procedure>(get-clipboard-text) → string</procedure>
    1716 
    1717 See [[https://wiki.libsdl.org/SDL_GetClipboardText|SDL_GetClipboardText]].
    1718 
    1719 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    1720 
    1721 
    1722 <procedure>(set-clipboard-text! text)</procedure>
    1723 
    1724 See [[https://wiki.libsdl.org/SDL_SetClipboardText|SDL_SetClipboardText]].
    1725 
    1726 Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    1727 
    1728 
    1729 
    1730 
    1731 === Struct Bindings
     209==== Struct Memory Management
    1732210
    1733211The sdl2 egg has many "struct record types", which are record types
     
    1735213example, the sdl2:surface record type wraps a pointer to an
    1736214SDL_Surface struct.
    1737 
    1738 Each struct record type has some associated procedures, which get or
    1739 set the value of a certain field of the underlying C struct.
    1740 
    1741 
    1742 ==== Struct Memory Management
    1743215
    1744216Some struct record types have procedures for allocating or freeing an
     
    1832304
    1833305
     306=== Initialization and Clean Up
     307
     308<procedure>(set-main-ready!)</procedure>
     309
     310See [[https://wiki.libsdl.org/SDL_SetMainReady|SDL_SetMainReady]].
     311
     312You should call this soon after your program starts, '''before''' calling {{init!}}.
     313See [[/egg/sdl2#ensuring-proper-clean-up|Ensuring Proper Clean Up]].
     314
     315
     316<procedure>(init! #!optional flags-list)</procedure>
     317
     318Initialize SDL.
     319You should call this soon after your program starts, '''after''' calling {{set-main-ready!}}.
     320See [[/egg/sdl2#ensuring-proper-clean-up|Ensuring Proper Clean Up]].
     321
     322{{flags-list}} defaults to {{'(everything)}}. It must be a list of one or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#init-flags|init flag symbols]]:
     323
     324* {{'timer}}
     325* {{'audio}}
     326* {{'video}}
     327* {{'joystick}}
     328* {{'haptic}}
     329* {{'game-controller}}
     330* {{'events}}
     331* {{'everything}}
     332
     333See [[https://wiki.libsdl.org/SDL_Init|SDL_Init]].
     334
     335Signals an exception of kind {{(exn sdl2)}} if initialization fails.
     336
     337
     338<procedure>(init-subsystem! flags-list)</procedure>
     339
     340See [[https://wiki.libsdl.org/SDL_InitSubSystem|SDL_InitSubSystem]].
     341
     342{{flags-list}} must be a list of one or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#init-flags|init flag]] symbols.
     343
     344Signals an exception of kind {{(exn sdl2)}} if initialization fails.
     345
     346
     347<procedure>(quit!)</procedure>
     348
     349Clean up SDL.
     350You must make sure to call this before your program ends.
     351See [[/egg/sdl2#ensuring-proper-clean-up|Ensuring Proper Clean Up]].
     352
     353See [[https://wiki.libsdl.org/SDL_Quit|SDL_Quit]].
     354
     355
     356<procedure>(quit-subsystem! flags-list)</procedure>
     357
     358See [[https://wiki.libsdl.org/SDL_QuitSubSystem|SDL_QuitSubSystem]].
     359
     360{{flags-list}} must be a list of one or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#init-flags|init flag]] symbols.
     361
     362
     363<procedure>(was-init #!optional flags-list) → list of symbols</procedure>
     364
     365See [[https://wiki.libsdl.org/SDL_WasInit|SDL_WasInit]].
     366
     367{{flags-list}} defaults to {{'(everything)}}. It must be a list of one or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#init-flags|init flag]] symbols.
     368
     369
     370
     371=== Audio
     372
    1834373==== sdl2:audio-cvt
    1835374
     
    1960499
    1961500
     501
     502=== Color
    1962503
    1963504==== sdl2:color
     
    2071612
    2072613
     614=== Cursor
     615
    2073616==== sdl2:cursor
    2074617
     
    2083626
    2084627
    2085 ==== sdl2:display-mode
    2086 
    2087 sdl2:display-mode is a record type that wraps a pointer to an
    2088 [[https://wiki.libsdl.org/SDL_DisplayMode|SDL_DisplayMode]] struct.
    2089 
    2090 
    2091 <procedure>(display-mode? obj) → boolean</procedure>
    2092 
    2093 Returns #t if {{obj}} is an sdl2:display-mode.
    2094 
    2095 
    2096 <procedure>(make-display-mode #!optional format w h refresh-rate) → sdl2:display-mode</procedure>
    2097 <procedure>(make-display-mode* #!optional format w h refresh-rate) → sdl2:display-mode</procedure>
    2098 
    2099 Allocate and initialize a new sdl2:display-mode.
    2100 
    2101 {{format}} defaults to {{'unknown}}. It must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]] or equivalent integer.
    2102 
    2103 {{w}}, {{h}}, and {{refresh-rate}} default to 0. They must be integers.
    2104 
    2105 * {{make-display-mode}} returns a managed sdl2:display-mode.
    2106 * {{make-display-mode*}} returns an unmanaged sdl2:display-mode, which must be freed with {{free-display-mode!}} when you are done with it.
    2107 
    2108 
    2109 <procedure>(free-display-mode! display-mode)</procedure>
    2110 
    2111 Free the memory of the sdl2:display-mode's underlying struct.
    2112 {{display-mode}}'s pointer will be set to null (see {{struct-null?}}).
    2113 It is safe to call this procedure with managed or unmanaged
    2114 sdl2:display-modes. It is safe (but has no effect) to free a struct
    2115 record multiple times.
    2116 
    2117 
    2118 <procedure>(display-mode-format display-mode) → symbol</procedure>
    2119 <procedure>(display-mode-format-raw display-mode) → fixnum</procedure>
    2120 <setter>(set! (display-mode-format display-mode) val)</setter>
    2121 <setter>(display-mode-format-set! display-mode val)</setter>
    2122 
    2123 Get or set the sdl2:display-mode's "format" field.
    2124 
    2125 * {{display-mode-format}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]].
    2126 * {{display-mode-format-raw}} returns an integer.
    2127 * The setters accept either a symbol or an integer.
    2128 
    2129 
    2130 <procedure>(display-mode-w display-mode) → fixnum</procedure>
    2131 <setter>(set! (display-mode-w display-mode) val)</setter>
    2132 <setter>(display-mode-w-set! display-mode val)</setter>
    2133 
    2134 Get or set the sdl2:display-mode's "w" field, as an integer.
    2135 
    2136 
    2137 <procedure>(display-mode-h display-mode) → fixnum</procedure>
    2138 <setter>(set! (display-mode-h display-mode) val)</setter>
    2139 <setter>(display-mode-h-set! display-mode val)</setter>
    2140 
    2141 Get or set the sdl2:display-mode's "h" field, as an integer.
    2142 
    2143 
    2144 <procedure>(display-mode-refresh-rate display-mode) → fixnum</procedure>
    2145 <setter>(set! (display-mode-refresh-rate display-mode) val)</setter>
    2146 <setter>(display-mode-refresh-rate-set! display-mode val)</setter>
    2147 
    2148 Get or set the sdl2:display-mode's "refresh-rate" field, as an integer.
    2149 
     628=== Event
     629
     630==== Event Functions
     631
     632<procedure>(event-state type) → boolean</procedure>
     633<setter>(set! (event-state type) state) → boolean</setter>
     634<setter>(event-state-set! type state) → boolean</setter>
     635
     636Get or set the state of the given event type.
     637#t means the event type is enabled, so events of that type may appear on the event queue.
     638#f means the event type is disabled, so events of that type will be automatically discarded.
     639It is beneficial to your program's performance to disable event types that your program does not need.
     640
     641{{type}} must be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbol]] or corresponding integer.
     642
     643If you set an event type's state to #f, any events of that type already on the event queue will be immediately discarded.
     644The setters return the previous state of the given event type.
     645
     646See [[https://wiki.libsdl.org/SDL_EventState|SDL_EventState]].
     647
     648
     649<procedure>(flush-event! type)</procedure>
     650<procedure>(flush-events! #!optional min-type max-type)</procedure>
     651
     652Remove all events on the event queue that match the given type or range of types.
     653See [[https://wiki.libsdl.org/SDL_FlushEvent|SDL_FlushEvent]]
     654and [[https://wiki.libsdl.org/SDL_FlushEvents|SDL_FlushEvents]].
     655
     656For {{flush-event!}}, {{type}} must be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbol]] or corresponding integer.
     657
     658For {{flush-events!}}, {{min-type}} and {{max-type}} specify the range of event types to remove.
     659Events with a type outside of this range will not be removed.
     660{{min-type}} and {{max-type}} must be [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbols]] or corresponding integers.
     661{{min-type}} defaults to {{'first}} and {{max-type}} defaults to {{'last}}, which means all event types match by default.
     662
     663
     664<procedure>(has-event? type) → boolean</procedure>
     665<procedure>(has-events? #!optional min-type max-type) → boolean</procedure>
     666
     667Returns #t if the event queue currently has at least one event matching the given type or range of types.
     668See [[https://wiki.libsdl.org/SDL_HasEvent|SDL_HasEvent]]
     669and [[https://wiki.libsdl.org/SDL_HasEvents|SDL_HasEvents]].
     670
     671For {{has-event?}}, {{type}} must be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbol]] or corresponding integer.
     672
     673For {{has-events?}}, {{min-type}} and {{max-type}} specify the range of event types to consider.
     674Events with a type outside of this range will not be considered.
     675{{min-type}} and {{max-type}} must be [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbols]] or corresponding integers.
     676{{min-type}} defaults to {{'first}} and {{max-type}} defaults to {{'last}}, which means all event types match by default.
     677
     678
     679<procedure>(quit-requested?) → boolean</procedure>
     680
     681Returns #t if the event queue currently has at least one event of type {{'quit}}.
     682See [[https://wiki.libsdl.org/SDL_QuitRequested|SDL_QuitRequested]].
     683
     684
     685<procedure>(get-events! num #!optional min-type max-type) → list of sdl2:events</procedure>
     686<procedure>(peek-events num #!optional min-type max-type) → list of sdl2:events</procedure>
     687
     688Get multiple matching events from the front of the event queue.
     689Returns a list of managed sdl2:events.
     690See [[https://wiki.libsdl.org/SDL_PeepEvents|SDL_PeepEvents]].
     691
     692* {{get-events!}} removes the returned events from the event queue.
     693* {{peek-events}} does not remove the returned events from the event queue.
     694
     695{{num}} specifies the maximum number of events to return.
     696May return fewer events if there are not enough matching events on the event queue.
     697
     698{{min-type}} and {{max-type}} specify the range of event types to return.
     699Events with a type outside of this range will not be returned (they will remain on the queue).
     700{{min-type}} and {{max-type}} must be [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#event-types|event type symbols]] or corresponding integers.
     701{{min-type}} defaults to {{'first}} and {{max-type}} defaults to {{'last}}, which means all event types match by default.
     702
     703Both procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
     704
     705
     706<procedure>(poll-event! #!optional result-event) → sdl2:event</procedure>
     707
     708Get the next event from the event queue.
     709The returned event is removed from the event queue.
     710See [[https://wiki.libsdl.org/SDL_PollEvent|SDL_PollEvent]].
     711
     712If {{result-event}} is omitted or #f, a new managed sdl2:event will be returned.
     713If {{result-event}} is an sdl2:event, it will be modified and returned.
     714This allows you to allocate a single event and reuse it many times in your event loop,
     715so that your program does not create as much garbage for the garbage collector.
     716
     717
     718<procedure>(pump-events!)</procedure>
     719
     720See [[https://wiki.libsdl.org/SDL_PumpEvents|SDL_PumpEvents]].
     721
     722
     723<procedure>(push-event! event) → boolean</procedure>
     724
     725See [[https://wiki.libsdl.org/SDL_PushEvent|SDL_PushEvent]].
     726
     727Returns #t if the event was pushed onto the event queue, or #f if the event was discarded,
     728e.g. because the event type is disabled (see {{event-state}}).
     729
     730Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     731
     732
     733<procedure>(wait-event! #!optional result-event) → sdl2:event</procedure>
     734<procedure>(wait-event-timeout! timeout #!optional result-event) → sdl2:event or #f</procedure>
     735
     736Wait for the next event to appear on the event queue, then return it.
     737The returned event will be removed from the event queue.
     738If there is already an event on the event queue, it will be returned immediately.
     739Otherwise, these procedures will block the current thread until the next event appears (or the timeout expires).
     740
     741* {{wait-event!}} will wait indefinitely for an event to appear.
     742* {{wait-event-timeout!}} will stop waiting and return #f if no event appears within {{timeout}} milliseconds.
     743  (It may actually wait a few milliseconds longer than specified.
     744  You should not rely on its timing being very precise.)
     745
     746If {{result-event}} is omitted or #f, a new managed sdl2:event will be returned.
     747If {{result-event}} is an sdl2:event, it will be modified and returned.
     748This allows you to allocate a single event and reuse it many times in your event loop,
     749so that your program does not create as much garbage for the garbage collector.
     750
     751These procedures are compatible with [[/manual/Unit srfi-18|SRFI-18]] multithreading.
     752Only the current thread will block while waiting.
     753Other threads will continue as normal.
     754
     755These procedures are inspired by (but do not actually use)
     756[[https://wiki.libsdl.org/SDL_WaitEvent|SDL_WaitEvent]] and
     757[[https://wiki.libsdl.org/SDL_WaitEventTimeout|SDL_WaitEventTimeout]].
     758
     759
     760<procedure>(register-events! event-symbols) → list of pairs</procedure>
     761
     762Register zero or more symbols as new user event types.
     763After registration, the given symbols may be used as event types, e.g. with {{event-type-set!}}.
     764The symbols will be associated with the sdl2:user-event variant of sdl2:event.
     765
     766{{event-symbols}} must be a list of symbols that are not already being used as event types.
     767If any symbol is already being used, or if any member of the list is not a symbol,
     768an error will be signalled and none of the new event types will be registered.
     769
     770There are 32767 user event type numbers available to register.
     771Each symbol in {{event-symbols}} will be assigned a sequential number.
     772If there are not enough remaining numbers to register all the symbols in {{event-symbols}},
     773this procedure will signal an exception of kind {{(exn sdl2)}}, and none of the new event types will be registered.
     774
     775This procedure returns a list of pairs, with the car of each pair being a new event type symbol, and the cdr of each pair being that symbol's assigned number.
     776
     777This procedure is based on [[https://wiki.libsdl.org/SDL_RegisterEvents|SDL_RegisterEvents]].
    2150778
    2151779
     
    2339967
    2340968
    2341 ===== sdl2:controller-axis-event
     969==== sdl2:controller-axis-event
    2342970
    2343971sdl2:controller-axis-event is a variant of sdl2:event that wraps a pointer to an
     
    23811009
    23821010
    2383 ===== sdl2:controller-button-event
     1011==== sdl2:controller-button-event
    23841012
    23851013sdl2:controller-button-event is a variant of sdl2:event that wraps a pointer to an
     
    24241052
    24251053
    2426 ===== sdl2:controller-device-event
     1054==== sdl2:controller-device-event
    24271055
    24281056sdl2:controller-device-event is a variant of sdl2:event that wraps a pointer to an
     
    24521080
    24531081
    2454 ===== sdl2:dollar-gesture-event
     1082==== sdl2:dollar-gesture-event
    24551083
    24561084sdl2:dollar-gesture-event is a variant of sdl2:event that wraps a pointer to an
     
    25131141
    25141142
    2515 ===== sdl2:drop-event
     1143==== sdl2:drop-event
    25161144
    25171145sdl2:drop-event is a variant of sdl2:event that wraps a pointer to an
     
    25391167
    25401168
    2541 ===== sdl2:joy-axis-event
     1169==== sdl2:joy-axis-event
    25421170
    25431171sdl2:joy-axis-event is a variant of sdl2:event that wraps a pointer to an
     
    25811209
    25821210
    2583 ===== sdl2:joy-ball-event
     1211==== sdl2:joy-ball-event
    25841212
    25851213sdl2:joy-ball-event is a variant of sdl2:event that wraps a pointer to an
     
    26291257
    26301258
    2631 ===== sdl2:joy-button-event
     1259==== sdl2:joy-button-event
    26321260
    26331261sdl2:joy-button-event is a variant of sdl2:event that wraps a pointer to an
     
    26731301
    26741302
    2675 ===== sdl2:joy-device-event
     1303==== sdl2:joy-device-event
    26761304
    26771305sdl2:joy-device-event is a variant of sdl2:event that wraps a pointer to an
     
    27011329
    27021330
    2703 ===== sdl2:joy-hat-event
     1331==== sdl2:joy-hat-event
    27041332
    27051333sdl2:joy-hat-event is a variant of sdl2:event that wraps a pointer to an
     
    27471375
    27481376
    2749 ===== sdl2:keyboard-event
     1377==== sdl2:keyboard-event
    27501378
    27511379sdl2:keyboard-event is a variant of sdl2:event that wraps a pointer to an
     
    28441472
    28451473
    2846 ===== sdl2:mouse-button-event
     1474==== sdl2:mouse-button-event
    28471475
    28481476sdl2:mouse-button-event is a variant of sdl2:event that wraps a pointer to an
     
    29161544
    29171545
    2918 ===== sdl2:mouse-motion-event
     1546==== sdl2:mouse-motion-event
    29191547
    29201548sdl2:mouse-motion-event is a variant of sdl2:event that wraps a pointer to an
     
    29931621
    29941622
    2995 ===== sdl2:mouse-wheel-event
     1623==== sdl2:mouse-wheel-event
    29961624
    29971625sdl2:mouse-wheel-event is a variant of sdl2:event that wraps a pointer to an
     
    30411669
    30421670
    3043 ===== sdl2:multi-gesture-event
     1671==== sdl2:multi-gesture-event
    30441672
    30451673sdl2:multi-gesture-event is a variant of sdl2:event that wraps a pointer to an
     
    31021730
    31031731
    3104 ===== sdl2:quit-event
     1732==== sdl2:quit-event
    31051733
    31061734sdl2:quit-event is a variant of sdl2:event that wraps a pointer to an
     
    31211749
    31221750
    3123 ===== sdl2:sys-wm-event
     1751==== sdl2:sys-wm-event
    31241752
    31251753sdl2:sys-wm-event is a variant of sdl2:event that wraps a pointer to an
     
    31471775
    31481776
    3149 ===== sdl2:text-editing-event
     1777==== sdl2:text-editing-event
    31501778
    31511779sdl2:text-editing-event is a variant of sdl2:event that wraps a pointer to an
     
    31941822
    31951823
    3196 ===== sdl2:text-input-event
     1824==== sdl2:text-input-event
    31971825
    31981826sdl2:text-input-event is a variant of sdl2:event that wraps a pointer to an
     
    32271855
    32281856
    3229 ===== sdl2:touch-finger-event
     1857==== sdl2:touch-finger-event
    32301858
    32311859sdl2:touch-finger-event is a variant of sdl2:event that wraps a pointer to an
     
    32991927
    33001928
    3301 ===== sdl2:user-event
     1929==== sdl2:user-event
    33021930
    33031931sdl2:user-event is a variant of sdl2:event that wraps a pointer to an
     
    33601988
    33611989
    3362 ===== sdl2:window-event
     1990==== sdl2:window-event
    33631991
    33641992sdl2:window-event is a variant of sdl2:event that wraps a pointer to an
     
    34182046
    34192047
    3420 ==== sdl2:finger
    3421 
    3422 sdl2:finger is a record type that wraps a pointer to an
    3423 [[https://wiki.libsdl.org/SDL_Finger|SDL_Finger]] struct.
    3424 
    3425 
    3426 <procedure>(finger? obj) → boolean</procedure>
    3427 
    3428 Returns #t if {{obj}} is an sdl2:finger.
    3429 
    3430 
    3431 <procedure>(finger-id finger) → fixnum</procedure>
    3432 
    3433 Get the sdl2:finger's "id" field, as an integer.
    3434 
    3435 
    3436 <procedure>(finger-x finger) → float</procedure>
    3437 
    3438 Get the sdl2:finger's "x" field, as a float in the range 0.0 to 1.0 (inclusive), indicating the normalized X position of the finger.
    3439 
    3440 
    3441 <procedure>(finger-y finger) → float</procedure>
    3442 
    3443 Get the sdl2:finger's "y" field, as a float in the range 0.0 to 1.0 (inclusive), indicating the normalized Y position of the finger.
    3444 
    3445 
    3446 <procedure>(finger-pressure finger) → float</procedure>
    3447 
    3448 Get the sdl2:finger's "pressure" field, as a float in the range 0.0 to 1.0 (inclusive), indicating the normalized pressure of the finger.
     2048=== Joystick
     2049
     2050==== Joystick Functions
     2051
     2052<procedure>(num-joysticks) → fixnum</procedure>
     2053
     2054See [[https://wiki.libsdl.org/SDL_NumJoysticks|SDL_NumJoysticks]].
     2055
     2056Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     2057
     2058
     2059<procedure>(joystick-open! index) → sdl2:joystick</procedure>
     2060
     2061See [[https://wiki.libsdl.org/SDL_JoystickOpen|SDL_JoystickOpen]].
     2062
     2063Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     2064
     2065
     2066<procedure>(joystick-close! joystick)</procedure>
     2067
     2068See [[https://wiki.libsdl.org/SDL_JoystickClose|SDL_JoystickClose]].
     2069
     2070
     2071<procedure>(joystick-update!)</procedure>
     2072
     2073See [[https://wiki.libsdl.org/SDL_JoystickUpdate|SDL_JoystickUpdate]].
     2074
     2075
     2076<procedure>(joystick-event-state) → boolean</procedure>
     2077<setter>(set! (joystick-event-state) state) → boolean</setter>
     2078<setter>(joystick-event-state-set! state) → boolean</setter>
     2079
     2080{{joystick-event-state}} returns #t if joystick events are currently enabled, or #f if they are disabled (i.e. all future joystick-related events will be ignored).
     2081
     2082The setters enable (if {{state}} is #t) or disable (if {{state}} is #f) joytsick events.
     2083'''WARNING:''' Calling the setters may delete all events currently in the event queue.
     2084
     2085These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
     2086
     2087See [[https://wiki.libsdl.org/SDL_JoystickEventState|SDL_JoystickEventState]].
     2088
     2089
     2090<procedure>(joystick-attached? joystick) → boolean</procedure>
     2091
     2092See [[https://wiki.libsdl.org/SDL_JoystickGetAttached|SDL_JoystickGetAttached]].
     2093
     2094
     2095<procedure>(joystick-num-axes joystick) → fixnum</procedure>
     2096
     2097See [[https://wiki.libsdl.org/SDL_JoystickNumAxes|SDL_JoystickNumAxes]].
     2098
     2099Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     2100
     2101
     2102<procedure>(joystick-num-balls joystick) → fixnum</procedure>
     2103
     2104See [[https://wiki.libsdl.org/SDL_JoystickNumBalls|SDL_JoystickNumBalls]].
     2105
     2106Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     2107
     2108
     2109<procedure>(joystick-num-buttons joystick) → fixnum</procedure>
     2110
     2111See [[https://wiki.libsdl.org/SDL_JoystickNumButtons|SDL_JoystickNumButtons]].
     2112
     2113Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     2114
     2115
     2116<procedure>(joystick-num-hats joystick) → fixnum</procedure>
     2117
     2118See [[https://wiki.libsdl.org/SDL_JoystickNumHats|SDL_JoystickNumHats]].
     2119
     2120Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     2121
     2122
     2123<procedure>(joystick-get-axis joystick axis-num) → fixnum</procedure>
     2124
     2125See [[https://wiki.libsdl.org/SDL_JoystickGetAxis|SDL_JoystickGetAxis]].
     2126
     2127Signals an exception of kind {{(exn bounds)}} if {{axis-num}} is less than 0 or greater than the last axis on the joystick (see {{joystick-num-axiss}}).
     2128
     2129
     2130<procedure>(joystick-get-ball joystick ball-num) → [dx dy]</procedure>
     2131
     2132See [[https://wiki.libsdl.org/SDL_JoystickGetBall|SDL_JoystickGetBall]].
     2133
     2134This procedure returns multiple values.
     2135
     2136Signals an exception of kind {{(exn bounds)}} if {{ball-num}} is less than 0 or greater than the last trackball on the joystick (see {{joystick-num-balls}}).
     2137Signals an exception of kind {{(exn sdl2)}} if some other error occurs.
     2138
     2139
     2140<procedure>(joystick-get-button joystick button-num) → boolean</procedure>
     2141
     2142See [[https://wiki.libsdl.org/SDL_JoystickGetButton|SDL_JoystickGetButton]].
     2143
     2144Signals an exception of kind {{(exn bounds)}} if {{button-num}} is less than 0 or greater than the last button on the joystick (see {{joystick-num-buttons}}).
     2145
     2146<procedure>(joystick-get-hat joystick hat-num) → symbol</procedure>
     2147<procedure>(joystick-get-hat-raw joystick hat-num) → fixnum</procedure>
     2148
     2149See [[https://wiki.libsdl.org/SDL_JoystickGetHat|SDL_JoystickGetHat]].
     2150
     2151* {{joystick-get-hat}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#joystick-hat-position|joystick hat position symbol]].
     2152* {{joystick-get-hat-raw}} returns an integer.
     2153
     2154Both procedures signal an exception of kind {{(exn bounds)}} if {{hat-num}} is less than 0 or greater than the last hat switch on the joystick (see {{joystick-num-hats}}).
     2155
     2156
     2157<procedure>(joystick-instance-id joystick) → fixnum</procedure>
     2158
     2159See [[https://wiki.libsdl.org/SDL_JoystickInstanceID|SDL_JoystickInstanceID]].
     2160
     2161Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     2162
     2163
     2164<procedure>(joystick-name joystick) → string or #f</procedure>
     2165
     2166See [[https://wiki.libsdl.org/SDL_JoystickName|SDL_JoystickName]].
     2167
     2168Returns #f if no name can be found.
     2169
     2170
     2171<procedure>(joystick-name-for-index device-index) → string or #f</procedure>
     2172
     2173See [[https://wiki.libsdl.org/SDL_JoystickNameForIndex|SDL_JoystickNameForIndex]].
     2174
     2175Returns #f if no name can be found.
     2176
     2177
     2178<procedure>(joystick-get-device-guid device-index) → sdl2:joystick-guid</procedure>
     2179
     2180See [[https://wiki.libsdl.org/SDL_JoystickGetDeviceGUID|SDL_JoystickGetDeviceGUID]].
     2181
     2182Returns a new managed sdl2:joystick-guid.
     2183
     2184
     2185<procedure>(joystick-get-guid joystick) → sdl2:joystick-guid</procedure>
     2186
     2187See [[https://wiki.libsdl.org/SDL_JoystickGetGUID|SDL_JoystickGetGUID]].
     2188
     2189Returns a new managed sdl2:joystick-guid.
     2190
     2191
     2192<procedure>(joystick-get-guid-from-string str) → sdl2:joystick-guid</procedure>
     2193
     2194See [[https://wiki.libsdl.org/SDL_JoystickGetGUIDFromString|SDL_JoystickGetGUIDFromString]].
     2195
     2196Returns a new managed sdl2:joystick-guid.
     2197
     2198
     2199<procedure>(joystick-get-guid-string guid) → string</procedure>
     2200
     2201See [[https://wiki.libsdl.org/SDL_JoystickGetGUIDString|SDL_JoystickGetGUIDString]].
    34492202
    34502203
     
    34842237
    34852238
     2239=== Keyboard
     2240
     2241==== Keyboard Functions
     2242
     2243<procedure>(get-key-from-name name-str) → symbol</procedure>
     2244<procedure>(get-key-from-name-raw name-str) → fixnum</procedure>
     2245
     2246See [[https://wiki.libsdl.org/SDL_GetKeyFromName|SDL_GetKeyFromName]].
     2247
     2248* {{get-key-from-name}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]].
     2249* {{get-key-from-name-raw}} returns an integer.
     2250
     2251
     2252<procedure>(get-key-from-scancode scancode) → symbol</procedure>
     2253<procedure>(get-key-from-scancode-raw scancode) → fixnum</procedure>
     2254
     2255See [[https://wiki.libsdl.org/SDL_GetKeyFromScancode|SDL_GetKeyFromScancode]].
     2256
     2257{{scancode}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]] or an integer representing a keyboard scancode.
     2258
     2259* {{get-key-from-scancode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]].
     2260* {{get-key-from-scancode-raw}} returns an integer.
     2261
     2262
     2263<procedure>(get-key-name key) → string</procedure>
     2264
     2265See [[https://wiki.libsdl.org/SDL_GetKeyName|SDL_GetKeyName]].
     2266
     2267{{key}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]] or an integer representing a keyboard keycode.
     2268
     2269
     2270<procedure>(get-scancode-from-name name-str) → symbol</procedure>
     2271<procedure>(get-scancode-from-name-raw name-str) → fixnum</procedure>
     2272
     2273See [[https://wiki.libsdl.org/SDL_GetScancodeFromName|SDL_GetScancodeFromName]].
     2274
     2275* {{get-scancode-from-name}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]].
     2276* {{get-scancode-from-name-raw}} returns an integer.
     2277
     2278
     2279<procedure>(get-scancode-from-key key) → symbol</procedure>
     2280<procedure>(get-scancode-from-key-raw key) → fixnum</procedure>
     2281
     2282See [[https://wiki.libsdl.org/SDL_GetScancodeFromKey|SDL_GetScancodeFromKey]].
     2283
     2284{{key}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-keycodes|keyboard keycode symbol]] or an integer representing a keyboard keycode.
     2285
     2286* {{get-scancode-from-key}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]].
     2287* {{get-scancode-from-key-raw}} returns an integer.
     2288
     2289
     2290<procedure>(get-scancode-name scancode) → string</procedure>
     2291
     2292See [[https://wiki.libsdl.org/SDL_GetScancodeName|SDL_GetScancodeName]].
     2293
     2294{{scancode}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]] or an integer representing a keyboard scancode.
     2295
     2296
     2297<procedure>(get-keyboard-focus) → sdl2:window</procedure>
     2298
     2299See [[https://wiki.libsdl.org/SDL_GetKeyboardFocus|SDL_GetKeyboardFocus]].
     2300
     2301
     2302<procedure>(scancode-pressed? scancode) → boolean</procedure>
     2303
     2304Returns #t if the keyboard key with the given scancode is currently
     2305being pressed.
     2306
     2307{{scancode}} must be either a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-scancodes|keyboard scancode symbol]] or an integer representing a scancode.
     2308
     2309This procedure queries SDL's internal keyboard state, which is tied to
     2310the event system. Call {{pump-events!}} to update the keyboard state.
     2311
     2312This procedure is based on
     2313[[https://wiki.libsdl.org/SDL_GetKeyboardState|SDL_GetKeyboardState]].
     2314
     2315
     2316<procedure>(mod-state) → list of symbols </procedure>
     2317<procedure>(mod-state-raw) → fixnum</procedure>
     2318<setter>(set! (mod-state) state)</setter>
     2319<setter>(mod-state-set! state)</setter>
     2320
     2321See [[https://wiki.libsdl.org/SDL_GetModState|SDL_GetModState]].
     2322
     2323* {{mod-state}} returns a list of zero or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#keyboard-modifiers|keyboard modifier symbols]].
     2324* {{mod-state-raw}} returns an integer representing a bitfield of keyboard modifiers.
     2325* The setters accept either a list of zero or more symbols, or an integer.
     2326
     2327
     2328<setter>(text-input-rect-set! rect)</setter>
     2329
     2330{{rect}} can be an sdl2:rect or #f.
     2331
     2332See [[https://wiki.libsdl.org/SDL_SetTextInputRect|SDL_SetTextInputRect]].
     2333
     2334
     2335<procedure>(start-text-input!)</procedure>
     2336
     2337See [[https://wiki.libsdl.org/SDL_StartTextInput|SDL_StartTextInput]].
     2338
     2339
     2340<procedure>(stop-text-input!)</procedure>
     2341
     2342See [[https://wiki.libsdl.org/SDL_StopTextInput|SDL_StopTextInput]].
     2343
     2344
     2345<procedure>(text-input-active?) → boolean</procedure>
     2346
     2347See [[https://wiki.libsdl.org/SDL_IsTextInputActive|SDL_IsTextInputActive]].
     2348
     2349
     2350<procedure>(screen-keyboard-support?) → boolean</procedure>
     2351
     2352See [[https://wiki.libsdl.org/SDL_HasScreenKeyboardSupport|SDL_HasScreenKeyboardSupport]].
     2353
     2354
     2355<procedure>(screen-keyboard-shown? window) → boolean</procedure>
     2356
     2357See [[https://wiki.libsdl.org/SDL_IsScreenKeyboardShown|SDL_IsScreenKeyboardShown]].
     2358
     2359
    34862360==== sdl2:keysym
    34872361
     
    35532427* The setters accept either a list of zero or more symbols, or an integer.
    35542428
     2429
     2430
     2431=== OpenGL
     2432
     2433==== OpenGL Functions
     2434
     2435<procedure>(gl-create-context! window) → sdl2:gl-context</procedure>
     2436
     2437See [[https://wiki.libsdl.org/SDL_GL_CreateContext|SDL_GL_CreateContext]].
     2438
     2439Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     2440
     2441
     2442<procedure>(gl-delete-context! gl-context)</procedure>
     2443
     2444See [[https://wiki.libsdl.org/SDL_GL_DeleteContext|SDL_GL_DeleteContext]].
     2445
     2446
     2447<procedure>(gl-make-current! window gl-context)</procedure>
     2448
     2449See [[https://wiki.libsdl.org/SDL_GL_MakeCurrent|SDL_GL_MakeCurrent]].
     2450
     2451Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     2452
     2453
     2454<procedure>(gl-get-current-window) → sdl2:window</procedure>
     2455
     2456See [[https://wiki.libsdl.org/SDL_GL_GetCurrentWindow|SDL_GL_GetCurrentWindow]].
     2457
     2458Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     2459
     2460
     2461<procedure>(gl-get-current-context) → sdl2:gl-context</procedure>
     2462
     2463See [[https://wiki.libsdl.org/SDL_GL_GetCurrentContext|SDL_GL_GetCurrentContext]].
     2464
     2465Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     2466
     2467
     2468<procedure>(gl-attribute attr) → value</procedure>
     2469<setter>(set! (gl-attribute attr) value)</setter>
     2470<setter>(gl-attribute-set! attr value)</setter>
     2471
     2472See [[https://wiki.libsdl.org/SDL_GL_GetAttribute|SDL_GL_GetAttribute]]
     2473and [[https://wiki.libsdl.org/SDL_GL_SetAttribute|SDL_GL_SetAttribute]].
     2474
     2475{{attr}} must be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#opengl-attributes|OpenGL attribute symbol]] or corresponding integer.
     2476
     2477The value's type depends on {{attr}}:
     2478
     2479* If {{attr}} is {{'context-profile-mask}}, the value will be an [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#opengl-profiles|OpenGL profile symbol]]. (The setter also accepts a corresponding integer.)
     2480
     2481* If {{attr}} is {{'context-flags}}, the value will be a list of zero or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#opengl-context-flags|OpenGL context flag symbols]] will be returned. (The setter also accepts an equivalent integer bitfield.)
     2482
     2483* Otherwise, the value is an integer.
     2484
     2485The getter and the setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
     2486
     2487
     2488<procedure>(gl-reset-attributes!)</procedure>
     2489
     2490See [[https://wiki.libsdl.org/SDL_GL_ResetAttributes|SDL_GL_ResetAttributes]].
     2491
     2492Requires SDL 2.0.2 or higher. Signals an error if the compiled version
     2493of SDL is not high enough. Use {{(version-at-least? 2 0 2)}} to
     2494check before calling this procedure.
     2495
     2496
     2497<procedure>(gl-get-drawable-size window) → [width height]</procedure>
     2498
     2499See [[https://wiki.libsdl.org/SDL_GL_GetDrawableSize|SDL_GL_GetDrawableSize]].
     2500
     2501This procedure returns multiple values.
     2502
     2503Requires SDL 2.0.1 or higher. Signals an error if the compiled version
     2504of SDL is not high enough. Use {{(version-at-least? 2 0 1)}} to
     2505check before calling this procedure.
     2506
     2507
     2508<procedure>(gl-swap-window!)</procedure>
     2509
     2510See [[https://wiki.libsdl.org/SDL_GL_SwapWindow|SDL_GL_SwapWindow]].
     2511
     2512
     2513<procedure>(gl-swap-interval) → fixnum</procedure>
     2514<setter>(set! (gl-swap-interval) interval)</setter>
     2515<setter>(gl-set-swap-interval! interval)</setter>
     2516
     2517See [[https://wiki.libsdl.org/SDL_GL_GetSwapInterval|SDL_GL_GetSwapInterval]]
     2518and [[https://wiki.libsdl.org/SDL_GL_SetSwapInterval|SDL_GL_SetSwapInterval]].
     2519
     2520The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
     2521
     2522
     2523<procedure>(gl-extension-supported? name-string) → boolean</procedure>
     2524
     2525See [[https://wiki.libsdl.org/SDL_GL_ExtensionSupported|SDL_GL_ExtensionSupported]].
     2526
     2527
     2528
     2529==== sdl2:gl-context
     2530
     2531sdl2:gl-context is a record type that wraps a pointer to an SDL_GLContext struct.
     2532
     2533<procedure>(gl-context? obj) → boolean</procedure>
     2534
     2535Returns #t if {{obj}} is an sdl2:gl-context.
     2536
     2537
     2538
     2539=== Palette
     2540
     2541==== Palette Functions
     2542
     2543<procedure>(palette-ref palette i) → sdl2:color</procedure>
     2544<setter>(set! (palette-ref palette i) color)</setter>
     2545<setter>(palette-set! palette i color)</setter>
     2546
     2547{{palette-ref}} returns a copy of the color at the given index of the palette, as a managed sdl2:color.
     2548
     2549The setters set the given index of the palette to a copy of the given sdl2:color.
     2550
     2551These procedures signal an exception of kind {{(exn bounds)}} if the given index is out of bounds.
     2552
     2553
     2554<procedure>(palette-colors palette) → vector of sdl2:colors </procedure>
     2555<procedure>(palette-colours palette) → vector of sdl2:colors </procedure>
     2556<setter>(set! (palette-colors palette) colors-vec) → boolean</setter>
     2557<setter>(set! (palette-colours palette) colors-vec) → boolean</setter>
     2558<setter>(palette-colors-set! colors-vec #!optional firstcolor) → boolean</setter>
     2559<setter>(palette-colours-set! colors-vec #!optional firstcolor) → boolean</setter>
     2560
     2561{{palette-colors}} and {{palette-colours}} return copies of all colors in the palette, as a Scheme vector of managed sdl2:colors.
     2562
     2563The setters set multiple colors in the palette to copies of the given colors.
     2564See [[https://wiki.libsdl.org/SDL_SetPaletteColors|SDL_SetPaletteColors]].
     2565
     2566{{colors-vec}} must be a Scheme vector of sdl2:colors.
     2567
     2568{{firstcolor}} specifies the first index of the palette to set.
     2569I.e., palette index {{firstcolor}} will be set to the first color in {{colors-vec}},
     2570palette index {{firstcolor + 1}} will be set to the second color, and so on.
     2571{{firstcolor}} defaults to 0.
     2572Signals an exception of kind {{(exn bounds)}} if {{firstcolor}} is out of bounds.
     2573
     2574The {{set!}} form cannot accept the {{firstcolor}} argument.
     2575
     2576The setters return #t if every color in {{colors-vec}} was used, or #f if some colors were not used,
     2577e.g. because there were more colors in the vector than could fit in the palette.
    35552578
    35562579
     
    36052628
    36062629
     2630=== Pixel Format
     2631
     2632==== Pixel Format Functions
     2633
     2634<procedure>(map-rgb pixel-format r g b) → fixnum</procedure>
     2635<procedure>(map-rgba pixel-format r g b a) → fixnum</procedure>
     2636
     2637See [[https://wiki.libsdl.org/SDL_MapRGB|SDL_MapRGB]]
     2638and [[https://wiki.libsdl.org/SDL_MapRGBA|SDL_MapRGBA]].
     2639
     2640
     2641<procedure>(get-rgb pixel pixel-format) → [r g b]</procedure>
     2642<procedure>(get-rgba pixel pixel-format) → [r g b a]</procedure>
     2643
     2644See [[https://wiki.libsdl.org/SDL_GetRGB|SDL_GetRGB]]
     2645and [[https://wiki.libsdl.org/SDL_GetRGBA|SDL_GetRGBA]].
     2646
     2647These procedures return multiple values.
     2648
     2649
     2650<procedure>(pixel-format-enum-to-masks format-enum) → [bpp rmask gmask bmask amask]</procedure>
     2651
     2652See [[https://wiki.libsdl.org/SDL_PixelFormatEnumToMasks|SDL_PixelFormatEnumToMasks]].
     2653
     2654{{format-enum}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]] or equivalent integer.
     2655
     2656This procedure returns multiple values:
     2657
     2658; bpp   : The color depth (bits per pixel) of the format.
     2659; rmask : The red mask of the format.
     2660; gmask : The green mask of the format.
     2661; bmask : The blue mask of the format.
     2662; amask : The alpha mask of the format.
     2663
     2664Signals an exception of kind {{(exn sdl2)}} if conversion was not possible.
     2665
     2666
    36072667==== sdl2:pixel-format
    36082668
     
    36962756
    36972757
     2758=== Rect / Point
     2759
     2760==== Rect / Point Functions
     2761
     2762<procedure>(rect-empty? rect) → boolean</procedure>
     2763
     2764See [[https://wiki.libsdl.org/SDL_RectEmpty|SDL_RectEmpty]].
     2765
     2766
     2767<procedure>(enclose-points points #!optional clip result-rect) → [rect any-enclosed?]</procedure>
     2768
     2769See [[https://wiki.libsdl.org/SDL_EnclosePoints|SDL_EnclosePoints]].
     2770
     2771{{points}} must be a list of sdl2:points.
     2772
     2773{{clip}} must be either an sdl2:rect or #f (the default). If {{clip}}
     2774is an sdl2:rect, points outside the clip rect will be ignored.
     2775
     2776If {{result-rect}} is omitted or #f, a new managed sdl2:rect will be
     2777returned. If {{result-rect}} is an sdl2:rect, it will be modified and
     2778returned. {{result-rect}} must not be the same object as either
     2779{{rect1}} or {{rect2}}.
     2780
     2781This procedure returns multiple values:
     2782
     2783; rect : An sdl2:rect that encloses all matching points. Possibly the same object as {{result-rect}}.
     2784; any-enclosed? : #t if any points were enclosed, or #f if all points were clipped
     2785
     2786
     2787<procedure>(has-intersection? rect1 rect2) → boolean</procedure>
     2788
     2789See [[https://wiki.libsdl.org/SDL_HasIntersection|SDL_HasIntersection]].
     2790
     2791
     2792<procedure>(intersect-rect rect1 rect2 #!optional result-rect) → [rect intersect?]</procedure>
     2793
     2794See [[https://wiki.libsdl.org/SDL_IntersectRect|SDL_IntersectRect]].
     2795
     2796If {{result-rect}} is omitted or #f, a new managed sdl2:rect will be
     2797returned. If {{result-rect}} is an sdl2:rect, it will be modified and
     2798returned. {{result-rect}} must not be the same object as either
     2799{{rect1}} or {{rect2}}.
     2800
     2801This procedure returns multiple values:
     2802
     2803; rect : An sdl2:rect of the intersection of {{rect1}} and {{rect2}}. Possibly the same object as {{result-rect}}.
     2804; intersect? : #t if {{rect1}} and {{rect2}} intersect, otherwise #f
     2805
     2806
     2807<procedure>(intersect-rect-and-line rect x1 y1 x2 y2) → [intersect? x1-new y1-new x2-new y2-new]</procedure>
     2808
     2809See [[https://wiki.libsdl.org/SDL_IntersectRectAndLine|SDL_IntersectRectAndLine]].
     2810
     2811This procedure returns multiple values:
     2812
     2813; intersect? : #t if the given line intersects with the rect
     2814; x1-new : the x value of the point within rect that is closest to the first point
     2815; y1-new : the y value ...
     2816; x2-new : the x value of the point within rect that is closest to the second point
     2817; y2-new : the y value ...
     2818
     2819
     2820<procedure>(union-rect rect1 rect2 #!optional result-rect) → rect</procedure>
     2821
     2822See [[https://wiki.libsdl.org/SDL_UnionRect|SDL_UnionRect]].
     2823
     2824If {{result-rect}} is omitted or #f, a new managed sdl2:rect will be
     2825returned. If {{result-rect}} is an sdl2:rect, it will be modified and
     2826returned. {{result-rect}} must not be the same object as either
     2827{{rect1}} or {{rect2}}.
     2828
     2829
     2830
     2831==== sdl2:rect
     2832
     2833sdl2:rect is a record type that wraps a pointer to an
     2834[[https://wiki.libsdl.org/SDL_Rect|SDL_Rect]] struct.
     2835
     2836
     2837<procedure>(rect? obj) → boolean</procedure>
     2838
     2839Returns #t if {{obj}} is an sdl2:rect.
     2840
     2841
     2842<procedure>(make-rect #!optional x y w h) → sdl2:rect</procedure>
     2843<procedure>(make-rect* #!optional x y w h) → sdl2:rect</procedure>
     2844
     2845Allocate and initialize a new sdl2:rect.
     2846
     2847{{x}}, {{y}}, {{w}}, and {{h}} must be integers in the range -2147483648 to 2147483647 (inclusive).
     2848They all default to 0.
     2849
     2850* {{make-rect}} returns a managed sdl2:rect.
     2851* {{make-rect*}} returns an unmanaged sdl2:rect, which must be freed with {{free-rect!}} when you are done with it.
     2852
     2853
     2854<procedure>(free-rect! rect)</procedure>
     2855
     2856Free the memory of the sdl2:rect's underlying struct. {{rect}}'s
     2857pointer will be set to null (see {{struct-null?}}). It is safe to call
     2858this procedure with managed or unmanaged sdl2:rects. It is safe (but
     2859has no effect) to free a struct record multiple times.
     2860
     2861
     2862<procedure>(rect-x rect) → fixnum</procedure>
     2863<setter>(set! (rect-x rect) val)</setter>
     2864<setter>(rect-x-set! rect val)</setter>
     2865
     2866Get or set the sdl2:rect's "x" field, as an integer in the range -2147483648 to 2147483647 (inclusive).
     2867
     2868
     2869<procedure>(rect-y rect) → fixnum</procedure>
     2870<setter>(set! (rect-y rect) val)</setter>
     2871<setter>(rect-y-set! rect val)</setter>
     2872
     2873Get or set the sdl2:rect's "y" field, as an integer in the range -2147483648 to 2147483647 (inclusive).
     2874
     2875
     2876<procedure>(rect-w rect) → fixnum</procedure>
     2877<setter>(set! (rect-w rect) val)</setter>
     2878<setter>(rect-w-set! rect val)</setter>
     2879
     2880Get or set the sdl2:rect's "w" (width) field, as an integer in the range -2147483648 to 2147483647 (inclusive).
     2881
     2882
     2883<procedure>(rect-h rect) → fixnum</procedure>
     2884<setter>(set! (rect-h rect) val)</setter>
     2885<setter>(rect-h-set! rect val)</setter>
     2886
     2887Get or set the sdl2:rect's "h" (height) field, as an integer in the range -2147483648 to 2147483647 (inclusive).
     2888
     2889
     2890<procedure>(rect-set! rect #!optional x y w h) → rect</procedure>
     2891
     2892Convenient way of setting multiple fields of the sdl2:rect.
     2893Any arguments that are {{#f}} will cause no change to that field.
     2894E.g. {{(rect-set! my-rect 42 #f 1337 #f)}} will set the "x" field to 42 and the "w" field to 1337, but will not change the "y" or "h" fields.
     2895Returns {{rect}} after it is modified.
     2896
     2897
     2898<procedure>(rect->list rect) → list of fixnums</procedure>
     2899
     2900Returns a list {{(x y w h)}} containing the value of each field of the sdl2:rect.
     2901
     2902
     2903<procedure>(rect=? rect1 rect2) → boolean</procedure>
     2904
     2905Efficiently compare two sdl2:rects.
     2906Returns #t if the value of every field in {{rect1}} is equal to the value of the corresponding field in {{rect2}}.
     2907See [[https://wiki.libsdl.org/SDL_RectEquals|SDL_RectEquals]].
     2908
     2909
     2910<procedure>(copy-rect rect) → sdl2:rect</procedure>
     2911<procedure>(copy-rect* rect) → sdl2:rect</procedure>
     2912
     2913Efficiently copy the given sdl2:rect, returning a new sdl2:rect with the same values.
     2914
     2915* {{copy-rect}} returns a managed sdl2:rect.
     2916* {{copy-rect*}} returns an unmanaged sdl2:rect, which must be freed with {{free-rect!}} when you are done with it.
     2917
     2918
     2919
    36982920==== sdl2:point
    36992921
     
    37692991
    37702992
    3771 ==== sdl2:rect
    3772 
    3773 sdl2:rect is a record type that wraps a pointer to an
    3774 [[https://wiki.libsdl.org/SDL_Rect|SDL_Rect]] struct.
    3775 
    3776 
    3777 <procedure>(rect? obj) → boolean</procedure>
    3778 
    3779 Returns #t if {{obj}} is an sdl2:rect.
    3780 
    3781 
    3782 <procedure>(make-rect #!optional x y w h) → sdl2:rect</procedure>
    3783 <procedure>(make-rect* #!optional x y w h) → sdl2:rect</procedure>
    3784 
    3785 Allocate and initialize a new sdl2:rect.
    3786 
    3787 {{x}}, {{y}}, {{w}}, and {{h}} must be integers in the range -2147483648 to 2147483647 (inclusive).
    3788 They all default to 0.
    3789 
    3790 * {{make-rect}} returns a managed sdl2:rect.
    3791 * {{make-rect*}} returns an unmanaged sdl2:rect, which must be freed with {{free-rect!}} when you are done with it.
    3792 
    3793 
    3794 <procedure>(free-rect! rect)</procedure>
    3795 
    3796 Free the memory of the sdl2:rect's underlying struct. {{rect}}'s
    3797 pointer will be set to null (see {{struct-null?}}). It is safe to call
    3798 this procedure with managed or unmanaged sdl2:rects. It is safe (but
    3799 has no effect) to free a struct record multiple times.
    3800 
    3801 
    3802 <procedure>(rect-x rect) → fixnum</procedure>
    3803 <setter>(set! (rect-x rect) val)</setter>
    3804 <setter>(rect-x-set! rect val)</setter>
    3805 
    3806 Get or set the sdl2:rect's "x" field, as an integer in the range -2147483648 to 2147483647 (inclusive).
    3807 
    3808 
    3809 <procedure>(rect-y rect) → fixnum</procedure>
    3810 <setter>(set! (rect-y rect) val)</setter>
    3811 <setter>(rect-y-set! rect val)</setter>
    3812 
    3813 Get or set the sdl2:rect's "y" field, as an integer in the range -2147483648 to 2147483647 (inclusive).
    3814 
    3815 
    3816 <procedure>(rect-w rect) → fixnum</procedure>
    3817 <setter>(set! (rect-w rect) val)</setter>
    3818 <setter>(rect-w-set! rect val)</setter>
    3819 
    3820 Get or set the sdl2:rect's "w" (width) field, as an integer in the range -2147483648 to 2147483647 (inclusive).
    3821 
    3822 
    3823 <procedure>(rect-h rect) → fixnum</procedure>
    3824 <setter>(set! (rect-h rect) val)</setter>
    3825 <setter>(rect-h-set! rect val)</setter>
    3826 
    3827 Get or set the sdl2:rect's "h" (height) field, as an integer in the range -2147483648 to 2147483647 (inclusive).
    3828 
    3829 
    3830 <procedure>(rect-set! rect #!optional x y w h) → rect</procedure>
    3831 
    3832 Convenient way of setting multiple fields of the sdl2:rect.
    3833 Any arguments that are {{#f}} will cause no change to that field.
    3834 E.g. {{(rect-set! my-rect 42 #f 1337 #f)}} will set the "x" field to 42 and the "w" field to 1337, but will not change the "y" or "h" fields.
    3835 Returns {{rect}} after it is modified.
    3836 
    3837 
    3838 <procedure>(rect->list rect) → list of fixnums</procedure>
    3839 
    3840 Returns a list {{(x y w h)}} containing the value of each field of the sdl2:rect.
    3841 
    3842 
    3843 <procedure>(rect=? rect1 rect2) → boolean</procedure>
    3844 
    3845 Efficiently compare two sdl2:rects.
    3846 Returns #t if the value of every field in {{rect1}} is equal to the value of the corresponding field in {{rect2}}.
    3847 See [[https://wiki.libsdl.org/SDL_RectEquals|SDL_RectEquals]].
    3848 
    3849 
    3850 <procedure>(copy-rect rect) → sdl2:rect</procedure>
    3851 <procedure>(copy-rect* rect) → sdl2:rect</procedure>
    3852 
    3853 Efficiently copy the given sdl2:rect, returning a new sdl2:rect with the same values.
    3854 
    3855 * {{copy-rect}} returns a managed sdl2:rect.
    3856 * {{copy-rect*}} returns an unmanaged sdl2:rect, which must be freed with {{free-rect!}} when you are done with it.
    3857 
     2993
     2994=== RWops
     2995
     2996==== RWops Functions
     2997
     2998<procedure>(rw-from-file filepath) → sdl2:rwops</procedure>
     2999
     3000See [[https://wiki.libsdl.org/SDL_RWFromFile|SDL_RWFromFile]].
     3001
     3002You should close the sdl2:rwops when you are done with it, using
     3003{{rw-close!}} or one of the procedures that can automatically close
     3004the sdl2:rwops, such as {{load-bmp-rw}}.
     3005
     3006Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3007
     3008
     3009<procedure>(rw-from-const-mem pointer) → sdl2:rwops</procedure>
     3010
     3011See [[https://wiki.libsdl.org/SDL_RWFromConstMem|SDL_RWFromConstMem]].
     3012
     3013You should close the sdl2:rwops when you are done with it, using
     3014{{rw-close!}} or one of the procedures that can automatically close
     3015the sdl2:rwops, such as {{load-bmp-rw}}.
     3016
     3017Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3018
     3019
     3020<procedure>(rw-from-mem pointer) → sdl2:rwops</procedure>
     3021
     3022See [[https://wiki.libsdl.org/SDL_RWFromMem|SDL_RWFromMem]].
     3023
     3024You should close the sdl2:rwops when you are done with it, using
     3025{{rw-close!}} or one of the procedures that can automatically close
     3026the sdl2:rwops, such as {{load-bmp-rw}}.
     3027
     3028Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3029
     3030
     3031<procedure>(rw-from-blob blob) → sdl2:rwops</procedure>
     3032
     3033Create a new sdl2:rwops that accesses the memory of the given
     3034[[http://wiki.call-cc.org/manual/Unit%20library#blobs|blob]]. You
     3035should close the sdl2:rwops when you are done with it, using
     3036{{rw-close!}} or one of the procedures that can automatically close
     3037the sdl2:rwops, such as {{load-bmp-rw}}.
     3038
     3039Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3040
     3041You can also use this procedure to create a sdl2:rwops from a
     3042[[/manual/Unit srfi-4|SRFI-4]] numeric vector, by first converting it
     3043to a blob using e.g. {{u8vector->blob/shared}}.
     3044
     3045'''CAUTION:''' Creating a sdl2:rwops from a blob in CHICKEN-managed
     3046memory is unstable: the blob might be garbage collected or moved in
     3047memory, which would break the sdl2:rwops. To be safe, you should
     3048[[/manual/Unit lolevel#object-evict|evict]] the blob and create the
     3049sdl2:rwops from the evicted blob (not the original). You may wish to
     3050[[/manual/Unit lolevel#object-release|release]] the evicted blob after
     3051you have closed the sdl2:rwops. Example:
     3052
     3053<enscript highlight="scheme">
     3054(let* ((evicted-blob (object-evict '#${...}))
     3055       (rwops (sdl2:rw-from-blob evicted-blob))
     3056       (surf (sdl2:load-bmp-rw rwops #t)))
     3057  (object-release evicted-blob)
     3058  surf)
     3059</enscript>
     3060
     3061
     3062<procedure>(rw-from-string str) → sdl2:rwops</procedure>
     3063
     3064Create a new sdl2:rwops that accesses the memory of the given CHICKEN
     3065Scheme string. You should close the sdl2:rwops when you are done with
     3066it, using {{rw-close!}} or one of the procedures that can
     3067automatically close the sdl2:rwops, such as {{load-bmp-rw}}.
     3068
     3069Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3070
     3071'''CAUTION:''' Creating a sdl2:rwops from a string in CHICKEN-managed
     3072memory is unstable: the string might be garbage collected or moved in
     3073memory, which would break the sdl2:rwops. To be safe, you should
     3074[[/manual/Unit lolevel#object-evict|evict]] the string and create the
     3075sdl2:rwops from the evicted string (not the original). You may wish to
     3076[[/manual/Unit lolevel#object-release|release]] the evicted string
     3077after you have closed the sdl2:rwops. Example:
     3078
     3079<enscript highlight="scheme">
     3080(let* ((evicted-string (object-evict "..."))
     3081       (rwops (sdl2:rw-from-string evicted-string))
     3082       (surf (sdl2:load-bmp-rw rwops #t)))
     3083  (object-release evicted-string)
     3084  surf)
     3085</enscript>
     3086
     3087
     3088<procedure>(rw-close! rwops)</procedure>
     3089
     3090See [[https://wiki.libsdl.org/SDL_RWclose|SDL_RWclose]].
     3091
     3092Close and clean up the given sdl2:rwops. This frees the memory used by
     3093the SDL_RWops struct itself, but does not free or release the pointer,
     3094blob, or string that the sdl2:rwops was reading/writing from. (It does
     3095close files opened with {{rw-from-file}}, though.)
     3096
     3097Signals an exception of kind {{(exn sdl2)}} if an error occurs.
    38583098
    38593099
     
    38853125
    38863126
     3127=== Surface
     3128
     3129==== Surface Functions
     3130
     3131<procedure>(create-rgb-surface* flags width height depth rmask gmask bmask amask) → sdl2:surface</procedure>
     3132
     3133See [[https://wiki.libsdl.org/SDL_CreateRGBSurface|SDL_CreateRGBSurface]].
     3134
     3135Returns a new '''unmanaged''' sdl2:surface with the given properties.
     3136You must call {{free-surface!}} when you are done with it.
     3137
     3138See {{make-surface}} for a more convenient interface.
     3139
     3140Signals an exception of kind {{(exn sdl2)}} if the surface cannot be created.
     3141
     3142
     3143<procedure>(create-rgb-surface-from* pixels width height depth pitch rmask gmask bmask amask) → sdl2:surface</procedure>
     3144
     3145Returns a new '''unmanaged''' sdl2:surface with the given properties,
     3146using existing pixel data (a pointer, e.g. from {{surface-pixels-raw}}).
     3147You must call {{free-surface!}} when you are done with it.
     3148
     3149See [[https://wiki.libsdl.org/SDL_CreateRGBSurfaceFrom|SDL_CreateRGBSurfaceFrom]].
     3150
     3151Signals an exception of kind {{(exn sdl2)}} if the surface cannot be created.
     3152
     3153
     3154<procedure>(convert-surface surface pixel-format) → sdl2:surface</procedure>
     3155<procedure>(convert-surface* surface pixel-format) → sdl2:surface</procedure>
     3156
     3157Creates a copy of the given sdl2:surface, but converts it to the given sdl2:pixel-format.
     3158
     3159See [[https://wiki.libsdl.org/SDL_ConvertSurface|SDL_ConvertSurface]].
     3160
     3161* {{convert-surface}} returns a managed sdl2:surface.
     3162* {{convert-surface*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
     3163
     3164Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3165
     3166
     3167<procedure>(load-bmp path-string) → sdl2:surface</procedure>
     3168<procedure>(load-bmp* filepath) → sdl2:surface</procedure>
     3169
     3170See [[https://wiki.libsdl.org/SDL_LoadBMP|SDL_LoadBMP]].
     3171
     3172Attempts to load a BMP image file. Returns a sdl2:surface containing
     3173the image data, or #f if the image could not be loaded.
     3174
     3175'''NOTE:''' This procedure only supports certain kinds of BMP image.
     3176Use the [[/egg/sdl2-image|sdl2-image egg]] for better BMP support,
     3177plus support for loading other image formats like JPG, PNG, and GIF.
     3178
     3179* {{load-bmp}} returns a managed sdl2:surface.
     3180* {{load-bmp*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
     3181
     3182Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3183
     3184
     3185<procedure>(load-bmp-rw rwops #!optional close?) → sdl2:surface</procedure>
     3186<procedure>(load-bmp-rw* rwops #!optional close?) → sdl2:surface</procedure>
     3187
     3188See [[https://wiki.libsdl.org/SDL_LoadBMP_RW|SDL_LoadBMP_RW]].
     3189
     3190Attempts to load a BMP image from the given sdl2:rwops. Returns a
     3191sdl2:surface containing the image data, or #f if the image could not
     3192be loaded.
     3193
     3194If {{close?}} is #t, {{rwops}} will be automatically closed (see
     3195{{rw-close!}}) after the image is loaded. If {{close?}} is #f or
     3196omitted, {{rwops}} will not be closed.
     3197
     3198'''NOTE:''' This procedure only supports certain kinds of BMP image.
     3199Use the [[/egg/sdl2-image|sdl2-image egg]] for better BMP support,
     3200plus support for loading other image formats like JPG, PNG, and GIF.
     3201
     3202* {{load-bmp-rw}} returns a managed sdl2:surface.
     3203* {{load-bmp-rw*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} when you are done with it.
     3204
     3205Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3206
     3207
     3208<procedure>(save-bmp! surface filepath) → fixnum</procedure>
     3209
     3210See [[https://wiki.libsdl.org/SDL_SaveBMP|SDL_SaveBMP]].
     3211
     3212Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3213
     3214
     3215<procedure>(save-bmp-rw! surface rwops #!optional close?) → fixnum</procedure>
     3216
     3217See [[https://wiki.libsdl.org/SDL_SaveBMP_RW|SDL_SaveBMP_RW]].
     3218
     3219If {{close?}} is #t, {{rwops}} will be automatically closed (see
     3220{{rw-close!}}) after the image is loaded. If {{close?}} is #f or
     3221omitted, {{rwops}} will not be closed.
     3222
     3223Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3224
     3225
     3226<procedure>(lock-surface! surface) → fixnum</procedure>
     3227<procedure>(unlock-surface! surface)</procedure>
     3228
     3229See [[https://wiki.libsdl.org/SDL_LockSurface|SDL_LockSurface]]
     3230and [[https://wiki.libsdl.org/SDL_UnlockSurface|SDL_UnlockSurface]].
     3231
     3232{{lock-surface!}} signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3233
     3234
     3235<procedure>(must-lock? surface) → boolean</procedure>
     3236
     3237See [[https://wiki.libsdl.org/SDL_MUSTLOCK|SDL_MUSTLOCK]].
     3238
     3239
     3240<procedure>(blit-surface! src src-rect dest dest-rect) → fixnum</procedure>
     3241
     3242See [[https://wiki.libsdl.org/SDL_BlitSurface|SDL_BlitSurface]].
     3243
     3244May modify dest-rect.
     3245
     3246Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3247
     3248
     3249<procedure>(blit-scaled! src src-rect dest dest-rect) → fixnum</procedure>
     3250
     3251See [[https://wiki.libsdl.org/SDL_BlitScaled|SDL_BlitScaled]].
     3252
     3253May modify dest-rect.
     3254
     3255Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3256
     3257
     3258<procedure>(fill-rect! surface rect color) → fixnum</procedure>
     3259
     3260See [[https://wiki.libsdl.org/SDL_FillRect|SDL_FillRect]].
     3261
     3262{{rect}} may be an sdl2:rect to fill part of the surface, or #f to fill
     3263the entire surface.
     3264
     3265{{color}} may be an sdl2:color or a mapped color (an integer, like
     3266returned by {{map-rgba}}).
     3267
     3268Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3269
     3270
     3271<procedure>(fill-rects! surface rects color) → fixnum</procedure>
     3272
     3273See [[https://wiki.libsdl.org/SDL_FillRects|SDL_FillRects]].
     3274
     3275{{rects}} must be a list of sdl2:rects.
     3276
     3277{{color}} may be an sdl2:color or a mapped color (an integer, like
     3278returned by {{map-rgba}}).
     3279
     3280Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3281
     3282
     3283<procedure>(surface-ref surface x y) → sdl2:color</procedure>
     3284<procedure>(surface-ref-raw surface x y) → fixnum</procedure>
     3285<setter>(set! (surface-ref surface x y) color)</setter>
     3286<setter>(surface-set! surface x y color)</setter>
     3287
     3288Get or set the color of the specified pixel on the surface.
     3289
     3290* {{surface-ref}} returns an sdl2:color.
     3291* {{surface-ref-raw}} returns a mapped color (an integer). You can use {{get-rgba}} to convert the mapped color to color fields.
     3292* The setters accept either an sdl2:color or a mapped color.
     3293
     3294These procedures automatically lock and unlock the surface if needed.
     3295They signal an exception of kind {{(exn sdl2)}} if the surface cannot be locked.
     3296
     3297These procedures signal an exception of kind {{(exn bounds)}} if {{x}} or {{y}} is out of bounds.
     3298
     3299The setters ignore the surface's clip rect.
     3300
     3301
     3302<procedure>(surface-clip-rect surface) → sdl2:rect</procedure>
     3303<setter>(set! (surface-clip-rect surface) rect) → boolean</setter>
     3304<setter>(surface-clip-rect-set! surface rect) → boolean</setter>
     3305
     3306{{surface-clip-rect}} returns a copy of the surface's clip rect.
     3307See [[https://wiki.libsdl.org/SDL_GetClipRect|SDL_GetClipRect]].
     3308
     3309The setters sets the surface's clip rect to a copy of the given rect.
     3310{{rect}} may be #f, which disables clipping.
     3311See [[https://wiki.libsdl.org/SDL_SetClipRect|SDL_SetClipRect]].
     3312
     3313The setters return #t if the given rect intersects the surface at all, or #f if the rect is out of bounds (completely clips out the surface).
     3314
     3315
     3316<procedure>(surface-color-key surface) → sdl2:color or #f</procedure>
     3317<procedure>(surface-colour-key surface) → sdl2:color or #f</procedure>
     3318<procedure>(surface-color-key-raw surface) → fixnum or #f</procedure>
     3319<procedure>(surface-colour-key-raw surface) → fixnum or #f</procedure>
     3320<setter>(set! (surface-color-key surface) color)</setter>
     3321<setter>(set! (surface-colour-key surface) color)</setter>
     3322<setter>(surface-color-key-set! surface color)</setter>
     3323<setter>(surface-colour-key-set! surface color)</setter>
     3324
     3325Get or set the sdl2:surface's color key.
     3326
     3327See [[https://wiki.libsdl.org/SDL_GetColorKey|SDL_GetColorKey]]
     3328and [[https://wiki.libsdl.org/SDL_SetColorKey|SDL_SetColorKey]].
     3329
     3330* {{surface-color-key}} and {{surface-colour-key}} return an sdl2:color if the surface has a color key, or #f if the surface does not have a color key.
     3331* {{surface-color-key-raw}} and {{surface-colour-key-raw}} return a mapped color (an integer) if the surface has a color key, or #f if the surface does not have a color key.
     3332* The setters accept either an sdl2:color, a mapped color (an integer), or #f to disable color keying.
     3333
     3334These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
     3335
     3336
     3337<procedure>(surface-alpha-mod surface) → fixnum</procedure>
     3338<setter>(set! (surface-alpha-mod surface) mod) → fixnum</setter>
     3339<setter>(surface-alpha-mod-set! surface mod) → fixnum</setter>
     3340
     3341See [[https://wiki.libsdl.org/SDL_GetSurfaceAlphaMod|SDL_GetSurfaceAlphaMod]]
     3342and [[https://wiki.libsdl.org/SDL_SetSurfaceAlphaMod|SDL_SetSurfaceAlphaMod]].
     3343
     3344These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
     3345
     3346
     3347<procedure>(surface-blend-mode surface) → symbol</procedure>
     3348<procedure>(surface-blend-mode-raw surface) → fixnum</procedure>
     3349<setter>(set! (surface-blend-mode surface) mode)</setter>
     3350<setter>(surface-blend-mode-set! surface mode)</setter>
     3351
     3352See [[https://wiki.libsdl.org/SDL_GetSurfaceBlendMode|SDL_GetSurfaceBlendMode]]
     3353and [[https://wiki.libsdl.org/SDL_SetSurfaceBlendMode|SDL_SetSurfaceBlendMode]].
     3354
     3355* {{surface-blend-mode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-mode|blend mode symbol]]:
     3356** {{'none}}
     3357** {{'blend}}
     3358** {{'add}}
     3359** {{'mod}}
     3360* {{surface-blend-mode-raw}} returns an integer.
     3361* The setters accept either a symbol or integer.
     3362
     3363These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
     3364
     3365
     3366
     3367<procedure>(surface-color-mod surface) → [r g b]</procedure>
     3368<procedure>(surface-colour-mod surface) → [r g b]</procedure>
     3369<setter>(set! (surface-color-mod surface) rgb)</setter>
     3370<setter>(set! (surface-colour-mod surface) rgb)</setter>
     3371<setter>(surface-color-mod-set! surface rgb)</setter>
     3372<setter>(surface-colour-mod-set! surface rgb)</setter>
     3373
     3374See [[https://wiki.libsdl.org/SDL_GetSurfaceColorMod|SDL_GetSurfaceColorMod]]
     3375and [[https://wiki.libsdl.org/SDL_SetSurfaceColorMod|SDL_SetSurfaceColorMod]].
     3376
     3377{{surface-color-mod}} and {{surface-colour-mod}} return multiple values.
     3378
     3379The setters accept either a list {{(r g b)}} of color values, or an sdl2:color (the sdl2:color's "a" field will be ignored).
     3380
     3381These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
     3382
     3383
     3384<procedure>(surface-palette surface) → sdl2:palette or #f</procedure>
     3385<setter>(set! (surface-palette surface) palette)</setter>
     3386<setter>(surface-palette-set! surface palette)</setter>
     3387
     3388{{surface-palette}} returns the surface's palette, or #f if it has no palette.
     3389It is equivalent to {{(compose pixel-format-palette surface-format)}}.
     3390
     3391The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
     3392
     3393See [[https://wiki.libsdl.org/SDL_SetSurfacePalette|SDL_SetSurfacePalette]].
     3394
     3395
     3396<setter>(surface-rle-set! surface enable?)</setter>
     3397
     3398Enable RLE acceleration if {{enable?}} is #t, or disable RLE acceleration if {{enable?}} is #f.
     3399See [[https://wiki.libsdl.org/SDL_SetSurfaceRLE|SDL_SetSurfaceRLE]].
     3400
     3401Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3402
     3403
     3404<procedure>(rotate-surface-90 surface turns) → sdl2:surface</procedure>
     3405
     3406Return a copy of the given surface rotated by the given number of 90º clockwise turns.
     3407{{turns}} must be an integer.
     3408For example:
     3409
     3410* {{turns}} 0 means no rotation
     3411* {{turns}} 1 means 90º clockwise rotation
     3412* {{turns}} 2 means 180º rotation
     3413* {{turns}} 3 (or -1) means 270º clockwise (i.e. 90º counter-clockwise) rotation
     3414
     3415If the given surface has a palette, the new surface will share the same palette.
     3416
     3417Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3418
     3419
     3420<procedure>(flip-surface surface flip-x? flip-y?) → sdl2:surface</procedure>
     3421
     3422Return a copy of the given surface flipped on the X (horizontal) and/or Y (vertical) axes.
     3423If the given surface has a palette, the new surface will share the same palette.
     3424
     3425Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3426
     3427
    38873428==== sdl2:surface
    38883429
     
    39733514
    39743515
     3516=== Texture
     3517
    39753518==== sdl2:texture
    39763519
     
    39853528
    39863529
     3530=== Timer
     3531
     3532<procedure>(delay! milliseconds)</procedure>
     3533
     3534See [[https://wiki.libsdl.org/SDL_Delay|SDL_Delay]].
     3535
     3536'''CAUTION:''' This procedure is not compatible with [[/manual/Unit srfi-18|SRFI-18]]
     3537threads. It will cause '''all threads to sleep''' for the given
     3538duration. If you are using multiple threads, you should instead call
     3539SRFI-18's {{thread-sleep!}}, which will cause only the current thread
     3540to sleep. For example, call {{(thread-sleep! 0.025)}} instead of
     3541{{(delay! 25)}}.
     3542
     3543
     3544<procedure>(get-ticks) → fixnum</procedure>
     3545
     3546See [[https://wiki.libsdl.org/SDL_GetTicks|SDL_GetTicks]].
     3547
     3548
     3549<procedure>(get-performance-counter) → fixnum</procedure>
     3550
     3551See [[https://wiki.libsdl.org/SDL_GetPerformanceCounter|SDL_GetPerformanceCounter]].
     3552
     3553
     3554<procedure>(get-performance-frequency) → fixnum</procedure>
     3555
     3556See [[https://wiki.libsdl.org/SDL_GetPerformanceFrequency|SDL_GetPerformanceFrequency]].
     3557
     3558
     3559
     3560=== Touch / Gesture
     3561
     3562==== Touch / Gesture Functions
     3563
     3564<procedure>(get-num-touch-devices) → fixnum</procedure>
     3565
     3566See [[https://wiki.libsdl.org/SDL_GetNumTouchDevices|SDL_GetNumTouchDevices]].
     3567
     3568
     3569<procedure>(get-touch-device device-id) → fixnum</procedure>
     3570
     3571See [[https://wiki.libsdl.org/SDL_GetTouchDevice|SDL_GetTouchDevice]].
     3572
     3573Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3574
     3575
     3576<procedure>(get-num-touch-fingers touch-id) → fixnum</procedure>
     3577
     3578See [[https://wiki.libsdl.org/SDL_GetNumTouchFingers|SDL_GetNumTouchFingers]].
     3579
     3580
     3581<procedure>(get-touch-finger touch-id index) → sdl2:finger</procedure>
     3582
     3583See [[https://wiki.libsdl.org/SDL_GetTouchFinger|SDL_GetTouchFinger]].
     3584
     3585Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3586
     3587
     3588==== sdl2:finger
     3589
     3590sdl2:finger is a record type that wraps a pointer to an
     3591[[https://wiki.libsdl.org/SDL_Finger|SDL_Finger]] struct.
     3592
     3593
     3594<procedure>(finger? obj) → boolean</procedure>
     3595
     3596Returns #t if {{obj}} is an sdl2:finger.
     3597
     3598
     3599<procedure>(finger-id finger) → fixnum</procedure>
     3600
     3601Get the sdl2:finger's "id" field, as an integer.
     3602
     3603
     3604<procedure>(finger-x finger) → float</procedure>
     3605
     3606Get the sdl2:finger's "x" field, as a float in the range 0.0 to 1.0 (inclusive), indicating the normalized X position of the finger.
     3607
     3608
     3609<procedure>(finger-y finger) → float</procedure>
     3610
     3611Get the sdl2:finger's "y" field, as a float in the range 0.0 to 1.0 (inclusive), indicating the normalized Y position of the finger.
     3612
     3613
     3614<procedure>(finger-pressure finger) → float</procedure>
     3615
     3616Get the sdl2:finger's "pressure" field, as a float in the range 0.0 to 1.0 (inclusive), indicating the normalized pressure of the finger.
     3617
     3618
     3619
     3620=== Version
     3621
     3622<procedure>(version-at-least? major minor patch) → boolean</procedure>
     3623
     3624See [[https://wiki.libsdl.org/SDL_VERSION_ATLEAST|SDL_VERSION_ATLEAST]].
     3625
     3626Returns #t if the sdl2 egg was compiled with a version of SDL at least as high as specified.
     3627For example, {{(version-at-least? 2 0 1)}} returns #t if the sdl2 egg was compiled with SDL 2.0.1 or higher.
     3628
     3629Some SDL features are only available after a certain version, so you can use this procedure to check whether the feature is available.
     3630
     3631
     3632<procedure>(compiled-version) → list of fixnums</procedure>
     3633<procedure>(current-version) → list of fixnums</procedure>
     3634
     3635Returns a list of three nonnegative integers, indicating a version number of SDL.
     3636For example, the list {{(2 0 3)}} indicates SDL 2.0.3.
     3637
     3638* {{compiled-version}} returns the version of SDL that the sdl2 egg was compiled with.
     3639* {{current-version}} returns the version of SDL that the sdl2 egg is currently using.
     3640
     3641For example, the user may have compiled the sdl2 egg with SDL 2.0.3, then later upgraded SDL to 2.1.0, but not yet recompiled the sdl2 egg with the new version.
     3642In such a case, {{compiled-version}} would return {{(2 0 3)}}, and {{current-version}} would return {{(2 1 0)}}.
     3643But, features from the new version would not be available until the user recompiles the sdl2 egg.
     3644
     3645See [[https://wiki.libsdl.org/SDL_VERSION|SDL_VERSION]]
     3646and [[https://wiki.libsdl.org/SDL_GetVersion|SDL_GetVersion]].
     3647
     3648
     3649
     3650=== Window / Display Mode
     3651
     3652==== Window / Display Mode Functions
     3653
     3654<procedure>(create-window! title x y w h #!optional flags) → sdl2:window</procedure>
     3655
     3656See [[https://wiki.libsdl.org/SDL_CreateWindow|SDL_CreateWindow]].
     3657
     3658{{x}} and {{y}} can be integers, the symbol {{'centered}}, or the symbol {{'undefined}}.
     3659
     3660{{flags}} defaults to {{'()}}. It must be a list of zero or more [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#window-flags|window flag symbols]] (or an equivalent integer bitfield):
     3661
     3662* {{'fullscreen}}
     3663* {{'fullscreen-desktop}}
     3664* {{'opengl}}
     3665* {{'shown}}
     3666* {{'hidden}}
     3667* {{'borderless}}
     3668* {{'resizable}}
     3669* {{'minimized}}
     3670* {{'maximized}}
     3671* {{'input-grabbed}}
     3672* {{'input-focus}}
     3673* {{'mouse-focus}}
     3674* {{'foreign}}
     3675
     3676
     3677<procedure>(get-window-from-id id) → sdl2:window</procedure>
     3678
     3679See [[https://wiki.libsdl.org/SDL_GetWindowFromID|SDL_GetWindowFromID]].
     3680
     3681
     3682<procedure>(destroy-window! window)</procedure>
     3683
     3684See [[https://wiki.libsdl.org/SDL_DestroyWindow|SDL_DestroyWindow]].
     3685
     3686
     3687<procedure>(update-window-surface! window)</procedure>
     3688
     3689See [[https://wiki.libsdl.org/SDL_UpdateWindowSurface|SDL_UpdateWindowSurface]].
     3690
     3691Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3692
     3693
     3694<procedure>(update-window-surface-rects! window rects)</procedure>
     3695
     3696See [[https://wiki.libsdl.org/SDL_UpdateWindowSurfaceRects|SDL_UpdateWindowSurfaceRects]].
     3697
     3698{{rects}} must be a list of sdl2:rects.
     3699
     3700Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3701
     3702
     3703<procedure>(show-window! window)</procedure>
     3704
     3705See [[https://wiki.libsdl.org/SDL_ShowWindow|SDL_ShowWindow]].
     3706
     3707
     3708<procedure>(hide-window! window)</procedure>
     3709
     3710See [[https://wiki.libsdl.org/SDL_HideWindow|SDL_HideWindow]].
     3711
     3712
     3713<procedure>(maximize-window! window)</procedure>
     3714
     3715See [[https://wiki.libsdl.org/SDL_MaximizeWindow|SDL_MaximizeWindow]].
     3716
     3717
     3718<procedure>(minimize-window! window)</procedure>
     3719
     3720See [[https://wiki.libsdl.org/SDL_MinimizeWindow|SDL_MinimizeWindow]].
     3721
     3722
     3723<procedure>(raise-window! window)</procedure>
     3724
     3725See [[https://wiki.libsdl.org/SDL_RaiseWindow|SDL_RaiseWindow]].
     3726
     3727
     3728<procedure>(restore-window! window)</procedure>
     3729
     3730See [[https://wiki.libsdl.org/SDL_RestoreWindow|SDL_RestoreWindow]].
     3731
     3732
     3733<procedure>(window-bordered? window) → boolean</procedure>
     3734<setter>(set! (window-bordered? window) bordered)</setter>
     3735<setter>(window-bordered-set! window bordered)</setter>
     3736
     3737Get or set whether the window has a border (window decoration).
     3738#t means the window has a border, #f means the window is borderless.
     3739
     3740Setting this to #f has essentially the same effect as passing the {{'borderless}} flag to {{create-window!}} when creating the window.
     3741
     3742See [[https://wiki.libsdl.org/SDL_SetWindowBordered|SDL_SetWindowBordered]].
     3743
     3744
     3745<procedure>(window-brightness window) → float</procedure>
     3746<setter>(set! (window-brightness window) brightness)</setter>
     3747<setter>(window-brightness-set! window brightness)</setter>
     3748
     3749See [[https://wiki.libsdl.org/SDL_GetWindowBrightness|SDL_GetWindowBrightness]]
     3750and [[https://wiki.libsdl.org/SDL_SetWindowBrightness|SDL_SetWindowBrightness]].
     3751
     3752The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
     3753
     3754
     3755<procedure>(window-display-index window) → fixnum</procedure>
     3756
     3757See [[https://wiki.libsdl.org/SDL_GetWindowDisplayIndex|SDL_GetWindowDisplayIndex]].
     3758
     3759Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3760
     3761
     3762<procedure>(window-display-mode window) → sdl2:display-mode</procedure>
     3763<setter>(set! (window-display-mode window) display-mode)</setter>
     3764<setter>(window-display-mode-set! window display-mode)</setter>
     3765
     3766See [[https://wiki.libsdl.org/SDL_GetWindowDisplayMode|SDL_GetWindowDisplayMode]]
     3767and [[https://wiki.libsdl.org/SDL_SetWindowDisplayMode|SDL_SetWindowDisplayMode]].
     3768
     3769These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
     3770
     3771
     3772<procedure>(window-flags window) → list of symbols</procedure>
     3773<procedure>(window-flags-raw window) → fixnum</procedure>
     3774
     3775See [[https://wiki.libsdl.org/SDL_GetWindowFlags|SDL_GetWindowFlags]].
     3776
     3777* {{window-flags}} returns a list of [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#window-flags|window flag symbols]].
     3778* {{window-flags-raw}} returns an integer bitfield.
     3779
     3780
     3781<procedure>(window-fullscreen window) → symbol or #f</procedure>
     3782<setter>(set! (window-fullscreen window) mode)</setter>
     3783<setter>(window-fullscreen-set! window mode)</setter>
     3784
     3785Get or set the sdl2:window's fullscreen mode.
     3786See [[https://wiki.libsdl.org/SDL_SetWindowFullscreen|SDL_SetWindowFullscreen]].
     3787
     3788{{window-fullscreen}} returns one of the following values:
     3789
     3790* {{'fullscreen}} means "real" fullscreen mode
     3791* {{'fullscreen-desktop}} means "fake" fullscreen mode that takes the size of the desktop
     3792* {{#f}} means windowed (non-fullscreen) mode
     3793
     3794The setters accept any of the above values, or #t (which means the same as {{'fullscreen}}), or an equivalent integer value.
     3795
     3796The setters signal an exception of kind {{(exn sdl2)}} if an error occurs.
     3797
     3798
     3799<procedure>(window-grab? window) → boolean</procedure>
     3800<setter>(set! (window-grab? window) grab?)</setter>
     3801<setter>(window-grab-set! window grab?)</setter>
     3802
     3803See [[https://wiki.libsdl.org/SDL_GetWindowGrab|SDL_GetWindowGrab]]
     3804and [[https://wiki.libsdl.org/SDL_SetWindowGrab|SDL_SetWindowGrab]].
     3805
     3806
     3807<setter>(window-icon-set! window icon-surface)</setter>
     3808
     3809See [[https://wiki.libsdl.org/SDL_SetWindowIcon|SDL_SetWindowIcon]].
     3810
     3811
     3812<procedure>(window-id window) → fixnum</procedure>
     3813
     3814See [[https://wiki.libsdl.org/SDL_GetWindowID|SDL_GetWindowID]].
     3815
     3816
     3817<procedure>(window-maximum-size window) → [width height]</procedure>
     3818<setter>(set! (window-maximum-size window) size)</setter>
     3819<setter>(window-maximum-size-set! window size)</setter>
     3820
     3821See [[https://wiki.libsdl.org/SDL_GetWindowMaximumSize|SDL_GetWindowMaximumSize]]
     3822and [[https://wiki.libsdl.org/SDL_SetWindowMaximumSize|SDL_SetWindowMaximumSize]].
     3823
     3824{{window-maximum-size}} returns multiple values.
     3825
     3826The setters accept a list of integers {{(width height)}}.
     3827
     3828
     3829<procedure>(window-minimum-size window) → [width height]</procedure>
     3830<setter>(set! (window-minimum-size window) size)</setter>
     3831<setter>(window-minimum-size-set! window size)</setter>
     3832
     3833See [[https://wiki.libsdl.org/SDL_GetWindowMinimumSize|SDL_GetWindowMinimumSize]]
     3834and [[https://wiki.libsdl.org/SDL_SetWindowMinimumSize|SDL_SetWindowMinimumSize]].
     3835
     3836{{window-minimum-size}} returns multiple values.
     3837
     3838The setters accept a list of integers {{(width height)}}.
     3839
     3840
     3841<procedure>(window-pixel-format window) → symbol</procedure>
     3842<procedure>(window-pixel-format-raw window) → fixnum</procedure>
     3843
     3844Returns a symbol or integer indicating the given window's pixel format.
     3845See [[https://wiki.libsdl.org/SDL_GetWindowPixelFormat|SDL_GetWindowPixelFormat]].
     3846
     3847* {{window-pixel-format}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]].
     3848* {{window-pixel-format-raw}} returns an integer.
     3849
     3850
     3851<procedure>(window-position window) → [x y]</procedure>
     3852<setter>(set! (window-position window) pos)</setter>
     3853<setter>(window-position-set! window pos)</setter>
     3854
     3855See [[https://wiki.libsdl.org/SDL_GetWindowPosition|SDL_GetWindowPosition]]
     3856and [[https://wiki.libsdl.org/SDL_SetWindowPosition|SDL_SetWindowPosition]].
     3857
     3858{{window-position}} returns multiple values.
     3859
     3860The setters accept a list of integers {{(x y)}}.
     3861
     3862
     3863<procedure>(window-size window) → [width height]</procedure>
     3864<setter>(set! (window-size window) size)</setter>
     3865<setter>(window-size-set! window size)</setter>
     3866
     3867See [[https://wiki.libsdl.org/SDL_GetWindowSize|SDL_GetWindowSize]]
     3868and [[https://wiki.libsdl.org/SDL_SetWindowSize|SDL_SetWindowSize]].
     3869
     3870{{window-size}} returns multiple values.
     3871
     3872The setters accept a list of integers {{(width height)}}.
     3873
     3874
     3875<procedure>(window-surface window) → sdl2:surface</procedure>
     3876
     3877See [[https://wiki.libsdl.org/SDL_GetWindowSurface|SDL_GetWindowSurface]].
     3878
     3879Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     3880
     3881
     3882<procedure>(window-title window) → string</procedure>
     3883<setter>(set! (window-title window) title)</setter>
     3884<setter>(window-title-set! window title)</setter>
     3885
     3886See [[https://wiki.libsdl.org/SDL_GetWindowTitle|SDL_GetWindowTitle]]
     3887and [[https://wiki.libsdl.org/SDL_SetWindowTitle|SDL_SetWindowTitle]].
     3888
     3889
     3890
    39873891==== sdl2:window
    39883892
     
    39943898
    39953899Returns #t if {{obj}} is an sdl2:window.
     3900
     3901
     3902
     3903==== sdl2:display-mode
     3904
     3905sdl2:display-mode is a record type that wraps a pointer to an
     3906[[https://wiki.libsdl.org/SDL_DisplayMode|SDL_DisplayMode]] struct.
     3907
     3908
     3909<procedure>(display-mode? obj) → boolean</procedure>
     3910
     3911Returns #t if {{obj}} is an sdl2:display-mode.
     3912
     3913
     3914<procedure>(make-display-mode #!optional format w h refresh-rate) → sdl2:display-mode</procedure>
     3915<procedure>(make-display-mode* #!optional format w h refresh-rate) → sdl2:display-mode</procedure>
     3916
     3917Allocate and initialize a new sdl2:display-mode.
     3918
     3919{{format}} defaults to {{'unknown}}. It must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]] or equivalent integer.
     3920
     3921{{w}}, {{h}}, and {{refresh-rate}} default to 0. They must be integers.
     3922
     3923* {{make-display-mode}} returns a managed sdl2:display-mode.
     3924* {{make-display-mode*}} returns an unmanaged sdl2:display-mode, which must be freed with {{free-display-mode!}} when you are done with it.
     3925
     3926
     3927<procedure>(free-display-mode! display-mode)</procedure>
     3928
     3929Free the memory of the sdl2:display-mode's underlying struct.
     3930{{display-mode}}'s pointer will be set to null (see {{struct-null?}}).
     3931It is safe to call this procedure with managed or unmanaged
     3932sdl2:display-modes. It is safe (but has no effect) to free a struct
     3933record multiple times.
     3934
     3935
     3936<procedure>(display-mode-format display-mode) → symbol</procedure>
     3937<procedure>(display-mode-format-raw display-mode) → fixnum</procedure>
     3938<setter>(set! (display-mode-format display-mode) val)</setter>
     3939<setter>(display-mode-format-set! display-mode val)</setter>
     3940
     3941Get or set the sdl2:display-mode's "format" field.
     3942
     3943* {{display-mode-format}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format symbol]].
     3944* {{display-mode-format-raw}} returns an integer.
     3945* The setters accept either a symbol or an integer.
     3946
     3947
     3948<procedure>(display-mode-w display-mode) → fixnum</procedure>
     3949<setter>(set! (display-mode-w display-mode) val)</setter>
     3950<setter>(display-mode-w-set! display-mode val)</setter>
     3951
     3952Get or set the sdl2:display-mode's "w" field, as an integer.
     3953
     3954
     3955<procedure>(display-mode-h display-mode) → fixnum</procedure>
     3956<setter>(set! (display-mode-h display-mode) val)</setter>
     3957<setter>(display-mode-h-set! display-mode val)</setter>
     3958
     3959Get or set the sdl2:display-mode's "h" field, as an integer.
     3960
     3961
     3962<procedure>(display-mode-refresh-rate display-mode) → fixnum</procedure>
     3963<setter>(set! (display-mode-refresh-rate display-mode) val)</setter>
     3964<setter>(display-mode-refresh-rate-set! display-mode val)</setter>
     3965
     3966Get or set the sdl2:display-mode's "refresh-rate" field, as an integer.
     3967
     3968
     3969
     3970=== Miscellaneous
     3971
     3972<procedure>(clear-error!)</procedure>
     3973
     3974See [[https://wiki.libsdl.org/SDL_ClearError|SDL_ClearError]].
     3975
     3976
     3977<procedure>(get-error) → string</procedure>
     3978
     3979See [[https://wiki.libsdl.org/SDL_GetError|SDL_GetError]].
     3980
     3981
     3982<procedure>(set-error! message)</procedure>
     3983
     3984See [[https://wiki.libsdl.org/SDL_SetError|SDL_SetError]].
     3985
     3986Unlike SDL_SetError, this procedure only accepts one argument, a
     3987string. You can use {{sprintf}} to do string substitution if desired.
     3988
     3989
     3990<procedure>(get-platform) → string</procedure>
     3991
     3992See [[https://wiki.libsdl.org/SDL_GetPlatform|SDL_GetPlatform]].
     3993
     3994
     3995<procedure>(screen-saver-enabled?) → boolean</procedure>
     3996<setter>(set! (screen-saver-enabled?) enabled?)</setter>
     3997<setter>(screen-saver-enabled-set! enabled?)</setter>
     3998
     3999See [[https://wiki.libsdl.org/SDL_IsScreenSaverEnabled|SDL_IsScreenSaverEnabled]],
     4000[[https://wiki.libsdl.org/SDL_EnableScreenSaver|SDL_EnableScreenSaver]],
     4001and [[https://wiki.libsdl.org/SDL_DisableScreenSaver|SDL_DisableScreenSaver]].
     4002
     4003
     4004<procedure>(has-clipboard-text?) → boolean</procedure>
     4005
     4006See [[https://wiki.libsdl.org/SDL_HasClipboardText|SDL_HasClipboardText]].
     4007
     4008
     4009<procedure>(get-clipboard-text) → string</procedure>
     4010
     4011See [[https://wiki.libsdl.org/SDL_GetClipboardText|SDL_GetClipboardText]].
     4012
     4013Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     4014
     4015
     4016<procedure>(set-clipboard-text! text)</procedure>
     4017
     4018See [[https://wiki.libsdl.org/SDL_SetClipboardText|SDL_SetClipboardText]].
     4019
     4020Signals an exception of kind {{(exn sdl2)}} if an error occurs.
Note: See TracChangeset for help on using the changeset viewer.