Trait gfx_hal::device::Device

source · 
pub trait Device<B: Backend>: Any + Send + Sync {

Show 66 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: IntoIterator,
        IA::Item: Borrow<Attachment>,
        IS: IntoIterator,
        IS::Item: Borrow<SubpassDesc<'a>>,
        ID: IntoIterator,
        ID::Item: Borrow<SubpassDependency>;
    unsafe fn destroy_render_pass(&self, rp: B::RenderPass);
    unsafe fn create_pipeline_layout<IS, IR>(
        &self,
        set_layouts: IS,
        push_constant: IR
    ) -> Result<B::PipelineLayout, OutOfMemory>
    where
        IS: IntoIterator,
        IS::Item: Borrow<B::DescriptorSetLayout>,
        IR: IntoIterator,
        IR::Item: Borrow<(ShaderStageFlags, Range<u32>)>;
    unsafe fn destroy_pipeline_layout(&self, layout: B::PipelineLayout);
    fn create_pipeline_cache(&self) -> Result<B::PipelineCache, OutOfMemory>;
    unsafe fn merge_pipeline_caches<I>(
        &self,
        target: &B::PipelineCache,
        sources: I
    ) -> Result<(), OutOfMemory>
    where
        I: IntoIterator,
        I::Item: Borrow<B::PipelineCache>;
    unsafe fn destroy_pipeline_cache(&self, cache: B::PipelineCache);
    unsafe fn destroy_graphics_pipeline(&self, pipeline: B::GraphicsPipeline);
    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: IntoIterator,
        I::Item: Borrow<B::ImageView>;
    unsafe fn destroy_framebuffer(&self, buf: B::Framebuffer);
    unsafe fn create_shader_module(
        &self,
        spirv_data: &[u8]
    ) -> Result<B::ShaderModule, ShaderError>;
    unsafe fn destroy_shader_module(&self, shader: B::ShaderModule);
    unsafe fn create_buffer(
        &self,
        size: u64,
        usage: Usage
    ) -> 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<R: RangeArg<u64>>(
        &self,
        buf: &B::Buffer,
        fmt: Option<Format>,
        range: R
    ) -> 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,
        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,
        range: SubresourceRange
    ) -> Result<B::ImageView, ViewError>;
    unsafe fn destroy_image_view(&self, view: B::ImageView);
    unsafe fn create_sampler(
        &self,
        info: SamplerInfo
    ) -> 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
    ) -> Result<B::DescriptorPool, OutOfMemory>
    where
        I: IntoIterator,
        I::Item: Borrow<DescriptorRangeDesc>;
    unsafe fn destroy_descriptor_pool(&self, pool: B::DescriptorPool);
    unsafe fn create_descriptor_set_layout<I, J>(
        &self,
        bindings: I,
        immutable_samplers: J
    ) -> Result<B::DescriptorSetLayout, OutOfMemory>
    where
        I: IntoIterator,
        I::Item: Borrow<DescriptorSetLayoutBinding>,
        J: IntoIterator,
        J::Item: Borrow<B::Sampler>;
    unsafe fn destroy_descriptor_set_layout(
        &self,
        layout: B::DescriptorSetLayout
    );
    unsafe fn write_descriptor_sets<'a, I, J>(&self, write_iter: I)
    where
        I: IntoIterator<Item = DescriptorSetWrite<'a, B, J>>,
        J: IntoIterator,
        J::Item: Borrow<Descriptor<'a, B>>;
    unsafe fn copy_descriptor_sets<'a, I>(&self, copy_iter: I)
    where
        I: IntoIterator,
        I::Item: Borrow<DescriptorSetCopy<'a, B>>;
    unsafe fn map_memory<R>(
        &self,
        memory: &B::Memory,
        range: R
    ) -> Result<*mut u8, Error>
    where
        R: RangeArg<u64>;
    unsafe fn flush_mapped_memory_ranges<'a, I, R>(
        &self,
        ranges: I
    ) -> Result<(), OutOfMemory>
    where
        I: IntoIterator,
        I::Item: Borrow<(&'a B::Memory, R)>,
        R: RangeArg<u64>;
    unsafe fn invalidate_mapped_memory_ranges<'a, I, R>(
        &self,
        ranges: I
    ) -> Result<(), OutOfMemory>
    where
        I: IntoIterator,
        I::Item: Borrow<(&'a B::Memory, R)>,
        R: RangeArg<u64>;
    unsafe fn unmap_memory(&self, memory: &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 get_fence_status(
        &self,
        fence: &B::Fence
    ) -> Result<bool, DeviceLost>;
    unsafe fn destroy_fence(&self, fence: B::Fence);
    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: Offset,
        flags: ResultFlags
    ) -> Result<bool, OomOrDeviceLost>;
    unsafe fn create_swapchain(
        &self,
        surface: &mut B::Surface,
        config: SwapchainConfig,
        old_swapchain: Option<B::Swapchain>
    ) -> Result<(B::Swapchain, Backbuffer<B>), CreationError>;
    unsafe fn destroy_swapchain(&self, swapchain: B::Swapchain);
    fn wait_idle(&self) -> Result<(), HostExecutionError>;

    unsafe fn create_command_pool_typed<C>(
        &self,
        group: &QueueGroup<B, C>,
        flags: CommandPoolCreateFlags
    ) -> Result<CommandPool<B, C>, OutOfMemory> { ... }
    unsafe fn create_graphics_pipeline<'a>(
        &self,
        desc: &GraphicsPipelineDesc<'a, B>,
        cache: Option<&B::PipelineCache>
    ) -> Result<B::GraphicsPipeline, CreationError> { ... }
    unsafe fn create_graphics_pipelines<'a, I>(
        &self,
        descs: I,
        cache: Option<&B::PipelineCache>
    ) -> Vec<Result<B::GraphicsPipeline, CreationError>>
    where
        I: IntoIterator,
        I::Item: Borrow<GraphicsPipelineDesc<'a, B>>,
    { ... }
    unsafe fn create_compute_pipeline<'a>(
        &self,
        desc: &ComputePipelineDesc<'a, B>,
        cache: Option<&B::PipelineCache>
    ) -> Result<B::ComputePipeline, CreationError> { ... }
    unsafe fn create_compute_pipelines<'a, I>(
        &self,
        descs: I,
        cache: Option<&B::PipelineCache>
    ) -> Vec<Result<B::ComputePipeline, CreationError>>
    where
        I: IntoIterator,
        I::Item: Borrow<ComputePipelineDesc<'a, B>>,
    { ... }
    unsafe fn acquire_mapping_reader<'a, T>(
        &self,
        memory: &'a B::Memory,
        range: Range<u64>
    ) -> Result<Reader<'a, B, T>, Error>
    where
        T: Copy,
    { ... }
    unsafe fn release_mapping_reader<'a, T>(&self, reader: Reader<'a, B, T>) { ... }
    unsafe fn acquire_mapping_writer<'a, T>(
        &self,
        memory: &'a B::Memory,
        range: Range<u64>
    ) -> Result<Writer<'a, B, T>, Error>
    where
        T: Copy,
    { ... }
    unsafe fn release_mapping_writer<'a, T>(
        &self,
        writer: Writer<'a, B, T>
    ) -> Result<(), OutOfMemory> { ... }
    unsafe fn reset_fence(&self, fence: &B::Fence) -> Result<(), OutOfMemory> { ... }
    unsafe fn reset_fences<I>(&self, fences: I) -> Result<(), OutOfMemory>
    where
        I: IntoIterator,
        I::Item: Borrow<B::Fence>,
    { ... }
    unsafe fn wait_for_fence(
        &self,
        fence: &B::Fence,
        timeout_ns: u64
    ) -> Result<bool, OomOrDeviceLost> { ... }
    unsafe fn wait_for_fences<I>(
        &self,
        fences: I,
        wait: WaitFor,
        timeout_ns: u64
    ) -> Result<bool, OomOrDeviceLost>
    where
        I: IntoIterator,
        I::Item: Borrow<B::Fence>,
    { ... }

}
Expand description

