vulkanalia/

lib.rs

// SPDX-License-Identifier: Apache-2.0

//! Vulkan bindings for Rust.
//!
//! For a detailed guide on how this crate (thinly) wraps the Vulkan API, see
//! the `API Concepts` section of the `Overview` chapter of the `vulkanalia`
//! Vulkan tutorial which can be found
//! [here](https://kylemayes.github.io/vulkanalia/overview.html#api-concepts).
//!
//! For the classic triangle example, see
//! [here](https://github.com/KyleMayes/vulkanalia/tree/master/examples/src).
//!
//! #### Quick Tips
//!
//! ##### 1. Use builder structs, but don't `build` them unless you need to!
//!
//! `vulkanalia`'s implementation of Vulkan structs like
//! [`vk::InstanceCreateInfo`] each have associated builder structs that make
//! constructing instances of these structs simple (
//! [`vk::InstanceCreateInfoBuilder`] in this case).
//!
//! You can call the `build` method on a builder struct to extract the Vulkan
//! struct, but this discards valuable information! Builder structs are often
//! parameterized with lifetimes that ensure that the values passed to the
//! builder struct live at least as long as the builder struct itself.
//!
//! Any Vulkan command in `vulkanalia` that takes a Vulkan struct like
//! [`vk::InstanceCreateInfo`] as an argument can also accept the associated
//! builder struct as an argument. This means you can skip those `build` calls
//! and directly invoke Vulkan commands with your builder structs so that the
//! lifetimes can protect you from an entire class of bugs.
//!
//! __Don't__
//!
//! ```ignore
//! let info = vk::InstanceCreateInfo::builder()
//!     .enabled_extension_names(&vec![/* 3 extension names */])
//!     .build();
//!
//! let instance = entry.create_instance(&info, None).unwrap();
//! // 💥: this will (hopefully) crash when the Vulkan implementation attempts
//! // to read a now deallocated list of extension names
//! ```
//!
//! __Do__
//!
//! ```ignore
//! let info = vk::InstanceCreateInfo::builder()
//!     .enabled_extension_names(&vec![/* 3 extension names */]);
//!     // Look ma, no `build`!
//!
//! let instance = entry.create_instance(&info, None).unwrap();
//! // 🦀: this will raise an error at compiletime about how the reference to
//! // the temporary list of extension names doesn't live long enough
//! ```

#![cfg_attr(not(feature = "std"), no_std)]
#![cfg_attr(feature = "no_std_error", feature(error_in_core))]
#![allow(unsafe_op_in_unsafe_fn)]

extern crate alloc;

pub mod bytecode;
pub mod chain;
pub mod loader;
pub mod vk;

#[cfg(feature = "window")]
pub mod window;

use alloc::boxed::Box;
use alloc::collections::btree_set::BTreeSet;
use alloc::sync::Arc;
use core::ffi::c_char;
use core::fmt;
use core::mem;
use core::slice;

use self::loader::{Loader, LoaderError};
use self::prelude::v1_0::*;
use self::vk::{DeviceCommands, EntryCommands, InstanceCommands, StaticCommands};

/// Preludes.
pub mod prelude {
    /// Vulkan 1.0 prelude.
    pub mod v1_0 {
        pub use crate::vk;
        pub use crate::vk::{DeviceV1_0, EntryV1_0, InstanceV1_0};
        pub use crate::vk::{Handle, HasBuilder};
        pub use crate::{Device, Entry, Instance, VkResult, VkSuccessResult};
    }

    /// Vulkan 1.1 prelude.
    pub mod v1_1 {
        pub use crate::prelude::v1_0::*;
        pub use crate::vk::{DeviceV1_1, EntryV1_1, InstanceV1_1};
    }

    /// Vulkan 1.2 prelude.
    pub mod v1_2 {
        pub use crate::prelude::v1_1::*;
        pub use crate::vk::{DeviceV1_2, EntryV1_2, InstanceV1_2};
    }

