Trait Device

pub trait Device<B: Backend>:
    Debug
    + Any
    + Send
    + Sync {
    // Required methods
    unsafe fn allocate_memory(
        &self,
        memory_type: MemoryTypeId,
        size: u64,
    ) -> Result<B::Memory, AllocationError>;
    unsafe fn free_memory(&self, memory: B::Memory);
    unsafe fn create_command_pool(
        &self,
        family: QueueFamilyId,
        create_flags: CommandPoolCreateFlags,
    ) -> Result<B::CommandPool, OutOfMemory>;
    unsafe fn destroy_command_pool(&self, pool: B::CommandPool);
    unsafe fn create_render_pass<'a, Ia, Is, Id>(
        &self,
        attachments: Ia,
        subpasses: Is,
        dependencies: Id,
    ) -> Result<B::RenderPass, OutOfMemory>
       where Ia: Iterator<Item = Attachment>,
             Is: Iterator<Item = SubpassDesc<'a>>,
             Id: Iterator<Item = SubpassDependency>;
    unsafe fn destroy_render_pass(&self, rp: B::RenderPass);
    unsafe fn create_pipeline_layout<'a, Is, Ic>(
        &self,
        set_layouts: Is,
        push_constant: Ic,
    ) -> Result<B::PipelineLayout, OutOfMemory>
       where Is: Iterator<Item = &'a B::DescriptorSetLayout>,
             Ic: Iterator<Item = (ShaderStageFlags, Range<u32>)>;
    unsafe fn destroy_pipeline_layout(&self, layout: B::PipelineLayout);
    unsafe fn create_pipeline_cache(
        &self,
        data: Option<&[u8]>,
    ) -> Result<B::PipelineCache, OutOfMemory>;
    unsafe fn get_pipeline_cache_data(
        &self,
        cache: &B::PipelineCache,
    ) -> Result<Vec<u8>, OutOfMemory>;
    unsafe fn merge_pipeline_caches<'a, I>(
        &self,
        target: &mut B::PipelineCache,
        sources: I,
    ) -> Result<(), OutOfMemory>
       where I: Iterator<Item = &'a B::PipelineCache>;
    unsafe fn destroy_pipeline_cache(&self, cache: B::PipelineCache);
    unsafe fn create_graphics_pipeline<'a>(
        &self,
        desc: &GraphicsPipelineDesc<'a, B>,
        cache: Option<&B::PipelineCache>,
    ) -> Result<B::GraphicsPipeline, CreationError>;
    unsafe fn destroy_graphics_pipeline(&self, pipeline: B::GraphicsPipeline);
    unsafe fn create_compute_pipeline<'a>(
        &self,
        desc: &ComputePipelineDesc<'a, B>,
        cache: Option<&B::PipelineCache>,
    ) -> Result<B::ComputePipeline, CreationError>;
    unsafe fn destroy_compute_pipeline(&self, pipeline: B::ComputePipeline);
    unsafe fn create_framebuffer<I>(
        &self,
        pass: &B::RenderPass,
        attachments: I,
        extent: Extent,
    ) -> Result<B::Framebuffer, OutOfMemory>
       where I: Iterator<Item = FramebufferAttachment>;
    unsafe fn destroy_framebuffer(&self, buf: B::Framebuffer);
    unsafe fn create_shader_module(
        &self,
        spirv: &[u32],
    ) -> Result<B::ShaderModule, ShaderError>;
    unsafe fn destroy_shader_module(&self, shader: B::ShaderModule);
    unsafe fn create_buffer(
        &self,
        size: u64,
        usage: Usage,
        sparse: SparseFlags,
    ) -> Result<B::Buffer, CreationError>;
    unsafe fn get_buffer_requirements(&self, buf: &B::Buffer) -> Requirements;
    unsafe fn bind_buffer_memory(
        &self,
        memory: &B::Memory,
        offset: u64,
        buf: &mut B::Buffer,
    ) -> Result<(), BindError>;
    unsafe fn destroy_buffer(&self, buffer: B::Buffer);
    unsafe fn create_buffer_view(
        &self,
        buf: &B::Buffer,
        fmt: Option<Format>,
        range: SubRange,
    ) -> Result<B::BufferView, ViewCreationError>;
    unsafe fn destroy_buffer_view(&self, view: B::BufferView);
    unsafe fn create_image(
        &self,
        kind: Kind,
        mip_levels: Level,
        format: Format,
        tiling: Tiling,
        usage: Usage,
        sparse: SparseFlags,
        view_caps: ViewCapabilities,
    ) -> Result<B::Image, CreationError>;
    unsafe fn get_image_requirements(&self, image: &B::Image) -> Requirements;
    unsafe fn get_image_subresource_footprint(
        &self,
        image: &B::Image,
        subresource: Subresource,
    ) -> SubresourceFootprint;
    unsafe fn bind_image_memory(
        &self,
        memory: &B::Memory,
        offset: u64,
        image: &mut B::Image,
    ) -> Result<(), BindError>;
    unsafe fn destroy_image(&self, image: B::Image);
    unsafe fn create_image_view(
        &self,
        image: &B::Image,
        view_kind: ViewKind,
        format: Format,
        swizzle: Swizzle,
        usage: Usage,
        range: SubresourceRange,
    ) -> Result<B::ImageView, ViewCreationError>;
    unsafe fn destroy_image_view(&self, view: B::ImageView);
    unsafe fn create_sampler(
        &self,
        desc: &SamplerDesc,
    ) -> Result<B::Sampler, AllocationError>;
    unsafe fn destroy_sampler(&self, sampler: B::Sampler);
    unsafe fn create_descriptor_pool<I>(
        &self,
        max_sets: usize,
        descriptor_ranges: I,
        flags: DescriptorPoolCreateFlags,
    ) -> Result<B::DescriptorPool, OutOfMemory>
       where I: Iterator<Item = DescriptorRangeDesc>;
    unsafe fn destroy_descriptor_pool(&self, pool: B::DescriptorPool);
    unsafe fn create_descriptor_set_layout<'a, I, J>(
        &self,
        bindings: I,
        immutable_samplers: J,
    ) -> Result<B::DescriptorSetLayout, OutOfMemory>
       where I: Iterator<Item = DescriptorSetLayoutBinding>,
             J: Iterator<Item = &'a B::Sampler>;
    unsafe fn destroy_descriptor_set_layout(
        &self,
        layout: B::DescriptorSetLayout,
    );
    unsafe fn write_descriptor_set<'a, I>(
        &self,
        op: DescriptorSetWrite<'a, B, I>,
    )
       where I: Iterator<Item = Descriptor<'a, B>>;
    unsafe fn copy_descriptor_set<'a>(&self, op: DescriptorSetCopy<'a, B>);
    unsafe fn map_memory(
        &self,
        memory: &mut B::Memory,
        segment: Segment,
    ) -> Result<*mut u8, MapError>;
    unsafe fn flush_mapped_memory_ranges<'a, I>(
        &self,
        ranges: I,
    ) -> Result<(), OutOfMemory>
       where I: Iterator<Item = (&'a B::Memory, Segment)>;
    unsafe fn invalidate_mapped_memory_ranges<'a, I>(
        &self,
        ranges: I,
    ) -> Result<(), OutOfMemory>
       where I: Iterator<Item = (&'a B::Memory, Segment)>;
    unsafe fn unmap_memory(&self, memory: &mut B::Memory);
    fn create_semaphore(&self) -> Result<B::Semaphore, OutOfMemory>;
    unsafe fn destroy_semaphore(&self, semaphore: B::Semaphore);
    fn create_fence(&self, signaled: bool) -> Result<B::Fence, OutOfMemory>;
    unsafe fn reset_fence(
        &self,
        fence: &mut B::Fence,
    ) -> Result<(), OutOfMemory>;
    unsafe fn get_fence_status(
        &self,
        fence: &B::Fence,
    ) -> Result<bool, DeviceLost>;
    unsafe fn destroy_fence(&self, fence: B::Fence);
    fn create_event(&self) -> Result<B::Event, OutOfMemory>;
    unsafe fn destroy_event(&self, event: B::Event);
    unsafe fn get_event_status(
        &self,
        event: &B::Event,
    ) -> Result<bool, WaitError>;
    unsafe fn set_event(&self, event: &mut B::Event) -> Result<(), OutOfMemory>;
    unsafe fn reset_event(
        &self,
        event: &mut B::Event,
    ) -> Result<(), OutOfMemory>;
    unsafe fn create_query_pool(
        &self,
        ty: Type,
        count: Id,
    ) -> Result<B::QueryPool, CreationError>;
    unsafe fn destroy_query_pool(&self, pool: B::QueryPool);
    unsafe fn get_query_pool_results(
        &self,
        pool: &B::QueryPool,
        queries: Range<Id>,
        data: &mut [u8],
        stride: Stride,
        flags: ResultFlags,
    ) -> Result<bool, WaitError>;
    fn wait_idle(&self) -> Result<(), OutOfMemory>;
    unsafe fn set_image_name(&self, image: &mut B::Image, name: &str);
    unsafe fn set_buffer_name(&self, buffer: &mut B::Buffer, name: &str);
    unsafe fn set_command_buffer_name(
        &self,
        command_buffer: &mut B::CommandBuffer,
        name: &str,
    );
    unsafe fn set_semaphore_name(
        &self,
        semaphore: &mut B::Semaphore,
        name: &str,
    );
    unsafe fn set_fence_name(&self, fence: &mut B::Fence, name: &str);
    unsafe fn set_framebuffer_name(
        &self,
        framebuffer: &mut B::Framebuffer,
        name: &str,
    );
    unsafe fn set_render_pass_name(
        &self,
        render_pass: &mut B::RenderPass,
        name: &str,
    );
    unsafe fn set_descriptor_set_name(
        &self,
        descriptor_set: &mut B::DescriptorSet,
        name: &str,
    );
    unsafe fn set_descriptor_set_layout_name(
        &self,
        descriptor_set_layout: &mut B::DescriptorSetLayout,
        name: &str,
    );
    unsafe fn set_pipeline_layout_name(
        &self,
        pipeline_layout: &mut B::PipelineLayout,
        name: &str,
    );
    unsafe fn set_display_power_state(
        &self,
        display: &Display<B>,
        power_state: &PowerState,
    ) -> Result<(), DisplayControlError>;
    unsafe fn register_device_event(
        &self,
        device_event: &DeviceEvent,
        fence: &mut B::Fence,
    ) -> Result<(), DisplayControlError>;
    unsafe fn register_display_event(
        &self,
        display: &Display<B>,
        display_event: &DisplayEvent,
        fence: &mut B::Fence,
    ) -> Result<(), DisplayControlError>;
    unsafe fn create_allocate_external_buffer(
        &self,
        external_memory_type_flags: ExternalBufferMemoryType,
        usage: Usage,
        sparse: SparseFlags,
        type_mask: u32,
        size: u64,
    ) -> Result<(B::Buffer, B::Memory), ExternalResourceError>;
    unsafe fn import_external_buffer(
        &self,
        external_memory: ExternalBufferMemory,
        usage: Usage,
        sparse: SparseFlags,
        type_mask: u32,
        size: u64,
    ) -> Result<(B::Buffer, B::Memory), ExternalResourceError>;
    unsafe fn create_allocate_external_image(
        &self,
        external_memory_type: ExternalImageMemoryType,
        kind: Kind,
        mip_levels: Level,
        format: Format,
        tiling: Tiling,
        usage: Usage,
        sparse: SparseFlags,
        view_caps: ViewCapabilities,
        type_mask: u32,
    ) -> Result<(B::Image, B::Memory), ExternalResourceError>;
    unsafe fn import_external_image(
        &self,
        external_memory: ExternalImageMemory,
        kind: Kind,
        mip_levels: Level,
        format: Format,
        tiling: Tiling,
        usage: Usage,
        sparse: SparseFlags,
        view_caps: ViewCapabilities,
        type_mask: u32,
    ) -> Result<(B::Image, B::Memory), ExternalResourceError>;
    unsafe fn export_memory(
        &self,
        external_memory_type: ExternalMemoryType,
        memory: &B::Memory,
    ) -> Result<PlatformMemory, ExternalMemoryExportError>;
    unsafe fn drm_format_modifier(
        &self,
        image: &B::Image,
    ) -> Option<DrmModifier>;
    fn start_capture(&self);
    fn stop_capture(&self);

    // Provided methods
    unsafe fn create_shader_module_from_naga(
        &self,
        shader: NagaShader,
    ) -> Result<B::ShaderModule, (ShaderError, NagaShader)> { ... }
    unsafe fn wait_for_fence(
        &self,
        fence: &B::Fence,
        timeout_ns: u64,
    ) -> Result<bool, WaitError> { ... }
    unsafe fn wait_for_fences<'a, I>(
        &self,
        fences: I,
        wait: WaitFor,
        timeout_ns: u64,
    ) -> Result<bool, WaitError>
       where I: Iterator<Item = &'a B::Fence> { ... }
}

