manim-web 0.2.0

package/dist/core/Scene.d.ts

@@ -0,0 +1,353 @@
+import { Renderer } from './Renderer';
+import { Camera2D } from './Camera';
+import { Mobject } from './Mobject';
+import { Animation } from '../animation/Animation';
+import { Timeline } from '../animation/Timeline';
+import { SceneStateManager, SceneSnapshot } from './StateManager';
+import { AudioManager, AddSoundOptions, AudioTrack } from './AudioManager';
+import * as THREE from 'three';
+/**
+ * Options for configuring a Scene.
+ */
+export interface SceneOptions {
+    /** Canvas width in pixels. Defaults to container width. */
+    width?: number;
+    /** Canvas height in pixels. Defaults to container height. */
+    height?: number;
+    /** Background color as CSS color string. Defaults to Manim's dark gray (#1C1C1C). */
+    backgroundColor?: string;
+    /** Frame width in world units. Defaults to 14 (Manim standard). */
+    frameWidth?: number;
+    /** Frame height in world units. Defaults to 8 (Manim standard). */
+    frameHeight?: number;
+    /** Target frame rate in fps. Defaults to 60. */
+    targetFps?: number;
+    /** Enable frustum culling optimization. Defaults to true. */
+    frustumCulling?: boolean;
+    /** Enable auto-render on add/remove. Defaults to true. */
+    autoRender?: boolean;
+}
+/**
+ * Scene orchestrator for manimweb.
+ * Manages the renderer, camera, mobjects, and animation playback.
+ * Works like Manim's Scene class - add mobjects, play animations.
+ */
+export declare class Scene {
+    private _renderer;
+    private _camera;
+    private _threeScene;
+    private _mobjects;
+    private _timeline;
+    private _isPlaying;
+    private _currentTime;
+    private _animationFrameId;
+    private _backgroundTimerId;
+    private _lastFrameTime;
+    private _playPromiseResolve;
+    private _targetFps;
+    private _targetFrameTime;
+    private _frustumCulling;
+    private _frustum;
+    private _projScreenMatrix;
+    private static _tempBox3;
+    protected _autoRender: boolean;
+    private _renderOrderCounter;
+    private _stateManager;
+    private _audioManager;
+    /**
+     * Create a new Scene.
+     * @param container - DOM element to render into
+     * @param options - Scene configuration options
+     */
+    constructor(container: HTMLElement, options?: SceneOptions);
+    /**
+     * Get the Three.js scene.
+     */
+    get threeScene(): THREE.Scene;
+    /**
+     * Get the camera.
+     */
+    get camera(): Camera2D;
+    /**
+     * Get the renderer.
+     */
+    get renderer(): Renderer;
+    /**
+     * Get the current timeline.
+     */
+    get timeline(): Timeline | null;
+    /**
+     * Get whether animations are currently playing.
+     */
+    get isPlaying(): boolean;
+    /**
+     * Get the current playback time.
+     */
+    get currentTime(): number;
+    /**
+     * Get all mobjects in the scene.
+     */
+    get mobjects(): ReadonlySet<Mobject>;
+    /**
+     * Get the audio manager (lazily created on first access).
+     * Use this to access lower-level audio controls.
+     */
+    get audioManager(): AudioManager;
+    /**
+     * Add a sound to play at a specific time on the timeline.
+     * Mirrors Python manim's `self.add_sound("file.wav", time_offset=0.5)`.
+     *
+     * @param url - URL of the audio file
+     * @param options - Scheduling and playback options
+     * @returns Promise resolving to the created AudioTrack
+     *
+     * @example
+     * ```ts
+     * await scene.addSound('/sounds/click.wav', { time: 0.5 });
+     * await scene.addSound('/sounds/whoosh.wav');  // plays at time 0
+     * ```
+     */
+    addSound(url: string, options?: AddSoundOptions): Promise<AudioTrack>;
+    /**
+     * Add a sound that starts when a given animation begins.
+     *
+     * @param animation - The animation to sync with
+     * @param url - URL of the audio file
+     * @param options - Additional options (timeOffset shifts relative to animation start)
+     * @returns Promise resolving to the created AudioTrack
+     *
+     * @example
+     * ```ts
+     * const fadeIn = new FadeIn(circle);
+     * await scene.addSoundAtAnimation(fadeIn, '/sounds/appear.wav');
+     * await scene.play(fadeIn);
+     * ```
+     */
+    addSoundAtAnimation(animation: Animation, url: string, options?: Omit<AddSoundOptions, 'time'> & {
+        timeOffset?: number;
+    }): Promise<AudioTrack>;
+    /**
+     * Add mobjects as foreground objects that render on top of everything.
+     * Matches Manim Python's add_foreground_mobject().
+     * @param mobjects - Mobjects to add in the foreground
+     */
+    addForegroundMobject(...mobjects: Mobject[]): this;
+    /**
+     * Add mobjects to the scene.
+     * @param mobjects - Mobjects to add
+     */
+    add(...mobjects: Mobject[]): this;
+    /**
+     * Remove mobjects from the scene.
+     * @param mobjects - Mobjects to remove
+     */
+    remove(...mobjects: Mobject[]): this;
+    /**
+     * Check if a THREE object is already part of this scene's graph.
+     */
+    private _isInSceneGraph;
+    /**
+     * Clear all mobjects from the scene.
+     */
+    clear(): this;
+    /**
+     * Recursively collect all leaf animations from animation groups.
+     */
+    private _collectAllAnimations;
+    /**
+     * Play animations in parallel (all at once).
+     * Matches Manim's scene.play() behavior where multiple animations run simultaneously.
+     * Automatically adds mobjects to the scene if not already present.
+     * @param animations - Animations to play
+     * @returns Promise that resolves when all animations complete
+     */
+    play(...animations: Animation[]): Promise<void>;
+    /**
+     * Play multiple animations in parallel (all at once).
+     * Alias for play() - delegates to play() to avoid duplicated logic.
+     * @param animations - Animations to play simultaneously
+     * @returns Promise that resolves when all animations complete
+     */
+    playAll(...animations: Animation[]): Promise<void>;
+    /**
+     * Wait for a duration (pause between animations).
+     * Runs a render loop during the wait so that updaters keep ticking.
+     * @param duration - Duration in seconds
+     * @returns Promise that resolves after the duration
+     */
+    wait(duration?: number): Promise<void>;
+    /**
+     * Seek to a specific time in the timeline.
+     * Also seeks the audio manager if audio has been used.
+     * @param time - Time in seconds
+     */
+    seek(time: number): this;
+    /**
+     * Pause playback (video and audio).
+     */
+    pause(): this;
+    /**
+     * Resume playback (video and audio).
+     */
+    resume(): this;
+    /**
+     * Stop playback and reset timeline (video and audio).
+     */
+    stop(): this;
+    /**
+     * Recursively find all descendant mobjects with waitForRender() and
+     * trigger a scene re-render when each completes.
+     */
+    private _awaitAsyncRenders;
+    /**
+     * Render a single frame.
+     * Syncs only dirty mobjects before rendering for performance.
+     * Protected so subclasses (e.g. ZoomedScene) can override for multi-pass rendering.
+     */
+    protected _render(): void;
+    /**
+     * Sync only mobjects that have been modified (dirty flag optimization).
+     */
+    private _syncDirtyMobjects;
+    /**
+     * Update frustum for culling calculations.
+     */
+    private _updateFrustum;
+    /**
+     * Check if an object is within the camera's view frustum.
+     * Useful for manual culling checks or debugging.
+     * @param object - Three.js object to check
+     * @returns true if object is in view or if culling is disabled
+     */
+    isInView(object: THREE.Object3D): boolean;
+    /**
+     * Check if the timeline is finished and resolve the play promise.
+     * Shared by both the rAF loop and the background timer.
+     */
+    private _checkFinished;
+    /**
+     * Start the animation render loop with frame rate control.
+     * Uses requestAnimationFrame for smooth foreground rendering,
+     * plus a setInterval fallback so the timeline still advances
+     * when the tab is in the background (rAF is suspended).
+     */
+    private _startRenderLoop;
+    /**
+     * Stop the animation render loop.
+     */
+    private _stopRenderLoop;
+    /**
+     * Batch multiple mobject updates without re-rendering between each.
+     * Useful for performance when making many changes at once.
+     * @param callback - Function containing multiple mobject operations
+     * @example
+     * ```ts
+     * scene.batch(() => {
+     *   circle.setColor('red');
+     *   circle.shift([1, 0, 0]);
+     *   square.setOpacity(0.5);
+     * });
+     * ```
+     */
+    batch(callback: () => void): void;
+    /**
+     * Set the target frame rate.
+     * @param fps - Target frames per second (1-120)
+     */
+    setTargetFps(fps: number): this;
+    /**
+     * Get the current target frame rate.
+     * @returns Target fps
+     */
+    getTargetFps(): number;
+    /**
+     * Enable or disable frustum culling.
+     * @param enabled - Whether frustum culling should be enabled
+     */
+    setFrustumCulling(enabled: boolean): this;
+    /**
+     * Handle window resize.
+     * @param width - New width in pixels
+     * @param height - New height in pixels
+     */
+    resize(width: number, height: number): this;
+    /**
+     * Get the canvas element.
+     * @returns The HTMLCanvasElement used for rendering
+     */
+    getCanvas(): HTMLCanvasElement;
+    /**
+     * Get the container element the scene is rendered into.
+     * Returns the parent element of the canvas.
+     * @returns The container HTMLElement
+     */
+    getContainer(): HTMLElement;
+    /**
+     * Get the width of the canvas in pixels.
+     * @returns Canvas width in pixels
+     */
+    getWidth(): number;
+    /**
+     * Get the height of the canvas in pixels.
+     * @returns Canvas height in pixels
+     */
+    getHeight(): number;
+    /**
+     * Get the total duration of the current timeline.
+     * @returns Duration in seconds, or 0 if no timeline
+     */
+    getTimelineDuration(): number;
+    /**
+     * Get the scene's state manager for advanced undo/redo control.
+     */
+    get stateManager(): SceneStateManager;
+    /**
+     * Save the current state of all scene mobjects.
+     * Pushes onto the undo stack and clears the redo stack.
+     *
+     * @param label - Optional human-readable label
+     * @returns The captured SceneSnapshot
+     *
+     * @example
+     * ```ts
+     * scene.add(circle, square);
+     * scene.saveState();
+     * circle.shift([2, 0, 0]);
+     * scene.undo(); // circle returns to original position
+     * ```
+     */
+    saveState(label?: string): SceneSnapshot;
+    /**
+     * Undo the last change (restore the most recently saved state).
+     * The current state is pushed to the redo stack.
+     *
+     * @returns true if undo was applied, false if nothing to undo
+     */
+    undo(): boolean;
+    /**
+     * Redo the last undone change.
+     * The current state is pushed to the undo stack.
+     *
+     * @returns true if redo was applied, false if nothing to redo
+     */
+    redo(): boolean;
+    /**
+     * Get a snapshot of the current scene state without modifying stacks.
+     */
+    getState(label?: string): SceneSnapshot;
+    /**
+     * Apply a previously captured snapshot, overwriting all mobject states.
+     * Does NOT modify undo/redo stacks. Call saveState() first to preserve.
+     */
+    setState(snapshot: SceneSnapshot): void;
+    /**
+     * Force render a single frame.
+     * Useful for video export where frames need to be captured at specific times.
+     */
+    render(): void;
+    /**
+     * Clean up all resources (renderer, mobjects, audio).
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=Scene.d.ts.map

package/dist/core/Scene.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Scene.d.ts","sourceRoot":"","sources":["../../src/core/Scene.ts"],"names":[],"mappings":"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"}