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): the camera a frame was drawn with is a value anyone can hold

yhh433713758c33
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index c56ac19dd..adace87e3 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -2,11 +2,11 @@
"note": "Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.",
"counts": {
"public": 113,
- "beta": 91,
+ "beta": 96,
"experimental": 1824,
"deprecated": 3
},
- "total": 2028,
+ "total": 2033,
"subsystems": [
{
"id": "ecs",
@@ -1825,6 +1825,30 @@
"minigame"
]
},
+ {
+ "name": "CameraCommit",
+ "kind": "const",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "CameraCommitData",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "CameraData",
"kind": "interface",
@@ -1849,6 +1873,18 @@
"minigame"
]
},
+ {
+ "name": "CameraLens",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "CameraTransformFields",
"kind": "interface",
@@ -2234,6 +2270,18 @@
"minigame"
]
},
+ {
+ "name": "PresentedCameraView",
+ "kind": "const",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "ProjectionType",
"kind": "enum",
@@ -2763,6 +2811,18 @@
"index.node"
]
},
+ {
+ "name": "presentedCameraView",
+ "kind": "const",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "removeNode",
"kind": "function",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index f76ccda28..3a6e8ad3a 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 84 beta · 1663 experimental · 3 deprecated
+Symbols: 113 public · 89 beta · 1663 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -1694,6 +1694,22 @@ minX: number
minY: number
```
+## CameraCommit — const @beta
+```
+ResourceDef<CameraCommitData>
+```
+
+## CameraCommitData — interface @beta
+```
+revision: number
+valid: boolean
+viewProjection: Float32Array<ArrayBufferLike>
+vpH: number
+vpW: number
+vpX: number
+vpY: number
+```
+
## CameraData — interface @beta
```
aspectRatio: number
@@ -1759,6 +1775,15 @@ renderTarget: number | undefined
viewport: { x: number; y: number; z: number; w: number; }
```
+## CameraLens — interface @beta
+```
+viewProjection: Float32Array<ArrayBufferLike>
+vpH: number
+vpW: number
+vpX: number
+vpY: number
+```
+
## CameraPOV — interface @experimental
```
clearFlags: number
@@ -1817,7 +1842,7 @@ projectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | null
screenRay: (screenX: number, screenY: number) => WorldRay | null
screenToWorld: (screenX: number, screenY: number, planeZ?: number) => { x: number; y: number; } | null
worldToScreen: (worldX: number, worldY: number, worldZ?: number) => { x: number; y: number; } | null
-static new (app_: App): CameraViewAPI
+static new (app_: App, lens_?: (app: App) => CameraLens | null): CameraViewAPI
static prototype: CameraViewAPI
```
@@ -2545,7 +2570,7 @@ ScreenScalingData
## DEFAULT_UI_CAMERA_INFO — const @experimental
```
-{ readonly viewProjection: Float32Array<ArrayBuffer>; readonly vpX: 0; readonly vpY: 0; readonly vpW: 0; readonly vpH: 0; readonly screenW: 0; readonly screenH: 0; readonly worldLeft: 0; readonly worldBottom: 0; readonly worldRight: 0; readonly worldTop: 0; readonly worldMouseX: 0; readonly worldMouseY: 0; readonly valid: false; }
+{ readonly viewProjection: Float32Array<ArrayBuffer>; readonly vpX: 0; readonly vpY: 0; readonly vpW: 0; readonly vpH: 0; readonly screenW: 0; readonly screenH: 0; readonly worldLeft: 0; readonly worldBottom: 0; readonly worldRight: 0; readonly worldTop: 0; readonly worldMouseX: 0; readonly worldMouseY: 0; readonly valid: false; readonly revision: 0; }
```
## DODGE_KEY — const @experimental
@@ -6553,6 +6578,11 @@ generation: number | undefined
query: (view: InterestProviderQueryView) => ReadonlySet<Entity> | "all"
```
+## PresentedCameraView — const @beta
+```
+ResourceDef<CameraViewAPI>
+```
+
## ProbedRegistrations — interface @experimental
```
fingerprint: string
@@ -9512,6 +9542,7 @@ SizeY = 11
## UICameraData — interface @beta
```
+revision: number
screenH: number
screenW: number
valid: boolean
@@ -12618,6 +12649,11 @@ PrefabsPlugin
(prefab: PrefabData, loadPrefab: (path: string) => Promise<PrefabData>, cache: Map<string, PrefabData>, visited?: Set<string>, depth?: number): Promise<void>
```
+## presentedCameraView — const @beta
+```
+(app: App) => CameraViewAPI
+```
+
## probeRegistrations — function @experimental
```
(register: () => Promise<void>): Promise<ProbedRegistrations>
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index e17dcde49..940211fb3 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 89 beta · 1682 experimental · 3 deprecated
+Symbols: 113 public · 94 beta · 1682 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -1694,6 +1694,22 @@ minX: number
minY: number
```
+## CameraCommit — const @beta
+```
+ResourceDef<CameraCommitData>
+```
+
+## CameraCommitData — interface @beta
+```
+revision: number
+valid: boolean
+viewProjection: Float32Array<ArrayBufferLike>
+vpH: number
+vpW: number
+vpX: number
+vpY: number
+```
+
## CameraData — interface @beta
```
aspectRatio: number
@@ -1759,6 +1775,15 @@ renderTarget: number | undefined
viewport: { x: number; y: number; z: number; w: number; }
```
+## CameraLens — interface @beta
+```
+viewProjection: Float32Array<ArrayBufferLike>
+vpH: number
+vpW: number
+vpX: number
+vpY: number
+```
+
## CameraPOV — interface @experimental
```
clearFlags: number
@@ -1817,7 +1842,7 @@ projectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | null
screenRay: (screenX: number, screenY: number) => WorldRay | null
screenToWorld: (screenX: number, screenY: number, planeZ?: number) => { x: number; y: number; } | null
worldToScreen: (worldX: number, worldY: number, worldZ?: number) => { x: number; y: number; } | null
-static new (app_: App): CameraViewAPI
+static new (app_: App, lens_?: (app: App) => CameraLens | null): CameraViewAPI
static prototype: CameraViewAPI
```
@@ -2553,7 +2578,7 @@ ScreenScalingData
## DEFAULT_UI_CAMERA_INFO — const @experimental
```
-{ readonly viewProjection: Float32Array<ArrayBuffer>; readonly vpX: 0; readonly vpY: 0; readonly vpW: 0; readonly vpH: 0; readonly screenW: 0; readonly screenH: 0; readonly worldLeft: 0; readonly worldBottom: 0; readonly worldRight: 0; readonly worldTop: 0; readonly worldMouseX: 0; readonly worldMouseY: 0; readonly valid: false; }
+{ readonly viewProjection: Float32Array<ArrayBuffer>; readonly vpX: 0; readonly vpY: 0; readonly vpW: 0; readonly vpH: 0; readonly screenW: 0; readonly screenH: 0; readonly worldLeft: 0; readonly worldBottom: 0; readonly worldRight: 0; readonly worldTop: 0; readonly worldMouseX: 0; readonly worldMouseY: 0; readonly valid: false; readonly revision: 0; }
```
## DODGE_KEY — const @experimental
@@ -6736,6 +6761,11 @@ generation: number | undefined
query: (view: InterestProviderQueryView) => ReadonlySet<Entity> | "all"
```
+## PresentedCameraView — const @beta
+```
+ResourceDef<CameraViewAPI>
+```
+
## ProbedRegistrations — interface @experimental
```
fingerprint: string
@@ -9705,6 +9735,7 @@ SizeY = 11
## UICameraData — interface @beta
```
+revision: number
screenH: number
screenW: number
valid: boolean
@@ -12861,6 +12892,11 @@ PrefabsPlugin
(prefab: PrefabData, loadPrefab: (path: string) => Promise<PrefabData>, cache: Map<string, PrefabData>, visited?: Set<string>, depth?: number): Promise<void>
```
+## presentedCameraView — const @beta
+```
+(app: App) => CameraViewAPI
+```
+
## probeRegistrations — function @experimental
```
(register: () => Promise<void>): Promise<ProbedRegistrations>
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 583f74857..c17a9cc38 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 86 beta · 1662 experimental · 3 deprecated
+Symbols: 113 public · 91 beta · 1662 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -1689,6 +1689,22 @@ minX: number
minY: number
```
+## CameraCommit — const @beta
+```
+ResourceDef<CameraCommitData>
+```
+
+## CameraCommitData — interface @beta
+```
+revision: number
+valid: boolean
+viewProjection: Float32Array<ArrayBufferLike>
+vpH: number
+vpW: number
+vpX: number
+vpY: number
+```
+
## CameraData — interface @beta
```
aspectRatio: number
@@ -1754,6 +1770,15 @@ renderTarget: number | undefined
viewport: { x: number; y: number; z: number; w: number; }
```
+## CameraLens — interface @beta
+```
+viewProjection: Float32Array<ArrayBufferLike>
+vpH: number
+vpW: number
+vpX: number
+vpY: number
+```
+
## CameraPOV — interface @experimental
```
clearFlags: number
@@ -1812,7 +1837,7 @@ projectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | null
screenRay: (screenX: number, screenY: number) => WorldRay | null
screenToWorld: (screenX: number, screenY: number, planeZ?: number) => { x: number; y: number; } | null
worldToScreen: (worldX: number, worldY: number, worldZ?: number) => { x: number; y: number; } | null
-static new (app_: App): CameraViewAPI
+static new (app_: App, lens_?: (app: App) => CameraLens | null): CameraViewAPI
static prototype: CameraViewAPI
```
@@ -2540,7 +2565,7 @@ ScreenScalingData
## DEFAULT_UI_CAMERA_INFO — const @experimental
```
-{ readonly viewProjection: Float32Array<ArrayBuffer>; readonly vpX: 0; readonly vpY: 0; readonly vpW: 0; readonly vpH: 0; readonly screenW: 0; readonly screenH: 0; readonly worldLeft: 0; readonly worldBottom: 0; readonly worldRight: 0; readonly worldTop: 0; readonly worldMouseX: 0; readonly worldMouseY: 0; readonly valid: false; }
+{ readonly viewProjection: Float32Array<ArrayBuffer>; readonly vpX: 0; readonly vpY: 0; readonly vpW: 0; readonly vpH: 0; readonly screenW: 0; readonly screenH: 0; readonly worldLeft: 0; readonly worldBottom: 0; readonly worldRight: 0; readonly worldTop: 0; readonly worldMouseX: 0; readonly worldMouseY: 0; readonly valid: false; readonly revision: 0; }
```
## DODGE_KEY — const @experimental
@@ -6548,6 +6573,11 @@ generation: number | undefined
query: (view: InterestProviderQueryView) => ReadonlySet<Entity> | "all"
```
+## PresentedCameraView — const @beta
+```
+ResourceDef<CameraViewAPI>
+```
+
## ProbedRegistrations — interface @experimental
```
fingerprint: string
@@ -9507,6 +9537,7 @@ SizeY = 11
## UICameraData — interface @beta
```
+revision: number
screenH: number
screenW: number
valid: boolean
@@ -12623,6 +12654,11 @@ PrefabsPlugin
(prefab: PrefabData, loadPrefab: (path: string) => Promise<PrefabData>, cache: Map<string, PrefabData>, visited?: Set<string>, depth?: number): Promise<void>
```
+## presentedCameraView — const @beta
+```
+(app: App) => CameraViewAPI
+```
+
## probeRegistrations — function @experimental
```
(register: () => Promise<void>): Promise<ProbedRegistrations>
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 613a64437..8dfb6f0c1 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 84 beta · 1684 experimental · 3 deprecated
+Symbols: 113 public · 89 beta · 1684 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -1689,6 +1689,22 @@ minX: number
minY: number
```
+## CameraCommit — const @beta
+```
+ResourceDef<CameraCommitData>
+```
+
+## CameraCommitData — interface @beta
+```
+revision: number
+valid: boolean
+viewProjection: Float32Array<ArrayBufferLike>
+vpH: number
+vpW: number
+vpX: number
+vpY: number
+```
+
## CameraData — interface @beta
```
aspectRatio: number
@@ -1754,6 +1770,15 @@ renderTarget: number | undefined
viewport: { x: number; y: number; z: number; w: number; }
```
+## CameraLens — interface @beta
+```
+viewProjection: Float32Array<ArrayBufferLike>
+vpH: number
+vpW: number
+vpX: number
+vpY: number
+```
+
## CameraPOV — interface @experimental
```
clearFlags: number
@@ -1812,7 +1837,7 @@ projectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | null
screenRay: (screenX: number, screenY: number) => WorldRay | null
screenToWorld: (screenX: number, screenY: number, planeZ?: number) => { x: number; y: number; } | null
worldToScreen: (worldX: number, worldY: number, worldZ?: number) => { x: number; y: number; } | null
-static new (app_: App): CameraViewAPI
+static new (app_: App, lens_?: (app: App) => CameraLens | null): CameraViewAPI
static prototype: CameraViewAPI
```
@@ -2540,7 +2565,7 @@ ScreenScalingData
## DEFAULT_UI_CAMERA_INFO — const @experimental
```
-{ readonly viewProjection: Float32Array<ArrayBuffer>; readonly vpX: 0; readonly vpY: 0; readonly vpW: 0; readonly vpH: 0; readonly screenW: 0; readonly screenH: 0; readonly worldLeft: 0; readonly worldBottom: 0; readonly worldRight: 0; readonly worldTop: 0; readonly worldMouseX: 0; readonly worldMouseY: 0; readonly valid: false; }
+{ readonly viewProjection: Float32Array<ArrayBuffer>; readonly vpX: 0; readonly vpY: 0; readonly vpW: 0; readonly vpH: 0; readonly screenW: 0; readonly screenH: 0; readonly worldLeft: 0; readonly worldBottom: 0; readonly worldRight: 0; readonly worldTop: 0; readonly worldMouseX: 0; readonly worldMouseY: 0; readonly valid: false; readonly revision: 0; }
```
## DODGE_KEY — const @experimental
@@ -6794,6 +6819,11 @@ generation: number | undefined
query: (view: InterestProviderQueryView) => ReadonlySet<Entity> | "all"
```
+## PresentedCameraView — const @beta
+```
+ResourceDef<CameraViewAPI>
+```
+
## ProbedRegistrations — interface @experimental
```
fingerprint: string
@@ -9753,6 +9783,7 @@ SizeY = 11
## UICameraData — interface @beta
```
+revision: number
screenH: number
screenW: number
valid: boolean
@@ -12880,6 +12911,11 @@ PrefabsPlugin
(prefab: PrefabData, loadPrefab: (path: string) => Promise<PrefabData>, cache: Map<string, PrefabData>, visited?: Set<string>, depth?: number): Promise<void>
```
+## presentedCameraView — const @beta
+```
+(app: App) => CameraViewAPI
+```
+
## probeRegistrations — function @experimental
```
(register: () => Promise<void>): Promise<ProbedRegistrations>
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 1778caec2..f96013e8f 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 84 beta · 1674 experimental · 3 deprecated
+Symbols: 113 public · 89 beta · 1674 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -1689,6 +1689,22 @@ minX: number
minY: number
```
+## CameraCommit — const @beta
+```
+ResourceDef<CameraCommitData>
+```
+
+## CameraCommitData — interface @beta
+```
+revision: number
+valid: boolean
+viewProjection: Float32Array<ArrayBufferLike>
+vpH: number
+vpW: number
+vpX: number
+vpY: number
+```
+
## CameraData — interface @beta
```
aspectRatio: number
@@ -1754,6 +1770,15 @@ renderTarget: number | undefined
viewport: { x: number; y: number; z: number; w: number; }
```
+## CameraLens — interface @beta
+```
+viewProjection: Float32Array<ArrayBufferLike>
+vpH: number
+vpW: number
+vpX: number
+vpY: number
+```
+
## CameraPOV — interface @experimental
```
clearFlags: number
@@ -1812,7 +1837,7 @@ projectDirectionAt: (at: Vec3, dir: Vec3) => { x: number; y: number; } | null
screenRay: (screenX: number, screenY: number) => WorldRay | null
screenToWorld: (screenX: number, screenY: number, planeZ?: number) => { x: number; y: number; } | null
worldToScreen: (worldX: number, worldY: number, worldZ?: number) => { x: number; y: number; } | null
-static new (app_: App): CameraViewAPI
+static new (app_: App, lens_?: (app: App) => CameraLens | null): CameraViewAPI
static prototype: CameraViewAPI
```
@@ -2540,7 +2565,7 @@ ScreenScalingData
## DEFAULT_UI_CAMERA_INFO — const @experimental
```
-{ readonly viewProjection: Float32Array<ArrayBuffer>; readonly vpX: 0; readonly vpY: 0; readonly vpW: 0; readonly vpH: 0; readonly screenW: 0; readonly screenH: 0; readonly worldLeft: 0; readonly worldBottom: 0; readonly worldRight: 0; readonly worldTop: 0; readonly worldMouseX: 0; readonly worldMouseY: 0; readonly valid: false; }
+{ readonly viewProjection: Float32Array<ArrayBuffer>; readonly vpX: 0; readonly vpY: 0; readonly vpW: 0; readonly vpH: 0; readonly screenW: 0; readonly screenH: 0; readonly worldLeft: 0; readonly worldBottom: 0; readonly worldRight: 0; readonly worldTop: 0; readonly worldMouseX: 0; readonly worldMouseY: 0; readonly valid: false; readonly revision: 0; }
```
## DODGE_KEY — const @experimental
@@ -6555,6 +6580,11 @@ generation: number | undefined
query: (view: InterestProviderQueryView) => ReadonlySet<Entity> | "all"
```
+## PresentedCameraView — const @beta
+```
+ResourceDef<CameraViewAPI>
+```
+
## ProbedRegistrations — interface @experimental
```
fingerprint: string
@@ -9514,6 +9544,7 @@ SizeY = 11
## UICameraData — interface @beta
```
+revision: number
screenH: number
screenW: number
valid: boolean
@@ -12646,6 +12677,11 @@ PrefabsPlugin
(prefab: PrefabData, loadPrefab: (path: string) => Promise<PrefabData>, cache: Map<string, PrefabData>, visited?: Set<string>, depth?: number): Promise<void>
```
+## presentedCameraView — const @beta
+```
+(app: App) => CameraViewAPI
+```
+
## probeRegistrations — function @experimental
```
(register: () => Promise<void>): Promise<ProbedRegistrations>
diff --git a/sdk/src/app/corePlugin.ts b/sdk/src/app/corePlugin.ts
index 0997aaba0..aa8ff2f08 100644
--- a/sdk/src/app/corePlugin.ts
+++ b/sdk/src/app/corePlugin.ts
@@ -11,7 +11,7 @@ import { initGeometryAPI, shutdownGeometryAPI } from '../render/geometry';
import { initPostProcessAPI, shutdownPostProcessAPI } from '../postprocess';
import { initRendererAPI, shutdownRendererAPI } from '../render/renderer';
import { initGLDebugAPI, shutdownGLDebugAPI } from '../render/glDebug';
-import { CameraView, CameraViewAPI } from '../camera/Camera';
+import { CameraView, CameraViewAPI, PresentedCameraView, presentedCameraView } from '../camera/Camera';
let offMemoryWarning: (() => void) | null = null;
@@ -37,6 +37,10 @@ export const corePlugin: Plugin = {
initRendererAPI(module);
initGLDebugAPI(module);
app.insertResource(CameraView, new CameraViewAPI(app));
+ // Published beside it, not instead of it: a system inside the frame
+ // wants the camera being resolved, and an overlay on the picture wants
+ // the one that drew it. Two questions, so two resources.
+ app.insertResource(PresentedCameraView, presentedCameraView(app));
},
cleanup() {
@@ -60,4 +64,5 @@ export const DEFAULT_UI_CAMERA_INFO = {
worldLeft: 0, worldBottom: 0, worldRight: 0, worldTop: 0,
worldMouseX: 0, worldMouseY: 0,
valid: false,
+ revision: 0,
} as const;
diff --git a/sdk/src/camera/Camera.ts b/sdk/src/camera/Camera.ts
index b51d81651..0d61904ec 100644
--- a/sdk/src/camera/Camera.ts
+++ b/sdk/src/camera/Camera.ts
@@ -3,6 +3,7 @@
import type { App } from '../app/app';
import { defineResource } from '../ecs/resource';
import { UICameraInfo, type UICameraData } from '../ui/core/ui-camera-info';
+import { CameraCommit } from './CameraCommit';
import type { Vec3 } from '../types';
import { screenToWorld, projectWorldPoint, projectDirectionAt, nearPlaneSide, isProjectable, createInvVPCache, screenRay, type WorldRay } from '../ui/util/math';
@@ -18,12 +19,60 @@ import { screenToWorld, projectWorldPoint, projectDirectionAt, nearPlaneSide, is
/** How far inside the near plane a cut lands, as a fraction of the segment. */
const CLIP_NUDGE = 1e-4;
+/**
+ * The camera as a LENS — what a projection needs, and nothing about the surface.
+ *
+ * Narrower than {@link UICameraData} on purpose: it is the part two different
+ * cameras can both supply, one being resolved and one already drawn with.
+ * @beta
+ */
+export interface CameraLens {
+ viewProjection: Float32Array;
+ vpX: number;
+ vpY: number;
+ vpW: number;
+ vpH: number;
+}
+
+/** The camera currently being resolved — moves twice a frame. */
+const liveLens = (app: App): CameraLens | null => {
+ const cam: UICameraData = app.getResource(UICameraInfo);
+ return cam.valid ? cam : null;
+};
+
+/** The camera the last frame was drawn with. */
+const committedLens = (app: App): CameraLens | null => {
+ const commit = app.getResource(CameraCommit);
+ return commit.valid ? commit : null;
+};
+
export class CameraViewAPI {
private readonly invVPCache = createInvVPCache();
- constructor(private readonly app_: App) {}
+ /**
+ * @param lens_ Which camera this view answers for. The default is the one
+ * being resolved — what a system inside the frame wants.
+ * Anything aligning to the PICTURE wants
+ * {@link PresentedCameraView}: the live one moves mid-frame and
+ * can hold a state no frame was drawn from.
+ */
+ constructor(
+ private readonly app_: App,
+ private readonly lens_: (app: App) => CameraLens | null = liveLens,
+ ) {}
+
+ private cam(): CameraLens | null {
+ return this.lens_(this.app_);
+ }
- private cam(): UICameraData | null {
+ /**
+ * The live UI surface, for the two answers that are not projections.
+ *
+ * Where the pointer is and what box UI lays out within are facts about the
+ * surface as it stands, not about a picture that was drawn — so they read
+ * the live resource even on a view over the committed camera.
+ */
+ private surface(): UICameraData | null {
const cam = this.app_.getResource(UICameraInfo);
return cam.valid ? cam : null;
}
@@ -122,13 +171,13 @@ export class CameraViewAPI {
}
getWorldMousePosition(): { x: number; y: number } | null {
- const cam = this.cam();
+ const cam = this.surface();
if (!cam) return null;
return { x: cam.worldMouseX, y: cam.worldMouseY };
}
getWorldBounds(): { left: number; right: number; bottom: number; top: number } | null {
- const cam = this.cam();
+ const cam = this.surface();
if (!cam) return null;
return { left: cam.worldLeft, right: cam.worldRight, bottom: cam.worldBottom, top: cam.worldTop };
}
@@ -140,3 +189,16 @@ export class CameraViewAPI {
* `CameraView` rather than `Camera` because `Camera` is the ECS component.)
*/
export const CameraView = defineResource<CameraViewAPI>(null!, 'CameraView');
+
+/**
+ * The same queries, against the camera the last frame was actually drawn with.
+ *
+ * One implementation, two sources: a second projection written over the commit
+ * would be a second near-plane cut to keep in step, and a wireframe cut by one
+ * and drawn by the other comes apart exactly where a segment leaves the view.
+ * @beta
+ */
+export const PresentedCameraView = defineResource<CameraViewAPI>(null!, 'PresentedCameraView');
+
+/** A view over the camera the last frame was drawn with. @beta */
+export const presentedCameraView = (app: App): CameraViewAPI => new CameraViewAPI(app, committedLens);
diff --git a/sdk/src/camera/CameraCommit.ts b/sdk/src/camera/CameraCommit.ts
new file mode 100644
index 000000000..68e99b7b3
--- /dev/null
+++ b/sdk/src/camera/CameraCommit.ts
@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file CameraCommit.ts
+ * @brief The camera the picture on screen was drawn from.
+ * @details Anything that draws OVER the canvas — an editor's gizmo overlay, a
+ * DOM label pinned to a world point — has to project through the same
+ * camera the canvas did, or it lands somewhere the picture never was.
+ *
+ * {@link UICameraInfo} cannot answer that. Its matrix is rewritten in
+ * place twice a frame (an early peek, then the authoritative resolve),
+ * so a reader on its own clock samples at an arbitrary phase and can
+ * get a camera no frame was ever drawn with — not stale, a third state.
+ *
+ * This is a COPY, published once, after the draw. A reader holding it
+ * holds a moment rather than a view onto memory somebody else is still
+ * writing, and `revision` says which moment, so an overlay can be held
+ * to having used the same one.
+ */
+import { defineResource } from '../ecs/resource';
+
+/** @beta */
+export interface CameraCommitData {
+ /** The {@link UICameraData.revision} this frame was drawn with; 0 = none. */
+ revision: number;
+ /** The view-projection that drew it — a copy, not the live resource's array. */
+ viewProjection: Float32Array;
+ /** Where the picture landed, in window pixels. */
+ vpX: number;
+ vpY: number;
+ vpW: number;
+ vpH: number;
+ /** False until a frame has been drawn with a camera at all. */
+ valid: boolean;
+}
+
+/** The last drawn camera, as a resource. @beta */
+export const CameraCommit = defineResource<CameraCommitData>({
+ revision: 0,
+ viewProjection: new Float32Array(16),
+ vpX: 0, vpY: 0, vpW: 0, vpH: 0,
+ valid: false,
+}, 'CameraCommit');
diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.ts
index eb35bc999..9d2515227 100644
--- a/sdk/src/camera/CameraPlugin.ts
+++ b/sdk/src/camera/CameraPlugin.ts
@@ -16,6 +16,7 @@ import type { ESEngineModule, CppRegistry } from '../wasm';
import type { World } from '../ecs/world';
import type { Entity } from '../types';
import { UICameraInfo, type UICameraData } from '../ui/core/ui-camera-info';
+import { CameraCommit } from './CameraCommit';
import { ScreenLayout, screenLayoutRect, screenProjection } from '../ui/core/screen-layout';
import { ScreenOverlay } from '../ui/core/screen-overlay';
import { ProjectionType, SceneOwner, ClearFlags } from '../ecs/component';
@@ -589,6 +590,28 @@ function publishScreenLayout(
);
}
+/**
+ * Publish the camera this frame was drawn from, as a copy.
+ *
+ * After the submit, never from the early peek: the value names a picture, and a
+ * peek draws nothing. Copied because UICameraInfo's array is rewritten in place,
+ * so a view onto it would change under a reader mid-gizmo.
+ */
+function commitCamera(app: App, cam: CameraInfo | null, uiCam: UICameraData): void {
+ const commit = app.getResource(CameraCommit);
+ if (!cam) {
+ commit.valid = false;
+ return;
+ }
+ commit.viewProjection.set(cam.viewProjection);
+ commit.vpX = uiCam.vpX;
+ commit.vpY = uiCam.vpY;
+ commit.vpW = uiCam.vpW;
+ commit.vpH = uiCam.vpH;
+ commit.revision = uiCam.revision;
+ commit.valid = true;
+}
+
function syncUICameraInfo(
app: App,
module: ESEngineModule | null,
@@ -606,6 +629,9 @@ function syncUICameraInfo(
if (cameras.length > 0) {
const cam = cameras[0];
uiCam.viewProjection.set(cam.viewProjection);
+ // In the same statement group as the write it names: a revision published
+ // apart from the matrix is a reader's chance to see one without the other.
+ uiCam.revision++;
// Against the WINDOW, not the camera's render target: this rect is what a
// pointer's coordinates are normalised by, and a pointer is on the window.
const box = viewportPixels(cam.viewportRect, width, height);
@@ -639,6 +665,7 @@ function syncUICameraInfo(
uiCam.valid = true;
} else {
uiCam.valid = false;
+ uiCam.revision++;
}
publishScreenOverlay(app, width, height, uiCam, cameras);
}
@@ -860,6 +887,11 @@ export function cameraPlugin(
// swapchain image goes back.
pipeline.endFrame();
}, { remainder: 'wait' });
+
+ // The frame is drawn; say which camera drew it. After the
+ // submit, so nothing can publish a commit for a picture that
+ // then failed to render.
+ commitCamera(app, cameras.length > 0 ? cameras[0] : null, app.getResource(UICameraInfo));
},
};
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index 9dad62425..d23c2661b 100644
--- a/sdk/src/core-render.ts
+++ b/sdk/src/core-render.ts
@@ -41,7 +41,8 @@ export { TextureFilter, TextureWrap, setTextureFilter, setTextureWrap, setTextur
// Camera
// =============================================================================
-export { CameraView, CameraViewAPI } from './camera/Camera';
+export { CameraView, CameraViewAPI, PresentedCameraView, presentedCameraView, type CameraLens } from './camera/Camera';
+export { CameraCommit, type CameraCommitData } from './camera/CameraCommit';
export { EditorView, DEFAULT_EDITOR_VIEW, editorViewHalfHeight, editorViewHalfExtent, editorViewWorldPerPixel, setEditorViewHalfHeight, editorViewIsOrbited, editorViewAxes, editorViewAxisAngles, editorViewBasis, editorViewEye, editorViewStandoff, editorViewClipFar, editorViewClipNear, editorViewWorkPlane, editorViewGridPlane, screenWorkAxes, worldAxisVector, moveEditorViewFocus, editorViewBoxExtent } from './camera/EditorView';
export type { EditorViewData, ScreenAxis, EditorViewBasis, EditorWorkPlane, WorldAxis } from './camera/EditorView';
export { ScreenScaling, DEFAULT_SCREEN_SCALING, SCREEN_FIT_OFF } from './camera/ScreenScaling';
diff --git a/sdk/src/ui/core/ui-camera-info.ts b/sdk/src/ui/core/ui-camera-info.ts
index 47daa45f2..a4425550a 100644
--- a/sdk/src/ui/core/ui-camera-info.ts
+++ b/sdk/src/ui/core/ui-camera-info.ts
@@ -23,6 +23,14 @@ export interface UICameraData {
worldMouseX: number;
worldMouseY: number;
valid: boolean;
+ /**
+ * Which write of {@link UICameraData.viewProjection} this is.
+ *
+ * The matrix is rewritten IN PLACE twice a frame — an early peek, then the
+ * resolve the renderer draws from — so a reader holds live memory and cannot
+ * tell the two apart. This number can; `CameraCommit` is the drawn one.
+ */
+ revision: number;
}
/** The UI surface, as a resource — what a system reads to place something in
@@ -35,4 +43,5 @@ export const UICameraInfo = defineResource<UICameraData>({
worldLeft: 0, worldBottom: 0, worldRight: 0, worldTop: 0,
worldMouseX: 0, worldMouseY: 0,
valid: false,
+ revision: 0,
}, 'UICameraInfo');
diff --git a/sdk/tests/camera-commit.test.ts b/sdk/tests/camera-commit.test.ts
new file mode 100644
index 000000000..dc49bf7ea
--- /dev/null
+++ b/sdk/tests/camera-commit.test.ts
@@ -0,0 +1,158 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file The camera an overlay is allowed to project through.
+ *
+ * A gizmo drawn over the canvas has to use the camera the canvas was drawn with.
+ * UICameraInfo cannot answer that: its matrix is rewritten in place twice a
+ * frame — an early peek that must not tick the director's blend, then the
+ * authoritative resolve the render system draws from — so a reader on its own
+ * clock samples at an arbitrary phase. CameraCommit is the answer, published
+ * once, after the submit, as a copy.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { bootMockApp } from './helpers/mockApp';
+import { setPlatform } from '../src/platform/base';
+import type { PlatformAdapter } from '../src/platform/types';
+import { cameraPlugin } from '../src/camera/CameraPlugin';
+import { CameraCommit } from '../src/camera/CameraCommit';
+import { UICameraInfo } from '../src/ui/core/ui-camera-info';
+import { RenderPipeline } from '../src/render/renderPipeline';
+import { setRendererBackend, type RendererBackend } from '../src/render/renderer';
+import { defineSystem, Schedule } from '../src/ecs/system';
+import { Camera, Transform, ProjectionType } from '../src/ecs/component';
+import { Query, Mut } from '../src/ecs/query';
+import type { Entity } from '../src/types';
+import type { CppRegistry } from '../src/wasm';
+
+/** The mock's registry. Its runtime shape is wider than the module type, which
+ * declares a `Registry` constructor rather than this accessor. */
+const registryOf = (module: unknown): Record<string, unknown> & CppRegistry =>
+ (module as { getRegistry(): unknown }).getRegistry() as Record<string, unknown> & CppRegistry;
+
+describe('the camera a frame was drawn with', () => {
+ let drawnWith: Float32Array | null = null;
+
+ function fakeBackend(): RendererBackend {
+ return {
+ init: () => {}, resize: () => {},
+ beginFrame: () => {}, updateTransforms: () => {},
+ begin: (viewProjection) => { drawnWith = new Float32Array(viewProjection); },
+ submitAll: () => {}, flush: () => {}, end: () => {}, endFrame: () => {},
+ hasScreenOverlay: () => false,
+ beginScreenOverlay: () => {}, submitScreenOverlay: () => {}, endScreenOverlay: () => {},
+ setStage: () => {}, setViewport: () => {},
+ setYSortLayers: () => {}, setDepthLayers: () => {}, setCullingMask: () => {},
+ setViewId: () => {},
+ lodInspect: () => null, setLodPreview: () => {}, lightStatus: () => null, shadowStatus: () => null,
+ getStats: () => ({ drawCalls: 0, triangles: 0, sprites: 0, text: 0, skeletal: 0, meshes: 0, culled: 0 }),
+ };
+ }
+
+ /** An app with one orthographic camera, drawing through the fake backend. */
+ function bootWithCamera() {
+ const { app, module } = bootMockApp();
+ const registry = registryOf(module);
+ const cam = app.world.spawn('camera') as Entity;
+ app.world.insert(cam, Transform, { position: { x: 0, y: 0, z: 0 } });
+ app.world.insert(cam, Camera, {
+ isActive: true, projectionType: ProjectionType.Orthographic, orthoSize: 300,
+ });
+ registry.getCameraEntities = () => [cam];
+ registry.getCanvasEntities = () => [];
+ app.setPipeline(new RenderPipeline());
+ setRendererBackend(fakeBackend());
+ app.addPlugin(cameraPlugin(() => ({ width: 800, height: 600 })));
+ return { app, cam };
+ }
+
+ beforeEach(() => {
+ drawnWith = null;
+ setPlatform({ now: () => 0, devicePixelRatio: () => 1 } as unknown as PlatformAdapter);
+ });
+ afterEach(() => { setRendererBackend(null); });
+
+ it('is published, and names the write it came from', async () => {
+ const { app } = bootWithCamera();
+ await app.tick(1 / 60);
+
+ const commit = app.getResource(CameraCommit);
+ expect(commit.valid).toBe(true);
+ expect(commit.revision).toBeGreaterThan(0);
+ // The picture and the commit agree — one that named a different matrix
+ // would send every overlay somewhere the frame never drew.
+ expect(drawnWith).not.toBeNull();
+ expect(Array.from(commit.viewProjection)).toEqual(Array.from(drawnWith!));
+ });
+
+ it('is a copy, so a later write cannot move it under a reader', async () => {
+ const { app } = bootWithCamera();
+ await app.tick(1 / 60);
+ const commit = app.getResource(CameraCommit);
+ const held = new Float32Array(commit.viewProjection);
+
+ // What the engine does to UICameraInfo between an overlay's two reads.
+ const uiCam = app.getResource(UICameraInfo);
+ uiCam.viewProjection.fill(99);
+
+ expect(Array.from(commit.viewProjection)).toEqual(Array.from(held));
+ expect(commit.viewProjection).not.toBe(uiCam.viewProjection);
+ });
+
+ it('advances once per drawn frame, never backwards', async () => {
+ const { app } = bootWithCamera();
+ const seen: number[] = [];
+ for (let i = 0; i < 3; i++) {
+ await app.tick(1 / 60);
+ seen.push(app.getResource(CameraCommit).revision);
+ }
+ expect(seen).toEqual([...seen].sort((a, b) => a - b));
+ expect(new Set(seen).size).toBe(seen.length);
+ });
+
+ it('is BEHIND the live resource mid-frame, which is the reason it exists', async () => {
+ // The early peek moves UICameraInfo.revision before anything is drawn
+ // with it, so a reader landing here holds a camera no frame was ever
+ // drawn from: not a stale one, a third state.
+ const { app } = bootWithCamera();
+ await app.tick(1 / 60);
+
+ let midFrame = -1;
+ app.addSystemToSchedule(Schedule.PreUpdate, defineSystem(
+ [],
+ () => { midFrame = app.getResource(UICameraInfo).revision; },
+ { name: 'readAfterEarlySync' },
+ ));
+ const committedBefore = app.getResource(CameraCommit).revision;
+ await app.tick(1 / 60);
+
+ expect(midFrame).toBeGreaterThan(committedBefore);
+ expect(midFrame).not.toBe(app.getResource(CameraCommit).revision);
+ });
+
+ it('follows the camera that moved, not the one the peek saw', async () => {
+ const { app } = bootWithCamera();
+ const SPEED = 300;
+ app.addSystemToSchedule(Schedule.Update, defineSystem(
+ [Query(Mut(Transform), Camera)],
+ (query) => { query.forEach((_e, t) => { t.position.x += SPEED * (1 / 60); }); },
+ { name: 'cameraMove' },
+ ));
+ await app.tick(1 / 60);
+
+ const commit = app.getResource(CameraCommit);
+ expect(Array.from(commit.viewProjection)).toEqual(Array.from(drawnWith!));
+ });
+
+ it('says nothing when no camera drew', async () => {
+ const { app, module } = bootMockApp();
+ const registry = registryOf(module);
+ registry.getCameraEntities = () => [];
+ registry.getCanvasEntities = () => [];
+ app.setPipeline(new RenderPipeline());
+ setRendererBackend(fakeBackend());
+ app.addPlugin(cameraPlugin(() => ({ width: 800, height: 600 })));
+ await app.tick(1 / 60);
+ expect(app.getResource(CameraCommit).valid).toBe(false);
+ });
+});
diff --git a/sdk/tests/ui-anchor-preset.test.ts b/sdk/tests/ui-anchor-preset.test.ts
index b2fda9211..867f5907e 100644
--- a/sdk/tests/ui-anchor-preset.test.ts
+++ b/sdk/tests/ui-anchor-preset.test.ts
@@ -114,7 +114,7 @@ describe.skipIf(!HAS_WASM)('anchor presets lay out via Yoga (WASM integration)',
viewProjection: new Float32Array(16),
vpX: 0, vpY: 0, vpW: 0, vpH: 0, screenW: 0, screenH: 0,
worldLeft: -400, worldBottom: -300, worldRight: 400, worldTop: 300,
- worldMouseX: 0, worldMouseY: 0, valid: true,
+ worldMouseX: 0, worldMouseY: 0, valid: true, revision: 1,
});
setScreenBox(app, -400, -300, 400, 300);
app.addPlugin(uiLayoutPlugin);
diff --git a/sdk/tests/ui-components.test.ts b/sdk/tests/ui-components.test.ts
index c3416ca16..65fd1be18 100644
--- a/sdk/tests/ui-components.test.ts
+++ b/sdk/tests/ui-components.test.ts
@@ -77,6 +77,7 @@ describe.skipIf(!HAS_WASM)('UI Components (WASM integration)', () => {
worldLeft: 0, worldBottom: 0, worldRight: 0, worldTop: 0,
worldMouseX: 0, worldMouseY: 0,
valid: false,
+ revision: 1,
});
app.addPlugin(uiLayoutPlugin);
diff --git a/sdk/tests/ui-layout-incremental.test.ts b/sdk/tests/ui-layout-incremental.test.ts
index 6df9957cf..e20031be4 100644
--- a/sdk/tests/ui-layout-incremental.test.ts
+++ b/sdk/tests/ui-layout-incremental.test.ts
@@ -64,7 +64,7 @@ describe.skipIf(!HAS_WASM)('incremental layout equals a fresh solve', () => {
vpX: 0, vpY: 0, vpW: 0, vpH: 0, screenW: 0, screenH: 0,
worldLeft: -camW / 2, worldBottom: -camH / 2,
worldRight: camW / 2, worldTop: camH / 2,
- worldMouseX: 0, worldMouseY: 0, valid: true,
+ worldMouseX: 0, worldMouseY: 0, valid: true, revision: 1,
});
setScreenBox(app, -camW / 2, -camH / 2, camW / 2, camH / 2);
app.addPlugin(uiLayoutPlugin);
diff --git a/sdk/tests/ui-layout-integration.test.ts b/sdk/tests/ui-layout-integration.test.ts
index a5da23cba..7e65ae42c 100644
--- a/sdk/tests/ui-layout-integration.test.ts
+++ b/sdk/tests/ui-layout-integration.test.ts
@@ -108,6 +108,7 @@ describe.skipIf(!HAS_WASM)('UI Layout via App.tick() (WASM integration)', () =>
worldLeft: 0, worldBottom: 0, worldRight: 0, worldTop: 0,
worldMouseX: 0, worldMouseY: 0,
valid: false,
+ revision: 1,
});
app.insertResource(ScreenLayout, { ...ScreenLayout._default });
diff --git a/sdk/tests/ui-list-view-widget.test.ts b/sdk/tests/ui-list-view-widget.test.ts
index 81d7b23d6..5ab1e47a4 100644
--- a/sdk/tests/ui-list-view-widget.test.ts
+++ b/sdk/tests/ui-list-view-widget.test.ts
@@ -30,7 +30,7 @@ describe.skipIf(!HAS_WASM)('createListView (WASM integration)', () => {
viewProjection: new Float32Array(16),
vpX: 0, vpY: 0, vpW: 0, vpH: 0, screenW: 0, screenH: 0,
worldLeft: 0, worldBottom: 0, worldRight: 800, worldTop: 600,
- worldMouseX: 0, worldMouseY: 0, valid: true,
+ worldMouseX: 0, worldMouseY: 0, valid: true, revision: 1,
});
// No inputPlugin: it binds platform input (unavailable in tests). The Input
// resource has a default InputState, so the ScrollWheelSystem still resolves.