@@ -38,6 +38,127 @@ import type {
3838import { WebPlatform } from '../core/platforms/web/WebPlatform.js' ;
3939import { Platform } from '../core/platforms/Platform.js' ;
4040
41+ /**
42+ * FPS Update Event Data
43+ *
44+ * @category Events
45+ * @example
46+ * ```typescript
47+ * renderer.on('fpsUpdate', (data) => {
48+ * console.log(`Current FPS: ${data.fps}`);
49+ * if (data.contextSpyData) {
50+ * console.log('WebGL calls:', data.contextSpyData);
51+ * }
52+ * });
53+ * ```
54+ */
55+ export interface RendererMainFpsUpdateEvent {
56+ /** Current frames per second */
57+ fps : number ;
58+ /** Context spy data (if enabled) - contains WebGL call statistics */
59+ contextSpyData ?: unknown ;
60+ }
61+
62+ /**
63+ * Frame Tick Event Data
64+ *
65+ * @category Events
66+ * @example
67+ * ```typescript
68+ * renderer.on('frameTick', (data) => {
69+ * console.log(`Frame time: ${data.time}ms, delta: ${data.delta}ms`);
70+ * });
71+ * ```
72+ */
73+ export interface RendererMainFrameTickEvent {
74+ /** Current timestamp */
75+ time : number ;
76+ /** Time delta since last frame */
77+ delta : number ;
78+ }
79+
80+ /**
81+ * Quads Update Event Data
82+ *
83+ * @category Events
84+ * @example
85+ * ```typescript
86+ * renderer.on('quadsUpdate', (data) => {
87+ * console.log(`Rendered quads: ${data.quads}`);
88+ * });
89+ * ```
90+ */
91+ export interface RendererMainQuadsUpdateEvent {
92+ /** Number of rendered quads */
93+ quads : number ;
94+ }
95+
96+ /**
97+ * Idle Event Data
98+ *
99+ * @category Events
100+ * @remarks
101+ * This event is emitted when the renderer has no scene updates to process.
102+ * The event has no payload - use this for performance optimizations during idle periods.
103+ *
104+ * @example
105+ * ```typescript
106+ * renderer.on('idle', () => {
107+ * // Renderer is idle - perfect time for cleanup, analytics, etc.
108+ * console.log('Renderer is idle - no scene changes');
109+ *
110+ * // Example: Perform background tasks
111+ * performBackgroundCleanup();
112+ * sendAnalytics();
113+ * });
114+ * ```
115+ */
116+ export interface RendererMainIdleEvent {
117+ /** This event has no payload - listen without parameters */
118+ readonly __eventHasNoPayload ?: never ;
119+ }
120+
121+ /**
122+ * Critical Cleanup Event Data
123+ *
124+ * @category Events
125+ * @example
126+ * ```typescript
127+ * renderer.on('criticalCleanup', (data) => {
128+ * console.log(`Memory cleanup triggered!`);
129+ * console.log(`Memory used: ${data.memUsed} bytes`);
130+ * console.log(`Critical threshold: ${data.criticalThreshold} bytes`);
131+ * });
132+ * ```
133+ */
134+ export interface RendererMainCriticalCleanupEvent {
135+ /** Memory used before cleanup (bytes) */
136+ memUsed : number ;
137+ /** Critical threshold (bytes) */
138+ criticalThreshold : number ;
139+ }
140+
141+ /**
142+ * Critical Cleanup Failed Event Data
143+ *
144+ * @category Events
145+ * @example
146+ * ```typescript
147+ * renderer.on('criticalCleanupFailed', (data) => {
148+ * console.warn(`Memory cleanup failed!`);
149+ * console.log(`Memory still used: ${data.memUsed} bytes`);
150+ * console.log(`Critical threshold: ${data.criticalThreshold} bytes`);
151+ * // Consider reducing texture usage or forcing cleanup
152+ * });
153+ * ```
154+ */
155+ export interface RendererMainCriticalCleanupFailedEvent {
156+ /** Memory used after cleanup (bytes) */
157+ memUsed : number ;
158+ /** Critical threshold (bytes) */
159+ criticalThreshold : number ;
160+ }
161+
41162/**
42163 * Settings for the Renderer that can be updated during runtime.
43164 */
@@ -330,31 +451,32 @@ export type RendererMainSettings = RendererRuntimeSettings & {
330451 * );
331452 * ```
332453 *
333- * ## Events
334- * - `fpsUpdate`
335- * - Emitted every `fpsUpdateInterval` milliseconds with the current FPS
336- * - `frameTick`
337- * - Emitted every frame tick
338- * - `quadsUpdate`
339- * - Emitted when number of quads rendered is updated
340- * - `idle`
341- * - Emitted when the renderer is idle (no changes to the scene
342- * graph/animations running)
343- * - `criticalCleanup`
344- * - Emitted when the Texture Memory Manager Cleanup process is triggered
345- * - Payload: { memUsed: number, criticalThreshold: number }
346- * - `memUsed` - The amount of memory (in bytes) used by textures before the
347- * cleanup process
348- * - `criticalThreshold` - The critical threshold (in bytes)
349- * - `criticalCleanupFailed`
350- * - Emitted when the Texture Memory Manager Cleanup process is unable to free
351- * up enough texture memory to reach below the critical threshold.
352- * This can happen when there is not enough non-renderable textures to
353- * free up.
354- * - Payload (object with keys):
355- * - `memUsed` - The amount of memory (in bytes) used by textures after
356- * the cleanup process
357- * - `criticalThreshold` - The critical threshold (in bytes)
454+ * ## Event Handling
455+ *
456+ * Listen to events using the standard EventEmitter API:
457+ * ```typescript
458+ * renderer.on('fpsUpdate', (data: RendererMainFpsUpdateEvent) => {
459+ * console.log(`FPS: ${data.fps}`);
460+ * });
461+ *
462+ * renderer.on('idle', (data: RendererMainIdleEvent) => {
463+ * // Renderer is idle - no scene changes
464+ * });
465+ * ```
466+ *
467+ * @see {@link RendererMainFpsUpdateEvent }
468+ * @see {@link RendererMainFrameTickEvent }
469+ * @see {@link RendererMainQuadsUpdateEvent }
470+ * @see {@link RendererMainIdleEvent }
471+ * @see {@link RendererMainCriticalCleanupEvent }
472+ * @see {@link RendererMainCriticalCleanupFailedEvent }
473+ *
474+ * @fires RendererMain#fpsUpdate
475+ * @fires RendererMain#frameTick
476+ * @fires RendererMain#quadsUpdate
477+ * @fires RendererMain#idle
478+ * @fires RendererMain#criticalCleanup
479+ * @fires RendererMain#criticalCleanupFailed
358480 */
359481export class RendererMain extends EventEmitter {
360482 readonly root : INode ;
0 commit comments