RelaxationGridBuffer.hpp

Go to the documentation of this file.

#pragma once
 
#include "MayaFlux/Buffers/VKBuffer.hpp"
#include "MayaFlux/Portal/Graphics/ShaderSpec.hpp"
#include "MayaFlux/Vruta/BroadcastSource.hpp"
 
namespace MayaFlux::Buffers {
 
class RelaxationStepProcessor;
class RelaxationEmitProcessor;
class RenderProcessor;
 
/**
 * @class RelaxationGridBuffer
 * @brief GPU-resident, double-buffered SSBO state for synchronous
 *        local-rule systems evaluated over a fixed 2D topology: cellular
 *        automata, Jacobi/Gauss-Seidel relaxation, discrete diffusion, and
 *        any rule where every cell updates from its own and neighbors'
 *        previous-generation state.
 *
 * Grid state lives entirely as two raw Vulkan handle pairs inside
 * VKBufferResources::back_buffers, allocated once at construction. No
 * VKBuffer object represents the grid state at any point; descriptor
 * writes for these handles are issued directly against ShaderFoundry by
 * RelaxationStepProcessor and RelaxationEmitProcessor, bypassing
 * ShaderProcessor::bind_buffer entirely, since that call requires a
 * VKBuffer wrapper this design does not create.
 *
 * The VKBuffer base itself (this object) owns only the emitted vertex
 * output (Usage::VERTEX), written each generation by
 * RelaxationEmitProcessor from the front generation's state, then drawn
 * directly by RenderProcessor as ordinary untextured point geometry.
 *
 * Chain order:
 *   default  — RelaxationStepProcessor (rule shader: state front -> back)
 *   flat[0]  — RelaxationEmitProcessor (emit shader: front state -> vertices)
 *   final    — RenderProcessor
 *
 * Snapshot delivery uses a BroadcastSource<std::vector<uint8_t>>, owned by
 * this buffer and exposed via snapshot_source(). RelaxationStepProcessor
 * signals it directly once a requested download completes; there is no
 * intermediate queue or poll. Subscribe via Kriya::on_signal() or
 * on_signal_matching() at whatever cadence the caller chooses — the class
 * imposes none.
 *
 * Usage:
 * @code
 * auto grid = std::make_shared<RelaxationGridBuffer>(
 *     256, 256, sizeof(uint32_t), "ca_rule.comp", "ca_emit.comp");
 * grid->setup_processors(ProcessingToken::GRAPHICS_BACKEND);
 * grid->setup_rendering({ .target_window = window });
 * @endcode
 */
class MAYAFLUX_API RelaxationGridBuffer : public VKBuffer {
public:
    /**
     * @brief Either a shader file path or a generated ShaderSpec, resolved at
     *        construction time by setup_processors().
     */
    using ShaderSource = std::variant<std::string, Portal::Graphics::ShaderSpec>;
 
    /**
     * @struct GridConfig
     * @brief Arrangement of a relaxation grid: extent, the update rule, the
     *        emit stage that draws it, and their constants.
     *
     * Carries what varies between grids. What does not vary is fixed by the
     * processors: stage order (rule, then emit, then render), the leading
     * push constant prefixes, and the dispatch tiling. A rule shader
     * declares GridExtent first and uses a 16x16 local size. An emit shader
     * declares EmitParams first, uses a 256 local size, and writes one packed
     * Kakshya::Vertex per cell.
     *
     * Names no rule. Any ShaderSource meeting those contracts is a rule,
     * generated or hand-written.
     *
     * Structural: width, height, and every Stage::state and Stage::shader.
     * They decide buffer sizes and which processors are built, so they are
     * fixed at construction. Stage::constants initialize trailing push
     * constant words during setup_processors. They establish that footprint
     * for path shaders, while generated specs declare it themselves. Every
     * word in the resulting block remains live-tunable through
     * RelaxationStepProcessor::set_constant and
     * RelaxationEmitProcessor::set_constant. extent and point_size are
     * live-tunable through RelaxationEmitProcessor::set_extent and
     * set_point_size. Float feeds remain available through
     * ShaderProcessor::feed at an explicit byte offset.
     */
    struct GridConfig {
        /** @brief One 4-byte push constant word, in the scalar types a shader block can hold. */
        using Constant = std::variant<uint32_t, int32_t, float>;
 
        /**
         * @struct Stage
         * @brief One compute stage of the grid, rule or emit.
         */
        struct Stage {
            std::optional<Kakshya::GpuDataFormat> state; ///< Format of one cell as this stage reads it. Nullopt derives it from the ShaderSpec binding ("state_in" for a rule, "cell_state" for an emit). Required when shader is a path.
            ShaderSource shader; ///< Hand-written shader path or generated ShaderSpec.
            std::vector<Constant> constants; ///< Initial words after the stage's fixed prefix (GridExtent for a rule, EmitParams for an emit), in shader declaration order. Required to establish trailing words for path shaders.
        };
 
