GraphicsUtils.hpp

Go to the documentation of this file.

#pragma once
 
#include "MayaFlux/Kakshya/NDData/ImageData.hpp"
#include "MayaFlux/Kinesis/Viewport/Scissor.hpp"
 
namespace MayaFlux::Core {
class Window;
class VKImage;
}
 
namespace MayaFlux::Portal::Graphics {
 
//============================================================================
// Primitive Topology
//============================================================================
 
/**
 * @enum PrimitiveTopology
 * @brief Vertex assembly primitive topology
 *
 * Used to configure how vertices are assembled into primitives
 * before rasterization.
 */
enum class PrimitiveTopology : uint8_t {
    POINT_LIST,
    LINE_LIST,
    LINE_STRIP,
    TRIANGLE_LIST,
    TRIANGLE_STRIP,
    TRIANGLE_FAN
};
 
/**
 * @brief Whether two adjacent spans of this topology can be concatenated
 *        without altering the primitives they assemble.
 *
 * List topologies assemble each primitive from its own fixed-size group of
 * consecutive vertices, so appending one span to another adds primitives and
 * leaves existing ones untouched. Strip and fan topologies assemble each
 * primitive from vertices shared with its predecessor, so concatenation
 * fabricates an extra primitive spanning the join.
 */
[[nodiscard]] constexpr bool is_concatenable_topology(PrimitiveTopology topology) noexcept
{
    return topology == PrimitiveTopology::POINT_LIST
        || topology == PrimitiveTopology::LINE_LIST
        || topology == PrimitiveTopology::TRIANGLE_LIST;
}
 
//============================================================================
// Rasterization
//============================================================================
 
/**
 * @enum PolygonMode
 * @brief Rasterization polygon mode
 */
enum class PolygonMode : uint8_t {
    FILL,
    LINE,
    POINT
};
 
/**
 * @enum CullMode
 * @brief Face culling mode
 */
enum class CullMode : uint8_t {
    NONE,
    FRONT,
    BACK,
    FRONT_AND_BACK
};
 
//============================================================================
// Depth/Stencil
//============================================================================
 
/**
 * @enum CompareOp
 * @brief Depth/stencil comparison operation
 */
enum class CompareOp : uint8_t {
    NEVER,
    LESS,
    EQUAL,
    LESS_OR_EQUAL,
    GREATER,
    NOT_EQUAL,
    GREATER_OR_EQUAL,
    ALWAYS
};
 
//============================================================================
// Blending
//============================================================================
 
/**
 * @enum BlendFactor
 * @brief Blending factor
 */
enum class BlendFactor : uint8_t {
    ZERO,
    ONE,
    SRC_COLOR,
    ONE_MINUS_SRC_COLOR,
    DST_COLOR,
    ONE_MINUS_DST_COLOR,
    SRC_ALPHA,
    ONE_MINUS_SRC_ALPHA,
    DST_ALPHA,
    ONE_MINUS_DST_ALPHA
};
 
/**
 * @enum BlendOp
 * @brief Blending operation
 */
enum class BlendOp : uint8_t {
    ADD,
    SUBTRACT,
    REVERSE_SUBTRACT,
    MIN,
    MAX
};
 
//============================================================================
// GPU Buffer Bindings
//============================================================================
 
/**
 * @enum BufferUsageHint
 * @brief Semantic usage hint for buffer allocation and memory properties
 *
 * This enum describes the intended usage pattern of a buffer, which informs
 * the graphics backend how to allocate memory and set Vulkan usage flags.
 * It is not a direct mapping to Vulkan flags, but rather a higher-level
 * abstraction for common use cases.
 */
enum class BufferUsageHint : uint8_t {
    STAGING, ///< Host-visible staging buffer (CPU-writable, eTransferSrc|Dst)
    DEVICE, ///< Device-local GPU-only buffer
    COMPUTE, ///< Storage buffer for compute shaders (device-local)
    VERTEX, ///< Vertex buffer
    INDEX, ///< Index buffer
    UNIFORM, ///< Uniform buffer (host-visible)
    UNIFORM_BDA, ///< Uniform buffer with device address query support
    STORAGE_BDA, ///< Storage buffer with device address query support
    INDIRECT, ///< Indirect draw/dispatch buffer (device-local)
    HOST_STORAGE, ///< Host-visible storage buffer (eStorageBuffer + eHostVisible|eHostCoherent)
    COMPUTE_STORAGE, ///< Bare eStorageBuffer, no transfer flags. GpuResourceManager's host-visible/host-coherent compute buffers.
};
 
/**
 * @struct GpuBufferBinding
 * @brief Declares a single storage buffer or image binding a compute shader expects.
 *
 * Vulkan-agnostic description consumed by ComputePress/ShaderFoundry to
 * derive descriptor types, barrier targets, and staging behavior. Carries
 * no vk:: types itself; translation to vk::DescriptorType happens at the
 * point of use.
 */
struct GpuBufferBinding {
    uint32_t set { 0 }; ///< Descriptor set index.
    uint32_t binding { 0 }; ///< Binding index within the set.
    bool skip_auto_readback { false }; ///< Skip automatic CPU readback after dispatch for this binding.
 
