gpu_pass.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/render/gpu_capabilities.hpp>
#include <pulp/render/gpu_surface.hpp>
#include <pulp/render/wgsl_diagnostics.hpp>
#include <pulp/runtime/result.hpp>
 
#include <array>
#include <chrono>
#include <cstddef>
#include <cstdint>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <vector>
 
namespace pulp::canvas {
class Canvas;
}
 
namespace pulp::render {
 
namespace detail {
struct GpuDeviceState;
struct GpuTextureState;
struct GpuBufferState;
struct GpuSamplerState;
struct GpuShaderModuleState;
struct GpuRenderPipelineState;
struct GpuComputePipelineState;
struct GpuBindGroupState;
struct GpuTargetState;
struct GpuFrameState;
struct GpuSubmissionState;
struct GpuAccess;
} // namespace detail
 
// ── Errors ───────────────────────────────────────────────────────────────
 
struct GpuError {
    enum class Kind : std::uint8_t {
        unavailable,
        invalid_argument,
        shader_compilation,
        validation,
        out_of_memory,
        internal,
        device_lost,
        timeout,
    };
 
    Kind kind = Kind::internal;
    std::string message;
    std::vector<WgslDiagnostic> diagnostics;

    std::string describe() const;
};
 
std::string_view gpu_error_kind_name(GpuError::Kind kind);
 
template <typename T> using GpuResult = runtime::Result<T, GpuError>;
using GpuStatus = runtime::Result<void, GpuError>;
 
// ── Flags ────────────────────────────────────────────────────────────────

enum class GpuTextureUsage : std::uint32_t {
    none = 0,
    copy_src = 1u << 0,
    copy_dst = 1u << 1,
    sampled = 1u << 2,
    storage = 1u << 3,
    render_target = 1u << 4,
};

enum class GpuBufferUsage : std::uint32_t {
    none = 0,
    map_read = 1u << 0,
    map_write = 1u << 1,
    copy_src = 1u << 2,
    copy_dst = 1u << 3,
    index = 1u << 4,
    vertex = 1u << 5,
    uniform = 1u << 6,
    storage = 1u << 7,
};
 
constexpr GpuTextureUsage operator|(GpuTextureUsage a, GpuTextureUsage b) {
    return static_cast<GpuTextureUsage>(static_cast<std::uint32_t>(a) |
                                        static_cast<std::uint32_t>(b));
}
constexpr bool has_usage(GpuTextureUsage set, GpuTextureUsage bit) {
    return (static_cast<std::uint32_t>(set) & static_cast<std::uint32_t>(bit)) != 0;
}
constexpr GpuBufferUsage operator|(GpuBufferUsage a, GpuBufferUsage b) {
    return static_cast<GpuBufferUsage>(static_cast<std::uint32_t>(a) |
                                       static_cast<std::uint32_t>(b));
}
constexpr bool has_usage(GpuBufferUsage set, GpuBufferUsage bit) {
    return (static_cast<std::uint32_t>(set) & static_cast<std::uint32_t>(bit)) != 0;
}
 
// ── Resources ────────────────────────────────────────────────────────────
 
struct GpuTextureDesc {
    std::uint32_t width = 0;
    std::uint32_t height = 0;
    GpuFormat format = GpuFormat::rgba8_unorm;
    GpuTextureUsage usage =
        GpuTextureUsage::render_target | GpuTextureUsage::sampled | GpuTextureUsage::copy_src;
    std::uint32_t sample_count = 1;
    std::string label;
};
 
class GpuTexture {
  public:
    GpuTexture() = default;
    bool valid() const noexcept;
    std::uint32_t width() const noexcept;
    std::uint32_t height() const noexcept;
    GpuFormat format() const noexcept;
    GpuTextureUsage usage() const noexcept;
    std::uint32_t sample_count() const noexcept;
 
