Pack sdlpl -- prolog/sdl/gpu.pl

sdl_gpu_shader_format(?Format:atom, ?Value:integer) is nondet

Shader backend bytecode formats. A list of these atoms is passed to sdl_creategpudevice/4 so SDL can pick a backend supporting at least one of them. The private atom means no format is requested; it is not a sdl_gpu_shader_format and is handled separately by sdl_creategpudevice.

private
spirv
dxbc
dxil
msl
metallib

See also: - https://wiki.libsdl.org/SDL3/SDL_GPUShaderFormat

sdl_getgpudriver(+Index:integer, -Name:atom) is det

Returns the name of the compiled-in GPU driver at Index (e.g. vulkan, direct3d12, metal). Index ranges from 0 to sdl_getnumgpudrivers - 1; an out-of-range index throws an error.

See also: - https://wiki.libsdl.org/SDL3/SDL_GetGPUDriver

sdl_creategpudevice(-Device:blob, +ShaderFormats:list(sdl_gpu_shader_format), +Debug:boolean, +Name:oneof([null]);sdl_gpu_driver) is det

Creates a GPU device. ShaderFormats is the list of shader bytecode formats this backend must support; SDL picks a backend supporting at least one of them. Debug enables the GPU validation layer. Name is null to use the default driver or one of the driver atoms returned by sdl_getgpudriver/2.

The device is the root handle from which windows and resources are claimed/created.

See also: - https://wiki.libsdl.org/SDL3/SDL_CreateGPUDevice

sdl_destroygpudevice(+Device:blob) is det

Destroys the GPU device, releasing all claimed windows and resources created from it on the SDL side. The Blob is invalid after this call.

See also: - https://wiki.libsdl.org/SDL3/SDL_DestroyGPUDevice

sdl_claimwindowforgpudevice(+Device:blob, +Window:blob) is det

Claims a window for GPU rendering (creates its swapchain) or releases it. The window must have been created with the backend-matching window flag (vulkan on Linux/Windows, metal on macOS). These are state mutations on existing handles — no new blob is produced, like sdl_setwindowposition.

The device blob maintains a registered-ref list of claimed windows so the window blob cannot be GC'd while the claim is live (mirrors the SDLRendererBlob -> SDLWindowBlob parent ref). sdl_releasewindowfrom- gpudevice/2 throws existence_error(claimed_window, Window) if the window is not currently claimed by the device, catching double-release and release-without-claim bugs. SDL_DestroyGPUDevice releases all claimed windows on the SDL side and clears the ref list, so explicit release is only required to reclaim a window before device destruction.

sdl_releasewindowfromgpudevice(+Device:blob, +Window:blob) is det

Releases a window previously claimed with sdl_claimwindowforgpudevice/2, removing its swapchain. Throws existence_error(claimed_window, Window) if the window is not currently claimed by the device, catching double-release and release-without-claim bugs. SDL_DestroyGPUDevice releases all claimed windows on the SDL side, so this is only required to reclaim a window before device destruction.

See also: - https://wiki.libsdl.org/SDL3/SDL_ReleaseWindowFromGPUDevice

sdl_acquiregpucommandbuffer(-CmdBuf:blob, +Device:blob) is det

Acquire a command buffer for the current frame. Commands are recorded into it, then submitted to the GPU. The command buffer may only be used on the thread that acquired it.

RAII: if a command buffer blob is GC'd without being submitted (e.g. an exception discarded it mid-frame), the foreign destroy hook calls SDL_CancelGPUCommandBuffer to prevent a leak. After a successful submit the blob is marked consumed so the cancel path is not triggered. The blob holds a parent ref to the device, pinning it against GC for the command buffer's lifetime (mirrors SDLRendererBlob -> SDLWindowBlob).

Submitting an already-submitted/cancelled command buffer raises existence_error(command_buffer, CmdBuf).

See also: - https://wiki.libsdl.org/SDL3/SDL_AcquireGPUCommandBuffer

sdl_submitgpucommandbuffer(+CmdBuf:blob) is det

Submits the command buffer to the GPU for execution. After submission the command buffer pointer is invalid; the blob is marked consumed so its destructor does not cancel an already-submitted buffer. Submitting an already-submitted/cancelled command buffer raises existence_error(command_buffer, CmdBuf).