    /**
     * @enum Direction
     * @brief Data flow direction for this binding.
     *
     * INPUT_OUTPUT bindings receive a cross-pass memory barrier when used
     * across multiple recorded dispatches in one command buffer (see
     * ComputePress::record_sequence), since the same resource is both
     * read and written by consecutive stages.
     */
    enum class Direction : uint8_t {
        INPUT,
        OUTPUT,
        INPUT_OUTPUT
    } direction { Direction::INPUT };
 
    /**
     * @enum ElementType
     * @brief Element type the shader expects in this binding.
     *
     * FLOAT32          — cast double channels to float (default).
     * UINT32           — reinterpret variant bytes as uint32_t.
     * INT32            — reinterpret variant bytes as int32_t.
     * PASSTHROUGH      — upload raw variant bytes with no cast; caller
     *                    must pre-stage for INPUT / INPUT_OUTPUT bindings.
     * IMAGE_STORAGE    — writeonly/readonly image2D, storage image descriptor.
     * IMAGE_SAMPLED    — sampler2D, combined image sampler descriptor.
     */
    enum class ElementType : uint8_t {
        FLOAT32,
        UINT32,
        INT32,
        PASSTHROUGH,
        IMAGE_STORAGE,
        IMAGE_SAMPLED
    } element_type { ElementType::FLOAT32 };
 
    BufferUsageHint usage_hint { BufferUsageHint::COMPUTE_STORAGE }; ///< Hint for buffer allocation and memory properties.
};
 
/**
 * @brief Byte width of one GpuBufferBinding::ElementType element.
 *
 * Bridges to Kakshya::gpu_data_format_bytes for FLOAT32/UINT32/INT32,
 * the single authoritative sizing source. Returns 0 for PASSTHROUGH,
 * IMAGE_STORAGE, and IMAGE_SAMPLED, which carry no fixed element width.
 *
 * @param et ElementType to size.
 * @return Byte width, or 0 if unsized.
 */
[[nodiscard]] MAYAFLUX_API size_t element_type_bytes(GpuBufferBinding::ElementType et) noexcept;
 
//============================================================================
// Shader Types
//============================================================================
 
/**
 * @enum ShaderStage
 * @brief User-friendly shader stage enum
 *
 * Abstracts vk::ShaderStageFlagBits for Portal API convenience.
 * Maps directly to Vulkan stages internally.
 */
enum class ShaderStage : uint8_t {
    COMPUTE,
    VERTEX,
    FRAGMENT,
    GEOMETRY,
    TESS_CONTROL,
    TESS_EVALUATION,
    MESH,
    TASK
};
 
//============================================================================
// Image Helpers
//============================================================================
 
/**
 * @brief Portal name for Kakshya::ImageFormat, which maps to vk::Format in TextureLoom.
 */
using ImageFormat = Kakshya::ImageFormat;
 
/**
 * @enum FilterMode
 * @brief Texture filtering mode
 */
enum class FilterMode : uint8_t {
    NEAREST, ///< Nearest neighbor (pixelated)
    LINEAR, ///< Bilinear filtering (smooth)
    CUBIC ///< Bicubic filtering (high quality, slower)
};
 
/**
 * @enum AddressMode
 * @brief Texture addressing mode (wrapping)
 */
enum class AddressMode : uint8_t {
    REPEAT, ///< Repeat texture
    MIRRORED_REPEAT, ///< Mirror and repeat
    CLAMP_TO_EDGE, ///< Clamp to edge color
    CLAMP_TO_BORDER ///< Clamp to border color
};
 
/**
 * @enum BorderColor
 * @brief Color read outside the texture when an address mode is CLAMP_TO_BORDER
 */
enum class BorderColor : uint8_t {
    DEFAULT, ///< The sampler's historical border, opaque black
    TRANSPARENT_BLACK, ///< Zero in every channel
    OPAQUE_BLACK, ///< Black with full alpha
    OPAQUE_WHITE ///< White with full alpha
};
 
/**
 * @struct SamplerConfig
 * @brief Sampler configuration
 */
struct SamplerConfig {
    FilterMode mag_filter = FilterMode::LINEAR;
    FilterMode min_filter = FilterMode::LINEAR;
    AddressMode address_mode_u = AddressMode::REPEAT;
    AddressMode address_mode_v = AddressMode::REPEAT;
    AddressMode address_mode_w = AddressMode::REPEAT;
    float max_anisotropy = 1.0F; // 1.0 = disabled, 16.0 = max quality
    bool enable_mipmaps = false;
    BorderColor border_color = BorderColor::DEFAULT;
};
 
/**
 * @enum FitMode
 * @brief How a source extent is mapped onto a destination extent
 */
enum class FitMode : uint8_t {
    STRETCH, ///< Whole source onto whole destination, aspect ignored
    CONTAIN, ///< Whole source, aspect kept, centered, the rest left uncovered
    COVER, ///< Aspect kept, destination filled, source cropped
    CENTER, ///< No scaling, centered, clipped to the destination
    TILE, ///< Source repeated at its own size
    TILE_MIRRORED ///< Source repeated, every other tile mirrored
};
 
 
/**
 * @struct RenderConfig
 * @brief Unified rendering configuration for graphics buffers
 *
 * This is the persistent state that processors query and react to.
 * All rendering parameters in one place, independent of buffer type.
 * Child buffer classes populate it with context-specific defaults
 * during construction, then expose it to their processors.
 *
 * Design:
 * - Owned by VKBuffer as persistent state
 * - Processors query and react to changes
 * - Child classes have their own convenience RenderConfig with defaults
 *   that bridge to this Portal-level config
 */
struct RenderConfig {
    std::shared_ptr<Core::Window> target_window;
    std::string vertex_shader;
    std::string fragment_shader;
    std::string geometry_shader;
    std::string default_texture_binding;
    PrimitiveTopology topology { PrimitiveTopology::POINT_LIST };
    PolygonMode polygon_mode { PolygonMode::FILL };
    CullMode cull_mode { CullMode::NONE };
 