Logical device handle, responsible for creating and managing resources for the physical device it was created from.

Resource Construction and Handling

This device structure can then be used to create and manage different resources, like buffers, shader modules and images. See the individual methods for more information.

Mutability

All the methods get &self. Any internal mutability of the Device is hidden from the user.

Synchronization

Device should be usable concurrently from multiple threads. The Send and Sync bounds are not enforced at the HAL level due to OpenGL constraint (to be revised). Users can still benefit from the backends that support synchronization of the Device.

Required Methods

unsafe fn allocate_memory( &self, memory_type: MemoryTypeId, size: u64, ) -> Result<B::Memory, AllocationError>

Allocates a memory segment of a specified type.

There is only a limited amount of allocations allowed depending on the implementation!

Arguments

• memory_type - Index of the memory type in the memory properties of the associated physical device.
• size - Size of the allocation.

unsafe fn free_memory(&self, memory: B::Memory)

Free device memory

unsafe fn create_command_pool( &self, family: QueueFamilyId, create_flags: CommandPoolCreateFlags, ) -> Result<B::CommandPool, OutOfMemory>

Create a new command pool for a given queue family.

Note: the family has to be associated with one of the queue groups of this device.

unsafe fn destroy_command_pool(&self, pool: B::CommandPool)

Destroy a command pool.

