Struct Factory

pub struct Factory<B: Backend> { /* private fields */ }

Higher level device interface. Manges memory, resources and queue families.

Implementations

impl<B> Factory<B>

where B: Backend,

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

Wait for whole device become idle. This function is very heavy and usually used only for teardown.

pub fn create_relevant_buffer( &self, info: BufferInfo, memory_usage: impl MemoryUsage, ) -> Result<Buffer<B>, BufferCreationError>

Creates a buffer with the specified properties.

This function returns relevant value, that is, the value cannot be dropped. However buffer can be destroyed using destroy_relevant_buffer function.

pub unsafe fn destroy_relevant_buffer(&self, buffer: Buffer<B>)

Destroy buffer. If buffer was created using create_buffer it must be unescaped first. If buffer was shaderd unescaping may fail due to other owners existing. In any case unescaping and destroying manually can slightly increase performance.

Safety

Buffer must not be used by any pending commands or referenced anywhere.

pub fn create_buffer( &self, info: BufferInfo, memory_usage: impl MemoryUsage, ) -> Result<Escape<Buffer<B>>, BufferCreationError>

Creates a buffer with the specified properties.

This function (unlike create_relevant_buffer) returns value that can be dropped.

pub fn create_relevant_image( &self, info: ImageInfo, memory_usage: impl MemoryUsage, ) -> Result<Image<B>, ImageCreationError>

Creates an image with the specified properties.

This function returns relevant value, that is, the value cannot be dropped. However image can be destroyed using destroy_relevant_image function.

pub unsafe fn destroy_relevant_image(&self, image: Image<B>)

Destroy image. If image was created using create_image it must be unescaped first. If image was shaderd unescaping may fail due to other owners existing. In any case unescaping and destroying manually can slightly increase performance.

Safety

Image must not be used by any pending commands or referenced anywhere.

pub fn create_image( &self, info: ImageInfo, memory_usage: impl MemoryUsage, ) -> Result<Escape<Image<B>>, ImageCreationError>

Creates an image with the specified properties.

This function (unlike create_relevant_image) returns value that can be dropped.

pub fn image_format_properties( &self, info: ImageInfo, ) -> Option<FormatProperties>

Fetch image format details for a particular ImageInfo.

pub fn create_relevant_image_view( &self, image: Handle<Image<B>>, info: ImageViewInfo, ) -> Result<ImageView<B>, ImageViewCreationError>

Create an image view with the specified properties

This function returns relevant value, that is, the value cannot be dropped. However image view can be destroyed using destroy_relevant_image_view function.

pub unsafe fn destroy_relevant_image_view(&self, view: ImageView<B>)

Destroy image view. If image view was created using create_image_view it must be unescaped first. If image view was shaderd unescaping may fail due to other owners existing. In any case unescaping and destroying manually can slightly increase performance.

Safety

Image view must not be used by any pending commands or referenced anywhere.

pub fn create_image_view( &self, image: Handle<Image<B>>, info: ImageViewInfo, ) -> Result<Escape<ImageView<B>>, ImageViewCreationError>

Create an image view with the specified properties

This function (unlike create_relevant_image_view) returns value that can be dropped.

pub fn create_relevant_sampler( &self, info: SamplerDesc, ) -> Result<Sampler<B>, AllocationError>

Create an sampler with the specified properties

This function returns relevant value, that is, the value cannot be dropped. However sampler can be destroyed using destroy_relevant_sampler function.

pub unsafe fn destroy_relevant_sampler(&self, sampler: Sampler<B>)

Destroy sampler. If sampler was created using create_sampler it must be unescaped first. If sampler was shaderd unescaping may fail due to other owners existing. In any case unescaping and destroying manually can slightly increase performance. If sampler was acquired using get_sampler unescaping will most probably fail due to factory holding handler’s copy in cache.

Safety

Sampler view must not be used by any pending commands or referenced anywhere.

pub fn create_sampler( &self, info: SamplerDesc, ) -> Result<Escape<Sampler<B>>, AllocationError>

Creates a sampler with the specified properties.

This function (unlike create_relevant_sampler) returns value that can be dropped.

pub fn get_sampler( &self, info: SamplerDesc, ) -> Result<Handle<Sampler<B>>, AllocationError>

Get cached sampler or create new one. User should prefer this function to create_sampler and create_relevant_sampler because usually only few sampler configuration is required.

pub unsafe fn upload_visible_buffer<T>( &self, buffer: &mut Buffer<B>, offset: u64, content: &[T], ) -> Result<(), MapError>

where T: 'static + Copy,

Update content of the buffer bound to host visible memory. This function (unlike upload_buffer) update content immediatelly.

