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.

perf(renderer): own transform gizmos in the scene pass

yhhcf8b9c63420d
diff --git a/desktop b/desktop
index 929c93f33..fbff609d6 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 929c93f3322a1d1b2e4bddb9b367eb3920f65c13
+Subproject commit fbff609d6e51f26a47d470a50aad07a2e7a48c79
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 7ab2cddac..d98ff019d 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 113,
"beta": 99,
- "experimental": 1824,
+ "experimental": 1825,
"deprecated": 3
},
- "total": 2036,
+ "total": 2037,
"subsystems": [
{
"id": "ecs",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 97c9c5b2f..52447b49f 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 · 92 beta · 1663 experimental · 3 deprecated
+Symbols: 113 public · 92 beta · 1664 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -2953,6 +2953,7 @@ getDrawCallCount: () => number
getPrimitiveCount: () => number
line3D: (from: Vec3, to: Vec3, color: Color, thickness?: number) => void
line3DScreen: (from: Vec3, to: Vec3, color: Color, thickness?: number) => void
+line3DScreenOffset: (anchor: Vec3, fromOffset: Vec2, toOffset: Vec2, color: Color, thickness?: number) => void
line: (from: Vec2, to: Vec2, color: Color, thickness?: number) => void
rect: (position: Vec2, size: Vec2, color: Color, filled?: boolean) => void
rectOutline: (position: Vec2, size: Vec2, color: Color, thickness?: number) => void
@@ -2994,7 +2995,14 @@ vertexCount: number
## DrawCallback — type @experimental
```
-(elapsed: number) => void
+(elapsed: number, frame: DrawFrameInfo) => void
+```
+
+## DrawFrameInfo — interface @experimental
+```
+height: number
+viewProjection: Float32Array<ArrayBufferLike>
+width: number
```
## DrawRank — interface @experimental
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 2f0e7d668..b7f6131f1 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 · 97 beta · 1682 experimental · 3 deprecated
+Symbols: 113 public · 97 beta · 1683 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -2961,6 +2961,7 @@ getDrawCallCount: () => number
getPrimitiveCount: () => number
line3D: (from: Vec3, to: Vec3, color: Color, thickness?: number) => void
line3DScreen: (from: Vec3, to: Vec3, color: Color, thickness?: number) => void
+line3DScreenOffset: (anchor: Vec3, fromOffset: Vec2, toOffset: Vec2, color: Color, thickness?: number) => void
line: (from: Vec2, to: Vec2, color: Color, thickness?: number) => void
rect: (position: Vec2, size: Vec2, color: Color, filled?: boolean) => void
rectOutline: (position: Vec2, size: Vec2, color: Color, thickness?: number) => void
@@ -3002,7 +3003,14 @@ vertexCount: number
## DrawCallback — type @experimental
```
-(elapsed: number) => void
+(elapsed: number, frame: DrawFrameInfo) => void
+```
+
+## DrawFrameInfo — interface @experimental
+```
+height: number
+viewProjection: Float32Array<ArrayBufferLike>
+width: number
```
## DrawRank — interface @experimental
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index d12d7ea22..070792ddc 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 · 94 beta · 1662 experimental · 3 deprecated
+Symbols: 113 public · 94 beta · 1663 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -2948,6 +2948,7 @@ getDrawCallCount: () => number
getPrimitiveCount: () => number
line3D: (from: Vec3, to: Vec3, color: Color, thickness?: number) => void
line3DScreen: (from: Vec3, to: Vec3, color: Color, thickness?: number) => void
+line3DScreenOffset: (anchor: Vec3, fromOffset: Vec2, toOffset: Vec2, color: Color, thickness?: number) => void
line: (from: Vec2, to: Vec2, color: Color, thickness?: number) => void
rect: (position: Vec2, size: Vec2, color: Color, filled?: boolean) => void
rectOutline: (position: Vec2, size: Vec2, color: Color, thickness?: number) => void
@@ -2989,7 +2990,14 @@ vertexCount: number
## DrawCallback — type @experimental
```
-(elapsed: number) => void
+(elapsed: number, frame: DrawFrameInfo) => void
+```
+
+## DrawFrameInfo — interface @experimental
+```
+height: number
+viewProjection: Float32Array<ArrayBufferLike>
+width: number
```
## DrawRank — interface @experimental
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 62a61c9dc..f7987d29a 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 · 92 beta · 1684 experimental · 3 deprecated
+Symbols: 113 public · 92 beta · 1685 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -2948,6 +2948,7 @@ getDrawCallCount: () => number
getPrimitiveCount: () => number
line3D: (from: Vec3, to: Vec3, color: Color, thickness?: number) => void
line3DScreen: (from: Vec3, to: Vec3, color: Color, thickness?: number) => void
+line3DScreenOffset: (anchor: Vec3, fromOffset: Vec2, toOffset: Vec2, color: Color, thickness?: number) => void
line: (from: Vec2, to: Vec2, color: Color, thickness?: number) => void
rect: (position: Vec2, size: Vec2, color: Color, filled?: boolean) => void
rectOutline: (position: Vec2, size: Vec2, color: Color, thickness?: number) => void
@@ -2989,7 +2990,14 @@ vertexCount: number
## DrawCallback — type @experimental
```
-(elapsed: number) => void
+(elapsed: number, frame: DrawFrameInfo) => void
+```
+
+## DrawFrameInfo — interface @experimental
+```
+height: number
+viewProjection: Float32Array<ArrayBufferLike>
+width: number
```
## DrawRank — interface @experimental
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 98a1b53ea..24b09ba15 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -247,11 +247,13 @@ deviceStatus: (() => number) | undefined
draw_begin: (matrixPtr: number, viewportWidth: number, viewportHeight: number) => void
draw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => void
draw_circleOutline: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, thickness: number, segments: number) => void
+draw_deferEnd: () => void
draw_end: () => void
draw_getDrawCallCount: () => number
draw_getPrimitiveCount: () => number
draw_line3D: (fromX: number, fromY: number, fromZ: number, toX: number, toY: number, toZ: number, r: number, g: number, b: number, a: number, thickness: number) => void
draw_line3DScreen: (fromX: number, fromY: number, fromZ: number, toX: number, toY: number, toZ: number, r: number, g: number, b: number, a: number, thickness: number) => void
+draw_line3DScreenOffset: (anchorX: number, anchorY: number, anchorZ: number, fromX: number, fromY: number, toX: number, toY: number, r: number, g: number, b: number, a: number, thickness: number) => void
draw_line: (fromX: number, fromY: number, toX: number, toY: number, r: number, g: number, b: number, a: number, thickness: number) => void
draw_mesh: (geometryHandle: number, shaderHandle: number, transformPtr: number) => void
draw_meshWithMaterial: (geometryHandle: number, materialId: number) => boolean
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index b36b4136f..1d3bec1a0 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 · 92 beta · 1674 experimental · 3 deprecated
+Symbols: 113 public · 92 beta · 1675 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -2948,6 +2948,7 @@ getDrawCallCount: () => number
getPrimitiveCount: () => number
line3D: (from: Vec3, to: Vec3, color: Color, thickness?: number) => void
line3DScreen: (from: Vec3, to: Vec3, color: Color, thickness?: number) => void
+line3DScreenOffset: (anchor: Vec3, fromOffset: Vec2, toOffset: Vec2, color: Color, thickness?: number) => void
line: (from: Vec2, to: Vec2, color: Color, thickness?: number) => void
rect: (position: Vec2, size: Vec2, color: Color, filled?: boolean) => void
rectOutline: (position: Vec2, size: Vec2, color: Color, thickness?: number) => void
@@ -2989,7 +2990,14 @@ vertexCount: number
## DrawCallback — type @experimental
```
-(elapsed: number) => void
+(elapsed: number, frame: DrawFrameInfo) => void
+```
+
+## DrawFrameInfo — interface @experimental
+```
+height: number
+viewProjection: Float32Array<ArrayBufferLike>
+width: number
```
## DrawRank — interface @experimental
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index 9c6927145..7e9e3b28d 100644
--- a/sdk/src/core-render.ts
+++ b/sdk/src/core-render.ts
@@ -277,6 +277,7 @@ export {
unregisterDrawCallback,
clearDrawCallbacks,
type DrawCallback,
+ type DrawFrameInfo,
registerPreSceneDrawCallback,
unregisterPreSceneDrawCallback,
type PreSceneDrawCallback,
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index 562a27ead..3a994f3e7 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -26,12 +26,14 @@ export interface NativeEngineApi {
draw_begin?(matrixPtr: number, viewportWidth: number, viewportHeight: number): void;
draw_circle?(centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number): void;
draw_circleOutline?(centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, thickness: number, segments: number): void;
+ draw_deferEnd?(): void;
draw_end?(): void;
draw_getDrawCallCount?(): number;
draw_getPrimitiveCount?(): number;
draw_line?(fromX: number, fromY: number, toX: number, toY: number, r: number, g: number, b: number, a: number, thickness: number): void;
draw_line3D?(fromX: number, fromY: number, fromZ: number, toX: number, toY: number, toZ: number, r: number, g: number, b: number, a: number, thickness: number): void;
draw_line3DScreen?(fromX: number, fromY: number, fromZ: number, toX: number, toY: number, toZ: number, r: number, g: number, b: number, a: number, thickness: number): void;
+ draw_line3DScreenOffset?(anchorX: number, anchorY: number, anchorZ: number, fromX: number, fromY: number, toX: number, toY: number, r: number, g: number, b: number, a: number, thickness: number): void;
draw_mesh?(geometryHandle: number, shaderHandle: number, transformPtr: number): void;
draw_meshWithMaterial?(geometryHandle: number, materialId: number): boolean;
draw_meshWithUniforms?(geometryHandle: number, shaderHandle: number, transformPtr: number, uniformsPtr: number, uniformCount: number): void;
@@ -288,12 +290,14 @@ export function createNativeEngineApi(
bind('draw_begin', 'es_draw_begin', false);
bind('draw_circle', 'es_draw_circle', false);
bind('draw_circleOutline', 'es_draw_circleOutline', false);
+ bind('draw_deferEnd', 'es_draw_deferEnd', false);
bind('draw_end', 'es_draw_end', false);
bind('draw_getDrawCallCount', 'es_draw_getDrawCallCount', false);
bind('draw_getPrimitiveCount', 'es_draw_getPrimitiveCount', false);
bind('draw_line', 'es_draw_line', false);
bind('draw_line3D', 'es_draw_line3D', false);
bind('draw_line3DScreen', 'es_draw_line3DScreen', false);
+ bind('draw_line3DScreenOffset', 'es_draw_line3DScreenOffset', false);
bind('draw_mesh', 'es_draw_mesh', false);
bind('draw_meshWithMaterial', 'es_draw_meshWithMaterial', false);
bind('draw_meshWithUniforms', 'es_draw_meshWithUniforms', false);
diff --git a/sdk/src/render/customDraw.ts b/sdk/src/render/customDraw.ts
index 745030013..322b42601 100644
--- a/sdk/src/render/customDraw.ts
+++ b/sdk/src/render/customDraw.ts
@@ -5,7 +5,16 @@
* @brief Custom draw callback registration for the render pipeline
*/
-export type DrawCallback = (elapsed: number) => void;
+/** The camera facts used by the draw pass invoking a callback. */
+export interface DrawFrameInfo {
+ /** Canonical view-projection matrix for this render pass. Valid for the callback. */
+ readonly viewProjection: Float32Array;
+ /** Framebuffer viewport dimensions used by Draw.begin. */
+ readonly width: number;
+ readonly height: number;
+}
+
+export type DrawCallback = (elapsed: number, frame: DrawFrameInfo) => void;
const callbacks = new Map<string, { fn: DrawCallback; scene: string }>();
diff --git a/sdk/src/render/draw.ts b/sdk/src/render/draw.ts
index f857a03e7..c9de3c296 100644
--- a/sdk/src/render/draw.ts
+++ b/sdk/src/render/draw.ts
@@ -76,6 +76,15 @@ export function shutdownDrawAPI(): void {
module = null;
}
+/** @internal Close custom overlay collection for the owning renderer pass. */
+export function endPresentedDraw(): void {
+ try {
+ getModule().draw_deferEnd();
+ } catch (e) {
+ handleWasmError(e, 'Draw.endPresented');
+ }
+}
+
// =============================================================================
// Draw API Interface
// =============================================================================
@@ -119,6 +128,10 @@ export interface DrawAPI {
*/
line3DScreen(from: Vec3, to: Vec3, color: Color, thickness?: number): void;
+ /** Draws a framebuffer-sized line at one world anchor. Offsets are pixels, +Y up. */
+ line3DScreenOffset(anchor: Vec3, fromOffset: Vec2, toOffset: Vec2,
+ color: Color, thickness?: number): void;
+
/**
* Draws a filled or outlined rectangle.
* @param position Center position
@@ -306,6 +319,20 @@ export const Draw: DrawAPI = {
}
},
+ line3DScreenOffset(anchor: Vec3, fromOffset: Vec2, toOffset: Vec2,
+ color: Color, thickness = 1): void {
+ try {
+ getModule().draw_line3DScreenOffset(
+ anchor.x, anchor.y, anchor.z,
+ fromOffset.x, fromOffset.y, toOffset.x, toOffset.y,
+ color.r, color.g, color.b, color.a,
+ thickness,
+ );
+ } catch (e) {
+ handleWasmError(e, 'Draw.line3DScreenOffset');
+ }
+ },
+
rect(position: Vec2, size: Vec2, color: Color, filled = true): void {
try {
getModule().draw_rect(
diff --git a/sdk/src/render/renderPipeline.ts b/sdk/src/render/renderPipeline.ts
index ff22c063a..67659584f 100644
--- a/sdk/src/render/renderPipeline.ts
+++ b/sdk/src/render/renderPipeline.ts
@@ -10,7 +10,7 @@ import type { Entity } from '../types';
import { Renderer } from './renderer';
import type { PostProcessAPI } from '../postprocess';
import type { ScreenOverlayData } from '../ui/core/screen-overlay';
-import { Draw, isDrawAPIReady } from './draw';
+import { Draw, endPresentedDraw, isDrawAPIReady } from './draw';
import {
getDrawCallbacks,
unregisterDrawCallback,
@@ -292,13 +292,17 @@ export class RenderPipeline {
for (const [id, entry] of cbs.entries()) {
if (entry.scene && this.activeScenes_ && !this.activeScenes_.has(entry.scene)) continue;
try {
- entry.fn(elapsed);
+ entry.fn(elapsed, {
+ viewProjection,
+ width: viewport.w,
+ height: viewport.h,
+ });
} catch (e) {
log.error('render', `callback '${id}' error`, e);
failed.push(id);
}
}
- Draw.end();
+ endPresentedDraw();
for (const id of failed) {
unregisterDrawCallback(id);
}
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 39b9a1ff1..148a63d1b 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -406,6 +406,7 @@ export interface ESEngineModule {
// ImmediateDraw API
draw_begin(matrixPtr: number, viewportWidth: number, viewportHeight: number): void;
draw_end(): void;
+ draw_deferEnd(): void;
draw_line(fromX: number, fromY: number, toX: number, toY: number,
r: number, g: number, b: number, a: number, thickness: number): void;
draw_line3D(fromX: number, fromY: number, fromZ: number,
@@ -414,6 +415,9 @@ export interface ESEngineModule {
draw_line3DScreen(fromX: number, fromY: number, fromZ: number,
toX: number, toY: number, toZ: number,
r: number, g: number, b: number, a: number, thickness: number): void;
+ draw_line3DScreenOffset(anchorX: number, anchorY: number, anchorZ: number,
+ fromX: number, fromY: number, toX: number, toY: number,
+ r: number, g: number, b: number, a: number, thickness: number): void;
draw_rect(x: number, y: number, width: number, height: number,
r: number, g: number, b: number, a: number, filled: boolean): void;
draw_rectOutline(x: number, y: number, width: number, height: number,
diff --git a/sdk/tests/draw.test.ts b/sdk/tests/draw.test.ts
index 1da2a1c56..cc1dced81 100644
--- a/sdk/tests/draw.test.ts
+++ b/sdk/tests/draw.test.ts
@@ -27,7 +27,7 @@ vi.mock('../src/render/material', () => {
});
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { Draw, initDrawAPI, shutdownDrawAPI, BlendMode } from '../src/render/draw';
+import { Draw, initDrawAPI, shutdownDrawAPI, endPresentedDraw, BlendMode } from '../src/render/draw';
import { Material, isTextureRef } from '../src/render/material';
import type { ESEngineModule } from '../src/wasm';
@@ -50,9 +50,11 @@ function createDrawMockModule() {
draw_begin: vi.fn(),
draw_end: vi.fn(),
+ draw_deferEnd: vi.fn(),
draw_line: vi.fn(),
draw_line3D: vi.fn(),
draw_line3DScreen: vi.fn(),
+ draw_line3DScreenOffset: vi.fn(),
draw_rect: vi.fn(),
draw_rectOutline: vi.fn(),
draw_circle: vi.fn(),
@@ -202,6 +204,14 @@ describe('Draw API', () => {
});
});
+ describe('endPresentedDraw', () => {
+ it('defers submission to the owning renderer pass', () => {
+ endPresentedDraw();
+ expect(mock.draw_deferEnd).toHaveBeenCalledOnce();
+ expect(mock.draw_end).not.toHaveBeenCalled();
+ });
+ });
+
describe('Draw.line3DScreen', () => {
it('passes world endpoints and pixel thickness to the native primitive', () => {
Draw.line3DScreen(
@@ -214,6 +224,18 @@ describe('Draw API', () => {
});
});
+ describe('Draw.line3DScreenOffset', () => {
+ it('passes one world anchor and framebuffer offsets to the native primitive', () => {
+ Draw.line3DScreenOffset(
+ { x: 1, y: 2, z: 3 }, { x: -4, y: 5 }, { x: 6, y: -7 },
+ { r: 0.1, g: 0.2, b: 0.3, a: 0.4 }, 2,
+ );
+ expect(mock.draw_line3DScreenOffset).toHaveBeenCalledWith(
+ 1, 2, 3, -4, 5, 6, -7, 0.1, 0.2, 0.3, 0.4, 2,
+ );
+ });
+ });
+
// =========================================================================
// Draw.rect
// =========================================================================
diff --git a/sdk/tests/renderPipeline.test.ts b/sdk/tests/renderPipeline.test.ts
index 0385e89d9..da98f779a 100644
--- a/sdk/tests/renderPipeline.test.ts
+++ b/sdk/tests/renderPipeline.test.ts
@@ -51,12 +51,16 @@ vi.mock('../src/render/draw', () => ({
begin: vi.fn(),
end: vi.fn(),
},
+ endPresentedDraw: vi.fn(),
// These cases are about a core that HAS a Draw API; the one that has not is
// covered where the skip lives (nav-debug-draw).
isDrawAPIReady: () => true,
}));
-const mockCallbacks = new Map<string, { fn: (elapsed: number) => void; scene: string }>();
+const mockCallbacks = new Map<string, {
+ fn: (elapsed: number, frame: { viewProjection: Float32Array; width: number; height: number }) => void;
+ scene: string;
+}>();
const mockPreSceneCallbacks = new Map<string, (info: unknown) => void>();
vi.mock('../src/render/customDraw', () => ({
getDrawCallbacks: vi.fn(() => mockCallbacks),
@@ -68,7 +72,7 @@ vi.mock('../src/render/customDraw', () => ({
import { RenderPipeline } from '../src/render/renderPipeline';
import { Renderer } from '../src/render/renderer';
import { PostProcess } from '../src/postprocess';
-import { Draw } from '../src/render/draw';
+import { Draw, endPresentedDraw } from '../src/render/draw';
import { unregisterDrawCallback } from '../src/render/customDraw';
describe('RenderPipeline', () => {
@@ -164,33 +168,45 @@ describe('RenderPipeline', () => {
});
describe('custom draw callbacks', () => {
- it('does not call Draw.begin/end when no callbacks', () => {
+ it('does not open or close a presented draw when no callbacks', () => {
pipeline.render({ registry, viewProjection, width: 800, height: 600, elapsed: 0 });
expect(Draw.begin).not.toHaveBeenCalled();
- expect(Draw.end).not.toHaveBeenCalled();
+ expect(endPresentedDraw).not.toHaveBeenCalled();
});
- it('calls Draw.begin/end and callback when callbacks exist', () => {
+ it('collects a presented draw around callbacks', () => {
const cb = vi.fn();
mockCallbacks.set('test-cb', { fn: cb, scene: '' });
pipeline.render({ registry, viewProjection, width: 800, height: 600, elapsed: 16 });
expect(Draw.begin).toHaveBeenCalledWith(viewProjection, 800, 600);
- expect(cb).toHaveBeenCalledWith(16);
- expect(Draw.end).toHaveBeenCalled();
+ expect(cb).toHaveBeenCalledWith(16, { viewProjection, width: 800, height: 600 });
+ expect(endPresentedDraw).toHaveBeenCalled();
});
- it('calls callbacks in correct order within Draw.begin/end', () => {
+ it('hands callbacks the exact draw-frame camera facts', () => {
+ const cb = vi.fn();
+ mockCallbacks.set('test-cb', { fn: cb, scene: '' });
+
+ pipeline.render({ registry, viewProjection, width: 800, height: 600, elapsed: 7 });
+
+ const [, frame] = cb.mock.calls[0]!;
+ expect(frame.viewProjection).toBe(viewProjection);
+ expect(frame).toEqual({ viewProjection, width: 800, height: 600 });
+ });
+
+ it('calls callbacks in order before closing the presented draw', () => {
const callOrder: string[] = [];
(Draw.begin as ReturnType<typeof vi.fn>).mockImplementation(() => callOrder.push('Draw.begin'));
- (Draw.end as ReturnType<typeof vi.fn>).mockImplementation(() => callOrder.push('Draw.end'));
+ (endPresentedDraw as ReturnType<typeof vi.fn>)
+ .mockImplementation(() => callOrder.push('endPresentedDraw'));
mockCallbacks.set('cb1', { fn: () => callOrder.push('cb1'), scene: '' });
mockCallbacks.set('cb2', { fn: () => callOrder.push('cb2'), scene: '' });
pipeline.render({ registry, viewProjection, width: 800, height: 600, elapsed: 0 });
- expect(callOrder).toEqual(['Draw.begin', 'cb1', 'cb2', 'Draw.end']);
+ expect(callOrder).toEqual(['Draw.begin', 'cb1', 'cb2', 'endPresentedDraw']);
});
it('filters callbacks by activeScenes', () => {
@@ -221,13 +237,13 @@ describe('RenderPipeline', () => {
errorSpy.mockRestore();
});
- it('still calls Draw.end even when callback throws', () => {
+ it('still closes the presented draw when a callback throws', () => {
vi.spyOn(console, 'error').mockImplementation(() => {});
mockCallbacks.set('bad-cb', { fn: () => { throw new Error('fail'); }, scene: '' });
pipeline.render({ registry, viewProjection, width: 800, height: 600, elapsed: 0 });
- expect(Draw.end).toHaveBeenCalled();
+ expect(endPresentedDraw).toHaveBeenCalled();
vi.restoreAllMocks();
});
});
@@ -258,8 +274,8 @@ describe('RenderPipeline', () => {
pipeline.renderCamera({ registry, viewProjection, viewportPixels, clearFlags: 3, elapsed: 16 });
expect(Draw.begin).toHaveBeenCalledWith(viewProjection, 400, 300);
- expect(cb).toHaveBeenCalledWith(16);
- expect(Draw.end).toHaveBeenCalled();
+ expect(cb).toHaveBeenCalledWith(16, { viewProjection, width: 400, height: 300 });
+ expect(endPresentedDraw).toHaveBeenCalled();
});
});
diff --git a/src/esengine/bindings/ImmediateDrawBindings.cpp b/src/esengine/bindings/ImmediateDrawBindings.cpp
index 1a29262bc..39708919a 100644
--- a/src/esengine/bindings/ImmediateDrawBindings.cpp
+++ b/src/esengine/bindings/ImmediateDrawBindings.cpp
@@ -56,6 +56,13 @@ void draw_end() {
ctx().state().immediate_draw_active = false;
}
+void draw_deferEnd() {
+ if (!g_initialized || !g_immediateDraw || !g_immediateDrawActive) return;
+
+ g_immediateDraw->deferEnd();
+ ctx().state().immediate_draw_active = false;
+}
+
void draw_line(f32 fromX, f32 fromY, f32 toX, f32 toY,
f32 r, f32 g, f32 b, f32 a, f32 thickness) {
if (!g_immediateDraw || !g_immediateDrawActive) return;
@@ -92,6 +99,20 @@ void draw_line3DScreen(f32 fromX, f32 fromY, f32 fromZ, f32 toX, f32 toY, f32 to
);
}
+void draw_line3DScreenOffset(f32 anchorX, f32 anchorY, f32 anchorZ,
+ f32 fromX, f32 fromY, f32 toX, f32 toY,
+ f32 r, f32 g, f32 b, f32 a, f32 thickness) {
+ if (!g_immediateDraw || !g_immediateDrawActive) return;
+
+ g_immediateDraw->line3DScreenOffset(
+ glm::vec3(anchorX, anchorY, anchorZ),
+ glm::vec2(fromX, fromY),
+ glm::vec2(toX, toY),
+ glm::vec4(r, g, b, a),
+ thickness
+ );
+}
+
void draw_rect(f32 x, f32 y, f32 width, f32 height,
f32 r, f32 g, f32 b, f32 a, bool filled) {
if (!g_immediateDraw || !g_immediateDrawActive) return;
diff --git a/src/esengine/bindings/ImmediateDrawBindings.hpp b/src/esengine/bindings/ImmediateDrawBindings.hpp
index c645a7a67..59be56b80 100644
--- a/src/esengine/bindings/ImmediateDrawBindings.hpp
+++ b/src/esengine/bindings/ImmediateDrawBindings.hpp
@@ -9,12 +9,16 @@ namespace esengine {
void draw_begin(uintptr_t matrixPtr, i32 viewportWidth, i32 viewportHeight);
void draw_end();
+void draw_deferEnd();
void draw_line(f32 fromX, f32 fromY, f32 toX, f32 toY,
f32 r, f32 g, f32 b, f32 a, f32 thickness);
void draw_line3D(f32 fromX, f32 fromY, f32 fromZ, f32 toX, f32 toY, f32 toZ,
f32 r, f32 g, f32 b, f32 a, f32 thickness);
void draw_line3DScreen(f32 fromX, f32 fromY, f32 fromZ, f32 toX, f32 toY, f32 toZ,
f32 r, f32 g, f32 b, f32 a, f32 thickness);
+void draw_line3DScreenOffset(f32 anchorX, f32 anchorY, f32 anchorZ,
+ f32 fromX, f32 fromY, f32 toX, f32 toY,
+ f32 r, f32 g, f32 b, f32 a, f32 thickness);
void draw_rect(f32 x, f32 y, f32 width, f32 height,
f32 r, f32 g, f32 b, f32 a, bool filled);
void draw_rectOutline(f32 x, f32 y, f32 width, f32 height,
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index d8ad5e6af..a1a1b66d7 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -545,9 +545,11 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("draw_begin", &esengine::draw_begin);
emscripten::function("draw_end", &esengine::draw_end);
+ emscripten::function("draw_deferEnd", &esengine::draw_deferEnd);
emscripten::function("draw_line", &esengine::draw_line);
emscripten::function("draw_line3D", &esengine::draw_line3D);
emscripten::function("draw_line3DScreen", &esengine::draw_line3DScreen);
+ emscripten::function("draw_line3DScreenOffset", &esengine::draw_line3DScreenOffset);
emscripten::function("draw_rect", &esengine::draw_rect);
emscripten::function("draw_rectOutline", &esengine::draw_rectOutline);
emscripten::function("draw_circle", &esengine::draw_circle);
diff --git a/src/esengine/core/EstellaContext.cpp b/src/esengine/core/EstellaContext.cpp
index 82002638f..7d4397590 100644
--- a/src/esengine/core/EstellaContext.cpp
+++ b/src/esengine/core/EstellaContext.cpp
@@ -216,6 +216,7 @@ void EstellaContext::initSubsystems(Unique<GfxDevice> gfxDevice) {
auto* rc = services_.getService<RenderContext>();
auto immediateDraw = makeUnique<ImmediateDraw>(*gfxDevicePtr, *rc, *rm);
immediateDraw->init();
+ auto* immediateDrawPtr = immediateDraw.get();
services_.registerOwned<ImmediateDraw>(std::move(immediateDraw));
services_.registerOwned<GeometryManager>(makeUnique<GeometryManager>());
@@ -225,6 +226,7 @@ void EstellaContext::initSubsystems(Unique<GfxDevice> gfxDevice) {
#endif
auto renderFrame = makeUnique<RenderFrame>(*gfxDevicePtr, *rc, *rm);
+ renderFrame->setPresentedOverlayDraw(immediateDrawPtr);
renderFrame->addPlugin(std::make_unique<SpritePlugin>());
renderFrame->addPlugin(std::make_unique<UIElementPlugin>());
#ifdef ES_ENABLE_BITMAP_TEXT
diff --git a/src/esengine/renderer/draw/ImmediateDraw.cpp b/src/esengine/renderer/draw/ImmediateDraw.cpp
index c2a6f5796..06718ded7 100644
--- a/src/esengine/renderer/draw/ImmediateDraw.cpp
+++ b/src/esengine/renderer/draw/ImmediateDraw.cpp
@@ -66,6 +66,26 @@ bool clipLineToNearPlane(glm::vec3& from, glm::vec3& to, const glm::mat4& viewPr
return true;
}
+/** Unproject one framebuffer-pixel offset at an anchor's clip depth. */
+bool screenOffsetPoint(const glm::mat4& inverseViewProjection,
+ const glm::vec4& clipAnchor,
+ const glm::vec2& offset,
+ f32 viewportWidth, f32 viewportHeight,
+ glm::vec3& point) {
+ const glm::vec4 clip = clipAnchor + glm::vec4(
+ 2.0f * offset.x * clipAnchor.w / viewportWidth,
+ 2.0f * offset.y * clipAnchor.w / viewportHeight,
+ 0.0f, 0.0f);
+ const glm::vec4 world = inverseViewProjection * clip;
+ if (!std::isfinite(world.x) || !std::isfinite(world.y)
+ || !std::isfinite(world.z) || !std::isfinite(world.w)
+ || std::abs(world.w) < 1e-9f) {
+ return false;
+ }
+ point = glm::vec3(world) / world.w;
+ return std::isfinite(point.x) && std::isfinite(point.y) && std::isfinite(point.z);
+}
+
} // namespace
ImmediateDraw::ImmediateDraw(GfxDevice& device, RenderContext& context,
@@ -225,6 +245,20 @@ void ImmediateDraw::end() {
inFrame_ = false;
}
+void ImmediateDraw::deferEnd() {
+ if (!inFrame_) return;
+ deferredGeometry_ = pendingGeometry_;
+ inFrame_ = false;
+}
+
+void ImmediateDraw::flushDeferred() {
+ if (!deferredGeometry_) return;
+ inFrame_ = true;
+ flush();
+ inFrame_ = false;
+ deferredGeometry_ = false;
+}
+
void ImmediateDraw::useTexture(u32 textureId) {
if (textureId != currentTexture_) {
if (pendingGeometry_) flush();
@@ -394,6 +428,28 @@ void ImmediateDraw::line3DScreen(const glm::vec3& from, const glm::vec3& to,
++primitiveCount_;
}
+void ImmediateDraw::line3DScreenOffset(const glm::vec3& anchor,
+ const glm::vec2& fromOffset,
+ const glm::vec2& toOffset,
+ const glm::vec4& color, f32 thickness) {
+ if (!inFrame_ || !(thickness > 0.0f)) return;
+
+ const glm::vec4 clipAnchor = viewProjection_ * glm::vec4(anchor, 1.0f);
+ if (!std::isfinite(clipAnchor.x) || !std::isfinite(clipAnchor.y)
+ || !std::isfinite(clipAnchor.z) || !std::isfinite(clipAnchor.w)
+ || std::abs(clipAnchor.w) < 1e-9f || clipAnchor.z + clipAnchor.w < 0.0f) {
+ return;
+ }
+
+ glm::vec3 from;
+ glm::vec3 to;
+ if (!screenOffsetPoint(inverseViewProjection_, clipAnchor, fromOffset,
+ viewportWidth_, viewportHeight_, from)
+ || !screenOffsetPoint(inverseViewProjection_, clipAnchor, toOffset,
+ viewportWidth_, viewportHeight_, to)) return;
+ line3DScreen(from, to, color, thickness);
+}
+
void ImmediateDraw::polyline(std::span<const glm::vec2> vertices,
const glm::vec4& color, f32 thickness, bool closed) {
if (!inFrame_ || vertices.size() < 2) return;
diff --git a/src/esengine/renderer/draw/ImmediateDraw.hpp b/src/esengine/renderer/draw/ImmediateDraw.hpp
index 89ea3aa30..71e7dd0bb 100644
--- a/src/esengine/renderer/draw/ImmediateDraw.hpp
+++ b/src/esengine/renderer/draw/ImmediateDraw.hpp
@@ -91,6 +91,12 @@ public:
/** @brief Ends the frame and submits all draw commands */
void end();
+ /** Close collection now and submit it when the owning scene pass executes. */
+ void deferEnd();
+
+ /** Submit a collection closed by deferEnd inside the active render pass. */
+ void flushDeferred();
+
/**
* @brief Flushes pending draw commands without ending the frame
* @details Use before operations that change GL state to ensure accumulated
@@ -119,6 +125,17 @@ public:
void line3DScreen(const glm::vec3& from, const glm::vec3& to,
const glm::vec4& color, f32 thickness = 1.0f);
+ /**
+ * @brief A framebuffer-sized line attached to one world-space anchor.
+ * @details Offsets use framebuffer pixels (+X right, +Y up). The anchor is
+ * projected through the active draw frame, so editor handles keep a
+ * stable size without sampling a second camera.
+ */
+ void line3DScreenOffset(const glm::vec3& anchor,
+ const glm::vec2& fromOffset,
+ const glm::vec2& toOffset,
+ const glm::vec4& color, f32 thickness = 1.0f);
+
void polyline(std::span<const glm::vec2> vertices, const glm::vec4& color,
f32 thickness = 1.0f, bool closed = false);
@@ -209,6 +226,7 @@ private:
u32 white_texture_id_ = 0;
u32 currentTexture_ = 0;
bool pendingGeometry_ = false;
+ bool deferredGeometry_ = false;
/// Where the camera looks, from the view-projection this frame began with —
/// what a 3D line is widened across.
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index 7768edfbc..0116ca4df 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -5,6 +5,7 @@
#include "../rhi/ShaderEmbeds.generated.hpp"
#include "../store/LightStore.hpp"
#include "../draw/BatchBuilder.hpp"
+#include "../draw/ImmediateDraw.hpp"
#include "../../ecs/components/Transform.hpp"
#include "../../ecs/components/Light.hpp"
#include "../../ecs/components/ShadowCaster2D.hpp"
@@ -545,7 +546,10 @@ void RenderFrame::end() {
if (shadow_resource_ != rg::kNoResource) {
scene.dependencies.push_back(shadow_resource_);
}
- scene.execute = [this](const rg::PassContext&) { drawScene(); };
+ scene.execute = [this](const rg::PassContext&) {
+ drawScene();
+ if (presented_overlay_draw_) presented_overlay_draw_->flushDeferred();
+ };
graph_.addPass(std::move(scene));
}
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index 829ae9699..9aedffce9 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -36,6 +36,7 @@
namespace esengine {
namespace ecs { struct Light; }
+class ImmediateDraw;
/// The one shadow texture every map a frame renders shares. One size for every
/// scene: coverage adapts to the camera instead, so texel density is a property of
@@ -102,6 +103,9 @@ public:
void shutdown();
void resize(u32 width, u32 height);
+ /** Geometry collected for this camera and drawn after its scene. */
+ void setPresentedOverlayDraw(ImmediateDraw* draw) { presented_overlay_draw_ = draw; }
+
/// Rebuilds everything this frame owns after a device loss: the transient
/// pool, the render targets, the batch program ids and the post-process chain.
void recreateGpuResources();
@@ -454,6 +458,7 @@ private:
GfxDevice& device_;
RenderContext& context_;
resource::ResourceManager& resource_manager_;
+ ImmediateDraw* presented_overlay_draw_ = nullptr;
#ifdef ES_ENABLE_POSTPROCESS
Unique<PostProcessPipeline> post_process_;