unsafe fn create_render_pass<'a, Ia, Is, Id>( &self, attachments: Ia, subpasses: Is, dependencies: Id, ) -> Result<B::RenderPass, OutOfMemory>

where Ia: Iterator<Item = Attachment>, Is: Iterator<Item = SubpassDesc<'a>>, Id: Iterator<Item = SubpassDependency>,

Create a render pass with the given attachments and subpasses.

The use of a render pass in a command buffer is a render pass instance.

Arguments

• attachments - image attachments to be used in this render pass. Usually you need at least one attachment, to be used as output.
• subpasses - subpasses to use. You need to use at least one subpass.
• dependencies - dependencies between subpasses. Can be empty.

unsafe fn destroy_render_pass(&self, rp: B::RenderPass)

Destroys a render pass created by this device.

unsafe fn create_pipeline_layout<'a, Is, Ic>( &self, set_layouts: Is, push_constant: Ic, ) -> Result<B::PipelineLayout, OutOfMemory>

where Is: Iterator<Item = &'a B::DescriptorSetLayout>, Ic: Iterator<Item = (ShaderStageFlags, Range<u32>)>,

Create a new pipeline layout object.

Arguments

• set_layouts - Descriptor set layouts
• push_constants - Ranges of push constants. A shader stage may only contain one push constant block. The range is defined in units of bytes.