  private:
    friend struct detail::GpuAccess;
    std::shared_ptr<detail::GpuTextureState> state_;
};
 
struct GpuBufferDesc {
    std::uint64_t size = 0;
    GpuBufferUsage usage = GpuBufferUsage::uniform | GpuBufferUsage::copy_dst;
    std::string label;
};
 
class GpuBuffer {
  public:
    GpuBuffer() = default;
    bool valid() const noexcept;
    std::uint64_t size() const noexcept;
    GpuBufferUsage usage() const noexcept;
 
  private:
    friend struct detail::GpuAccess;
    std::shared_ptr<detail::GpuBufferState> state_;
};
 
struct GpuSamplerDesc {
    bool linear = true;
    bool repeat = false;
    std::string label;
};
 
class GpuSampler {
  public:
    GpuSampler() = default;
    bool valid() const noexcept;
 
  private:
    friend struct detail::GpuAccess;
    std::shared_ptr<detail::GpuSamplerState> state_;
};

class GpuShaderModule {
  public:
    GpuShaderModule() = default;
    bool valid() const noexcept;
    const std::vector<WgslDiagnostic>& warnings() const noexcept;
 
  private:
    friend struct detail::GpuAccess;
    std::shared_ptr<detail::GpuShaderModuleState> state_;
};
 
// ── Pipelines ────────────────────────────────────────────────────────────
 
enum class GpuVertexFormat : std::uint8_t {
    float32,
    float32x2,
    float32x3,
    float32x4,
    uint32,
    sint32,
    unorm8x4,
};
 
struct GpuVertexAttribute {
    GpuVertexFormat format = GpuVertexFormat::float32x2;
    std::uint64_t offset = 0;
    std::uint32_t location = 0;
};
 
struct GpuVertexBufferLayout {
    std::uint64_t stride = 0;
    bool per_instance = false;
    std::vector<GpuVertexAttribute> attributes;
};
 
enum class GpuBlend : std::uint8_t {
    replace,
    alpha,
    premultiplied,
    additive,
};
 
enum class GpuPrimitiveTopology : std::uint8_t {
    triangle_list,
    triangle_strip,
    line_list,
    line_strip,
    point_list,
};
 
enum class GpuCullMode : std::uint8_t { none, front, back };
 
enum class GpuCompare : std::uint8_t {
    never,
    less,
    less_equal,
    greater,
    greater_equal,
    equal,
    not_equal,
    always,
};
 
struct GpuColorTargetDesc {
    GpuFormat format = GpuFormat::rgba8_unorm;
    GpuBlend blend = GpuBlend::replace;
};
 
struct GpuDepthStateDesc {
    GpuFormat format = GpuFormat::depth24_plus;
    bool write = true;
    GpuCompare compare = GpuCompare::less;
};
 
struct GpuRenderPipelineDesc {
    GpuShaderModule module;
    std::string vertex_entry = "vs_main";
    std::optional<GpuShaderModule> fragment_module;
    std::string fragment_entry = "fs_main";
    std::vector<GpuVertexBufferLayout> vertex_buffers;
    std::vector<GpuColorTargetDesc> color_targets{GpuColorTargetDesc{}};
    std::optional<GpuDepthStateDesc> depth;
    GpuPrimitiveTopology topology = GpuPrimitiveTopology::triangle_list;
    GpuCullMode cull = GpuCullMode::none;
    std::uint32_t sample_count = 1;
    std::string label;
};
 
class GpuRenderPipeline {
  public:
    GpuRenderPipeline() = default;
    bool valid() const noexcept;
 
  private:
    friend struct detail::GpuAccess;
    std::shared_ptr<detail::GpuRenderPipelineState> state_;
};
 
struct GpuComputePipelineDesc {
    GpuShaderModule module;
    std::string entry = "main";
    std::string label;
};
 
class GpuComputePipeline {
  public:
    GpuComputePipeline() = default;
    bool valid() const noexcept;
 
  private:
    friend struct detail::GpuAccess;
    std::shared_ptr<detail::GpuComputePipelineState> state_;
};

struct GpuBinding {
    enum class Kind : std::uint8_t { buffer, texture, sampler };
 
    std::uint32_t binding = 0;
    Kind kind = Kind::buffer;
    GpuBuffer buffer;
    std::uint64_t offset = 0;
    std::uint64_t size = 0;
    GpuTexture texture;
    GpuSampler sampler;
 
