Documentation todos (#1920)

* Added ImageUsage::transient_input_attachment()

* Address TODOs in examples

* Added actual example to command_buffer module documentation.

* Fixed error in command_buffer example

* Check  max_framebuffer_height/width/layers in AttachmentImage constructors.

* Add detailed explanation for shader! macro to triangle examples

examples/src/bin/deferred/frame/system.rs

@@ -142,18 +142,12 @@ impl FrameSystem {
 
         // For now we create three temporary images with a dimension of 1 by 1 pixel.
         // These images will be replaced the first time we call `frame()`.
-        // TODO: use shortcut provided in vulkano 0.6
-        let atch_usage = ImageUsage {
-            transient_attachment: true,
-            input_attachment: true,
-            ..ImageUsage::none()
-        };
         let diffuse_buffer = ImageView::new_default(
             AttachmentImage::with_usage(
                 gfx_queue.device().clone(),
                 [1, 1],
                 Format::A2B10G10R10_UNORM_PACK32,
-                atch_usage,
+                ImageUsage::transient_input_attachment(),
             )
             .unwrap(),
         )
@@ -163,7 +157,7 @@ impl FrameSystem {
                 gfx_queue.device().clone(),
                 [1, 1],
                 Format::R16G16B16A16_SFLOAT,
-                atch_usage,
+                ImageUsage::transient_input_attachment(),
             )
             .unwrap(),
         )
@@ -173,7 +167,7 @@ impl FrameSystem {
                 gfx_queue.device().clone(),
                 [1, 1],
                 Format::D16_UNORM,
-                atch_usage,
+                ImageUsage::transient_input_attachment(),
             )
             .unwrap(),
         )
@@ -232,13 +226,6 @@ impl FrameSystem {
         // `self.depth_buffer` if their dimensions doesn't match the dimensions of the final image.
         let img_dims = final_image.image().dimensions().width_height();
         if self.diffuse_buffer.image().dimensions().width_height() != img_dims {
-            // TODO: use shortcut provided in vulkano 0.6
-            let atch_usage = ImageUsage {
-                transient_attachment: true,
-                input_attachment: true,
-                ..ImageUsage::none()
-            };
-
             // Note that we create "transient" images here. This means that the content of the
             // image is only defined when within a render pass. In other words you can draw to
             // them in a subpass then read them in another subpass, but as soon as you leave the
@@ -248,7 +235,7 @@ impl FrameSystem {
                     self.gfx_queue.device().clone(),
                     img_dims,
                     Format::A2B10G10R10_UNORM_PACK32,
-                    atch_usage,
+                    ImageUsage::transient_input_attachment(),
                 )
                 .unwrap(),
             )
@@ -258,7 +245,7 @@ impl FrameSystem {
                     self.gfx_queue.device().clone(),
                     img_dims,
                     Format::R16G16B16A16_SFLOAT,
-                    atch_usage,
+                    ImageUsage::transient_input_attachment(),
                 )
                 .unwrap(),
             )
@@ -268,7 +255,7 @@ impl FrameSystem {
                     self.gfx_queue.device().clone(),
                     img_dims,
                     Format::D16_UNORM,
-                    atch_usage,
+                    ImageUsage::transient_input_attachment(),
                 )
                 .unwrap(),
             )

examples/src/bin/push-constants.rs

@@ -7,7 +7,11 @@
 // notice may not be copied, modified, or distributed except
 // according to those terms.
 