    /// Vulkan 1.3 prelude.
    pub mod v1_3 {
        pub use crate::prelude::v1_2::*;
        pub use crate::vk::{DeviceV1_3, EntryV1_3, InstanceV1_3};
    }

    /// Vulkan 1.4 prelude.
    pub mod v1_4 {
        pub use crate::prelude::v1_3::*;
        pub use crate::vk::{DeviceV1_4, EntryV1_4, InstanceV1_4};
    }
}

/// The result of a executing a fallible Vulkan command.
pub type VkResult<T> = Result<T, vk::ErrorCode>;
/// The result of a executing a fallible Vulkan command with multiple success codes.
pub type VkSuccessResult<T> = Result<(T, vk::SuccessCode), vk::ErrorCode>;

/// An extension trait for [`vk::Result`].
pub trait ResultExt {
    /// Converts a [`vk::Result`] into a [`VkResult`].
    fn result(self) -> VkResult<()>;
}

impl ResultExt for vk::Result {
    #[inline]
    fn result(self) -> VkResult<()> {
        match self {
            vk::Result::SUCCESS => Ok(()),
            error => Err(error.into()),
        }
    }
}

/// A Vulkan version.
#[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct Version {
    /// The major version (the `x` in `x.y.z`).
    pub major: u32,
    /// The minor version (the `y` in `x.y.z`).
    pub minor: u32,
    /// The patch version (the `z` in `x.y.z`).
    ///
    /// If the version of Vulkan is not at least `1.1.0`, then the patch version
    /// will not be known due to the `vkEnumerateInstanceVersion` function not
    /// being available. In this case this field is set to `0`.
    pub patch: u32,
}

impl Version {
    /// The version for Vulkan `1.0.x`.
    pub const V1_0_0: Version = Version::new(1, 0, 0);
    /// The version for Vulkan `1.1.0`.
    pub const V1_1_0: Version = Version::new(1, 1, 0);
    /// The version for Vulkan `1.2.0`.
    pub const V1_2_0: Version = Version::new(1, 2, 0);
    /// The version for Vulkan `1.3.0`.
    pub const V1_3_0: Version = Version::new(1, 3, 0);
    /// The version for Vulkan `1.4.0`.
    pub const V1_4_0: Version = Version::new(1, 4, 0);

    /// Constructs a new Vulkan version.
    pub const fn new(major: u32, minor: u32, patch: u32) -> Self {
        Self {
            major,
            minor,
            patch,
        }
    }
}

impl Default for Version {
    #[inline]
    fn default() -> Self {
        Self::V1_0_0
    }
}

impl fmt::Display for Version {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "{}.{}.{}", self.major, self.minor, self.patch)
    }
}

impl From<u32> for Version {
    #[inline]
    fn from(version: u32) -> Self {
        Self::new(
            vk::version_major(version),
            vk::version_minor(version),
            vk::version_patch(version),
        )
    }
}

impl From<Version> for u32 {
    fn from(version: Version) -> Self {
        vk::make_version(version.major, version.minor, version.patch)
    }
}

impl From<(u32, u32, u32)> for Version {
    fn from((major, minor, patch): (u32, u32, u32)) -> Self {
        Self::new(major, minor, patch)
    }
}

impl From<Version> for (u32, u32, u32) {
    fn from(version: Version) -> Self {
        (version.major, version.minor, version.patch)
    }
}

/// A Vulkan entry point.
#[derive(Clone)]
pub struct Entry {
    _loader: Option<Arc<dyn Loader>>,
    static_commands: StaticCommands,
    commands: EntryCommands,
}

impl Entry {
    /// Loads a Vulkan entry point from previously loaded [`StaticCommands`].
    ///
    /// # Safety
    ///
    /// `static_commands` must contain valid Vulkan commands.
    #[inline]
    pub unsafe fn from_commands(static_commands: &StaticCommands) -> Self {
        let load = |n| (static_commands.get_instance_proc_addr)(vk::Instance::null(), n);
        let commands = EntryCommands::load(load);

        Self {
            _loader: None,
            static_commands: *static_commands,
            commands,
        }
    }

