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
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.mdindex a930f53d0..2d147257f 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -5816,6 +5816,7 @@ screenStack: PostProcessStack | nullsetBypass: (bypass: boolean) => voidsetOutputTransform: (transform: OutputTransform) => voidsetOutputViewport: (x: number, y: number, w: number, h: number) => void+setPresentRequired: (required: boolean) => voidsetScreenStack: (stack: PostProcessStack | null) => voidshutdown: () => voidstate: PostProcessStatediff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex bca2ae7f8..f5f898af8 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -5999,6 +5999,7 @@ screenStack: PostProcessStack | nullsetBypass: (bypass: boolean) => voidsetOutputTransform: (transform: OutputTransform) => voidsetOutputViewport: (x: number, y: number, w: number, h: number) => void+setPresentRequired: (required: boolean) => voidsetScreenStack: (stack: PostProcessStack | null) => voidshutdown: () => voidstate: PostProcessStatediff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex c939987c6..e2fa112ab 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -5811,6 +5811,7 @@ screenStack: PostProcessStack | nullsetBypass: (bypass: boolean) => voidsetOutputTransform: (transform: OutputTransform) => voidsetOutputViewport: (x: number, y: number, w: number, h: number) => void+setPresentRequired: (required: boolean) => voidsetScreenStack: (stack: PostProcessStack | null) => voidshutdown: () => voidstate: PostProcessStatediff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex f66da3c31..cfdd88551 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -6056,6 +6056,7 @@ screenStack: PostProcessStack | nullsetBypass: (bypass: boolean) => voidsetOutputTransform: (transform: OutputTransform) => voidsetOutputViewport: (x: number, y: number, w: number, h: number) => void+setPresentRequired: (required: boolean) => voidsetScreenStack: (stack: PostProcessStack | null) => voidshutdown: () => voidstate: PostProcessStatediff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 44b796334..0be1d3c1c 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -326,6 +326,7 @@ postprocess_setBypass: (bypass: boolean) => voidpostprocess_setOutputTransform: ((transform: number) => void) | undefinedpostprocess_setOutputViewport: (x: number, y: number, w: number, h: number) => voidpostprocess_setPassTexture: (passName: string, uniform: string, textureHandle: number) => void+postprocess_setPresentRequired: ((required: boolean) => void) | undefinedpostprocess_setScreenUniformFloat: (passName: string, uniform: string, value: number) => voidpostprocess_setScreenUniformVec4: (passName: string, uniform: string, x: number, y: number, z: number, w: number) => voidpostprocess_setUniformFloat: (passName: string, uniform: string, value: number) => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 0ed182efb..46297af9c 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -5818,6 +5818,7 @@ screenStack: PostProcessStack | nullsetBypass: (bypass: boolean) => voidsetOutputTransform: (transform: OutputTransform) => voidsetOutputViewport: (x: number, y: number, w: number, h: number) => void+setPresentRequired: (required: boolean) => voidsetScreenStack: (stack: PostProcessStack | null) => voidshutdown: () => voidstate: PostProcessStatediff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 ondiff --git a/sdk/tests/renderPipeline.test.ts b/sdk/tests/renderPipeline.test.tsindex 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.cppindex 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.hppindex 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.cppindex 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.cppindex 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.hppindex 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;