▼SDL3:   Racket Bindings for SDL3
►27 GPU API
On this page:
27.1 Devices
make-gpu-device
gpu-device?
gpu-device-destroy!
gpu-device-driver
gpu-device-shader-formats
gpu-supports-shader-formats?
27.2 Swapchain
gpu-claim-window!
gpu-release-window!
gpu-swapchain-texture-format
gpu-set-swapchain-parameters!
gpu-acquire-swapchain-texture
gpu-wait-for-swapchain!
27.3 Command Buffers
gpu-acquire-command-buffer
gpu-submit!
gpu-submit-and-acquire-fence!
gpu-cancel-command-buffer!
27.4 Render Passes
gpu-begin-render-pass
gpu-end-render-pass!
27.5 Graphics Pipelines
make-gpu-graphics-pipeline
gpu-graphics-pipeline?
gpu-graphics-pipeline-destroy!
gpu-bind-graphics-pipeline!
27.6 Shaders
make-gpu-shader
gpu-shader?
gpu-shader-ptr
gpu-shader-destroy!
27.7 Buffers
27.7.1 GPU Buffers
make-gpu-buffer
gpu-buffer?
gpu-buffer-ptr
gpu-buffer-destroy!
27.7.2 Transfer Buffers
make-gpu-transfer-buffer
gpu-transfer-buffer?
gpu-transfer-buffer-ptr
gpu-transfer-buffer-destroy!
gpu-map-transfer-buffer
gpu-unmap-transfer-buffer!
27.8 Copy Passes
gpu-begin-copy-pass
gpu-end-copy-pass!
gpu-upload-to-buffer!
gpu-upload-to-texture!
27.9 Textures
make-gpu-texture
gpu-texture?
gpu-texture-destroy!
gpu-set-texture-name!
27.10 Samplers
make-gpu-sampler
gpu-sampler?
gpu-sampler-destroy!
27.11 Drawing
gpu-bind-vertex-buffers!
gpu-bind-index-buffer!
gpu-set-viewport!
gpu-set-scissor!
gpu-push-vertex-uniform-data!
gpu-push-fragment-uniform-data!
gpu-draw-primitives!
gpu-draw-indexed-primitives!
27.12 Fences
gpu-fence?
gpu-query-fence
gpu-release-fence!
gpu-wait-for-idle!
27.13 Blitting
gpu-blit-texture!
9.0.0.11
Racket
  top  contents    up  next → 

27 GPU API🔗ℹ

This section covers SDL3’s new GPU API, which provides a modern cross-platform graphics abstraction supporting Vulkan, Direct3D 12, and Metal backends.

The GPU API is more complex than the 2D renderer but provides much more power and control for 3D graphics and compute workloads.

27.1 Devices🔗ℹ

procedure