-// TODO: Give a paragraph about what push constants are and what problems they solve
+// Push constants are a small bank of values written directly to the command buffer 
+// and accessible in shaders. They allow the application to set values used in shaders
+// without creating buffers or modifying and binding descriptor sets for each update.
+// As a result, they are expected to outperform such memory-backed resource updates.
+
 
 use vulkano::{
     buffer::{BufferUsage, CpuAccessibleBuffer},

examples/src/bin/texture_array/main.rs

@@ -206,7 +206,7 @@ fn main() {
             width: 128,
             height: 128,
             array_layers: 3,
-        }; // TODO replace with your actual image array dimensions
+        }; // Replace with your actual image array dimensions
         let (image, future) = ImmutableImage::from_iter(
             image_array_data,
             dimensions,

examples/src/bin/triangle-v1_3.rs

@@ -289,12 +289,20 @@ fn main() {
 
     // The next step is to create the shaders.
     //
-    // The raw shader creation API provided by the vulkano library is unsafe, for various reasons.
+    // The raw shader creation API provided by the vulkano library is unsafe for various
+    // reasons, so The `shader!` macro provides a way to generate a Rust module from GLSL
+    // source - in the example below, the source is provided as a string input directly to
+    // the shader, but a path to a source file can be provided as well. Note that the user
+    // must specify the type of shader (e.g., "vertex," "fragment, etc.") using the `ty`
+    // option of the macro. 
     //
-    // An overview of what the `shader!` macro generates can be found in the
+    // The module generated by the `shader!` macro includes a `load` function which loads
+    // the shader using an input logical device. The module also includes type definitions
+    // for layout structures defined in the shader source, for example, uniforms and push
+    // constants.
+    //
+    // A more detailed overview of what the `shader!` macro generates can be found in the
     // `vulkano-shaders` crate docs. You can view them at https://docs.rs/vulkano-shaders/
-    //
-    // TODO: explain this in details
     mod vs {
         vulkano_shaders::shader! {
             ty: "vertex",

examples/src/bin/triangle.rs

@@ -269,12 +269,20 @@ fn main() {
 
     // The next step is to create the shaders.
     //
-    // The raw shader creation API provided by the vulkano library is unsafe, for various reasons.
+    // The raw shader creation API provided by the vulkano library is unsafe for various
+    // reasons, so The `shader!` macro provides a way to generate a Rust module from GLSL
+    // source - in the example below, the source is provided as a string input directly to
+    // the shader, but a path to a source file can be provided as well. Note that the user
+    // must specify the type of shader (e.g., "vertex," "fragment, etc.") using the `ty`
+    // option of the macro. 
     //
-    // An overview of what the `shader!` macro generates can be found in the
+    // The module generated by the `shader!` macro includes a `load` function which loads
+    // the shader using an input logical device. The module also includes type definitions
+    // for layout structures defined in the shader source, for example, uniforms and push
+    // constants.
+    //
+    // A more detailed overview of what the `shader!` macro generates can be found in the
     // `vulkano-shaders` crate docs. You can view them at https://docs.rs/vulkano-shaders/
-    //
-    // TODO: explain this in details
     mod vs {
         vulkano_shaders::shader! {
             ty: "vertex",
@@ -331,7 +339,9 @@ fn main() {
                 // of your structs that implements the `FormatDesc` trait). Here we use the
                 // same format as the swapchain.
                 format: swapchain.image_format(),
-                // TODO:
+                // `samples: 1` means that we ask the GPU to use one sample to determine the value
+                // of each pixel in the color attachment. We could use a larger value (multisampling)
+                // for antialiasing. An example of this can be found in msaa-renderpass.rs.
                 samples: 1,
             }
         },

vulkano/src/command_buffer/mod.rs

@@ -49,15 +49,28 @@
 //! use vulkano::command_buffer::AutoCommandBufferBuilder;
 //! use vulkano::command_buffer::CommandBufferUsage;
 //! use vulkano::command_buffer::PrimaryCommandBuffer;
+//! use vulkano::command_buffer::SubpassContents;
 //!
+//! # #[repr(C)]
+//! # #[derive(Clone, Copy, Debug, Default, bytemuck::Zeroable, bytemuck::Pod)]
+//! # struct Vertex { position: [f32; 3] };
+//! # vulkano::impl_vertex!(Vertex, position);
+//! # use vulkano::buffer::TypedBufferAccess;
 //! # let device: std::sync::Arc<vulkano::device::Device> = return;
 //! # let queue: std::sync::Arc<vulkano::device::Queue> = return;
+//! # let vertex_buffer: std::sync::Arc<vulkano::buffer::CpuAccessibleBuffer<[Vertex]>> = return;
+//! # let render_pass_begin_info: vulkano::command_buffer::RenderPassBeginInfo = return;
+//! # let graphics_pipeline: std::sync::Arc<vulkano::pipeline::graphics::GraphicsPipeline> = return;
 //! let cb = AutoCommandBufferBuilder::primary(
 //!     device.clone(),
 //!     queue.family(),
 //!     CommandBufferUsage::MultipleSubmit
 //! ).unwrap()
-//! // TODO: add an actual command to this example
+//! .begin_render_pass(render_pass_begin_info, SubpassContents::Inline).unwrap()
+//! .bind_pipeline_graphics(graphics_pipeline.clone())
+//! .bind_vertex_buffers(0, vertex_buffer.clone())
+//! .draw(vertex_buffer.len() as u32, 1, 0, 0).unwrap()
+//! .end_render_pass().unwrap()
 //! .build().unwrap();
 //!
 //! let _future = cb.execute(queue.clone());

vulkano/src/image/attachment.rs

@@ -401,7 +401,18 @@ impl AttachmentImage {
         base_usage: ImageUsage,
         samples: SampleCount,
     ) -> Result<Arc<AttachmentImage>, ImageCreationError> {
-        // TODO: check dimensions against the max_framebuffer_width/height/layers limits
+        let physical_device = device.physical_device();
+        let device_properties = physical_device.properties();
+
+        if dimensions[0] > device_properties.max_framebuffer_height {
+            panic!("AttachmentImage height exceeds physical device's max_framebuffer_height");
+        }
+        if dimensions[1] > device_properties.max_framebuffer_width {
+            panic!("AttachmentImage width exceeds physical device's max_framebuffer_width");
+        }
+        if array_layers > device_properties.max_framebuffer_layers {
+            panic!("AttachmentImage layer count exceeds physical device's max_framebuffer_layers");
+        }
 
         let aspects = format.aspects();
         let is_depth = aspects.depth || aspects.stencil;
@@ -471,7 +482,18 @@ impl AttachmentImage {
         base_usage: ImageUsage,
         samples: SampleCount,
     ) -> Result<Arc<AttachmentImage>, ImageCreationError> {
-        // TODO: check dimensions against the max_framebuffer_width/height/layers limits
+        let physical_device = device.physical_device();
+        let device_properties = physical_device.properties();
+
+        if dimensions[0] > device_properties.max_framebuffer_height {
+            panic!("AttachmentImage height exceeds physical device's max_framebuffer_height");
+        }
+        if dimensions[1] > device_properties.max_framebuffer_width {
+            panic!("AttachmentImage width exceeds physical device's max_framebuffer_width");
+        }
+        if array_layers > device_properties.max_framebuffer_layers {
+            panic!("AttachmentImage layer count exceeds physical device's max_framebuffer_layers");
+        }
 
         let aspects = format.aspects();
         let is_depth = aspects.depth || aspects.stencil;

vulkano/src/image/usage.rs

@@ -151,6 +151,21 @@ impl ImageUsage {
             input_attachment: false,
         }
     }
+
+    /// Builds a ImageUsage with input_attachment and transient_attachment set to true and the rest to false.
+    #[inline]
+    pub fn transient_input_attachment() -> ImageUsage {
+        ImageUsage {
+            transfer_src: false,
+            transfer_dst: false,
+            sampled: false,
+            storage: false,
+            color_attachment: false,
+            depth_stencil_attachment: false,
+            transient_attachment: true,
+            input_attachment: true,
+        }
+    }
 }
 
 impl From<ImageUsage> for ash::vk::ImageUsageFlags {