Graphics.h

浏览该文件的文档.

#pragma once
#include "common/Export.h"
 
 
#include <assimp/matrix4x4.h>
#include <cstdint>
#include <glm/mat4x4.hpp>
#include <glm/vec2.hpp>
#include <glm/vec3.hpp>
#include <glm/vec4.hpp>
#include <memory>
#include <optional>
#include <span>
#include <string>
#include <vector>
#include "common/FramePresentation.h"
#include "common/Module.h"
#include "common/Result.h"
#include "common/WindowSurfaceHost.h"
#include "graphics/BlendMode.h"
#include "graphics/Canvas.h"
#include "graphics/Color.h"
#include "graphics/Font.h"
#include "graphics/GpuDrivenTypes.h"
#include "graphics/GpuParticles.h"
#include "graphics/ICanvasFactory.h"
#include "graphics/ICanvasTarget.h"
#include "graphics/IGraphics2D.h"
#include "graphics/IGraphics3D.h"
#include "graphics/IPostFX.h"
#include "graphics/IResourceFactory.h"
#include "graphics/ISolidRectRenderer.h"
#include "graphics/RayTracingCaps.h"
#include "graphics/SurfaceMode.h"
 
struct aiMesh;
 
namespace eve {
class Subscription;
}
 
namespace eve::graphics {
struct PbrSurface;
struct ShaderResourceInputs;
 
 
class AmbientOcclusion;
class AntiAliasing;
class Bloom;
class DepthOfField;
class Exposure;
class DepthPyramid;
class Camera3D;
class Drawable;
class GBuffer;
class GlobalIllumination;
class GrassField;
namespace hair {
class GroomInstance;
}
class Material;
class Mesh;
class PrimitiveScene;
 
struct TextureRegionUpload {
    int x = 0;
    int y = 0;
    int width = 0;
    int height = 0;
    std::span<const std::uint8_t> rgba;
    std::size_t bytesPerRow = 0;
};
 
struct MeshBackendDescriptor {
    std::uint32_t vertexCount      = 0;
    std::uint32_t indexCount       = 0;
    std::uint32_t vertexStride     = 0;
    std::uint32_t indexElementSize = 0;
};
class Outline;
class Quad;
class RenderControl;
class Renderable2D;
class AlphaMask;
class DepthOfField;
class MapFog;
class ScreenSpaceReflection;
class Shader;
struct MeshShaderRasterState;
class Texture;
class Volumetric;
class Water;
class Waterfall;
class ReflectionProbeCapture;
class ReflectionProbeRegistry;
struct ClusteredLightingUpload;
struct Lighting2DUBO;
struct Lighting3DPack;
struct ShadowUpload;
struct TextureCreateInfo;
struct TextureSampler;
 
class EVENGINE_API_BACKENDS Graphics : public Module,
                                       public Canvas,
                                       public IWindowSurfaceHost,
                                       public IGraphics2D,
                                       public IGraphics3D,
                                       public ICanvasFactory,
                                       public ICanvasTarget,
                                       public IResourceFactory,
                                       public ISolidRectRenderer,
                                       public IPostFX,
                                       public IFramePresentation {
public:
    Module_REG(Graphics);
    Graphics();
    ~Graphics() override;
 
    virtual void reset();
 
    virtual void clearScreen();
    virtual void setBackgroundColorRGBA(float r, float g, float b, float a = 1.f);
    virtual void drawSolidRectRGBA(float x, float y, float w, float h, float r, float g, float b, float a = 1.f);
    virtual void drawTexturedRectRGBA(Texture *texture, float x, float y, float w, float h, float r, float g, float b,
                                      float a = 1.f);
    virtual void drawTexturedRectRotatedRGBA(Texture* texture, float cx, float cy, float w, float h, float degrees,
                                             float r, float g, float b, float a = 1.f);
    virtual void drawSolidRect(float x, float y, float w, float h, float r, float g, float b, float a = 1.f);
    virtual void drawTexturedRect(Texture *texture, float x, float y, float w, float h, float r, float g, float b,
                                  float a = 1.f);
    void renderSprites();
    Renderable2D *newSprite2D();
    Texture *newTextureFromImageData(image::ImageData *data, bool repeatU = false,
                                     bool repeatV = false);
    Texture *newTextureFromImageData(image::ImageData *data, const TextureCreateInfo &info);
 
    [[nodiscard]] eve::Result<void> updateTextureFromImageData(Texture* texture, image::ImageData* data);
 
    Texture* newTextureWithSampler(image::ImageData* data, bool repeatU, bool repeatV, bool generateMipmaps,
                                   float maxAnisotropy, const std::string& filter, const std::string& mipmap,
                                   float lodBias = 0.f);
 
    virtual void setTextureSampler(Texture *texture, const std::string &filter, const std::string &mipmap,
                                   float maxAnisotropy, float lodBias);
 
    virtual void present() = 0;
 
    virtual std::string getBackendName() const = 0;
 
    virtual bool supportsRuntimeGlslCompilation() const { return false; }
    [[nodiscard]] std::weak_ptr<const void> resourceLifetime() const;
    [[nodiscard]] Result<eve::Subscription> onResourcesRetiring(std::function<void()> callback) const;
 
 
    virtual bool supportsGBufferPost() const { return true; }
 
    // ---- GPU-driven rendering (stage 1): capability-gated seam ----
    // Backends without the GPU-driven path (WebGPU, software) return false and
    // RenderSystem3D falls back to the legacy per-draw path.
 
    virtual bool supportsDeferredLighting() const { return false; }
 
    virtual void drawDeferredLighting() {}
 
    virtual bool supportsGpuDriven3D() const { return false; }
 
    virtual bool supportsRayTracing() const { return false; }
 
    virtual RayTracingCaps rayTracingCaps() const { return {}; }
 
    virtual bool gpuDrivenEnabled() const { return false; }
 
    virtual void gpuDrivenSetEnabled(bool enabled) { (void)enabled; }
 
    virtual uint32_t gpuDrivenMeshRecord(Mesh* mesh) {
        (void)mesh;
        return kInvalidGpuDrivenSlot;
    }
 
    virtual uint32_t gpuDrivenMaterialRecord(Material *material) {
        (void)material;
        return kInvalidGpuDrivenSlot;
    }
 
    [[nodiscard]] virtual Result<void> gpuDrivenReleaseMaterialRecord(Material *material) {
        (void)material;
        return Result<void>::failure(Diagnostic::error(
            DiagnosticCode::Unsupported, "GPU-driven material records are unavailable on this backend"));
    }
 
    virtual bool gpuDrivenMaterialUsable(Material *material) {
        (void)material;
        return false;
    }
 
    virtual uint32_t gpuDrivenReflectionProbeSlot(Texture *cubemap) {
        (void)cubemap;
        return kInvalidGpuDrivenSlot;
    }
 
    // ---- GPU-resident 2D particles ---------------------------------------
 
    virtual bool supportsGpuParticles() const { return false; }
 
    virtual bool canSubmitGpuParticles() const { return false; }
 
    virtual GpuParticleHandle createGpuParticleEmitter(std::uint32_t capacity) {
        (void)capacity;
        return kInvalidGpuParticleHandle;
    }
 
    virtual void releaseGpuParticleEmitter(GpuParticleHandle handle) { (void)handle; }
 
    virtual void resetGpuParticleEmitter(GpuParticleHandle handle) { (void)handle; }
 
    virtual bool updateGpuParticleEmitter(GpuParticleHandle handle, const GpuParticleUpdate& update,
                                          const GpuParticleSpawn* spawns, std::uint32_t spawnCount) {
        (void)handle;
        (void)update;
        (void)spawns;
        (void)spawnCount;
        return false;
    }
 
    virtual bool drawGpuParticleEmitter(GpuParticleHandle handle, const GpuParticleDraw& draw) {
        (void)handle;
        (void)draw;
        return false;
    }
 
    virtual GpuParticleStats getGpuParticleStats(GpuParticleHandle handle) const {
        (void)handle;
        return {};
    }
 
    virtual bool gpuDrivenSubmitOpaque(const GpuInstance *instances, uint32_t instanceCount) {
        (void)instances;
        (void)instanceCount;
        return false;
    }
 
    virtual GpuResidentSubmitStatus gpuDrivenSubmitResident(const GpuResidentInstanceBatch &batch) {
        (void)batch;
        return GpuResidentSubmitStatus::Unsupported;
    }
 
    // ---- GPU-driven rendering (stage 2): GPU cull seam ----
    // Backends without the compute cull chain return false / no-op; the
    // renderer then falls back to gpuDrivenSubmitOpaque (stage 1) or legacy.
 
    virtual bool gpuDrivenCullEnabled() const { return false; }
 
    virtual bool gpuDrivenScenePassPending() const { return false; }
 
    virtual bool gpuDrivenCullBegin(const GpuInstance *instances, uint32_t instanceCount) {
        (void)instances;
        (void)instanceCount;
        return false;
    }
 
    virtual void gpuDrivenCullEmit(const glm::mat4& viewProj, const glm::vec3& eye, float fovYDeg, float nearZ,
                                   float farZ) {
        (void)viewProj;
        (void)eye;
        (void)fovYDeg;
        (void)nearZ;
        (void)farZ;
    }
 
    virtual void gpuDrivenOpenScenePass() {}
 
    virtual void gpuDrivenDrawOpaque() {}
 
    // ---- GPU-driven rendering (stage 3): visibility buffer + resolve seam ----
    // Backends without the resolve path return false / no-op; the renderer
    // keeps using gpuDrivenDrawOpaque (forward shading).
 
    virtual bool gpuDrivenResolveWanted() const { return false; }
 
    virtual void gpuDrivenRecordVisPass() {}
 
    virtual void gpuDrivenResolve() {}
 
    // ---- GPU-driven rendering (stage 3): virtual-geometry seam ----
    // Backends without VG support return kInvalidGpuDrivenSlot / false; the
    // renderer then draws the mesh through the normal GPU-driven path.
 
    virtual std::uint32_t gpuDrivenVgUpload(const GpuVgAssetUpload &asset) {
        (void)asset;
        return kInvalidGpuDrivenSlot;
    }
 
    virtual std::uint32_t gpuDrivenVgAssetId(Mesh *mesh) const {
        (void)mesh;
        return kInvalidGpuDrivenSlot;
    }
 
    virtual bool gpuDrivenVgAttachToMesh(Mesh *mesh, std::uint32_t vgAssetId) {
        (void)mesh;
        (void)vgAssetId;
        return false;
    }
 
    virtual bool gpuDrivenVgSetInstance(std::uint32_t vgAssetId, const glm::mat4 &model,
                                        std::uint32_t materialId) {
        (void)vgAssetId;
        (void)model;
        (void)materialId;
        return false;
    }
 
    virtual void gpuDrivenVgComputeSection(const glm::mat4& viewProj, const glm::vec3& eye, float fovYDeg, float nearZ,
                                           float farZ) {
        (void)viewProj;
        (void)eye;
        (void)fovYDeg;
        (void)nearZ;
        (void)farZ;
    }
 
    virtual void initWithWindow(void *nativeWindow) = 0;
 
    virtual void initHeadless(int width, int height);
 
    virtual bool isHeadless() const { return false; }
 
    virtual void setViewportSize(int width, int height, int pixelwidth, int pixelheight) = 0;
 
    int getWidth() const { return width; }
    int getHeight() const { return height; }
    int getPixelWidth() const { return pixelWidth; }
    int getPixelHeight() const { return pixelHeight; }
 
    double getCurrentDPIScale() const { return (width > 0) ? double(pixelWidth) / double(width) : 1.0; }
    double getScreenDPIScale() const { return getCurrentDPIScale(); }
 
    [[nodiscard]] std::shared_ptr<PrimitiveScene> getPrimitiveScene() const noexcept { return primitiveScene_; }
 
    virtual void drawSolidRect(float x, float y, float w, float h, const Color &color,
                               BlendMode blend = BlendMode::Alpha) = 0;
 
    virtual void drawSolidRectRotated(float cx, float cy, float w, float h, float degrees, const Color& color,
                                      BlendMode blend = BlendMode::Alpha) = 0;
 
    virtual Texture *newTexture(int width, int height, const uint8_t *rgba, bool repeatU = false,
                                bool repeatV = false) = 0;
 
    virtual Texture* newTexture(int width, int height, const uint8_t* rgba, const TextureCreateInfo& info) = 0;
 
    virtual Texture *newCubemap(int faceSize, const uint8_t *rgbaFaces) = 0;
 
    virtual Texture *newCubemap(int faceSize, const uint8_t *rgbaFaces,
                                const TextureCreateInfo &info) = 0;
 
    virtual Texture *newHDRCubemap(int faceSize) {
        (void)faceSize;
        return nullptr;
    }
 
    virtual bool copyHDRCanvasToCubemapFace(Canvas *source, Texture *cubemap, int face) {
        (void)source;
        (void)cubemap;
        (void)face;
        return false;
    }
 
    virtual bool copyHDRCanvasesToCubemap(Canvas* const* sources, int faceCount, Texture* cubemap) {
        if (!sources || faceCount < 1 || faceCount > 6) return false;
        for (int face = 0; face < faceCount; ++face)
            if (!copyHDRCanvasToCubemapFace(sources[face], cubemap, face)) return false;
        return true;
    }
 
    virtual bool filterHDRReflectionCubemap(Texture *cubemap, int sampleCount = 64) {
        (void)cubemap;
        (void)sampleCount;
        return false;
    }
 
    virtual Texture *newTexture(image::ImageData *data) = 0;
 
    virtual Texture *newTexture(image::ImageData *data, const TextureCreateInfo &info) = 0;
 
    virtual bool updateTexture(Texture *texture, int width, int height, const uint8_t *rgba) = 0;
 
    [[nodiscard]] virtual eve::Result<void> updateTextureFromResidentRgba8(Texture*                     texture,
                                                                           const GpuResidentBufferView& source,
                                                                           int width, int height) {
        (void)texture;
        (void)source;
        (void)width;
        (void)height;
        return eve::Result<void>::failure(eve::Diagnostic::error(eve::DiagnosticCode::Unsupported,
                                                                 "Resident texture upload is unavailable",
                                                                 "graphics.updateTextureFromResidentRgba8"));
    }
 
    [[nodiscard]] virtual eve::Result<void> updateTextureRegion(Texture* texture, int x, int y, int width, int height,
                                                                std::span<const std::uint8_t> rgba,
                                                                std::size_t                   bytesPerRow = 0) = 0;
 
    [[nodiscard]] virtual eve::Result<void> updateTextureRegions(Texture*                             texture,
                                                                 std::span<const TextureRegionUpload> regions) = 0;
 
    virtual void setTextureSampler(Texture *texture, const TextureSampler &sampler) = 0;
 
    virtual float getMaxAnisotropy() const = 0;
 
    virtual Texture *newTextureFromFile(const std::string &filename) = 0;
    Texture *newTextureFromFileRepeated(const std::string &filename, bool repeatU, bool repeatV);
 
    void ensureFileTexturesReady();
 
    virtual bool reloadTextureFromFile(const std::string &filename) = 0;
 
    virtual bool releaseTexture(Texture *texture) {
        (void)texture;
        return false;
    }
 
    virtual void drawTexturedRect(Texture* texture, float x, float y, float w, float h, const Color& color) = 0;
 
    virtual void drawTexturedRectShader(Texture* texture, Shader* shader, float x, float y, float w, float h,
                                        const Color& color) = 0;
 
    virtual void drawTexturedRectUV(Texture* texture, float x, float y, float w, float h, float u0, float v0, float u1,
                                    float v1, const Color& color) = 0;
 
    virtual void drawTexturedRectShaderUV(Texture* texture, Shader* shader, float x, float y, float w, float h,
                                          float u0, float v0, float u1, float v1, const Color& color,
                                          bool rotatedUV = false, BlendMode blend = BlendMode::Alpha) = 0;
 
    virtual void drawTexturedRectShaderUVRotated(Texture* texture, Shader* shader, float cx, float cy, float w, float h,
                                                 float degrees, float u0, float v0, float u1, float v1,
                                                 const Color &color, bool rotatedUV = false,
                                                 BlendMode blend = BlendMode::Alpha) = 0;
 
    virtual void drawTexturedRectShaderDepth(Texture* color, Texture* depth, Shader* shader, float x, float y, float w,
                                             float h, const Color& tint) = 0;
 
    virtual void drawTexturedRectShaderDepthMotion(Texture* color, Texture* depth, Texture* motion, Shader* shader,
                                                   float x, float y, float w, float h, const Color& tint) = 0;
 
    virtual void drawTexturedRectShader4(Texture* color, Texture* depth, Texture* motion, Texture* extra,
                                         Shader* shader, float x, float y, float w, float h, const Color& tint) = 0;
 
    virtual void drawTexturedRectShader5(Texture* color, Texture* depth, Texture* motion, Texture* extra,
                                         Texture* specular, Shader* shader, float x, float y, float w, float h,
                                         const Color &tint) = 0;
 
    enum class SceneColorDistortionStatus { Queued, Unavailable };
 
    virtual SceneColorDistortionStatus drawSceneColorDistortionUVRotated(Texture* displacement, float cx, float cy,
                                                                         float w, float h, float degrees, float u0,
                                                                         float v0, float u1, float v1,
                                                                         float strengthPixels, float opacity,
        bool rotatedUV = false) {
        return SceneColorDistortionStatus::Unavailable;
    }
 
    virtual void drawTexturedRectLitUV(Texture *albedo, Texture *normal, float x, float y, float w, float h, float u0,
                                       float v0, float u1, float v1, const Color &color,
                                       BlendMode blend = BlendMode::Alpha) = 0;
 
    virtual void drawTexturedRectLitUVRotated(Texture *albedo, Texture *normal, float cx, float cy, float w, float h,
                                              float degrees, float u0, float v0, float u1, float v1, const Color &color,
                                              BlendMode blend = BlendMode::Alpha) = 0;
 
    virtual void setLighting2D(const Lighting2DUBO &ubo) = 0;
 
    Quad *newQuad(int x, int y, int w, int h);
 
    virtual Mesh *newMeshFromAssimp(const ::aiMesh &mesh) = 0;
 
    virtual Mesh *newMeshFromAssimp(const ::aiMesh &mesh, const aiMatrix4x4 &worldTransform) = 0;
 
    virtual Mesh *newMeshFromArrays(const float *posXYZ, const float *nrmXYZ, const float *uvST,
                                    int vertexCount, const uint32_t *indices, int indexCount) = 0;
    virtual Mesh *newMeshFromArraysColored(const float *posXYZ, const float *nrmXYZ, const float *uvST,
                                           const float *colorRGBA, int vertexCount,
                                           const uint32_t *indices, int indexCount) = 0;
 
    [[nodiscard]] virtual std::optional<MeshBackendDescriptor> describeMesh(Mesh *mesh) const {
        (void)mesh;
        return std::nullopt;
    }
 
    virtual bool updateMeshVertices(Mesh *mesh, const float *posXYZ, const float *nrmXYZ,
                                    const float *uvST, int vertexCount, const uint32_t *indices,
                                    int indexCount) = 0;
 
    virtual bool setMeshSkinningData(Mesh *mesh, const uint16_t *joints4, const float *weights4,
                                     int vertexCount) {
        (void)mesh;
        (void)joints4;
        (void)weights4;
        (void)vertexCount;
        return false;
    }
 
    virtual bool bakeMeshMorph(Mesh *mesh) = 0;
 
    virtual Mesh *newMeshSphere(int slices = 32, int stacks = 16) = 0;
 
    virtual Mesh *newMeshCylinder(int slices = 32, int stacks = 1, bool caps = true) = 0;
 
    Mesh *newMeshCube(float size = 1.f);
 
    virtual bool releaseMesh(Mesh *mesh) {
        (void)mesh;
        return false;
    }
 
    virtual void render3D();
    virtual void renderScene3DToCanvas(Canvas *canvas, Camera3D *camera);
    virtual void setDirectionalLight(float dx, float dy, float dz, float r = 1.f, float g = 1.f, float b = 1.f);
 
    virtual void drawScene3DRGBA(float x, float y, float w, float h, float r = 1.f, float g = 1.f, float b = 1.f,
                                 float a = 1.f);
    void drawScene3D(float x, float y, float w, float h) { drawScene3DRGBA(x, y, w, h, 1.f, 1.f, 1.f, 1.f); }
 
    virtual void drawCanvasRGBA(Canvas *canvas, float x, float y, float w, float h, float r = 1.f, float g = 1.f,
                                float b = 1.f, float a = 1.f);
    void drawCanvas(Canvas *canvas, float x, float y, float w, float h) {
        drawCanvasRGBA(canvas, x, y, w, h, 1.f, 1.f, 1.f, 1.f);
    }
 
    virtual void pushValidationScope() = 0;
    virtual void popValidationScope() = 0;
 
    Material *newMaterial();
 
    RenderControl *getRenderControl();
 
    virtual void beginGBufferPass(int width, int height) = 0;
    virtual void drawMeshGBuffer(Mesh* mesh, const glm::mat4& mvp, const glm::mat4& model, float nearZ, float farZ,
                                 Texture* albedo = nullptr, float tintR = 1.f, float tintG = 1.f, float tintB = 1.f,
                                 float motionX = 0.f, float motionY = 0.f, float roughness = 0.45f,
                                 float metallic = 0.f)   = 0;
    virtual void drawMeshGBufferAlpha(Mesh* mesh, const glm::mat4& mvp, const glm::mat4& model, float nearZ, float farZ,
                                      Texture* albedo = nullptr, float tintR = 1.f, float tintG = 1.f,
                                      float tintB = 1.f, float motionX = 0.f, float motionY = 0.f,
                                      float roughness = 0.45f, float metallic = 0.f) = 0;
    virtual void endGBufferPass() = 0;
 
    virtual void begin3DFrame() = 0;
 
    virtual void begin3DFrameToCanvas(Canvas *canvas) = 0;
    virtual void end3DFrameToCanvas() = 0;
 
    virtual float getLastOffscreen3DGpuDurationMs() const { return 0.f; }
 
    virtual void setMesh3DViewProj(const glm::mat4 &viewProj) = 0;
 
    virtual void setMesh3DView(const glm::mat4 &view) = 0;
 
    virtual void setMesh3DClip(float nearZ, float farZ) = 0;
 
    virtual Texture *getSceneColorTexture() { return nullptr; }
    virtual Texture* getSceneLinearDepthTexture() { return nullptr; }
 
    struct EntityIdDraw {
        Mesh *mesh = nullptr;
        glm::mat4 model{1.f};
        glm::vec4 idColor{0.f, 0.f, 0.f, 1.f};
    };
    virtual image::ImageData *renderEntityIdMask(const std::vector<EntityIdDraw> &draws,
                                                 const glm::mat4 &viewProj, int w, int h) {
        (void)draws;
        (void)viewProj;
        (void)w;
        (void)h;
        return nullptr;
    }
 
    virtual image::ImageData *readGBufferToImageData(const std::string &attachment) {
        (void)attachment;
        return nullptr;
    }
    virtual image::ImageData *readDecalLayerToImageData(const std::string &attachment) {
        (void)attachment;
        return nullptr;
    }
 
    virtual void drawMesh(Mesh *mesh, const glm::mat4 &model, Texture *texture, const Color &tint) = 0;
 
    virtual void drawMeshShader(Mesh *mesh, const glm::mat4 &model, Texture *texture, const Color &tint,
                                Shader *shader) = 0;
 
    [[nodiscard]] virtual Result<void> drawMeshShaderInstances(Mesh &mesh, Shader &shader, const glm::mat4 &model,
                                                               const Color &tint, std::uint32_t first,
                                                               std::uint32_t count) {
        (void)mesh;
        (void)shader;
        (void)model;
        (void)tint;
        (void)first;
        (void)count;
        return Result<void>::failure(Diagnostic::error(DiagnosticCode::Unsupported,
                                                       "Custom mesh instancing is unavailable on this backend",
                                                       "graphics.instances"));
    }
 
    virtual void setMesh3DNormalTexture(Texture *normal) = 0;
 
    virtual void setMesh3DPackedNormalMask(bool enabled) = 0;
 
    virtual void setMesh3DHeightTexture(Texture *height) = 0;
 
    virtual void setMesh3DVirtualTexture(bool enabled, int pageCountX, int pageCountY, int atlasSlotsX, int atlasSlotsY,
                                         float borderFraction) = 0;
 
    virtual void setMesh3DSceneDepth(Texture *depth) = 0;
 
    virtual void setMesh3DSceneColor(Texture *color) = 0;
 
    enum class Mesh3DSceneColorCaptureStatus { ExplicitOverride, Scheduled, Captured, HistoryReuse, Unavailable };
 
    [[nodiscard]] virtual Mesh3DSceneColorCaptureStatus captureMesh3DSceneColor() {
        return Mesh3DSceneColorCaptureStatus::HistoryReuse;
    }
 
    virtual void setMesh3DMaterial(float metallic, float roughness) = 0;
    [[nodiscard]] virtual Result<void> setMesh3DPbrSurface(const PbrSurface* surface) {
        if (!surface) return Result<void>::success();
        return Result<void>::failure(Diagnostic::error(
            DiagnosticCode::Unsupported, "extended PBR material rendering is unavailable on this backend"));
    }
 
    virtual void setMesh3DSurface(SurfaceMode mode, BlendMode blend, bool depthWrite, bool doubleSided,
                                  float alphaCutoff, const std::string& alphaTechnique = "cutoff") = 0;
 
    virtual void setMesh3DTexCellBomb(float cellScale, float strength, float rotAmount = 1.f) = 0;
 
    virtual void setMesh3DParallax(float scale, float minLayers = 8.f, float maxLayers = 32.f) = 0;
 
    virtual void setMesh3DLodDither(float weight, bool reverse, bool enabled) = 0;
 
    virtual void setMesh3DLighting(const Lighting3DPack &pack) = 0;
 
    virtual void setCloudShadows(float strength, float worldCell, float time, float windSpeed, float windAngle,
                                 float coverage, float detail) = 0;
 
    virtual void setMesh3DClusteredLighting(const ClusteredLightingUpload &upload) = 0;
 
    virtual void setMesh3DClusteredActive(bool active) = 0;
 
    virtual void setMesh3DSSAO(float intensity) = 0;
 
    virtual void setMesh3DLight(const glm::vec3 &dir, const glm::vec3 &color) = 0;
 
    virtual void setMesh3DCameraPos(const glm::vec3 &eye) = 0;
 
    virtual void drawVoxelFaceInstances(const uint32_t* packed, int count, float originX, float originY, float originZ,
                                        const std::string& faceDir, Texture* atlas, int tilesPerRow = 16,
                                        const uint32_t *ao = nullptr) = 0;
 
    virtual bool supportsDecal() const { return true; }
 
    virtual void beginDecalPass(int width, int height) = 0;
 
    virtual void setDecalCamera(const glm::mat4 &viewProj, float nearZ, float farZ) = 0;
 
    virtual void drawDecal(const glm::mat4 &model, Texture *albedo, Texture *normal,
                           Texture *params, const float uvRect[4], float fade,
                           float normalStrength, float roughnessStrength, float metalStrength,
                           float emissiveStrength, int blendMode = 0, int projectionMode = 0,
                           float blendSharpness = 4.f, float parallaxScale = 0.f,
                           float parallaxMinLayers = 8.f, float parallaxMaxLayers = 24.f,
                           float edgeFadeWidth = 0.06f) = 0;
    virtual void endDecalPass() = 0;
 
    virtual void setMesh3DEnv(Texture *cube, float intensity) = 0;
    virtual void setMesh3DEnvProbe(const glm::vec3 &center, const glm::vec3 &extent) = 0;
    virtual void setMesh3DReflectionProbes(const ReflectionProbeUpload &upload) = 0;
    enum class SceneToneMapping { None, Aces, Filmic };
    enum class DisplayOutputMode { Sdr, Auto, Hdr10, ScRgb };
    enum class DisplayColorSpace { Sdr, ScRgb, Hdr10 };
    struct DisplayOutputSupport {
        bool sdr = true;
        bool hdr10 = false;
        bool scRgb = false;
    };
    [[nodiscard]] virtual Result<void> setSceneToneMapping(SceneToneMapping mode);
    virtual SceneToneMapping getSceneToneMapping() const { return SceneToneMapping::Aces; }
    [[nodiscard]] virtual Result<void> setDisplayOutputMode(DisplayOutputMode mode);
    virtual DisplayOutputMode getDisplayOutputMode() const;
    [[nodiscard]] virtual Result<void> setDisplayHdrCalibration(float paperWhiteNits, float peakNits);
    virtual float getDisplayPaperWhiteNits() const;
    virtual float getDisplayPeakNits() const;
    virtual DisplayColorSpace getActiveDisplayColorSpace() const;
    virtual bool isDisplayHdrActive() const;
    [[nodiscard]] virtual Result<DisplayOutputSupport> queryDisplayOutputSupport() const;
    [[nodiscard]] virtual Result<void> setScenePhotographicVignette(float intensity);
    virtual float getScenePhotographicVignette() const { return 0; }
    virtual void setSceneExposure(float exposure) = 0;
    virtual float getSceneExposure() const = 0;
    virtual void setSceneColorFilter(const glm::vec3& color) = 0;
    virtual glm::vec3 getSceneColorFilter() const = 0;
    virtual void setSceneLiftGammaGain(const glm::vec3& lift, const glm::vec3& inverseGamma, const glm::vec3& gain) = 0;
    virtual glm::vec3 getSceneLift() const = 0;
    virtual glm::vec3 getSceneInverseGamma() const = 0;
    virtual glm::vec3 getSceneGain() const = 0;
    virtual void setSceneTransitionFx(float vignette, float vignetteSmoothness, float lensDistortion,
                                      float lensScale) = 0;
    virtual float getSceneTransitionVignette() const = 0;
    virtual float getSceneTransitionVignetteSmoothness() const = 0;
    virtual float getSceneTransitionLensDistortion() const = 0;
    virtual float getSceneTransitionLensScale() const = 0;
    virtual void setSceneAutoExposure(bool enabled, float minEV, float maxEV) = 0;
    virtual bool getSceneAutoExposure() const = 0;
    virtual float getSceneAutoExposureMinEV() const = 0;
    virtual float getSceneAutoExposureMaxEV() const = 0;
    virtual void setSceneBloom(float intensity, float threshold) = 0;
    virtual float getSceneBloomIntensity() const = 0;
    virtual float getSceneBloomThreshold() const = 0;
    virtual void setSceneDepthOfField(float focusDistance, float maxBlurPx, float focusRange,
                                      float nearZ, float farZ) = 0;
    virtual float getSceneDofFocusDistance() const = 0;
    virtual float getSceneDofMaxBlur() const = 0;
    virtual float getSceneDofFocusRange() const = 0;
    virtual float getSceneDofNearZ() const = 0;
    virtual float getSceneDofFarZ() const = 0;
 
    virtual void setMesh3DShadows(const ShadowUpload &upload) = 0;
 
    virtual void setMesh3DShadowReceive(bool receive) = 0;
 
    virtual void setMesh3DSkinInfluenceLimit(SkinInfluenceLimit count) = 0;
 
    virtual void beginShadowPass(int cascadeIndex) = 0;
    virtual void drawMeshShadow(Mesh *mesh, const glm::mat4 &lightMVP, bool doubleSided = true) = 0;
    virtual void drawMeshShadowAlpha(Mesh* mesh, const glm::mat4& lightMVP, Texture* albedo = nullptr,
                                     bool doubleSided = true, float lodWeight = 1.f,
                                     bool lodFadeReverse = false, bool lodDither = false) = 0;
    virtual void endShadowPass() = 0;
 
    bool consumeFrameHad3D() {
        bool v = frameHad3D;
        return v;
    }
    bool had3DThisFrame() const { return frameHad3D; }
 
    Color getBackgroundColor() const { return backgroundColor; }
    void setBackgroundColor(const Color &c) { backgroundColor = c; }
 
    virtual void setScreenReadbackEnabled(bool enabled) { screenReadbackEnabled = enabled; }
    bool isScreenReadbackEnabled() const { return screenReadbackEnabled; }
 
    bool saveFramePng(const std::string &path);
 
    virtual bool beginFrameReadback(const std::string &path) {
        (void)path;
        return false;
    }
    virtual int frameReadbackStatus() const { return 0; }
 
    virtual void setVSync(bool enabled) { vsyncEnabled = enabled; }
    bool isVSync() const { return vsyncEnabled; }
    void setVSyncCount(int count) override { presentationVSyncCount_=count;setVSync(count!=0); }
    int getVSyncCount() const noexcept override{return presentationVSyncCount_;}
 
    virtual void setMsaaSamples(int samples) { msaaSamples = samples > 0 ? samples : 0; }
    virtual int getMsaaSamples() const { return msaaSamples; }
 
    void setActive(bool active) override {
        graphicsActive = active;
        if (active) markSwapchainDirty();
    }
    bool isActive() const { return graphicsActive; }
 
    virtual void markSwapchainDirty() {}
 
    void requestSurfaceRecreate() override {}
 
    virtual void onNativeWindowDestroyed() {
        for (auto &cb : windowDestroyedCallbacks_) cb.first(cb.second);
        windowDestroyedCallbacks_.clear();
        clearPresentOverlay();
    }
 
    void clearPresentOverlay() {
        presentOverlayFn_ = nullptr;
        presentOverlayUser_ = nullptr;
    }
 
    using WindowDestroyedCallback = void (*)(void *userdata);
    void addWindowDestroyedCallback(WindowDestroyedCallback cb, void *userdata) {
        windowDestroyedCallbacks_.emplace_back(cb, userdata);
    }
 
    using PresentOverlayFn = bool (*)(void *userdata, void *commandBuffer);
    void setPresentOverlay(PresentOverlayFn fn, void *userdata) {
        presentOverlayFn_ = fn;
        presentOverlayUser_ = userdata;
    }
    PresentOverlayFn getPresentOverlay() const { return presentOverlayFn_; }
    void *getPresentOverlayUser() const { return presentOverlayUser_; }
 
    Font *newFont(font::FontData *data, std::string charset = Font::defaultCharset());
 
    virtual void setFont(Font *font) { currentFont = font; }
    Font *getFont() const { return currentFont; }
 
    virtual void print(const std::string& text, float x, float y, const Color& color = Color(1.f, 1.f, 1.f, 1.f),
                       float scale = 1.f);
 
    virtual void drawText(Font *font, const std::string &text, float x, float y,
                          const Color &color = Color(1.f, 1.f, 1.f, 1.f), float scale = 1.f);
 
    void drawTextRGBA(Font* font, const std::string& text, float x, float y, float r, float g, float b, float a,
                      float scale = 1.f) {
        drawText(font, text, x, y, Color(r, g, b, a), scale);
    }
 
    void printRGBA(const std::string& text, float x, float y, float r, float g, float b, float a, float scale = 1.f) {
        print(text, x, y, Color(r, g, b, a), scale);
    }
 
    virtual void setShader(Shader *shader);
    virtual void setShader();
 
    Shader *getShader() const { return currentShader; }
 
    virtual Shader *newShaderFromSpv(const std::vector<uint32_t> &vertSpv,
                                    const std::vector<uint32_t> &fragSpv) = 0;
 
    virtual Shader *newShaderFromSpvFile(const std::string &vertPath, const std::string &fragPath) = 0;
    Shader *newShaderFromSpvFile(const std::string &fragPath) {
        return newShaderFromSpvFile(std::string(), fragPath);
    }
 
    virtual Shader *newShader(const std::string &vertGlsl, const std::string &fragGlsl) = 0;
    Shader *newShader(const std::string &fragGlsl) { return newShader(std::string(), fragGlsl); }
 
    virtual Shader *newShaderFromWgsl(const std::string &vertWgsl,
                                      const std::string &fragWgsl) = 0;
 
    [[nodiscard]] virtual Result<void> replaceShaderFromSpv(Shader& shader, const std::vector<uint32_t>& vertSpv,
        const std::vector<uint32_t> &fragSpv) = 0;
 
    [[nodiscard]] virtual Result<void> replaceMeshShaderResources(Shader &shader, const std::vector<uint32_t> &vertSpv,
                                                                  const std::vector<uint32_t> &fragSpv,
                                                                  const ShaderResourceInputs  &resources);
 
    [[nodiscard]] virtual Result<void> replaceShaderFromWgsl(Shader& shader, const std::string& vertWgsl,
                                                             const std::string& fragWgsl) = 0;
 
    [[nodiscard]] virtual Result<void> replaceShaderFromGlsl(
        Shader &shader, const std::string &vertGlsl, const std::string &fragGlsl) = 0;
 
    virtual Shader *newMeshShaderFromSpv(const std::vector<uint32_t> &vertSpv,
                                         const std::vector<uint32_t> &fragSpv) = 0;
    virtual Shader *newMeshShaderFromWgsl(const std::string &vertWgsl,
                                          const std::string &fragWgsl) = 0;
    virtual Shader *newMeshShader(const std::string &vertGlsl, const std::string &fragGlsl) = 0;
    [[nodiscard]] virtual eve::Result<void> configureMeshShaderSurface(Shader &, BlendMode, bool, bool) {
        return eve::Result<void>::failure(
            eve::Diagnostic::error(eve::DiagnosticCode::Unsupported, "Custom mesh surface state is unavailable"));
    }
    [[nodiscard]] virtual eve::Result<void> configureMeshShaderRaster(Shader                      &shader,
                                                                      const MeshShaderRasterState &state) {
        return eve::Result<void>::failure(
            eve::Diagnostic::error(eve::DiagnosticCode::Unsupported, "Custom mesh raster state is unavailable"));
    }
    Shader *newMeshShaderVF(const std::string &vertGlsl, const std::string &fragGlsl) {
        return newMeshShader(vertGlsl, fragGlsl);
    }
    Shader *newMeshShader(const std::string &fragGlsl) {
        return newMeshShader(std::string(), fragGlsl);
    }
 
    virtual Shader *newHairShaderFromSpv(const std::vector<uint32_t> &vertSpv,
                                         const std::vector<uint32_t> &fragSpv) = 0;
    virtual Shader* newHairShaderFromWgsl(const std::string& vertWgsl, const std::string& fragWgsl) = 0;
    Shader *newHairShader();
 
    Mesh *newHairCardMesh(float width = 0.12f, float height = 0.45f);
 
    Material *newHairCardMaterial(Texture *albedo = nullptr);
 
    virtual bool releaseShader(Shader *shader) {
        (void)shader;
        return false;
    }
 
    Shader *newGrassShader();
 
    Shader* newTreeWindShader();
 
    GrassField *newGrassField();
 
    hair::GroomInstance *newGroomInstance();
 
    Waterfall *newWaterfall();
 
    Water *newWater();
    [[nodiscard]] Result<void> configureFoliageWind(Material *material, float directionX, float directionZ,
                                                    float strength, float bending, float bendingSpeed, float branch,
                                                    float branchSpeed, float flutter, float flutterSpeed,
                                                    float fadeDistance, float bendFactor);
    ReflectionProbeCapture *newReflectionProbeCapture();
    ReflectionProbeRegistry *newReflectionProbeRegistry();
 
    virtual Canvas *newCanvas(int width, int height) = 0;
 
    virtual Canvas *newHDRCanvas(int width, int height) = 0;
 
    virtual void setCanvas(Canvas *canvas) = 0;
    void setCanvas() { setCanvas(nullptr); }
 
    virtual bool isCanvasActive() const = 0;
    virtual Canvas *getCanvas() const = 0;
 
    Volumetric *newVolumetric();
    DepthOfField* newDepthOfField();
 
    AmbientOcclusion *newAmbientOcclusion();
 
    Outline *newOutline();
    AlphaMask *newAlphaMask();
    MapFog *newMapFog();
 
    GlobalIllumination *newGlobalIllumination();
 
    ScreenSpaceReflection *newScreenSpaceReflection();
 
    AmbientOcclusion *pipelineAmbientOcclusion();
    GlobalIllumination *pipelineGlobalIllumination();
    ScreenSpaceReflection *pipelineScreenSpaceReflection();
    AntiAliasing *pipelineAntiAliasing();
    Bloom *pipelineBloom();
    DepthOfField *pipelineDepthOfField();
    Exposure *pipelineExposure();
    DepthPyramid *pipelineDepthPyramid();
    Texture *prepareFinalSceneTexture(Texture *scene, Texture *motion = nullptr);
    Canvas *pipelineReflectionComposite(int width, int height);
    void setFinalSceneTexture(Texture *texture) { finalSceneTexture_ = texture; }
    Texture *takeFinalSceneTexture() {
        Texture *texture = finalSceneTexture_;
        finalSceneTexture_ = nullptr;
        return texture;
    }
    Outline *pipelineOutline();
 
    AntiAliasing *newAntiAliasing();
 
    virtual void draw(Drawable *drawable, const glm::mat4 &m);
 
    virtual void drawOcclusion(Drawable *drawable, const glm::mat4 &m);
    virtual void drawOcclusionSolid(float x, float y, float w, float h);
    virtual void drawOcclusionTexture(Texture *texture, float x, float y, float w, float h);
    // void draw(Texture *texture, Quad *quad, const glm::mat4 &m);
    // void drawLayer(Texture *texture, int layer, const glm::mat4 &m);
    // void drawLayer(Texture *texture, int layer, Quad *quad, const glm::mat4 &m);
    // void drawInstanced(Mesh *mesh, const glm::mat4 &m, int instancecount);
 
 
    void points(const std::vector<glm::vec2> &positions, const std::vector<Color> &colors);
 
    void polyline(const glm::mat4 *vertices, size_t count);
 
    void rectangle(std::string mode, float x, float y, float w, float h);
 
    void rectangle(std::string mode, float x, float y, float w, float h, float rx, float ry, int points);
    void rectangle(std::string mode, float x, float y, float w, float h, float rx, float ry);
 
    void circle(std::string mode, float x, float y, float radius, int points);
    void circle(std::string mode, float x, float y, float radius);
 
    void ellipse(std::string mode, float x, float y, float a, float b, int points);
    void ellipse(std::string mode, float x, float y, float a, float b);
 
    void arc(std::string mode, std::string arcmode, float x, float y, float radius, float angle1, float angle2,
             int points);
    void arc(std::string mode, std::string arcmode, float x, float y, float radius, float angle1, float angle2);
 
    void polygon(std::string mode, const std::vector<glm::vec2> &vertices, bool skipLastFilledVertex = true);
 
 
    void push(bool all);
    void pop();
 
    const glm::mat4 &getTransform() const;
    const glm::mat4 &getProjection() const;
 
    void rotate(float r);
    void scale(float x, float y = 1.0f);
    void translate(float x, float y);
    void origin();
 
    // void applyTransform(love::math::Transform *transform);
    // void replaceTransform(love::math::Transform *transform);
 
    glm::vec2 transformPoint(glm::vec2 point);
    glm::vec2 inverseTransformPoint(glm::vec2 point);
 
    // virtual void draw(const DrawCommand &cmd) = 0;
    // virtual void draw(const DrawIndexedCommand &cmd) = 0;
    // virtual void drawQuads(int start, int count, const vertex::Attributes &attributes, const vertex::BufferBindings
    // &buffers, Texture *texture) = 0;
 
protected:
    struct DeferredFileTexture {
        std::string key;
        Texture *texture = nullptr;
    };
 
    void requestFileImageDecode(const std::string &key);
    bool fileTextureSourceExists(const std::string &filename) const;
    void dropDeferredFileTexture(Texture *texture);
    virtual bool uploadDeferredFileTexture(Texture *texture, image::ImageData *data);
 
    std::vector<DeferredFileTexture> deferredFileTextures_;
    bool realizingFileTextures_ = false;
 
    int width = 0;
    int height = 0;
    int pixelWidth = 0;
    int pixelHeight = 0;
    Color backgroundColor{0.1f, 0.1f, 0.12f, 1.0f};
    bool frameHad3D = false;
    bool recordingEngine3D_ = false;
    bool screenReadbackEnabled = false;
    bool vsyncEnabled = true;
    int presentationVSyncCount_=1;
    DisplayOutputMode displayOutputMode_ = DisplayOutputMode::Sdr;
    DisplayColorSpace activeDisplayColorSpace_ = DisplayColorSpace::Sdr;
    float displayPaperWhiteNits_ = 200.f;
    float displayPeakNits_ = 1000.f;
    bool graphicsActive = true;
    int msaaSamples = 4;
    PresentOverlayFn presentOverlayFn_ = nullptr;
    void *presentOverlayUser_ = nullptr;
    std::vector<std::pair<WindowDestroyedCallback, void *>> windowDestroyedCallbacks_;
    Shader *currentShader = nullptr;
    Font *currentFont = nullptr;
    std::unique_ptr<RenderControl> renderControl_;
    std::shared_ptr<PrimitiveScene>                         primitiveScene_;
    std::unique_ptr<AmbientOcclusion> pipelineAO_;
    std::unique_ptr<GlobalIllumination> pipelineGI_;
    std::unique_ptr<ScreenSpaceReflection> pipelineSSR_;
    std::unique_ptr<AntiAliasing> pipelineAA_;
    std::unique_ptr<Bloom> pipelineBloom_;
    std::unique_ptr<DepthOfField> pipelineDof_;
    std::unique_ptr<Exposure> pipelineExposure_;
    bool                                                   sceneDepthOfFieldEnabled_           = false;
    float                                                  sceneDepthOfFieldFocusDistance_     = 10.f;
    float                                                  sceneDepthOfFieldFocusRange_        = 5.f;
    float                                                  sceneDepthOfFieldMaximumBlurPixels_ = 8.f;
    float                                                  sceneDepthOfFieldNearPlane_         = 0.1f;
    float                                                  sceneDepthOfFieldFarPlane_          = 100.f;
    std::unique_ptr<DepthPyramid> pipelineDepthPyramid_;
    Canvas *spatialAAResolve_ = nullptr;
    int spatialAAResolveWidth_ = 0;
    int spatialAAResolveHeight_ = 0;
    Canvas *reflectionComposite_ = nullptr;
    int reflectionCompositeWidth_ = 0;
    int reflectionCompositeHeight_ = 0;
    Texture *finalSceneTexture_ = nullptr;
    Texture                                                *foliageWindMotionTexture_  = nullptr;
    Texture                                                *foliageWindNoiseTexture_   = nullptr;
    std::unique_ptr<Outline> pipelineOutline_;
 
    Shader *prepareSceneColorResolveShader(Texture *scene);
    void    retireResourceLifetime() const;
};
 
}  // namespace eve::graphics