3 // <LICENSE-APACHE or
4 // https://www.apache.org/licenses/LICENSE-2.0> or the MIT
5 // license <LICENSE-MIT or https://opensource.org/licenses/MIT>,
12 //! The first thing to do after loading the Vulkan library is to create an `Instance` object.
23 //!     .unwrap_or_else(|err| panic!("Couldn't load Vulkan library: {:?}", err));
29 //! ie. all the Vulkan implementations that are available on the system.
59 //! Certain devices, currently those on MacOS and iOS systems, do not fully conform to the Vulkan
61 //! is required; some mandatory parts of Vulkan are missing. These are known as
67 //! automatically enable it when creating the device. When it is enabled, some parts of Vulkan that
68 //! are available in standard Vulkan will not be available by default, but they can be used by
71 //! Because these devices are non-conformant, Vulkan programs that rely on full compliance may
73 //! Vulkan that is missing from the non-conformant device. Therefore, Vulkan hides them from
79 //! do this, your program must be prepared to handle the non-conformant aspects of these devices,
85 pub use self::{extensions::InstanceExtensions, layers::LayerProperties};
109 mod layers;  module
111 /// An instance of a Vulkan context. This is the main object that should be created by an
140 /// Both an `Instance` and a [`Device`](crate::device::Device) have a highest version of the Vulkan
141 /// API that they support. This places a limit on what Vulkan functions and features are available
151 /// it. For example, if both instance and device potentially support Vulkan 1.2, but you specify
152 /// 1.1 as the maximum API version when creating the `Instance`, then you can only use Vulkan 1.1
161 /// Due to a quirk in how the Vulkan 1.0 specification was written, if the instance only
162 /// supports Vulkan 1.0, then it is not possible to specify a maximum API version higher than 1.0.
169 /// newly-created instance. Trying to enable an extension that is not supported by the system will
182 /// succeed on anything else than an Android-running device.
191 ///     .unwrap_or_else(|err| panic!("Couldn't load Vulkan library: {:?}", err));
209 /// # Layers
211 /// When creating an `Instance`, you have the possibility to pass a list of **layers** that will
212 /// be activated on the newly-created instance. The list of available layers can be retrieved by
216 /// A layer is a component that will hook and potentially modify the Vulkan function calls.
217 /// For example, activating a layer could add a frames-per-second counter on the screen, or it
220 /// > **Note**: From an application's point of view, layers "just exist". In practice, on Windows
221 /// > and Linux, layers can be installed by third party installers or by package managers and can
223 /// > before starting the program. See the documentation of the official Vulkan loader for these
226 /// > **Note**: In practice, the most common use of layers right now is for debugging purposes.
229 /// > `export VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_api_dump` on Linux if you installed the Vulkan SDK
230 /// > will print the list of raw Vulkan function calls.
240 /// # fn test() -> Result<Arc<Instance>, Box<dyn Error>> {
243 /// // For the sake of the example, we activate all the layers that
245 /// let layers: Vec<_> = library.layer_properties()?
252 ///         enabled_layers: layers.iter().map(|l| l.name().to_owned()).collect(),
259 // TODO: mention that extensions must be supported by layers as well
282     /// - Panics if any version numbers in `create_info` contain a field too large to be converted
283     ///   into a Vulkan version number.
284     /// - Panics if `create_info.max_api_version` is not at least `V1_0`.
288     ) -> Result<Arc<Instance>, InstanceCreationError> {  in new()
304     /// - Panics if the `message_severity` or `message_type` members of any element of
309     /// - The `user_callback` of each element of `debug_utils_messengers` must not make any calls
310     ///   to the Vulkan API.
315     ) -> Result<Arc<Instance>, InstanceCreationError> {  in with_debug_utils_messengers()
343         // VUID-VkApplicationInfo-apiVersion-04010  in with_debug_utils_messengers()
426             // VUID-VkValidationFeaturesEXT-pEnabledValidationFeatures-02967  in with_debug_utils_messengers()
433             // VUID-VkValidationFeaturesEXT-pEnabledValidationFeatures-02968  in with_debug_utils_messengers()
465             // VUID-VkInstanceCreateInfo-pNext-04926  in with_debug_utils_messengers()
476             // VUID-VkDebugUtilsMessengerCreateInfoEXT-messageSeverity-parameter  in with_debug_utils_messengers()
479             // VUID-VkDebugUtilsMessengerCreateInfoEXT-messageSeverity-requiredbitmask  in with_debug_utils_messengers()
482             // VUID-VkDebugUtilsMessengerCreateInfoEXT-messageType-parameter  in with_debug_utils_messengers()
485             // VUID-VkDebugUtilsMessengerCreateInfoEXT-messageType-requiredbitmask  in with_debug_utils_messengers()
488             // VUID-PFN_vkDebugUtilsMessengerCallbackEXT-None-04769  in with_debug_utils_messengers()
506             debug_utils_messenger_create_infos[i - 1].p_next =  in with_debug_utils_messengers()
514         // Creating the Vulkan instance.  in with_debug_utils_messengers()
524         // Loading the function pointers of the newly-created instance.  in with_debug_utils_messengers()
546     /// Returns the Vulkan library used to create this instance.
548     pub fn library(&self) -> &Arc<VulkanLibrary> {  in library()
552     /// Returns the Vulkan version supported by the instance.
558     pub fn api_version(&self) -> Version {  in api_version()
562     /// Returns the maximum Vulkan version that was specified when creating the instance.
564     pub fn max_api_version(&self) -> Version {  in max_api_version()
568     /// Returns pointers to the raw Vulkan functions of the instance.
570     pub fn fns(&self) -> &InstanceFunctions {  in fns()
576     pub fn enabled_extensions(&self) -> &InstanceExtensions {  in enabled_extensions()
580     /// Returns the layers that have been enabled on the instance.
582     pub fn enabled_layers(&self) -> &[String] {  in enabled_layers()
604     ) -> Result<impl ExactSizeIterator<Item = Arc<PhysicalDevice>>, VulkanError> {  in enumerate_physical_devices()
656     fn handle(&self) -> Self::Handle {  in handle()
664     fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), FmtError> {  in fmt()
707     /// The layers to enable on the instance.
721     /// The highest Vulkan API version that the application will use with the instance.
729 …lude [portability subset](crate::instance#portability-subset-devices-and-the-enumerate_portability…
733     /// non-conformant aspects of these devices.
735     /// If this flag is not enabled, and there are no fully-conformant devices on the system, then
767     fn default() -> Self {  in default()
790     /// - Panics if the required environment variables are missing, which happens if the project
793     pub fn application_from_cargo_toml() -> Self {  in application_from_cargo_toml()
812     /// Failed to initialize for an implementation-specific reason.
815     /// One of the requested layers is missing.
834     fn source(&self) -> Option<&(dyn Error + 'static)> {  in source()
843     fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), FmtError> {  in fmt()
864     fn from(err: OomError) -> Self {  in from()
870     fn from(err: ExtensionRestrictionError) -> Self {  in from()
876     fn from(err: VulkanError) -> Self {  in from()