See also: - https://wiki.libsdl.org/SDL3/SDL_SubmitGPUCommandBuffer

sdl_cancelgpucommandbuffer(+CmdBuf:blob) is det

Cancels a command buffer acquired with sdl_acquiregpucommandbuffer/2, discarding any recorded commands. CmdBuf is consumed; after this call the buffer is invalid. Cancelling an already-submitted/cancelled buffer raises existence_error(command_buffer, CmdBuf).

See also: - https://wiki.libsdl.org/SDL3/SDL_CancelGPUCommandBuffer

sdl_acquiregpuswapchaintexture(+CmdBuf:blob, +Window:blob, -Texture:null;blob, -Width:integer, -Height:integer) is det

Acquires the swapchain texture for the current frame (non-blocking). Texture may be the atom null when the window is minimized or too many frames are in flight — this is not an error; skip rendering that frame and submit the empty command buffer. The texture is managed by SDL (must not be freed) and is valid only within CmdBuf. After acquiring a swapchain texture, submit the command buffer rather than cancelling it (SDL handles presentation).

See also: - https://wiki.libsdl.org/SDL3/SDL_AcquireGPUSwapchainTexture

sdl_waitandacquiregpuswapchaintexture(+CmdBuf:blob, +Window:blob, -Texture:null;blob, -Width:integer, -Height:integer) is det

Blocking variant of sdl_acquiregpuswapchaintexture/5: waits until a swapchain texture is available, then acquires it. Texture may still be the atom null when the window is minimized — this is not an error; skip rendering that frame and submit the empty command buffer. The texture is managed by SDL (must not be freed) and is valid only within CmdBuf. After acquiring a swapchain texture, submit the command buffer rather than cancelling it (SDL handles presentation).

See also: - https://wiki.libsdl.org/SDL3/SDL_WaitAndAcquireGPUSwapchainTexture

sdl_gpu_load_op(?LoadOp:atom, ?Value:integer) is nondet

Enumerate SDL_GPULoadOp values. Each flag is a Prolog atom linked to its SDL enum value.

The user-facing load-op atoms are:

load
clear
dont_care

See also: - https://wiki.libsdl.org/SDL3/SDL_GPULoadOp

sdl_gpu_store_op(?StoreOp:atom, ?Value:integer) is nondet

Enumerate SDL_GPUStoreOp values. Each flag is a Prolog atom linked to its SDL enum value.

The user-facing store-op atoms are:

store
dont_care
resolve
resolve_and_store

See also: - https://wiki.libsdl.org/SDL3/SDL_GPUStoreOp

sdl_gpu_texture_type(?Type:atom, ?Value:integer) is nondet

Enumerate SDL_GPUTextureType values. Each flag is a Prolog atom linked to its SDL enum value.

The user-facing texture-type atoms are:

`2d` -- normal 2D texture
`2d_array` -- 2D texture array
`3d` -- 3D texture
cube -- cubemap
cube_array -- cubemap array

See also: - https://wiki.libsdl.org/SDL3/SDL_GPUTextureType

sdl_gpu_texture_usage(?Usage:atom, ?Value:integer) is nondet

Enumerate SDL_GPUTextureUsageFlag values. Each flag is a Prolog atom linked to its SDL bit-mask value; a list of these atoms may be combined into a single mask where used.

The user-facing texture-usage atoms are:

sampler
color_target
depth_stencil_target
graphics_storage_read
compute_storage_read
compute_storage_write
compute_storage_simultaneous_read_write

See also: - https://wiki.libsdl.org/SDL3/SDL_GPUTextureUsageFlags

sdl_gpu_sample_count(?Count:integer, ?Value:integer) is nondet

Enumerate SDL_GPUSampleCount values. Each flag is a Prolog integer linked to its SDL enum value.

The user-facing sample-count values are:

See also: - https://wiki.libsdl.org/SDL3/SDL_GPUSampleCount

sdl_gpu_texture_format(?Format:atom, ?Value:integer) is nondet

Enumerate SDL_GPUTextureFormat values. Each Format is a Prolog atom linked to its SDL enum value. Generated from SDL_gpu.h.

The user-facing texture-format atoms are:

