Struct vulkano::instance::Instance [−][src]
pub struct Instance { /* fields omitted */ }
Expand description
An instance of a Vulkan context. This is the main object that should be created by an application before everything else.
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}; use vulkano::Version; // 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), Version::V1_1, &InstanceExtensions::none(), None).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
FunctionPointers::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
.
However, 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; use vulkano::instance::InstanceExtensions; use vulkano::Version; let extensions = InstanceExtensions { khr_surface: true, khr_android_surface: true, .. InstanceExtensions::none() }; let instance = match Instance::new(None, Version::V1_1, &extensions, None) { Ok(i) => i, Err(err) => panic!("Couldn't build 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 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, Version::V1_1, &InstanceExtensions::none(), layer_names)?;
Implementations
pub fn new<'a, L>(
app_infos: Option<&ApplicationInfo<'_>>,
max_api_version: Version,
extensions: &InstanceExtensions,
layers: L
) -> Result<Arc<Instance>, InstanceCreationError> where
L: IntoIterator<Item = &'a str>,
pub fn new<'a, L>(
app_infos: Option<&ApplicationInfo<'_>>,
max_api_version: Version,
extensions: &InstanceExtensions,
layers: L
) -> Result<Arc<Instance>, InstanceCreationError> where
L: IntoIterator<Item = &'a str>,
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; use vulkano::Version; let instance = match Instance::new(None, Version::V1_1, &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>(
loader: FunctionPointers<Box<dyn Loader + Send + Sync>>,
app_infos: Option<&ApplicationInfo<'_>>,
max_api_version: Version,
extensions: &InstanceExtensions,
layers: L
) -> Result<Arc<Instance>, InstanceCreationError> where
L: IntoIterator<Item = &'a str>,
pub fn with_loader<'a, L>(
loader: FunctionPointers<Box<dyn Loader + Send + Sync>>,
app_infos: Option<&ApplicationInfo<'_>>,
max_api_version: Version,
extensions: &InstanceExtensions,
layers: L
) -> Result<Arc<Instance>, InstanceCreationError> where
L: IntoIterator<Item = &'a str>,
Same as new
, but allows specifying a loader where to load Vulkan from.
Returns the Vulkan version supported by the instance.
This is the lower of the
driver’s supported version and
max_api_version
.
Returns the maximum Vulkan version that was specified when creating the instance.
Returns the extensions that have been enabled on the instance.
This list is equal to what was passed to Instance::new()
.
Example
use vulkano::instance::Instance; use vulkano::instance::InstanceExtensions; use vulkano::Version; let extensions = InstanceExtensions::supported_by_core().unwrap(); let instance = Instance::new(None, Version::V1_1, &extensions, None).unwrap(); assert_eq!(instance.loaded_extensions(), &extensions);
Trait Implementations
Returns a reference to the object.
Auto Trait Implementations
Blanket Implementations
Mutably borrows from an owned value. Read more
Builds a pointer to this type from a raw pointer.
Returns true if the size is suitable to store a type like this.
Returns the size of an individual element.