Skip to content

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.

perf(gi): the medium level runs the dynamic GI its cheaper way - half-resolution gather, a quarter of a probe's rays a frame, cards over eight frames, two thirds of the probe rows; 7.3 -> 4.5 ms on a Snapdragon 8 Elite

yhh447c76c64482
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 927a91a71..5268fcc2a 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -8113,7 +8113,7 @@ antialiasing: "msaa" | "temporal"
begin: () => void
bind: (camera: Entity, stack: PostProcessStack) => void
createStack: () => PostProcessStack
-dynamicGIHalfRes: boolean
+dynamicGIReduced: boolean
effectAllowed: (type: string) => boolean
end: () => void
getStack: (camera: Entity) => PostProcessStack | null
@@ -8591,7 +8591,7 @@ antialiasing: "msaa" | "temporal"
depthPrepass: boolean
detailScale: number
drawCallBudget: number
-dynamicGIHalfRes: boolean
+dynamicGIReduced: boolean
lighting: "full" | "direct"
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index a2eb93f0e..ab7d62c5a 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -8320,7 +8320,7 @@ antialiasing: "msaa" | "temporal"
begin: () => void
bind: (camera: Entity, stack: PostProcessStack) => void
createStack: () => PostProcessStack
-dynamicGIHalfRes: boolean
+dynamicGIReduced: boolean
effectAllowed: (type: string) => boolean
end: () => void
getStack: (camera: Entity) => PostProcessStack | null
@@ -8798,7 +8798,7 @@ antialiasing: "msaa" | "temporal"
depthPrepass: boolean
detailScale: number
drawCallBudget: number
-dynamicGIHalfRes: boolean
+dynamicGIReduced: boolean
lighting: "full" | "direct"
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 13199dc5b..d7a9618ba 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -8108,7 +8108,7 @@ antialiasing: "msaa" | "temporal"
begin: () => void
bind: (camera: Entity, stack: PostProcessStack) => void
createStack: () => PostProcessStack
-dynamicGIHalfRes: boolean
+dynamicGIReduced: boolean
effectAllowed: (type: string) => boolean
end: () => void
getStack: (camera: Entity) => PostProcessStack | null
@@ -8586,7 +8586,7 @@ antialiasing: "msaa" | "temporal"
depthPrepass: boolean
detailScale: number
drawCallBudget: number
-dynamicGIHalfRes: boolean
+dynamicGIReduced: boolean
lighting: "full" | "direct"
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 2f9f00e69..db2b1eea7 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -8405,7 +8405,7 @@ antialiasing: "msaa" | "temporal"
begin: () => void
bind: (camera: Entity, stack: PostProcessStack) => void
createStack: () => PostProcessStack
-dynamicGIHalfRes: boolean
+dynamicGIReduced: boolean
effectAllowed: (type: string) => boolean
end: () => void
getStack: (camera: Entity) => PostProcessStack | null
@@ -8883,7 +8883,7 @@ antialiasing: "msaa" | "temporal"
depthPrepass: boolean
detailScale: number
drawCallBudget: number
-dynamicGIHalfRes: boolean
+dynamicGIReduced: boolean
lighting: "full" | "direct"
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 9703ea283..588d1c9ff 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -8115,7 +8115,7 @@ antialiasing: "msaa" | "temporal"
begin: () => void
bind: (camera: Entity, stack: PostProcessStack) => void
createStack: () => PostProcessStack
-dynamicGIHalfRes: boolean
+dynamicGIReduced: boolean
effectAllowed: (type: string) => boolean
end: () => void
getStack: (camera: Entity) => PostProcessStack | null
@@ -8593,7 +8593,7 @@ antialiasing: "msaa" | "temporal"
depthPrepass: boolean
detailScale: number
drawCallBudget: number
-dynamicGIHalfRes: boolean
+dynamicGIReduced: boolean
lighting: "full" | "direct"
minRenderScale: number
msaaSamples: 2 | 1 | 4 | 8
diff --git a/sdk/src/postprocess/PostProcessAPI.ts b/sdk/src/postprocess/PostProcessAPI.ts
index cdab10c19..043c77534 100644
--- a/sdk/src/postprocess/PostProcessAPI.ts
+++ b/sdk/src/postprocess/PostProcessAPI.ts
@@ -263,9 +263,9 @@ export class PostProcessAPI {
return this.qualityFilter_?.antialiasing ?? 'msaa';
}
- /** Whether the quality level in force has the dynamic GI gather at half resolution: the volume system sets the effect's switch from it. */
- get dynamicGIHalfRes(): boolean {
- return this.qualityFilter_?.dynamicGIHalfRes ?? false;
+ /** Whether the quality level in force has the dynamic GI run its cheaper way: the volume system sets the effect's switches from it. */
+ get dynamicGIReduced(): boolean {
+ return this.qualityFilter_?.dynamicGIReduced ?? false;
}
/**
diff --git a/sdk/src/postprocess/effects.ts b/sdk/src/postprocess/effects.ts
index 9d0c6140b..423fdbe94 100644
--- a/sdk/src/postprocess/effects.ts
+++ b/sdk/src/postprocess/effects.ts
@@ -589,6 +589,8 @@ registerEffect({
{ name: 'u_skip', label: 'Skip Passes (profiling)', min: 0, max: 63, step: 1, defaultValue: 0 },
// 1: one pixel in four asks the probes and the rest take the light of the four round them. A quality level below the highest turns it on.
{ name: 'u_halfRes', label: 'Half Resolution', min: 0, max: 1, step: 1, defaultValue: 0 },
+ // How many of the rows of probes are kept where Probe Spacing is 0: fewer cost less and blur the light more.
+ { name: 'u_probeDensity', label: 'Probe Density', min: 0.25, max: 1, step: 0.01, defaultValue: 1 },
{ name: 'u_cellSize', label: 'Field Cell Size', min: 0, max: 1000, step: 0.1, defaultValue: 0, worldUnits: 1 },
],
});
diff --git a/sdk/src/postprocess/volumeSystem.ts b/sdk/src/postprocess/volumeSystem.ts
index 565b9848f..db9f33dfe 100644
--- a/sdk/src/postprocess/volumeSystem.ts
+++ b/sdk/src/postprocess/volumeSystem.ts
@@ -275,8 +275,14 @@ function applyBlendedEffects(
} else if (def.native) {
stack.addNativePass(effectType, def.native);
for (const u of def.uniforms) stack.setUniform(effectType, u.name, effectData.uniforms.get(u.name) ?? uniformInUnits(u).defaultValue);
- // The quality level's say over how the dynamic GI gathers: on where the level asks, whatever the volume holds.
- if (effectType === 'dynamicGI' && api.dynamicGIHalfRes) stack.setUniform(effectType, 'u_halfRes', 1);
+ // The quality level's say over what the dynamic GI spends: its cheaper way where the level asks, and never dearer than the volume set.
+ if (effectType === 'dynamicGI' && api.dynamicGIReduced) {
+ const held = (name: string, fallback: number): number => effectData.uniforms.get(name) ?? fallback;
+ stack.setUniform(effectType, 'u_halfRes', 1);
+ stack.setUniform(effectType, 'u_probeStride', Math.max(held('u_probeStride', 2), 4));
+ stack.setUniform(effectType, 'u_cardSlices', Math.max(held('u_cardSlices', 4), 8));
+ stack.setUniform(effectType, 'u_probeDensity', Math.min(held('u_probeDensity', 1), 2 / 3));
+ }
} else if (def.compute) {
// The params block is the effect's uniforms in their listed order, each at the volume's value or the effect's own default.
stack.addComputePass(effectType, {
diff --git a/sdk/src/render/quality.ts b/sdk/src/render/quality.ts
index 8dc475d00..8e1443d16 100644
--- a/sdk/src/render/quality.ts
+++ b/sdk/src/render/quality.ts
@@ -83,10 +83,13 @@ export interface QualityProfile {
shadowSoftSamples: number;
lighting: 'full' | 'direct';
/**
- * Whether the dynamic GI asks its probes for one pixel in four and spreads the light to the rest: about half of what a pixel reads, for
- * light that runs a pixel or two across an edge two surfaces share. It acts on a volume that lists `dynamicGI`, at a level that runs it.
+ * Whether the dynamic GI runs its cheaper way: one pixel in four asks the probes and the rest take the light of the four round them, a
+ * probe traces a quarter of its rays a frame instead of half, the cards are relit over eight frames instead of four, and there are two
+ * thirds of the rows of probes. On a Snapdragon 8 Elite at 2530 x 1200 the effect costs 4.5 ms this way and 7.3 the full way. What it
+ * gives up: light runs a pixel or two across an edge two surfaces share, and light that changes takes about twice as long to settle.
+ * It acts on a volume that lists `dynamicGI`, at a level that runs it, and never makes a volume's own settings dearer.
*/
- dynamicGIHalfRes: boolean;
+ dynamicGIReduced: boolean;
/**
* The most draws a frame at this level should ask of the GPU, every pass counted (shadows, prepass, reflections and post-processing with the
* scene). Nothing is held back to meet it: the profiler and the stats overlay show a frame over it, and the frame debugger says where the draws
@@ -154,7 +157,7 @@ const PROFILES: Record<QualityLevel, QualityProfile> = {
shadowDistance: 0, detailScale: 0.5, particleLimit: 1000, postProcess: true, ssao: false,
waterWaves: 2, waterRippleCells: 32, waterDisplacement: false, waterMirror: false, waterCaustics: false,
skipEffects: ['ssr', 'taa', 'depthOfField', 'lightShafts', 'motionBlur', 'lensFlare', 'gtao', 'subsurface', 'voxelGI', 'dynamicGI'],
- shelterMaskSize: 256, shadowSoftSamples: 8, lighting: 'direct', dynamicGIHalfRes: true, drawCallBudget: 150, textureStreaming: true, textureStreamingBudget: 128,
+ shelterMaskSize: 256, shadowSoftSamples: 8, lighting: 'direct', dynamicGIReduced: true, drawCallBudget: 150, textureStreaming: true, textureStreamingBudget: 128,
},
medium: {
renderScale: 1, minRenderScale: 0.65, msaaSamples: 2, antialiasing: 'temporal',
@@ -163,7 +166,7 @@ const PROFILES: Record<QualityLevel, QualityProfile> = {
shadowDistance: 0, detailScale: 0.8, particleLimit: 5000, postProcess: true, ssao: true,
waterWaves: 3, waterRippleCells: 64, waterDisplacement: true, waterMirror: true, waterCaustics: true,
skipEffects: ['ssr', 'depthOfField'],
- shelterMaskSize: 512, shadowSoftSamples: 12, lighting: 'direct', dynamicGIHalfRes: true, drawCallBudget: 400, textureStreaming: true, textureStreamingBudget: 256,
+ shelterMaskSize: 512, shadowSoftSamples: 12, lighting: 'direct', dynamicGIReduced: true, drawCallBudget: 400, textureStreaming: true, textureStreamingBudget: 256,
},
high: {
renderScale: 1, minRenderScale: 0.75, msaaSamples: 4, antialiasing: 'msaa',
@@ -174,7 +177,7 @@ const PROFILES: Record<QualityLevel, QualityProfile> = {
shadowDistance: 0, detailScale: 1, particleLimit: 20000, postProcess: true, ssao: true,
waterWaves: 4, waterRippleCells: 128, waterDisplacement: true, waterMirror: true, waterCaustics: true,
skipEffects: [],
- shelterMaskSize: 1024, shadowSoftSamples: 16, lighting: 'full', dynamicGIHalfRes: false, drawCallBudget: 1500, textureStreaming: false, textureStreamingBudget: 0,
+ shelterMaskSize: 1024, shadowSoftSamples: 16, lighting: 'full', dynamicGIReduced: false, drawCallBudget: 1500, textureStreaming: false, textureStreamingBudget: 0,
},
};
@@ -277,7 +280,7 @@ function resolveProfile(level: QualityLevel, value: unknown): QualityProfile {
depthPrepass: typeof r.depthPrepass === 'boolean' ? r.depthPrepass : base.depthPrepass,
postProcess: typeof r.postProcess === 'boolean' ? r.postProcess : base.postProcess,
ssao: typeof r.ssao === 'boolean' ? r.ssao : base.ssao,
- dynamicGIHalfRes: typeof r.dynamicGIHalfRes === 'boolean' ? r.dynamicGIHalfRes : base.dynamicGIHalfRes,
+ dynamicGIReduced: typeof r.dynamicGIReduced === 'boolean' ? r.dynamicGIReduced : base.dynamicGIReduced,
waterWaves: Math.round(finite(r.waterWaves, base.waterWaves, 1, 4)),
waterRippleCells: Math.round(finite(r.waterRippleCells, base.waterRippleCells, 0, 256)),
waterDisplacement: typeof r.waterDisplacement === 'boolean' ? r.waterDisplacement : base.waterDisplacement,
diff --git a/sdk/tests/quality.test.ts b/sdk/tests/quality.test.ts
index 6c0c494d0..84a47f217 100644
--- a/sdk/tests/quality.test.ts
+++ b/sdk/tests/quality.test.ts
@@ -232,6 +232,12 @@ describe('what a quality level lets the chain run', () => {
}
});
+ it('runs the dynamic GI its cheaper way at the medium level and the full way at the high one', () => {
+ expect(new QualityController({ mode: 'medium' }).profile.dynamicGIReduced).toBe(true);
+ expect(new QualityController({ mode: 'high' }).profile.dynamicGIReduced).toBe(false);
+ expect(new QualityController({ mode: 'high', profiles: { high: { dynamicGIReduced: true } } }).profile.dynamicGIReduced).toBe(true);
+ });
+
it('keeps the old prefix reading for a name no effect answers to, and the ssao and post-process switches', async () => {
const { qualityPassAllowed } = await import('../src/postprocess/qualityFilter');
expect(qualityPassAllowed(level(['custom']), 'custom_pass')).toBe(false);
diff --git a/src/esengine/renderer/frame/DynamicGI.cpp b/src/esengine/renderer/frame/DynamicGI.cpp
index 5552041c9..4c5e35eff 100644
--- a/src/esengine/renderer/frame/DynamicGI.cpp
+++ b/src/esengine/renderer/frame/DynamicGI.cpp
@@ -869,8 +869,11 @@ rg::ResourceId DynamicGI::declare(rg::RenderGraph& graph, rg::ResourceId input,
#else
constexpr u32 kProbeRows = 90;
#endif
+ // A quality level may ask for fewer rows still (`probeDensity` under 1): two thirds of them is 30 rows on a phone, 1.2 ms of a
+ // Snapdragon 8 Elite's 6.6.
+ const u32 rows = std::max(static_cast<u32>(static_cast<f32>(kProbeRows) * std::clamp(params.probeDensity, 0.25f, 1.0f) + 0.5f), 8u);
probeSpacing_ = params.probeSpacing > 0 ? std::clamp(params.probeSpacing, 4u, 64u)
- : std::clamp(((height + kProbeRows - 1) / kProbeRows + 1) / 2 * 2, 8u, 32u);
+ : std::clamp(((height + rows - 1) / rows + 1) / 2 * 2, 8u, 48u);
const u32 tilesX = (width + probeSpacing_ - 1) / probeSpacing_, tilesY = (height + probeSpacing_ - 1) / probeSpacing_;
if (!ensureProbes(tilesX, tilesY)) return input;
diff --git a/src/esengine/renderer/frame/DynamicGI.hpp b/src/esengine/renderer/frame/DynamicGI.hpp
index 60c410de7..89513a15e 100644
--- a/src/esengine/renderer/frame/DynamicGI.hpp
+++ b/src/esengine/renderer/frame/DynamicGI.hpp
@@ -48,6 +48,8 @@ struct DynamicGIParams {
/// The probes are asked by one pixel in four and the rest take the light of the four round them: about half the reads of a pixel, for
/// light that runs a pixel or two across an edge two surfaces share. What a quality level below the highest runs.
bool halfRes = false;
+ /// How many of the rows of probes the picture would have are kept, 0.25 to 1 (it acts where `probeSpacing` is 0).
+ f32 probeDensity = 1.0f;
};
/**
diff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cpp
index a3fd2e827..203822223 100644
--- a/src/esengine/renderer/frame/PostProcessPipeline.cpp
+++ b/src/esengine/renderer/frame/PostProcessPipeline.cpp
@@ -1341,6 +1341,7 @@ void PostProcessPipeline::runChain(std::vector<PostProcessPass>& passes, rg::Res
gi.skip = static_cast<u32>(std::max(get("u_skip", 0.0f), 0.0f));
gi.probeSpacing = static_cast<u32>(std::max(get("u_probeSpacing", 0.0f), 0.0f));
gi.halfRes = get("u_halfRes", 0.0f) > 0.5f;
+ gi.probeDensity = get("u_probeDensity", 1.0f);
auto& cache = dynamic_gis_[temporalKey_];
if (!cache) {
if (dynamic_gis_.size() > 4) {