Extend the renderer
Add your own GPU passes at fixed points of the frame from a game module or plugin, and know what the scene renderer accepts from code.
A game module or plugin can add GPU work at a fixed place in the frame without changing SceneRenderer. You register a pass at an insertion point, say which scene textures it reads and writes, and record it with the Renderer:: API. The renderer adds it to its frame graph, so the barriers before and after your pass are handled for you.
Insertion points
ERenderPassPoint names six points in the frame pipeline:
| Point | Runs | What the scene textures hold |
|---|---|---|
AfterGBuffer | After the G-Buffer pass and GPU foliage | The opaque G-Buffer and depth. Nothing is lit. |
BeforeLighting | After decals, AO and ray-traced sun shadows | The G-Buffer as lighting will read it. |
AfterLighting | After direct light, MegaLights, Global Illumination, SSGI and subsurface scattering | SceneColor holds opaque lit radiance. The sky is next. |
BeforeTranslucency | After sky, clouds, fog and reflections | SceneColor without glass, water and particles. |
AfterTonemap | After the tonemap, before TAA, lens flare and the final pass | PostTonemapColor holds the display-encoded image. |
BeforeUI | After the final pass and the editor overlays | Output is the presentable image the UI draws over. |
Scene textures
A pass names the textures it touches with ESceneTexture:
| Texture | Format | Available |
|---|---|---|
SceneColor | RGBA16F, lit HDR at render resolution | Every point |
SceneDepth | D32F, read-only | Every point |
GBufferA | RGBA8: albedo, metallic | Every point |
GBufferB | RGBA16F: world normal, roughness | Every point |
GBufferC | RGBA16F: emissive, AO | Every point |
PostTonemapColor | RGBA8 for SDR, RGBA16F for an HDR display | AfterTonemap and BeforeUI |
Output | The presentable image | BeforeUI only |
Each use also has an access: ShaderRead, UnorderedAccess, RenderTarget or DepthRead. A pass that names a texture its point does not have yet is skipped there with one warning. A pass that tries to write SceneDepth is refused.
Register a pass
Fill an FRenderPassExtensionDesc and hand it to FRenderPassExtensions::Register. This example draws letterbox bars over the tonemapped image with the ready-made FSceneTextureFill body, which overwrites a rectangle of an RGBA8 or RGBA16F texture through a UAV:
#include "Renderer/RenderPassExtension.h"
#include "RHI/Renderer.h"
#include <algorithm>
#include <cstdint>
#include <memory>
#include <utility>
static uint64_t s_LetterboxHandle = 0;
static std::unique_ptr<Mowo::FSceneTextureFill> s_LetterboxFill;
void RegisterLetterbox() {
s_LetterboxFill = std::make_unique<Mowo::FSceneTextureFill>();
Mowo::FRenderPassExtensionDesc desc;
desc.Name = "Letterbox";
desc.Point = Mowo::ERenderPassPoint::AfterTonemap;
desc.Writes = { { Mowo::ESceneTexture::PostTonemapColor, Mowo::ESceneTextureAccess::UnorderedAccess } };
desc.Execute = [](const Mowo::FRenderPassContext& ctx) {
const uint32_t bar = std::max(1u, ctx.OutputHeight / 16);
const Mowo::Vec4 black(0.0f, 0.0f, 0.0f, 1.0f);
s_LetterboxFill->Fill(ctx, Mowo::ESceneTexture::PostTonemapColor, 0, 0, ctx.OutputWidth, bar, black);
s_LetterboxFill->Fill(ctx, Mowo::ESceneTexture::PostTonemapColor, 0, ctx.OutputHeight - bar, ctx.OutputWidth, ctx.OutputHeight, black);
};
s_LetterboxHandle = Mowo::FRenderPassExtensions::Register(std::move(desc));
}
void UnregisterLetterbox() {
if (s_LetterboxHandle != 0) {
Mowo::FRenderPassExtensions::Unregister(s_LetterboxHandle);
s_LetterboxHandle = 0;
}
if (s_LetterboxFill && Mowo::Renderer::GetDynamicRHI()) {
Mowo::Renderer::WaitIdle();
}
s_LetterboxFill.reset();
}Call the register function from your module's startup and the unregister function from its shutdown. The MowoSandbox game-module template does exactly this ().
What the pass body gets
The body receives an FRenderPassContext:
GetTexture(texture)returns each declared texture, already in the state you asked for.WidthandHeightare the active render extent. With dynamic resolution the frame renders into the top-left of a larger allocation, so do not use the texture size.OutputWidthandOutputHeightare the size ofPostTonemapColorandOutputwhen an upscaler resolved the frame.FrameIndex,ViewandProjectiondescribe the current view.
Record with the Renderer:: API: bind your pipeline and descriptor sets, then draw or dispatch. Whatever runs after your pass gets its own barriers, so a UAV write into SceneColor is transitioned back before the sky draws into it.
Ordering
Passes at the same point run by Priority, lowest first, then in registration order. A pass that reads what another writes is ordered after it by the graph whatever the priority says.
Registration is thread-safe. Each registration bumps a generation number; the renderer checks it once per frame and rebuilds the affected graph, so a new pass appears on the next frame and never in the middle of one.
Module lifetime
Every entry remembers the module that registered it. When that module unloads, the engine drains the rendering thread and removes its passes, clearing each body while the module is still mapped, so no graph calls into freed code. This is a safety net: still call Unregister in your module's shutdown, and destroy your pipelines only after the GPU has finished with them, as the example does with Renderer::WaitIdle().
Drawing through the scene renderer
Most content reaches the renderer through components in a scene, and the scene's render bridge submits it each frame. When you drive a SceneRenderer yourself, bracket a frame with BeginScene(camera, environment) and EndScene(), and submit between them with SubmitStaticMesh, SubmitSkinnedMesh, SubmitDirectionalLight, SubmitPointLight, SubmitSpotLight, SubmitRectLight, SubmitDecal, SubmitReflectionProbe, SubmitFogVolume and SubmitDebugLines (). One renderer can drive several views with CreateView: each view owns its resolution-sized targets, temporal history and eye adaptation (a screenshot or capture view meters its own exposure), and the scene-wide data (shadow atlases, Global Illumination volumes, pipelines) is shared.
API reference
- SceneRenderer module:
FRenderPassExtensions,FRenderPassExtensionDesc,FRenderPassContext,FSceneTextureFill,SceneRenderer
Engine sources
This page describes behavior implemented in these files of the engine repository, checked against commit d1ef44623.
- Engine/Source/Runtime/SceneRenderer/Public/Renderer/RenderPassExtension.h
- Engine/Source/Runtime/SceneRenderer/Public/Renderer/SceneRenderer.h