    /// Loads a Vulkan entry point using a Vulkan function loader.
    ///
    /// # Safety
    ///
    /// The [`Loader::load`] method will be called on the supplied [`Loader`]
    /// implementation to load the entry commands so the safety requirements of
    /// [`Loader::load`] for the [`Loader`] implementation used must be upheld.
    #[inline]
    pub unsafe fn new(loader: impl Loader + 'static) -> Result<Self, Box<dyn LoaderError>> {
        let loader = Arc::new(loader);

        type F = extern "system" fn();

        let raw = loader.load(b"vkGetInstanceProcAddr")?;
        let get_instance_proc_addr = mem::transmute::<F, vk::PFN_vkGetInstanceProcAddr>(raw);

        let raw = loader.load(b"vkGetDeviceProcAddr")?;
        let get_device_proc_addr = mem::transmute::<F, vk::PFN_vkGetDeviceProcAddr>(raw);

        let static_commands = StaticCommands {
            get_instance_proc_addr,
            get_device_proc_addr,
        };

        let load = |n| get_instance_proc_addr(vk::Instance::null(), n);
        let commands = EntryCommands::load(load);

        Ok(Self {
            _loader: Some(loader),
            static_commands,
            commands,
        })
    }

    /// Gets the instance-level version of this Vulkan entry point.
    #[inline]
    pub fn version(&self) -> VkResult<Version> {
        unsafe { get_version(self.static_commands.get_instance_proc_addr) }
    }

    /// Creates a Vulkan instance using this Vulkan entry point.
    ///
    /// # Safety
    ///
    /// The [`Loader::load`] method will be called on the supplied [`Loader`]
    /// implementation to load the instance commands so the safety requirements
    /// of [`Loader::load`] for the [`Loader`] implementation used must be
    /// upheld.
    #[inline]
    pub unsafe fn create_instance(
        &self,
        info: &vk::InstanceCreateInfo,
        allocator: Option<&vk::AllocationCallbacks>,
    ) -> VkResult<Instance> {
        let instance = EntryV1_0::create_instance(self, info, allocator)?;
        Instance::from_created(self, info, instance)
    }
}

impl fmt::Debug for Entry {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "Entry")
    }
}

unsafe impl Send for Entry {}
unsafe impl Sync for Entry {}

/// A Vulkan instance.
#[derive(Clone)]
pub struct Instance {
    entry: Entry,
    handle: vk::Instance,
    commands: InstanceCommands,
    version: Version,
    extensions: BTreeSet<vk::ExtensionName>,
    layers: BTreeSet<vk::ExtensionName>,
}

impl Instance {
    /// Loads a Vulkan instance from a previously created [`vk::Instance`].
    ///
    /// # Safety
    ///
    /// `instance` must have been created using `entry` and `info`.
    #[inline]
    pub unsafe fn from_created(
        entry: &Entry,
        info: &vk::InstanceCreateInfo,
        instance: vk::Instance,
    ) -> VkResult<Self> {
        let load = |n| (entry.static_commands.get_instance_proc_addr)(instance, n);
        let commands = InstanceCommands::load(load);

        let version = get_version(entry.static_commands.get_instance_proc_addr)?;

        let extensions = get_names(info.enabled_extension_count, info.enabled_extension_names);
        let layers = get_names(info.enabled_layer_count, info.enabled_layer_names);

        Ok(Self {
            entry: entry.clone(),
            handle: instance,
            commands,
            version,
            extensions,
            layers,
        })
    }

    /// Gets the version for this Vulkan instance.
    #[inline]
    pub fn version(&self) -> Version {
        self.version
    }

    /// Gets the loaded extensions for this Vulkan instance.
    #[inline]
    pub fn extensions(&self) -> &BTreeSet<vk::ExtensionName> {
        &self.extensions
    }

    /// Gets the loaded layers for this Vulkan instance.
    #[inline]
    pub fn layers(&self) -> &BTreeSet<vk::ExtensionName> {
        &self.layers
    }

