jay_ash/

instance.rs

#[cfg(doc)]
use super::Entry;
use crate::RawPtr;
use crate::device::Device;
use crate::prelude::*;
use crate::vk;
use alloc::vec::Vec;
use core::ffi;
use core::mem;
use core::ptr;

/// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkInstance.html>
#[derive(Clone)]
pub struct Instance {
    pub(crate) handle: vk::Instance,

    pub(crate) instance_fn_1_0: crate::InstanceFnV1_0,
    pub(crate) instance_fn_1_1: crate::InstanceFnV1_1,
    pub(crate) instance_fn_1_3: crate::InstanceFnV1_3,
}

impl Instance {
    pub unsafe fn load(static_fn: &crate::StaticFn, instance: vk::Instance) -> Self {
        unsafe {
            Self::load_with(
                |name| mem::transmute((static_fn.get_instance_proc_addr)(instance, name.as_ptr())),
                instance,
            )
        }
    }

    pub unsafe fn load_with(
        mut load_fn: impl FnMut(&ffi::CStr) -> *const ffi::c_void,
        instance: vk::Instance,
    ) -> Self {
        Self::from_parts_1_3(
            instance,
            crate::InstanceFnV1_0::load(&mut load_fn),
            crate::InstanceFnV1_1::load(&mut load_fn),
            crate::InstanceFnV1_3::load(&mut load_fn),
        )
    }

    #[inline]
    pub fn from_parts_1_3(
        handle: vk::Instance,
        instance_fn_1_0: crate::InstanceFnV1_0,
        instance_fn_1_1: crate::InstanceFnV1_1,
        instance_fn_1_3: crate::InstanceFnV1_3,
    ) -> Self {
        Self {
            handle,

            instance_fn_1_0,
            instance_fn_1_1,
            instance_fn_1_3,
        }
    }

    #[inline]
    pub fn handle(&self) -> vk::Instance {
        self.handle
    }
}

/// Vulkan core 1.3
impl Instance {
    #[inline]
    pub fn fp_v1_3(&self) -> &crate::InstanceFnV1_3 {
        &self.instance_fn_1_3
    }