    /**
     * @brief Reduce supplied spans to triangles before drawing them.
     *
     * @c topology describes span ordering, not the pipeline: it is always
     * built TRIANGLE_LIST, no geometry stage on any platform, and each span
     * is milled into quads/ribbons before one draw. Applies to any span
     * shape on any platform; macOS additionally forces it on for
     * LINE_LIST/LINE_STRIP since line.geom (NDC expansion) isn't available
     * there.
     *
     * A custom vertex_shader is unchanged: same attributes, same transform
     * to clip space. A custom fragment_shader needs one new thing: every
     * span shares one fragment shader, so @c \#include "include/mill_shape.glsl"
     * and check @c mill_is_point(in_uv) to tell a point quad from a
     * ribbon/passthrough-triangle fragment. milled_shape.frag/_textured/_multi
     * are reference implementations (the multi variant's array index shares
     * MillSpec's per-vertex size slot -- set use_vertex_extent = false to
     * decouple them).
     *
     * Resolved at configuration time, not inferred from spans arriving,
     * since shader/topology/geometry-stage selection happen here while
     * spans arrive per frame.
     */
    bool triangulate { false };
 
    std::vector<std::pair<std::string, std::shared_ptr<Core::VKImage>>> additional_textures;
 
    /**
     * @brief Clip this buffer's draws to an NDC region.
     *
     * Unset means the full framebuffer, matching the behavior before this
     * field existed. Set via Kinesis::Scissor::from(bounds), from(anchor)
     * for anything exposing bounds(), or from(aabb3d, view_transform) to
     * project a world-space box.
     */
    std::optional<Kinesis::Scissor> scissor;
 
    ///< For child-specific fields
    std::unordered_map<std::string, std::string> extra_string_params;
 
    /// @brief Draw-order priority. Higher sorts later (drawn on top). Default 0.
    int64_t draw_priority {};
 
    bool operator==(const RenderConfig& other) const = default;
};
 
/**
 * @struct DrawRun
 * @brief One contiguous span of vertices sharing a primitive topology.
 *
 * The topology declares how this span's vertices are ordered, not which
 * pipeline draws it. A consumer configured to triangulate reduces every span to
 * triangles and draws them all with one call, turning points into quads and
 * line segments into ribbons, so a set of spans of differing topology still
 * resolves to a single draw.
 *
 * Carries no knowledge of what produced it: an operator's collections, an
 * arena's per-element sub-ranges, or anything else. Producers build these; the
 * consumer shapes and draws them.
 */
struct DrawRun {
    PrimitiveTopology topology {};
    uint32_t vertex_offset {};
    uint32_t vertex_count {};
};
 
/**
 * @brief Vertices a span of @p n at @p topology yields once reduced to a
 *        TRIANGLE_LIST, with points becoming quads and line segments ribbons.
 *
 * Closed form, so a caller can size a destination or budget a dispatch without
 * inspecting vertex data. Spans too short to assemble a primitive yield zero
 * rather than underflowing, and list topologies floor to whole primitives, so
 * an odd LINE_LIST count drops its dangling vertex instead of reading past the
 * span.
 */
[[nodiscard]] constexpr uint32_t triangle_vertex_count(
    PrimitiveTopology topology,
    uint32_t n) noexcept
{
    switch (topology) {
    case PrimitiveTopology::POINT_LIST:
        return 6U * n;
    case PrimitiveTopology::LINE_LIST:
        return 6U * (n / 2U);
    case PrimitiveTopology::LINE_STRIP:
        return n < 2U ? 0U : 6U * (n - 1U);
    case PrimitiveTopology::TRIANGLE_LIST:
        return 3U * (n / 3U);
    case PrimitiveTopology::TRIANGLE_STRIP:
    case PrimitiveTopology::TRIANGLE_FAN:
        return n < 3U ? 0U : 3U * (n - 2U);
    }
    return 0U;
}
 
}