    /// Creates a Vulkan device using this Vulkan instance.
    ///
    /// # Safety
    ///
    /// The [`Loader::load`] method will be called on the supplied [`Loader`]
    /// implementation to load the device commands so the safety requirements of
    /// [`Loader::load`] for the [`Loader`] implementation used must be upheld.
    #[inline]
    pub unsafe fn create_device(
        &self,
        physical_device: vk::PhysicalDevice,
        info: &vk::DeviceCreateInfo,
        allocator: Option<&vk::AllocationCallbacks>,
    ) -> VkResult<Device> {
        let device = InstanceV1_0::create_device(self, physical_device, info, allocator)?;
        Device::from_created(&self.entry, physical_device, info, device)
    }
}

impl fmt::Debug for Instance {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.debug_struct("Instance")
            .field("handle", &self.handle)
            .field("extensions", &self.extensions)
            .field("layers", &self.layers)
            .finish()
    }
}

unsafe impl Send for Instance {}
unsafe impl Sync for Instance {}

/// A Vulkan device.
#[derive(Clone)]
pub struct Device {
    handle: vk::Device,
    commands: DeviceCommands,
    physical_device: vk::PhysicalDevice,
    extensions: BTreeSet<vk::ExtensionName>,
    layers: BTreeSet<vk::ExtensionName>,
}

impl Device {
    /// Loads a Vulkan device from a previously created [`vk::Device`].
    ///
    /// # Safety
    ///
    /// `device` must have been created using `entry`, `physical_device`, and `info`.
    #[inline]
    pub unsafe fn from_created(
        entry: &Entry,
        physical_device: vk::PhysicalDevice,
        info: &vk::DeviceCreateInfo,
        device: vk::Device,
    ) -> VkResult<Self> {
        let load = |n| (entry.static_commands.get_device_proc_addr)(device, n);
        let commands = DeviceCommands::load(load);

        let extensions = get_names(info.enabled_extension_count, info.enabled_extension_names);
        let layers = get_names(info.enabled_layer_count, info.enabled_layer_names);

        Ok(Self {
            handle: device,
            commands,
            physical_device,
            extensions,
            layers,
        })
    }

    /// Gets the physical device for this Vulkan device.
    #[inline]
    pub fn physical_device(&self) -> vk::PhysicalDevice {
        self.physical_device
    }

    /// Gets the loaded extensions for this Vulkan device.
    #[inline]
    pub fn extensions(&self) -> &BTreeSet<vk::ExtensionName> {
        &self.extensions
    }

    /// Gets the loaded layers for this Vulkan device.
    #[inline]
    pub fn layers(&self) -> &BTreeSet<vk::ExtensionName> {
        &self.layers
    }
}

impl fmt::Debug for Device {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.debug_struct("Device")
            .field("handle", &self.handle)
            .field("extensions", &self.extensions)
            .field("layers", &self.layers)
            .finish()
    }
}

unsafe impl Send for Device {}
unsafe impl Sync for Device {}

#[inline]
unsafe fn get_names(
    num_strings: u32,
    strings: *const *const c_char,
) -> BTreeSet<vk::ExtensionName> {
    if strings.is_null() || num_strings == 0 {
        return BTreeSet::new();
    }

    slice::from_raw_parts(strings, num_strings as usize)
        .iter()
        .map(|s| vk::ExtensionName::from_ptr(*s))
        .collect()
}

#[inline]
unsafe fn get_version(get_instance_proc_addr: vk::PFN_vkGetInstanceProcAddr) -> VkResult<Version> {
    let name = c"vkEnumerateInstanceVersion".as_ptr();
    let raw = (get_instance_proc_addr)(vk::Instance::null(), name);
    let enumerate: Option<vk::PFN_vkEnumerateInstanceVersion> = mem::transmute(raw);
    if let Some(enumerate) = enumerate {
        let mut version = 0;
        match unsafe { enumerate(&mut version) } {
            vk::Result::SUCCESS => Ok(Version::from(version)),
            error => Err(error.into()),
        }
    } else {
        Ok(Version::V1_0_0)
    }
}