Buffers allocated from host-invisible memory types cannot be updated via this function.

Updated content will be automatically made visible to device operations that will be submitted later.

Panics

Panics if buffer size is less than offset + size of content.

Safety

Caller must ensure that device doesn’t use memory region that being updated.

pub unsafe fn upload_buffer<T>( &self, buffer: &Buffer<B>, offset: u64, content: &[T], last: Option<BufferState>, next: BufferState, ) -> Result<(), UploadError>

where T: 'static + Copy,

Update buffer range content with provided data.

Update operation will actually be submitted to the graphics device queue upon next [flush_uploads] or [maintain] call to this Factory, and is guaranteed to take place after all previous operations that have been submitted to the same graphics queue on this Factory since last [flush_uploads] or [maintain] call

Note that buffer range will receive content as raw bytes. And interpretation will depend solely on device operation. Slice of generic type is allowed for convenience. It usually should be POD struct of numeric values or other POD structs.

#[repr(C)] can be used to guarantee defined memory layout of struct fields.

Safety

If buffer is used by device then last state must match the last usage state of the buffer before updating happen. In order to guarantee that updated content will be made visible to next device operation that reads content of the buffer range the next must match buffer usage state in that operation.

pub unsafe fn upload_from_staging_buffer( &self, buffer: &Buffer<B>, offset: u64, staging: Escape<Buffer<B>>, last: Option<BufferState>, next: BufferState, ) -> Result<(), OutOfMemory>

Update buffer content with provided staging buffer.

Update operation will actually be submitted to the graphics device queue upon next [flush_uploads] or [maintain] call to this Factory, and is guaranteed to take place after all previous operations that have been submitted to the same graphics queue on this Factory since last [flush_uploads] or [maintain] call

Safety

If buffer is used by device then last state must match the last usage state of the buffer before updating happen. In order to guarantee that updated content will be made visible to next device operation that reads content of the buffer range the next must match buffer usage state in that operation.

pub unsafe fn transition_image( &self, image: Handle<Image<B>>, image_range: SubresourceRange, last: impl Into<ImageStateOrLayout>, next: ImageState, )

Update image layers content with provided data. Transition part of image from one state to another.

Update operation will actually be submitted to the graphics device queue upon next [flush_uploads] or [maintain] call to this Factory, and is guaranteed to take place after all previous operations that have been submitted to the same graphics queue on this Factory since last [flush_uploads] or [maintain] call

Safety

Image must be created by this Factory. If image is used by device then last state must match the last usage state of the image before transition.

pub unsafe fn upload_image<T>( &self, image: Handle<Image<B>>, data_width: u32, data_height: u32, image_layers: SubresourceLayers, image_offset: Offset, image_extent: Extent, content: &[T], last: impl Into<ImageStateOrLayout>, next: ImageState, ) -> Result<(), UploadError>

where T: 'static + Copy,

Update image layers content with provided data.

Update operation will actually be submitted to the graphics device queue upon next [flush_uploads] or [maintain] call to this Factory, and is guaranteed to take place after all previous operations that have been submitted to the same graphics queue on this Factory since last [flush_uploads] or [maintain] call

Note that image layers will receive content as raw bytes. And interpretation will depend solely on device operation. Slice of generic type is allowed for convenience. It usually should be compatible type of pixel or channel. For example &[[u8; 4]] or &[u8] for Rgba8Unorm format.

Safety

Image must be created by this Factory. If image is used by device then last state must match the last usage state of the image before updating happen. In order to guarantee that updated content will be made visible to next device operation that reads content of the image layers the next must match image usage state in that operation.

pub fn blitter(&self) -> &Blitter<B>

Get blitter instance

pub fn create_surface( &mut self, handle: &impl HasRawWindowHandle, ) -> Result<Surface<B>, InitError>

Create rendering surface from window handle.

pub unsafe fn create_surface_with( &mut self, f: impl FnOnce(&B::Instance) -> B::Surface, ) -> Surface<B>

Create rendering surface from window.

Safety

Closure must return surface object created from raw instance provided as closure argument.

pub fn get_surface_formats(&self, surface: &Surface<B>) -> Option<Vec<Format>>

Get formats supported by the Surface

Panics

Panics if surface was not created by this Factory

pub fn get_surface_capabilities( &self, surface: &Surface<B>, ) -> SurfaceCapabilities

Get compatibility of Surface

Panics

Panics if surface was not created by this Factory

pub fn get_surface_format(&self, surface: &Surface<B>) -> Format

Get surface format.

Panics

Panics if surface was not created by this Factory

pub fn surface_support(&self, family: FamilyId, surface: &Surface<B>) -> bool

Check if queue family supports presentation to the specified surface.

