[][src]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.