        uint32_t width; ///< Grid width in cells. Required.
        uint32_t height; ///< Grid height in cells. Required.
        Stage rule; ///< Required. Reads "state_in", writes "state_out".
        Stage emit; ///< Required. Reads "cell_state", writes packed vertices.
        float extent { 1.0F }; ///< NDC half-span the grid occupies.
        float point_size { 2.0F }; ///< Per-point size written to the vertex scalar field.
    };
 
    /**
     * @brief Construct an unregistered double-buffered grid buffer.
     * @param width Grid width in cells.
     * @param height Grid height in cells.
     * @param cell_stride_bytes Size in bytes of one cell's state.
     * @param rule_source Either a path to a hand-written rule shader (for
     *        rules needing branchy multi-state logic, e.g. Conway, Wireworld)
     *        or a generated ShaderSpec (e.g. RelaxationSpecs::jacobi_diffusion()).
     * @param emit_source Either a path to a hand-written emit shader, or a
     *        generated ShaderSpec that meets the packed vertex contract.
     *
     * rule_source and emit_source are independent: any pairing meeting their
     * respective contracts is supported. Processors are constructed from
     * whichever alternative each holds in setup_processors().
     */
    RelaxationGridBuffer(
        uint32_t width,
        uint32_t height,
        size_t cell_stride_bytes,
        ShaderSource rule_source,
        ShaderSource emit_source);
 
    /**
     * @brief Construct from a GridConfig.
     * @param config Grid arrangement.
     * @throws std::invalid_argument When a path stage declares no state,
     *         when rule and emit disagree on the cell format, or when the
     *         format is a three component vector, whose std430 array stride
     *         (16 bytes) differs from gpu_data_format_bytes.
     *
     * Derives the cell stride from the stage format and delegates to the
     * positional constructor.
     */
    explicit RelaxationGridBuffer(const GridConfig& config);
 
    /**
     * @brief Destructor.
     *
     * Raw handles in m_resources.back_buffers are released by the backend
     * during buffer service teardown, consistent with how VKBuffer's own
     * primary buffer/memory are released; this class performs no manual
     * Vulkan destruction itself.
     */
    ~RelaxationGridBuffer() override = default;
 
    /**
     * @brief Create and attach RelaxationStepProcessor (default processor)
     *        and RelaxationEmitProcessor (flat processor), and set the
     *        per-cell vertex layout on this buffer's own storage.
     * @param token Processing domain (typically GRAPHICS_BACKEND).
     */
    void setup_processors(ProcessingToken token) override;
 
    /**
     * @brief Attach a RenderProcessor drawing the emitted vertex output as
     *        ordinary untextured point geometry.
     * @param config Render target; vertex/fragment shaders default to the
     *               standard untextured pair unless overridden. Topology
     *               is always forced to POINT_LIST regardless of what is
     *               supplied in @p config.
     */
    void setup_rendering(const RenderConfig& config);
 
    /** @brief Grid width in cells. */
    [[nodiscard]] uint32_t get_grid_width() const { return m_width; }
 
    /** @brief Grid height in cells. */
    [[nodiscard]] uint32_t get_grid_height() const { return m_height; }
 
    /** @brief Total cell count, width * height. */
    [[nodiscard]] uint32_t get_cell_count() const { return m_width * m_height; }
 
    /** @brief Total byte size of one generation's state buffer. */
    [[nodiscard]] size_t get_state_bytes() const
    {
        return static_cast<size_t>(m_width) * m_height * m_cell_stride_bytes;
    }
 
    /**
     * @brief Size in bytes of one cell's state, fixed at construction.
     *
     * A caller reinterpreting request_snapshot()/snapshot_source()'s raw
     * bytes needs this to know how to slice them into individual cells:
     * get_state_bytes() alone gives only the total, and state format
     * genuinely varies by rule (a single float, a uint32 automaton state,
     * a vec2 reaction-diffusion pair, or anything else a rule shader
     * defines), so nothing here can infer it.
     */
    [[nodiscard]] size_t get_cell_stride_bytes() const { return m_cell_stride_bytes; }
 
    /**
     * @brief Write initial state directly into the current front generation.
     * @param data Pointer to cell_count * cell_stride_bytes of state data.
     * @param size Byte count; must equal get_state_bytes().
     *
     * Direct host-visible memcpy into back_buffers[front_index()], mirroring
     * VKBuffer::set_data's own host-visible write path. Valid only before the
     * buffer's processing chain has run at least once, or between generations
     * where overwriting the current front state is intended (e.g. a runtime
     * reset). Does not touch the back generation or trigger a swap.
     */
    void seed_state(const void* data, size_t size);
 
