| // Copyright (c) 2016 The vulkano developers | |
| // Licensed under the Apache License, Version 2.0 | |
| // <LICENSE-APACHE or | |
| // https://www.apache.org/licenses/LICENSE-2.0> or the MIT | |
| // license <LICENSE-MIT or https://opensource.org/licenses/MIT>, | |
| // at your option. All files in the project carrying such | |
| // notice may not be copied, modified, or distributed except | |
| // according to those terms. | |
| #![doc(html_logo_url = "https://raw.githubusercontent.com/vulkano-rs/vulkano/master/logo.png")] | |
| //! Safe and rich Rust wrapper around the Vulkan API. | |
| //! | |
| //! # Starting off with Vulkano | |
| //! | |
| //! 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. | |
| //! | |
| //! 1. Create a [`VulkanLibrary`]. This represents a Vulkan library on the system, which must be | |
| //! loaded before you can do anything with Vulkan. | |
| //! | |
| //! 2. Create an [`Instance`]. This is the API entry point, and represents an initialised Vulkan | |
| //! library. | |
| //! | |
| //! 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. | |
| //! | |
| //! 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. | |
| //! | |
| //! 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. | |
| //! | |
| //! 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. | |
| //! | |
| //! 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`. | |
| //! | |
| //! # Cargo features | |
| //! | |
| //! | Feature | Description | | |
| //! |----------------------|---------------------------------------------------------------|| | |
| //! | `macros` | Include reexports from [`vulkano-macros`]. Enabled by default. | | |
| //! | `document_unchecked` | Include `_unchecked` functions in the generated documentation. | | |
| //! | `serde` | Enables (de)serialization of certain types using [`serde`]. | | |
| //! | |
| //! [`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 | |
| //! [`vulkano-macros`]: vulkano_macros | |
| //! [`serde`]: https://crates.io/crates/serde | |
| //#![warn(missing_docs)] // TODO: activate | |
| #![warn( | |
| rust_2018_idioms, | |
| rust_2021_compatibility, | |
| clippy::trivially_copy_pass_by_ref | |
| )] | |
| // These lints are a bit too pedantic, so they're disabled here. | |
| #![allow( | |
| clippy::collapsible_else_if, | |
| clippy::collapsible_if, | |
| clippy::derivable_impls, // TODO: remove | |
| clippy::large_enum_variant, | |
| clippy::len_without_is_empty, | |
| clippy::missing_safety_doc, // TODO: remove | |
| clippy::module_inception, | |
| clippy::mutable_key_type, | |
| clippy::needless_borrowed_reference, | |
| clippy::new_without_default, | |
| clippy::nonminimal_bool, | |
| clippy::op_ref, // Seems to be bugged, the fixed code triggers a compile error | |
| clippy::result_large_err, | |
| clippy::too_many_arguments, | |
| clippy::type_complexity, | |
| clippy::vec_box, | |
| clippy::wrong_self_convention | |
| )] | |
| pub use ash::vk::Handle; | |
| pub use half; | |
| pub use library::{LoadingError, VulkanLibrary}; | |
| use std::{ | |
| error::Error, | |
| fmt::{Display, Error as FmtError, Formatter}, | |
| num::NonZeroU64, | |
| ops::Deref, | |
| sync::Arc, | |
| }; | |
| pub use {extensions::ExtensionProperties, version::Version}; | |
| #[macro_use] | |
| mod tests; | |
| #[macro_use] | |
| mod extensions; | |
| pub mod buffer; | |
| pub mod command_buffer; | |
| pub mod descriptor_set; | |
| pub mod device; | |
| pub mod format; | |
| mod version; | |
| #[macro_use] | |
| pub mod render_pass; | |
| mod cache; | |
| mod fns; | |
| pub mod image; | |
| pub mod instance; | |
| pub mod library; | |
| mod macros; | |
| pub mod memory; | |
| pub mod padded; | |
| pub mod pipeline; | |
| pub mod query; | |
| mod range_map; | |
| pub mod range_set; | |
| pub mod sampler; | |
| pub mod shader; | |
| pub mod swapchain; | |
| pub mod sync; | |
| /// Represents memory size and offset values on a Vulkan device. | |
| /// Analogous to the Rust `usize` type on the host. | |
| pub use ash::vk::DeviceSize; | |
| /// A [`DeviceSize`] that is known not to equal zero. | |
| pub type NonZeroDeviceSize = NonZeroU64; | |
| // Allow refering to crate by its name to work around limitations of proc-macros | |
| // in doctests. | |
| // See https://github.com/rust-lang/cargo/issues/9886 | |
| // and https://github.com/bkchr/proc-macro-crate/issues/10 | |
| #[allow(unused_extern_crates)] | |
| extern crate self as vulkano; | |
| /// Alternative to the `Deref` trait. Contrary to `Deref`, must always return the same object. | |
| pub unsafe trait SafeDeref: Deref {} | |
| unsafe impl<'a, T: ?Sized> SafeDeref for &'a T {} | |
| unsafe impl<T: ?Sized> SafeDeref for Arc<T> {} | |
| unsafe impl<T: ?Sized> SafeDeref for Box<T> {} | |
| /// Gives access to the internal identifier of an object. | |
| pub unsafe trait VulkanObject { | |
| /// The type of the object. | |
| type Handle: ash::vk::Handle; | |
| /// Returns the raw Vulkan handle of the object. | |
| fn handle(&self) -> Self::Handle; | |
| } | |
| unsafe impl<T, U> VulkanObject for T | |
| where | |
| T: SafeDeref<Target = U>, | |
| U: VulkanObject + ?Sized, | |
| { | |
| type Handle = U::Handle; | |
| #[inline] | |
| fn handle(&self) -> Self::Handle { | |
| (**self).handle() | |
| } | |
| } | |
| /// Error type returned by most Vulkan functions. | |
| #[derive(Copy, Clone, Debug, PartialEq, Eq)] | |
| pub enum OomError { | |
| /// There is no memory available on the host (ie. the CPU, RAM, etc.). | |
| OutOfHostMemory, | |
| /// There is no memory available on the device (ie. video memory). | |
| OutOfDeviceMemory, | |
| } | |
| impl Error for OomError {} | |
| impl Display for OomError { | |
| fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), FmtError> { | |
| write!( | |
| f, | |
| "{}", | |
| match self { | |
| OomError::OutOfHostMemory => "no memory available on the host", | |
| OomError::OutOfDeviceMemory => "no memory available on the graphical device", | |
| } | |
| ) | |
| } | |
| } | |
| impl From<VulkanError> for OomError { | |
| fn from(err: VulkanError) -> OomError { | |
| match err { | |
| VulkanError::OutOfHostMemory => OomError::OutOfHostMemory, | |
| VulkanError::OutOfDeviceMemory => OomError::OutOfDeviceMemory, | |
| _ => panic!("unexpected error: {:?}", err), | |
| } | |
| } | |
| } | |
| // Generated by build.rs | |
| include!(concat!(env!("OUT_DIR"), "/errors.rs")); | |
| impl Error for VulkanError {} | |
| impl Display for VulkanError { | |
| fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), FmtError> { | |
| write!( | |
| f, | |
| "{}", | |
| match self { | |
| VulkanError::OutOfHostMemory => "a host memory allocation has failed", | |
| VulkanError::OutOfDeviceMemory => "a device memory allocation has failed", | |
| VulkanError::InitializationFailed => { | |
| "initialization of an object could not be completed for \ | |
| implementation-specific reasons" | |
| } | |
| VulkanError::DeviceLost => "the logical or physical device has been lost", | |
| VulkanError::MemoryMapFailed => "mapping of a memory object has failed", | |
| VulkanError::LayerNotPresent => { | |
| "a requested layer is not present or could not be loaded" | |
| } | |
| VulkanError::ExtensionNotPresent => "a requested extension is not supported", | |
| VulkanError::FeatureNotPresent => "a requested feature is not supported", | |
| VulkanError::IncompatibleDriver => { | |
| "the requested version of Vulkan is not supported by the driver or is \ | |
| otherwise incompatible for implementation-specific reasons" | |
| } | |
| VulkanError::TooManyObjects => { | |
| "too many objects of the type have already been created" | |
| } | |
| VulkanError::FormatNotSupported => { | |
| "a requested format is not supported on this device" | |
| } | |
| VulkanError::FragmentedPool => { | |
| "a pool allocation has failed due to fragmentation of the pool's memory" | |
| } | |
| VulkanError::Unknown => { | |
| "an unknown error has occurred; either the application has provided invalid \ | |
| input, or an implementation failure has occurred" | |
| } | |
| VulkanError::OutOfPoolMemory => "a pool memory allocation has failed", | |
| VulkanError::InvalidExternalHandle => { | |
| "an external handle is not a valid handle of the specified type" | |
| } | |
| VulkanError::Fragmentation => { | |
| "a descriptor pool creation has failed due to fragmentation" | |
| } | |
| VulkanError::InvalidOpaqueCaptureAddress => { | |
| "a buffer creation or memory allocation failed because the requested address \ | |
| is not available. A shader group handle assignment failed because the \ | |
| requested shader group handle information is no longer valid" | |
| } | |
| VulkanError::IncompatibleDisplay => { | |
| "the display used by a swapchain does not use the same presentable image \ | |
| layout, or is incompatible in a way that prevents sharing an image" | |
| } | |
| VulkanError::NotPermitted => "a requested operation was not permitted", | |
| VulkanError::SurfaceLost => "a surface is no longer available", | |
| VulkanError::NativeWindowInUse => { | |
| "the requested window is already in use by Vulkan or another API in a manner \ | |
| which prevents it from being used again" | |
| } | |
| VulkanError::OutOfDate => { | |
| "a surface has changed in such a way that it is no longer compatible with the \ | |
| swapchain, and further presentation requests using the swapchain will fail" | |
| } | |
| VulkanError::ValidationFailed => "validation failed", | |
| VulkanError::FullScreenExclusiveModeLost => { | |
| "an operation on a swapchain created with application controlled full-screen \ | |
| access failed as it did not have exclusive full-screen access" | |
| } | |
| VulkanError::InvalidDrmFormatModifierPlaneLayout => { | |
| "the requested DRM format modifier plane layout is invalid" | |
| } | |
| VulkanError::InvalidShader => "one or more shaders failed to compile or link", | |
| VulkanError::ImageUsageNotSupported => | |
| "the requested `ImageUsage` are not supported", | |
| VulkanError::VideoPictureLayoutNotSupported => | |
| "the requested video picture layout is not supported", | |
| VulkanError::VideoProfileOperationNotSupported => | |
| "a video profile operation specified via \ | |
| `VideoProfileInfo::video_codec_operation` is not supported", | |
| VulkanError::VideoProfileFormatNotSupported => | |
| "format parameters in a requested `VideoProfileInfo` chain are not supported", | |
| VulkanError::VideoProfileCodecNotSupported => | |
| "codec-specific parameters in a requested `VideoProfileInfo` chain are not \ | |
| supported", | |
| VulkanError::VideoStdVersionNotSupported => | |
| "the specified video Std header version is not supported", | |
| VulkanError::CompressionExhausted => | |
| "an image creation failed because internal resources required for compression \ | |
| are exhausted", | |
| VulkanError::Unnamed(result) => | |
| return write!(f, "unnamed error, VkResult value {}", result.as_raw()), | |
| } | |
| ) | |
| } | |
| } | |
| /// Used in errors to indicate a set of alternatives that needs to be available/enabled to allow | |
| /// a given operation. | |
| #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] | |
| pub struct RequiresOneOf { | |
| /// A minimum Vulkan API version that would allow the operation. | |
| pub api_version: Option<Version>, | |
| /// Enabled features that would allow the operation. | |
| pub features: &'static [&'static str], | |
| /// Available/enabled device extensions that would allow the operation. | |
| pub device_extensions: &'static [&'static str], | |
| /// Available/enabled instance extensions that would allow the operation. | |
| pub instance_extensions: &'static [&'static str], | |
| } | |
| impl RequiresOneOf { | |
| /// Returns whether there is more than one possible requirement. | |
| pub fn len(&self) -> usize { | |
| self.api_version.map_or(0, |_| 1) | |
| + self.features.len() | |
| + self.device_extensions.len() | |
| + self.instance_extensions.len() | |
| } | |
| } | |
| impl Display for RequiresOneOf { | |
| fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), FmtError> { | |
| let mut members_written = 0; | |
| if let Some(version) = self.api_version { | |
| write!(f, "Vulkan API version {}.{}", version.major, version.minor)?; | |
| members_written += 1; | |
| } | |
| if let Some((last, rest)) = self.features.split_last() { | |
| if members_written != 0 { | |
| write!(f, ", ")?; | |
| } | |
| members_written += 1; | |
| if rest.is_empty() { | |
| write!(f, "feature {}", last)?; | |
| } else { | |
| write!(f, "features ")?; | |
| for feature in rest { | |
| write!(f, "{}, ", feature)?; | |
| } | |
| write!(f, "{}", last)?; | |
| } | |
| } | |
| if let Some((last, rest)) = self.device_extensions.split_last() { | |
| if members_written != 0 { | |
| write!(f, ", ")?; | |
| } | |
| members_written += 1; | |
| if rest.is_empty() { | |
| write!(f, "device extension {}", last)?; | |
| } else { | |
| write!(f, "device extensions ")?; | |
| for feature in rest { | |
| write!(f, "{}, ", feature)?; | |
| } | |
| write!(f, "{}", last)?; | |
| } | |
| } | |
| if let Some((last, rest)) = self.instance_extensions.split_last() { | |
| if members_written != 0 { | |
| write!(f, ", ")?; | |
| } | |
| if rest.is_empty() { | |
| write!(f, "instance extension {}", last)?; | |
| } else { | |
| write!(f, "instance extensions ")?; | |
| for feature in rest { | |
| write!(f, "{}, ", feature)?; | |
| } | |
| write!(f, "{}", last)?; | |
| } | |
| } | |
| Ok(()) | |
| } | |
| } | |
| #[derive(Clone, Copy, Debug)] | |
| pub(crate) struct RequirementNotMet { | |
| pub(crate) required_for: &'static str, | |
| pub(crate) requires_one_of: RequiresOneOf, | |
| } | |
| /// A helper type for non-exhaustive structs. | |
| /// | |
| /// This type cannot be constructed outside Vulkano. Structures with a field of this type can only | |
| /// be constructed by calling a constructor function or `Default::default()`. The effect is similar | |
| /// to the standard Rust `#[non_exhaustive]` attribute, except that it does not prevent update | |
| /// syntax from being used. | |
| #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] // add traits as needed | |
| pub struct NonExhaustive(pub(crate) ()); |