Hd2d.h

浏览该文件的文档.

#pragma once
#include "common/Export.h"
 
 
// HD-2D module: renders 2D tilemaps and 2D sprite characters inside the 3D
// scene. Both techniques layer on top of the existing graphics 3D pipeline
// (GBuffer + CSM shadows):
//
//   * TileMap3D  -- extrudes a map::TileLayer into a 3D relief mesh. Every
//                   non-empty tile becomes a box whose top face shows the
//                   tile's atlas region and whose side walls extrude down to
//                   the configured depth (or to the per-tile elevation read
//                   from tile metadata). Handed to a graphics::Renderable3D so
//                   it picks up depth, shadows and GBuffer automatically.
//   * Sprite3D   -- a camera-facing billboard quad in the 3D world carrying a
//                   2D texture (a character / animation frame). It is an ECS
//                   graphics::Renderable3D oriented toward the camera each
//                   frame (screen-aligned billboard), so it composites
//                   into the forward pass and casts shadows like any mesh.
//                   Supports a sprite-sheet frame grid so existing 2D
//                   animations play in 3D.
//
// Script binding: eve.Hd2d (slot hd2d). See module_manifest.cmake.
 
#include "common/Module.h"
 
#include <glm/mat4x4.hpp>
 
#include <cstdint>
#include <string>
#include <vector>
 
namespace eve::graphics {
class Camera3D;
class Graphics;
class Mesh;
class Renderable3D;
class Texture;
}  // namespace eve::graphics
namespace eve::map { class TileLayer; }
 
namespace eve::hd2d {
 
class EVENGINE_API_DOMAINS TileMap3D {
public:
    TileMap3D() = default;
    TileMap3D(const TileMap3D &) = delete;
    TileMap3D &operator=(const TileMap3D &) = delete;
 
    void setSideDepth(float depth);
    float getSideDepth() const;
    void setHeightScale(float scale);
    float getHeightScale() const;
    void setWallUV(float u0, float v0, float u1, float v1);
    void setTint(float r, float g, float b, float a = 1.f);
 
    graphics::Mesh *buildMesh(graphics::Graphics *gfx, map::TileLayer *layer);
 
    graphics::Renderable3D *buildRenderable(graphics::Graphics *gfx, map::TileLayer *layer);
 
    int getTileCount() const { return tileCount_; }
 
private:
    float sideDepth_ = 6.f;
    float heightScale_ = 1.f;
    float wallU0_ = 0.f, wallV0_ = 0.f, wallU1_ = 0.05f, wallV1_ = 0.05f;
    float tintR_ = 1.f, tintG_ = 1.f, tintB_ = 1.f, tintA_ = 1.f;
    int tileCount_ = 0;
};
 
class EVENGINE_API_DOMAINS Sprite3D {
public:
    Sprite3D();
    ~Sprite3D();
    Sprite3D(const Sprite3D &) = delete;
    Sprite3D &operator=(const Sprite3D &) = delete;
 
    void setTexture(graphics::Texture *texture);
    graphics::Texture *getTexture() const;
 
    void setFrame(float u0, float v0, float u1, float v1);
    void getFrame(float &u0, float &v0, float &u1, float &v1) const;
    void setFlipX(bool flip);
    void setFlipY(bool flip);
 
    void setFrameGrid(int columns, int rows);
    int getFrameGridColumns() const;
    int getFrameGridRows() const;
    void setFrameIndex(int index);
    int getFrameIndex() const;
    int getFrameCount() const;
    void play(int start, int end, float fps);
    void stop();
    bool isPlaying() const;
    void update(float dt);
 
    void setCamera(graphics::Camera3D *camera);
 
    void setPivot(float x, float y);
    void setPosition(float x, float y, float z);
    float getPositionX() const;
    float getPositionY() const;
    float getPositionZ() const;
    void setSize(float width, float height);
    float getWidth() const;
    float getHeight() const;
    void setTint(float r, float g, float b, float a = 1.f);
    void setVisible(bool visible);
    bool getVisible() const;
 
    void setAlphaCutoff(float cutoff);
    float getAlphaCutoff() const;
    void setDepthWrite(bool enabled);
    bool getDepthWrite() const;
    void setDoubleSided(bool enabled);
    bool getDoubleSided() const;
    void setBillboardMode(const std::string &mode);
    std::string getBillboardMode() const;
 
    graphics::Mesh *quadMesh() const { return quad_; }
 
private:
    friend class Hd2D;
    struct Anim {
        int start = 0, end = 0;
        float fps = 12.f;
        float clock = 0.f;
        bool playing = false;
    };
 
    void buildQuad(graphics::Graphics *gfx);
    void updateFrameUv();
    void orientToCamera();
    void syncMaterial();
 
    graphics::Graphics *gfx_ = nullptr;
    graphics::Texture *texture_ = nullptr;
    graphics::Mesh *quad_ = nullptr;
    graphics::Renderable3D *renderable_ = nullptr;
    graphics::Camera3D *camera_ = nullptr;
 
    // frame UV
    float u0_ = 0.f, v0_ = 0.f, u1_ = 1.f, v1_ = 1.f;
    bool flipX_ = false, flipY_ = false;
 
    // grid
    int gridCols_ = 1, gridRows_ = 1;
    int frameIndex_ = 0;
    Anim anim_;
 
    // placement
    float x_ = 0.f, y_ = 0.f, z_ = 0.f;
    float width_ = 1.f, height_ = 1.f;
    float pivotX_ = 0.5f, pivotY_ = 0.5f;
    float tintR_ = 1.f, tintG_ = 1.f, tintB_ = 1.f, tintA_ = 1.f;
    bool visible_ = true;
    float alphaCutoff_ = 0.5f;
    bool depthWrite_ = true;
    bool doubleSided_ = true;
    bool yawBillboard_ = false;
};
 
class EVENGINE_API_DOMAINS Hd2dLook {
public:
    Hd2dLook() = default;
 
    void setFocusDistance(float distance);
    float getFocusDistance() const { return focusDistance_; }
    void setMaxBlur(float blurPx);
    float getMaxBlur() const { return maxBlurPx_; }
    void setFocusRange(float range);
    float getFocusRange() const { return focusRange_; }
    void setBloomIntensity(float intensity);
    float getBloomIntensity() const { return bloomIntensity_; }
    void setBloomThreshold(float threshold);
    float getBloomThreshold() const { return bloomThreshold_; }
 
    void apply(graphics::Camera3D *camera) const;
 
    void applyPixelSampler(graphics::Graphics *gfx, graphics::Texture *texture) const;
 
    static Hd2dLook miniature();
    static Hd2dLook soft();
 
private:
    float focusDistance_ = 18.f;
    float maxBlurPx_ = 5.f;
    float focusRange_ = 14.f;
    float bloomIntensity_ = 0.35f;
    float bloomThreshold_ = 1.2f;
};
 
class EVENGINE_API_DOMAINS Hd2D : public Module {
public:
    Module_REG(Hd2D);
    Hd2D();
    ~Hd2D() override;
 
    TileMap3D *newTileMap3D();
    Sprite3D *newSprite(graphics::Graphics *gfx);
    Hd2dLook *newLook();
    Hd2dLook *newMiniatureLook();
};
 
}  // namespace eve::hd2d