Trait gfx_hal::device::Device

source · [−]
pub trait Device<B: Backend>: Debug + Any + Send + Sync {

Show 84 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);

    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>,
    { ... }

}
Expand description

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

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.

Free device memory

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.

Destroy a command pool.

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

Destroys a render pass created by this device.

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.

Destroy a pipeline layout object

Create a pipeline cache object.

Retrieve data from pipeline cache object.

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

Destroy a pipeline cache object.

Create a graphics pipeline.

Arguments

Destroy a graphics pipeline.

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

Create a compute pipeline.

Destroy a compute pipeline.

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

Create a new framebuffer object.

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

Destroy a framebuffer.

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

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.

Destroy a shader module module

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

Create a new buffer (unbound).

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

Get memory requirements for the buffer

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.

Destroy a buffer.

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

Create a new buffer view object

Destroy a buffer view object

Create a new image object

Get memory requirements for the Image

Bind device memory to an image object

Destroy an image.

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

Create an image view from an existing image

Destroy an image view object

Create a new sampler object

Destroy a sampler object

Create a descriptor pool.

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

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.

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.

Destroy a descriptor set layout object

Specifying the parameters of a descriptor set write operation.

Structure specifying a copy descriptor set operation.

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

Flush mapped memory ranges

Invalidate ranges of non-coherent memory from the host caches

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

Create a new semaphore object.

Destroy a semaphore object.

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.

Resets a given fence to its original, unsignaled state.

true for signaled, false for not ready

Destroy a fence object

Create an event object.

Destroy an event object.

Query the status of an event.

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

Sets an event.

Resets an event.

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.

Destroy a query pool object

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.

Wait for all queues associated with this device to idle.

Host access to all queues needs to be externally sycnhronized!

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

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

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

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

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

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

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

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

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

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

Control the power state of the provided display

Register device event

Register display event

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.

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.

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.

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.

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.

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

Arguments
  • image - the image object.

Starts frame capture.

Stops frame capture.

Provided methods

Create a new shader module from the naga module.

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

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

Implementors