Struct Device

pub struct Device {

    raw: Box<dyn DynDevice>,
    pub(crate) adapter: Arc<Adapter>,
    pub(crate) queue: OnceLock<Weak<Queue>>,
    pub(crate) zero_buffer: ManuallyDrop<Box<dyn DynBuffer>>,
    label: String,
    pub(crate) command_allocator: CommandAllocator,
    pub(crate) command_indices: RwLock<CommandIndices>,
    pub(crate) last_successful_submission_index: AtomicFenceValue,
    pub(crate) fence: RwLock<ManuallyDrop<Box<dyn DynFence>>>,
    pub(crate) snatchable_lock: SnatchLock,
    pub(crate) valid: AtomicBool,
    pub(crate) device_lost_closure: Mutex<Option<DeviceLostClosure>>,
    pub(crate) trackers: Mutex<DeviceTracker>,
    pub(crate) tracker_indices: TrackerIndexAllocators,
    pub(crate) bgl_pool: ResourcePool<EntryMap, BindGroupLayout>,
    pub(crate) alignments: Alignments,
    pub(crate) limits: Limits,
    pub(crate) features: Features,
    pub(crate) downlevel: DownlevelCapabilities,
    pub(crate) instance_flags: InstanceFlags,
    pub(crate) deferred_destroy: Mutex<Vec<DeferredDestroy>>,
    pub(crate) usage_scopes: Mutex<Vec<(BufferUsageScope, TextureUsageScope)>>,
    pub(crate) indirect_validation: Option<IndirectValidation>,
    pub(crate) timestamp_normalizer: OnceLock<TimestampNormalizer>,
    pub(crate) default_external_texture_params_buffer: ManuallyDrop<Box<dyn DynBuffer>>,
}

Structure describing a logical device. Some members are internally mutable, stored behind mutexes.

Fields

raw: Box<dyn DynDevice>

adapter: Arc<Adapter>

queue: OnceLock<Weak<Queue>>

zero_buffer: ManuallyDrop<Box<dyn DynBuffer>>

label: String

The label from the descriptor used to create the resource.

command_allocator: CommandAllocator

command_indices: RwLock<CommandIndices>

last_successful_submission_index: AtomicFenceValue

The index of the last successful submission to this device’s hal::Queue.

Unlike active_submission_index, which is incremented each time submission is attempted, this is updated only when submission succeeds, so waiting for this value won’t hang waiting for work that was never submitted.

fence: RwLock<ManuallyDrop<Box<dyn DynFence>>>

snatchable_lock: SnatchLock

valid: AtomicBool

Is this device valid? Valid is closely associated with “lose the device”, which can be triggered by various methods, including at the end of device destroy, and by any GPU errors that cause us to no longer trust the state of the device. Ideally we would like to fold valid into the storage of the device itself (for example as an Error enum), but unfortunately we need to continue to be able to retrieve the device in poll_devices to determine if it can be dropped. If our internal accesses of devices were done through ref-counted references and external accesses checked for Error enums, we wouldn’t need this. For now, we need it. All the call sites where we check it are areas that should be revisited if we start using ref-counted references for internal access.

device_lost_closure: Mutex<Option<DeviceLostClosure>>

Closure to be called on “lose the device”. This is invoked directly by device.lose or by the UserCallbacks returned from maintain when the device has been destroyed and its queues are empty.

trackers: Mutex<DeviceTracker>

Stores the state of buffers and textures.

tracker_indices: TrackerIndexAllocators

bgl_pool: ResourcePool<EntryMap, BindGroupLayout>

Pool of bind group layouts, allowing deduplication.

alignments: Alignments

limits: Limits

features: Features

downlevel: DownlevelCapabilities

instance_flags: InstanceFlags

deferred_destroy: Mutex<Vec<DeferredDestroy>>

usage_scopes: Mutex<Vec<(BufferUsageScope, TextureUsageScope)>>

indirect_validation: Option<IndirectValidation>

