FormaBuffer.hpp

Go to the documentation of this file.

#pragma once
 
#include "MayaFlux/Buffers/Staging/SliceSet.hpp"
#include "MayaFlux/Buffers/VKBuffer.hpp"
 
namespace MayaFlux::Core {
class Window;
}
 
namespace MayaFlux::Buffers {
class FormaProcessor;
class RenderProcessor;
 
/**
 * @class FormaBuffer
 * @brief VKBuffer for 2D screen-space Forma geometry.
 *
 * Encodes the invariants that hold for all Forma geometry:
 *   - No depth test, no depth write, no view transform.
 *   - Alpha blending enabled on the RenderProcessor.
 *   - Topology fixed at construction (determines default shaders).
 *
 * Provides write_bytes() as the clean write interface for Mapped::sync(),
 * replacing the raw set_data path on plain VKBuffer.
 *
 * Usage:
 * @code
 * auto buf = std::make_shared<FormaBuffer>(
 *     initial_capacity_bytes,
 *     Portal::Graphics::PrimitiveTopology::TRIANGLE_STRIP);
 * buf->setup_processors(ProcessingToken::GRAPHICS_BACKEND);
 * buf->setup_rendering({ .target_window = window });
 * @endcode
 */
class MAYAFLUX_API FormaBuffer : public Buffers::VKBuffer {
public:
    /**
     * @brief Construct a FormaBuffer.
     * @param capacity_bytes  Initial buffer capacity. Size the buffer for the
     *                        maximum expected vertex count from the geometry
     *                        function. write_bytes() will warn if exceeded.
     * @param topology        Primitive topology. Determines default shaders
     *                        selected in setup_rendering().
     */
    FormaBuffer(
        size_t capacity_bytes,
        Portal::Graphics::PrimitiveTopology topology);
 
    /**
     * @brief Construct a FormaBuffer.
     * @param topology        Primitive topology. Determines default shaders
     *                        selected in setup_rendering().
     */
    FormaBuffer(
        Portal::Graphics::PrimitiveTopology topology);
 
    ~FormaBuffer() override = default;
 
    FormaBuffer(const FormaBuffer&) = delete;
    FormaBuffer& operator=(const FormaBuffer&) = delete;
    FormaBuffer(FormaBuffer&&) = delete;
    FormaBuffer& operator=(FormaBuffer&&) = delete;
 
    /**
     * @brief Register with the graphics subsystem.
     *        Creates a BufferUploadProcessor as default processor.
     */
    void setup_processors(ProcessingToken token) override;
 
    /**
     * @brief Attach a RenderProcessor targeting the given window.
     *
     * Selects default shaders from topology set at construction. Always
     * enables alpha blending, disables depth testing. Caller may override
     * shaders via config fields.
     *
     * TRIANGLE_LIST/TRIANGLE_STRIP picks its fragment shader from texture
     * state (forma_multi/forma_textured/triangle.frag) regardless of
     * @c triangulate -- PrimitiveMill's triangle pass copies UV unchanged,
     * so texturing stays correct either way; it never falls back to
     * milled_shape.frag, which would blank every textured scene.
     *
     * POINT_LIST does switch under triangulate, to milled_shape.vert plus
     * milled_shape.frag/_textured/_multi depending on texture state
     * (point.frag's gl_PointCoord is meaningless once forced TRIANGLE_LIST).
     * The multi variant's array index shares the scalar slot PrimitiveMill
     * reads as point size -- set_mill_spec(use_vertex_extent = false)
     * decouples them; left default, size and index are the same number.
     */
    void setup_rendering(const RenderConfig& config);
 
    /**
     * @brief Write vertex bytes into the buffer.
     *
     * Called by Mapped::sync() each time the geometry function produces
     * new vertex data. Copies bytes into the mapped host-visible region
     * and marks the dirty range for flush on the next graphics tick.
     *
     * @param bytes Raw interleaved vertex bytes. Must not exceed the
     *              capacity set at construction.
     */
    void submit(const std::vector<uint8_t>& bytes);
 
    using SliceId = SliceSet::SliceId;
 