(make-gpu-device [#:shader-formats formats    
  #:debug? debug?    
  #:driver driver]) → gpu-device?
  formats : exact-nonnegative-integer?
   = SDL_GPU_SHADERFORMAT_SPIRV
  debug? : boolean? = #f
  driver : (or/c string? #f) = #f
Creates a GPU device.

formats specifies which shader formats are required (e.g., SPIRV, DXBC, MSL). debug? enables debug/validation layers. driver optionally forces a specific backend.

(define device (make-gpu-device #:debug? #t))

procedure

(gpu-device? v) → boolean?

  v : any/c
Returns #t if v is a GPU device.

procedure

(gpu-device-destroy! device) → void?

  device : gpu-device?
Destroys a GPU device.

Note: Devices are automatically destroyed when their custodian shuts down.

procedure

(gpu-device-driver device) → string?

  device : gpu-device?
Returns the name of the GPU driver in use.

procedure

(gpu-device-shader-formats device) → exact-nonnegative-integer?

  device : gpu-device?
Returns the shader formats supported by the device.

procedure

(gpu-supports-shader-formats? formats    
  [#:driver driver]) → boolean?
  formats : exact-nonnegative-integer?
  driver : (or/c string? #f) = #f
Returns #t if the specified shader formats are supported.

27.2 Swapchain🔗ℹ

The swapchain manages the images presented to a window.

procedure

(gpu-claim-window! device window) → void?

  device : gpu-device?
  window : cpointer?
Claims a window for GPU rendering.

Must be called before acquiring swapchain textures.

procedure

(gpu-release-window! device window) → void?

  device : gpu-device?
  window : cpointer?
Releases a window from GPU rendering.

procedure

(gpu-swapchain-texture-format device 
  window) 
 → exact-nonnegative-integer?
  device : gpu-device?
  window : cpointer?
Returns the pixel format of the swapchain.

procedure

(gpu-set-swapchain-parameters! device    
  window    
  composition    
  present-mode) → void?
  device : gpu-device?
  window : cpointer?
  composition : exact-nonnegative-integer?
  present-mode : exact-nonnegative-integer?
Sets swapchain presentation parameters.

procedure

(gpu-acquire-swapchain-texture cmd-buffer 
  window) 
 → 
(or/c cpointer? #f)
exact-nonnegative-integer?
exact-nonnegative-integer?
  cmd-buffer : cpointer?
  window : cpointer?
Acquires the next swapchain texture for rendering.

Returns (values texture width height), or (values #f 0 0) if no texture is available.

procedure

(gpu-wait-for-swapchain! device window) → void?

  device : gpu-device?
  window : cpointer?
Waits for the swapchain to be ready.

27.3 Command Buffers🔗ℹ

Command buffers record GPU commands for later submission.

procedure

(gpu-acquire-command-buffer device) → cpointer?

  device : gpu-device?
Acquires a command buffer for recording commands.

procedure

(gpu-submit! cmd-buffer) → void?

  cmd-buffer : cpointer?
Submits a command buffer for execution.

procedure

(gpu-submit-and-acquire-fence! device    
  cmd-buffer) → gpu-fence?
  device : gpu-device?
  cmd-buffer : cpointer?
Submits a command buffer and returns a fence for synchronization.

procedure

(gpu-cancel-command-buffer! cmd-buffer) → void?

  cmd-buffer : cpointer?
Cancels a command buffer without submitting.

27.4 Render Passes🔗ℹ

Render passes define a set of render targets and rendering operations.

procedure

(gpu-begin-render-pass cmd-buffer 
  color-targets 
  [#:depth-stencil-target depth-stencil]) 
 → cpointer?
  cmd-buffer : cpointer?
  color-targets : cpointer?
  depth-stencil : (or/c cpointer? #f) = #f
Begins a render pass.

color-targets is a pointer to color target info structures.

procedure

(gpu-end-render-pass! pass) → void?

  pass : cpointer?
Ends a render pass.

27.5 Graphics Pipelines🔗ℹ

Pipelines define the complete graphics state for rendering.

procedure

(make-gpu-graphics-pipeline device 
  create-info) 
 → gpu-graphics-pipeline?
  device : gpu-device?
  create-info : cpointer?
Creates a graphics pipeline.

procedure

(gpu-graphics-pipeline? v) → boolean?

  v : any/c
Returns #t if v is a graphics pipeline.

procedure

(gpu-graphics-pipeline-destroy! pipeline) → void?

  pipeline : gpu-graphics-pipeline?
Destroys a graphics pipeline.

procedure

(gpu-bind-graphics-pipeline! render-pass    
  pipeline) → void?
  render-pass : cpointer?
  pipeline : gpu-graphics-pipeline?
Binds a graphics pipeline in a render pass.

27.6 Shaders🔗ℹ

procedure

(make-gpu-shader device create-info) → gpu-shader?

  device : gpu-device?
  create-info : cpointer?
Creates a shader from compiled bytecode.

procedure

(gpu-shader? v) → boolean?

  v : any/c
Returns #t if v is a shader.

procedure

(gpu-shader-ptr shader) → cpointer?

  shader : gpu-shader?
Returns the underlying shader pointer.

procedure

(gpu-shader-destroy! shader) → void?

  shader : gpu-shader?
Destroys a shader.

27.7 Buffers🔗ℹ

27.7.1 GPU Buffers🔗ℹ

GPU buffers hold vertex, index, and uniform data on the GPU.

procedure

(make-gpu-buffer device create-info) → gpu-buffer?

  device : gpu-device?
  create-info : cpointer?
Creates a GPU buffer.

procedure

(gpu-buffer? v) → boolean?

  v : any/c
Returns #t if v is a GPU buffer.

procedure

(gpu-buffer-ptr buffer) → cpointer?

  buffer : gpu-buffer?
Returns the underlying buffer pointer.

procedure

(gpu-buffer-destroy! buffer) → void?

  buffer : gpu-buffer?
Destroys a GPU buffer.

27.7.2 Transfer Buffers🔗ℹ

Transfer buffers are used to upload data from CPU to GPU.

procedure

(make-gpu-transfer-buffer device    
  create-info) → gpu-transfer-buffer?
  device : gpu-device?
  create-info : cpointer?
Creates a transfer buffer.

procedure

(gpu-transfer-buffer? v) → boolean?

  v : any/c
Returns #t if v is a transfer buffer.

procedure

(gpu-transfer-buffer-ptr buffer) → cpointer?

  buffer : gpu-transfer-buffer?
Returns the underlying buffer pointer.

procedure

(gpu-transfer-buffer-destroy! buffer) → void?

  buffer : gpu-transfer-buffer?
Destroys a transfer buffer.

procedure

(gpu-map-transfer-buffer device    
  buffer    
  [#:cycle? cycle?]) → cpointer?
  device : gpu-device?
  buffer : gpu-transfer-buffer?
  cycle? : boolean? = #f
Maps a transfer buffer for CPU access.

Returns a pointer to the buffer memory.

procedure

(gpu-unmap-transfer-buffer! device buffer) → void?

  device : gpu-device?
  buffer : gpu-transfer-buffer?
Unmaps a transfer buffer.

27.8 Copy Passes🔗ℹ

Copy passes transfer data between buffers and textures.

procedure

(gpu-begin-copy-pass cmd-buffer) → cpointer?

  cmd-buffer : cpointer?
Begins a copy pass.

procedure

(gpu-end-copy-pass! pass) → void?

  pass : cpointer?
Ends a copy pass.

procedure

(gpu-upload-to-buffer! copy-pass    
  source    
  destination    
  [#:cycle? cycle?]) → void?
  copy-pass : cpointer?
  source : cpointer?
  destination : cpointer?
  cycle? : boolean? = #f
Uploads data from a transfer buffer to a GPU buffer.

procedure

(gpu-upload-to-texture! copy-pass    
  source    
  destination    
  [#:cycle? cycle?]) → void?
  copy-pass : cpointer?
  source : cpointer?
  destination : cpointer?
  cycle? : boolean? = #f
Uploads data from a transfer buffer to a texture.

27.9 Textures🔗ℹ

procedure

(make-gpu-texture device create-info) → gpu-texture?

  device : gpu-device?
  create-info : cpointer?
Creates a GPU texture.

procedure

(gpu-texture? v) → boolean?

  v : any/c
Returns #t if v is a GPU texture.

procedure

(gpu-texture-destroy! texture) → void?

  texture : gpu-texture?
Destroys a GPU texture.

procedure

(gpu-set-texture-name! device texture name) → void?

  device : gpu-device?
  texture : gpu-texture?
  name : string?
Sets a debug name for a texture.

27.10 Samplers🔗ℹ

procedure

(make-gpu-sampler device create-info) → gpu-sampler?

  device : gpu-device?
  create-info : cpointer?
Creates a texture sampler.

procedure

(gpu-sampler? v) → boolean?

  v : any/c
Returns #t if v is a sampler.

procedure

(gpu-sampler-destroy! sampler) → void?

  sampler : gpu-sampler?
Destroys a sampler.

27.11 Drawing🔗ℹ

procedure

(gpu-bind-vertex-buffers! render-pass    
  bindings    
  [#:first-slot first-slot]) → void?
  render-pass : cpointer?
  bindings : cpointer?
  first-slot : exact-nonnegative-integer? = 0
Binds vertex buffers in a render pass.

procedure

(gpu-bind-index-buffer! render-pass    
  binding    
  element-size) → void?
  render-pass : cpointer?
  binding : cpointer?
  element-size : exact-nonnegative-integer?
Binds an index buffer in a render pass.

procedure

(gpu-set-viewport! render-pass viewport) → void?

  render-pass : cpointer?
  viewport : cpointer?
Sets the viewport in a render pass.

procedure

(gpu-set-scissor! render-pass rect) → void?

  render-pass : cpointer?
  rect : cpointer?
Sets the scissor rectangle in a render pass.

procedure

(gpu-push-vertex-uniform-data! cmd-buffer    
  slot    
  data    
  length) → void?
  cmd-buffer : cpointer?
  slot : exact-nonnegative-integer?
  data : cpointer?
  length : exact-nonnegative-integer?
Pushes vertex shader uniform data.

procedure

(gpu-push-fragment-uniform-data! cmd-buffer    
  slot    
  data    
  length) → void?
  cmd-buffer : cpointer?
  slot : exact-nonnegative-integer?
  data : cpointer?
  length : exact-nonnegative-integer?
Pushes fragment shader uniform data.

procedure

(gpu-draw-primitives! render-pass    
  num-vertices    
  [#:num-instances num-instances    
  #:first-vertex first-vertex    
  #:first-instance first-instance]) → void?
  render-pass : cpointer?
  num-vertices : exact-nonnegative-integer?
  num-instances : exact-nonnegative-integer? = 1
  first-vertex : exact-nonnegative-integer? = 0
  first-instance : exact-nonnegative-integer? = 0
Draws non-indexed primitives.

procedure

(gpu-draw-indexed-primitives! render-pass 
  num-indices 
  [#:num-instances num-instances 
  #:first-index first-index 
  #:vertex-offset vertex-offset 
  #:first-instance first-instance]) 
 → void?
  render-pass : cpointer?
  num-indices : exact-nonnegative-integer?
  num-instances : exact-nonnegative-integer? = 1
  first-index : exact-nonnegative-integer? = 0
  vertex-offset : exact-integer? = 0
  first-instance : exact-nonnegative-integer? = 0
Draws indexed primitives.

27.12 Fences🔗ℹ

Fences are used for GPU-CPU synchronization.

procedure

(gpu-fence? v) → boolean?

  v : any/c
Returns #t if v is a fence.

procedure

(gpu-query-fence fence) → boolean?

  fence : gpu-fence?
Returns #t if the fence has signaled.

procedure

(gpu-release-fence! fence) → void?

  fence : gpu-fence?
Releases a fence.

procedure

(gpu-wait-for-idle! device) → void?

  device : gpu-device?
Waits for all GPU work to complete.

27.13 Blitting🔗ℹ

procedure

(gpu-blit-texture! cmd-buffer blit-info) → void?

  cmd-buffer : cpointer?
  blit-info : cpointer?
Copies and optionally scales/converts a texture region.

  top  contents    up  next →