invalid
a8_unorm
r8_unorm
r8g8_unorm
r8g8b8a8_unorm
r16_unorm
r16g16_unorm
r16g16b16a16_unorm
r10g10b10a2_unorm
b5g6r5_unorm
b5g5r5a1_unorm
b4g4r4a4_unorm
b8g8r8a8_unorm
bc1_rgba_unorm
bc2_rgba_unorm
bc3_rgba_unorm
bc4_r_unorm
bc5_rg_unorm
bc7_rgba_unorm
bc6h_rgb_float
bc6h_rgb_ufloat
r8_snorm
r8g8_snorm
r8g8b8a8_snorm
r16_snorm
r16g8_snorm
r16g16b16a16_snorm
r16_float
r16g16_float
r16g16b16a16_float
r32_float
r32g32_float
r32g32b32a32_float
r11g11b10_ufloat
r8_uint
r8g8_uint
r8g8b8a8_uint
r16_uint
r16g16_uint
r16g16b16a16_uint
r32_uint
r32g32_uint
r32g32b32a32_uint
r8_int
r8g8_int
r8g8b8a8_int
r16_int
r16g16_int
r16g16b16a16_int
r32_int
r32g32_int
r32g32b32a32_int
r8g8b8a8_unorm_srgb
b8g8r8a8_unorm_srgb
bc1_rgba_unorm_srgb
bc2_rgba_unorm_srgb
bc3_rgba_unorm_srgb
bc7_rgba_unorm_srgb
d16_unorm
d24_unorm
d32_float
d24_unorm_s8_uint
d32_float_s8_uint
astc_4x4_unorm
astc_5x4_unorm
astc_5x5_unorm
astc_6x5_unorm
astc_6x6_unorm
astc_8x5_unorm
astc_8x6_unorm
astc_8x8_unorm
astc_10x5_unorm
astc_10x6_unorm
astc_10x8_unorm
astc_10x10_unorm
astc_12x10_unorm
astc_12x12_unorm
astc_4x4_unorm_srgb
astc_5x4_unorm_srgb
astc_5x5_unorm_srgb
astc_6x5_unorm_srgb
astc_6x6_unorm_srgb
astc_8x5_unorm_srgb
astc_8x6_unorm_srgb
astc_8x8_unorm_srgb
astc_10x5_unorm_srgb
astc_10x6_unorm_srgb
astc_10x8_unorm_srgb
astc_10x10_unorm_srgb
astc_12x10_unorm_srgb
astc_12x12_unorm_srgb
astc_4x4_float
astc_5x4_float
astc_5x5_float
astc_6x5_float
astc_6x6_float
astc_8x5_float
astc_8x6_float
astc_8x8_float
astc_10x5_float
astc_10x6_float
astc_10x8_float
astc_10x10_float
astc_12x10_float
astc_12x12_float

See also: - https://wiki.libsdl.org/SDL3/SDL_GPUTextureFormat sdl_gpu_texture_format/2 — maps SDL_GPUTextureFormat enum values.

sdl_gpu_shader_stage(?Stage:atom, ?Value:integer) is nondet

Enumerate SDL_GPUShaderStage values. Each flag is a Prolog atom linked to its SDL enum value.

The user-facing shader-stage atoms are:

vertex
fragment

See also: - https://wiki.libsdl.org/SDL3/SDL_GPUShaderStage

sdl_gpu_primitive_type(?Type:atom, ?Value:integer) is nondet

Enumerate SDL_GPUPrimitiveType values. Each flag is a Prolog atom linked to its SDL enum value.

The user-facing primitive-type atoms are:

trianglelist
trianglestrip
linelist
linestrip
pointlist

See also: - https://wiki.libsdl.org/SDL3/SDL_GPUPrimitiveType

sdl_gpu_fill_mode(?Mode:atom, ?Value:integer) is nondet

Enumerate SDL_GPUFillMode values. Each flag is a Prolog atom linked to its SDL enum value.

The user-facing fill-mode atoms are:

fill
line

See also: - https://wiki.libsdl.org/SDL3/SDL_GPUFillMode

sdl_gpu_cull_mode(?Mode:atom, ?Value:integer) is nondet

Enumerate SDL_GPUCullMode values. Each flag is a Prolog atom linked to its SDL enum value.

