5 Windows and Renderers

9.0.0.11

Racket

5 Windows and Renderers🔗ℹ

SDL3 applications display graphics through windows and renderers. A window is an OS window that can display content. A renderer is a 2D rendering context attached to a window.

5.1 Creating Windows and Renderers🔗ℹ

syntax
(with-window+renderer title width height (win-id ren-id)
maybe-window-flags body ...)

maybe-window-flags =
| #:window-flags flags

flags : (or/c symbol? (listof symbol?))

Creates a window and renderer, binds them to win-id and ren-id, evaluates body, then destroys both resources.

This is the recommended way to create a window and renderer.

Available window flags:

'resizable — Window can be resized
'fullscreen — Fullscreen window
'high-pixel-density — High-DPI mode
'opengl — OpenGL rendering context

(with-sdl
  (with-window+renderer "My Game" 800 600 (win ren)
    ;; win and ren are available here
    (render-clear! ren)
    (render-present! ren)))

(with-window+renderer "Resizable" 800 600 (win ren)
  #:window-flags 'resizable
  ;; ...
  )

(with-window+renderer "HiDPI" 800 600 (win ren)
  #:window-flags '(resizable high-pixel-density)
  ;; ...
  )

syntax
(with-window title width height win-id body ...)

Creates a window without a renderer. Use this when you need a window but will create the renderer separately (e.g., for OpenGL contexts).

syntax
(with-renderer win ren-id body ...)

Creates a renderer for an existing window.

5.2 Window Functions🔗ℹ

