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): a camera can render into a texture

esenginef7de8a0cec1b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e5866aa47..bec3e0681 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,21 @@ published separately; it ships inside the editor.
### Changed
+- **A camera can render into a texture.** `Camera.renderTarget` takes a
+ `RenderTexture` handle and that camera draws there instead of the screen — a
+ minimap, a mirror, a portrait, the scene half of cache-as-bitmap. The engine
+ could always open a pass on an offscreen target; what was missing is that no
+ camera ever named one, so `Renderer.begin` was called with 0 every time. Such a
+ camera does not compete to be the main view (a camera drawing elsewhere is not a
+ candidate for the screen) and renders BEFORE the screen cameras, because what it
+ draws is usually what they are about to sample. Its viewport fractions are of
+ the target, whose own size sets the resolution, and a released target falls back
+ to the screen rather than drawing nowhere.
+
+ WebGL2 today. The WebGPU backend cannot yet adopt a device texture into the
+ resource table (`importExternalTexture`), so the target a camera fills there
+ cannot be handed to a `Sprite`.
+
- **Removed: 26 engine entry points no host called.** Five of them
(`renderer_submitSprites` / `submitUIElements` / `submitBitmapText` /
`submitShapes` / `submitParticles`) had bodies that were `(void)registry;` —
@@ -193,6 +208,13 @@ published separately; it ships inside the editor.
### Fixed
+- **WebGPU reused one pipeline for two different colour formats.** The pipeline
+ variant key mapped every 8-bit unorm format to one slot, so a pipeline built for
+ the surface (`BGRA8Unorm`) was handed to a pass on a render target
+ (`RGBA8Unorm`) — which WebGPU rejects outright, taking the whole command buffer
+ with it. Nothing had drawn a scene into an offscreen target on that backend
+ before, so nothing had asked.
+
- **The manual taught an import that does not exist.** `facingFromQuat` was
removed when perception moved to a dot-product cone, and four pages went on
importing it — including a complete turret example a reader would copy. It is
diff --git a/docs/astro/src/content/docs/graphics/drawing.mdx b/docs/astro/src/content/docs/graphics/drawing.mdx
index 7a10fa3ad..e4e4ad9b6 100644
--- a/docs/astro/src/content/docs/graphics/drawing.mdx
+++ b/docs/astro/src/content/docs/graphics/drawing.mdx
@@ -165,7 +165,15 @@ For minimaps, portraits, mirrors — and as the backing of
[cache-as-bitmap](/docs/graphics/sprites/) — `RenderTexture` allocates an offscreen
render target. Wrap draw commands in `begin`/`end` to render into it; the
resulting `texture` is an ordinary texture handle usable anywhere (a
-`Sprite.texture`, `Draw.texture`, a material texture param):
+`Sprite.texture`, `Draw.texture`, a material texture param).
+
+A whole **scene** goes into one by pointing a camera at it: set
+`Camera.renderTarget` to the target's handle and that camera draws there instead
+of the screen, before the screen cameras and without competing to be the main
+view. Its own sorting layers (`Camera.cullingMask`) decide what it sees, so a
+minimap camera and the player's camera can look at the same world and show
+different parts of it. On WebGL2 today; the WebGPU backend cannot yet hand a
+render target's texture to a `Sprite`:
```typescript
import { RenderTexture, Draw } from 'esengine';
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx b/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx
index c8d8cf347..eaa2eba90 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx
@@ -154,7 +154,13 @@ registerDrawCallback('custom-mesh', () => {
小地图、头像、镜面——以及[位图缓存](/docs/zh-cn/graphics/sprites/)的底层——
`RenderTexture` 分配一个离屏渲染目标。把绘制命令包在 `begin`/`end` 之间即渲染
进去;得到的 `texture` 是普通纹理句柄,哪里都能用(`Sprite.texture`、
-`Draw.texture`、材质纹理参数):
+`Draw.texture`、材质纹理参数)。
+
+要把**整个场景**画进去,让一台相机指向它:把 `Camera.renderTarget` 设成目标的句柄,
+那台相机就画到那里而不是屏幕——在屏幕相机之前渲染,也不参与「谁是主视图」的竞争。
+它看见什么由自己的排序层(`Camera.cullingMask`)决定,所以小地图相机和玩家相机可以
+看同一个世界、显示不同的部分。目前仅 WebGL2:WebGPU 后端还不能把渲染目标的纹理
+交给 `Sprite`:
```typescript
import { RenderTexture, Draw } from 'esengine';
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index cafe07962..6d7a07e88 100644
--- a/docs/astro/src/data/components.generated.json
+++ b/docs/astro/src/data/components.generated.json
@@ -402,6 +402,13 @@
"default": "4294967295",
"doc": "Which sorting layers this camera renders."
},
+ {
+ "key": "renderTarget",
+ "type": "number",
+ "default": "0",
+ "doc": "Render into a RenderTexture instead of the screen (0 = screen). Set at run time.",
+ "advanced": true
+ },
{
"key": "showFrustum",
"type": "boolean",
diff --git a/examples/render-texture/src/main.ts b/examples/render-texture/src/main.ts
index 634d10016..87e05ce9b 100644
--- a/examples/render-texture/src/main.ts
+++ b/examples/render-texture/src/main.ts
@@ -9,9 +9,9 @@
// 768×480 at a fixed display size — resize() returns a NEW handle whose
// textureId the sprite must be re-pointed at.
//
-// RenderTexture is a low-level surface: a camera cannot target it, and it does
-// not re-render the scene. It redirects Draw commands issued between begin()
-// and end() into an offscreen target, under a view-projection you supply.
+// RenderTexture is the low-level surface: Draw commands issued between begin()
+// and end() go into an offscreen target under a view-projection you supply.
+// A whole SCENE goes into one through Camera.renderTarget.
import { addStartupSystem, addSystemToSchedule, Schedule } from 'esengine';
import './components';
diff --git a/fixtures/scenes/camera-target.esscene b/fixtures/scenes/camera-target.esscene
new file mode 100644
index 000000000..b42828684
--- /dev/null
+++ b/fixtures/scenes/camera-target.esscene
@@ -0,0 +1,136 @@
+{
+ "version": 2,
+ "name": "CameraTarget",
+ "entities": [
+ {
+ "id": 0,
+ "name": "OffscreenCamera",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 10
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 100,
+ "isActive": true,
+ "priority": 0,
+ "clearFlags": 3,
+ "cullingMask": 2
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "RedFill",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 400,
+ "y": 400
+ },
+ "color": {
+ "r": 1,
+ "g": 0,
+ "b": 0,
+ "a": 1
+ },
+ "layer": 1
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 2,
+ "name": "ScreenCamera",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 10
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 300,
+ "isActive": true,
+ "priority": 1,
+ "clearFlags": 3,
+ "cullingMask": 1
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 3,
+ "name": "Screen",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 300,
+ "y": 300
+ },
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "layer": 0
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/fixtures/scenes/camera-target.textures.json b/fixtures/scenes/camera-target.textures.json
new file mode 100644
index 000000000..0967ef424
--- /dev/null
+++ b/fixtures/scenes/camera-target.textures.json
@@ -0,0 +1 @@
+{}
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index c852b7b35..0b3dbf04b 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -5,7 +5,7 @@ Symbols: 113 public · 66 beta · 1507 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"43f91684e5f3d3fb"
+"f4ba1e6b5d361dee"
```
## ANCHOR_AXES — const @experimental
@@ -1535,6 +1535,7 @@ orthoSize: number
pixelPerfect: boolean
priority: number
projectionType: number
+renderTarget: number
showFrustum: boolean
viewport: Vec4
```
@@ -1582,6 +1583,7 @@ orthoSize: number
pixelPerfect: boolean
priority: number
projectionType: number
+renderTarget: number | undefined
viewport: { x: number; y: number; z: number; w: number; }
```
@@ -1599,6 +1601,7 @@ orthoSize: number
pixelPerfect: boolean
priority: number
projection: number
+renderTarget: number
rotation: number
tilt: { x: number; y: number; z: number; w: number; } | undefined
viewport: { x: number; y: number; z: number; w: number; }
@@ -1615,6 +1618,7 @@ clearFlags: number
cullingMask: number | undefined
elapsed: number
registry: { _cpp: CppRegistry; }
+renderTarget: number | undefined
viewProjection: Float32Array<ArrayBufferLike>
viewportPixels: Viewport
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 7c6a34918..8956f141f 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -5,7 +5,7 @@ Symbols: 113 public · 71 beta · 1526 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"43f91684e5f3d3fb"
+"f4ba1e6b5d361dee"
```
## ANCHOR_AXES — const @experimental
@@ -1535,6 +1535,7 @@ orthoSize: number
pixelPerfect: boolean
priority: number
projectionType: number
+renderTarget: number
showFrustum: boolean
viewport: Vec4
```
@@ -1582,6 +1583,7 @@ orthoSize: number
pixelPerfect: boolean
priority: number
projectionType: number
+renderTarget: number | undefined
viewport: { x: number; y: number; z: number; w: number; }
```
@@ -1599,6 +1601,7 @@ orthoSize: number
pixelPerfect: boolean
priority: number
projection: number
+renderTarget: number
rotation: number
tilt: { x: number; y: number; z: number; w: number; } | undefined
viewport: { x: number; y: number; z: number; w: number; }
@@ -1615,6 +1618,7 @@ clearFlags: number
cullingMask: number | undefined
elapsed: number
registry: { _cpp: CppRegistry; }
+renderTarget: number | undefined
viewProjection: Float32Array<ArrayBufferLike>
viewportPixels: Viewport
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index df4bb47ff..3d8824cbc 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1530,6 +1530,7 @@ orthoSize: number
pixelPerfect: boolean
priority: number
projectionType: number
+renderTarget: number
showFrustum: boolean
viewport: Vec4
```
@@ -1577,6 +1578,7 @@ orthoSize: number
pixelPerfect: boolean
priority: number
projectionType: number
+renderTarget: number | undefined
viewport: { x: number; y: number; z: number; w: number; }
```
@@ -1594,6 +1596,7 @@ orthoSize: number
pixelPerfect: boolean
priority: number
projection: number
+renderTarget: number
rotation: number
tilt: { x: number; y: number; z: number; w: number; } | undefined
viewport: { x: number; y: number; z: number; w: number; }
@@ -1610,6 +1613,7 @@ clearFlags: number
cullingMask: number | undefined
elapsed: number
registry: { _cpp: CppRegistry; }
+renderTarget: number | undefined
viewProjection: Float32Array<ArrayBufferLike>
viewportPixels: Viewport
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 80ab93907..179cf5c80 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1530,6 +1530,7 @@ orthoSize: number
pixelPerfect: boolean
priority: number
projectionType: number
+renderTarget: number
showFrustum: boolean
viewport: Vec4
```
@@ -1577,6 +1578,7 @@ orthoSize: number
pixelPerfect: boolean
priority: number
projectionType: number
+renderTarget: number | undefined
viewport: { x: number; y: number; z: number; w: number; }
```
@@ -1594,6 +1596,7 @@ orthoSize: number
pixelPerfect: boolean
priority: number
projection: number
+renderTarget: number
rotation: number
tilt: { x: number; y: number; z: number; w: number; } | undefined
viewport: { x: number; y: number; z: number; w: number; }
@@ -1610,6 +1613,7 @@ clearFlags: number
cullingMask: number | undefined
elapsed: number
registry: { _cpp: CppRegistry; }
+renderTarget: number | undefined
viewProjection: Float32Array<ArrayBufferLike>
viewportPixels: Viewport
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 57d4cb71f..b4fabf82b 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1530,6 +1530,7 @@ orthoSize: number
pixelPerfect: boolean
priority: number
projectionType: number
+renderTarget: number
showFrustum: boolean
viewport: Vec4
```
@@ -1577,6 +1578,7 @@ orthoSize: number
pixelPerfect: boolean
priority: number
projectionType: number
+renderTarget: number | undefined
viewport: { x: number; y: number; z: number; w: number; }
```
@@ -1594,6 +1596,7 @@ orthoSize: number
pixelPerfect: boolean
priority: number
projection: number
+renderTarget: number
rotation: number
tilt: { x: number; y: number; z: number; w: number; } | undefined
viewport: { x: number; y: number; z: number; w: number; }
@@ -1610,6 +1613,7 @@ clearFlags: number
cullingMask: number | undefined
elapsed: number
registry: { _cpp: CppRegistry; }
+renderTarget: number | undefined
viewProjection: Float32Array<ArrayBufferLike>
viewportPixels: Viewport
```
diff --git a/sdk/src/camera/CameraDirector.ts b/sdk/src/camera/CameraDirector.ts
index 114aebd2c..7c5e331cd 100644
--- a/sdk/src/camera/CameraDirector.ts
+++ b/sdk/src/camera/CameraDirector.ts
@@ -60,6 +60,7 @@ export function lerpPOV(a: CameraPOV, b: CameraPOV, t: number): CameraPOV {
priority: b.priority,
pixelPerfect: t < 0.5 ? a.pixelPerfect : b.pixelPerfect, // discrete: flip at the midpoint
cullingMask: b.cullingMask, // discrete: the target camera decides what it shows
+ renderTarget: b.renderTarget, // discrete: a blend cannot be half in a texture
};
}
diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.ts
index c2945462e..94584696e 100644
--- a/sdk/src/camera/CameraPlugin.ts
+++ b/sdk/src/camera/CameraPlugin.ts
@@ -22,6 +22,7 @@ import { EditorView, DEFAULT_EDITOR_VIEW, editorViewStandoff, editorViewClipFar,
import { ScreenScaling, DEFAULT_SCREEN_SCALING, SCREEN_FIT_OFF } from './ScreenScaling';
import { CameraDirector, createDirectorState, resolveMainPOV } from './CameraDirector';
import { RenderPipeline } from '../render/renderPipeline';
+import { renderTargetSize } from '../render/renderTexture';
import { Renderer } from '../render/renderer';
import { platformNow, platformDevicePixelRatio } from '../platform';
import { SceneManager } from '../scene/sceneManager';
@@ -45,6 +46,8 @@ interface CameraInfo {
cameraX: number;
cameraY: number;
cullingMask: number;
+ /** Offscreen target this camera draws into; 0 = the screen. */
+ renderTarget: number;
}
function acquireCameraInfo(pool: CameraInfo[], index: number): CameraInfo {
@@ -62,6 +65,7 @@ function acquireCameraInfo(pool: CameraInfo[], index: number): CameraInfo {
cameraX: 0,
cameraY: 0,
cullingMask: 0xFFFFFFFF,
+ renderTarget: 0,
};
pool.push(info);
return info;
@@ -174,6 +178,8 @@ export interface CameraPOV {
pixelPerfect: boolean;
/** Sorting layers this camera renders; bit i = layer i. */
cullingMask: number;
+ /** Offscreen target this camera draws into; 0 = the screen. */
+ renderTarget: number;
}
/**
@@ -206,6 +212,8 @@ export interface CameraFields {
pixelPerfect: boolean;
/** Absent on a core built before the field; that camera drew every layer. */
cullingMask?: number;
+ /** Absent on a core built before the field; that camera drew to the screen. */
+ renderTarget?: number;
}
/**
@@ -248,6 +256,7 @@ function readCameraPOV(
pixelPerfect: camera.pixelPerfect,
// A core built before the field answers undefined; that camera drew everything.
cullingMask: camera.cullingMask ?? 0xFFFFFFFF,
+ renderTarget: camera.renderTarget ?? 0,
};
}
@@ -321,6 +330,7 @@ export function buildCameraInfo(
cam.cameraX = camX;
cam.cameraY = camY;
cam.cullingMask = pov.cullingMask;
+ cam.renderTarget = pov.renderTarget;
return cam;
}
@@ -447,6 +457,7 @@ export function editorCameraInfo(
// The editor's own eye is not a game camera: it shows every layer, so a
// culled scene camera never hides content from authoring.
cullingMask: 0xFFFFFFFF,
+ renderTarget: 0,
};
return buildCameraInfo(pov, width, height, null, pool, 0);
}
@@ -506,10 +517,16 @@ function resolveCameras(
const povs = collectCameraPOVs(module, cppRegistry, width, height, world, activeScenes);
if (povs.length === 0) return [];
const canvas = resolveFitSource(app, findCanvasData(module, cppRegistry, world, activeScenes));
- const fullFrame = povs.filter((p) => isFullFrame(p.viewport));
- const overlays = povs.filter((p) => !isFullFrame(p.viewport)).sort((a, b) => a.priority - b.priority);
+ // A camera drawing into a texture is not a candidate for the screen: it does
+ // not compete with the main view, and it renders BEFORE it, because what it
+ // draws is usually what the main view is about to sample.
+ const offscreen = povs.filter((p) => p.renderTarget !== 0).sort((a, b) => a.priority - b.priority);
+ const onScreen = povs.filter((p) => p.renderTarget === 0);
+ const fullFrame = onScreen.filter((p) => isFullFrame(p.viewport));
+ const overlays = onScreen.filter((p) => !isFullFrame(p.viewport)).sort((a, b) => a.priority - b.priority);
const out: CameraInfo[] = [];
+ for (const p of offscreen) out.push(buildCameraInfo(p, width, height, canvas, pool, out.length));
// The director resolves ONE main view from the full-frame candidates (active
// camera + view-target blending); index 0 → it also drives screen<->world.
if (fullFrame.length > 0 && app.hasResource(CameraDirector)) {
@@ -685,10 +702,17 @@ export function cameraPlugin(
pipeline.beginScreenCapture();
for (const cam of cameras) {
const vp = cam.viewportRect;
- const px = Math.round(vp.x * width);
- const py = Math.round((1 - vp.y - vp.h) * height);
- const pw = Math.round(vp.w * width);
- const ph = Math.round(vp.h * height);
+ // A camera drawing into a texture is measured against
+ // THAT surface: its viewport rect is a fraction, and
+ // the fraction is of the target it draws to.
+ const target = cam.renderTarget !== 0
+ ? renderTargetSize(cam.renderTarget) : null;
+ const w = target?.width ?? width;
+ const h = target?.height ?? height;
+ const px = Math.round(vp.x * w);
+ const py = Math.round((1 - vp.y - vp.h) * h);
+ const pw = Math.round(vp.w * w);
+ const ph = Math.round(vp.h * h);
pipeline.renderCamera({
registry: { _cpp: cppRegistry },
viewProjection: cam.viewProjection,
@@ -698,6 +722,9 @@ export function cameraPlugin(
cameraEntity: cam.entity,
clearColor,
cullingMask: cam.cullingMask,
+ // A released target leaves the handle behind; drawing
+ // to it would draw nowhere, so it falls to the screen.
+ renderTarget: target ? cam.renderTarget : 0,
});
}
pipeline.endScreenCapture();
diff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
index 327b7c24b..70611af59 100644
--- a/sdk/src/ecs/bridge/ptrAccessors.generated.ts
+++ b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
@@ -170,6 +170,7 @@ export interface CameraPtrData {
clearFlags: number;
pixelPerfect: boolean;
cullingMask: number;
+ renderTarget: number;
}
export function fillCamera(
@@ -188,6 +189,7 @@ export function fillCamera(
out.clearFlags = u8[ptr + 48];
out.pixelPerfect = u8[ptr + 49] !== 0;
out.cullingMask = u32[(ptr + 52) >> 2];
+ out.renderTarget = u32[(ptr + 56) >> 2];
}
export function writeCamera(
@@ -206,6 +208,7 @@ export function writeCamera(
u8[ptr + 48] = data.clearFlags;
u8[ptr + 49] = data.pixelPerfect ? 1 : 0;
u32[(ptr + 52) >> 2] = data.cullingMask;
+ u32[(ptr + 56) >> 2] = data.renderTarget;
}
export function createCameraData(): CameraPtrData {
@@ -222,6 +225,7 @@ export function createCameraData(): CameraPtrData {
clearFlags: 0,
pixelPerfect: false,
cullingMask: 0,
+ renderTarget: 0,
};
}
diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.ts
index f12fb5e08..414edf4d0 100644
--- a/sdk/src/ecs/component.generated.ts
+++ b/sdk/src/ecs/component.generated.ts
@@ -15,7 +15,7 @@ import type { Dimension, Padding } from '../wasm/wasm.generated';
* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to
* run on mismatch, because mismatched offsets read the wrong heap bytes.
*/
-export const ABI_LAYOUT_HASH = '43f91684e5f3d3fb';
+export const ABI_LAYOUT_HASH = 'f4ba1e6b5d361dee';
/**
* One asset-valued field of a component: which field, and what kind of
@@ -160,6 +160,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
clearFlags: 3,
pixelPerfect: false,
cullingMask: 4294967295,
+ renderTarget: 0,
},
editorDefaults: {
projectionType: 1,
@@ -182,6 +183,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
clearFlags: { tooltip: "Which buffers to clear before rendering this camera." },
pixelPerfect: { tooltip: "Snap the camera to the pixel grid for crisp pixel-art (Orthographic).", advanced: true, shownWhen: { field: "projectionType", values: [1] } },
cullingMask: { tooltip: "Which sorting layers this camera renders.", bitmask: { source: "sortingLayers" } },
+ renderTarget: { tooltip: "Render into a RenderTexture instead of the screen (0 = screen). Set at run time.", advanced: true },
},
},
Canvas: {
@@ -1112,6 +1114,7 @@ export interface CameraData {
clearFlags: number;
pixelPerfect: boolean;
cullingMask: number;
+ renderTarget: number;
}
export interface CanvasData {
diff --git a/sdk/src/render/renderPipeline.ts b/sdk/src/render/renderPipeline.ts
index 0d663d2f3..855fec86a 100644
--- a/sdk/src/render/renderPipeline.ts
+++ b/sdk/src/render/renderPipeline.ts
@@ -46,6 +46,8 @@ export interface CameraRenderParams {
clearColor?: { x: number; y: number; z: number; w: number };
/** Sorting layers this camera draws (`Camera.cullingMask`); omitted = all. */
cullingMask?: number;
+ /** Offscreen target to draw into; 0 (default) is the screen. */
+ renderTarget?: number;
}
export class RenderPipeline {
@@ -158,7 +160,7 @@ export class RenderPipeline {
Renderer.setViewport(vp.x, vp.y, vp.w, vp.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, 0, clearFlags, params.clearColor, vp);
+ Renderer.begin(viewProjection, params.renderTarget ?? 0, clearFlags, params.clearColor, vp);
// 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);
diff --git a/sdk/src/render/renderTexture.ts b/sdk/src/render/renderTexture.ts
index 2ba490772..a3c0a53c5 100644
--- a/sdk/src/render/renderTexture.ts
+++ b/sdk/src/render/renderTexture.ts
@@ -27,6 +27,18 @@ export interface RenderTextureHandle {
_filter: 'nearest' | 'linear';
}
+/**
+ * Handle → the size of the target behind it. A `Camera.renderTarget` is a bare
+ * handle (a component holds no object), and what decides that camera's
+ * resolution is the target's own size — so the one place that knows it says so.
+ */
+const sizes = new Map<RenderTargetHandle, { width: number; height: number }>();
+
+/** The size of a live render target, or null once it has been released. */
+export function renderTargetSize(handle: RenderTargetHandle): { width: number; height: number } | null {
+ return sizes.get(handle) ?? null;
+}
+
export const RenderTexture = {
create(options: RenderTextureOptions): RenderTextureHandle {
const depth = options.depth ?? true;
@@ -41,6 +53,7 @@ export const RenderTexture = {
? getResourceManager()?.registerExternalTexture(textureId, options.width, options.height) ?? 0
: 0;
+ sizes.set(handle, { width: options.width, height: options.height });
return {
_handle: handle,
textureId,
@@ -54,6 +67,7 @@ export const RenderTexture = {
release(rt: RenderTextureHandle): void {
if (rt.texture !== 0) getResourceManager()?.releaseTexture(rt.texture);
+ sizes.delete(rt._handle);
Renderer.releaseRenderTarget(rt._handle);
},
diff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.ts
index 42a5bd877..4510aa6c9 100644
--- a/sdk/src/wasm/ptrLayouts.generated.ts
+++ b/sdk/src/wasm/ptrLayouts.generated.ts
@@ -79,6 +79,7 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {
{ name: 'clearFlags', type: 'u8', offset: 48 },
{ name: 'pixelPerfect', type: 'bool', offset: 49 },
{ name: 'cullingMask', type: 'u32', offset: 52 },
+ { name: 'renderTarget', type: 'u32', offset: 56 },
],
},
Canvas: {
diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.ts
index 7c070b3cb..aafcfce58 100644
--- a/sdk/src/wasm/wasm.generated.ts
+++ b/sdk/src/wasm/wasm.generated.ts
@@ -263,6 +263,7 @@ export interface Camera {
clearFlags: number;
pixelPerfect: boolean;
cullingMask: number;
+ renderTarget: number;
}
export interface Canvas {
diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
index 081bb1b19..a5f70b776 100644
--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
@@ -109,6 +109,10 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho
],
"tooltip": "Orthographic (2D) or Perspective projection.",
},
+ "renderTarget": {
+ "advanced": true,
+ "tooltip": "Render into a RenderTexture instead of the screen (0 = screen). Set at run time.",
+ },
"showFrustum": {
"advanced": true,
"tooltip": "Draw this camera's whole view volume in the editor, not just what it frames on the content plane.",
diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cpp
index 4ae44dfd8..5728a4ad8 100644
--- a/src/esengine/bindings/EditorAPI.generated.cpp
+++ b/src/esengine/bindings/EditorAPI.generated.cpp
@@ -2,10 +2,10 @@
* @file EditorAPI.generated.cpp
* @brief Auto-generated editor API with string-dispatched component access
* @details Generated by EHT - DO NOT EDIT
- * @schema_hash a430f15de6d510eb
+ * @schema_hash 1bc8702f5edc3115
*/
-#define ES_EDITOR_API_SCHEMA_HASH "a430f15de6d510eb"
+#define ES_EDITOR_API_SCHEMA_HASH "1bc8702f5edc3115"
#include <emscripten/bind.h>
#include <string>
@@ -160,7 +160,8 @@ std::string editor_getComponentSchema(const std::string& name) {
{"key":"viewport.w","type":"float","group":"Camera"},
{"key":"clearFlags","type":"enum","group":"Camera","values":["Nothing","Color","Depth","ColorAndDepth"]},
{"key":"pixelPerfect","type":"bool","group":"Camera"},
- {"key":"cullingMask","type":"int","group":"Camera"}
+ {"key":"cullingMask","type":"int","group":"Camera"},
+ {"key":"renderTarget","type":"int","group":"Camera"}
])JSON";
} else if (name == "Canvas") {
return R"JSON([
@@ -1939,6 +1940,7 @@ bool editor_setInt(Registry& reg, u32 e, const std::string& comp, const std::str
else if (field == "priority") { c.priority = static_cast<i32>(value); }
else if (field == "clearFlags") { c.clearFlags = static_cast<ClearFlags>(value); }
else if (field == "cullingMask") { c.cullingMask = static_cast<u32>(value); }
+ else if (field == "renderTarget") { c.renderTarget = static_cast<u32>(value); }
else { return false; }
return true;
} else if (comp == "Canvas") {
@@ -2168,6 +2170,7 @@ i32 editor_getInt(Registry& reg, u32 e, const std::string& comp, const std::stri
else if (field == "priority") { return static_cast<i32>(c.priority); }
else if (field == "clearFlags") { return static_cast<i32>(c.clearFlags); }
else if (field == "cullingMask") { return static_cast<i32>(c.cullingMask); }
+ else if (field == "renderTarget") { return static_cast<i32>(c.renderTarget); }
} else if (comp == "Canvas") {
if (!reg.has<esengine::ecs::Canvas>(entity)) return 0;
const auto& c = reg.get<esengine::ecs::Canvas>(entity);
diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cpp
index e9f413f8b..127d24acc 100644
--- a/src/esengine/bindings/WebBindings.generated.cpp
+++ b/src/esengine/bindings/WebBindings.generated.cpp
@@ -316,6 +316,7 @@ struct CameraJS {
i32 clearFlags;
bool pixelPerfect;
u32 cullingMask;
+ u32 renderTarget;
};
void cameraApplyJS(esengine::ecs::Camera& c, const CameraJS& js) {
@@ -331,6 +332,7 @@ void cameraApplyJS(esengine::ecs::Camera& c, const CameraJS& js) {
c.clearFlags = static_cast<ClearFlags>(js.clearFlags);
c.pixelPerfect = js.pixelPerfect;
c.cullingMask = js.cullingMask;
+ c.renderTarget = js.renderTarget;
}
esengine::ecs::Camera cameraFromJS(const CameraJS& js) {
@@ -353,6 +355,7 @@ CameraJS cameraToJS(const esengine::ecs::Camera& c) {
js.clearFlags = static_cast<i32>(c.clearFlags);
js.pixelPerfect = c.pixelPerfect;
js.cullingMask = c.cullingMask;
+ js.renderTarget = c.renderTarget;
return js;
}
@@ -1336,7 +1339,8 @@ EMSCRIPTEN_BINDINGS(esengine_components) {
.field("viewport", &CameraJS::viewport)
.field("clearFlags", &CameraJS::clearFlags)
.field("pixelPerfect", &CameraJS::pixelPerfect)
- .field("cullingMask", &CameraJS::cullingMask);
+ .field("cullingMask", &CameraJS::cullingMask)
+ .field("renderTarget", &CameraJS::renderTarget);
value_object<CanvasJS>("Canvas")
.field("designResolution", &CanvasJS::designResolution)
@@ -2741,6 +2745,7 @@ static_assert(offsetof(esengine::ecs::Camera, viewport) == 32, "ABI offset drift
static_assert(offsetof(esengine::ecs::Camera, clearFlags) == 48, "ABI offset drift: esengine::ecs::Camera.clearFlags (EHT expected 48)");
static_assert(offsetof(esengine::ecs::Camera, pixelPerfect) == 49, "ABI offset drift: esengine::ecs::Camera.pixelPerfect (EHT expected 49)");
static_assert(offsetof(esengine::ecs::Camera, cullingMask) == 52, "ABI offset drift: esengine::ecs::Camera.cullingMask (EHT expected 52)");
+static_assert(offsetof(esengine::ecs::Camera, renderTarget) == 56, "ABI offset drift: esengine::ecs::Camera.renderTarget (EHT expected 56)");
static_assert(offsetof(esengine::ecs::Canvas, designResolution) == 0, "ABI offset drift: esengine::ecs::Canvas.designResolution (EHT expected 0)");
static_assert(offsetof(esengine::ecs::Canvas, pixelsPerUnit) == 8, "ABI offset drift: esengine::ecs::Canvas.pixelsPerUnit (EHT expected 8)");
static_assert(offsetof(esengine::ecs::Canvas, scaleMode) == 12, "ABI offset drift: esengine::ecs::Canvas.scaleMode (EHT expected 12)");
@@ -3065,7 +3070,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif
// ABI Hash -- runtime handshake against the SDK bundle
// =============================================================================
-static const char* kEsAbiLayoutHash = "43f91684e5f3d3fb";
+static const char* kEsAbiLayoutHash = "f4ba1e6b5d361dee";
std::string esengineGetAbiLayoutHash() {
return std::string(kEsAbiLayoutHash);
diff --git a/src/esengine/ecs/components/Camera.hpp b/src/esengine/ecs/components/Camera.hpp
index 68561cfbe..fb036c0bb 100644
--- a/src/esengine/ecs/components/Camera.hpp
+++ b/src/esengine/ecs/components/Camera.hpp
@@ -121,6 +121,13 @@ struct Camera {
ES_PROPERTY(bitmask_source=sortingLayers, tooltip="Which sorting layers this camera renders.")
u32 cullingMask{0xFFFFFFFFu};
+ /** @brief Offscreen target this camera draws into; 0 = the screen. A RenderTexture
+ * handle, so it is created at run time and set from a script — a minimap,
+ * a mirror, a portrait rendered once. The camera's viewport covers the
+ * whole target, whose own size decides the resolution. */
+ ES_PROPERTY(advanced, tooltip="Render into a RenderTexture instead of the screen (0 = screen). Set at run time.")
+ u32 renderTarget{0};
+
Camera() = default;
};
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.cpp b/src/esengine/renderer/webgpu/WebGPUDevice.cpp
index 9656ec850..8e4d4ca9f 100644
--- a/src/esengine/renderer/webgpu/WebGPUDevice.cpp
+++ b/src/esengine/renderer/webgpu/WebGPUDevice.cpp
@@ -48,6 +48,7 @@ u32 colorVariantOf(WGPUTextureFormat format) {
switch (format) {
case WGPUTextureFormat_RGBA8UnormSrgb: return WebGPUDevice::kColorSrgb8;
case WGPUTextureFormat_RGBA16Float: return WebGPUDevice::kColorRgba16f;
+ case WGPUTextureFormat_BGRA8Unorm: return WebGPUDevice::kColorBgra8;
default: return WebGPUDevice::kColorRgba8;
}
}
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.hpp b/src/esengine/renderer/webgpu/WebGPUDevice.hpp
index 2792d9bfc..ae48d2562 100644
--- a/src/esengine/renderer/webgpu/WebGPUDevice.hpp
+++ b/src/esengine/renderer/webgpu/WebGPUDevice.hpp
@@ -49,8 +49,13 @@ public:
enum DsVariant : u32 { kDsNone = 0, kDsDepthOnly = 1, kDsDepthStencil = 2, kDsVariantCount = 3 };
/** @brief Color attachment format of a pass — like DsVariant, WebGPU
- * validates the pipeline's color target format against the pass. */
- enum ColorVariant : u32 { kColorRgba8 = 0, kColorSrgb8 = 1, kColorRgba16f = 2, kColorVariantCount = 3 };
+ * validates the pipeline's color target format against the pass, and
+ * BGRA is a DIFFERENT format from RGBA to that check even though both
+ * are 8-bit unorm: a surface is usually the former, a render target
+ * the latter, so they cannot share a slot. */
+ enum ColorVariant : u32 {
+ kColorRgba8 = 0, kColorBgra8 = 1, kColorSrgb8 = 2, kColorRgba16f = 3, kColorVariantCount = 4,
+ };
/** @brief @p device may be null for bookkeeping-only use (tests, bring-up).
* @param instance The host's WGPUInstance to share. Web/emscripten passes
diff --git a/tools/render-host/host.ts b/tools/render-host/host.ts
index f817b7100..24e1b136b 100644
--- a/tools/render-host/host.ts
+++ b/tools/render-host/host.ts
@@ -19,6 +19,7 @@ import {
loadSceneData, Renderer, instantiatePrefab, writeFieldPath, Transform, Name,
getComponent, DeviceStatus, getDeviceStatus, getDeviceLostReport, recoverDevice,
finishDeviceRecovery, getContextLossGuardInfo, decodeImagePixels, captureFramePixels,
+ RenderTexture, Camera, Sprite,
} from 'esengine';
import type { App, SceneData, PrefabData, RenderSurfaceSource } from 'esengine';
import type { ESEngineModule } from 'esengine/wasm';
@@ -490,6 +491,35 @@ window.__estellaHeadless = {
if (!mesh?.handle) return 0;
return m.meshRenderer_setMeshAll(registry, mesh.handle);
},
+ /**
+ * Point a camera at an offscreen target and show that target on a sprite.
+ * The whole claim in one hop: what the first camera drew has to arrive as the
+ * second camera's texture, so the probe reads a colour that only exists
+ * because a camera rendered somewhere other than the screen.
+ */
+ renderToTexture: (spec: { camera: number; sprite: number; width: number; height: number }) => {
+ if (!app) return null;
+ // By the order the scene lists them: a loaded entity's handle carries a
+ // generation, so the ids in a scene file are not the World's.
+ const loaded = [...app.world.getAllEntities()];
+ const camEntity = loaded[spec.camera];
+ const spriteEntity = loaded[spec.sprite];
+ if (camEntity === undefined || spriteEntity === undefined) return { error: 'entity index out of range' };
+
+ const rt = RenderTexture.create({ width: spec.width, height: spec.height, depth: true });
+ const cam = app.world.get(camEntity, Camera) as { renderTarget: number };
+ cam.renderTarget = rt._handle;
+ app.world.insert(camEntity, Camera, cam as never);
+ const sprite = app.world.get(spriteEntity, Sprite) as { texture: number };
+ sprite.texture = rt.texture;
+ app.world.insert(spriteEntity, Sprite, sprite as never);
+ return {
+ target: rt._handle,
+ texture: rt.texture,
+ appliedTarget: (app.world.get(camEntity, Camera) as { renderTarget: number }).renderTarget,
+ appliedTexture: (app.world.get(spriteEntity, Sprite) as { texture: number }).texture,
+ };
+ },
loadMaterialAsset: async (path: string) => {
const assets = app?.getResource(Assets);
const m = module as unknown as { meshRenderer_setMaterialAll?(registry: unknown, id: number): number } | null;
diff --git a/tools/render-host/run.mjs b/tools/render-host/run.mjs
index 2e8cdb1dd..ec14ba209 100644
--- a/tools/render-host/run.mjs
+++ b/tools/render-host/run.mjs
@@ -183,6 +183,7 @@ app.whenReady().then(async () => {
let deviceLoss = null;
let meshResident = null;
let meshAsset = null;
+ let cameraTarget = null;
let meshMaterial = null;
let meshPrefab = null;
let setField = null;
@@ -282,6 +283,18 @@ app.whenReady().then(async () => {
})()`);
}
+ // ESTELLA_VERIFY_CAMERA_TARGET={"camera","sprite","width","height"}: point a
+ // camera at an offscreen texture and show that texture on a sprite. Nothing
+ // else can produce the probe's colour, so it says the camera drew there.
+ if (process.env.ESTELLA_VERIFY_CAMERA_TARGET) {
+ const spec = JSON.parse(process.env.ESTELLA_VERIFY_CAMERA_TARGET);
+ cameraTarget = await exec(`(async () => {
+ const out = window.__estellaHeadless.renderToTexture(${JSON.stringify(spec)});
+ await window.__estellaHeadless.api.step(3, 1 / 60);
+ return out;
+ })()`);
+ }
+
// ESTELLA_VERIFY_SET_FIELD={"entity","component","key","value"} writes one
// inspector field the way the editor's own door does, then waits: an asset
// assigned after load is COLD, and reaching the World is an async load away.
@@ -634,7 +647,7 @@ app.whenReady().then(async () => {
};
`);
}
- finish({ ok: true, entityCount, drawCalls, draws, capture, expect, resize, preview, meshPreview, grid, deviceLoss, meshResident, meshAsset, meshMaterial, meshPrefab, setField, pick }, server);
+ finish({ ok: true, entityCount, drawCalls, draws, capture, expect, resize, preview, meshPreview, grid, deviceLoss, meshResident, meshAsset, meshMaterial, meshPrefab, setField, pick, cameraTarget }, server);
} catch (e) {
finish({ ok: false, error: String((e && e.stack) || e) }, server);
}
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index bd6bc5a76..ec3fd4362 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -256,6 +256,10 @@ export const SCENES = [
// and just outside it, so a box that collapsed or grew is caught without
// asking a glyph to land on a given pixel.
{ id: "ui-text-box", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/ui-text-uinode.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/ui-text-uinode.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.36,\"y\":0.36,\"rgb\":[46,51,71],\"tol\":20},{\"x\":0.64,\"y\":0.36,\"rgb\":[46,51,71],\"tol\":20},{\"x\":0.5,\"y\":0.7,\"rgb\":[0,0,0],\"tol\":15}]" } },
+ // Red at the centre exists only if a camera rendered into a texture: the fill
+ // sits on a layer the screen camera culls, and the screen sprite wears that
+ // target. webgl2 only — WebGPU has no importExternalTexture yet.
+ { id: "camera-render-target", tier: "pr", env: { ESTELLA_VERIFY_SCENE: "/scenes/camera-target.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/camera-target.textures.json", ESTELLA_VERIFY_CAMERA_TARGET: "{\"camera\":0,\"sprite\":3,\"width\":128,\"height\":128}", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[255,0,0],\"tol\":40}]" } },
{ id: "material-lit", tier: "nightly", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-lit.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mat-lit.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":50}]" } },
{ id: "material-lit-point", tier: "pr", webgpu: { ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,253,0],\"tol\":25},{\"x\":0.75,\"y\":0.5,\"rgb\":[0,52,0],\"tol\":25}]" }, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-lit-point.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mat-lit-point.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":50},{\"x\":0.75,\"y\":0.5,\"rgb\":[0,64,0],\"tol\":60}]" } },
{ id: "material-lit-normal", tier: "nightly", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-lit-normal.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mat-lit-normal.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.333,\"y\":0.5,\"rgb\":[0,252,0],\"tol\":45},{\"x\":0.667,\"y\":0.5,\"rgb\":[0,36,0],\"tol\":50}]" } },