pub struct Device { /* private fields */ }
Expand description
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§
source§impl Device
impl Device
sourcepub fn poll(&self, maintain: Maintain) -> MaintainResult
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. Queue
s can be shared between threads, so
other threads could submit new work at any time.)
When running on WebGPU, this is a no-op. Device
s are automatically polled.
sourcepub fn features(&self) -> Features
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.
sourcepub fn limits(&self) -> Limits
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.
sourcepub fn create_shader_module(
&self,
desc: ShaderModuleDescriptor<'_>
) -> ShaderModule
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.
sourcepub unsafe fn create_shader_module_unchecked(
&self,
desc: ShaderModuleDescriptor<'_>
) -> ShaderModule
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.
sourcepub unsafe fn create_shader_module_spirv(
&self,
desc: &ShaderModuleDescriptorSpirV<'_>
) -> ShaderModule
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
.
sourcepub fn create_command_encoder(
&self,
desc: &CommandEncoderDescriptor<'_>
) -> CommandEncoder
pub fn create_command_encoder( &self, desc: &CommandEncoderDescriptor<'_> ) -> CommandEncoder
Creates an empty CommandEncoder
.
sourcepub fn create_render_bundle_encoder(
&self,
desc: &RenderBundleEncoderDescriptor<'_>
) -> RenderBundleEncoder<'_>
pub fn create_render_bundle_encoder( &self, desc: &RenderBundleEncoderDescriptor<'_> ) -> RenderBundleEncoder<'_>
Creates an empty RenderBundleEncoder
.
sourcepub fn create_bind_group(&self, desc: &BindGroupDescriptor<'_>) -> BindGroup
pub fn create_bind_group(&self, desc: &BindGroupDescriptor<'_>) -> BindGroup
Creates a new BindGroup
.
sourcepub fn create_bind_group_layout(
&self,
desc: &BindGroupLayoutDescriptor<'_>
) -> BindGroupLayout
pub fn create_bind_group_layout( &self, desc: &BindGroupLayoutDescriptor<'_> ) -> BindGroupLayout
Creates a BindGroupLayout
.
sourcepub fn create_pipeline_layout(
&self,
desc: &PipelineLayoutDescriptor<'_>
) -> PipelineLayout
pub fn create_pipeline_layout( &self, desc: &PipelineLayoutDescriptor<'_> ) -> PipelineLayout
Creates a PipelineLayout
.
sourcepub fn create_render_pipeline(
&self,
desc: &RenderPipelineDescriptor<'_>
) -> RenderPipeline
pub fn create_render_pipeline( &self, desc: &RenderPipelineDescriptor<'_> ) -> RenderPipeline
Creates a RenderPipeline
.
sourcepub fn create_compute_pipeline(
&self,
desc: &ComputePipelineDescriptor<'_>
) -> ComputePipeline
pub fn create_compute_pipeline( &self, desc: &ComputePipelineDescriptor<'_> ) -> ComputePipeline
Creates a ComputePipeline
.
sourcepub fn create_buffer(&self, desc: &BufferDescriptor<'_>) -> Buffer
pub fn create_buffer(&self, desc: &BufferDescriptor<'_>) -> Buffer
Creates a Buffer
.
sourcepub fn create_texture(&self, desc: &TextureDescriptor<'_>) -> Texture
pub fn create_texture(&self, desc: &TextureDescriptor<'_>) -> Texture
Creates a new Texture
.
desc
specifies the general format of the texture.
sourcepub unsafe fn create_texture_from_hal<A: HalApi>(
&self,
hal_texture: A::Texture,
desc: &TextureDescriptor<'_>
) -> Texture
Available on wgpu_core
only.
pub unsafe fn create_texture_from_hal<A: HalApi>( &self, hal_texture: A::Texture, desc: &TextureDescriptor<'_> ) -> Texture
wgpu_core
only.sourcepub unsafe fn create_buffer_from_hal<A: HalApi>(
&self,
hal_buffer: A::Buffer,
desc: &BufferDescriptor<'_>
) -> Buffer
Available on wgpu_core
only.
pub unsafe fn create_buffer_from_hal<A: HalApi>( &self, hal_buffer: A::Buffer, desc: &BufferDescriptor<'_> ) -> Buffer
wgpu_core
only.sourcepub fn create_sampler(&self, desc: &SamplerDescriptor<'_>) -> Sampler
pub fn create_sampler(&self, desc: &SamplerDescriptor<'_>) -> Sampler
Creates a new Sampler
.
desc
specifies the behavior of the sampler.
sourcepub fn create_query_set(&self, desc: &QuerySetDescriptor<'_>) -> QuerySet
pub fn create_query_set(&self, desc: &QuerySetDescriptor<'_>) -> QuerySet
Creates a new QuerySet
.
sourcepub fn on_uncaptured_error(&self, handler: Box<dyn UncapturedErrorHandler>)
pub fn on_uncaptured_error(&self, handler: Box<dyn UncapturedErrorHandler>)
Set a callback for errors that are not handled in error scopes.
sourcepub fn push_error_scope(&self, filter: ErrorFilter)
pub fn push_error_scope(&self, filter: ErrorFilter)
Push an error scope.
sourcepub fn pop_error_scope(
&self
) -> impl Future<Output = Option<Error>> + WasmNotSend
pub fn pop_error_scope( &self ) -> impl Future<Output = Option<Error>> + WasmNotSend
Pop an error scope.
sourcepub fn start_capture(&self)
pub fn start_capture(&self)
Starts frame capture.
sourcepub fn stop_capture(&self)
pub fn stop_capture(&self)
Stops frame capture.
sourcepub fn get_internal_counters(&self) -> InternalCounters
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).
sourcepub fn generate_allocator_report(&self) -> Option<AllocatorReport>
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.
sourcepub 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.
pub unsafe fn as_hal<A: HalApi, F: FnOnce(Option<&A::Device>) -> R, R>( &self, hal_device_callback: F ) -> Option<R>
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.
sourcepub fn set_device_lost_callback(
&self,
callback: impl Fn(DeviceLostReason, String) + Send + 'static
)
pub fn set_device_lost_callback( &self, callback: impl Fn(DeviceLostReason, String) + Send + 'static )
Set a DeviceLostCallback on this device.
sourcepub unsafe fn create_pipeline_cache(
&self,
desc: &PipelineCacheDescriptor<'_>
) -> PipelineCache
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
1. 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 ondesc
is false; and - the
data
provided would not be used2
If an error value is used in subsequent calls, default caching will be used.
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. ↩
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. ↩