The user-facing cull-mode atoms are:

none
front
back

See also: - https://wiki.libsdl.org/SDL3/SDL_GPUCullMode

sdl_gpu_front_face(?Face:atom, ?Value:integer) is nondet

Enumerate SDL_GPUFrontFace values. Each flag is a Prolog atom linked to its SDL enum value.

The user-facing front-face atoms are:

counter_clockwise
clockwise

See also: - https://wiki.libsdl.org/SDL3/SDL_GPUFrontFace

sdl_gpu_compare_op(?Op:atom, ?Value:integer) is nondet

Enumerate SDL_GPUCompareOp values. Each flag is a Prolog atom linked to its SDL enum value.

The user-facing compare-op atoms are:

invalid
never
less
equal
less_or_equal
greater
not_equal
greater_or_equal
always

See also: - https://wiki.libsdl.org/SDL3/SDL_GPUCompareOp

sdl_gpu_stencil_op(?Op:atom, ?Value:integer) is nondet

Enumerate SDL_GPUStencilOp values. Each flag is a Prolog atom linked to its SDL enum value.

The user-facing stencil-op atoms are:

invalid
keep
zero
replace
increment_and_clamp
decrement_and_clamp
invert
increment_and_wrap
decrement_and_wrap

See also: - https://wiki.libsdl.org/SDL3/SDL_GPUStencilOp

sdl_gpu_blend_op(?Op:atom, ?Value:integer) is nondet

Enumerate SDL_GPUBlendOp values. Each flag is a Prolog atom linked to its SDL enum value.

The user-facing blend-op atoms are:

invalid
add
subtract
reverse_subtract
min
max

See also: - https://wiki.libsdl.org/SDL3/SDL_GPUBlendOp

sdl_gpu_blend_factor(?Factor:atom, ?Value:integer) is nondet

Enumerate SDL_GPUBlendFactor values. Each flag is a Prolog atom linked to its SDL enum value.

The user-facing blend-factor atoms are:

invalid
zero
one
src_color
one_minus_src_color
dst_color
one_minus_dst_color
src_alpha
one_minus_src_alpha
dst_alpha
one_minus_dst_alpha
constant_color
one_minus_constant_color
src_alpha_saturate

See also: - https://wiki.libsdl.org/SDL3/SDL_GPUBlendFactor

sdl_gpu_vertex_input_rate(?Rate:atom, ?Value:integer) is nondet

Enumerate SDL_GPUVertexInputRate values. Each flag is a Prolog atom linked to its SDL enum value.

The user-facing vertex-input-rate atoms are:

vertex
instance

See also: - https://wiki.libsdl.org/SDL3/SDL_GPUVertexInputRate

sdl_gpu_vertex_element_format(?Format:atom, ?Value:integer) is nondet

Enumerate SDL_GPUVertexElementFormat values. Each Format is a Prolog atom linked to its SDL enum value.

The user-facing vertex-element-format atoms are:

invalid
int
int2
int3
int4
uint
uint2
uint3
uint4
float
float2
float3
float4
byte2
byte4
ubyte2
ubyte4
byte2_norm
byte4_norm
ubyte2_norm
ubyte4_norm
short2
short4
ushort2
ushort4
short2_norm
short4_norm
ushort2_norm
ushort4_norm
half2
half4

See also: - https://wiki.libsdl.org/SDL3/SDL_GPUVertexElementFormat sdl_gpu_vertex_element_format/2 — maps SDL_GPUVertexElementFormat enum values (sequential from 0).

sdl_gpu_color_component(?Component:atom, ?Value:integer) is nondet

Enumerate SDL_GPUColorComponentFlag values. Each flag is a Prolog atom linked to its SDL bit-mask value; a list of these atoms may be combined into a single mask where used.

The user-facing color-component atoms are:

See also: - https://wiki.libsdl.org/SDL3/SDL_GPUColorComponent

sdl_begingpurenderpass(-RenderPass:blob, +CmdBuf:blob, +ColorTargets:list(sdl_gpu_color_target), +DepthStencil:null;depth_stencil_target) is det

Begins a render pass on CmdBuf, targeting one or more color textures (typically the swapchain texture) and optionally a depth-stencil texture. All graphics operations must take place inside a render pass, ended with sdl_endgpurenderpass/1. ColorTargets is a list of color_target records; DepthStencil is null or a depth_stencil_target record.