    static GpuBinding of(std::uint32_t binding, GpuBuffer buffer, std::uint64_t offset = 0,
                         std::uint64_t size = 0);
    static GpuBinding of(std::uint32_t binding, GpuTexture texture);
    static GpuBinding of(std::uint32_t binding, GpuSampler sampler);
};
 
class GpuBindGroup {
  public:
    GpuBindGroup() = default;
    bool valid() const noexcept;
 
  private:
    friend struct detail::GpuAccess;
    std::shared_ptr<detail::GpuBindGroupState> state_;
};
 
// ── Offscreen target ────────────────────────────────────────────────────
 
struct GpuTargetDesc {
    std::uint32_t width = 0;
    std::uint32_t height = 0;
    GpuFormat color_format = GpuFormat::rgba8_unorm;
    std::optional<GpuFormat> depth_format;
    std::string label;
};

struct GpuPixels {
    std::vector<std::uint8_t> bytes;
    std::uint32_t width = 0;
    std::uint32_t height = 0;
    std::uint32_t bytes_per_pixel = 0;
    GpuFormat format = GpuFormat::undefined;

    std::array<std::uint8_t, 4> rgba8_at(std::uint32_t x, std::uint32_t y) const;
};

class GpuTarget {
  public:
    GpuTarget() = default;
    bool valid() const noexcept;
    std::uint32_t width() const noexcept;
    std::uint32_t height() const noexcept;
    GpuTexture color() const;
    std::optional<GpuTexture> depth() const;

    GpuResult<GpuPixels>
    read_pixels(std::chrono::milliseconds timeout = std::chrono::milliseconds(2000)) const;
 
  private:
    friend struct detail::GpuAccess;
    std::shared_ptr<detail::GpuTargetState> state_;
};
 
// ── Device ──────────────────────────────────────────────────────────────

class GpuDevice {
  public:
    GpuDevice() = default;

    static GpuResult<GpuDevice> from_surface(GpuSurface& surface);
 
    bool valid() const noexcept;
    bool is_lost() const;
    const GpuDeviceCapabilities& capabilities() const;
 
    GpuResult<GpuTexture> create_texture(const GpuTextureDesc& desc) const;
    GpuResult<GpuBuffer> create_buffer(const GpuBufferDesc& desc) const;
    GpuResult<GpuSampler> create_sampler(const GpuSamplerDesc& desc = {}) const;
    GpuResult<GpuShaderModule> create_shader_module(std::string_view wgsl,
                                                    std::string_view label = {}) const;
    GpuResult<GpuRenderPipeline> create_render_pipeline(const GpuRenderPipelineDesc& desc) const;
    GpuResult<GpuComputePipeline> create_compute_pipeline(const GpuComputePipelineDesc& desc) const;
    GpuResult<GpuBindGroup> create_bind_group(const GpuRenderPipeline& pipeline,
                                              std::uint32_t group,
                                              const std::vector<GpuBinding>& bindings) const;
    GpuResult<GpuBindGroup> create_bind_group(const GpuComputePipeline& pipeline,
                                              std::uint32_t group,
                                              const std::vector<GpuBinding>& bindings) const;
    GpuResult<GpuTarget> create_target(const GpuTargetDesc& desc) const;

    GpuStatus write_buffer(const GpuBuffer& buffer, std::uint64_t offset, const void* data,
                           std::size_t size) const;

    void process_events() const;
 
  private:
    friend struct detail::GpuAccess;
    std::shared_ptr<detail::GpuDeviceState> state_;
};
 
// ── Recording ───────────────────────────────────────────────────────────
 
struct GpuColorAttachment {
    GpuTexture texture;
    std::optional<std::array<float, 4>> clear;
    std::optional<GpuTexture> resolve;
};
 
struct GpuRenderPassDesc {
    std::vector<GpuColorAttachment> colors;
    std::optional<GpuTexture> depth;
    std::optional<float> depth_clear = 1.0f;
    std::string label;