PipelineLayout

Access to descriptor sets from a pipeline is accomplished through a pipeline layout. Zero or more descriptor set layouts and zero or more push constant ranges are combined to form a pipeline layout object which describes the complete set of resources that can be accessed by a pipeline. The pipeline layout represents a sequence of descriptor sets with each having a specific layout. This sequence of layouts is used to determine the interface between shader stages and shader resources. Each pipeline is created using a pipeline layout.

unsafe fn destroy_pipeline_layout(&self, layout: B::PipelineLayout)

Destroy a pipeline layout object

unsafe fn create_pipeline_cache( &self, data: Option<&[u8]>, ) -> Result<B::PipelineCache, OutOfMemory>

Create a pipeline cache object.

unsafe fn get_pipeline_cache_data( &self, cache: &B::PipelineCache, ) -> Result<Vec<u8>, OutOfMemory>

Retrieve data from pipeline cache object.

unsafe fn merge_pipeline_caches<'a, I>( &self, target: &mut B::PipelineCache, sources: I, ) -> Result<(), OutOfMemory>

where I: Iterator<Item = &'a B::PipelineCache>,

Merge a number of source pipeline caches into the target one.

unsafe fn destroy_pipeline_cache(&self, cache: B::PipelineCache)

Destroy a pipeline cache object.

unsafe fn create_graphics_pipeline<'a>( &self, desc: &GraphicsPipelineDesc<'a, B>, cache: Option<&B::PipelineCache>, ) -> Result<B::GraphicsPipeline, CreationError>

Create a graphics pipeline.

Arguments

• desc - the description of the graphics pipeline to create.
• cache - the pipeline cache, obtained from this device, used for faster PSO creation.

unsafe fn destroy_graphics_pipeline(&self, pipeline: B::GraphicsPipeline)

Destroy a graphics pipeline.

