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 scene's own resolution and the rect it lands in come apart
yhh76816be413ea
diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.tsindex 94584696e..47e0d8d5e 100644--- a/sdk/src/camera/CameraPlugin.ts+++ b/sdk/src/camera/CameraPlugin.ts@@ -700,6 +700,12 @@ export function cameraPlugin(} else {pipeline.beginFrame(elapsed);pipeline.beginScreenCapture();+ // One project-level choice, read once: a per-camera answer+ // would let two cameras present the same surface at two+ // resolutions, which is a picture nobody asked for.+ const renderPolicy = app.hasResource(ScreenScaling)+ ? app.getResource(ScreenScaling).renderPolicy+ : undefined;for (const cam of cameras) {const vp = cam.viewportRect;// A camera drawing into a texture is measured against@@ -725,6 +731,10 @@ export function cameraPlugin(// A released target leaves the handle behind; drawing// to it would draw nowhere, so it falls to the screen.renderTarget: target ? cam.renderTarget : 0,+ // The world the camera shows vertically is what the+ // render size matches, so worldPerPixel lands on 1.+ worldHeight: 2 * cam.halfH,+ renderPolicy,});}pipeline.endScreenCapture();diff --git a/sdk/src/camera/ScreenScaling.ts b/sdk/src/camera/ScreenScaling.tsindex 1e600508e..25b2ad4c5 100644--- a/sdk/src/camera/ScreenScaling.ts+++ b/sdk/src/camera/ScreenScaling.ts@@ -22,6 +22,7 @@* the project config (design resolution + fit). Read by CameraPlugin.resolveCameras.*/import { defineResource } from '../ecs/resource';+import { RenderResolution } from './presentPlan';/** `scaleMode` sentinel: no camera fit — the camera uses its own orthoSize (default). */export const SCREEN_FIT_OFF = -1;@@ -35,6 +36,13 @@ export interface ScreenScalingData {scaleMode: number;/** Match-mode blend 0..1 (0 = fit width, 1 = fit height); ignored for other modes. */matchWidthOrHeight: number;+ /**+ * Whether the scene renders at its own resolution and is then scaled to the+ * surface, or straight to the surface. See {@link RenderResolution}. Optional+ * because a project file written before it existed must still read; absent+ * means `Surface`, which is the behaviour every project already had.+ */+ renderPolicy?: RenderResolution;}/** Off by default (scaleMode = -1) ⇒ zero behavior change for a project that never@@ -44,6 +52,7 @@ export const DEFAULT_SCREEN_SCALING: ScreenScalingData = {designHeight: 1080,scaleMode: SCREEN_FIT_OFF,matchWidthOrHeight: 0.5,+ renderPolicy: RenderResolution.Surface,};export const ScreenScaling = defineResource<ScreenScalingData>({ ...DEFAULT_SCREEN_SCALING }, 'ScreenScaling');diff --git a/sdk/src/render/renderPipeline.ts b/sdk/src/render/renderPipeline.tsindex 855fec86a..31232e484 100644--- a/sdk/src/render/renderPipeline.ts+++ b/sdk/src/render/renderPipeline.ts@@ -17,6 +17,7 @@ import {unregisterPreSceneDrawCallback,} from './customDraw';import { log } from '../util/logger';+import { planPresent, RenderResolution } from '../camera/presentPlan';export interface Viewport {x: number;@@ -48,6 +49,10 @@ export interface CameraRenderParams {cullingMask?: number;/** Offscreen target to draw into; 0 (default) is the screen. */renderTarget?: number;+ /** World units the camera shows vertically (`2 * halfH`); drives the render size. */+ worldHeight?: number;+ /** How the render resolution is chosen; omitted = render straight to the surface. */+ renderPolicy?: RenderResolution;}export class RenderPipeline {@@ -147,28 +152,44 @@ export class RenderPipeline {renderCamera(params: CameraRenderParams): void {const { registry, viewProjection, viewportPixels: vp, clearFlags, elapsed, cameraEntity } = params;+ // Where the scene is drawn and where it lands are two rects. A sprite that+ // scales itself can only clamp at its own texture's edge, so every boundary+ // breaks; scaling one whole image has no interior boundary to break.+ const plan = planPresent(+ params.renderPolicy ?? RenderResolution.Surface,+ params.worldHeight ?? 0, vp.w, vp.h);+ const scene: Viewport = plan.oneToOne+ ? vp+ : { x: 0, y: 0, w: plan.renderWidth, h: plan.renderHeight };+ const present: Viewport = plan.oneToOne+ ? vp+ : { x: vp.x + plan.x, y: vp.y + plan.y, w: plan.width, h: plan.height };+const pp = this.postProcess_;- const hasPostProcess = pp !== null && cameraEntity !== undefined && pp.getStack(cameraEntity) !== null;+ const hasStack = pp !== null && cameraEntity !== undefined && pp.getStack(cameraEntity) !== null;+ // A scaling present needs the chain even with no effects on it: the blit+ // that ends the chain IS the present, and nothing else can draw one.+ const hasPostProcess = pp !== null && (hasStack || !plan.oneToOne);if (hasPostProcess) {- pp!._applyForCamera(cameraEntity!);- pp!.resize(vp.w, vp.h);- pp!.setOutputViewport(vp.x, vp.y, vp.w, vp.h);+ if (hasStack) pp!._applyForCamera(cameraEntity!);+ pp!.resize(scene.w, scene.h);+ pp!.setOutputViewport(present.x, present.y, present.w, present.h);pp!.begin();}- Renderer.setViewport(vp.x, vp.y, vp.w, vp.h);+ Renderer.setViewport(scene.x, scene.y, scene.w, scene.h);// The camera's clear rides begin as a region-scoped load-op — no scissor// dance, no sticky clear state at the boundary.- Renderer.begin(viewProjection, params.renderTarget ?? 0, clearFlags, params.clearColor, vp);+ Renderer.begin(viewProjection, params.renderTarget ?? 0, clearFlags, params.clearColor, scene);// Set after begin (which clears the draw list) and before the collect it gates.Renderer.setCullingMask(params.cullingMask ?? 0xFFFFFFFF);- this.submitScene(registry, viewProjection, vp, elapsed);+ this.submitScene(registry, viewProjection, scene, elapsed);Renderer.end();if (hasPostProcess) {pp!.end();- pp!._resetAfterCamera();+ if (hasStack) pp!._resetAfterCamera();}}diff --git a/sdk/tests/render-present.test.ts b/sdk/tests/render-present.test.tsnew file mode 100644index 000000000..84e464c9b--- /dev/null+++ b/sdk/tests/render-present.test.ts@@ -0,0 +1,139 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file The whole render-policy change is one thing: the size the scene is+ * drawn at and the rect it lands in stop being the same numbers. So the+ * test asserts exactly that, on the two calls that carry them, and+ * asserts they still AGREE under the default policy — a test that only+ * ran the default would be measuring an inert change.+ */+import { describe, it, expect, beforeEach, vi } from 'vitest';++vi.mock('../src/render/renderer', () => ({+ Renderer: {+ init: vi.fn(), resize: vi.fn(), begin: vi.fn(), flush: vi.fn(), end: vi.fn(),+ submitAll: vi.fn(), setStage: vi.fn(), setClearColor: vi.fn(),+ setViewport: vi.fn(), setCullingMask: vi.fn(), updateTransforms: vi.fn(),+ beginFrame: vi.fn(),+ },+}));++import { Renderer } from '../src/render/renderer';+import { RenderPipeline } from '../src/render/renderPipeline';+import { RenderResolution } from '../src/camera/presentPlan';++/** Only the four calls this change touches; everything else a no-op. */+function fakePostProcess(hasStack: boolean) {+ return {+ getStack: vi.fn().mockReturnValue(hasStack ? {} : null),+ resize: vi.fn(),+ setOutputViewport: vi.fn(),+ begin: vi.fn(),+ end: vi.fn(),+ _applyForCamera: vi.fn(),+ _resetAfterCamera: vi.fn(),+ };+}++const VP = { x: 0, y: 0, w: 1244, h: 700 }; // an editor play panel+const DESIGN_WORLD_HEIGHT = 1080;++function run(policy: RenderResolution | undefined, hasStack: boolean) {+ const pp = fakePostProcess(hasStack);+ const pipeline = new RenderPipeline();+ pipeline.setPostProcess(pp as never);+ pipeline.renderCamera({+ registry: { _cpp: {} as never },+ viewProjection: new Float32Array(16),+ viewportPixels: VP,+ clearFlags: 3,+ elapsed: 0,+ cameraEntity: 1 as never,+ worldHeight: DESIGN_WORLD_HEIGHT,+ renderPolicy: policy,+ });+ return pp;+}++beforeEach(() => vi.clearAllMocks());++describe('renderCamera — the render size and the present rect', () => {+ it('THE CHANGE: under a render policy the two calls carry different numbers', () => {+ const pp = run(RenderResolution.Design, /*hasStack=*/false);++ // Drawn at the world height, so one world unit is one rendered pixel.+ expect(pp.resize).toHaveBeenCalledWith(expect.any(Number), DESIGN_WORLD_HEIGHT);+ // Landed on the whole panel, which is a different height entirely.+ expect(pp.setOutputViewport).toHaveBeenCalledWith(0, 0, VP.w, VP.h);++ const [, renderH] = pp.resize.mock.calls[0]!;+ const [, , , presentH] = pp.setOutputViewport.mock.calls[0]!;+ expect(renderH).not.toBe(presentH);+ });++ it('engages the chain with no effects on it — the blit that ends it IS the present', () => {+ const pp = run(RenderResolution.Design, /*hasStack=*/false);+ expect(pp.begin).toHaveBeenCalled();+ expect(pp.end).toHaveBeenCalled();+ // No stack means no per-camera effect state to apply or unwind.+ expect(pp._applyForCamera).not.toHaveBeenCalled();+ expect(pp._resetAfterCamera).not.toHaveBeenCalled();+ });++ it('draws the scene into the whole render target, not the panel rect', () => {+ run(RenderResolution.Design, false);+ expect(Renderer.setViewport).toHaveBeenCalledWith(0, 0, expect.any(Number), DESIGN_WORLD_HEIGHT);+ });++ it('...and the default policy leaves both calls agreeing, as they always did', () => {+ // The same measurement on the untouched path. Without it, the assertions+ // above could pass on a pipeline that scaled everything unconditionally.+ const pp = run(undefined, /*hasStack=*/true);+ expect(pp.resize).toHaveBeenCalledWith(VP.w, VP.h);+ expect(pp.setOutputViewport).toHaveBeenCalledWith(VP.x, VP.y, VP.w, VP.h);+ expect(Renderer.setViewport).toHaveBeenCalledWith(VP.x, VP.y, VP.w, VP.h);+ });++ it('...and with no policy and no stack the chain stays out of the frame entirely', () => {+ const pp = run(undefined, /*hasStack=*/false);+ expect(pp.begin).not.toHaveBeenCalled();+ expect(pp.resize).not.toHaveBeenCalled();+ });++ it('a camera whose viewport already matches the world height does not scale', () => {+ // Nothing to gain and a blit to pay for. `oneToOne` is what spares it.+ const pp = fakePostProcess(false);+ const pipeline = new RenderPipeline();+ pipeline.setPostProcess(pp as never);+ pipeline.renderCamera({+ registry: { _cpp: {} as never },+ viewProjection: new Float32Array(16),+ viewportPixels: { x: 0, y: 0, w: 1920, h: 1080 },+ clearFlags: 3,+ elapsed: 0,+ cameraEntity: 1 as never,+ worldHeight: 1080,+ renderPolicy: RenderResolution.Design,+ });+ expect(pp.begin).not.toHaveBeenCalled();+ });++ it('offsets the present rect by the camera viewport, so split-screen still lands right', () => {+ const pp = fakePostProcess(false);+ const pipeline = new RenderPipeline();+ pipeline.setPostProcess(pp as never);+ pipeline.renderCamera({+ registry: { _cpp: {} as never },+ viewProjection: new Float32Array(16),+ viewportPixels: { x: 960, y: 0, w: 960, h: 700 },+ clearFlags: 3,+ elapsed: 0,+ cameraEntity: 1 as never,+ worldHeight: 1080,+ renderPolicy: RenderResolution.Design,+ });+ const [x, , w] = pp.setOutputViewport.mock.calls[0]!;+ expect(x).toBe(960);+ expect(w).toBe(960);+ });+});diff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cppindex f1b21605e..a69f461de 100644--- a/src/esengine/renderer/frame/PostProcessPipeline.cpp+++ b/src/esengine/renderer/frame/PostProcessPipeline.cpp@@ -524,7 +524,12 @@ void PostProcessPipeline::blitPass() {void PostProcessPipeline::runChain(std::vector<PostProcessPass>& passes, rg::ResourceId scene) {if (!graph_ || scene == rg::kNoResource) return;- const rg::ResourceId out = graph_->importTarget(output_target_fbo_, width_, height_);+ // The surface has to be declared big enough to hold the rect the blit writes,+ // which is NOT the chain's size once the present scales. Only the extent+ // matters: blitPass sets its own viewport, so the graph's default never runs.+ const u32 outW = std::max(width_, output_vp_x_ + output_vp_w_);+ const u32 outH = std::max(height_, output_vp_y_ + output_vp_h_);+ const rg::ResourceId out = graph_->importTarget(output_target_fbo_, outW, outH);const rg::TargetDesc desc = chainTarget(/*withDepth=*/false);rg::ResourceId input = scene;diff --git a/src/esengine/renderer/frame/PostProcessPipeline.hpp b/src/esengine/renderer/frame/PostProcessPipeline.hppindex e5c5314ba..6cd3ad564 100644--- a/src/esengine/renderer/frame/PostProcessPipeline.hpp+++ b/src/esengine/renderer/frame/PostProcessPipeline.hpp@@ -188,15 +188,30 @@ public:/*** @brief Whether the scene goes through the graph or straight to the surface.*- * @details Three things engage it: effects to run, the linear pipeline (whose+ * @details Four things engage it: effects to run, the linear pipeline (whose* final pass carries an encode a WebGL2 canvas framebuffer cannot do- * for itself), or an output transform. One predicate because everyone- * asks at both ends of a frame, and two copies of it is one edit away- * from a capture that is opened and never resolved.+ * for itself), an output transform, or a present that scales. One+ * predicate because everyone asks at both ends of a frame, and two+ * copies of it is one edit away from a capture that is opened and+ * never resolved.*/bool isEngaged() const {return initialized_ && ((!bypass_ && !passes_.empty()) || linear_output_- || output_transform_ != OutputTransform::None);+ || output_transform_ != OutputTransform::None+ || presentScales());+ }++ /**+ * @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_);}/**