rayzee 4.8.9 → 4.8.11

package/src/api/AnimationAPI.js

@@ -0,0 +1,87 @@
+/**
+ * Animation sub-API — playback controls for GLTF animation clips.
+ *
+ * Access via `engine.animation`.
+ *
+ * @example
+ * engine.animation.play(0);
+ * engine.animation.setSpeed(2);
+ * console.log(engine.animation.clips);
+ */
+export class AnimationAPI {
+
+	/** @param {import('../PathTracerApp.js').PathTracerApp} app */
+	constructor( app ) {
+
+		this._app = app;
+
+	}
+
+	/**
+	 * Plays an animation clip by index.
+	 * @param {number} [clipIndex=0]
+	 */
+	play( clipIndex = 0 ) {
+
+		this._app.playAnimation( clipIndex );
+
+	}
+
+	/**
+	 * Pauses animation, preserving current time position.
+	 */
+	pause() {
+
+		this._app.pauseAnimation();
+
+	}
+
+	/**
+	 * Resumes animation from paused state.
+	 */
+	resume() {
+
+		this._app.resumeAnimation();
+
+	}
+
+	/**
+	 * Stops animation and resets to beginning.
+	 */
+	stop() {
+
+		this._app.stopAnimationPlayback();
+
+	}
+
+	/**
+	 * Sets playback speed multiplier.
+	 * @param {number} speed - 1.0 = normal speed
+	 */
+	setSpeed( speed ) {
+
+		this._app.setAnimationSpeed( speed );
+
+	}
+
+	/**
+	 * Sets loop mode for animation playback.
+	 * @param {boolean} loop - true for repeat, false for play-once
+	 */
+	setLoop( loop ) {
+
+		this._app.setAnimationLoop( loop );
+
+	}
+
+	/**
+	 * Available animation clips.
+	 * @returns {{ index: number, name: string, duration: number }[]}
+	 */
+	get clips() {
+
+		return this._app.animationClips;
+
+	}
+
+}

package/src/api/CameraAPI.js

@@ -0,0 +1,109 @@
+/**
+ * Camera sub-API — camera switching, auto-focus, DOF, and raw Three.js access.
+ *
+ * Access via `engine.camera`.
+ *
+ * @example
+ * engine.camera.switch(1);
+ * engine.camera.active.fov = 60;
+ * engine.camera.controls.target.set(0, 1, 0);
+ */
+export class CameraAPI {
+
+	/** @param {import('../PathTracerApp.js').PathTracerApp} app */
+	constructor( app ) {
+
+		this._app = app;
+
+	}
+
+	/**
+	 * The active Three.js PerspectiveCamera.
+	 * @returns {import('three').PerspectiveCamera}
+	 */
+	get active() {
+
+		return this._app.cameraManager?.camera ?? this._app._camera;
+
+	}
+
+	/**
+	 * The OrbitControls instance.
+	 * @returns {import('three/addons/controls/OrbitControls.js').OrbitControls}
+	 */
+	get controls() {
+
+		return this._app.cameraManager?.controls ?? this._app._controls;
+
+	}
+
+	/**
+	 * Switches the active camera by index.
+	 * @param {number} index
+	 */
+	switch( index ) {
+
+		this._app.switchCamera( index );
+
+	}
+
+	/**
+	 * Returns display names for all available cameras.
+	 * @returns {string[]}
+	 */
+	getNames() {
+
+		return this._app.getCameraNames();
+
+	}
+
+	/**
+	 * Focuses the orbit camera on a world-space point.
+	 * @param {import('three').Vector3} center
+	 */
+	focusOn( center ) {
+
+		this._app.focusOnPoint( center );
+
+	}
+
+	/**
+	 * Sets the auto-focus mode.
+	 * @param {'auto'|'manual'} mode
+	 */
+	setAutoFocusMode( mode ) {
+
+		this._app.cameraManager?.setAutoFocusMode( mode );
+
+	}
+
+	/**
+	 * Sets the normalized AF screen point (0-1 range).
+	 * @param {number} x
+	 * @param {number} y
+	 */
+	setAFScreenPoint( x, y ) {
+
+		this._app.cameraManager?.setAFScreenPoint( x, y );
+
+	}
+
+	/**
+	 * Enters AF point placement interaction mode.
+	 */
+	enterAFPointPlacementMode() {
+
+		this._app.cameraManager?.enterAFPointPlacementMode();
+
+	}
+
+	/**
+	 * Exits AF point placement interaction mode.
+	 */
+	exitAFPointPlacementMode() {
+
+		this._app.cameraManager?.exitAFPointPlacementMode();
+
+	}
+
+}