RAII: the render pass blob holds a parent ref to the command buffer. If GC'd without being explicitly ended, the foreign destroy hook calls sdl_endgpurenderpass as a safety net. After explicit end the blob is marked consumed; ending an already-ended render pass raises existence_error(render_pass, Pass).

See also: - https://wiki.libsdl.org/SDL3/SDL_BeginGPURenderPass

sdl_endgpurenderpass(+RenderPass:blob) is det

Ends the render pass, marking the render pass blob consumed. After this call RenderPass is invalid. Ending an already-ended render pass raises existence_error(render_pass, Pass).

See also: - https://wiki.libsdl.org/SDL3/SDL_EndGPURenderPass

sdl_creategputexture(-Texture:blob, +Device:blob, +CreateInfo:sdl_gpu_texture_create_info) is det

Creates a GPU texture (render target, sampler source, storage, etc.). CreateInfo is a gpu_texture_create_info record mapping 1-to-1 to SDL_GPUTextureCreateInfo (props is always 0).

The blob is owning: destroy() calls SDL_ReleaseGPUTexture. It holds a parent ref to the device, pinning it against GC.

See also: - https://wiki.libsdl.org/SDL3/SDL_CreateGPUTexture

sdl_releasegputexture(+Texture:blob) is det

Releases a GPU texture created with sdl_creategputexture/3. The blob is marked consumed; after this call Texture is invalid. Releasing an already-released texture raises existence_error(texture, Texture).

See also: - https://wiki.libsdl.org/SDL3/SDL_ReleaseGPUTexture

sdl_creategpushader(-Shader:blob, +Device:blob, +CreateInfo:sdl_gpu_shader_create_info) is det

Creates a GPU shader from precompiled bytecode (e.g. SPIR-V for Vulkan). CreateInfo is a gpu_shader_create_info record mapping 1-to-1 to SDL_GPUShaderCreateInfo (props is always 0). Code is a Prolog string containing raw bytecode — read it from a .spv file with read_file_to_string(File, Code, [type(binary)]).

The blob is owning: destroy() calls SDL_ReleaseGPUShader. It holds a parent ref to the device, pinning it against GC.

See also: - https://wiki.libsdl.org/SDL3/SDL_CreateGPUShader

sdl_releasegpushader(+Shader:blob) is det

Releases a GPU shader created with sdl_creategpushader/3. The blob is marked consumed; after this call Shader is invalid. Releasing an already-released shader raises existence_error(shader, Shader).

See also: - https://wiki.libsdl.org/SDL3/SDL_ReleaseGPUShader

sdl_creategpugraphicspipeline(-Pipeline:blob, +Device:blob, +CreateInfo:sdl_gpu_graphics_pipeline_create_info) is det

Creates a graphics pipeline. CreateInfo is a gpu_graphics_pipeline_create_info record mapping 1-to-1 to SDL_GPUGraphicsPipelineCreateInfo (props is always 0), with nested records for each sub-struct.

The blob is owning: destroy() calls SDL_ReleaseGPUGraphicsPipeline. It holds a parent ref to the device.

See also: - https://wiki.libsdl.org/SDL3/SDL_CreateGPUGraphicsPipeline

sdl_releasegpugraphicspipeline(+Pipeline:blob) is det

Releases a graphics pipeline created with sdl_creategpugraphicspipeline/3. The blob is marked consumed; after this call Pipeline is invalid. Releasing an already-released pipeline raises existence_error(pipeline, Pipeline).

See also: - https://wiki.libsdl.org/SDL3/SDL_ReleaseGPUGraphicsPipeline

sdl_gpu_buffer_usage(?Usage:atom, ?Value:integer) is nondet

Enumerate SDL_GPUBufferUsageFlag values. Each flag is a Prolog atom linked to its SDL bit-mask value; a list of these atoms may be combined into a single mask where used.

The user-facing buffer-usage atoms are:

vertex
index
indirect
graphics_storage_read
compute_storage_read
compute_storage_write

See also: - https://wiki.libsdl.org/SDL3/SDL_GPUBufferUsage

