An opaque handle representing the SDL_GPU context. More...

Inheritance diagram for SDL::GPUDevice:

Public Member Functions
constexpr	GPUDevice (std::nullptr_t=nullptr) noexcept
	Default ctor.

constexpr	GPUDevice (const GPUDeviceRaw resource) noexcept
	Constructs from GPUDeviceParam. More...

constexpr	GPUDevice (GPUDevice &&other) noexcept
	Move constructor.

constexpr	GPUDevice (const GPUDeviceRef &other)=delete

constexpr	GPUDevice (GPUDeviceRef &&other)=delete

	GPUDevice (GPUShaderFormat format_flags, bool debug_mode, StringParam name)
	Creates a GPU context. More...

	GPUDevice (PropertiesParam props)
	Creates a GPU context. More...

	~GPUDevice ()
	Destructor.

constexpr GPUDevice &	operator= (GPUDevice &&other) noexcept
	Assignment operator.

constexpr GPUDeviceRaw	get () const noexcept
	Retrieves underlying GPUDeviceRaw.

constexpr GPUDeviceRaw	release () noexcept
	Retrieves underlying GPUDeviceRaw and clear this.

constexpr auto	operator<=> (const GPUDevice &other) const noexcept=default
	Comparison.

constexpr	operator bool () const noexcept
	Converts to bool.

constexpr	operator GPUDeviceParam () const noexcept
	Converts to GPUDeviceParam.

void	Destroy ()
	Destroys a GPU context previously returned by GPUDevice.GPUDevice. More...

const char *	GetDriver ()
	Returns the name of the backend used to create this GPU context. More...

GPUShaderFormat	GetShaderFormats ()
	Returns the supported shader formats for this GPU context. More...

PropertiesRef	GetProperties ()
	Get the properties associated with a GPU device. More...

GPUComputePipeline	CreateComputePipeline (const GPUComputePipelineCreateInfo &createinfo)
	Creates a pipeline object to be used in a compute workflow. More...

GPUGraphicsPipeline	CreateGraphicsPipeline (const GPUGraphicsPipelineCreateInfo &createinfo)
	Creates a pipeline object to be used in a graphics workflow. More...

GPUSampler	CreateSampler (const GPUSamplerCreateInfo &createinfo)
	Creates a sampler object to be used when binding textures in a graphics workflow. More...

GPUShader	CreateShader (const GPUShaderCreateInfo &createinfo)
	Creates a shader to be used when creating a graphics pipeline. More...

GPUTexture	CreateTexture (const GPUTextureCreateInfo &createinfo)
	Creates a texture object to be used in graphics or compute workflows. More...

GPUBuffer	CreateBuffer (const GPUBufferCreateInfo &createinfo)
	Creates a buffer object to be used in graphics or compute workflows. More...

GPUTransferBuffer	CreateTransferBuffer (const GPUTransferBufferCreateInfo &createinfo)
	Creates a transfer buffer to be used when uploading to or downloading from graphics resources. More...

void	SetBufferName (GPUBuffer buffer, StringParam text)
	Sets an arbitrary string constant to label a buffer. More...

void	SetTextureName (GPUTexture texture, StringParam text)
	Sets an arbitrary string constant to label a texture. More...

void	ReleaseTexture (GPUTexture texture)
	Frees the given texture as soon as it is safe to do so. More...

void	ReleaseSampler (GPUSampler sampler)
	Frees the given sampler as soon as it is safe to do so. More...

void	ReleaseBuffer (GPUBuffer buffer)
	Frees the given buffer as soon as it is safe to do so. More...

void	ReleaseTransferBuffer (GPUTransferBuffer transfer_buffer)
	Frees the given transfer buffer as soon as it is safe to do so. More...

void	ReleaseComputePipeline (GPUComputePipeline compute_pipeline)
	Frees the given compute pipeline as soon as it is safe to do so. More...

void	ReleaseShader (GPUShader shader)
	Frees the given shader as soon as it is safe to do so. More...

void	ReleaseGraphicsPipeline (GPUGraphicsPipeline graphics_pipeline)
	Frees the given graphics pipeline as soon as it is safe to do so. More...

GPUCommandBuffer	AcquireCommandBuffer ()
	Acquire a command buffer. More...