The graphics pipeline shouldn’t be destroyed before any submitted command buffer, which references the graphics pipeline, has finished execution.

unsafe fn create_compute_pipeline<'a>( &self, desc: &ComputePipelineDesc<'a, B>, cache: Option<&B::PipelineCache>, ) -> Result<B::ComputePipeline, CreationError>

Create a compute pipeline.

unsafe fn destroy_compute_pipeline(&self, pipeline: B::ComputePipeline)

Destroy a compute pipeline.

The compute pipeline shouldn’t be destroyed before any submitted command buffer, which references the compute pipeline, has finished execution.

unsafe fn create_framebuffer<I>( &self, pass: &B::RenderPass, attachments: I, extent: Extent, ) -> Result<B::Framebuffer, OutOfMemory>

where I: Iterator<Item = FramebufferAttachment>,

Create a new framebuffer object.

Safety

• extent.width, extent.height and extent.depth must be greater than 0.

unsafe fn destroy_framebuffer(&self, buf: B::Framebuffer)

Destroy a framebuffer.

The framebuffer shouldn’t be destroyed before any submitted command buffer, which references the framebuffer, has finished execution.

unsafe fn create_shader_module( &self, spirv: &[u32], ) -> Result<B::ShaderModule, ShaderError>

Create a new shader module object from the SPIR-V binary data.

Once a shader module has been created, any entry points it contains can be used in pipeline shader stages of compute pipelines and graphics pipelines.

unsafe fn destroy_shader_module(&self, shader: B::ShaderModule)

Destroy a shader module module

A shader module can be destroyed while pipelines created using its shaders are still in use.

unsafe fn create_buffer( &self, size: u64, usage: Usage, sparse: SparseFlags, ) -> Result<B::Buffer, CreationError>

Create a new buffer (unbound).

The created buffer won’t have associated memory until bind_buffer_memory is called.

unsafe fn get_buffer_requirements(&self, buf: &B::Buffer) -> Requirements

Get memory requirements for the buffer

unsafe fn bind_buffer_memory( &self, memory: &B::Memory, offset: u64, buf: &mut B::Buffer, ) -> Result<(), BindError>

Bind memory to a buffer.

Be sure to check that there is enough memory available for the buffer. Use get_buffer_requirements to acquire the memory requirements.

unsafe fn destroy_buffer(&self, buffer: B::Buffer)

Destroy a buffer.

The buffer shouldn’t be destroyed before any submitted command buffer, which references the images, has finished execution.

unsafe fn create_buffer_view( &self, buf: &B::Buffer, fmt: Option<Format>, range: SubRange, ) -> Result<B::BufferView, ViewCreationError>

Create a new buffer view object

unsafe fn destroy_buffer_view(&self, view: B::BufferView)

Destroy a buffer view object

unsafe fn create_image( &self, kind: Kind, mip_levels: Level, format: Format, tiling: Tiling, usage: Usage, sparse: SparseFlags, view_caps: ViewCapabilities, ) -> Result<B::Image, CreationError>

Create a new image object

unsafe fn get_image_requirements(&self, image: &B::Image) -> Requirements

Get memory requirements for the Image

unsafe fn get_image_subresource_footprint( &self, image: &B::Image, subresource: Subresource, ) -> SubresourceFootprint

unsafe fn bind_image_memory( &self, memory: &B::Memory, offset: u64, image: &mut B::Image, ) -> Result<(), BindError>

Bind device memory to an image object

unsafe fn destroy_image(&self, image: B::Image)

Destroy an image.

The image shouldn’t be destroyed before any submitted command buffer, which references the images, has finished execution.

unsafe fn create_image_view( &self, image: &B::Image, view_kind: ViewKind, format: Format, swizzle: Swizzle, usage: Usage, range: SubresourceRange, ) -> Result<B::ImageView, ViewCreationError>

Create an image view from an existing image

unsafe fn destroy_image_view(&self, view: B::ImageView)

Destroy an image view object

unsafe fn create_sampler( &self, desc: &SamplerDesc, ) -> Result<B::Sampler, AllocationError>

Create a new sampler object

unsafe fn destroy_sampler(&self, sampler: B::Sampler)

Destroy a sampler object

unsafe fn create_descriptor_pool<I>( &self, max_sets: usize, descriptor_ranges: I, flags: DescriptorPoolCreateFlags, ) -> Result<B::DescriptorPool, OutOfMemory>

where I: Iterator<Item = DescriptorRangeDesc>,

