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 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.cpp
index 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.hpp
index 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_);
}
/**