    /// Retrieve the number of elements to pass to [`get_physical_device_tool_properties()`][Self::get_physical_device_tool_properties()]
    #[inline]
    pub unsafe fn get_physical_device_tool_properties_len(
        &self,
        physical_device: vk::PhysicalDevice,
    ) -> VkResult<usize> {
        unsafe {
            let mut count = mem::MaybeUninit::uninit();
            (self.instance_fn_1_3.get_physical_device_tool_properties)(
                physical_device,
                count.as_mut_ptr(),
                ptr::null_mut(),
            )
            .assume_init_on_success(count)
            .map(|c| c as usize)
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetPhysicalDeviceToolProperties.html>
    ///
    /// Call [`get_physical_device_tool_properties_len()`][Self::get_physical_device_tool_properties_len()] to query the number of elements to pass to `out`.
    /// Be sure to [`Default::default()`]-initialize these elements and optionally set their `p_next` pointer.
    #[inline]
    pub unsafe fn get_physical_device_tool_properties(
        &self,
        physical_device: vk::PhysicalDevice,
        out: &mut [vk::PhysicalDeviceToolProperties<'_>],
    ) -> VkResult<()> {
        unsafe {
            let mut count = out.len() as u32;
            (self.instance_fn_1_3.get_physical_device_tool_properties)(
                physical_device,
                &mut count,
                out.as_mut_ptr(),
            )
            .result()?;
            assert_eq!(count as usize, out.len());
            Ok(())
        }
    }
}

/// Vulkan core 1.1
impl Instance {
    #[inline]
    pub fn fp_v1_1(&self) -> &crate::InstanceFnV1_1 {
        &self.instance_fn_1_1
    }

    /// Retrieve the number of elements to pass to [`enumerate_physical_device_groups()`][Self::enumerate_physical_device_groups()]
    #[inline]
    pub unsafe fn enumerate_physical_device_groups_len(&self) -> VkResult<usize> {
        unsafe {
            let mut group_count = mem::MaybeUninit::uninit();
            (self.instance_fn_1_1.enumerate_physical_device_groups)(
                self.handle(),
                group_count.as_mut_ptr(),
                ptr::null_mut(),
            )
            .assume_init_on_success(group_count)
            .map(|c| c as usize)
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkEnumeratePhysicalDeviceGroups.html>
    ///
    /// Call [`enumerate_physical_device_groups_len()`][Self::enumerate_physical_device_groups_len()] to query the number of elements to pass to `out`.
    /// Be sure to [`Default::default()`]-initialize these elements and optionally set their `p_next` pointer.
    #[inline]
    pub unsafe fn enumerate_physical_device_groups(
        &self,
        out: &mut [vk::PhysicalDeviceGroupProperties<'_>],
    ) -> VkResult<()> {
        unsafe {
            let mut count = out.len() as u32;
            (self.instance_fn_1_1.enumerate_physical_device_groups)(
                self.handle(),
                &mut count,
                out.as_mut_ptr(),
            )
            .result()?;
            assert_eq!(count as usize, out.len());
            Ok(())
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetPhysicalDeviceFeatures2.html>
    #[inline]
    pub unsafe fn get_physical_device_features2(
        &self,
        physical_device: vk::PhysicalDevice,
        features: &mut vk::PhysicalDeviceFeatures2<'_>,
    ) {
        unsafe {
            (self.instance_fn_1_1.get_physical_device_features2)(physical_device, features);
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetPhysicalDeviceProperties2.html>
    #[inline]
    pub unsafe fn get_physical_device_properties2(
        &self,
        physical_device: vk::PhysicalDevice,
        prop: &mut vk::PhysicalDeviceProperties2<'_>,
    ) {
        unsafe {
            (self.instance_fn_1_1.get_physical_device_properties2)(physical_device, prop);
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetPhysicalDeviceFormatProperties2.html>
    #[inline]
    pub unsafe fn get_physical_device_format_properties2(
        &self,
        physical_device: vk::PhysicalDevice,
        format: vk::Format,
        out: &mut vk::FormatProperties2<'_>,
    ) {
        unsafe {
            (self.instance_fn_1_1.get_physical_device_format_properties2)(
                physical_device,
                format,
                out,
            );
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetPhysicalDeviceImageFormatProperties2.html>
    #[inline]
    pub unsafe fn get_physical_device_image_format_properties2(
        &self,
        physical_device: vk::PhysicalDevice,
        format_info: &vk::PhysicalDeviceImageFormatInfo2<'_>,
        image_format_prop: &mut vk::ImageFormatProperties2<'_>,
    ) -> VkResult<()> {
        unsafe {
            (self
                .instance_fn_1_1
                .get_physical_device_image_format_properties2)(
                physical_device,
                format_info,
                image_format_prop,
            )
            .result()
        }
    }

    /// Retrieve the number of elements to pass to [`get_physical_device_queue_family_properties2()`][Self::get_physical_device_queue_family_properties2()]
    #[inline]
    pub unsafe fn get_physical_device_queue_family_properties2_len(
        &self,
        physical_device: vk::PhysicalDevice,
    ) -> usize {
        unsafe {
            let mut queue_count = mem::MaybeUninit::uninit();
            (self
                .instance_fn_1_1
                .get_physical_device_queue_family_properties2)(
                physical_device,
                queue_count.as_mut_ptr(),
                ptr::null_mut(),
            );
            queue_count.assume_init() as usize
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetPhysicalDeviceQueueFamilyProperties2.html>
    ///
    /// Call [`get_physical_device_queue_family_properties2_len()`][Self::get_physical_device_queue_family_properties2_len()] to query the number of elements to pass to `out`.
    /// Be sure to [`Default::default()`]-initialize these elements and optionally set their `p_next` pointer.
    #[inline]
    pub unsafe fn get_physical_device_queue_family_properties2(
        &self,
        physical_device: vk::PhysicalDevice,
        out: &mut [vk::QueueFamilyProperties2<'_>],
    ) {
        unsafe {
            let mut count = out.len() as u32;
            (self
                .instance_fn_1_1
                .get_physical_device_queue_family_properties2)(
                physical_device,
                &mut count,
                out.as_mut_ptr(),
            );
            assert_eq!(count as usize, out.len());
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetPhysicalDeviceMemoryProperties2.html>
    #[inline]
    pub unsafe fn get_physical_device_memory_properties2(
        &self,
        physical_device: vk::PhysicalDevice,
        out: &mut vk::PhysicalDeviceMemoryProperties2<'_>,
    ) {
        unsafe {
            (self.instance_fn_1_1.get_physical_device_memory_properties2)(physical_device, out);
        }
    }

    /// Retrieve the number of elements to pass to [`get_physical_device_sparse_image_format_properties2()`][Self::get_physical_device_sparse_image_format_properties2()]
    #[inline]
    pub unsafe fn get_physical_device_sparse_image_format_properties2_len(
        &self,
        physical_device: vk::PhysicalDevice,
        format_info: &vk::PhysicalDeviceSparseImageFormatInfo2<'_>,
    ) -> usize {
        unsafe {
            let mut format_count = mem::MaybeUninit::uninit();
            (self
                .instance_fn_1_1
                .get_physical_device_sparse_image_format_properties2)(
                physical_device,
                format_info,
                format_count.as_mut_ptr(),
                ptr::null_mut(),
            );
            format_count.assume_init() as usize
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetPhysicalDeviceSparseImageFormatProperties2.html>
    ///
    /// Call [`get_physical_device_sparse_image_format_properties2_len()`][Self::get_physical_device_sparse_image_format_properties2_len()] to query the number of elements to pass to `out`.
    /// Be sure to [`Default::default()`]-initialize these elements and optionally set their `p_next` pointer.
    #[inline]
    pub unsafe fn get_physical_device_sparse_image_format_properties2(
        &self,
        physical_device: vk::PhysicalDevice,
        format_info: &vk::PhysicalDeviceSparseImageFormatInfo2<'_>,
        out: &mut [vk::SparseImageFormatProperties2<'_>],
    ) {
        unsafe {
            let mut count = out.len() as u32;
            (self
                .instance_fn_1_1
                .get_physical_device_sparse_image_format_properties2)(
                physical_device,
                format_info,
                &mut count,
                out.as_mut_ptr(),
            );
            assert_eq!(count as usize, out.len());
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetPhysicalDeviceExternalBufferProperties.html>
    #[inline]
    pub unsafe fn get_physical_device_external_buffer_properties(
        &self,
        physical_device: vk::PhysicalDevice,
        external_buffer_info: &vk::PhysicalDeviceExternalBufferInfo<'_>,
        out: &mut vk::ExternalBufferProperties<'_>,
    ) {
        unsafe {
            (self
                .instance_fn_1_1
                .get_physical_device_external_buffer_properties)(
                physical_device,
                external_buffer_info,
                out,
            );
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetPhysicalDeviceExternalFenceProperties.html>
    #[inline]
    pub unsafe fn get_physical_device_external_fence_properties(
        &self,
        physical_device: vk::PhysicalDevice,
        external_fence_info: &vk::PhysicalDeviceExternalFenceInfo<'_>,
        out: &mut vk::ExternalFenceProperties<'_>,
    ) {
        unsafe {
            (self
                .instance_fn_1_1
                .get_physical_device_external_fence_properties)(
                physical_device,
                external_fence_info,
                out,
            );
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetPhysicalDeviceExternalSemaphoreProperties.html>
    #[inline]
    pub unsafe fn get_physical_device_external_semaphore_properties(
        &self,
        physical_device: vk::PhysicalDevice,
        external_semaphore_info: &vk::PhysicalDeviceExternalSemaphoreInfo<'_>,
        out: &mut vk::ExternalSemaphoreProperties<'_>,
    ) {
        unsafe {
            (self
                .instance_fn_1_1
                .get_physical_device_external_semaphore_properties)(
                physical_device,
                external_semaphore_info,
                out,
            );
        }
    }
}

/// Vulkan core 1.0
impl Instance {
    #[inline]
    pub fn fp_v1_0(&self) -> &crate::InstanceFnV1_0 {
        &self.instance_fn_1_0
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkCreateDevice.html>
    ///
    /// # Safety
    ///
    /// There is a [parent/child relation] between [`Instance`] and the resulting [`Device`].  The
    /// application must not [destroy][Instance::destroy_instance()] the parent [`Instance`] object
    /// before first [destroying][Device::destroy_device()] the returned [`Device`] child object.
    /// [`Device`] does _not_ implement [drop][drop()] semantics and can only be destroyed via
    /// [`destroy_device()`][Device::destroy_device()].
    ///
    /// See the [`Entry::create_instance()`] documentation for more destruction ordering rules on
    /// [`Instance`].
    ///
    /// [parent/child relation]: https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#fundamentals-objectmodel-lifetime
    #[inline]
    pub unsafe fn create_device(
        &self,
        physical_device: vk::PhysicalDevice,
        create_info: &vk::DeviceCreateInfo<'_>,
        allocation_callbacks: Option<&vk::AllocationCallbacks<'_>>,
    ) -> VkResult<Device> {
        unsafe {
            let mut device = mem::MaybeUninit::uninit();
            let device = (self.instance_fn_1_0.create_device)(
                physical_device,
                create_info,
                allocation_callbacks.as_raw_ptr(),
                device.as_mut_ptr(),
            )
            .assume_init_on_success(device)?;
            Ok(Device::load(&self.instance_fn_1_0, device))
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetDeviceProcAddr.html>
    #[inline]
    pub unsafe fn get_device_proc_addr(
        &self,
        device: vk::Device,
        p_name: *const ffi::c_char,
    ) -> vk::PFN_vkVoidFunction {
        unsafe { (self.instance_fn_1_0.get_device_proc_addr)(device, p_name) }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkDestroyInstance.html>
    #[inline]
    pub unsafe fn destroy_instance(
        &self,
        allocation_callbacks: Option<&vk::AllocationCallbacks<'_>>,
    ) {
        unsafe {
            (self.instance_fn_1_0.destroy_instance)(
                self.handle(),
                allocation_callbacks.as_raw_ptr(),
            );
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetPhysicalDeviceFormatProperties.html>
    #[inline]
    pub unsafe fn get_physical_device_format_properties(
        &self,
        physical_device: vk::PhysicalDevice,
        format: vk::Format,
    ) -> vk::FormatProperties {
        unsafe {
            let mut format_prop = mem::MaybeUninit::uninit();
            (self.instance_fn_1_0.get_physical_device_format_properties)(
                physical_device,
                format,
                format_prop.as_mut_ptr(),
            );
            format_prop.assume_init()
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetPhysicalDeviceImageFormatProperties.html>
    #[inline]
    pub unsafe fn get_physical_device_image_format_properties(
        &self,
        physical_device: vk::PhysicalDevice,
        format: vk::Format,
        typ: vk::ImageType,
        tiling: vk::ImageTiling,
        usage: vk::ImageUsageFlags,
        flags: vk::ImageCreateFlags,
    ) -> VkResult<vk::ImageFormatProperties> {
        unsafe {
            let mut image_format_prop = mem::MaybeUninit::uninit();
            (self
                .instance_fn_1_0
                .get_physical_device_image_format_properties)(
                physical_device,
                format,
                typ,
                tiling,
                usage,
                flags,
                image_format_prop.as_mut_ptr(),
            )
            .assume_init_on_success(image_format_prop)
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetPhysicalDeviceMemoryProperties.html>
    #[inline]
    pub unsafe fn get_physical_device_memory_properties(
        &self,
        physical_device: vk::PhysicalDevice,
    ) -> vk::PhysicalDeviceMemoryProperties {
        unsafe {
            let mut memory_prop = mem::MaybeUninit::uninit();
            (self.instance_fn_1_0.get_physical_device_memory_properties)(
                physical_device,
                memory_prop.as_mut_ptr(),
            );
            memory_prop.assume_init()
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetPhysicalDeviceProperties.html>
    #[inline]
    pub unsafe fn get_physical_device_properties(
        &self,
        physical_device: vk::PhysicalDevice,
    ) -> vk::PhysicalDeviceProperties {
        unsafe {
            let mut prop = mem::MaybeUninit::uninit();
            (self.instance_fn_1_0.get_physical_device_properties)(
                physical_device,
                prop.as_mut_ptr(),
            );
            prop.assume_init()
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetPhysicalDeviceQueueFamilyProperties.html>
    #[inline]
    pub unsafe fn get_physical_device_queue_family_properties(
        &self,
        physical_device: vk::PhysicalDevice,
    ) -> Vec<vk::QueueFamilyProperties> {
        unsafe {
            read_into_uninitialized_vector(|count, data| {
                (self
                    .instance_fn_1_0
                    .get_physical_device_queue_family_properties)(
                    physical_device, count, data
                );
                vk::Result::SUCCESS
            })
            // The closure always returns SUCCESS
            .unwrap()
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetPhysicalDeviceFeatures.html>
    #[inline]
    pub unsafe fn get_physical_device_features(
        &self,
        physical_device: vk::PhysicalDevice,
    ) -> vk::PhysicalDeviceFeatures {
        unsafe {
            let mut prop = mem::MaybeUninit::uninit();
            (self.instance_fn_1_0.get_physical_device_features)(physical_device, prop.as_mut_ptr());
            prop.assume_init()
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkEnumeratePhysicalDevices.html>
    #[inline]
    pub unsafe fn enumerate_physical_devices(&self) -> VkResult<Vec<vk::PhysicalDevice>> {
        unsafe {
            read_into_uninitialized_vector(|count, data| {
                (self.instance_fn_1_0.enumerate_physical_devices)(self.handle(), count, data)
            })
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkEnumerateDeviceExtensionProperties.html>
    #[inline]
    pub unsafe fn enumerate_device_extension_properties(
        &self,
        device: vk::PhysicalDevice,
    ) -> VkResult<Vec<vk::ExtensionProperties>> {
        unsafe {
            read_into_uninitialized_vector(|count, data| {
                (self.instance_fn_1_0.enumerate_device_extension_properties)(
                    device,
                    ptr::null(),
                    count,
                    data,
                )
            })
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkEnumerateDeviceLayerProperties.html>
    #[inline]
    pub unsafe fn enumerate_device_layer_properties(
        &self,
        device: vk::PhysicalDevice,
    ) -> VkResult<Vec<vk::LayerProperties>> {
        unsafe {
            read_into_uninitialized_vector(|count, data| {
                (self.instance_fn_1_0.enumerate_device_layer_properties)(device, count, data)
            })
        }
    }

    /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetPhysicalDeviceSparseImageFormatProperties.html>
    #[inline]
    pub unsafe fn get_physical_device_sparse_image_format_properties(
        &self,
        physical_device: vk::PhysicalDevice,
        format: vk::Format,
        typ: vk::ImageType,
        samples: vk::SampleCountFlags,
        usage: vk::ImageUsageFlags,
        tiling: vk::ImageTiling,
    ) -> Vec<vk::SparseImageFormatProperties> {
        unsafe {
            read_into_uninitialized_vector(|count, data| {
                (self
                    .instance_fn_1_0
                    .get_physical_device_sparse_image_format_properties)(
                    physical_device,
                    format,
                    typ,
                    samples,
                    usage,
                    tiling,
                    count,
                    data,
                );
                vk::Result::SUCCESS
            })
            // The closure always returns SUCCESS
            .unwrap()
        }
    }
}