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(camera): where the scene is rendered and where it lands become two numbers

yhh7dbc14df4edf
diff --git a/sdk/src/camera/presentPlan.ts b/sdk/src/camera/presentPlan.ts
new file mode 100644
index 000000000..5094a33e6
--- /dev/null
+++ b/sdk/src/camera/presentPlan.ts
@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file presentPlan.ts
+ * @brief Where the scene is rendered, and where that image lands on the surface.
+ *
+ * A quad that scales itself can only clamp at its OWN texture's edge — the
+ * neighbouring sprite is a different texture — so every boundary breaks and N
+ * sprites give N candidate seams. Scaling one whole image has no interior
+ * boundary to break, which is why these are two numbers and not one.
+ *
+ * The invariant every policy but {@link RenderResolution.Surface} holds:
+ * `renderHeight === worldHeight`, so one world unit is one rendered pixel and
+ * every sprite samples 1:1.
+ *
+ * NO IMPORTS, no engine state: a build tool and a test read this the same way the
+ * render loop does.
+ */
+
+/** How the scene's own resolution is chosen. */
+export enum RenderResolution {
+ /**
+ * Render straight to the surface. Every sprite scales itself, so a
+ * non-integer texel-to-pixel ratio shows a seam at every sprite boundary.
+ * The behaviour every project had before this existed, and the default.
+ */
+ Surface = 0,
+ /**
+ * Render at the size the camera's world height asks for, then scale that
+ * image to fill the surface. One uniform resample, no seams; slightly soft
+ * at non-integer ratios.
+ */
+ Design = 1,
+ /**
+ * As {@link Design}, but the image is presented at a WHOLE multiple of its
+ * own size and unfiltered, so no resampling happens at all. Costs black bars
+ * wherever a whole multiple does not fill the surface.
+ */
+ IntegerMultiple = 2,
+}
+
+/** What the render loop needs: a target size, a destination rect, and a filter. */
+export interface PresentPlan {
+ /** Size of the offscreen target the scene is drawn into. */
+ renderWidth: number;
+ renderHeight: number;
+ /** Where that image lands on the surface, in surface pixels. */
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+ /** Whether the present may interpolate. False = a whole-pixel copy. */
+ linear: boolean;
+ /** True when render size equals the destination rect — the present is a no-op copy. */
+ oneToOne: boolean;
+}
+
+function clampDim(v: number): number {
+ return Math.max(1, Math.round(v));
+}
+
+/**
+ * Plan a frame's render target and its present rect.
+ *
+ * @param worldHeight World units the camera shows vertically — `2 *` the
+ * effective ortho size, AFTER the scale mode adapted it to the aspect.
+ * @param surfaceWidth Destination width in px: the camera's viewport, which is
+ * the window for a full-screen camera and a slice of it for split-screen.
+ */
+export function planPresent(
+ policy: RenderResolution,
+ worldHeight: number,
+ surfaceWidth: number,
+ surfaceHeight: number,
+): PresentPlan {
+ const sw = clampDim(surfaceWidth);
+ const sh = clampDim(surfaceHeight);
+
+ // A surface-sized render, and a world height nobody asked to match, are the
+ // same answer: draw where you present. Also the fallback for a nonsense
+ // world height, because a zero-tall render target is not a picture.
+ if (policy === RenderResolution.Surface || !(worldHeight > 0)) {
+ return { renderWidth: sw, renderHeight: sh, x: 0, y: 0, width: sw, height: sh, linear: true, oneToOne: true };
+ }
+
+ // The render target keeps the SURFACE's aspect, not the design resolution's:
+ // the scale mode has already decided how much world a wide window shows, and
+ // letterboxing here as well would crop what it just widened.
+ const renderHeight = clampDim(worldHeight);
+ const renderWidth = clampDim(renderHeight * (sw / sh));
+
+ if (policy === RenderResolution.IntegerMultiple) {
+ // The largest whole multiple that still fits. Below 1 there is none, and
+ // a downscale cannot be whole-pixel — so it falls back to filling, and
+ // says so through `linear` rather than pretending to be crisp.
+ const k = Math.floor(Math.min(sw / renderWidth, sh / renderHeight));
+ if (k >= 1) {
+ const w = renderWidth * k;
+ const h = renderHeight * k;
+ return {
+ renderWidth, renderHeight,
+ x: Math.floor((sw - w) / 2), y: Math.floor((sh - h) / 2),
+ width: w, height: h,
+ linear: false,
+ oneToOne: k === 1,
+ };
+ }
+ }
+
+ return {
+ renderWidth, renderHeight,
+ x: 0, y: 0, width: sw, height: sh,
+ linear: true,
+ oneToOne: renderWidth === sw && renderHeight === sh,
+ };
+}
+
+/**
+ * World units per rendered pixel under a plan — 1 exactly is what a seam-free
+ * frame needs, and what the render policies exist to produce.
+ */
+export function worldPerRenderedPixel(plan: PresentPlan, worldHeight: number): number {
+ return plan.renderHeight > 0 ? worldHeight / plan.renderHeight : 0;
+}
diff --git a/sdk/tests/present-plan.test.ts b/sdk/tests/present-plan.test.ts
new file mode 100644
index 000000000..5a303994a
--- /dev/null
+++ b/sdk/tests/present-plan.test.ts
@@ -0,0 +1,135 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file The present plan exists for ONE number: world units per rendered pixel.
+ * At exactly 1 a sprite samples its texture 1:1 and the clamp at its own
+ * edge never shows; at anything else every sprite boundary is a candidate
+ * seam. So the tests assert that number, and assert the surface policy
+ * FAILS it — a plan that could not tell the two apart would prove nothing.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+ planPresent, worldPerRenderedPixel, RenderResolution,
+} from '../src/camera/presentPlan';
+
+/** The surfaces a 1080-tall design actually meets: a panel, a window, a big screen. */
+const SURFACES: [number, number][] = [
+ [1244, 700], // editor play panel
+ [1600, 900], // a windowed export
+ [1920, 1080], // the design resolution itself
+ [2560, 1440], // a bigger screen
+ [1366, 768], // a laptop
+];
+
+describe('planPresent — the invariant', () => {
+ it('Design makes one world unit exactly one rendered pixel, on every surface', () => {
+ for (const [w, h] of SURFACES) {
+ const plan = planPresent(RenderResolution.Design, 1080, w, h);
+ expect(worldPerRenderedPixel(plan, 1080)).toBe(1);
+ }
+ });
+
+ it('IntegerMultiple holds it too — a whole multiple does not change the render size', () => {
+ for (const [w, h] of SURFACES) {
+ const plan = planPresent(RenderResolution.IntegerMultiple, 1080, w, h);
+ expect(worldPerRenderedPixel(plan, 1080)).toBe(1);
+ }
+ });
+
+ it('...and Surface does NOT, which is the bug these policies exist for', () => {
+ // Same measurement, same inputs. If it passed here the assertion above
+ // would be measuring nothing.
+ const off = SURFACES.filter(([, h]) => h !== 1080);
+ expect(off.length).toBeGreaterThan(0);
+ for (const [w, h] of off) {
+ const plan = planPresent(RenderResolution.Surface, 1080, w, h);
+ expect(worldPerRenderedPixel(plan, 1080)).not.toBe(1);
+ }
+ });
+
+ it('the ratio the old path was stuck with is the one measured off the report', () => {
+ // 1080 design shown in a ~700px panel: 1.54 world units per pixel, which
+ // is where the reported seams came from.
+ const plan = planPresent(RenderResolution.Surface, 1080, 1244, 700);
+ expect(worldPerRenderedPixel(plan, 1080)).toBeCloseTo(1.543, 3);
+ });
+});
+
+describe('planPresent — the render target', () => {
+ it('keeps the SURFACE aspect, so a wide window is not cropped', () => {
+ // The scale mode already widened the camera for a wide surface; taking the
+ // design aspect here would crop exactly what it just added.
+ const plan = planPresent(RenderResolution.Design, 1080, 2560, 1080);
+ expect(plan.renderHeight).toBe(1080);
+ expect(plan.renderWidth).toBe(2560);
+ });
+
+ it('follows the world height, not the design height — every scale mode is served', () => {
+ // FixedWidth mode hands a different world height per aspect. The plan must
+ // track it, or worldPerPixel is 1 only in FixedHeight.
+ const plan = planPresent(RenderResolution.Design, 1350, 1600, 900);
+ expect(plan.renderHeight).toBe(1350);
+ expect(worldPerRenderedPixel(plan, 1350)).toBe(1);
+ });
+
+ it('never returns a zero-sized target', () => {
+ for (const [w, h] of [[0, 0], [1, 1], [-5, 3]] as [number, number][]) {
+ const plan = planPresent(RenderResolution.Design, 1080, w, h);
+ expect(plan.renderWidth).toBeGreaterThan(0);
+ expect(plan.renderHeight).toBeGreaterThan(0);
+ expect(plan.width).toBeGreaterThan(0);
+ expect(plan.height).toBeGreaterThan(0);
+ }
+ });
+
+ it('falls back to the surface when the world height is nonsense', () => {
+ for (const bad of [0, -1, NaN]) {
+ const plan = planPresent(RenderResolution.Design, bad, 800, 600);
+ expect(plan).toMatchObject({ renderWidth: 800, renderHeight: 600, oneToOne: true });
+ }
+ });
+});
+
+describe('planPresent — IntegerMultiple', () => {
+ it('presents at a whole multiple, unfiltered, centred', () => {
+ // 540 world units tall into a 1080-tall surface: exactly 2x.
+ const plan = planPresent(RenderResolution.IntegerMultiple, 540, 1920, 1080);
+ expect(plan.renderHeight).toBe(540);
+ expect(plan.renderWidth).toBe(960);
+ expect(plan.height).toBe(1080);
+ expect(plan.width).toBe(1920);
+ expect(plan.linear).toBe(false);
+ expect(plan.x).toBe(0);
+ expect(plan.y).toBe(0);
+ });
+
+ it('letterboxes what a whole multiple cannot fill, and centres the bars', () => {
+ // 540 into 900: 1x fits, 2x does not. 360px of bar, 180 top and bottom.
+ const plan = planPresent(RenderResolution.IntegerMultiple, 540, 1600, 900);
+ expect(plan.renderHeight).toBe(540);
+ expect(plan.height).toBe(540);
+ expect(plan.y).toBe(180);
+ expect(plan.x).toBe((1600 - plan.width) / 2);
+ expect(plan.linear).toBe(false);
+ });
+
+ it('the whole-multiple rect is exactly k times the render size, both axes', () => {
+ // The property, not one arithmetic case: a non-integer ratio anywhere is a
+ // resample, which is the thing this policy promises never to do.
+ for (const [w, h] of SURFACES) {
+ const plan = planPresent(RenderResolution.IntegerMultiple, 360, w, h);
+ if (!plan.linear) {
+ expect(plan.width / plan.renderWidth).toBe(plan.height / plan.renderHeight);
+ expect(Number.isInteger(plan.width / plan.renderWidth)).toBe(true);
+ }
+ }
+ });
+
+ it('says linear rather than pretending, when it must shrink', () => {
+ // A render taller than the surface has no whole multiple. Claiming crisp
+ // here would be the promise `pixelPerfect` already makes and cannot keep.
+ const plan = planPresent(RenderResolution.IntegerMultiple, 2160, 1244, 700);
+ expect(plan.linear).toBe(true);
+ expect(worldPerRenderedPixel(plan, 2160)).toBe(1);
+ });
+});