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(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.tsnew file mode 100644index 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.tsnew file mode 100644index 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);+ });+});