Create a descriptor pool.

Descriptor pools allow allocation of descriptor sets. The pool can’t be modified directly, only through updating descriptor sets.

unsafe fn destroy_descriptor_pool(&self, pool: B::DescriptorPool)

Destroy a descriptor pool object

When a pool is destroyed, all descriptor sets allocated from the pool are implicitly freed and become invalid. Descriptor sets allocated from a given pool do not need to be freed before destroying that descriptor pool.

unsafe fn create_descriptor_set_layout<'a, I, J>( &self, bindings: I, immutable_samplers: J, ) -> Result<B::DescriptorSetLayout, OutOfMemory>

where I: Iterator<Item = DescriptorSetLayoutBinding>, J: Iterator<Item = &'a B::Sampler>,

Create a descriptor set layout.

A descriptor set layout object is defined by an array of zero or more descriptor bindings. Each individual descriptor binding is specified by a descriptor type, a count (array size) of the number of descriptors in the binding, a set of shader stages that can access the binding, and (if using immutable samplers) an array of sampler descriptors.

unsafe fn destroy_descriptor_set_layout(&self, layout: B::DescriptorSetLayout)

Destroy a descriptor set layout object

unsafe fn write_descriptor_set<'a, I>(&self, op: DescriptorSetWrite<'a, B, I>)

where I: Iterator<Item = Descriptor<'a, B>>,

Specifying the parameters of a descriptor set write operation.

unsafe fn copy_descriptor_set<'a>(&self, op: DescriptorSetCopy<'a, B>)

Structure specifying a copy descriptor set operation.

unsafe fn map_memory( &self, memory: &mut B::Memory, segment: Segment, ) -> Result<*mut u8, MapError>

Map a memory object into application address space

Call map_memory() to retrieve a host virtual address pointer to a region of a mappable memory object

unsafe fn flush_mapped_memory_ranges<'a, I>( &self, ranges: I, ) -> Result<(), OutOfMemory>