package/src/api/DenoisingAPI.js

@@ -0,0 +1,243 @@
+/**
+ * Denoising sub-API — denoiser strategy, ASVGF, OIDN, upscaler,
+ * adaptive sampling, and auto-exposure controls.
+ *
+ * Access via `engine.denoising`.
+ *
+ * @example
+ * engine.denoising.setStrategy('asvgf', 'medium');
+ * engine.denoising.setAutoExposure(true);
+ * engine.denoising.setASVGFParams({ temporalAlpha: 0.1 });
+ */
+export class DenoisingAPI {
+
+	/** @param {import('../PathTracerApp.js').PathTracerApp} app */
+	constructor( app ) {
+
+		this._app = app;
+
+	}
+
+	// ── Strategy ──
+
+	/**
+	 * Switches the real-time denoiser strategy.
+	 * @param {'none'|'asvgf'|'ssrc'|'edgeaware'} strategy
+	 * @param {string} [asvgfPreset] - ASVGF quality preset if strategy is 'asvgf'
+	 */
+	setStrategy( strategy, asvgfPreset ) {
+
+		this._app.setDenoiserStrategy( strategy, asvgfPreset );
+
+	}
+
+	/**
+	 * Enables or disables the ASVGF denoiser with optional quality preset.
+	 * @param {boolean} enabled
+	 * @param {string} [qualityPreset]
+	 */
+	setASVGFEnabled( enabled, qualityPreset ) {
+
+		this._app.setASVGFEnabled( enabled, qualityPreset );
+
+	}
+
+	/**
+	 * Applies an ASVGF quality preset.
+	 * @param {'low'|'medium'|'high'} presetName
+	 */
+	applyASVGFPreset( presetName ) {
+
+		this._app.applyASVGFPreset( presetName );
+
+	}
+
+	/**
+	 * Enables or disables auto-exposure.
+	 * @param {boolean} enabled
+	 */
+	setAutoExposure( enabled ) {
+
+		this._app.setAutoExposureEnabled( enabled );
+
+	}
+
+	/**
+	 * Enables or disables adaptive sampling.
+	 * @param {boolean} enabled
+	 */
+	setAdaptiveSampling( enabled ) {
+
+		this._app.setAdaptiveSamplingEnabled( enabled );
+
+	}
+
+	// ── Stage Parameters ──
+
+	/**
+	 * Updates ASVGF stage parameters.
+	 * @param {Object} params - { temporalAlpha, phiColor, phiLuminance, atrousIterations, ... }
+	 */
+	setASVGFParams( params ) {
+
+		this._app.updateASVGFParameters( params );
+
+	}
+
+	/**
+	 * Toggles the ASVGF heatmap debug overlay.
+	 * @param {boolean} enabled
+	 */
+	toggleASVGFHeatmap( enabled ) {
+
+		this._app.toggleASVGFHeatmap( enabled );
+
+	}
+
+	/**
+	 * Configures ASVGF for a specific render mode.
+	 * @param {Object} config - { enabled, temporalAlpha, atrousIterations, ... }
+	 */
+	configureASVGFForMode( config ) {
+
+		this._app.configureASVGFForMode( config );
+
+	}
+
+	/**
+	 * Updates SSRC stage parameters.
+	 * @param {Object} params - { temporalAlpha, spatialRadius, spatialWeight }
+	 */
+	setSSRCParams( params ) {
+
+		this._app.updateSSRCParameters( params );
+
+	}
+
+	/**
+	 * Updates edge-aware filtering parameters.
+	 * @param {Object} params - { pixelEdgeSharpness, edgeSharpenSpeed, edgeThreshold }
+	 */
+	setEdgeAwareParams( params ) {
+
+		this._app.updateEdgeAwareUniforms( params );
+
+	}
+
+	/**
+	 * Updates auto-exposure stage parameters.
+	 * @param {Object} params - { keyValue, minExposure, maxExposure, ... }
+	 */
+	setAutoExposureParams( params ) {
+
+		this._app.updateAutoExposureParameters( params );
+
+	}
+
+	// ── Adaptive Sampling ──
+
+	/**
+	 * Updates adaptive sampling parameters.
+	 * @param {Object} params
+	 */
+	setAdaptiveSamplingParams( params ) {
+
+		this._app.setAdaptiveSamplingParameters( params );
+
+	}
+
+	/**
+	 * Toggles the adaptive sampling debug helper.
+	 * @param {boolean} enabled
+	 */
+	toggleAdaptiveSamplingHelper( enabled ) {
+
+		this._app.toggleAdaptiveSamplingHelper( enabled );
+
+	}
+
+	// ── OIDN ──
+
+	/**
+	 * Enables or disables Intel OIDN denoiser (final render quality).
+	 * @param {boolean} enabled
+	 */
+	setOIDNEnabled( enabled ) {
+
+		this._app.setOIDNEnabled( enabled );
+
+	}
+
+	/**
+	 * Sets OIDN denoiser quality.
+	 * @param {string} quality
+	 */
+	setOIDNQuality( quality ) {
+
+		this._app.updateOIDNQuality( quality );
+
+	}
+
+	/**
+	 * Enables or disables the OIDN tile helper overlay.
+	 * @param {boolean} enabled
+	 */
+	setOIDNTileHelper( enabled ) {
+
+		this._app.setOIDNTileHelper( enabled );
+
+	}
+
+	/**
+	 * Enables or disables the tile helper overlay.
+	 * @param {boolean} enabled
+	 */
+	setTileHelperEnabled( enabled ) {
+
+		this._app.setTileHelperEnabled( enabled );
+
+	}
+
+	/**
+	 * Enables or disables tile highlight.
+	 * @param {boolean} enabled
+	 */
+	setTileHighlightEnabled( enabled ) {
+
+		this._app.setTileHighlightEnabled( enabled );
+
+	}
+
+	// ── AI Upscaler ──
+
+	/**
+	 * Enables or disables the AI upscaler.
+	 * @param {boolean} enabled
+	 */
+	setUpscalerEnabled( enabled ) {
+
+		this._app.setUpscalerEnabled( enabled );
+
+	}
+
+	/**
+	 * Sets the upscaler scale factor.
+	 * @param {number} factor
+	 */
+	setUpscalerScaleFactor( factor ) {
+
+		this._app.setUpscalerScaleFactor( factor );
+
+	}
+
+	/**
+	 * Sets the upscaler quality level.
+	 * @param {string} quality
+	 */
+	setUpscalerQuality( quality ) {
+
+		this._app.setUpscalerQuality( quality );
+
+	}
+
+}

