Module vulkano::device

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::Device;
use vulkano::device::DeviceExtensions;
use vulkano::device::Features;
use vulkano::instance::Instance;
use vulkano::instance::InstanceExtensions;
use vulkano::instance::PhysicalDevice;

// Creating the instance. See the documentation of the `instance` module.
let instance = match Instance::new(None, &InstanceExtensions::none(), None) {
    Ok(i) => i,
    Err(err) => panic!("Couldn't build 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 = PhysicalDevice::enumerate(&instance).next().expect("No physical device");

// Here is the device-creating code.
let device = {
    let queue_family = physical_device.queue_families().next().unwrap();
    let features = Features::none();
    let ext = DeviceExtensions::none();

    match Device::new(physical_device, &features, &ext, Some((queue_family, 1.0))) {
        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

Structs

Device	Represents a Vulkan context.
DeviceExtensions	List of extensions that are enabled or available.
Features	Represents all the features that are available on a physical device or enabled on a logical device.
Queue	Represents a queue where commands can be submitted.
QueuesIter	Iterator that returns the queues produced when creating a device.
RawDeviceExtensions	Set of extensions, not restricted to those vulkano knows about.

Enums

DeviceCreationError

Error that can be returned when creating a device.

Traits

DeviceOwned

Implemented on objects that belong to a Vulkan device.