Module vulkano::instance

Expand description

API entry point.

The first thing to do after loading the Vulkan library is to create an Instance object.

For example:

use vulkano::{
    instance::{Instance, InstanceExtensions},
    Version, VulkanLibrary,
};

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));

Creating an instance initializes everything and allows you to enumerate physical devices, ie. all the Vulkan implementations that are available on the system.

use vulkano::device::physical::PhysicalDevice;

for physical_device in instance.enumerate_physical_devices().unwrap() {
    println!("Available device: {}", physical_device.properties().device_name);
}

Enumerating physical devices and creating a device

After you have created an instance, the next step is usually to enumerate the physical devices that are available on the system with Instance::enumerate_physical_devices() (see above).

When choosing which physical device to use, keep in mind that physical devices may or may not be able to draw to a certain surface (ie. to a window or a monitor), or may even not be able to draw at all. See the swapchain module for more information about surfaces.

Once you have chosen a physical device, you can create a Device object from it. See the device module for more info.

Portability subset devices and the `enumerate_portability` flag

Certain devices, currently those on MacOS and iOS systems, do not fully conform to the Vulkan specification. They are usable as normal devices, but they do not implement everything that is required; some mandatory parts of Vulkan are missing. These are known as “portability subset” devices.

A portability subset device will advertise support for the khr_portability_subset device extension. This extension must always be enabled when it is supported, and Vulkano will automatically enable it when creating the device. When it is enabled, some parts of Vulkan that are available in standard Vulkan will not be available by default, but they can be used by enabling corresponding features when creating the device, if the device supports them.

Because these devices are non-conformant, Vulkan programs that rely on full compliance may not work (crash or have validation errors) when run on them, if they happen to use a part of Vulkan that is missing from the non-conformant device. Therefore, Vulkan hides them from the user by default when calling enumerate_physical_devices on the instance. If there are no conformant devices on the system, Instance::new will return an IncompatibleDriver error.

In order to enumerate portability subset devices, you must set the InstanceCreateInfo::enumerate_portability flag when creating the instance. However, if you do this, your program must be prepared to handle the non-conformant aspects of these devices, and must enable the appropriate features when creating the Device if you intend to use them.