Crate vulkano

source ·
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.

  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.

  5. 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.

  6. 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.

  7. 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:

  • 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

FeatureDescription
macrosInclude reexports from vulkano-macros. Enabled by default.
document_uncheckedInclude _unchecked functions in the generated documentation.
serdeEnables (de)serialization of certain types using serde.

Re-exports

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

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