procedure
(make-window title
width
height
[ #:flags flags
#:custodian cust]) → window?
  title : string?
  width : exact-positive-integer?
  height : exact-positive-integer?
  flags : (or/c symbol? (listof symbol?) #f) = '()
  cust : custodian? = (current-custodian)

Creates a new window. The window is registered with cust and will be destroyed when the custodian is shut down.

Returns a window? value.

procedure
(window? v) → boolean?
v : any/c

Returns #t if v is a window created by make-window.

procedure
(window-destroy! win) → void?
win : window?

Destroys a window. Usually not needed if using with-window or custodian-based cleanup.

5.2.1 Window Properties🔗ℹ

procedure
(window-title win) → string?
win : window?

Returns the window’s title.

procedure
(window-set-title! win title) → void?
win : window?
title : string?

Sets the window’s title.

procedure
(window-size win) →
exact-nonnegative-integer?
exact-nonnegative-integer?
win : window?

Returns the window’s client area size as two values: width and height.

(define-values (w h) (window-size win))
(printf "Window is ~ax~a~n" w h)

procedure
(window-set-size! win width height) → void?
  win : window?
  width : exact-positive-integer?
  height : exact-positive-integer?

Sets the window’s client area size.

procedure
(window-position win) →
exact-integer? exact-integer?
win : window?

Returns the window’s position as two values: x and y.

procedure
(window-set-position! win x y) → void?
  win : window?
  x : exact-integer?
  y : exact-integer?

Sets the window’s position.

procedure
(window-pixel-density win) → real?
win : window?

Returns the pixel density scale factor. On high-DPI displays, this may be greater than 1.0.

procedure
(window-id win) → exact-nonnegative-integer?
win : window?

Returns the window’s numeric ID.

procedure
(window-from-id id) → (or/c window? #f)
id : exact-nonnegative-integer?

Returns the window with the given ID, or #f if not found.

5.2.2 Window State🔗ℹ

procedure
(show-window! win) → void?
win : window?

Shows a hidden window.

procedure
(hide-window! win) → void?
win : window?

Hides a visible window.

procedure
(raise-window! win) → void?
win : window?

Raises the window above other windows and gives it input focus.

procedure
(maximize-window! win) → void?
win : window?

Maximizes the window.

procedure
(minimize-window! win) → void?
win : window?

Minimizes the window to the taskbar/dock.

procedure
(restore-window! win) → void?
win : window?

Restores a minimized or maximized window to its normal size.

procedure
(window-fullscreen? win) → boolean?
win : window?

Returns #t if the window is in fullscreen mode.

procedure
(window-set-fullscreen! win fullscreen?) → void?
win : window?
fullscreen? : boolean?

Sets the window’s fullscreen state.

5.2.3 Window Decoration🔗ℹ

procedure
(set-window-bordered! win bordered?) → void?
win : window?
bordered? : boolean?

Sets whether the window has a border.

procedure
(set-window-resizable! win resizable?) → void?
win : window?
resizable? : boolean?

Sets whether the window can be resized by the user.

procedure
(set-window-minimum-size! win width height) → void?
  win : window?
  width : exact-positive-integer?
  height : exact-positive-integer?

Sets the minimum allowed size for the window.

procedure
(set-window-maximum-size! win width height) → void?
  win : window?
  width : exact-positive-integer?
  height : exact-positive-integer?

Sets the maximum allowed size for the window.

procedure
(window-minimum-size win) →
exact-nonnegative-integer?
exact-nonnegative-integer?
win : window?

Returns the minimum size as two values: width and height.

procedure
(window-maximum-size win) →
exact-nonnegative-integer?
exact-nonnegative-integer?
win : window?

Returns the maximum size as two values: width and height.

5.2.4 Window Effects🔗ℹ

procedure
(window-opacity win) → real?
win : window?

Returns the window’s opacity (0.0 = transparent, 1.0 = opaque).

procedure
(set-window-opacity! win opacity) → void?
win : window?
opacity : real?

Sets the window’s opacity. opacity should be between 0.0 and 1.0.

procedure
(flash-window! win [operation]) → void?
win : window?
operation : (or/c 'cancel 'briefly 'until-focused) = 'briefly

Flashes the window to get user attention.

'briefly — Flash briefly (default)
'until-focused — Flash until the window gains focus
'cancel — Cancel any ongoing flash

procedure
(set-window-icon! win surface) → void?
win : window?
surface : any/c

Sets the window icon from a surface.

5.3 Renderer Functions🔗ℹ

procedure
(make-renderer win
[ #:name name
#:custodian cust]) → renderer?
  win : window?
  name : (or/c string? #f) = #f
  cust : custodian? = (current-custodian)

Creates a renderer for the given window. The renderer is registered with cust and will be destroyed when the custodian is shut down.

procedure
(renderer? v) → boolean?
v : any/c

Returns #t if v is a renderer.

procedure
(renderer-destroy! ren) → void?
ren : renderer?

Destroys a renderer. Usually not needed if using with-renderer or custodian-based cleanup.

procedure
(make-window+renderer title
width
height
[ #:window-flags window-flags
#:renderer-name renderer-name
#:custodian cust])
→
window? renderer?
  title : string?
  width : exact-positive-integer?
  height : exact-positive-integer?
  window-flags : (or/c symbol? (listof symbol?)) = '()
  renderer-name : (or/c string? #f) = #f
  cust : custodian? = (current-custodian)

Creates a window and renderer in one call. Returns two values.

(define-values (win ren)
(make-window+renderer "My App" 800 600))

5.4 Functional Alternatives🔗ℹ

For users who prefer explicit callbacks over syntax forms:

procedure
(call-with-sdl proc [#:flags flags]) → any
proc : (-> any)
flags : (or/c symbol? (listof symbol?)) = 'video

Initializes SDL, calls proc, then shuts down SDL.

procedure
(call-with-window title
width
height
proc
[ #:flags flags]) → any
  title : string?
  width : exact-positive-integer?
  height : exact-positive-integer?
  proc : (-> window? any)
  flags : (or/c symbol? (listof symbol?)) = '()

Creates a window, calls proc with it, then destroys the window.

procedure
(call-with-renderer win proc [#:name name]) → any
  win : window?
  proc : (-> renderer? any)
  name : (or/c string? #f) = #f

Creates a renderer, calls proc with it, then destroys the renderer.

procedure
(call-with-window+renderer title
width
height
proc
[ #:window-flags window-flags
#:renderer-name renderer-name]) → any
  title : string?
  width : exact-positive-integer?
  height : exact-positive-integer?
  proc : (-> window? renderer? any)
  window-flags : (or/c symbol? (listof symbol?)) = '()
  renderer-name : (or/c string? #f) = #f

Creates a window and renderer, calls proc with both, then destroys them.

1	Overview
2	Quick Start
3	Resource Management
4	Initialization
5	Windows and Renderers
6	Timer Functions
7	Configuration Hints
8	Properties
9	Drawing
10	Textures
11	Images and Surfaces
12	True Type Fonts
13	Rectangle Collision Detection
14	Events
15	Keyboard Functions
16	Mouse Functions
17	Gamepads
18	Joysticks
19	Audio
20	Camera
21	Display Information
22	Clipboard
23	Dialogs
24	System Tray
25	Open GL
26	Vulkan
27	GPU API

5.1	Creating Windows and Renderers
5.2	Window Functions
5.3	Renderer Functions
5.4	Functional Alternatives