Struct vulkano::instance::Instance

pub struct Instance { /* fields omitted */ }

An instance of a Vulkan context. This is the main object that should be created by an application before everything else.

See the documentation of the instance module for an introduction about Vulkan instances.

Extensions and application infos

Please check the documentation of the instance module.

Layers

When creating an Instance, you have the possibility to pass a list of layers that will be activated on the newly-created instance. The list of available layers can be retrieved by calling the layers_list function.

A layer is a component that will hook and potentially modify the Vulkan function calls. For example, activating a layer could add a frames-per-second counter on the screen, or it could send information to a debugger that will debug your application.

Note: From an application's point of view, layers "just exist". In practice, on Windows and Linux layers can be installed by third party installers or by package managers and can also be activated by setting the value of the VK_INSTANCE_LAYERS environment variable before starting the program. See the documentation of the official Vulkan loader for these platforms.

Note: In practice, the most common use of layers right now is for debugging purposes. To do so, you are encouraged to set the VK_INSTANCE_LAYERS environment variable on Windows or Linux instead of modifying the source code of your program. For example: export VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_api_dump on Linux if you installed the Vulkan SDK will print the list of raw Vulkan function calls.

Example

// For the sake of the example, we activate all the layers that
// contain the word "foo" in their description.
let layers: Vec<_> = instance::layers_list()?
    .filter(|l| l.description().contains("foo"))
    .collect();

let layer_names = layers.iter()
    .map(|l| l.name());

let instance = Instance::new(None, &InstanceExtensions::none(), layer_names)?;

Methods

impl Instance

pub fn new<'a, L, Ext>(
    app_infos: Option<&ApplicationInfo>,
    extensions: Ext,
    layers: L
) -> Result<Arc<Instance>, InstanceCreationError> where
    L: IntoIterator<Item = &'a str>,
    Ext: Into<RawInstanceExtensions>, 

Initializes a new instance of Vulkan.

See the documentation of Instance or of the instance module for more details.

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

Panic

• Panics if the version numbers passed in ApplicationInfo are too large can't be converted into a Vulkan version number.
• Panics if the application name or engine name contain a null character.

pub fn with_loader<'a, L, Ext>(
    loader: FunctionPointers<Box<dyn Loader + Send + Sync>>,
    app_infos: Option<&ApplicationInfo>,
    extensions: Ext,
    layers: L
) -> Result<Arc<Instance>, InstanceCreationError> where
    L: IntoIterator<Item = &'a str>,
    Ext: Into<RawInstanceExtensions>, 

Same as new, but allows specifying a loader where to load Vulkan from.

pub fn loaded_extensions(&self) -> &InstanceExtensions

Returns the list of extensions that have been loaded.

This list is equal to what was passed to Instance::new().

Example

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

let extensions = InstanceExtensions::supported_by_core().unwrap();
let instance = Instance::new(None, &extensions, None).unwrap();
assert_eq!(instance.loaded_extensions(), &extensions);

Trait Implementations

impl VulkanObject for Instance

type Object = Instance

The type of the object.

const TYPE: DebugReportObjectTypeEXT

The DebugReportObjectTypeEXT of the internal Vulkan handle.

fn internal_object(&self) -> Instance

Returns a reference to the object.

impl Drop for Instance

fn drop(&mut self)

Executes the destructor for this type.

impl Debug for Instance

fn fmt(&self, fmt: &mut Formatter) -> Result<(), Error>

Formats the value using the given formatter.

impl UnwindSafe for Instance

impl RefUnwindSafe for Instance