A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file PostProcessPipeline.hpp
* @brief Post-processing effects pipeline
*
* @author ESEngine Team
* @date 2026
*
* @copyright Copyright (c) 2026 ESEngine Team
* Licensed under the Apache License, Version 2.0.
*/
#pragma once
#include "../../core/Types.hpp"
#include "../../resource/Handle.hpp"
#include "../../math/Math.hpp"
#include "../rhi/Framebuffer.hpp"
#include "../graph/RenderGraph.hpp"
#include "../store/HdrFormat.hpp"
#include <glm/glm.hpp>
#include <algorithm>
#include <cmath>
#include <string>
#include <vector>
#include <unordered_map>
#include <memory>
namespace esengine {
class GfxDevice;
class RenderContext;
class Shader;
class VoxelGI;
class DynamicGI;
namespace resource {
class ResourceManager;
}
/**
* @brief What the last pass of a chain does to scene values on the way out.
*
* @details A tonemap is the OUTPUT transform, not an effect: it runs exactly once
* and last — after the effects, which want scene values, and before the
* OETF, which is a transfer function. `None` by default: a flat frame in
* linear light wants an exact round trip, and a filmic curve is not one.
*/
enum class OutputTransform : u8 {
None = 0, ///< Encode only. Values above 1 clip, which is what LDR content means.
ACES = 1, ///< Narkowicz ACES filmic curve, for a scene that carries HDR radiance.
Neutral = 2, ///< Khronos PBR Neutral: hue and saturation survive, highlights roll off.
};
/**
* @brief Post-processing pass configuration
*/
struct PostProcessPass {
std::string name;
resource::ShaderHandle shader;
bool enabled = true;
std::unordered_map<std::string, f32> floatUniforms;
std::unordered_map<std::string, glm::vec4> vec4Uniforms;
/// Effect-declared textures (LUTs, masks): sampler uniform name -> GL
/// texture id. #pragma-param shaders bind them at their reflected material
/// units; the legacy loose path binds in order above the two engine units
/// (0 = input, 1 = scene).
std::vector<std::pair<std::string, u32>> textureUniforms;
/// Set by the chain when the pass keeps its output for the next frame (its
/// shader declares `u_history`); the pass then reads the previous frame there.
bool temporal = false;
/// Set instead of `temporal` when the shader declares `u_feedback`: the pass keeps
/// its own last output without shifting the picture, and reads it there. An
/// auto-exposure's adapted value is remembered this way.
bool feedback = false;
/// Which remembered state the pass uses, resolved when the chain is declared.
u64 historyKey = 0;
/// Fraction of the chain's size this pass draws at; the pass consuming it
/// upsamples. The graph resolves the fraction, and u_viewport still reports
/// the CANVAS, so a fractional pass must read its extent off its texture.
f32 scale = 1.0f;
/// Set on every pass of a multi-pass effect after its first: unit 1 then
/// reads the input that effect started from, not this pass's own input. False
/// starts an effect, so a single-pass effect sees the chain as it reached it.
bool continuesEffect = false;
/// What this pass reads from passes earlier in its own effect: a texture param named `u_pass_<name>` is the output
/// of the pass called <name> (a bloom's upsample adds the downsample of its own size back). Resolved by the chain
/// each frame, which also keeps those targets alive until this pass has run.
std::vector<std::pair<std::string, rg::ResourceId>> earlierInputs;
/// A compute pass (see PostProcessPipeline::addComputePass): the program, which floats its params block holds, in
/// order, and the workgroup the shader declares. Invalid for every pass that draws.
ComputeHandle compute = ComputeHandle::Invalid;
bool isCompute = false;
/// A pass the engine implements itself, in compute passes of its own (see VoxelGI): its name, empty for every other pass.
std::string nativeKind;
std::vector<std::string> computeParams;
u32 workgroupX = 8;
u32 workgroupY = 8;
/// #pragma-param shaders: the pass's packed MaterialConstants payload +
/// its UBO (binding 1) — the same reflected block a material would use.
/// Rebuilt from float/vec4Uniforms over the layout defaults when dirty.
std::vector<u8> paramBytes;
BufferHandle paramUbo = BufferHandle::Invalid;
/** @brief The size paramUbo was made with: what lets the next chain's pass of the same size take it over. */
u32 paramUboBytes = 0;
bool paramDirty = true;
};
/**
* @brief Post-processing effects pipeline
*
* @details Owns the scene capture and the effect chains; the chains themselves
* are declared to a RenderGraph, which decides what physical targets
* they cost. The per-camera and screen-level chains are the same shape
* and go through the same builder.
*/
class PostProcessPipeline {
public:
/**
* @brief Builds a pipeline that declares its chains onto the FRAME's graph.
*
* @details A chain is not a graph of its own: the frame declares the scene
* and the effects that read it to one graph and executes it once,
* so every pass a frame runs is stated in one place.
*/
PostProcessPipeline(GfxDevice& device, RenderContext& context,
resource::ResourceManager& resourceManager, rg::RenderGraph& graph);
/**
* @brief Builds one with no frame behind it; it gets a graph of its own.
*
* @details The fallback path in the bindings, for a pipeline that exists
* without a RenderFrame having made one.
*/
PostProcessPipeline(GfxDevice& device, RenderContext& context,
resource::ResourceManager& resourceManager);
~PostProcessPipeline();
PostProcessPipeline(const PostProcessPipeline&) = delete;
PostProcessPipeline& operator=(const PostProcessPipeline&) = delete;
/**
* @brief Initializes the pipeline with given dimensions
*/
void init(u32 width, u32 height);
/**
* @brief Shuts down and releases resources
*/
void shutdown();
/**
* @brief Resizes the framebuffers
*/
void resize(u32 width, u32 height);
/**
* @brief Adds a post-processing pass
* @param name Unique name for the pass
* @param shader Shader handle for the effect
* @return Index of the added pass
*/
u32 addPass(const std::string& name, resource::ShaderHandle shader);
/**
* @brief Adds a pass that is a compute shader over the picture instead of a draw.
* @details The WGSL is handed these, at group 0: `@binding(0)` the image so far (`texture_2d<f32>`), `@binding(1)`
* the image it writes (`texture_storage_2d<rgba16float, write>`, the same size), `@binding(2)` a uniform
* block of @p params as f32s in that order, `@binding(3)` the size as `vec4f(w, h, 1/w, 1/h)`, `@binding(4)`
* the scene's depth (`texture_depth_2d`), `@binding(5)` a linear clamp sampler. A shader declares the ones it
* uses. It is dispatched over the whole image in groups of @p workgroupX x @p workgroupY, which it declares.
* Compute needs a device that supportsCompute(): on one that does not the pass is left out of the chain, and
* the picture goes through as it was.
* @return Index of the added pass.
*/
u32 addComputePass(const std::string& name, const std::string& wgsl, const std::vector<std::string>& params,
u32 workgroupX, u32 workgroupY);
/**
* @brief Adds a pass the engine implements itself: "voxelGI" (see VoxelGI). Its parameters are set like any pass's, by name.
* @details Needs a device with a compute stage; elsewhere the pass is left out of the chain.
*/
u32 addNativePass(const std::string& name, const std::string& kind);
/// Whether passes added with addComputePass run on this device.
bool supportsCompute() const;
/// The project's multisampling request; 1 = off. Clamped by the device.
void setRequestedSamples(u32 samples);
/// What the scene target is actually created with: the request after the
/// device's ceiling. The two silently differing is how a project ships at 1x
/// believing it asked for 8.
u32 sceneSamples() const { return scene_samples_; }
/// What was asked for, before the ceiling.
u32 requestedSamples() const { return requested_samples_; }
/// Draw @p passName at @p scale of the chain size (clamped to (0, 1]).
void setPassScale(const std::string& passName, f32 scale);
/// Mark @p passName as a later pass of the effect the pass before it began.
void setPassContinuesEffect(const std::string& passName);
/**
* @brief Sets a float uniform for a pass
*/
void setPassUniformFloat(const std::string& passName, const std::string& uniform, f32 value);
/**
* @brief Binds a texture to a pass's sampler uniform (unit 2 upward, in
* registration order). Replaces an existing binding of the same name.
*/
void setPassTexture(const std::string& passName, const std::string& uniform, u32 glTextureId);
/**
* @brief Sets a vec4 uniform for a pass
*/
void setPassUniformVec4(const std::string& passName, const std::string& uniform, const glm::vec4& value);
/**
* @brief Gets the pass count
*/
u32 getPassCount() const { return static_cast<u32>(passes_.size()); }
/**
* @brief Gets a pass by index
*/
const PostProcessPass* getPass(u32 index) const;
/**
* @brief Gets a pass by name
*/
const PostProcessPass* getPass(const std::string& name) const;
/**
* @brief Begins rendering to the pipeline
* @details Binds the input framebuffer. Render scene content after this.
* @p clearColor (RGBA) colors the capture's load-op clear — the
* camera background; null = opaque black.
*/
void begin(const f32* clearColor = nullptr);
/** The graph resource the scene is captured into, for the frame to declare
* its scene pass against. kNoResource when no capture is open. */
rg::ResourceId sceneResource() const { return inFrame_ ? sceneResource_ : rg::kNoResource; }
/** Declares this camera's chain onto the frame's graph. The frame runs it. */
void declareChain();
/** Closes the capture once the graph has run it. */
void chainDone();
/**
* @brief Whether this frame's chain holds a temporal effect.
*
* @details An effect is temporal when its shader declares a `u_history` texture:
* the engine then keeps the pass's last output for it and shifts the
* picture by a sub-pixel amount each frame. The pass list is the
* answer, so there is no flag to disagree with it.
*/
bool temporalActive();
/**
* @brief Whether an enabled pass that keeps no history reads the previous camera (`u_prevViewProjection0`).
*
* @details Motion blur is one: it needs to know where each pixel was a frame ago, and nothing else of the
* temporal machinery — no history, and above all no sub-pixel shift, which would shake a picture
* nothing resolves. The frame then follows the camera with @ref trackView.
*/
bool cameraMotionWanted();
/// The shape of the copy of the opaque scene a refractive surface reads: the chain's own, bilinear.
rg::TargetDesc grabTarget() const { return chainTarget(/*withDepth=*/false); }
/// Copies what is bound at unit 0 (the scene, as the pass before drew it) into the target being drawn. No exposure, no curve, no
/// encode: a copy, with the alpha set to a marker (0.5) a shader can tell from the white a texture param falls back to — unless
/// @p marked is false, for a copy that stands in for the scene itself (kept aside and put back): its alpha is coverage, and is kept.
void grabScene(bool marked = true);
/// Whether this device can hold the distances a depth copy is made of: a float target. Without one a surface that measures
/// the water in front of what is behind it gets no depth and falls back to a fixed column.
bool canGrabDepth();
/// The shape of the copy of the opaque scene's depth: how far each pixel is from the eye, in the red channel of a float target.
rg::TargetDesc grabDepthTarget() {
rg::TargetDesc desc = chainTarget(/*withDepth=*/false);
desc.format = GfxPixelFormat::RGBA16F;
return desc;
}
/// Draws, into the target being drawn, the distance to the opaque scene at every pixel (the scene's depth, read at its unit).
void grabDepth();
/**
* @brief Whether the scene is to be cleared to nothing (all four channels zero) so that its alpha says how much of each pixel geometry covers.
*
* @details A sky drawn after the scene (the Sky Atmosphere effect) replaces every pixel whose depth is the far plane. Depth is resolved from
* one sample of a multisampled target, so a wire narrower than a pixel — covered at some samples, not at the one depth keeps — is
* painted over wherever that sample missed, and a line becomes dashes. With a clear of (0,0,0,0) the resolved colour is the
* geometry's share premultiplied and the alpha is its coverage, which is exactly what the sky has to be laid UNDER.
* An enabled pass asks for it by declaring `u_sceneCoverage`, unless it keeps the scene's own background (`u_panorama` above zero):
* there the cleared pixels are what the picture shows, and they must stay the camera's colour.
*/
bool sceneCoverageWanted();
/// Records this frame's camera as the view @p key's current one, and last frame's as its previous. No shift.
void trackView(const glm::mat4& viewProjection, u64 key);
/**
* @brief Whether an enabled pass reads how far each moving surface travelled (`u_velocity`).
*
* @details The frame then draws its moving meshes a second time into a target of its own, so a
* temporal effect can follow an object by its own displacement instead of the camera's.
*/
bool velocityWanted();
/// What a temporal view would be given by its NEXT begin: the sub-pixel shift and last frame's camera.
struct TemporalView {
glm::vec2 jitter{0.0f};
glm::mat4 previous{1.0f};
/// The shift the previous frame was drawn with.
glm::vec2 previousJitter{0.0f};
};
/// Read before the scene is drawn, because the motion pass is collected with the scene and the shift
/// is only applied when it is drawn. Changes nothing: beginTemporalView still takes the same step.
TemporalView peekTemporalView(const glm::mat4& viewProjection, u64 key) const;
/**
* @brief The motion pass's target for this frame, declared in the graph (kNoResource when it cannot be made).
*
* @details RGBA32F: xy = how far the surface moved in uv, z = its window depth, w = 1 where something wrote.
* Depth in a float because the reader compares it with the scene's, and a half cannot tell two
* surfaces apart near the far plane.
*/
rg::ResourceId declareVelocity();
/**
* @brief Whether an enabled pass reads what stands over each place (`u_rainCover`).
*
* @details The frame then draws the scene from straight above, depth only, around the camera: a map of the highest
* surface at each spot, so an effect can tell open ground from ground under an awning.
*/
bool coverWanted();
/// How far from the camera, in world units, that map reaches each way (the effect's `u_shelterRange`).
f32 coverRange();
/// The bias the drawing effect reads the map with (its u_shelterBias), for a pass that only borrows the map.
f32 coverBias();
/// The map's target for this frame, declared in the graph (kNoResource when it cannot be made).
rg::ResourceId declareCover(u32 size);
/// The matrix the map was drawn through, for the effect to put a world point in it.
void setCoverMatrix(const glm::mat4& viewProjection) { cover_matrix_ = viewProjection; }
/**
* @brief Whether this frame's scene target carries a second attachment for the surface's material.
*
* @details Decided when the capture opens, from the passes: an effect whose shader says
* `#pragma gbuffer` reads what a surface IS (normal, roughness, metalness), which the
* scene's own shaders write beside the colour. A frame with no such effect makes none, so
* the cost is paid only by the project that asked for it.
*/
bool sceneHasGBuffer() const { return inFrame_ && scene_gbuffer_; }
/**
* @brief The frame's environment atlas, for an effect that reflects it (`u_environment`).
*
* @details Handed over by the frame that bound it for the scene: the same atlas the meshes
* reflect, so a reflection an effect adds where the scene's own ray found nothing is the
* sky the surface already shows. 0 = none this frame.
*/
void setEnvironmentTexture(u32 glTextureId) { environment_texture_ = glTextureId; }
/**
* @brief The frame's shadow atlas, for an effect that asks whether a point of air is in the sun (`#pragma lights`).
*
* @details The atlas is a graph resource the scene pass names as a dependency; an effect that reads it names it
* too, or the graph would hand it back to the pool before the effect ran. 0 / kNoResource = no map.
*/
void setShadowAtlas(u32 glTextureId, rg::ResourceId resource) {
shadow_texture_ = glTextureId;
shadow_resource_ = resource;
}
/**
* @brief Starts a frame of the temporal view @p key, and answers how far to shift it.
*
* @param key Names the view whose history this is — two cameras must not
* blend into one history. 0 for the screen.
* @return The shift in clip-square units, to hand to the camera constants.
*/
glm::vec2 beginTemporalView(const glm::mat4& viewProjection, u64 key);
/**
* @brief Checks if pipeline is initialized
*/
bool isInitialized() const { return initialized_; }
/**
* @brief Whether the scene goes through the graph or straight to the surface.
*
* @details Effects to run, the linear pipeline, an output transform, a display LUT or a scaling present engage it. One predicate, because
* everyone asks at both ends of a frame and a capture opened but never resolved is one edit away.
*/
bool isEngaged() const {
// `initialized_` leads, and that is load-bearing: init refuses when the
// blit shader will not compile, so a chain that cannot present degrades
// to drawing straight at the surface rather than to a black frame.
return initialized_ && ((!bypass_ && !passes_.empty()) || linear_output_
|| output_transform_ != OutputTransform::None
|| displayLutActive()
|| view_exposure_ != 0.0f
|| presentScales() || present_required_ || compute_needs_depth_);
}
/**
* @brief Whether the chain's own size differs from the rect it lands in.
*
* @details Inferred rather than flagged: the chain size and the output rect
* are already two separate calls, so "they disagree" needs no third
* piece of state to go stale. A scene rendered at one resolution and
* presented at another is a scale, and a scale needs the blit.
*/
bool presentScales() const {
return output_vp_w_ > 0 && output_vp_h_ > 0
&& (output_vp_w_ != width_ || output_vp_h_ != height_);
}
/**
* @brief The caller has decided this frame needs a present.
*
* @details A DECISION, not a rect — which is why it is set rather than
* inferred like presentScales(). A 1x letterbox and a split-screen
* viewport are the same geometry, same size and offset, and differ
* only in intent; the two rects cannot say which is which.
*/
/// A compute pass reads the scene's depth, which only a scene drawn into a target of the graph's has.
void setComputeNeedsDepth(bool needs) { compute_needs_depth_ = needs; }
void setPresentRequired(bool required) { present_required_ = required; }
/**
* @brief This camera keeps the colour under it: its present composites over the target by coverage.
*
* @details A camera that does not clear colour (a first-person view model, any overlay) still goes through a capture when
* the frame is linear or has an output transform, and the capture starts empty. Copied over the target as it
* was, it replaced the camera underneath with black. Set by the frame when it opens such a camera's pass (its
* capture is then cleared to transparent); cleared when the camera's chain is done.
*/
void setPresentOver(bool over) { present_over_ = over; }
/**
* @brief Whether the present is a whole-multiple upscale of the chain.
*
* @details Inferred from the two rects, for the reason presentScales() is:
* the rect is the one authority, and a filter beside it is a second
* one to disagree with. A whole multiple copies exactly, and
* interpolating it blurs a picture that needed no resampling.
*/
/// A present that stretches the chain's picture over a bigger rect by a factor that is not a whole number: where a
/// bilinear copy would blur it, and the blit resamples with a sharper filter instead.
bool presentUpscales() const {
return presentScales() && width_ > 0 && height_ > 0 && !presentIsWholeMultiple()
&& (output_vp_w_ > width_ || output_vp_h_ > height_);
}
bool presentIsWholeMultiple() const {
if (!presentScales() || width_ == 0 || height_ == 0) return false;
if (output_vp_w_ % width_ || output_vp_h_ % height_) return false;
return output_vp_w_ / width_ == output_vp_h_ / height_;
}
/**
* @brief Skip the EFFECTS, not the chain.
*
* @details It gates the authored passes and nothing else. The linear encode,
* the output transform and a scaling present all still engage —
* none of them is an effect, they are how the image reaches the
* screen, and a camera with no stack still needs them.
*/
void setBypass(bool bypass) { bypass_ = bypass; }
/**
* @brief Linear-light mode: sRGB-format intermediates (hardware linear
* blending) and an always-engaged capture+blit whose final pass
* carries the linear->sRGB encode. Overrides bypass.
*/
void setLinearOutput(bool linear) { linear_output_ = linear; }
/**
* @brief What this frame's intermediates were asked to be and allowed to be.
*
* @details The committed decision, not a re-derivation: an editor explaining
* why a linear project is running at 8-bit has to agree with the
* targets the frame actually made.
*/
const HdrFormatDecision& hdrFormat() const { return frame_format_; }
/**
* @brief Whether the scene target needs a depth attachment.
*
* @details A depth buffer is per-frame memory and clear bandwidth (≈8MB at 1080p),
* which a project with no depth layer should not pay for a feature it does
* not use. A flag and nothing more: the scene target is declared to the
* graph at every begin(), so the next frame asks the pool for the shape
* this answer describes and the old one is simply never handed out again.
*/
void setSceneNeedsDepth(bool needs) { scene_needs_depth_ = needs; }
bool linearOutput() const { return linear_output_; }
/**
* @brief The curve the final pass applies to scene values.
*
* @details Costs nothing when the chain is already engaged — the blit was
* always going to run — so this is a variant of that shader rather
* than a pass of its own.
*/
void setOutputTransform(OutputTransform transform) { output_transform_ = transform; }
/**
* @brief A graded look the final pass applies to the picture as the display will show it.
*
* @details The display stage of the last pass: after the output transform and the transfer function, from a 32x32x32 table laid out as
* a 1024x32 strip (slice along x is blue). It is a variant of that shader, so it costs one texture read and no pass. It belongs
* to the chain that set it, and is let go with the passes (clearPasses): a camera that wants it says so each time.
* @param glTexture The table's texture, or 0 for none.
* @param amount How far the picture moves toward the table's answer, 0 to 1.
*/
void setDisplayLut(u32 glTexture, f32 amount) {
display_lut_texture_ = glTexture;
display_lut_amount_ = std::isfinite(amount) ? std::clamp(amount, 0.0f, 1.0f) : 0.0f;
}
bool displayLutActive() const { return display_lut_texture_ != 0 && display_lut_amount_ > 0.0f; }
/// The editor view's exposure in stops, applied by the blit. Engages the blit when
/// non-zero, since only the blit carries it; the value rides the frame's time block.
void setViewExposure(f32 ev);
OutputTransform outputTransform() const { return output_transform_; }
/**
* @brief Checks if bypass mode is enabled
*/
/**
* @brief Clears all passes
*/
void clearPasses();
/**
* @brief Sets the output target for the final blit (Default = screen)
*/
void setOutputTarget(FramebufferHandle target);
/**
* @brief Sets the output viewport for the final blit
*/
void setOutputViewport(u32 x, u32 y, u32 w, u32 h);
/**
* @brief Begins screen-level capture (all camera output goes into screen FBO)
*/
void beginScreenCapture();
/**
* @brief Ends screen-level capture
*/
void endScreenCapture();
/**
* @brief Executes screen-level post-process passes on captured output
*/
void executeScreenPasses();
/**
* @brief Adds a screen-level post-process pass
*/
u32 addScreenPass(const std::string& name, resource::ShaderHandle shader);
/**
* @brief Clears all screen-level passes
*/
void clearScreenPasses();
/**
* @brief Sets a float uniform for a screen-level pass
*/
void setScreenPassUniformFloat(const std::string& passName, const std::string& uniform, f32 value);
/**
* @brief Sets a vec4 uniform for a screen-level pass
*/
void setScreenPassUniformVec4(const std::string& passName, const std::string& uniform, const glm::vec4& value);
/**
* @brief Gets the screen pass count
*/
u32 getScreenPassCount() const { return static_cast<u32>(screenPasses_.size()); }
/**
* @brief Checks if screen capture is active
*/
bool isScreenCaptureActive() const { return screenCaptureActive_; }
/** @brief The surface the scene is currently rendering into: the screen-capture
* FBO when the screen stack is live, the per-camera capture when
* in-frame, else the default target. The main-pass load-op clear must
* land HERE — rebinding the default target mid-capture breaks the stack. */
FramebufferHandle currentSceneFBO() const;
/**
* @brief Draws pass @p passName once more, next frame, into a @p width x @p height RGBA8 target with its float param
* `u_skyCapture` at 1, and reads it back: a sky effect's panorama (see the SDK's defineSkyEffect).
* @details The pass is drawn from a copy with a parameter buffer of its own — the same buffer written twice in one
* frame is one write on WebGPU. A request while one is in flight replaces it.
*/
void requestSkyCapture(const std::string& passName, u32 width, u32 height);
/** @brief Draws the texture on unit 0 into the bound target as RGBM over 8 (alpha 0 kept for nothing drawn): a probe
* capture's face, packed for an 8-bit readback. Called inside a graph pass that reads that texture. */
void encodeRgbm();
/** @brief 0 = not yet, 1 = the pixels are ready (skyCapturePixels), 2 = none was asked for or it failed. Issues the
* readback itself once the capture has been drawn, so call it between frames, never inside one. */
i32 pollSkyCapture();
/** @brief The captured pixels, RGBA8, rows bottom-up as every readback lands. Valid after poll answered 1. */
const std::vector<u8>& skyCapturePixels() const { return sky_capture_.pixels; }
/**
* @brief The sky that casts the sun's cloud shadow this frame, how far its map reaches each way in kilometres, and how many world
* units its kilometre is (its own `u_unitsPerKm` where it says, as Sky Atmosphere does; 0 where it leaves it to the project).
* @details A pass whose shader declares `u_cloudShadowPass` (sdk postprocess/cloudShadowParams.ts) and has `u_castCloudShadows`
* on, and, where it has a strength (Sky Atmosphere's `u_cloudShadow`), above nothing. Null when no enabled pass does.
*/
const PostProcessPass* cloudShadowCaster(f32& extentKm, f32& unitsPerKm) const;
/**
* @brief Draws the caster's cloud shadow into the tile at @p rect of the bound target: what of the sun is left in the alpha, white above.
* @details @p rect is the tile as the sun reads it (origin and side, in the target's texture coordinates), and @p inverse takes the
* tile's corners (clip x and y, -1 to 1) back to the world. The pass covers the target and finds the tile by the same
* coordinates the lookup uses, so the two agree on either backend whatever its viewport convention. Called from a graph pass
* that writes the shadow atlas before the scene, so the atlas is not bound for reading while it is drawn.
*/
void drawCloudShadow(const glm::mat4& inverse, const glm::vec4& rect, const rg::PassContext& ctx);
/// Draws material @p material through PostProcess shader @p shader over the pass's viewport (RenderFrame::queueMaterialBake), its
/// block in MaterialStore scratch @p scratch. False when it could not.
bool drawMaterialThrough(u32 material, u32 shader, const std::vector<std::pair<std::string, glm::vec4>>& overrides, u32 scratch);
private:
PostProcessPass* findPass(const std::string& name);
/// The capture's node: the copy of @p pass drawn into the capture target. Declared in the chain so it runs with the
/// frame's light and time bound, as the pass itself does.
void declareSkyCapture(const PostProcessPass& pass, rg::ResourceId input, rg::ResourceId effectInput);
/** Intermediate/capture attachment format for the active pipeline mode. */
GfxPixelFormat interFormat() const;
void commitFormat();
/** The shape of every target in a chain, the scene target included. */
rg::TargetDesc chainTarget(bool withDepth) const;
rg::TargetDesc blitSourceTarget(bool withDepth) const;
void ensureGraph();
void ensureScreenQuad();
void drawScreenQuad();
/// @p over: composite onto the target by the source's coverage (premultiplied) instead of replacing it.
void applyPassPipeline(const Shader& shader, bool over = false);
void renderPass(PostProcessPass& pass, const rg::PassContext& ctx);
/// A compute pass: its params and the size into a block each, the picture, the depth and the output bound, one dispatch over it.
void computePass(PostProcessPass& pass, const rg::PassContext& ctx);
/// Whether a pass has anything to run on this device: a drawn pass always, a compute one only where there is compute.
bool runnable(const PostProcessPass& pass) const;
/// Compute programs by source, kept while the pipeline lives: the passes are pushed again every camera, and a
/// program is a compiled pipeline, not something to build per frame.
std::unordered_map<std::string, ComputeHandle> compute_cache_;
/// The voxel GI's cache lives here, across frames: what it has seen is the point of it. One per camera, since a cache is a
/// window around the eye and two eyes would take turns tearing each other's down.
std::unordered_map<u64, Unique<VoxelGI>> voxel_gis_;
std::unordered_map<u64, Unique<DynamicGI>> dynamic_gis_;
/// The size block a compute pass reads, one for all of them (each dispatch writes it just before it runs).
BufferHandle compute_view_ubo_ = BufferHandle::Invalid;
/// Declares one chain onto an already-begun graph and runs it, ending in the
/// output target. @p scene is the resource the first effect reads.
void runChain(std::vector<PostProcessPass>& passes, rg::ResourceId scene);
/// The chain's last pass: the output transform, then the copy into the
/// output target's viewport.
void blitPass();
/// The blit variant the current output transform, present and display LUT need, compiled on demand.
resource::ShaderHandle outputShader();
/// The variant of the blit with these features, or an invalid handle when it does not compile.
resource::ShaderHandle blitVariant(bool upscale, OutputTransform transform, bool lut);
/// Binds what every variant of the blit declares: its parameter block (the display LUT's amount) and the table's texture.
void bindBlitInputs(const resource::ShaderHandle& shader);
/// One variant of blit.esshader, by feature.
resource::ShaderHandle compileBlit(const std::vector<std::string>& features);
/// Frees a pass's GPU-side param UBO (clearPasses/shutdown).
void releasePassResources(PostProcessPass& pass);
/**
* @brief A params block of `bytes` holding `data`: one a cleared chain left behind, if any is that size, or a new one.
*
* A camera's chain is said again every frame (clearPasses, then its passes), and each pass made and deleted a uniform buffer
* of its own each time: seventeen a frame for a lake scene's effects. The buffers of a cleared chain are kept for a few
* clears (a frame clears once per camera, and a camera with no effects sits between two frames of one with them), and one
* nothing took over in that time is deleted.
*/
BufferHandle takeParamUbo(u32 bytes, const void* data);
void dropSpareParamUbos();
struct SpareParamUbo { BufferHandle handle; u32 bytes; u32 clears; };
std::vector<SpareParamUbo> spare_param_ubos_;
GfxDevice& device_;
RenderContext& context_;
resource::ResourceManager& resourceManager_;
/// The frame's graph when one was given; `ownedGraph_` otherwise.
rg::RenderGraph* graph_ = nullptr;
/// The frame's graph, kept so a shutdown can hand it back. Null with no frame.
rg::RenderGraph* frameGraph_ = nullptr;
Unique<rg::RenderGraph> ownedGraph_;
VertexLayoutHandle screen_quad_layout_ = VertexLayoutHandle::Invalid;
BufferHandle screen_quad_vbo_ = BufferHandle::Invalid;
resource::ShaderHandle blitShader_;
/// The other variants of the same file the last pass needs (a curve, the resampling upscaler, the display LUT), by feature set, compiled when
/// a chain first asks. An invalid handle is a variant that would not compile: asked for once, not again.
std::unordered_map<u32, resource::ShaderHandle> blitVariants_;
u32 display_lut_texture_ = 0;
f32 display_lut_amount_ = 0.0f;
/// The last pass's parameter block (the display LUT's amount): one for every variant of the blit, written when the amount changes.
BufferHandle blitParamUbo_ = BufferHandle::Invalid;
f32 blitParamAmount_ = -1.0f;
resource::ShaderHandle copyShader_;
/// The copy that keeps alpha (grabScene(false)): the opaque scene kept aside and put back around the blended draws.
resource::ShaderHandle exactCopyShader_;
resource::ShaderHandle copyDepthShader_;
std::vector<PostProcessPass> passes_;
u32 width_ = 0;
u32 height_ = 0;
bool initialized_ = false;
bool inFrame_ = false;
bool bypass_ = false;
bool linear_output_ = false;
/// The format this frame committed to; see commitFormat().
HdrFormatDecision frame_format_{};
/// What screenFBO_ was created with, so a policy change can be noticed.
GfxPixelFormat screenFBOFormat_ = GfxPixelFormat::RGBA8;
bool scene_needs_depth_ = false;
/// What the PROJECT asked for (policy). 4 matches what a browser gives its
/// own drawing buffer, which is the quality a chain-less frame always had.
u32 requested_samples_ = 4;
/// What the scene target actually rasterises with: the request clamped by
/// the device's ceiling. Never read the ceiling as if it were the answer.
u32 scene_samples_ = 1;
void applySampleRequest();
OutputTransform output_transform_ = OutputTransform::None;
f32 view_exposure_ = 0.0f;
/// The graph resource the scene is drawn into, live between begin() and end().
rg::ResourceId sceneResource_ = rg::kNoResource;
TextureHandle sceneTexture_ = TextureHandle::Invalid;
FramebufferHandle output_target_fbo_ = FramebufferHandle::Default;
u32 output_vp_x_ = 0;
u32 output_vp_y_ = 0;
bool present_required_ = false;
bool present_over_ = false;
bool compute_needs_depth_ = false;
u32 output_vp_w_ = 0;
u32 output_vp_h_ = 0;
/// What a temporal pass remembers of one view between frames.
struct TemporalState {
glm::mat4 current{1.0f};
glm::mat4 previous{1.0f};
/// The render origin `current` was made for: the next frame's `previous` is it, taken to the origin then.
glm::dvec3 origin{0.0};
u32 frame = 0;
/// The frame whose chain last wrote the history; a gap means the history
/// is of a picture this one no longer follows.
u32 writtenFrame = 0;
Unique<Framebuffer> history[2];
u32 readIndex = 0;
bool valid = false;
u32 width = 0;
u32 height = 0;
GfxPixelFormat format = GfxPixelFormat::RGBA8;
};
std::unordered_map<u64, TemporalState> temporal_;
u64 temporalKey_ = 0;
bool passIsTemporal(const PostProcessPass& pass);
bool passUsesLights(const PostProcessPass& pass);
/// Some enabled pass of the chain reads the surface record.
bool passesWantGBuffer();
bool scene_gbuffer_ = false;
u32 environment_texture_ = 0;
u32 shadow_texture_ = 0;
rg::ResourceId shadow_resource_ = rg::kNoResource;
/// The motion pass's target, kept across frames for its size, and whether this frame drew into it.
Unique<Framebuffer> cover_fbo_;
rg::ResourceId cover_resource_ = rg::kNoResource;
/// A sky's panorama, drawn on request from a copy of its pass and read back (requestSkyCapture).
struct SkyCapture {
enum class State : u8 { Idle, Requested, Drawn, Reading };
State state = State::Idle;
std::string pass;
u32 width = 64;
u32 height = 32;
Unique<Framebuffer> target;
PostProcessPass copy;
ReadbackHandle readback = ReadbackHandle::Invalid;
std::vector<u8> pixels;
};
SkyCapture sky_capture_;
/// The caster's pass as drawCloudShadow draws it: the same shader and settings, with the map's own params and parameter buffer.
PostProcessPass cloud_shadow_copy_;
/// While drawCloudShadow draws into the atlas: renderPass binds a white texture where it would bind the atlas.
bool drawing_cloud_shadow_ = false;
resource::ShaderHandle rgbmShader_;
bool cover_active_ = false;
glm::mat4 cover_matrix_{1.0f};
Unique<Framebuffer> velocity_fbo_;
rg::ResourceId velocity_resource_ = rg::kNoResource;
bool velocity_active_ = false;
bool passHasTexture(const PostProcessPass& pass, const char* name);
/// A pass that has the overhead cover map drawn for it (it states a reach, u_shelterRange), not one that only reads it.
bool passDrawsCover(const PostProcessPass& pass);
/// A history made (or kept) at @p w x @p h, or null when it cannot be.
TemporalState* prepareHistory(TemporalState& state, u32 w, u32 h, GfxPixelFormat format);
/// The pass writes a measurement, so its target is a float one where the device has them.
bool passIsHighPrecision(const PostProcessPass& pass);
/// Per pass, per view: what a `u_feedback` pass remembers.
std::unordered_map<u64, TemporalState> feedback_;
u64 feedbackKey(const std::string& passName) const;
Unique<Framebuffer> screenFBO_;
bool screenFBOCreated_ = false;
bool screenCaptureActive_ = false;
std::vector<PostProcessPass> screenPasses_;
PostProcessPass* findScreenPass(const std::string& name);
void ensureScreenFBO();
};
} // namespace esengine