package/src/api/EnvironmentAPI.js

@@ -0,0 +1,106 @@
+/**
+ * Environment sub-API — HDR maps, sky modes, and procedural generation.
+ *
+ * Access via `engine.environment`.
+ *
+ * @example
+ * await engine.environment.setMode('gradient');
+ * engine.environment.params.sunElevation = 45;
+ * engine.environment.markDirty();
+ */
+export class EnvironmentAPI {
+
+	/** @param {import('../PathTracerApp.js').PathTracerApp} app */
+	constructor( app ) {
+
+		this._app = app;
+
+	}
+
+	/**
+	 * Current environment parameters (sun position, sky colors, etc.).
+	 * @returns {Object|null}
+	 */
+	get params() {
+
+		return this._app.getEnvParams();
+
+	}
+
+	/**
+	 * The loaded environment texture.
+	 * @returns {import('three').Texture|null}
+	 */
+	get texture() {
+
+		return this._app.getEnvironmentTexture();
+
+	}
+
+	/**
+	 * Loads an HDR/EXR environment map from URL.
+	 * @param {string} url
+	 */
+	async load( url ) {
+
+		await this._app.loadEnvironment( url );
+
+	}
+
+	/**
+	 * Sets a custom environment texture directly.
+	 * @param {import('three').Texture} texture
+	 */
+	async setTexture( texture ) {
+
+		await this._app.setEnvironmentMap( texture );
+
+	}
+
+	/**
+	 * Switches the sky mode.
+	 * @param {'hdri'|'procedural'|'gradient'|'color'} mode
+	 */
+	async setMode( mode ) {
+
+		await this._app.setEnvironmentMode( mode );
+
+	}
+
+	/**
+	 * Generates a procedural Preetham-model sky texture.
+	 */
+	async generateProcedural() {
+
+		return this._app.generateProceduralSkyTexture();
+
+	}
+
+	/**
+	 * Generates a gradient sky texture.
+	 */
+	async generateGradient() {
+
+		return this._app.generateGradientTexture();
+
+	}
+
+	/**
+	 * Generates a solid color sky texture.
+	 */
+	async generateSolid() {
+
+		return this._app.generateSolidColorTexture();
+
+	}
+
+	/**
+	 * Flags the environment texture for GPU re-upload.
+	 */
+	markDirty() {
+
+		this._app.markEnvironmentNeedsUpdate();
+
+	}
+
+}

