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.

feat(render): the SDK can say a present is needed, because the rects cannot

yhh8e5599e2bf07
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index a930f53d0..2d147257f 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -5816,6 +5816,7 @@ screenStack: PostProcessStack | null
setBypass: (bypass: boolean) => void
setOutputTransform: (transform: OutputTransform) => void
setOutputViewport: (x: number, y: number, w: number, h: number) => void
+setPresentRequired: (required: boolean) => void
setScreenStack: (stack: PostProcessStack | null) => void
shutdown: () => void
state: PostProcessState
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index bca2ae7f8..f5f898af8 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -5999,6 +5999,7 @@ screenStack: PostProcessStack | null
setBypass: (bypass: boolean) => void
setOutputTransform: (transform: OutputTransform) => void
setOutputViewport: (x: number, y: number, w: number, h: number) => void
+setPresentRequired: (required: boolean) => void
setScreenStack: (stack: PostProcessStack | null) => void
shutdown: () => void
state: PostProcessState
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index c939987c6..e2fa112ab 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -5811,6 +5811,7 @@ screenStack: PostProcessStack | null
setBypass: (bypass: boolean) => void
setOutputTransform: (transform: OutputTransform) => void
setOutputViewport: (x: number, y: number, w: number, h: number) => void
+setPresentRequired: (required: boolean) => void
setScreenStack: (stack: PostProcessStack | null) => void
shutdown: () => void
state: PostProcessState
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index f66da3c31..cfdd88551 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -6056,6 +6056,7 @@ screenStack: PostProcessStack | null
setBypass: (bypass: boolean) => void
setOutputTransform: (transform: OutputTransform) => void
setOutputViewport: (x: number, y: number, w: number, h: number) => void
+setPresentRequired: (required: boolean) => void
setScreenStack: (stack: PostProcessStack | null) => void
shutdown: () => void
state: PostProcessState
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 44b796334..0be1d3c1c 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -326,6 +326,7 @@ postprocess_setBypass: (bypass: boolean) => void
postprocess_setOutputTransform: ((transform: number) => void) | undefined
postprocess_setOutputViewport: (x: number, y: number, w: number, h: number) => void
postprocess_setPassTexture: (passName: string, uniform: string, textureHandle: number) => void
+postprocess_setPresentRequired: ((required: boolean) => void) | undefined
postprocess_setScreenUniformFloat: (passName: string, uniform: string, value: number) => void
postprocess_setScreenUniformVec4: (passName: string, uniform: string, x: number, y: number, z: number, w: number) => void
postprocess_setUniformFloat: (passName: string, uniform: string, value: number) => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 0ed182efb..46297af9c 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -5818,6 +5818,7 @@ screenStack: PostProcessStack | null
setBypass: (bypass: boolean) => void
setOutputTransform: (transform: OutputTransform) => void
setOutputViewport: (x: number, y: number, w: number, h: number) => void
+setPresentRequired: (required: boolean) => void
setScreenStack: (stack: PostProcessStack | null) => void
shutdown: () => void
state: PostProcessState
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index 2708bf720..c0f7262e2 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -96,6 +96,7 @@ export interface NativeEngineApi {
postprocess_setOutputTransform?(transform: number): void;
postprocess_setOutputViewport?(x: number, y: number, w: number, h: number): void;
postprocess_setPassTexture?(passName: string, uniform: string, textureHandle: number): void;
+ postprocess_setPresentRequired?(required: boolean): void;
postprocess_setScreenUniformFloat?(passName: string, uniform: string, value: number): void;
postprocess_setScreenUniformVec4?(passName: string, uniform: string, x: number, y: number, z: number, w: number): void;
postprocess_setUniformFloat?(passName: string, uniform: string, value: number): void;
@@ -322,6 +323,7 @@ export function createNativeEngineApi(
bind('postprocess_setOutputTransform', 'es_postprocess_setOutputTransform', false);
bind('postprocess_setOutputViewport', 'es_postprocess_setOutputViewport', false);
bind('postprocess_setPassTexture', 'es_postprocess_setPassTexture', false);
+ bind('postprocess_setPresentRequired', 'es_postprocess_setPresentRequired', false);
bind('postprocess_setScreenUniformFloat', 'es_postprocess_setScreenUniformFloat', false);
bind('postprocess_setScreenUniformVec4', 'es_postprocess_setScreenUniformVec4', false);
bind('postprocess_setUniformFloat', 'es_postprocess_setUniformFloat', false);
diff --git a/sdk/src/postprocess/PostProcessAPI.ts b/sdk/src/postprocess/PostProcessAPI.ts
index 12fa4e079..1320938dc 100644
--- a/sdk/src/postprocess/PostProcessAPI.ts
+++ b/sdk/src/postprocess/PostProcessAPI.ts
@@ -18,7 +18,7 @@ type PostProcessCore = Required<Pick<NonNullable<EngineApi>,
| 'postprocess_isInitialized' | 'postprocess_begin' | 'postprocess_end'
| 'postprocess_clearPasses' | 'postprocess_addPass' | 'postprocess_setPassTexture'
| 'postprocess_setUniformFloat' | 'postprocess_setUniformVec4'
- | 'postprocess_setBypass' | 'postprocess_setOutputTransform'
+ | 'postprocess_setBypass' | 'postprocess_setOutputTransform' | 'postprocess_setPresentRequired'
| 'postprocess_setOutputViewport'
| 'postprocess_beginScreenCapture' | 'postprocess_endScreenCapture'
| 'postprocess_executeScreenPasses' | 'postprocess_addScreenPass'
@@ -259,6 +259,16 @@ export class PostProcessAPI {
}
}
+ /** Say the frame needs a present when the rects alone cannot: a 1x letterbox
+ * and a split-screen viewport are the same geometry and differ only in intent. */
+ setPresentRequired(required: boolean): void {
+ try {
+ getModule().postprocess_setPresentRequired?.(required);
+ } catch (e) {
+ handleWasmError(e, 'PostProcess.setPresentRequired');
+ }
+ }
+
setOutputViewport(x: number, y: number, w: number, h: number): void {
try {
getModule().postprocess_setOutputViewport(x, y, w, h);
diff --git a/sdk/src/render/renderPipeline.ts b/sdk/src/render/renderPipeline.ts
index ea6b8c736..ac6cf8259 100644
--- a/sdk/src/render/renderPipeline.ts
+++ b/sdk/src/render/renderPipeline.ts
@@ -179,6 +179,9 @@ export class RenderPipeline {
if (hasStack) pp!._applyForCamera(cameraEntity!);
pp!.resize(scene.w, scene.h);
pp!.setOutputViewport(present.x, present.y, present.w, present.h);
+ // A letterbox at 1x is the same size as its chain and merely offset, so
+ // the engine cannot read the need for it off the rects.
+ pp!.setPresentRequired(!plan.oneToOne);
pp!.begin();
}
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index d7c94ce2b..02d3379d0 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -388,6 +388,8 @@ export interface ESEngineModule {
postprocess_setOutputTransform?(transform: number): void;
postprocess_clearPasses(): void;
postprocess_setOutputViewport(x: number, y: number, w: number, h: number): void;
+ /** Say a present is needed when the rects cannot: see PostProcessPipeline. */
+ postprocess_setPresentRequired?(required: boolean): void;
postprocess_beginScreenCapture(): void;
postprocess_endScreenCapture(): void;
postprocess_executeScreenPasses(): void;
diff --git a/sdk/tests/render-present.test.ts b/sdk/tests/render-present.test.ts
index 930f3ca28..610d98f2f 100644
--- a/sdk/tests/render-present.test.ts
+++ b/sdk/tests/render-present.test.ts
@@ -30,6 +30,7 @@ function fakePostProcess(hasStack: boolean) {
init: vi.fn(),
resize: vi.fn(),
setOutputViewport: vi.fn(),
+ setPresentRequired: vi.fn(),
begin: vi.fn(),
end: vi.fn(),
_applyForCamera: vi.fn(),
@@ -82,6 +83,14 @@ describe('renderCamera — the render size and the present rect', () => {
expect(pp._resetAfterCamera).not.toHaveBeenCalled();
});
+ it('SAYS a present is needed, because the rects alone cannot', () => {
+ // A 1x letterbox is the same size as its chain and merely offset, which is
+ // also what a split-screen viewport looks like. The engine cannot infer the
+ // difference, so the decision is stated.
+ expect(run(RenderResolution.Design, false).setPresentRequired)
+ .toHaveBeenCalledWith(true);
+ });
+
it('brings the pipeline up itself — with no stack nothing else ever would', () => {
// Only a stack initialises it, and an uninitialised pipeline reports
// itself disengaged. Without this the policy goes quietly missing on
diff --git a/sdk/tests/renderPipeline.test.ts b/sdk/tests/renderPipeline.test.ts
index 8bbe247b9..d17424ebf 100644
--- a/sdk/tests/renderPipeline.test.ts
+++ b/sdk/tests/renderPipeline.test.ts
@@ -30,6 +30,7 @@ vi.mock('../src/postprocess', () => ({
resize: vi.fn(),
setBypass: vi.fn(),
setOutputViewport: vi.fn(),
+ setPresentRequired: vi.fn(),
_applyForCamera: vi.fn(),
_resetAfterCamera: vi.fn(),
begin: vi.fn(),
diff --git a/src/esengine/bindings/PostProcessBindings.cpp b/src/esengine/bindings/PostProcessBindings.cpp
index 40b0829c4..f7028ad62 100644
--- a/src/esengine/bindings/PostProcessBindings.cpp
+++ b/src/esengine/bindings/PostProcessBindings.cpp
@@ -139,6 +139,12 @@ void postprocess_setOutputViewport(u32 x, u32 y, u32 w, u32 h) {
}
}
+void postprocess_setPresentRequired(bool required) {
+ if (g_postProcessPipeline) {
+ g_postProcessPipeline->setPresentRequired(required);
+ }
+}
+
void postprocess_beginScreenCapture() {
if (!g_postProcessPipeline) return;
g_postProcessPipeline->beginScreenCapture();
diff --git a/src/esengine/bindings/PostProcessBindings.hpp b/src/esengine/bindings/PostProcessBindings.hpp
index 12bf27075..7cf087a7d 100644
--- a/src/esengine/bindings/PostProcessBindings.hpp
+++ b/src/esengine/bindings/PostProcessBindings.hpp
@@ -27,6 +27,9 @@ void postprocess_setBypass(bool bypass);
void postprocess_setOutputTransform(u32 transform);
void postprocess_clearPasses();
void postprocess_setOutputViewport(u32 x, u32 y, u32 w, u32 h);
+/** Say the frame needs a present even when the two rects look alike; see
+ * PostProcessPipeline::setPresentRequired. */
+void postprocess_setPresentRequired(bool required);
void postprocess_beginScreenCapture();
void postprocess_endScreenCapture();
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index f90bcb2b8..63aaac264 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -573,6 +573,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("postprocess_setOutputTransform", &esengine::postprocess_setOutputTransform);
emscripten::function("postprocess_clearPasses", &esengine::postprocess_clearPasses);
emscripten::function("postprocess_setOutputViewport", &esengine::postprocess_setOutputViewport);
+ emscripten::function("postprocess_setPresentRequired", &esengine::postprocess_setPresentRequired);
emscripten::function("postprocess_beginScreenCapture", &esengine::postprocess_beginScreenCapture);
emscripten::function("postprocess_endScreenCapture", &esengine::postprocess_endScreenCapture);
emscripten::function("postprocess_executeScreenPasses", &esengine::postprocess_executeScreenPasses);
diff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cpp
index bcabfc255..b0bf5cfb6 100644
--- a/src/esengine/renderer/frame/PostProcessPipeline.cpp
+++ b/src/esengine/renderer/frame/PostProcessPipeline.cpp
@@ -397,6 +397,9 @@ void PostProcessPipeline::chainDone() {
device_.invalidatePipelineCache();
inFrame_ = false;
output_target_fbo_ = FramebufferHandle::Default;
+ // Per-frame, like the target above: a camera that asked for a present must not
+ // leave the next one engaged for a frame it never asked about.
+ present_required_ = false;
}
void PostProcessPipeline::renderPass(PostProcessPass& pass, const rg::PassContext& ctx) {
diff --git a/src/esengine/renderer/frame/PostProcessPipeline.hpp b/src/esengine/renderer/frame/PostProcessPipeline.hpp
index 12ca16652..3a9adcdac 100644
--- a/src/esengine/renderer/frame/PostProcessPipeline.hpp
+++ b/src/esengine/renderer/frame/PostProcessPipeline.hpp
@@ -201,7 +201,7 @@ public:
// to drawing straight at the surface rather than to a black frame.
return initialized_ && ((!bypass_ && !passes_.empty()) || linear_output_
|| output_transform_ != OutputTransform::None
- || presentScales());
+ || presentScales() || present_required_);
}
/**
@@ -217,9 +217,15 @@ public:
&& (output_vp_w_ != width_ || output_vp_h_ != height_);
}
- // KNOWN GAP: a 1x letterbox is same-size-but-OFFSET, indistinguishable here
- // from a split-screen viewport — engaging on offset alone would put a blit
- // under every split-screen camera. Closing it needs the surface size.
+ /**
+ * @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.
+ */
+ void setPresentRequired(bool required) { present_required_ = required; }
/**
* @brief Whether the present is a whole-multiple upscale of the chain.
@@ -397,6 +403,7 @@ private:
FramebufferHandle output_target_fbo_ = FramebufferHandle::Default;
u32 output_vp_x_ = 0;
u32 output_vp_y_ = 0;
+ bool present_required_ = false;
u32 output_vp_w_ = 0;
u32 output_vp_h_ = 0;