Struct wgpu::Device

pub struct Device { /* private fields */ }

Open connection to a graphics and/or compute device.

Responsible for the creation of most rendering and compute resources. These are then used in commands, which are submitted to a Queue.

A device may be requested from an adapter with Adapter::request_device.

Corresponds to WebGPU GPUDevice.

Implementations

impl Device

pub fn poll(&self, maintain: Maintain) -> MaintainResult

Check for resource cleanups and mapping callbacks. Will block if Maintain::Wait is passed.

Return true if the queue is empty, or false if there are more queue submissions still in flight. (Note that, unless access to the Queue is coordinated somehow, this information could be out of date by the time the caller receives it. Queues can be shared between threads, so other threads could submit new work at any time.)

When running on WebGPU, this is a no-op. Devices are automatically polled.

pub fn features(&self) -> Features

The features which can be used on this device.

No additional features can be used, even if the underlying adapter can support them.

pub fn limits(&self) -> Limits

The limits which can be used on this device.

No better limits can be used, even if the underlying adapter can support them.

pub fn create_shader_module( &self, desc: ShaderModuleDescriptor<'_> ) -> ShaderModule

Creates a shader module from either SPIR-V or WGSL source code.

This function may consume a lot of stack space. Compiler-enforced limits for parsing recursion exist; if shader compilation runs into them, it will return an error gracefully. However, on some build profiles and platforms, the default stack size for a thread may be exceeded before this limit is reached during parsing. Callers should ensure that there is enough stack space for this, particularly if calls to this method are exposed to user input.

pub unsafe fn create_shader_module_unchecked( &self, desc: ShaderModuleDescriptor<'_> ) -> ShaderModule

Creates a shader module from either SPIR-V or WGSL source code without runtime checks.

Safety

In contrast with create_shader_module this function creates a shader module without runtime checks which allows shaders to perform operations which can lead to undefined behavior like indexing out of bounds, thus it’s the caller responsibility to pass a shader which doesn’t perform any of this operations.

This has no effect on web.

pub unsafe fn create_shader_module_spirv( &self, desc: &ShaderModuleDescriptorSpirV<'_> ) -> ShaderModule

Creates a shader module from SPIR-V binary directly.

Safety

This function passes binary data to the backend as-is and can potentially result in a driver crash or bogus behaviour. No attempt is made to ensure that data is valid SPIR-V.

See also include_spirv_raw! and util::make_spirv_raw.

pub fn create_command_encoder( &self, desc: &CommandEncoderDescriptor<'_> ) -> CommandEncoder

Creates an empty CommandEncoder.

pub fn create_render_bundle_encoder( &self, desc: &RenderBundleEncoderDescriptor<'_> ) -> RenderBundleEncoder<'_>

Creates an empty RenderBundleEncoder.

pub fn create_bind_group(&self, desc: &BindGroupDescriptor<'_>) -> BindGroup

Creates a new BindGroup.

pub fn create_bind_group_layout( &self, desc: &BindGroupLayoutDescriptor<'_> ) -> BindGroupLayout

Creates a BindGroupLayout.

pub fn create_pipeline_layout( &self, desc: &PipelineLayoutDescriptor<'_> ) -> PipelineLayout

Creates a PipelineLayout.

pub fn create_render_pipeline( &self, desc: &RenderPipelineDescriptor<'_> ) -> RenderPipeline

Creates a RenderPipeline.

pub fn create_compute_pipeline( &self, desc: &ComputePipelineDescriptor<'_> ) -> ComputePipeline

Creates a ComputePipeline.

pub fn create_buffer(&self, desc: &BufferDescriptor<'_>) -> Buffer

Creates a Buffer.

pub fn create_texture(&self, desc: &TextureDescriptor<'_>) -> Texture

Creates a new Texture.

desc specifies the general format of the texture.

pub unsafe fn create_texture_from_hal<A: HalApi>( &self, hal_texture: A::Texture, desc: &TextureDescriptor<'_> ) -> Texture

Available on wgpu_core only.

Creates a Texture from a wgpu-hal Texture.

Safety

• hal_texture must be created from this device internal handle
• hal_texture must be created respecting desc
• hal_texture must be initialized

pub unsafe fn create_buffer_from_hal<A: HalApi>( &self, hal_buffer: A::Buffer, desc: &BufferDescriptor<'_> ) -> Buffer

Available on wgpu_core only.

Creates a Buffer from a wgpu-hal Buffer.

Safety

• hal_buffer must be created from this device internal handle
• hal_buffer must be created respecting desc
• hal_buffer must be initialized

pub fn create_sampler(&self, desc: &SamplerDescriptor<'_>) -> Sampler

Creates a new Sampler.

desc specifies the behavior of the sampler.

pub fn create_query_set(&self, desc: &QuerySetDescriptor<'_>) -> QuerySet

Creates a new QuerySet.

pub fn on_uncaptured_error(&self, handler: Box<dyn UncapturedErrorHandler>)

Set a callback for errors that are not handled in error scopes.

pub fn push_error_scope(&self, filter: ErrorFilter)

Push an error scope.

pub fn pop_error_scope( &self ) -> impl Future<Output = Option<Error>> + WasmNotSend

Pop an error scope.

pub fn start_capture(&self)

Starts frame capture.

pub fn stop_capture(&self)

Stops frame capture.

pub fn get_internal_counters(&self) -> InternalCounters

Query internal counters from the native backend for debugging purposes.

Some backends may not set all counters, or may not set any counter at all. The counters cargo feature must be enabled for any counter to be set.

If a counter is not set, its contains its default value (zero).

pub fn generate_allocator_report(&self) -> Option<AllocatorReport>

Generate an GPU memory allocation report if the underlying backend supports it.

Backends that do not support producing these reports return None. A backend may Support it and still return None if it is not using performing sub-allocation, for example as a workaround for driver issues.

pub unsafe fn as_hal<A: HalApi, F: FnOnce(Option<&A::Device>) -> R, R>( &self, hal_device_callback: F ) -> Option<R>

Available on wgpu_core only.

Apply a callback to this Device’s underlying backend device.

If this Device is implemented by the backend API given by A (Vulkan, Dx12, etc.), then apply hal_device_callback to Some(&device), where device is the underlying backend device type, A::Device.

If this Device uses a different backend, apply hal_device_callback to None.

The device is locked for reading while hal_device_callback runs. If the callback attempts to perform any wgpu operations that require write access to the device (destroying a buffer, say), deadlock will occur. The locks are automatically released when the callback returns.

Safety

• The raw handle passed to the callback must not be manually destroyed.

pub fn destroy(&self)

Destroy this device.

pub fn set_device_lost_callback( &self, callback: impl Fn(DeviceLostReason, String) + Send + 'static )

Set a DeviceLostCallback on this device.

pub unsafe fn create_pipeline_cache( &self, desc: &PipelineCacheDescriptor<'_> ) -> PipelineCache

Create a PipelineCache with initial data

This can be passed to Device::create_compute_pipeline and Device::create_render_pipeline to either accelerate these or add the cache results from those.

Safety

If the data field of desc is set, it must have previously been returned from a call to PipelineCache::get_data¹. This data will only be used if it came from an adapter with the same util::pipeline_cache_key. This is compatible across wgpu versions, as any data format change will be accounted for.

It is not supported to bring caches from previous direct uses of backend APIs into this method.

Errors

Returns an error value if:

• the PIPELINE_CACHE feature is not enabled
• this device is invalid; or
• the device is out of memory

This method also returns an error value if:

• The fallback field on desc is false; and
• the data provided would not be used²

If an error value is used in subsequent calls, default caching will be used.

---

1. We do recognise that saving this data to disk means this condition is impossible to fully prove. Consider the risks for your own application in this case. ↩

2. This data may be not used if: the data was produced by a prior version of wgpu; or was created for an incompatible adapter, or there was a GPU driver update. In some cases, the data might not be used and a real value is returned, this is left to the discretion of GPU drivers. ↩

impl Device

Features::EXPERIMENTAL_RAY_TRACING_ACCELERATION_STRUCTURE must be enabled on the device in order to call these functions.

pub fn create_blas( &self, desc: &CreateBlasDescriptor<'_>, sizes: BlasGeometrySizeDescriptors ) -> Blas

Create a bottom level acceleration structure, used inside a top level acceleration structure for ray tracing.

• desc: The descriptor of the acceleration structure.
• sizes: Size descriptor limiting what can be built into the acceleration structure.

Validation

If any of the following is not satisfied a validation error is generated

The device must have Features::EXPERIMENTAL_RAY_TRACING_ACCELERATION_STRUCTURE enabled. if sizes is [BlasGeometrySizeDescriptors::Triangles] then the following must be satisfied

• For every geometry descriptor (for the purposes this is called geo_desc) of sizes.descriptors the following must be satisfied:
  • geo_desc.vertex_format must be within allowed formats (allowed formats for a given feature set may be queried with Features::allowed_vertex_formats_for_blas).
  • Both or neither of geo_desc.index_format and geo_desc.index_count must be provided.

pub fn create_tlas(&self, desc: &CreateTlasDescriptor<'_>) -> Tlas

Create a top level acceleration structure, used for ray tracing.

• desc: The descriptor of the acceleration structure.

Validation

If any of the following is not satisfied a validation error is generated

The device must have Features::EXPERIMENTAL_RAY_TRACING_ACCELERATION_STRUCTURE enabled.

Trait Implementations

impl Debug for Device

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl DeviceExt for Device

fn create_buffer_init(&self, descriptor: &BufferInitDescriptor<'_>) -> Buffer

Creates a Buffer with data to initialize it.

fn create_texture_with_data( &self, queue: &Queue, desc: &TextureDescriptor<'_>, order: TextureDataOrder, data: &[u8] ) -> Texture

Upload an entire texture and its mipmaps from a source buffer.

impl Drop for Device

fn drop(&mut self)

Executes the destructor for this type.