pub fn destroy_surface(&mut self, surface: Surface<B>)

Destroy surface returning underlying window back to the caller.

Panics

Panics if surface was not created by this Factory

pub fn create_target( &self, surface: Surface<B>, extent: Extent2D, image_count: u32, present_mode: PresentMode, usage: Usage, ) -> Result<Target<B>, SwapchainError>

Create target out of rendering surface.

The compatibility of the surface with the queue family which will present to this target must have already been checked using Factory::surface_support.

Panics

Panics if surface was not created by this Factory.

pub unsafe fn destroy_target(&self, target: Target<B>) -> Surface<B>

Destroy target returning underlying surface back to the caller.

Safety

Target images must not be used by pending commands or referenced anywhere.

pub fn device(&self) -> &Device<B>

Get raw device.

pub fn physical(&self) -> &B::PhysicalDevice

Get raw physical device.

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

Create new semaphore.

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

Destroy semaphore.

Safety

Semaphore must be created by this Factory.

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

Create new fence

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

Wait for the fence become signeled.

pub fn reset_fences<'a>( &self, fences: impl IntoIterator<Item = &'a mut (impl BorrowMut<Fence<B>> + 'a)>, ) -> Result<(), OutOfMemory>

Wait for the fence become signeled.

Safety

Fences must be created by this Factory.

pub fn wait_for_fence( &self, fence: &mut Fence<B>, timeout_ns: u64, ) -> Result<bool, OomOrDeviceLost>

Wait for the fence become signeled.

pub fn wait_for_fences<'a>( &self, fences: impl IntoIterator<Item = &'a mut (impl BorrowMut<Fence<B>> + 'a)>, wait_for: WaitFor, timeout_ns: u64, ) -> Result<bool, OomOrDeviceLost>

Wait for the fences become signeled.

pub fn destroy_fence(&self, fence: Fence<B>)

Destroy fence.

Safety

Fence must be created by this Factory.

pub fn create_command_pool<R>( &self, family: &Family<B>, ) -> Result<CommandPool<B, QueueType, R>, OutOfMemory>

where R: Reset,

Create new command pool for specified family.

pub unsafe fn destroy_command_pool<C, R>(&self, pool: CommandPool<B, C, R>)

where R: Reset,

Create new command pool for specified family.

Safety

All command buffers allocated from the pool must be freed.

pub fn cleanup(&mut self, families: &Families<B>)

Cleanup unused resources

pub fn flush_uploads(&mut self, families: &mut Families<B>)

Flush uploads

pub fn flush_blits(&mut self, families: &mut Families<B>)

Flush blits

pub fn maintain(&mut self, families: &mut Families<B>)

Flush uploads and cleanup unused resources.

pub fn create_relevant_descriptor_set_layout( &self, bindings: Vec<DescriptorSetLayoutBinding>, ) -> Result<DescriptorSetLayout<B>, OutOfMemory>

Create descriptor set layout with specified bindings.

pub fn create_descriptor_set_layout( &self, bindings: Vec<DescriptorSetLayoutBinding>, ) -> Result<Escape<DescriptorSetLayout<B>>, OutOfMemory>

Create descriptor set layout with specified bindings.

pub fn create_relevant_descriptor_set( &self, layout: Handle<DescriptorSetLayout<B>>, ) -> Result<DescriptorSet<B>, OutOfMemory>

Create descriptor sets with specified layout.

pub fn create_descriptor_set( &self, layout: Handle<DescriptorSetLayout<B>>, ) -> Result<Escape<DescriptorSet<B>>, OutOfMemory>

Create descriptor sets with specified layout.

pub fn create_descriptor_sets<T>( &self, layout: Handle<DescriptorSetLayout<B>>, count: u32, ) -> Result<T, OutOfMemory>

where T: FromIterator<Escape<DescriptorSet<B>>>,

Create descriptor sets with specified layout.

Safety

layout must be created by this Factory.

pub fn memory_utilization(&self) -> TotalMemoryUtilization

Query memory utilization.

pub fn instance_id(&self) -> InstanceId

Get Factory’s instance id.

Methods from Deref<Target = Device<B>>

pub fn id(&self) -> DeviceId

Get device id.

pub fn raw(&self) -> &<B as Backend>::Device

Get reference to raw device.

Trait Implementations

impl<B: Debug + Backend> Debug for Factory<B>

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

Formats the value using the given formatter.

impl<B> Deref for Factory<B>

where B: Backend,

type Target = Device<B>

The resulting type after dereferencing.

fn deref(&self) -> &Device<B>

Dereferences the value.

impl<B> Drop for Factory<B>

where B: Backend,

fn drop(&mut self)

Executes the destructor for this type.