package/src/api/LightsAPI.js

@@ -0,0 +1,80 @@
+/**
+ * Lights sub-API — light CRUD, helpers, and GPU sync.
+ *
+ * Access via `engine.lights`.
+ *
+ * @example
+ * engine.lights.add('PointLight');
+ * engine.lights.showHelpers(true);
+ * engine.lights.getAll();
+ */
+export class LightsAPI {
+
+	/** @param {import('../PathTracerApp.js').PathTracerApp} app */
+	constructor( app ) {
+
+		this._app = app;
+
+	}
+
+	/**
+	 * Adds a light to the scene.
+	 * @param {'DirectionalLight'|'PointLight'|'SpotLight'|'RectAreaLight'} type
+	 * @returns {Object|null} Light descriptor
+	 */
+	add( type ) {
+
+		return this._app.addLight( type );
+
+	}
+
+	/**
+	 * Removes a light by UUID.
+	 * @param {string} uuid
+	 * @returns {boolean}
+	 */
+	remove( uuid ) {
+
+		return this._app.removeLight( uuid );
+
+	}
+
+	/**
+	 * Removes all lights from the scene.
+	 */
+	clear() {
+
+		this._app.clearLights();
+
+	}
+
+	/**
+	 * Returns descriptors for all lights in the scene.
+	 * @returns {Object[]}
+	 */
+	getAll() {
+
+		return this._app.getLights();
+
+	}
+
+	/**
+	 * Re-uploads light data to the GPU.
+	 */
+	sync() {
+
+		this._app.updateLights();
+
+	}
+
+	/**
+	 * Shows or hides visual light helpers.
+	 * @param {boolean} show
+	 */
+	showHelpers( show ) {
+
+		this._app.setShowLightHelper( show );
+
+	}
+
+}

package/src/api/MaterialsAPI.js

@@ -0,0 +1,73 @@
+/**
+ * Materials sub-API — material property updates and texture transforms.
+ *
+ * Access via `engine.materials`.
+ *
+ * @example
+ * engine.materials.setProperty(0, 'roughness', 0.5);
+ * engine.materials.refresh();
+ */
+export class MaterialsAPI {
+
+	/** @param {import('../PathTracerApp.js').PathTracerApp} app */
+	constructor( app ) {
+
+		this._app = app;
+
+	}
+
+	/**
+	 * Updates a single material property and triggers emissive rebuild if needed.
+	 * @param {number} materialIndex
+	 * @param {string} property
+	 * @param {*} value
+	 */
+	setProperty( materialIndex, property, value ) {
+
+		this._app.updateMaterialProperty( materialIndex, property, value );
+
+	}
+
+	/**
+	 * Updates a material's texture transform (offset, repeat, rotation).
+	 * @param {number} materialIndex
+	 * @param {string} textureName
+	 * @param {Object} transform
+	 */
+	setTextureTransform( materialIndex, textureName, transform ) {
+
+		this._app.updateTextureTransform( materialIndex, textureName, transform );
+
+	}
+
+	/**
+	 * Re-uploads all material data to the GPU.
+	 */
+	refresh() {
+
+		this._app.refreshMaterial();
+
+	}
+
+	/**
+	 * Replaces a material entirely.
+	 * @param {number} materialIndex
+	 * @param {import('three').Material} material
+	 */
+	replace( materialIndex, material ) {
+
+		this._app.updateMaterial( materialIndex, material );
+
+	}
+
+	/**
+	 * Full material rebuild (required after texture changes).
+	 * @param {import('three').Scene} [scene]
+	 */
+	async rebuild( scene ) {
+
+		await this._app.rebuildMaterials( scene );
+
+	}
+
+}