timestamp_normalizer: OnceLock<TimestampNormalizer>

default_external_texture_params_buffer: ManuallyDrop<Box<dyn DynBuffer>>

Uniform buffer containing ExternalTextureParams with values such that a TextureView bound to a wgt::BindingType::ExternalTexture binding point will be rendered correctly. Intended to be used as the hal::ExternalTextureBinding::params field.

Implementations

impl Device

pub fn create_blas( self: &Arc<Self>, blas_desc: &BlasDescriptor<'_>, sizes: BlasGeometrySizeDescriptors, ) -> Result<Arc<Blas>, CreateBlasError>

pub fn create_tlas( self: &Arc<Self>, desc: &TlasDescriptor<'_>, ) -> Result<Arc<Tlas>, CreateTlasError>

impl Device

pub(crate) fn raw(&self) -> &dyn DynDevice

pub(crate) fn require_features( &self, feature: Features, ) -> Result<(), MissingFeatures>

pub(crate) fn require_downlevel_flags( &self, flags: DownlevelFlags, ) -> Result<(), MissingDownlevelFlags>

pub unsafe fn start_graphics_debugger_capture(&self)

Safety

• See wgpu::Device::start_graphics_debugger_capture for details the safety.

pub unsafe fn stop_graphics_debugger_capture(&self)

Safety

• See wgpu::Device::stop_graphics_debugger_capture for details the safety.

impl Device

pub(crate) fn new( raw_device: Box<dyn DynDevice>, adapter: &Arc<Adapter>, desc: &DeviceDescriptor<'_>, instance_flags: InstanceFlags, ) -> Result<Self, DeviceError>

fn init_default_external_texture_params_buffer( self: &Arc<Self>, ) -> Result<(), DeviceError>

Initializes Device::default_external_texture_params_buffer with required values such that a TextureView bound to a wgt::BindingType::ExternalTexture binding point will be rendered correctly.

pub fn late_init_resources_with_queue( self: &Arc<Self>, ) -> Result<(), RequestDeviceError>

pub fn backend(&self) -> Backend

Returns the backend this device is using.

pub fn is_valid(&self) -> bool

pub fn check_is_valid(&self) -> Result<(), DeviceError>

pub fn lose_if_oom(&self)

Checks that we are operating within the memory budget reported by the native APIs.

If we are not, the device gets invalidated.

The budget might fluctuate over the lifetime of the application, so it should be checked somewhat frequently.

pub fn handle_hal_error(&self, error: DeviceError) -> DeviceError

pub fn handle_hal_error_with_nonfatal_oom( &self, error: DeviceError, ) -> DeviceError

pub(crate) fn deferred_resource_destruction(&self)

Run some destroy operations that were deferred.

Destroying the resources requires taking a write lock on the device’s snatch lock, so a good reason for deferring resource destruction is when we don’t know for sure how risky it is to take the lock (typically, it shouldn’t be taken from the drop implementation of a reference-counted structure). The snatch lock must not be held while this function is called.

pub fn get_queue(&self) -> Option<Arc<Queue>>

pub fn set_queue(&self, queue: &Arc<Queue>)

pub fn poll( &self, poll_type: PollType<SubmissionIndex>, ) -> Result<PollStatus, WaitIdleError>

pub(crate) fn poll_and_return_closures( &self, poll_type: PollType<SubmissionIndex>, ) -> (UserClosures, Result<PollStatus, WaitIdleError>)

Poll the device, returning any UserClosures that need to be executed.

The caller must invoke the UserClosures even if this function returns an error. This is an internal helper, used by Device::poll and Global::poll_all_devices, so that poll_all_devices can invoke closures once after all devices have been polled.

pub(crate) fn maintain<'this>( &'this self, fence: RwLockReadGuard<'_, ManuallyDrop<Box<dyn DynFence>>>, poll_type: PollType<SubmissionIndex>, snatch_guard: SnatchGuard<'_>, ) -> (UserClosures, Result<PollStatus, WaitIdleError>)

Check the current status of the GPU and process any submissions that have finished.

The poll_type argument tells if this function should wait for a particular submission index to complete, or if it should just poll the current status.

This will process all completed submissions, even if the caller only asked us to poll to a given submission index.

Return a pair (closures, result), where:

• closures is a list of callbacks that need to be invoked informing the user about various things occurring. These happen and should be handled even if this function returns an error, hence they are outside of the result.

• results is a boolean indicating the result of the wait operation, including if there was a timeout or a validation error.

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

pub fn set_buffer_data( self: &Arc<Self>, buffer: &Arc<Buffer>, offset: BufferAddress, data: &[u8], ) -> BufferAccessResult

pub(crate) fn create_texture_from_hal( self: &Arc<Self>, hal_texture: Box<dyn DynTexture>, desc: &TextureDescriptor<'_>, ) -> Result<Arc<Texture>, CreateTextureError>

pub(crate) unsafe fn create_buffer_from_hal( self: &Arc<Self>, hal_buffer: Box<dyn DynBuffer>, desc: &BufferDescriptor<'_>, ) -> (Fallible<Buffer>, Option<CreateBufferError>)

Safety

• hal_buffer must have been created on this device.
• hal_buffer must have been created respecting desc (in particular, the size).
• hal_buffer must be initialized.
• hal_buffer must not have zero size.

fn create_indirect_validation_bind_groups( &self, raw_buffer: &dyn DynBuffer, buffer_size: u64, usage: BufferUsages, ) -> Result<Snatchable<BindGroups>, CreateBufferError>

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

pub fn create_texture_view( self: &Arc<Self>, texture: &Arc<Texture>, desc: &TextureViewDescriptor<'_>, ) -> Result<Arc<TextureView>, CreateTextureViewError>

pub fn create_external_texture( self: &Arc<Self>, desc: &ExternalTextureDescriptor<'_>, planes: &[Arc<TextureView>], ) -> Result<Arc<ExternalTexture>, CreateExternalTextureError>

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

pub fn create_shader_module<'a>( self: &Arc<Self>, desc: &ShaderModuleDescriptor<'a>, source: ShaderModuleSource<'a>, ) -> Result<Arc<ShaderModule>, CreateShaderModuleError>

pub(crate) fn create_command_encoder( self: &Arc<Self>, label: &Label<'_>, ) -> Result<Arc<CommandEncoder>, DeviceError>

fn make_late_sized_buffer_groups( shader_binding_sizes: &HashMap<ResourceBinding, BufferSize, BuildHasherDefault<FxHasher>>, layout: &PipelineLayout, ) -> ArrayVec<LateSizedBufferGroup, { hal::MAX_BIND_GROUPS }>

Generate information about late-validated buffer bindings for pipelines.

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

fn create_buffer_binding<'a>( &self, bb: &'a ResolvedBufferBinding, binding: u32, decl: &BindGroupLayoutEntry, used_buffer_ranges: &mut Vec<BufferInitTrackerAction>, dynamic_binding_info: &mut Vec<BindGroupDynamicBindingData>, late_buffer_binding_sizes: &mut HashMap<u32, BufferSize, BuildHasherDefault<FxHasher>>, used: &mut BindGroupStates, snatch_guard: &'a SnatchGuard<'a>, ) -> Result<BufferBinding<'a, dyn DynBuffer>, CreateBindGroupError>

fn create_sampler_binding<'a>( &self, used: &mut BindGroupStates, binding: u32, decl: &BindGroupLayoutEntry, sampler: &'a Arc<Sampler>, ) -> Result<&'a dyn DynSampler, CreateBindGroupError>

fn create_texture_binding<'a>( &self, binding: u32, decl: &BindGroupLayoutEntry, view: &'a Arc<TextureView>, used: &mut BindGroupStates, used_texture_ranges: &mut Vec<TextureInitTrackerAction>, snatch_guard: &'a SnatchGuard<'a>, ) -> Result<TextureBinding<'a, dyn DynTextureView>, CreateBindGroupError>

fn create_tlas_binding<'a>( self: &Arc<Self>, used: &mut BindGroupStates, binding: u32, decl: &BindGroupLayoutEntry, tlas: &'a Arc<Tlas>, snatch_guard: &'a SnatchGuard<'a>, ) -> Result<&'a dyn DynAccelerationStructure, CreateBindGroupError>

fn create_external_texture_binding<'a>( &'a self, binding: u32, decl: &BindGroupLayoutEntry, external_texture: &'a Arc<ExternalTexture>, used: &mut BindGroupStates, snatch_guard: &'a SnatchGuard<'_>, ) -> Result<ExternalTextureBinding<'a, dyn DynBuffer, dyn DynTextureView>, CreateBindGroupError>

fn create_external_texture_binding_from_view<'a>( &'a self, binding: u32, decl: &BindGroupLayoutEntry, view: &'a Arc<TextureView>, used: &mut BindGroupStates, snatch_guard: &'a SnatchGuard<'_>, ) -> Result<ExternalTextureBinding<'a, dyn DynBuffer, dyn DynTextureView>, CreateBindGroupError>

pub fn create_bind_group( self: &Arc<Self>, desc: ResolvedBindGroupDescriptor<'_>, ) -> Result<Arc<BindGroup>, CreateBindGroupError>

fn check_array_binding( features: Features, count: Option<NonZeroU32>, num_bindings: usize, ) -> Result<(), CreateBindGroupError>

fn texture_use_parameters( &self, binding: u32, decl: &BindGroupLayoutEntry, view: &TextureView, expected: &'static str, ) -> Result<TextureUses, CreateBindGroupError>

pub fn create_pipeline_layout( self: &Arc<Self>, desc: &ResolvedPipelineLayoutDescriptor<'_>, ) -> Result<Arc<PipelineLayout>, CreatePipelineLayoutError>

pub(crate) fn derive_pipeline_layout( self: &Arc<Self>, derived_group_layouts: Box<ArrayVec<EntryMap, { hal::MAX_BIND_GROUPS }>>, ) -> Result<Arc<PipelineLayout>, ImplicitLayoutError>

pub fn create_compute_pipeline( self: &Arc<Self>, desc: ResolvedComputePipelineDescriptor<'_>, ) -> Result<Arc<ComputePipeline>, CreateComputePipelineError>

pub fn create_render_pipeline( self: &Arc<Self>, desc: ResolvedGeneralRenderPipelineDescriptor<'_>, ) -> Result<Arc<RenderPipeline>, CreateRenderPipelineError>

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

Safety

The data field on desc must have previously been returned from crate::global::Global::pipeline_cache_get_data

fn get_texture_format_features( &self, format: TextureFormat, ) -> TextureFormatFeatures

fn describe_format_features( &self, format: TextureFormat, ) -> Result<TextureFormatFeatures, MissingFeatures>

pub(crate) fn wait_for_submit( &self, submission_index: SubmissionIndex, ) -> Result<(), DeviceError>

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

pub fn configure_surface( self: &Arc<Self>, surface: &Surface, config: &SurfaceConfiguration<Vec<TextureFormat>>, ) -> Option<ConfigureSurfaceError>

fn lose(&self, message: &str)

fn release_gpu_resources(&self)

pub(crate) fn new_usage_scope(&self) -> UsageScope<'_>

pub fn get_hal_counters(&self) -> HalCounters

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

Trait Implementations

impl Debug for Device

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

Formats the value using the given formatter.

impl Drop for Device

fn drop(&mut self)

Executes the destructor for this type.

impl Labeled for Device

fn label(&self) -> &str

Returns a string identifying this resource for logging and errors.

fn error_ident(&self) -> ResourceErrorIdent

impl ResourceType for Device

const TYPE: &'static str = "Device"