where I: Iterator<Item = (&'a B::Memory, Segment)>,

Flush mapped memory ranges

unsafe fn invalidate_mapped_memory_ranges<'a, I>( &self, ranges: I, ) -> Result<(), OutOfMemory>

where I: Iterator<Item = (&'a B::Memory, Segment)>,

Invalidate ranges of non-coherent memory from the host caches

unsafe fn unmap_memory(&self, memory: &mut B::Memory)

Unmap a memory object once host access to it is no longer needed by the application

fn create_semaphore(&self) -> Result<B::Semaphore, OutOfMemory>

Create a new semaphore object.

unsafe fn destroy_semaphore(&self, semaphore: B::Semaphore)

Destroy a semaphore object.

fn create_fence(&self, signaled: bool) -> Result<B::Fence, OutOfMemory>

Create a new fence object.

Fences are a synchronization primitive that can be used to insert a dependency from a queue to the host. Fences have two states - signaled and unsignaled.

A fence can be signaled as part of the execution of a queue submission command.

Fences can be unsignaled on the host with reset_fence.

Fences can be waited on by the host with the wait_for_fences command.

A fence’s current state can be queried with get_fence_status.

Arguments

• signaled - the fence will be in its signaled state.

unsafe fn reset_fence(&self, fence: &mut B::Fence) -> Result<(), OutOfMemory>

Resets a given fence to its original, unsignaled state.

unsafe fn get_fence_status(&self, fence: &B::Fence) -> Result<bool, DeviceLost>

true for signaled, false for not ready

unsafe fn destroy_fence(&self, fence: B::Fence)

Destroy a fence object

fn create_event(&self) -> Result<B::Event, OutOfMemory>

Create an event object.

unsafe fn destroy_event(&self, event: B::Event)

Destroy an event object.

unsafe fn get_event_status(&self, event: &B::Event) -> Result<bool, WaitError>

Query the status of an event.

Returns true if the event is set, or false if it is reset.

unsafe fn set_event(&self, event: &mut B::Event) -> Result<(), OutOfMemory>

Sets an event.

unsafe fn reset_event(&self, event: &mut B::Event) -> Result<(), OutOfMemory>

Resets an event.

unsafe fn create_query_pool( &self, ty: Type, count: Id, ) -> Result<B::QueryPool, CreationError>

Create a new query pool object

Queries are managed using query pool objects. Each query pool is a collection of a specific number of queries of a particular type.

unsafe fn destroy_query_pool(&self, pool: B::QueryPool)

Destroy a query pool object

unsafe fn get_query_pool_results( &self, pool: &B::QueryPool, queries: Range<Id>, data: &mut [u8], stride: Stride, flags: ResultFlags, ) -> Result<bool, WaitError>

Get query pool results into the specified CPU memory. Returns Ok(false) if the results are not ready yet and neither of WAIT or PARTIAL flags are set.

fn wait_idle(&self) -> Result<(), OutOfMemory>

Wait for all queues associated with this device to idle.

Host access to all queues needs to be externally sycnhronized!

unsafe fn set_image_name(&self, image: &mut B::Image, name: &str)

Associate a name with an image, for easier debugging in external tools or with validation layers that can print a friendly name when referring to objects in error messages

unsafe fn set_buffer_name(&self, buffer: &mut B::Buffer, name: &str)

Associate a name with a buffer, for easier debugging in external tools or with validation layers that can print a friendly name when referring to objects in error messages

unsafe fn set_command_buffer_name( &self, command_buffer: &mut B::CommandBuffer, name: &str, )

Associate a name with a command buffer, for easier debugging in external tools or with validation layers that can print a friendly name when referring to objects in error messages

unsafe fn set_semaphore_name(&self, semaphore: &mut B::Semaphore, name: &str)

Associate a name with a semaphore, for easier debugging in external tools or with validation layers that can print a friendly name when referring to objects in error messages

unsafe fn set_fence_name(&self, fence: &mut B::Fence, name: &str)

Associate a name with a fence, for easier debugging in external tools or with validation layers that can print a friendly name when referring to objects in error messages

unsafe fn set_framebuffer_name( &self, framebuffer: &mut B::Framebuffer, name: &str, )

Associate a name with a framebuffer, for easier debugging in external tools or with validation layers that can print a friendly name when referring to objects in error messages

unsafe fn set_render_pass_name( &self, render_pass: &mut B::RenderPass, name: &str, )

Associate a name with a render pass, for easier debugging in external tools or with validation layers that can print a friendly name when referring to objects in error messages

unsafe fn set_descriptor_set_name( &self, descriptor_set: &mut B::DescriptorSet, name: &str, )

Associate a name with a descriptor set, for easier debugging in external tools or with validation layers that can print a friendly name when referring to objects in error messages

unsafe fn set_descriptor_set_layout_name( &self, descriptor_set_layout: &mut B::DescriptorSetLayout, name: &str, )

Associate a name with a descriptor set layout, for easier debugging in external tools or with validation layers that can print a friendly name when referring to objects in error messages

unsafe fn set_pipeline_layout_name( &self, pipeline_layout: &mut B::PipelineLayout, name: &str, )

Associate a name with a pipeline layout, for easier debugging in external tools or with validation layers that can print a friendly name when referring to objects in error messages

unsafe fn set_display_power_state( &self, display: &Display<B>, power_state: &PowerState, ) -> Result<(), DisplayControlError>

Control the power state of the provided display

unsafe fn register_device_event( &self, device_event: &DeviceEvent, fence: &mut B::Fence, ) -> Result<(), DisplayControlError>

Register device event

unsafe fn register_display_event( &self, display: &Display<B>, display_event: &DisplayEvent, fence: &mut B::Fence, ) -> Result<(), DisplayControlError>

Register display event

unsafe fn create_allocate_external_buffer( &self, external_memory_type_flags: ExternalBufferMemoryType, usage: Usage, sparse: SparseFlags, type_mask: u32, size: u64, ) -> Result<(B::Buffer, B::Memory), ExternalResourceError>

Create, allocate and bind a buffer that can be exported.

Arguments

• external_memory_type_flags - the external memory types the buffer will be valid to be used.
• usage - the usage of the buffer.
• sparse - the sparse flags of the buffer.
• type_mask - a memory type mask containing all the desired memory type ids.
• size - the size of the buffer.

Errors

• Returns OutOfMemory if the implementation goes out of memory during the operation.
• Returns TooManyObjects if the implementation can allocate buffers no more.
• Returns NoValidMemoryTypeId if the no one of the desired memory type id is valid for the implementation.
• Returns InvalidExternalHandle if the requested external memory type is invalid for the implementation.

unsafe fn import_external_buffer( &self, external_memory: ExternalBufferMemory, usage: Usage, sparse: SparseFlags, type_mask: u32, size: u64, ) -> Result<(B::Buffer, B::Memory), ExternalResourceError>

Import external memory as binded buffer and memory.

Arguments

• external_memory - the external memory types the buffer will be valid to be used.
• usage - the usage of the buffer.
• sparse - the sparse flags of the buffer.
• type_mask - a memory type mask containing all the desired memory type ids.
• size - the size of the buffer.

Errors

• Returns OutOfMemory if the implementation goes out of memory during the operation.
• Returns TooManyObjects if the implementation can allocate buffers no more.
• Returns NoValidMemoryTypeId if the no one of the desired memory type id is valid for the implementation.
• Returns InvalidExternalHandle if the requested external memory type is invalid for the implementation.

unsafe fn create_allocate_external_image( &self, external_memory_type: ExternalImageMemoryType, kind: Kind, mip_levels: Level, format: Format, tiling: Tiling, usage: Usage, sparse: SparseFlags, view_caps: ViewCapabilities, type_mask: u32, ) -> Result<(B::Image, B::Memory), ExternalResourceError>

Create, allocate and bind an image that can be exported.

Arguments

• external_memory - the external memory types the image will be valid to be used.
• kind - the image kind.
• mip_levels - the mip levels of the image.
• format - the format of the image.
• tiling - the tiling mode of the image.
• dimensions - the dimensions of the image.
• usage - the usage of the image.
• sparse - the sparse flags of the image.
• view_caps - the view capabilities of the image.
• type_mask - a memory type mask containing all the desired memory type ids.

Errors

• Returns OutOfMemory if the implementation goes out of memory during the operation.
• Returns TooManyObjects if the implementation can allocate images no more.
• Returns NoValidMemoryTypeId if the no one of the desired memory type id is valid for the implementation.
• Returns InvalidExternalHandle if the requested external memory type is invalid for the implementation.

unsafe fn import_external_image( &self, external_memory: ExternalImageMemory, kind: Kind, mip_levels: Level, format: Format, tiling: Tiling, usage: Usage, sparse: SparseFlags, view_caps: ViewCapabilities, type_mask: u32, ) -> Result<(B::Image, B::Memory), ExternalResourceError>

Import external memory as binded image and memory.

Arguments

• external_memory - the external memory types the image will be valid to be used.
• kind - the image kind.
• mip_levels - the mip levels of the image.
• format - the format of the image.
• tiling - the tiling mode of the image.
• dimensions - the dimensions of the image.
• usage - the usage of the image.
• sparse - the sparse flags of the image.
• view_caps - the view capabilities of the image.
• type_mask - a memory type mask containing all the desired memory type ids.

Errors

• Returns OutOfMemory if the implementation goes out of memory during the operation.
• Returns TooManyObjects if the implementation can allocate images no more.
• Returns NoValidMemoryTypeId if the no one of the desired memory type id is valid for the implementation.
• Returns InvalidExternalHandle if the requested external memory type is invalid for the implementation.

unsafe fn export_memory( &self, external_memory_type: ExternalMemoryType, memory: &B::Memory, ) -> Result<PlatformMemory, ExternalMemoryExportError>

Export memory as os type (Fd, Handle or Ptr) based on the requested external memory type.

Arguments

• external_memory_type - the external memory type the memory will be exported to.
• memory - the memory object.

Errors

• Returns OutOfMemory if the implementation goes out of memory during the operation.
• Returns TooManyObjects if the implementation can allocate images no more.
• Returns InvalidExternalHandle if the requested external memory type is invalid for the implementation.

unsafe fn drm_format_modifier(&self, image: &B::Image) -> Option<DrmModifier>

Retrieve the underlying drm format modifier from an image, if any.

Arguments

• image - the image object.

fn start_capture(&self)

Starts frame capture.

fn stop_capture(&self)

Stops frame capture.

Provided Methods

unsafe fn create_shader_module_from_naga( &self, shader: NagaShader, ) -> Result<B::ShaderModule, (ShaderError, NagaShader)>

Create a new shader module from the naga module.

unsafe fn wait_for_fence( &self, fence: &B::Fence, timeout_ns: u64, ) -> Result<bool, WaitError>

Blocks until the given fence is signaled. Returns true if the fence was signaled before the timeout.

unsafe fn wait_for_fences<'a, I>( &self, fences: I, wait: WaitFor, timeout_ns: u64, ) -> Result<bool, WaitError>

where I: Iterator<Item = &'a B::Fence>,

Blocks until all or one of the given fences are signaled. Returns true if fences were signaled before the timeout.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors