threepipe
Version:
A modern 3D viewer framework built on top of three.js, written in TypeScript, designed to make creating high-quality, modular, and extensible 3D experiences on the web simple and enjoyable.
213 lines • 8.81 kB
TypeScript
import { Texture, TextureDataType, Vector4, WebGLRenderTarget } from 'three';
import { ExtendedShaderPass, IPassID, IPipelinePass } from '../../postprocessing';
import { ThreeViewer } from '../../viewer';
import { PipelinePassPlugin } from '../base/PipelinePassPlugin';
import { ICamera, IMaterial, IRenderManager, IScene, IWebGLRenderer } from '../../core';
import { ValOrFunc } from 'ts-browser-helpers';
import { MaterialExtension } from '../../materials';
import { GBufferPlugin } from './GBufferPlugin';
import { GBufferUpdaterContext } from './GBufferMaterial';
export type SSAOPluginTarget = WebGLRenderTarget;
/**
* SSAO Packing modes for different texture formats and use cases
*
* - **Mode 1**: `(r: ssao, gba: depth)` - SSAO in red channel, depth in green/blue/alpha
* - **Mode 2**: `(rgb: ssao, a: 1)` - SSAO in RGB channels, alpha set to 1
* - **Mode 3**: `(rgba: packed_ssao)` - Packed SSAO data across all RGBA channels
* - **Mode 4**: `(rgb: packed_ssao, a: 1)` - Packed SSAO in RGB channels, alpha set to 1
*
* @remarks
* Currently only modes 1 and 2 are fully supported in the shader implementation.
* Modes 3 and 4 are available for future use but may require additional shader updates.
*/
export type SSAOPacking = 1 | 2 | 3 | 4;
/**
* Screen Space Ambient Occlusion (SSAO) Plugin for enhanced lighting and depth perception in 3D scenes.
*
* SSAO is a real-time ambient occlusion technique that approximates the soft shadows that occur in creases,
* holes, and surfaces that are close to each other. This plugin adds a pre-render pass that calculates
* ambient occlusion data which is then used by materials during the main render pass.
*
* ## Key Features
* - **Real-time SSAO calculation** using screen-space techniques
* - **Multiple packing modes** for different texture formats and optimization needs
* - **Per-material control** - materials can disable SSAO individually via userData
* - **Configurable quality settings** including sample count, radius, bias, and intensity
* - **Automatic serialization** of all settings with viewer configuration
* - **GBuffer integration** for optimized depth and normal data access
*
* ## Dependencies
* This plugin automatically adds {@link GBufferPlugin} as a dependency for efficient depth and normal data.
*
* ## Usage Scenarios
* - **Architectural visualization** - enhances depth perception in interior scenes
* - **Product visualization** - adds realistic ambient shadows to showcase products
* - **Game environments** - provides cost-effective ambient occlusion for real-time rendering
* - **CAD visualization** - improves understanding of complex mechanical assemblies
*
* ## Performance Considerations
* - Use lower `sizeMultiplier` values (0.5-0.75) for better performance on mobile devices
* - Combine with {@link ProgressivePlugin} and `TemporalAAPlugin` for temporal accumulation
* - Consider disabling SSAO on transparent or unlit materials to save processing
*
* @example Basic Usage
* ```typescript
* import {ThreeViewer, SSAOPlugin} from 'threepipe'
*
* const viewer = new ThreeViewer({
* plugins: [new SSAOPlugin()]
* })
*
* // Access the plugin and configure settings
* const ssaoPlugin = viewer.getPlugin(SSAOPlugin)!
* ssaoPlugin.pass.intensity = 1.2
* ssaoPlugin.pass.radius = 0.5
* ```
*
* @example Per-Material Control
* ```typescript
* // Disable SSAO for a specific material
* material.userData.ssaoDisabled = true
*
* // Disable SSAO casting (material won't contribute to AO calculation)
* material.userData.ssaoCastDisabled = true
* ```
*
* @example High Performance Setup
* ```typescript
* const ssaoPlugin = new SSAOPlugin(
* UnsignedByteType, // Buffer type
* 0.5, // Size multiplier for better performance
* true, // Enabled
* 1 // Packing mode
* )
* viewer.addPlugin(ssaoPlugin)
* ```
*
* @category Plugins
*/
export declare class SSAOPlugin extends PipelinePassPlugin<SSAOPluginPass, 'ssao'> {
readonly passId = "ssao";
static readonly PluginType = "SSAOPlugin";
static readonly OldPluginType = "SSAO";
/**
* Plugin dependencies - automatically adds GBufferPlugin for depth and normal data
* @internal
*/
dependencies: (typeof GBufferPlugin)[];
/** The render target containing SSAO data */
target?: SSAOPluginTarget;
/** Debug texture preview of the SSAO buffer (read-only) */
texture?: Texture;
protected _pass?: SSAOPluginPass;
/**
* Buffer data type for the SSAO render target.
* Cannot be changed after plugin creation.
*
* @remarks
* - `UnsignedByteType` - Standard 8-bit precision, good performance
* - `HalfFloatType` - 16-bit precision, better quality but slower
* - `FloatType` - 32-bit precision, highest quality but slowest
*/
readonly bufferType: TextureDataType;
/**
* Render target size multiplier relative to the main canvas size.
* Cannot be changed after plugin creation.
*
* @remarks
* - `1.0` - Full resolution (highest quality)
* - `0.75` - 75% resolution (good balance)
* - `0.5` - Half resolution (better performance)
* - `0.25` - Quarter resolution (mobile performance)
*/
readonly sizeMultiplier: number;
/**
* SSAO data packing mode for the render target.
* Cannot be changed after plugin creation.
*
* @see {@link SSAOPacking} for available packing modes
*/
readonly packing: SSAOPacking;
/**
* Creates a new SSAOPlugin instance.
*
* @param bufferType - Data type for the SSAO buffer (default: UnsignedByteType)
* @param sizeMultiplier - Size multiplier for the render target (default: 1.0)
* @param enabled - Whether the plugin is initially enabled (default: true)
* @param packing - SSAO data packing mode (default: 1)
*/
constructor(bufferType?: TextureDataType, sizeMultiplier?: number, enabled?: boolean, packing?: SSAOPacking);
protected _createTarget(recreate?: boolean): void;
protected _disposeTarget(): void;
private _gbufferUnpackExtension;
private _gbufferUnpackExtensionChanged;
protected _createPass(): SSAOPluginPass;
onAdded(viewer: ThreeViewer): void;
onRemove(viewer: ThreeViewer): void;
fromJSON(data: any, meta?: any): this | null | Promise<this | null>;
updateGBufferFlags(data: Vector4, c: GBufferUpdaterContext): void;
/**
* @deprecated use {@link target} instead
*/
get aoTarget(): SSAOPluginTarget | undefined;
}
export declare class SSAOPluginPass extends ExtendedShaderPass implements IPipelinePass {
readonly passId: IPassID;
target?: ValOrFunc<WebGLRenderTarget | undefined>;
before: string[];
after: string[];
required: string[];
intensity: number;
occlusionWorldRadius: number;
/**
* Whether to automatically adapt the occlusion radius based on the scene size.
* This is useful when scene is not centered or normalized
*/
autoRadius: boolean;
bias: number;
falloff: number;
numSamples: number;
/**
* Whether to check for gbuffer flag or not. This is used to disable SSAO casting by some objects. its enabled automatically by the SSAOPlugin when required.
* This is disabled by default so that we dont read texture for no reason.
*/
checkGBufferFlag: boolean;
split: number;
constructor(passId: IPassID, target?: ValOrFunc<WebGLRenderTarget | undefined>, packing?: SSAOPacking);
copyToWriteBuffer: boolean;
render(renderer: IWebGLRenderer, writeBuffer: WebGLRenderTarget, readBuffer: WebGLRenderTarget, deltaTime: number, maskActive: boolean): void;
private _projScale;
private _updateParameters;
beforeRender(scene: IScene, camera: ICamera, renderManager: IRenderManager): void;
readonly materialExtension: MaterialExtension;
/**
* Returns a uiConfig to toggle SSAO on a material.
* This uiConfig is added to each material by extension
* @param material
* @private
*/
protected _getUiConfig(material: IMaterial): {
type: string;
label: string;
children: {
type: string;
label: string;
value: boolean;
onChange: () => void;
}[];
};
}
declare module '../../core/IMaterial' {
interface IMaterialUserData {
/**
* Disable SSAOPlugin for this material.
*/
ssaoDisabled?: boolean;
/**
* Cast SSAO on other objects.
* if casting is not working when this is false, ensure render to depth is true, like for transparent objects
*/
ssaoCastDisabled?: boolean;
}
}
//# sourceMappingURL=../../src/plugins/pipeline/SSAOPlugin.d.ts.map