    /**
     * @brief Index into m_resources.back_buffers currently holding the
     *        most recently completed generation's state.
     */
    [[nodiscard]] uint32_t front_index() const { return m_front_is_a ? 0 : 1; }
 
    /**
     * @brief Index into m_resources.back_buffers currently serving as the
     *        write target for the next rule dispatch.
     */
    [[nodiscard]] uint32_t back_index() const { return m_front_is_a ? 1 : 0; }
 
    /**
     * @brief Request a snapshot of the next completed generation.
     *
     * Wait-free. Served by RelaxationStepProcessor after the next cycle that
     * dispatches, once that dispatch has completed: a device-to-host copy of
     * the newly-front state buffer is signalled on snapshot_source().
     */
    void request_snapshot() { m_snapshot_requested.store(true, std::memory_order_release); }
 
    /**
     * @brief BroadcastSource of completed generation snapshots.
     *
     * Signaled by RelaxationStepProcessor exactly once per fulfilled
     * request_snapshot() call, at the point the device-to-host download
     * actually completes — not polled, not tied to any particular pacing.
     * Subscribe via Kriya::on_signal()/on_signal_matching() at whatever
     * cadence suits the caller; the class itself imposes none.
     */
    [[nodiscard]] std::shared_ptr<Vruta::BroadcastSource<std::vector<uint8_t>>> snapshot_source() const
    {
        return m_snapshot_source;
    }
 
    /** @brief The attached rule-stage processor, valid after setup_processors(). */
    [[nodiscard]] std::shared_ptr<RelaxationStepProcessor> step_processor() const { return m_step_processor; }
 
    /** @brief The attached emit-stage processor, valid after setup_processors(). */
    [[nodiscard]] std::shared_ptr<RelaxationEmitProcessor> emit_processor() const { return m_emit_processor; }
 
    /**
     * @brief The rule source this buffer was constructed with: either a
     *        hand-written shader path or a generated ShaderSpec.
     *
     * For a caller building descriptive metadata (a rule name/identity
     * tag) about a capture rather than for driving the pipeline itself,
     * which goes through setup_processors() instead.
     */
    [[nodiscard]] const ShaderSource& rule_source() const { return m_rule_source; }
 
    /** @brief The emit source this buffer was constructed with. See rule_source(). */
    [[nodiscard]] const ShaderSource& emit_source() const { return m_emit_source; }
 
private:
    friend class RelaxationStepProcessor;
    friend class RelaxationEmitProcessor;
 
    [[nodiscard]] bool consume_snapshot_request()
    {
        return m_snapshot_requested.exchange(false, std::memory_order_acq_rel);
    }
 
    inline void swap_generation() { m_front_is_a = !m_front_is_a; }
 
    /** @brief Signaled by RelaxationStepProcessor when a requested snapshot completes. */
    std::shared_ptr<Vruta::BroadcastSource<std::vector<uint8_t>>> m_snapshot_source {
        std::make_shared<Vruta::BroadcastSource<std::vector<uint8_t>>>()
    };
 
    uint32_t m_width; ///< Grid width in cells.
    uint32_t m_height; ///< Grid height in cells.
    size_t m_cell_stride_bytes; ///< Size in bytes of one cell's state, fixed at construction.
    std::vector<GridConfig::Constant> m_rule_constants; ///< Rule constants from GridConfig, written at setup_processors.
    std::vector<GridConfig::Constant> m_emit_constants; ///< Emit constants from GridConfig, written at setup_processors.
    float m_extent { 1.0F }; ///< Emit extent applied at setup_processors.
    float m_point_size { 2.0F }; ///< Emit point size applied at setup_processors.
 
    ShaderSource m_rule_source; ///< Either a path to a hand-written rule shader or a generated ShaderSpec.
    ShaderSource m_emit_source; ///< Either a path to a hand-written emit shader or a generated ShaderSpec.
 
    bool m_front_is_a { true }; ///< True when back_buffers[0] holds the current front generation.
    std::atomic<bool> m_snapshot_requested { false }; ///< Set by request_snapshot(), cleared by consume_snapshot_request().
 
    std::shared_ptr<RelaxationStepProcessor> m_step_processor; ///< Rule stage, retained for parameter access.
    std::shared_ptr<RelaxationEmitProcessor> m_emit_processor; ///< Emit stage, retained for parameter access.
};
 
} // namespace MayaFlux::Buffers