void *	MapTransferBuffer (GPUTransferBuffer transfer_buffer, bool cycle)
	Maps a transfer buffer into application address space. More...

void	UnmapTransferBuffer (GPUTransferBuffer transfer_buffer)
	Unmaps a previously mapped transfer buffer. More...

bool	WindowSupportsSwapchainComposition (WindowParam window, GPUSwapchainComposition swapchain_composition)
	Determines whether a swapchain composition is supported by the window. More...

bool	WindowSupportsPresentMode (WindowParam window, GPUPresentMode present_mode)
	Determines whether a presentation mode is supported by the window. More...

void	ClaimWindow (WindowParam window)
	Claims a window, creating a swapchain structure for it. More...

void	ReleaseWindow (WindowParam window)
	Unclaims a window, destroying its swapchain structure. More...

bool	SetSwapchainParameters (WindowParam window, GPUSwapchainComposition swapchain_composition, GPUPresentMode present_mode)
	Changes the swapchain parameters for the given claimed window. More...

bool	SetAllowedFramesInFlight (Uint32 allowed_frames_in_flight)
	Configures the maximum allowed number of frames in flight. More...

GPUTextureFormat	GetSwapchainTextureFormat (WindowParam window)
	Obtains the texture format of the swapchain for the given window. More...

void	WaitForSwapchain (WindowParam window)
	Blocks the thread until a swapchain texture is available to be acquired. More...

void	WaitForIdle ()
	Blocks the thread until the GPU is completely idle. More...

void	WaitForFences (bool wait_all, std::span< GPUFence *const > fences)
	Blocks the thread until the given fences are signaled. More...

bool	QueryFence (GPUFence *fence)
	Checks the status of a fence. More...

void	ReleaseFence (GPUFence *fence)
	Releases a fence obtained from GPUCommandBuffer.SubmitAndAcquireFence. More...

bool	TextureSupportsFormat (GPUTextureFormat format, GPUTextureType type, GPUTextureUsageFlags usage)
	Determines whether a texture format is supported for a given type and usage. More...

bool	TextureSupportsSampleCount (GPUTextureFormat format, GPUSampleCount sample_count)
	Determines if a sample count for a texture format is supported. More...

void	GDKSuspendGPU ()
	Call this to suspend GPU operation on Xbox when you receive the EVENT_DID_ENTER_BACKGROUND event. More...

void	GDKResumeGPU ()
	Call this to resume GPU operation on Xbox when you receive the EVENT_WILL_ENTER_FOREGROUND event. More...

Protected Member Functions
constexpr	GPUDevice (const GPUDevice &other) noexcept=default
	Copy constructor.

constexpr GPUDevice &	operator= (const GPUDevice &other) noexcept=default
	Assignment operator.

Detailed Description

Since: This struct is available since SDL 3.2.0.

Category:: Resource

Constructor & Destructor Documentation

◆ GPUDevice() [1/3]

constexpr SDL::GPUDevice::GPUDevice ( const GPUDeviceRaw resource )

inlineexplicitconstexprnoexcept

Parameters

resource a GPUDeviceRaw to be wrapped.

This assumes the ownership, call release() if you need to take back.

◆ GPUDevice() [2/3]

SDL::GPUDevice::GPUDevice	(	GPUShaderFormat	format_flags,
		bool	debug_mode,
		StringParam	name
	)

inline

The GPU driver name can be one of the following:

"vulkan": Vulkan
"direct3d12": D3D12
"metal": Metal
nullptr: let SDL pick the optimal driver

Parameters

format_flags	a bitflag indicating which shader formats the app is able to provide.
debug_mode	enable debug mode properties and validations.
name	the preferred GPU driver, or nullptr to let SDL pick the optimal driver.

Postcondition: a GPU context on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: GPUDevice.GPUDevice; GPUDevice.GetShaderFormats; GPUDevice.GetDriver; GPUDevice.Destroy; GPUSupportsShaderFormats

◆ GPUDevice() [3/3]

SDL::GPUDevice::GPUDevice ( PropertiesParam props )

inline

These are the supported properties:

prop::GpuDevice.CREATE_DEBUGMODE_BOOLEAN: enable debug mode properties and validations, defaults to true.
prop::GpuDevice.CREATE_PREFERLOWPOWER_BOOLEAN: enable to prefer energy efficiency over maximum GPU performance, defaults to false.
prop::GpuDevice.CREATE_VERBOSE_BOOLEAN: enable to automatically log useful debug information on device creation, defaults to true.
prop::GpuDevice.CREATE_NAME_STRING: the name of the GPU driver to use, if a specific one is desired.
prop::GpuDevice.CREATE_FEATURE_CLIP_DISTANCE_BOOLEAN: Enable Vulkan device feature shaderClipDistance. If disabled, clip distances are not supported in shader code: gl_ClipDistance[] built-ins of GLSL, SV_ClipDistance0/1 semantics of HLSL and [[clip_distance]] attribute of Metal. Disabling optional features allows the application to run on some older Android devices. Defaults to true.
prop::GpuDevice.CREATE_FEATURE_DEPTH_CLAMPING_BOOLEAN: Enable Vulkan device feature depthClamp. If disabled, there is no depth clamp support and enable_depth_clip in GPURasterizerState must always be set to true. Disabling optional features allows the application to run on some older Android devices. Defaults to true.
prop::GpuDevice.CREATE_FEATURE_INDIRECT_DRAW_FIRST_INSTANCE_BOOLEAN: Enable Vulkan device feature drawIndirectFirstInstance. If disabled, the argument first_instance of GPUIndirectDrawCommand must be set to zero. Disabling optional features allows the application to run on some older Android devices. Defaults to true.
prop::GpuDevice.CREATE_FEATURE_ANISOTROPY_BOOLEAN: Enable Vulkan device feature samplerAnisotropy. If disabled, enable_anisotropy of GPUSamplerCreateInfo must be set to false. Disabling optional features allows the application to run on some older Android devices. Defaults to true.

These are the current shader format properties:

prop::GpuDevice.CREATE_SHADERS_PRIVATE_BOOLEAN: The app is able to provide shaders for an NDA platform.
prop::GpuDevice.CREATE_SHADERS_SPIRV_BOOLEAN: The app is able to provide SPIR-V shaders if applicable.
prop::GpuDevice.CREATE_SHADERS_DXBC_BOOLEAN: The app is able to provide DXBC shaders if applicable
prop::GpuDevice.CREATE_SHADERS_DXIL_BOOLEAN: The app is able to provide DXIL shaders if applicable.
prop::GpuDevice.CREATE_SHADERS_MSL_BOOLEAN: The app is able to provide MSL shaders if applicable.
prop::GpuDevice.CREATE_SHADERS_METALLIB_BOOLEAN: The app is able to provide Metal shader libraries if applicable.

With the D3D12 backend:

prop::GpuDevice.CREATE_D3D12_SEMANTIC_NAME_STRING: the prefix to use for all vertex semantics, default is "TEXCOORD".
prop::GpuDevice.CREATE_D3D12_ALLOW_FEWER_RESOURCE_SLOTS_BOOLEAN: By default, Resourcing Binding Tier 2 is required for D3D12 support. However, an application can set this property to true to enable Tier 1 support, if (and only if) the application uses 8 or fewer storage resources across all shader stages. As of writing, this property is useful for targeting Intel Haswell and Broadwell GPUs; other hardware either supports Tier 2 Resource Binding or does not support D3D12 in any capacity. Defaults to false.

With the Vulkan backend:

prop::GpuDevice.CREATE_VULKAN_REQUIRE_HARDWARE_ACCELERATION_BOOLEAN: By default, Vulkan device enumeration includes drivers of all types, including software renderers (for example, the Lavapipe Mesa driver). This can be useful if your application requires SDL_GPU, but if you can provide your own fallback renderer (for example, an OpenGL renderer) this property can be set to true. Defaults to false.
prop::GpuDevice.CREATE_VULKAN_OPTIONS_POINTER: a pointer to an GPUVulkanOptions structure to be processed during device creation. This allows configuring a variety of Vulkan-specific options such as increasing the API version and opting into extensions aside from the minimal set SDL requires.

Parameters

props the properties to use.

Postcondition: a GPU context on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: GPUDevice.GetShaderFormats; GPUDevice.GetDriver; GPUDevice.Destroy; GPUSupportsProperties

The documentation for this class was generated from the following file:

SDL3pp/SDL3pp_gpu.h

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ GPUDevice() [1/3]

◆ GPUDevice() [2/3]

◆ GPUDevice() [3/3]