Module vulkano::instance

API entry point.

The first thing to do before you start using Vulkan is to create an Instance object.

For example:

use vulkano::instance::Instance;
use vulkano::instance::InstanceExtensions;

let instance = match Instance::new(None, &InstanceExtensions::none(), None) {
    Ok(i) => i,
    Err(err) => panic!("Couldn't build 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::instance::PhysicalDevice;

for physical_device in PhysicalDevice::enumerate(&instance) {
    println!("Available device: {}", physical_device.name());
}

Extensions

Notice the second parameter of Instance::new(). It is an InstanceExtensions struct that contains a list of extensions that must be enabled on the newly-created instance. Trying to enable an extension that is not supported by the system will result in an error.

Contrary to OpenGL, it is not possible to use the features of an extension if it was not explicitly enabled.

Extensions are especially important to take into account if you want to render images on the screen, as the only way to do so is to use the VK_KHR_surface extension. More information about this in the swapchain module.

For example, here is how we create an instance with the VK_KHR_surface and VK_KHR_android_surface extensions enabled, which will allow us to render images to an Android screen. You can compile and run this code on any system, but it is highly unlikely to succeed on anything else than an Android-running device.

use vulkano::instance::Instance;
use vulkano::instance::InstanceExtensions;

let extensions = InstanceExtensions {
    khr_surface: true,
    khr_android_surface: true,
    .. InstanceExtensions::none()
};

let instance = match Instance::new(None, &extensions, None) {
    Ok(i) => i,
    Err(err) => panic!("Couldn't build instance: {:?}", err)
};

Application info

When you create an instance, you have the possibility to pass an ApplicationInfo struct as the first parameter. This struct contains various information about your application, most notably its name and engine.

Passing such a structure allows for example the driver to let the user configure the driver's behavior for your application alone through a control panel.

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

// Builds an `ApplicationInfo` by looking at the content of the `Cargo.toml` file at
// compile-time.
let app_infos = app_info_from_cargo_toml!();

let _instance = Instance::new(Some(&app_infos), &InstanceExtensions::none(), None).unwrap();

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 PhysicalDevice::enumerate() (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.

Re-exports

pub use self::loader::LoadingError;

Modules

debug	Debug callback called by intermediate layers or by the driver.
loader	Vulkan implementation loading system.

Structs

ApplicationInfo	Information that can be given to the Vulkan driver so that it can identify your application.
Instance	An instance of a Vulkan context. This is the main object that should be created by an application before everything else.
InstanceExtensions	List of extensions that are enabled or available.
LayerProperties	Properties of a layer.
LayersIterator	Iterator that produces the list of layers that are available.
Limits	Limits of a physical device.
MemoryHeap	Represents a memory heap in a physical device.
MemoryHeapsIter	Iterator for all the memory heaps available on a physical device.
MemoryType	Represents a memory type in a physical device.
MemoryTypesIter	Iterator for all the memory types available on a physical device.
PhysicalDevice	Represents one of the available devices on this machine.
PhysicalDevicesIter	Iterator for all the physical devices available on hardware.
QueueFamiliesIter	Iterator for all the queue families available on a physical device.
QueueFamily	Represents a queue family in a physical device.
RawInstanceExtensions	Set of extensions, not restricted to those vulkano knows about.
Version	Represents an API version of Vulkan.

Enums

InstanceCreationError	Error that can happen when creating an instance.
LayersListError	Error that can happen when loading the list of layers.
PhysicalDeviceType	Type of a physical device.

Functions

layers_list

Queries the list of layers that are available when creating an instance.