Module vulkano::device

source ·
Expand description

Communication channel with a physical device.

The Device is one of the most important objects of Vulkan. Creating a Device is required before you can create buffers, textures, shaders, etc.

Basic example:

use vulkano::{
    device::{physical::PhysicalDevice, Device, DeviceCreateInfo, DeviceExtensions, Features, QueueCreateInfo},
    instance::{Instance, InstanceExtensions},
    Version, VulkanLibrary,
};

// Creating the instance. See the documentation of the `instance` module.
let library = VulkanLibrary::new()
    .unwrap_or_else(|err| panic!("Couldn't load Vulkan library: {:?}", err));
let instance = Instance::new(library, Default::default())
    .unwrap_or_else(|err| panic!("Couldn't create instance: {:?}", err));

// We just choose the first physical device. In a real application you would choose depending
// on the capabilities of the physical device and the user's preferences.
let physical_device = instance
    .enumerate_physical_devices()
    .unwrap_or_else(|err| panic!("Couldn't enumerate physical devices: {:?}", err))
    .next().expect("No physical device");

// Here is the device-creating code.
let device = {
    let features = Features::empty();
    let extensions = DeviceExtensions::empty();

    match Device::new(
        physical_device,
        DeviceCreateInfo {
            queue_create_infos: vec![QueueCreateInfo {
                queue_family_index: 0,
                ..Default::default()
            }],
            enabled_extensions: extensions,
            enabled_features: features,
            ..Default::default()
        },
    ) {
        Ok(d) => d,
        Err(err) => panic!("Couldn't build device: {:?}", err)
    }
};

Features and extensions

Two of the parameters that you pass to Device::new are the list of the features and the list of extensions to enable on the newly-created device.

Note: Device extensions are the same as instance extensions, except for the device. Features are similar to extensions, except that they are part of the core Vulkan specifications instead of being separate documents.

Some Vulkan capabilities, such as swapchains (that allow you to render on the screen) or geometry shaders for example, require that you enable a certain feature or extension when you create the device. Contrary to OpenGL, you can’t use the functions provided by a feature or an extension if you didn’t explicitly enable it when creating the device.

Not all physical devices support all possible features and extensions. For example mobile devices tend to not support geometry shaders, because their hardware is not capable of it. You can query what is supported with respectively PhysicalDevice::supported_features and DeviceExtensions::supported_by_device.

Note: The fact that you need to manually enable features at initialization also means that you don’t need to worry about a capability not being supported later on in your code.

Queues

Each physical device proposes one or more queues that are divided in queue families. A queue is a thread of execution to which you can submit commands that the GPU will execute.

Note: You can think of a queue like a CPU thread. Each queue executes its commands one after the other, and queues run concurrently. A GPU behaves similarly to the hyper-threading technology, in the sense that queues will only run partially in parallel.

The Vulkan API requires that you specify the list of queues that you are going to use at the same time as when you create the device. This is done in vulkano by passing an iterator where each element is a tuple containing a queue family and a number between 0.0 and 1.0 indicating the priority of execution of the queue relative to the others.

TODO: write better doc here

The Device::new function returns the newly-created device, but also the list of queues.

Extended example

TODO: write

Modules

Structs

Traits