Module vulkano::instance

source ·
Expand description

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 callback called by intermediate layers or by the driver.
Vulkan implementation loading system.

Structs

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

Enums

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

Functions

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