    /**
     * @brief Add a block of vertices that shares this buffer with the others.
     *
     * submit() writes a default block of its own, so a buffer used only
     * through submit() holds one. Blocks share the buffer's topology and are
     * uploaded together; each can be updated, hidden or reordered without
     * touching the rest. Several blocks cost one draw when they are adjacent,
     * visible and in order.
     *
     * Valid once setup_processors() has run.
     *
     * @param bytes Whole interleaved vertices matching the topology; a trailing
     *              partial vertex is dropped.
     * @param topology Topology of this block; the buffer's when omitted. A
     *              different topology needs setup_rendering with triangulate,
     *              which draws mixed blocks as one batch.
     * @return Id of the block, or 0 when the buffer has no processor yet.
     */
    SliceId add_slice(const std::vector<uint8_t>& bytes,
        std::optional<Portal::Graphics::PrimitiveTopology> topology = std::nullopt);
 
    /** @brief Replace a block's vertices; later blocks shift if the size changes. */
    void update_slice(SliceId id, const std::vector<uint8_t>& bytes);
 
    /** @brief Number of blocks, 0 before setup_processors(). */
    [[nodiscard]] size_t slice_count() const noexcept;
 
    /** @brief True when @p id names a live block. */
    [[nodiscard]] bool has_slice(SliceId id) const noexcept;
 
    /** @brief Remove a block; later blocks shift down. */
    void remove_slice(SliceId id);
 
    /** @brief Hide or show a block without moving its data. */
    void set_slice_visible(SliceId id, bool visible);
 
    /** @brief Draw a block after every other. */
    void bring_slice_to_front(SliceId id);
 
    /** @brief Draw a block before every other. */
    void send_slice_to_back(SliceId id);
 
    /**
     * @brief Supply a texture to be bound on the next graphics tick.
     *
     * The image is owned externally — a TextBuffer's VKImage from
     * InkPress, a loaded asset, a render target, anything. FormaProcessor
     * forwards it to the RenderProcessor on the next processing_function
     * call. Calling again replaces the previous binding.
     *
     * @param image   GPU image to bind. nullptr clears the binding.
     * @param binding Descriptor name in the shader (e.g. "texSampler").
     */
    void set_texture(std::shared_ptr<Core::VKImage> image, std::string binding);
 
    /**
     * @brief Bind a texture to a slot in the multi-texture array at runtime.
     *
     * Valid only when setup_rendering was called with additional_textures.
     * @p array_index is 0-based into the array declared at setup time:
     *   index 0 = weight 1, index 1 = weight 2, etc.
     *
     * @param array_index Zero-based index into the textures[] array.
     * @param image       GPU image. Must be GPU-resident.
     */
    void bind_texture(uint32_t array_index, const std::shared_ptr<Core::VKImage>& image);
 
    [[nodiscard]] Portal::Graphics::PrimitiveTopology topology() const { return m_topology; }
 
    /**
     * @brief Submit a contiguous sequence of vertices.
     *
     * Accepts any contiguous range of trivially-copyable vertex structs:
     * std::array, std::vector, std::span, or a raw pointer + count pair.
     * Reinterprets the data as bytes and forwards to the primary submit().
     *
     * @tparam V  Vertex type. Must be trivially copyable.
     * @param vertices  Contiguous range of V.
     */
    template <typename V>
        requires std::ranges::contiguous_range<V>
        && std::is_trivially_copyable_v<std::ranges::range_value_t<V>>
    void submit(const V& vertices)
    {
        const auto* src = reinterpret_cast<const uint8_t*>(std::ranges::data(vertices));
        const size_t n = std::ranges::size(vertices) * sizeof(std::ranges::range_value_t<V>);
        submit(std::vector<uint8_t>(src, src + n));
    }
 
    /**
     * @brief Submit a single vertex struct.
     *
     * Convenience for point-list buffers and single-primitive cases where
     * constructing a container for one vertex is unnecessary.
     *
     * @tparam V  Vertex type. Must be trivially copyable.
     * @param vertex  The vertex to write.
     */
    template <typename V>
        requires std::is_trivially_copyable_v<V>
        && (!std::ranges::range<V>)
    void submit(const V& vertex)
    {
        const auto* src = reinterpret_cast<const uint8_t*>(&vertex);
        submit(std::vector<uint8_t>(src, src + sizeof(V)));
    }
 
private:
    Portal::Graphics::PrimitiveTopology m_topology;
    std::shared_ptr<Buffers::FormaProcessor> m_processor;
 
    /// @brief Geometry bytes from submit() before setup_processors(). Drained in setup_processors().
    std::vector<uint8_t> m_pending_geometry;
 
    /// @brief Textures from set_texture() before setup_processors(). Drained in setup_processors().
    std::vector<std::pair<std::shared_ptr<Core::VKImage>, std::string>> m_pending_textures;
};
 
} // namespace MayaFlux::Buffers