sdl_creategpubuffer(-Buffer:blob, +Device:blob, +Usage:list(sdl_gpu_buffer_usage), +Size:nonneg) is det

Creates a GPU buffer (vertex, index, indirect, or storage). Usage is a list of sdl_gpu_buffer_usage atoms (OR-ed together); Size is the buffer size in bytes. The blob is owning: destroy() calls SDL_ReleaseGPUBuffer.

See also: - https://wiki.libsdl.org/SDL3/SDL_CreateGPUBuffer

sdl_releasegpubuffer(+Buffer:blob) is det

Releases a buffer created with sdl_creategpubuffer/4. The blob is marked consumed; after this call Buffer is invalid. Releasing an already-released buffer raises existence_error(buffer, Buffer).

See also: - https://wiki.libsdl.org/SDL3/SDL_ReleaseGPUBuffer

sdl_gpu_transfer_buffer_usage(?Usage:atom, ?Value:integer) is nondet

Enumerate SDL_GPUTransferBufferUsage values. Each flag is a Prolog atom linked to its SDL enum value.

The user-facing transfer-buffer-usage atoms are:

upload
download

See also: - https://wiki.libsdl.org/SDL3/SDL_GPUTransferBufferUsage

sdl_creategputransferbuffer(-TransferBuffer:blob, +Device:blob, +Usage:sdl_gpu_transfer_buffer_usage, +Size:nonneg) is det

Creates a transfer buffer (staging area for uploading/downloading GPU data). Usage is an sdl_gpu_transfer_buffer_usage atom (upload or download); Size is the buffer size in bytes. The blob is owning: destroy() calls SDL_ReleaseGPUTransferBuffer.

See also: - https://wiki.libsdl.org/SDL3/SDL_CreateGPUTransferBuffer

sdl_releasegputransferbuffer(+TransferBuffer:blob) is det

Releases a transfer buffer created with sdl_creategputransferbuffer/4. The blob is marked consumed; after this call TransferBuffer is invalid. Releasing an already-released transfer buffer raises existence_error(transfer_buffer, TransferBuffer).

See also: - https://wiki.libsdl.org/SDL3/SDL_ReleaseGPUTransferBuffer

sdl_mapgputransferbuffer(-Ptr:ptr_blob, +TransferBuffer:blob, +Cycle:boolean) is det

Maps a transfer buffer into application address space. On success Ptr is a PtrBlob to the mapped memory; write vertex/index data into it via library(ptr) writers or cairo. Unmap with sdl_unmapgputransferbuffer/1 before encoding upload commands.

See also: - https://wiki.libsdl.org/SDL3/SDL_MapGPUTransferBuffer

sdl_unmapgputransferbuffer(+TransferBuffer:blob) is det

Unmaps a transfer buffer previously mapped with sdl_mapgputransferbuffer/3. Must be called before encoding upload commands.

See also: - https://wiki.libsdl.org/SDL3/SDL_UnmapGPUTransferBuffer

sdl_begingpucopypass(-CopyPass:blob, +CmdBuf:blob) is det

Begins a copy pass on a command buffer, used for upload/download operations (e.g. sdl_uploadtogpubuffer/4). All copy operations must take place inside a copy pass. You must not begin another copy pass, render pass, or compute pass before ending the current copy pass.

RAII: if the copy pass blob is GC'd without being explicitly ended, destroy() calls SDL_EndGPUCopyPass as a safety net.

See also: - https://wiki.libsdl.org/SDL3/SDL_BeginGPUCopyPass

sdl_endgpucopypass(+CopyPass:blob) is det

Ends a copy pass begun with sdl_begingpucopypass/2. The blob is marked consumed; after this call CopyPass is invalid. Ending an already-ended copy pass raises existence_error(copy_pass, CopyPass).

See also: - https://wiki.libsdl.org/SDL3/SDL_EndGPUCopyPass

sdl_uploadtogpubuffer(+CopyPass:blob, +Source:term, +Destination:term, +Cycle:boolean) is det

Uploads data from a transfer buffer to a GPU buffer. Must be called inside a copy pass. Source is a

transfer_buffer_location(TransferBuffer,
Offset)

compound; Destination is a buffer_region(Buffer, Offset, Size) compound. Cycle is true to cycle the buffer if already bound, false to overwrite.