Overview

A Device is 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 programs and textures. 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 by one as the Gpu::queue_groups.

Destroy a command pool.

Create a render pass with the given attachments and subpasses.

A render pass represents a collection of attachments, subpasses, and dependencies between the subpasses, and describes how the attachments are used over the course of the subpasses. The use of a render pass in a command buffer is a render pass instance.

Destroy a RenderPass.

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 length of the range indicates the number of u32 constants occupied by the push constant block.
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.

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

Destroy a pipeline cache object.

Destroy a graphics pipeline.

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

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

Destroy a framebuffer.

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

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

Once a shader module has been created, any entry points it contains can be used in pipeline shader stages as described in 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_fences. Fences can be waited on by the host with the wait_for_fences command, and the current state can be queried with get_fence_status.

true for signaled, false for not ready

Destroy a fence object

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.

Create a new swapchain from a surface and a queue family, optionally providing the old swapchain to aid in resource reuse and rendering continuity.

Note: The number of exposed images in the back buffer might differ from number of internally used buffers.

Safety

The queue family must support surface presentation. This can be checked by calling supports_queue_family on this surface.

Examples
use gfx_hal::{Device, SwapchainConfig};
use gfx_hal::format::Format;

let swapchain_config = SwapchainConfig::new(100, 100, Format::Rgba8Srgb, 2);
device.create_swapchain(&mut surface, swapchain_config, None);

Wait for all queues associated with this device to idle.

Host access to all queues needs to be externally sycnhronized!

Provided Methods

Create a strongly typed command pool wrapper.

Create a graphics pipeline.

Create graphics pipelines.

Create a compute pipeline.

Create compute pipelines.

Acquire a mapping Reader.

The accessible slice will correspond to the specified range (in bytes).

Release a mapping Reader.

Acquire a mapping Writer.

The accessible slice will correspond to the specified range (in bytes).

Release a mapping Writer.

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