10 Textures

10.1 Loading Textures🔗ℹ

procedure
(load-texture renderer
source
[ #:type type
#:custodian cust]) → texture?
  renderer : renderer?
  source : (or/c string? path? bytes? input-port?)
  type : (or/c symbol? string? #f) = #f
  cust : custodian? = (current-custodian)

Loads an image as a texture.

The source can be:

A file path (string or path)
Bytes containing image data
An input port

Supported formats include PNG, JPEG, BMP, GIF, and others via SDL_image.

The #:type hint specifies the image format when loading from bytes or a port. Use symbols like 'png, 'jpg, etc.

;; Load from file
(define tex (load-texture ren "sprites/player.png"))

;; Load from bytes with format hint
(define tex2 (load-texture ren image-bytes #:type 'png))

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

Returns #t if v is a texture.

procedure
(texture-ptr tex) → cpointer?
tex : texture?

Returns the underlying SDL texture pointer.

procedure
(texture-destroy! tex) → void?
tex : texture?

Destroys a texture and frees its GPU resources.

Note: Textures are automatically destroyed when their custodian shuts down, so manual destruction is usually not necessary.

10.2 Creating Textures🔗ℹ

procedure
(create-texture renderer
width
height
[ #:access access
#:scale scale
#:format format
#:custodian cust]) → texture?
  renderer : renderer?
  width : exact-nonnegative-integer?
  height : exact-nonnegative-integer?
  access : (or/c 'static 'streaming 'target) = 'target
  scale : (or/c 'nearest 'linear) = 'nearest
  format : exact-nonnegative-integer? = SDL_PIXELFORMAT_RGBA8888
  cust : custodian? = (current-custodian)

Creates a blank texture with the specified dimensions.

Access modes:

'static — Texture rarely changes, not lockable
'streaming — Texture changes frequently, lockable for CPU access
'target — Can be used as a render target

Scale modes:

'nearest — Nearest-neighbor sampling (pixelated look)
'linear — Linear filtering (smooth scaling)

;; Create a render target texture
(define target (create-texture ren 256 256 #:access 'target))

;; Create a streaming texture for dynamic updates
(define dynamic-tex (create-texture ren 64 64 #:access 'streaming))

procedure
(texture-from-pointer ptr [#:custodian cust]) → texture?
ptr : cpointer?
cust : custodian? = (current-custodian)

Wraps an existing SDL texture pointer in a texture struct.

The texture will be registered with the custodian for automatic cleanup.

10.3 Texture Properties🔗ℹ

procedure
(texture-size tex) →
real? real?
tex : texture?

Returns the width and height of the texture in pixels.

10.3.1 Scale Mode🔗ℹ

procedure
(texture-set-scale-mode! tex mode) → void?
tex : texture?
mode : (or/c 'nearest 'linear)

Sets the scale mode for a texture.

procedure
(texture-get-scale-mode tex) → symbol?
tex : texture?

Returns the current scale mode ('nearest or 'linear).

10.3.2 Blend Mode🔗ℹ

procedure
(set-texture-blend-mode! tex mode) → void?
tex : texture?
mode : (or/c symbol? exact-nonnegative-integer?)

Sets the blend mode for a texture.

Mode symbols include:

'none — No blending
'blend — Alpha blending
'add — Additive blending
'mod — Color modulation
'mul — Multiplicative blending

procedure
(get-texture-blend-mode tex) → symbol?
tex : texture?

Returns the current blend mode as a symbol.

10.4 Color and Alpha Modulation🔗ℹ

Color modulation tints the texture. Alpha modulation controls transparency.

procedure
(texture-set-color-mod! tex r g b) → void?
  tex : texture?
  r : byte?
  g : byte?
  b : byte?

Sets the color modulation (tint) for a texture.

Values are 0-255. The default (255, 255, 255) means no tint.

;; Tint texture red
(texture-set-color-mod! tex 255 100 100)

;; Remove tint
(texture-set-color-mod! tex 255 255 255)

procedure
(texture-get-color-mod tex) →
byte? byte? byte?
tex : texture?

Returns the current color modulation values.

procedure
(texture-set-alpha-mod! tex alpha) → void?
tex : texture?
alpha : byte?

Sets the alpha modulation (transparency) for a texture.

0 = fully transparent, 255 = fully opaque.

procedure
(texture-get-alpha-mod tex) → byte?
tex : texture?

Returns the current alpha modulation value.

10.4.1 Float Color/Alpha Modulation🔗ℹ

For extended range and precision, float versions are available:

procedure
(texture-set-color-mod-float! tex r g b) → void?
  tex : texture?
  r : real?
  g : real?
  b : real?

Sets color modulation using float values (typically 0.0-1.0).

procedure
(texture-get-color-mod-float tex) →
real? real? real?
tex : texture?

Returns float color modulation values.

procedure
(texture-set-alpha-mod-float! tex alpha) → void?
tex : texture?
alpha : real?

Sets alpha modulation using a float value (typically 0.0-1.0).

procedure
(texture-get-alpha-mod-float tex) → real?
tex : texture?

Returns float alpha modulation value.

10.5 Rendering Textures🔗ℹ

procedure
(render-texture! renderer
texture
x
y
[ #:width width
#:height height
#:src-x src-x
#:src-y src-y
#:src-w src-w
#:src-h src-h
#:angle angle
#:center center
#:flip flip]) → void?
  renderer : renderer?
  texture : texture?
  x : real?
  y : real?
  width : (or/c real? #f) = #f
  height : (or/c real? #f) = #f
  src-x : (or/c real? #f) = #f
  src-y : (or/c real? #f) = #f
  src-w : (or/c real? #f) = #f
  src-h : (or/c real? #f) = #f
  angle : (or/c real? #f) = #f
  center : (or/c (cons/c real? real?) #f) = #f
  flip : (or/c 'none 'horizontal 'vertical 'both #f) = #f

Renders a texture at the specified position.

Optional parameters:

#:width, #:height — Scale the texture to this size
#:src-x, #:src-y, #:src-w, #:src-h — Render only a portion of the texture (sprite sheet support)
#:angle — Rotation in degrees (clockwise)
#:center — Rotation center as (cons x y), defaults to texture center
#:flip — Flip the texture horizontally, vertically, or both

;; Simple render at position
(render-texture! ren tex 100 100)

;; Scale to specific size
(render-texture! ren tex 100 100 #:width 64 #:height 64)

;; Render a sprite from a sprite sheet
(render-texture! ren sprites 100 100
#:src-x (* frame 32) #:src-y 0
#:src-w 32 #:src-h 32)

;; Rotate 45 degrees
(render-texture! ren tex 100 100 #:angle 45.0)

;; Flip horizontally (for character facing)
(render-texture! ren tex 100 100 #:flip 'horizontal)

procedure
(render-texture-affine! renderer
texture
origin
right
down
[ #:src-x src-x
#:src-y src-y
#:src-w src-w
#:src-h src-h]) → void?
  renderer : renderer?
  texture : texture?
  origin : (or/c (cons/c real? real?) #f)
  right : (or/c (cons/c real? real?) #f)
  down : (or/c (cons/c real? real?) #f)
  src-x : (or/c real? #f) = #f
  src-y : (or/c real? #f) = #f
  src-w : (or/c real? #f) = #f
  src-h : (or/c real? #f) = #f

Renders a texture with an arbitrary affine transformation.

This allows for skewing, shearing, and other 2D transformations.

origin — Where the top-left corner appears
right — Where the top-right corner appears
down — Where the bottom-left corner appears

The bottom-right is inferred from these three points.

procedure
(render-texture-tiled! renderer
texture
dst-x
dst-y
dst-w
dst-h
[ #:scale scale
#:src-x src-x
#:src-y src-y
#:src-w src-w
#:src-h src-h]) → void?
  renderer : renderer?
  texture : texture?
  dst-x : real?
  dst-y : real?
  dst-w : real?
  dst-h : real?
  scale : real? = 1.0
  src-x : (or/c real? #f) = #f
  src-y : (or/c real? #f) = #f
  src-w : (or/c real? #f) = #f
  src-h : (or/c real? #f) = #f

Renders a texture tiled to fill a destination rectangle.

Useful for repeating patterns like backgrounds and floors.

;; Tile a grass texture across the ground
(render-texture-tiled! ren grass-tex 0 400 800 200)

procedure
(render-texture-9grid! renderer
texture
dst-x
dst-y
dst-w
dst-h
#:left-width left-width
#:right-width right-width
#:top-height top-height
#:bottom-height bottom-height
[ #:scale scale
#:src-x src-x
#:src-y src-y
#:src-w src-w
#:src-h src-h]) → void?
  renderer : renderer?
  texture : texture?
  dst-x : real?
  dst-y : real?
  dst-w : real?
  dst-h : real?
  left-width : real?
  right-width : real?
  top-height : real?
  bottom-height : real?
  scale : real? = 1.0
  src-x : (or/c real? #f) = #f
  src-y : (or/c real? #f) = #f
  src-w : (or/c real? #f) = #f
  src-h : (or/c real? #f) = #f

Renders a texture using 9-slice scaling.

This is ideal for UI elements like buttons and panels that need to scale without distorting corners.

The texture is divided into 9 regions: 4 corners (which don’t scale), 4 edges (which scale in one direction), and a center (which scales in both).

10.6 Render Targets🔗ℹ

Textures created with #:access 'target can be used as render targets, allowing you to draw onto them instead of the screen.

procedure
(set-render-target! renderer texture) → void?
renderer : renderer?
texture : (or/c texture? #f)

Sets the current render target.

Pass #f to restore rendering to the default target (the window).

;; Draw to an offscreen texture
(define offscreen (create-texture ren 256 256 #:access 'target))
(set-render-target! ren offscreen)
(set-draw-color! ren 0 0 0)
(render-clear! ren)
(set-draw-color! ren 255 0 0)
(fill-rect! ren 10 10 50 50)

;; Restore normal rendering and use the texture
(set-render-target! ren #f)
(render-texture! ren offscreen 100 100)

procedure
(get-render-target renderer) → (or/c texture? #f)
renderer : renderer?

Returns the current render target, or #f if rendering to the window.

syntax
(with-render-target renderer texture body ...)

Temporarily renders to a texture, then restores the previous target.

(with-render-target ren offscreen
  (set-draw-color! ren 0 0 0)
  (render-clear! ren)
  (draw-scene-to-texture!))

10.7 Texture Updates and Locking🔗ℹ

For streaming textures, you can update pixel data directly.

procedure
(texture-update! texture
pixels
pitch
[ #:rect rect]) → void?
  texture : texture?
  pixels : (or/c bytes? cpointer?)
  pitch : exact-nonnegative-integer?
  rect : (or/c (list/c real? real? real? real?) #f) = #f

Updates texture pixel data.

pitch is the number of bytes per row in the source data. rect specifies the region to update as (list x y w h), or #f for the entire texture.

procedure
(texture-lock! texture [#:rect rect])
→
cpointer? exact-nonnegative-integer?
texture : texture?
rect : (or/c (list/c real? real? real? real?) #f) = #f

Locks a streaming texture for direct pixel access.

Returns a pointer to the pixel data and the pitch (bytes per row). Call texture-unlock! when done.

procedure
(texture-unlock! texture) → void?
texture : texture?

Unlocks a texture after locking.

procedure
(call-with-locked-texture texture
proc
[ #:rect rect]) → any
  texture : texture?
   proc :
(-> cpointer? exact-nonnegative-integer?
    exact-nonnegative-integer? exact-nonnegative-integer?
    any)
  rect : (or/c (list/c real? real? real? real?) #f) = #f

Locks a texture, calls the procedure, and unlocks it.

The procedure receives: pixels-pointer, width, height, pitch.

(call-with-locked-texture tex
  (lambda (pixels w h pitch)
    ;; Modify pixels directly
    (for ([y (in-range h)])
      (for ([x (in-range w)])
        (define offset (+ (* y pitch) (* x 4)))
        ;; Set pixel to red (RGBA)
        (ptr-set! pixels _uint8 offset 255)
        (ptr-set! pixels _uint8 (+ offset 1) 0)
        (ptr-set! pixels _uint8 (+ offset 2) 0)
        (ptr-set! pixels _uint8 (+ offset 3) 255)))))

10.8 Flip Mode Conversion🔗ℹ

procedure
(symbol->flip-mode sym) → exact-nonnegative-integer?
sym : symbol?

Converts a flip mode symbol to its SDL constant.

Symbols: 'none, 'horizontal (or 'h), 'vertical (or 'v), 'both (or 'hv).

procedure
(flip-mode->symbol mode) → symbol?
mode : exact-nonnegative-integer?

Converts an SDL flip mode constant to a symbol.

10.9 Access Mode Conversion🔗ℹ

procedure
(symbol->texture-access sym) → exact-nonnegative-integer?
sym : symbol?

Converts an access mode symbol to its SDL constant.

Symbols: 'static, 'streaming, 'target.

procedure
(texture-access->symbol mode) → symbol?
mode : exact-nonnegative-integer?

Converts an SDL texture access constant to a symbol.

10.10 Scale Mode Conversion🔗ℹ

procedure
(symbol->scale-mode sym) → exact-nonnegative-integer?
sym : symbol?

Converts a scale mode symbol to its SDL constant.

Symbols: 'nearest, 'linear.

procedure
(scale-mode->symbol mode) → symbol?
mode : exact-nonnegative-integer?

Converts an SDL scale mode constant to a symbol.

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

10.1	Loading Textures
10.2	Creating Textures
10.3	Texture Properties
10.4	Color and Alpha Modulation
10.5	Rendering Textures
10.6	Render Targets
10.7	Texture Updates and Locking
10.8	Flip Mode Conversion
10.9	Access Mode Conversion
10.10	Scale Mode Conversion

10 Textures🔗ℹ