Skip to content

Commit

Permalink
Merge #2262
Browse files Browse the repository at this point in the history 
2262: Add comments to hal/src/device.rs r=kvark a=Michael-Lfx

Fixes #issue
PR checklist:
- [ ] `make` succeeds (on *nix)
- [ ] `make reftests` succeeds
- [ ] tested examples with the following backends:
- [ ] `rustfmt` run on changed code


Co-authored-by: Michael-LAI JINFENG <cihv2@163.com>
  • Loading branch information
@bors @Michael-Lfx
bors[bot] and Michael-Lfx committed Jul 24, 2018
2 parents c7718d0 + cdfc5f3 commit 514973f
Showing 1 changed file with 72 additions and 34 deletions.
106 changes: 72 additions & 34 deletions src/hal/src/device.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -141,15 +141,15 @@ pub trait Device<B: Backend>: Any + Send + Sync {
/// * `size` - Size of the allocation.
fn allocate_memory(&self, memory_type: MemoryTypeId, size: u64) -> Result<B::Memory, OutOfMemory>;

///
/// Free device memory
fn free_memory(&self, memory: B::Memory);

/// Creates a new command pool for a given queue family.
/// Create a new command pool for a given queue family.
///
/// *Note*: the family has to be associated by one as the `Gpu::queue_groups`.
fn create_command_pool(&self, family: QueueFamilyId, create_flags: CommandPoolCreateFlags) -> B::CommandPool;

/// Creates a strongly typed command pool wrapper.
/// Create a strongly typed command pool wrapper.
fn create_command_pool_typed<C>(
&self,
group: &QueueGroup<B, C>,
Expand All @@ -162,10 +162,14 @@ pub trait Device<B: Backend>: Any + Send + Sync {
pool
}

/// Destroys a command pool.
/// Destroy a command pool.
fn destroy_command_pool(&self, pool: B::CommandPool);

/// Creates a render pass with the given attachments and subpasses.
/// 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.
fn create_render_pass<'a, IA, IS, ID>(
&self,
attachments: IA,
Expand All @@ -180,17 +184,26 @@ pub trait Device<B: Backend>: Any + Send + Sync {
ID: IntoIterator,
ID::Item: Borrow<pass::SubpassDependency>;

/// Destroys a `RenderPass`.
/// Destroy a `RenderPass`.
fn destroy_render_pass(&self, rp: B::RenderPass);

/// Create a new pipeline layout.
/// 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.
fn create_pipeline_layout<IS, IR>(
&self,
set_layouts: IS,
Expand All @@ -202,7 +215,7 @@ pub trait Device<B: Backend>: Any + Send + Sync {
IR: IntoIterator,
IR::Item: Borrow<(pso::ShaderStageFlags, Range<u32>)>;

///
/// Destroy a pipeline layout object
fn destroy_pipeline_layout(&self, layout: B::PipelineLayout);

/// Create a graphics pipeline.
Expand All @@ -227,7 +240,7 @@ pub trait Device<B: Backend>: Any + Send + Sync {
.collect()
}

/// Destroys a graphics pipeline.
/// Destroy a graphics pipeline.
///
/// The graphics pipeline shouldn't be destroyed before any submitted command buffer,
/// which references the graphics pipeline, has finished execution.
Expand Down Expand Up @@ -255,13 +268,13 @@ pub trait Device<B: Backend>: Any + Send + Sync {
.collect()
}

/// Destroys 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.
fn destroy_compute_pipeline(&self, pipeline: B::ComputePipeline);

///
/// Create a new framebuffer object
fn create_framebuffer<I>(
&self,
pass: &B::RenderPass,
Expand All @@ -272,18 +285,23 @@ pub trait Device<B: Backend>: Any + Send + Sync {
I: IntoIterator,
I::Item: Borrow<B::ImageView>;

/// Destroys a framebuffer.
/// Destroy a framebuffer.
///
/// The framebuffer shouldn't be destroy before any submitted command buffer,
/// which references the framebuffer, has finished execution.
fn destroy_framebuffer(&self, buf: B::Framebuffer);

/// 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*.
fn create_shader_module(
&self, spirv_data: &[u8]
) -> Result<B::ShaderModule, ShaderError>;

/// Destroy a shader module module
///
/// A shader module can be destroyed while pipelines created using its shaders are still in use.
fn destroy_shader_module(&self, shader: B::ShaderModule);

/// Create a new buffer (unbound).
Expand All @@ -293,7 +311,7 @@ pub trait Device<B: Backend>: Any + Send + Sync {
&self, size: u64, usage: buffer::Usage,
) -> Result<B::UnboundBuffer, buffer::CreationError>;

///
/// Get memory requirements for the unbound buffer
fn get_buffer_requirements(&self, buf: &B::UnboundBuffer) -> Requirements;

/// Bind memory to a buffer.
Expand All @@ -305,46 +323,46 @@ pub trait Device<B: Backend>: Any + Send + Sync {
&self, memory: &B::Memory, offset: u64, buf: B::UnboundBuffer
) -> Result<B::Buffer, BindError>;

/// Destroys a buffer.
/// Destroy a buffer.
///
/// The buffer shouldn't be destroyed before any submitted command buffer,
/// which references the images, has finished execution.
fn destroy_buffer(&self, B::Buffer);

///
/// Create a new buffer view object
fn create_buffer_view<R: RangeArg<u64>>(
&self, buf: &B::Buffer, fmt: Option<format::Format>, range: R
) -> Result<B::BufferView, buffer::ViewCreationError>;

///
/// Destroy a buffer view object
fn destroy_buffer_view(&self, view: B::BufferView);

///
/// Create a new image object
fn create_image(
&self, kind: image::Kind, mip_levels: image::Level, format: format::Format,
tiling: image::Tiling, usage: image::Usage, storage_flags: image::StorageFlags,
) -> Result<B::UnboundImage, image::CreationError>;

///
/// Get memory requirements for the unbound Image
fn get_image_requirements(&self, image: &B::UnboundImage) -> Requirements;

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

///
/// Bind device memory to an image object
fn bind_image_memory(
&self, &B::Memory, offset: u64, B::UnboundImage
) -> Result<B::Image, BindError>;

/// Destroys an image.
/// Destroy an image.
///
/// The image shouldn't be destroyed before any submitted command buffer,
/// which references the images, has finished execution.
fn destroy_image(&self, image: B::Image);

///
/// Create an image view from an existing image
fn create_image_view(
&self,
image: &B::Image,
Expand All @@ -354,13 +372,13 @@ pub trait Device<B: Backend>: Any + Send + Sync {
range: image::SubresourceRange,
) -> Result<B::ImageView, image::ViewError>;

///
/// Destroy an image view object
fn destroy_image_view(&self, view: B::ImageView);

///
/// Create a new sampler object
fn create_sampler(&self, info: image::SamplerInfo) -> B::Sampler;

///
/// Destroy a sampler object
fn destroy_sampler(&self, sampler: B::Sampler);

/// Create a descriptor pool.
Expand All @@ -372,10 +390,19 @@ pub trait Device<B: Backend>: Any + Send + Sync {
I: IntoIterator,
I::Item: Borrow<pso::DescriptorRangeDesc>;

/// 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.
fn destroy_descriptor_pool(&self, pool: B::DescriptorPool);

/// 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.
fn create_descriptor_set_layout<I, J>(
&self, bindings: I, immutable_samplers: J
) -> B::DescriptorSetLayout
Expand All @@ -385,42 +412,44 @@ pub trait Device<B: Backend>: Any + Send + Sync {
J: IntoIterator,
J::Item: Borrow<B::Sampler>;

///
/// Destroy a descriptor set layout object
fn destroy_descriptor_set_layout(&self, layout: B::DescriptorSetLayout);

///
/// Specifying the parameters of a descriptor set write operation
fn write_descriptor_sets<'a, I, J>(&self, write_iter: I)
where
I: IntoIterator<Item = pso::DescriptorSetWrite<'a, B, J>>,
J: IntoIterator,
J::Item: Borrow<pso::Descriptor<'a, B>>;

///
/// Structure specifying a copy descriptor set operation
fn copy_descriptor_sets<'a, I>(&self, copy_iter: I)
where
I: IntoIterator,
I::Item: Borrow<pso::DescriptorSetCopy<'a, B>>;

/// 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
fn map_memory<R>(&self, memory: &B::Memory, range: R) -> Result<*mut u8, mapping::Error>
where
R: RangeArg<u64>;

///
/// Flush mapped memory ranges
fn flush_mapped_memory_ranges<'a, I, R>(&self, ranges: I)
where
I: IntoIterator,
I::Item: Borrow<(&'a B::Memory, R)>,
R: RangeArg<u64>;

///
/// Invalidate ranges of non-coherent memory from the host caches
fn invalidate_mapped_memory_ranges<'a, I, R>(&self, ranges: I)
where
I: IntoIterator,
I::Item: Borrow<(&'a B::Memory, R)>,
R: RangeArg<u64>;

///
/// Unmap a memory object once host access to it is no longer needed by the application
fn unmap_memory(&self, memory: &B::Memory);

/// Acquire a mapping Reader.
Expand Down Expand Up @@ -480,13 +509,19 @@ pub trait Device<B: Backend>: Any + Send + Sync {
self.unmap_memory(writer.memory);
}

///
/// Create a new semaphore object
fn create_semaphore(&self) -> B::Semaphore;

///
/// Destroy a semaphore object
fn destroy_semaphore(&self, semaphore: B::Semaphore);

/// 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*.
fn create_fence(&self, signaled: bool) -> B::Fence;

///
Expand Down Expand Up @@ -559,13 +594,16 @@ pub trait Device<B: Backend>: Any + Send + Sync {
/// true for signaled, false for not ready
fn get_fence_status(&self, fence: &B::Fence) -> bool;

///
/// Destroy a fence object
fn destroy_fence(&self, fence: B::Fence);

/// 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.
fn create_query_pool(&self, ty: query::QueryType, count: u32) -> B::QueryPool;

///
/// Destroy a query pool object
fn destroy_query_pool(&self, pool: B::QueryPool);

/// Create a new swapchain from a surface and a queue family, optionally providing the old
Expand Down

0 comments on commit 514973f

Please sign in to comment.