From f08e8767a9954a1e708106eb629b5836199dc038 Mon Sep 17 00:00:00 2001 From: Rua Date: Fri, 30 Dec 2022 10:14:43 +0100 Subject: [PATCH] Document features of each crate (#2115) --- vulkano-shaders/src/lib.rs | 11 +++ vulkano-win/src/lib.rs | 16 +++-- vulkano/src/lib.rs | 143 +++++++++++++++++++++++++++---------- 3 files changed, 125 insertions(+), 45 deletions(-) diff --git a/vulkano-shaders/src/lib.rs b/vulkano-shaders/src/lib.rs index 4fca5792..c8611b40 100644 --- a/vulkano-shaders/src/lib.rs +++ b/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 diff --git a/vulkano-win/src/lib.rs b/vulkano-win/src/lib.rs index 48651251..ca9f11f1 100644 --- a/vulkano-win/src/lib.rs +++ b/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_")] diff --git a/vulkano/src/lib.rs b/vulkano/src/lib.rs index 4e0e5214..f28de2f4 100644 --- a/vulkano/src/lib.rs +++ b/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. -//! It must be loaded before you can do anything with Vulkan. +//! | Feature | Description | +//! |----------------------|-------------------------------------------------------------------------------| +//! | `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 -//! an initialised Vulkan library. This is the first Vulkan object that you create. +//! # Starting off with Vulkano //! -//! - The [`PhysicalDevice`](crate::device::physical::PhysicalDevice) object represents a -//! Vulkan-capable device that is available on the system (eg. a graphics card, a software -//! implementation, etc.). Physical devices can be enumerated from an instance with -//! [`Instance::enumerate_physical_devices`](crate::instance::Instance::enumerate_physical_devices). +//! The steps for using Vulkan through Vulkano are in principle not any different from using +//! the raw Vulkan API, but the details may be different for the sake of idiomaticity, safety +//! and convenience. //! -//! - Once you have chosen a physical device to use, you can create a -//! [`Device`](crate::device::Device) object from it. The `Device` is the most important -//! 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. +//! 1. Create a [`VulkanLibrary`]. This represents a Vulkan library on the system, which must be +//! loaded before you can do anything with Vulkan. //! -//! - [*Buffers*](crate::buffer) and [*images*](crate::image) can be used to store data on -//! memory accessible by the GPU (or more generally by the Vulkan implementation). Buffers are -//! usually used to store information about vertices, lights, etc. or arbitrary data, while -//! images are used to store textures or multi-dimensional data. +//! 2. Create an [`Instance`]. This is the API entry point, and represents an initialised Vulkan +//! library. //! -//! - In order to show something on the screen, you need a -//! [`Surface` and a `Swapchain`](crate::swapchain). -//! A `Swapchain` contains special `Image`s that correspond to the content of the window or the -//! monitor. When you *present* a swapchain, the content of one of these special images is shown -//! on the screen. +//! 3. If you intend to show graphics to the user on a window or a screen, create a [`Surface`]. +//! A `Surface` is created from a window identifier or handle, that is specific to the display or +//! windowing system being used. The [`vulkano-win`] crate, which is part of the Vulkano +//! project, can make this step easier. //! -//! - For graphical operations, [`RenderPass`es and `Framebuffer`s](crate::render_pass) -//! describe which images the device must draw upon. +//! 4. [Enumerate the physical devices] that are available on the `Instance`, and choose one that +//! 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 -//! [pipeline object](crate::pipeline) that describes the operation you want. These objects are usually -//! created during your program's initialization. `Shader`s are programs that the GPU will -//! execute as part of a pipeline. [*Descriptor sets*](crate::descriptor_set) can be used to access -//! the content of buffers or images from within shaders. +//! 6. Create a [`Device`] and accompanying [`Queue`]s from the selected `PhysicalDevice`. +//! The `Device` is the most important object of Vulkan, and you need one to create almost +//! every other object. `Queue`s are created together with the `Device`, and are used to submit +//! work to the device to make it do something. //! -//! - To tell the GPU to do something, you must create a -//! [*command buffer*](crate::command_buffer). A command buffer contains a list of commands -//! that the GPU must perform. This can include copies between buffers and images, compute -//! operations, or graphics operations. For the work to start, the command buffer must then be -//! submitted to a [`Queue`](crate::device::Queue), which is obtained when you create the -//! `Device`. +//! 7. If you created a `Surface` earlier, create a [`Swapchain`]. This object contains special +//! images that correspond to the contents of the surface. Whenever you want to +//! change the contents (show something new to the user), you must first *acquire* one of these +//! images from the swapchain, fill it with the new contents (by rendering, copying or any +//! other means), and then *present* it back to the swapchain. +//! 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 -//! GPU will return an object that implements [the `GpuFuture` trait](crate::sync::GpuFuture). -//! `GpuFuture`s allow you to chain multiple submissions together and are essential to performing -//! multiple operations on multiple different GPU queues. +//! 8. Record a [*command buffer*](crate::command_buffer), containing commands that the device must +//! execute. Then build the command buffer and submit it to a `Queue`. //! +//! 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(