    static GpuRenderPassDesc for_target(
        const GpuTarget& target,
        std::optional<std::array<float, 4>> clear = std::array<float, 4>{0.0f, 0.0f, 0.0f, 0.0f});
};
 
class GpuFrame;

class GpuRenderPass {
  public:
    GpuRenderPass(GpuRenderPass&&) noexcept;
    GpuRenderPass& operator=(GpuRenderPass&&) noexcept;
    GpuRenderPass(const GpuRenderPass&) = delete;
    GpuRenderPass& operator=(const GpuRenderPass&) = delete;
    ~GpuRenderPass();
 
    bool valid() const noexcept;
    void set_pipeline(const GpuRenderPipeline& pipeline);
    void set_bind_group(std::uint32_t index, const GpuBindGroup& group);
    void set_vertex_buffer(std::uint32_t slot, const GpuBuffer& buffer, std::uint64_t offset = 0);
    void set_index_buffer(const GpuBuffer& buffer, bool uint32_indices = true,
                          std::uint64_t offset = 0);
    void set_viewport(float x, float y, float width, float height, float min_depth = 0.0f,
                      float max_depth = 1.0f);
    void set_scissor(std::uint32_t x, std::uint32_t y, std::uint32_t width, std::uint32_t height);
    void draw(std::uint32_t vertex_count, std::uint32_t instance_count = 1,
              std::uint32_t first_vertex = 0, std::uint32_t first_instance = 0);
    void draw_indexed(std::uint32_t index_count, std::uint32_t instance_count = 1,
                      std::uint32_t first_index = 0, std::int32_t base_vertex = 0,
                      std::uint32_t first_instance = 0);
    void end();
 
  private:
    friend class GpuFrame;
    struct Impl;
    explicit GpuRenderPass(std::unique_ptr<Impl> impl);
    std::unique_ptr<Impl> impl_;
};

class GpuComputePass {
  public:
    GpuComputePass(GpuComputePass&&) noexcept;
    GpuComputePass& operator=(GpuComputePass&&) noexcept;
    GpuComputePass(const GpuComputePass&) = delete;
    GpuComputePass& operator=(const GpuComputePass&) = delete;
    ~GpuComputePass();
 
    bool valid() const noexcept;
    void set_pipeline(const GpuComputePipeline& pipeline);
    void set_bind_group(std::uint32_t index, const GpuBindGroup& group);
    void dispatch(std::uint32_t x, std::uint32_t y = 1, std::uint32_t z = 1);
    void end();
 
  private:
    friend class GpuFrame;
    struct Impl;
    explicit GpuComputePass(std::unique_ptr<Impl> impl);
    std::unique_ptr<Impl> impl_;
};
 
enum class GpuSubmissionStatus : std::uint8_t { pending, succeeded, failed };

class GpuSubmission {
  public:
    GpuSubmission() = default;
    GpuSubmissionStatus status() const;
    GpuSubmissionStatus poll() const;
    GpuSubmissionStatus wait(std::chrono::milliseconds timeout) const;
    std::optional<GpuError> error() const;
 
  private:
    friend struct detail::GpuAccess;
    std::shared_ptr<detail::GpuSubmissionState> state_;
};

class GpuFrame {
  public:
    explicit GpuFrame(const GpuDevice& device, std::string_view label = {});
    GpuFrame(GpuFrame&&) noexcept;
    GpuFrame& operator=(GpuFrame&&) = delete;
    GpuFrame(const GpuFrame&) = delete;
    GpuFrame& operator=(const GpuFrame&) = delete;
    ~GpuFrame();
 
    GpuRenderPass render_pass(const GpuRenderPassDesc& desc);
    GpuComputePass compute_pass(std::string_view label = {});

    GpuResult<GpuSubmission> submit();
    bool submitted() const noexcept;
 
  private:
    std::shared_ptr<detail::GpuFrameState> state_;
};
 
// ── Compositing ─────────────────────────────────────────────────────────

GpuStatus draw_gpu_texture(canvas::Canvas& canvas, const GpuTexture& texture, float x, float y,
                           float w, float h);
 
} // namespace pulp::render