Crate vulkano

Expand description

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.

Create a VulkanLibrary. This represents a Vulkan library on the system, which must be loaded before you can do anything with Vulkan.
Create an Instance. This is the API entry point, and represents an initialised Vulkan library.
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.
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.
Create a Device and accompanying Queues from the selected PhysicalDevice. The Device is the most important object of Vulkan, and you need one to create almost every other object. Queues are created together with the Device, and are used to submit work to the device to make it do something.
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.
Record a 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 shaders, 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`.

Re-exports§

pub use library::LoadingError;
pub use library::VulkanLibrary;
pub use half;

Modules§

acceleration_structure: An opaque data structure that is used to accelerate spatial queries on geometry data.
buffer: Location in memory that contains data.
command_buffer: Recording commands to execute on the device.
deferred: Operations on the host that can be deferred.
descriptor_set: Bindings between shaders and the resources they access.
device: Communication channel with a physical device.
display: Control and use of display devices (e.g. monitors).
format: All the formats supported by Vulkan.
image: Image storage (1D, 2D, 3D, arrays, etc.) and image views.
instance: API entry point.
library: Vulkan library loading system.
memory: Device memory allocation and memory pools.
padded: A newtype wrapper for enforcing correct alignment for external types.
pipeline: Describes a processing operation that will execute on the Vulkan device.
query: Gather information about rendering, held in query pools.
range_set
render_pass: Description of the steps of the rendering process, and the images used as input or output.
shader: A program that is run on the device.
swapchain: Link between Vulkan and a window and/or the screen.
sync: Synchronization on the GPU.

Macros§

impl_vertexDeprecated: Implements the Vertex trait on a struct.
impl_vertex_member
ordered_passes_renderpass: Builds a RenderPass object whose template parameter is of indeterminate type.
single_pass_renderpass: Builds a RenderPass object whose template parameter is of indeterminate type.
statically_linked_vulkan_loader: Expression that returns a loader that assumes that Vulkan is linked to the executable you’re compiling.
type_for_format: Converts a format enum identifier to a standard Rust type that is suitable for representing the format in a buffer or image.

Structs§

ExtensionProperties: Properties of an extension in the loader or a physical device.
NonExhaustive: A helper type for non-exhaustive structs.
Packed24_8: Holds 24 bits in the least significant bits of memory, and 8 bytes in the most significant bits of that memory, occupying a single u32 in total.
RequiresAllOf: Used in errors to indicate a set of requirements that all need to be available/enabled to allow a given operation.
RequiresOneOf: Used in errors to indicate a set of alternatives that needs to be available/enabled to allow a given operation.
ValidationError: The arguments or other context of a call to a Vulkan function were not valid.
Version: Represents an API version of Vulkan.

Enums§

Requires: Something that needs to be supported or enabled to allow a particular operation.
Validated: A wrapper for error types of functions that can return validation errors.
VulkanError: An enumeration of runtime errors that can be returned by Vulkan.

Traits§

Handle
SafeDeref: Alternative to the Deref trait. Contrary to Deref, must always return the same object.
VulkanObject: Gives access to the internal identifier of an object.

Type Aliases§

DeviceAddress: Represents an address (pointer) on a Vulkan device. https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VkDeviceAddress.html
DeviceSize: Represents memory size and offset values on a Vulkan device. Analogous to the Rust usize type on the host. https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VkDeviceSize.html
NonNullDeviceAddress: A DeviceAddress that is known not to equal zero.
NonZeroDeviceSize: A DeviceSize that is known not to equal zero.

Crate vulkanoCopy item path