Struct vulkano::instance::Instance

source ·
pub struct Instance { /* private fields */ }
Expand description

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

Application and engine info

When you create an instance, you have the possibility to set information about your application and its engine.

Providing this information 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, InstanceCreateInfo, InstanceExtensions},
    Version, VulkanLibrary,
};

let library = VulkanLibrary::new().unwrap();
let _instance = Instance::new(
    library,
    InstanceCreateInfo::application_from_cargo_toml(),
).unwrap();

API versions

Both an Instance and a Device have a highest version of the Vulkan API that they support. This places a limit on what Vulkan functions and features are available to use when used on a particular instance or device. It is possible for the instance and the device to support different versions. The supported version for an instance can be queried before creation with VulkanLibrary::api_version, while for a device it can be retrieved with PhysicalDevice::api_version.

When creating an Instance, you have to specify a maximum API version that you will use. This restricts the API version that is available for the instance and any devices created from it. For example, if both instance and device potentially support Vulkan 1.2, but you specify 1.1 as the maximum API version when creating the Instance, then you can only use Vulkan 1.1 functions, even though they could theoretically support a higher version. You can think of it as a promise never to use any functionality from a higher version.

The maximum API version is not a minimum, so it is possible to set it to a higher version than what the instance or device inherently support. The final API version that you are able to use on an instance or device is the lower of the supported API version and the chosen maximum API version of the Instance.

Due to a quirk in how the Vulkan 1.0 specification was written, if the instance only supports Vulkan 1.0, then it is not possible to specify a maximum API version higher than 1.0. Trying to create an Instance will return an IncompatibleDriver error. Consequently, it is not possible to use a higher device API version with an instance that only supports 1.0.

Extensions

When creating an Instance, you must provide 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, InstanceCreateInfo, InstanceExtensions},
    Version, VulkanLibrary,
};

let library = VulkanLibrary::new()
    .unwrap_or_else(|err| panic!("Couldn't load Vulkan library: {:?}", err));

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

let instance = Instance::new(
    library,
    InstanceCreateInfo {
        enabled_extensions: extensions,
        ..Default::default()
    },
)
.unwrap_or_else(|err| panic!("Couldn't create instance: {:?}", err));

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 layer_properties method of VulkanLibrary.

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.

Examples

let library = VulkanLibrary::new()?;

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

let instance = Instance::new(
    library,
    InstanceCreateInfo {
        enabled_layers: layers.iter().map(|l| l.name().to_owned()).collect(),
        ..Default::default()
    },
)?;

Implementations§

source§

impl Instance

source

pub fn new( library: Arc<VulkanLibrary>, create_info: InstanceCreateInfo ) -> Result<Arc<Instance>, Validated<VulkanError>>

Creates a new Instance.

source

pub unsafe fn from_handle( library: Arc<VulkanLibrary>, handle: Instance, create_info: InstanceCreateInfo ) -> Arc<Self>

Creates a new Instance from a raw object handle.

Safety
  • handle must be a valid Vulkan object handle created from library.
  • create_info must match the info used to create the object.
source

pub fn library(&self) -> &Arc<VulkanLibrary>

Returns the Vulkan library used to create this instance.

source

pub fn flags(&self) -> InstanceCreateFlags

Returns the flags that the instance was created with.

source

pub fn api_version(&self) -> Version

Returns the Vulkan version supported by the instance.

This is the lower of the driver’s supported version and max_api_version.

source

pub fn max_api_version(&self) -> Version

Returns the maximum Vulkan version that was specified when creating the instance.

source

pub fn fns(&self) -> &InstanceFunctions

Returns pointers to the raw Vulkan functions of the instance.

source

pub fn enabled_extensions(&self) -> &InstanceExtensions

Returns the extensions that have been enabled on the instance.

This includes both the extensions specified in InstanceCreateInfo::enabled_extensions, and any extensions that are required by those extensions.

source

pub fn enabled_layers(&self) -> &[String]

Returns the layers that have been enabled on the instance.

source

pub fn enumerate_physical_devices( self: &Arc<Self> ) -> Result<impl ExactSizeIterator<Item = Arc<PhysicalDevice>>, VulkanError>

Returns an iterator that enumerates the physical devices available.

Examples

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

pub fn enumerate_physical_device_groups( self: &Arc<Self> ) -> Result<impl ExactSizeIterator<Item = PhysicalDeviceGroupProperties>, Validated<VulkanError>>

Returns an iterator that enumerates the groups of physical devices available. All physical devices in a group can be used to create a single logical device. They are guaranteed have the same properties, and support the same extensions and features.

Every physical device will be returned exactly once; physical devices that are not part of any group will be returned as a group of size 1.

The instance API version must be at least 1.1, or the khr_device_group_creation extension must be enabled on the instance.

source

pub fn is_same_device_group<'a>( self: &Arc<Self>, physical_devices: impl IntoIterator<Item = &'a PhysicalDevice> ) -> bool

Returns whether the given physical devices all belong to the same device group.

Returns false if physical_devices is empty.

Trait Implementations§

source§

impl Debug for Instance

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), FmtError>

Formats the value using the given formatter. Read more
source§

impl Drop for Instance

source§

fn drop(&mut self)

Executes the destructor for this type. Read more
source§

impl Hash for Instance

source§

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher. Read more
1.3.0 · source§

fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
source§

impl PartialEq for Instance

source§

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl VulkanObject for Instance

§

type Handle = Instance

The type of the object.
source§

fn handle(&self) -> Self::Handle

Returns the raw Vulkan handle of the object.
source§

impl Eq for Instance

source§

impl RefUnwindSafe for Instance

source§

impl UnwindSafe for Instance

Auto Trait Implementations§

§

impl Send for Instance

§

impl Sync for Instance

§

impl Unpin for Instance

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.