// SPDX-License-Identifier: AGPL-3.0-only

//! Vertex data structures and layout descriptions.

use bytemuck::{Pod, Zeroable};

/// Represents a single vertex in 3D space with position, colour, and face orientation.
///
/// Uses `repr(C)` to ensure the memory layout matches what the GPU expects (no Rust-specific reordering).
/// `Pod` and `Zeroable` allows safely casting this struct to a raw byte slice. Every field is 4-byte aligned and the struct is 28 bytes, so no implicit padding exists for `Pod` to expose.
#[repr(C)]
#[derive(Copy, Clone, Debug, PartialEq, Pod, Zeroable)]
pub struct Vertex {
    /// 3D position of the vertex (X, Y, Z).
    pub position: [f32; 3],
    /// The RGB color of the vertex [r, g, b].
    pub color: [f32; 3],
    /// Index of the face's outward normal into the shader's normal table.
    ///
    /// Cubic geometry admits only six distinct normals, so the direction is packed as an index rather than a `vec3`, saving 8 bytes per vertex. The vertex shader decodes it; the index ordering is defined by `FaceDir::to_index` in `meshing.rs` and must stay in step with the `FACE_NORMALS` table in `cube.vert`.
    pub normal: u32,
}

impl Vertex {
    /// Describes how Vulkan should read the vertex data from a buffer.
    ///
    /// This defines the 'stride' (distance between vertices) and specifies that data is read per-vertex rather than per-instance.
    ///
    /// # Panics
    /// Panics if the size of the vertex structure exceeds the maximum value of a 32-bit unsigned integer.
    #[expect(
        clippy::expect_used,
        reason = "the vertex struct size is far below u32::MAX"
    )]
    pub fn get_binding_description() -> ash::vk::VertexInputBindingDescription {
        ash::vk::VertexInputBindingDescription::default()
            .binding(0)
            .stride(
                u32::try_from(std::mem::size_of::<Self>()).expect("Vertex size exceeds u32 range"),
            )
            .input_rate(ash::vk::VertexInputRate::VERTEX)
    }

    /// Describes the layout of individual fields (attributes) within a single vertex.
    ///
    /// These 'locations' must match the `layout(location = X)` qualifiers in the vertex shader.
    pub fn get_attribute_descriptions() -> [ash::vk::VertexInputAttributeDescription; 3] {
        [
            // Location 0: position (vec3 -> R32G32B32_SFLOAT)
            ash::vk::VertexInputAttributeDescription::default()
                .binding(0)
                .location(0)
                .format(ash::vk::Format::R32G32B32_SFLOAT)
                .offset(0),
            ash::vk::VertexInputAttributeDescription::default()
                .binding(0)
                .location(1)
                .format(ash::vk::Format::R32G32B32_SFLOAT)
                .offset(12),
            // Location 2: packed face normal index (uint -> R32_UINT). The shader input must be declared `uint`; reading an integer-formatted attribute through a float declaration is undefined and silently produces garbage on some drivers.
            ash::vk::VertexInputAttributeDescription::default()
                .binding(0)
                .location(2)
                .format(ash::vk::Format::R32_UINT)
                .offset(24),
        ]
    }
}