Document features of each crate (#2115)

vulkano-shaders/src/lib.rs

@@ -1,6 +1,15 @@
 //! The procedural macro for vulkano's shader system.
 //! Manages the compile-time compilation of GLSL into SPIR-V and generation of assosciated rust code.
 //!
+//! # Cargo features
+//!
+//! | Feature                     | Description                                                                  |
+//! |-----------------------------|------------------------------------------------------------------------------|
+//! | `shaderc-build-from-source` | Build the `shaderc` library from source when compiling.                      |
+//! | `shaderc-debug`             | Compile shaders with debug information included.                             |
+//! | `cgmath`                    | Generate structures with vectors and matrices from the [`cgmath`] library.   |
+//! | `nalgebra`                  | Generate structures with vectors and matrices from the [`nalgebra`] library. |
+//!
 //! # Basic usage
 //!
 //! ```
@@ -204,6 +213,8 @@
 //!
 //! The crate fails to compile but prints the generated rust code to stdout.
 //!
+//! [`cgmath`]: https://crates.io/crates/cgmath
+//! [`nalgebra`]: https://crates.io/crates/nalgebra
 //! [reflect]: https://github.com/vulkano-rs/vulkano/blob/master/vulkano-shaders/src/lib.rs#L67
 //! [cargo-expand]: https://github.com/dtolnay/cargo-expand
 //! [ShaderModule::new]: https://docs.rs/vulkano/*/vulkano/pipeline/shader/struct.ShaderModule.html#method.new

vulkano-win/src/lib.rs

@@ -1,13 +1,17 @@
+//! # Cargo features
+//!
+//! | Feature              | Description                                                                |
+//! |----------------------|----------------------------------------------------------------------------|
+//! | `raw_window_handle_` | Include support for the [`raw_window_handle`] library. Enabled by default. |
+//! | `winit_`             | Include support for the [`winit`] library. Enabled by default.             |
+//!
+//! [`raw_window_handle`]: https://crates.io/crates/raw_window_handle
+//! [`winit`]: https://crates.io/crates/winit
+
 #![doc(html_logo_url = "https://raw.githubusercontent.com/vulkano-rs/vulkano/master/logo.png")]
 #![allow(clippy::missing_safety_doc)]
 #![warn(rust_2018_idioms, rust_2021_compatibility)]
 
-/// Create a surface either using winit or a RawWindowHandle
-/// Its possible to disable either one using features
-///
-/// RawWindowHandle feature is called 'raw-window-handle_'
-/// winit featur is called 'winit_'
-
 #[cfg(feature = "raw-window-handle_")]
 mod raw_window_handle;
 #[cfg(feature = "raw-window-handle_")]

vulkano/src/lib.rs

@@ -10,56 +10,121 @@
 #![doc(html_logo_url = "https://raw.githubusercontent.com/vulkano-rs/vulkano/master/logo.png")]
 //! Safe and rich Rust wrapper around the Vulkan API.
 //!
-//! # Brief summary of Vulkan
+//! # Cargo features
 //!
-//! - The [`VulkanLibrary`](crate::VulkanLibrary) represents a Vulkan library on the system.
+//! | Feature              | Description                                                                   |
-//!   It must be loaded before you can do anything with Vulkan.
+//! |----------------------|-------------------------------------------------------------------------------|
+//! | `document_unchecked` | Include `_unchecked` functions in the generated documentation.                |
+//! | `cgmath`             | Generate additional definitions and functions using the [`cgmath`] library.   |
+//! | `nalgebra`           | Generate additional definitions and functions using the [`nalgebra`] library. |
 //!
-//! - The [`Instance`](crate::instance::Instance) object is the API entry point, and represents
+//! # Starting off with Vulkano
-//!   an initialised Vulkan library. This is the first Vulkan object that you create.
 //!
-//! - The [`PhysicalDevice`](crate::device::physical::PhysicalDevice) object represents a
+//! The steps for using Vulkan through Vulkano are in principle not any different from using
-//!   Vulkan-capable device that is available on the system (eg. a graphics card, a software
+//! the raw Vulkan API, but the details may be different for the sake of idiomaticity, safety
-//!   implementation, etc.). Physical devices can be enumerated from an instance with
+//! and convenience.
-//!   [`Instance::enumerate_physical_devices`](crate::instance::Instance::enumerate_physical_devices).
 //!
-//! - Once you have chosen a physical device to use, you can create a
+//! 1. Create a [`VulkanLibrary`]. This represents a Vulkan library on the system, which must be
-//!   [`Device`](crate::device::Device) object from it. The `Device` is the most important
+//!    loaded before you can do anything with Vulkan.
-//!   object of Vulkan, as it represents an open channel of communication with a physical device.
-//!   You always need to have one before you can do interesting things with Vulkan.
 //!
-//! - [*Buffers*](crate::buffer) and [*images*](crate::image) can be used to store data on
+//! 2. Create an [`Instance`]. This is the API entry point, and represents an initialised Vulkan
-//!   memory accessible by the GPU (or more generally by the Vulkan implementation). Buffers are
+//!    library.
-//!   usually used to store information about vertices, lights, etc. or arbitrary data, while
-//!   images are used to store textures or multi-dimensional data.
 //!
-//! - In order to show something on the screen, you need a
+//! 3. If you intend to show graphics to the user on a window or a screen, create a [`Surface`].
-//!   [`Surface` and a `Swapchain`](crate::swapchain).
+//!    A `Surface` is created from a window identifier or handle, that is specific to the display or
-//!   A `Swapchain` contains special `Image`s that correspond to the content of the window or the
+//!    windowing system being used. The [`vulkano-win`] crate, which is part of the Vulkano
-//!   monitor. When you *present* a swapchain, the content of one of these special images is shown
+//!    project, can make this step easier.
-//!   on the screen.
 //!
-//! - For graphical operations, [`RenderPass`es and `Framebuffer`s](crate::render_pass)
+//! 4. [Enumerate the physical devices] that are available on the `Instance`, and choose one that
-//!   describe which images the device must draw upon.
+//!    is suitable for your program. A [`PhysicalDevice`] represents a Vulkan-capable device that
+//!    is available on the system, such as a graphics card, a software implementation, etc.
 //!
-//! - In order to be able to perform operations on the device, you need to have created a
+//! 6. Create a [`Device`] and accompanying [`Queue`]s from the selected `PhysicalDevice`.
-//!   [pipeline object](crate::pipeline) that describes the operation you want. These objects are usually
+//!    The `Device` is the most important object of Vulkan, and you need one to create almost
-//!   created during your program's initialization. `Shader`s are programs that the GPU will
+//!    every other object. `Queue`s are created together with the `Device`, and are used to submit
-//!   execute as part of a pipeline. [*Descriptor sets*](crate::descriptor_set) can be used to access
+//!    work to the device to make it do something.
-//!   the content of buffers or images from within shaders.
 //!
-//! - To tell the GPU to do something, you must create a
+//! 7. If you created a `Surface` earlier, create a [`Swapchain`]. This object contains special
-//!   [*command buffer*](crate::command_buffer). A command buffer contains a list of commands
+//!    images that correspond to the contents of the surface. Whenever you want to
-//!   that the GPU must perform. This can include copies between buffers and images, compute
+//!    change the contents (show something new to the user), you must first *acquire* one of these
-//!   operations, or graphics operations. For the work to start, the command buffer must then be
+//!    images from the swapchain, fill it with the new contents (by rendering, copying or any
-//!   submitted to a [`Queue`](crate::device::Queue), which is obtained when you create the
+//!    other means), and then *present* it back to the swapchain.
-//!   `Device`.
+//!    A swapchain can become outdated if the properties of the surface change, such as when
+//!    the size of the window changes. It then becomes necessary to create a new swapchain.
 //!
-//! - Once you have built a *command buffer* that contains a list of commands, submitting it to the
+//! 8. Record a [*command buffer*](crate::command_buffer), containing commands that the device must
-//!   GPU will return an object that implements [the `GpuFuture` trait](crate::sync::GpuFuture).
+//!    execute. Then build the command buffer and submit it to a `Queue`.
-//!   `GpuFuture`s allow you to chain multiple submissions together and are essential to performing
-//!   multiple operations on multiple different GPU queues.
 //!
+//! Many different operations can be recorded to a command buffer, such as *draw*, *compute* and
+//! *transfer* operations. To do any of these things, you will need to create several other objects,
+//! depending on your specific needs. This includes:
+//!
+//! - [*Buffers*] store general-purpose data on memory accessible by the device. This can include
+//!   mesh data (vertices, texture coordinates etc.), lighting information, matrices, and anything
+//!   else you can think of.
+//!
+//! - [*Images*] store texel data, arranged in a grid of one or more dimensions. They can be used
+//!   as textures, depth/stencil buffers, framebuffers and as part of a swapchain.
+//!
+//! - [*Pipelines*] describe operations on the device. They include one or more [*shader*]s, small
+//!   programs that the device will execute as part of a pipeline.
+//!   Pipelines come in several types:
+//!   - A [`ComputePipeline`] describes how *dispatch* commands are to be performed.
+//!   - A [`GraphicsPipeline`] describes how *draw* commands are to be performed.
+//!
+//! - [*Descriptor sets*] make buffers, images and other objects available to shaders. The
+//!   arrangement of these resources in shaders is described by a [`DescriptorSetLayout`]. One or
+//!   more of these layouts in turn forms a [`PipelineLayout`], which is used when creating a
+//!   pipeline object.
+//!
+//! - For more complex, multi-stage draw operations, you can create a [`RenderPass`] object.
+//!   This object describes the stages, known as subpasses, that draw operations consist of,
+//!   how they interact with one another, and which types of images are available in each subpass.
+//!   You must also create a [`Framebuffer`], which contains the image objects that are to be used
+//!   in a render pass.
+//!
+//! # `_unchecked` functions
+//!
+//! Many functions in Vulkano have two versions: the normal function, which is usually safe to
+//! call, and another function with `_unchecked` added onto the end of the name, which is unsafe
+//! to call. The `_unchecked` functions skip all validation checks, so they are usually more
+//! efficient, but you must ensure that you meet the validity/safety requirements of the function.
+//!
+//! For all `_unchecked` functions, a call to the function is valid, if a call to the
+//! corresponding normal function with the same arguments would return without any error.
+//! This includes following all the valid usage requirements of the Vulkan specification, but may
+//! also include additional requirements specific to Vulkano.
+//! **All other usage of `_unchecked` functions may be undefined behavior.**
+//!
+//! Because there are potentially many `_unchecked` functions, and because their name and operation
+//! can be straightforwardly understood based on the corresponding normal function, they are hidden
+//! from the Vulkano documentation by default. You can unhide them by enabling the
+//! `document_unchecked` cargo feature, and then generating the documentation with the command
+//! `cargo doc --open`.
+//!
+//! [`cgmath`]: https://crates.io/crates/cgmath
+//! [`nalgebra`]: https://crates.io/crates/nalgebra
+//! [`VulkanLibrary`]: crate::VulkanLibrary
+//! [`Instance`]: crate::instance::Instance
+//! [`Surface`]: crate::swapchain::Surface
+//! [`vulkano-win`]: https://crates.io/crates/vulkano-win
+//! [Enumerate the physical devices]: crate::instance::Instance::enumerate_physical_devices
+//! [`PhysicalDevice`]: crate::device::physical::PhysicalDevice
+//! [`Device`]: crate::device::Device
+//! [`Queue`]: crate::device::Queue
+//! [`Swapchain`]: crate::swapchain::Swapchain
+//! [*command buffer*]: crate::command_buffer
+//! [*Buffers*]: crate::buffer
+//! [*Images*]: crate::image
+//! [*Pipelines*]: crate::pipeline
+//! [*shader*]: crate::shader
+//! [`ComputePipeline`]: crate::pipeline::ComputePipeline
+//! [`GraphicsPipeline`]: crate::pipeline::GraphicsPipeline
+//! [*Descriptor sets*]: crate::descriptor_set
+//! [`DescriptorSetLayout`]: crate::descriptor_set::layout
+//! [`PipelineLayout`]: crate::pipeline::layout
+//! [`RenderPass`]: crate::render_pass::RenderPass
+//! [`Framebuffer`]: crate::render_pass::Framebuffer
 
 //#![warn(missing_docs)]        // TODO: activate
 #![warn(