tessl/npm-three
JavaScript 3D library providing WebGL and WebGPU renderers for creating interactive 3D graphics in web browsers
—
Pending
renderers.mddocs/
Renderers
Rendering system providing WebGL-based graphics output with comprehensive material support, post-processing capabilities, and performance optimizations. The renderer converts 3D scenes into 2D pixels for display.
Capabilities
WebGL Renderer
Primary renderer using WebGL 2.0 for hardware-accelerated graphics rendering with extensive configuration options.
import {
WebGLRenderer,
Scene,
Camera,
Color,
Vector2,
Vector4,
WebGLRenderTarget,
Material
} from 'three';
interface WebGLRendererParameters {
/** Canvas element or null for auto-creation */
canvas?: HTMLCanvasElement;
/** WebGL context or null for auto-creation */
context?: WebGLRenderingContext | WebGL2RenderingContext;
/** Enable depth buffer */
depth?: boolean;
/** Enable stencil buffer */
stencil?: boolean;
/** Enable alpha channel */
alpha?: boolean;
/** Enable antialiasing */
antialias?: boolean;
/** Premultiply alpha */
premultipliedAlpha?: boolean;
/** Preserve drawing buffer */
preserveDrawingBuffer?: boolean;
/** Power preference: 'default' | 'high-performance' | 'low-power' */
powerPreference?: 'default' | 'high-performance' | 'low-power';
/** Fail if major performance caveat */
failIfMajorPerformanceCaveat?: boolean;
/** Use reversed depth buffer */
reversedDepthBuffer?: boolean;
}
/**
* WebGL-based renderer with comprehensive 3D graphics capabilities
*/
class WebGLRenderer {
/** Type flag for WebGL renderer detection */
readonly isWebGLRenderer: true;
/** DOM element for rendering */
domElement: HTMLCanvasElement;
/** WebGL rendering context */
readonly context: WebGLRenderingContext | WebGL2RenderingContext;
/** Auto-clear flags */
autoClear: boolean;
autoClearColor: boolean;
autoClearDepth: boolean;
autoClearStencil: boolean;
/** Sorting objects flag */
sortObjects: boolean;
/** Clipping planes */
clippingPlanes: Plane[];
localClippingEnabled: boolean;
/** Output color space */
outputColorSpace: string;
/** Use legacy lights mode */
useLegacyLights: boolean;
/** Tone mapping settings */
toneMapping: number;
toneMappingExposure: number;
/** Shadow map settings */
shadowMap: {
enabled: boolean;
autoUpdate: boolean;
needsUpdate: boolean;
type: number;
};
/** Physical correct lights */
physicallyCorrectLights: boolean;
/** WebXR manager */
xr: WebXRManager;
/** Renderer capabilities */
capabilities: WebGLCapabilities;
/** Extensions manager */
extensions: WebGLExtensions;
/** Renderer properties */
properties: WebGLProperties;
/** Render state */
state: WebGLState;
/** Render info */
info: {
autoReset: boolean;
memory: { geometries: number; textures: number };
render: { calls: number; triangles: number; points: number; lines: number; frame: number };
programs: number;
};
/**
* Create WebGL renderer
* @param parameters - Configuration options
*/
constructor(parameters?: WebGLRendererParameters);
/**
* Get WebGL context
* @returns WebGL context
*/
getContext(): WebGLRenderingContext | WebGL2RenderingContext;
/**
* Get context attributes
* @returns Context attributes object
*/
getContextAttributes(): WebGLContextAttributes;
/**
* Force context loss (for testing)
*/
forceContextLoss(): void;
/**
* Force context restore (for testing)
*/
forceContextRestore(): void;
/**
* Get pixel ratio
* @returns Current pixel ratio
*/
getPixelRatio(): number;
/**
* Set pixel ratio
* @param value - Pixel ratio value
*/
setPixelRatio(value: number): void;
/**
* Get renderer size
* @param target - Target vector to store size
* @returns Size vector
*/
getSize(target: Vector2): Vector2;
/**
* Set renderer size
* @param width - Render width in pixels
* @param height - Render height in pixels
* @param updateStyle - Update canvas style (default: true)
*/
setSize(width: number, height: number, updateStyle?: boolean): void;
/**
* Get drawing buffer size
* @param target - Target vector to store size
* @returns Drawing buffer size
*/
getDrawingBufferSize(target: Vector2): Vector2;
/**
* Set drawing buffer size
* @param width - Buffer width
* @param height - Buffer height
* @param pixelRatio - Pixel ratio
*/
setDrawingBufferSize(width: number, height: number, pixelRatio: number): void;
/**
* Get current viewport
* @param target - Target vector to store viewport
* @returns Viewport vector (x, y, width, height)
*/
getCurrentViewport(target: Vector4): Vector4;
/**
* Get viewport
* @param target - Target vector to store viewport
* @returns Viewport vector
*/
getViewport(target: Vector4): Vector4;
/**
* Set viewport
* @param x - X offset
* @param y - Y offset
* @param width - Viewport width
* @param height - Viewport height
*/
setViewport(x: number, y: number, width: number, height: number): void;
setViewport(viewport: Vector4): void;
/**
* Get scissor region
* @param target - Target vector to store scissor
* @returns Scissor vector
*/
getScissor(target: Vector4): Vector4;
/**
* Set scissor test region
* @param x - X offset
* @param y - Y offset
* @param width - Scissor width
* @param height - Scissor height
*/
setScissor(x: number, y: number, width: number, height: number): void;
setScissor(scissor: Vector4): void;
/**
* Get scissor test enabled state
* @returns True if scissor test enabled
*/
getScissorTest(): boolean;
/**
* Enable/disable scissor test
* @param boolean - Enable scissor test
*/
setScissorTest(boolean: boolean): void;
/**
* Set opaque sort function
* @param method - Sort comparison function
*/
setOpaqueSort(method: (a: any, b: any) => number): void;
/**
* Set transparent sort function
* @param method - Sort comparison function
*/
setTransparentSort(method: (a: any, b: any) => number): void;
/**
* Get clear color
* @param target - Target color object
* @returns Clear color
*/
getClearColor(target: Color): Color;
/**
* Set clear color
* @param color - Clear color
* @param alpha - Clear alpha (optional)
*/
setClearColor(color: Color | string | number, alpha?: number): void;
/**
* Get clear alpha
* @returns Clear alpha value
*/
getClearAlpha(): number;
/**
* Set clear alpha
* @param alpha - Clear alpha value (0-1)
*/
setClearAlpha(alpha: number): void;
/**
* Clear buffers
* @param color - Clear color buffer
* @param depth - Clear depth buffer
* @param stencil - Clear stencil buffer
*/
clear(color?: boolean, depth?: boolean, stencil?: boolean): void;
/**
* Clear color buffer
*/
clearColor(): void;
/**
* Clear depth buffer
*/
clearDepth(): void;
/**
* Clear stencil buffer
*/
clearStencil(): void;
/**
* Dispose renderer resources
*/
dispose(): void;
/**
* Render scene with camera
* @param scene - Scene to render
* @param camera - Camera for rendering
*/
render(scene: Scene, camera: Camera): void;
/**
* Get active cube face
* @returns Active cube face index
*/
getActiveCubeFace(): number;
/**
* Get active mipmap level
* @returns Active mipmap level
*/
getActiveMipmapLevel(): number;
/**
* Get render target
* @returns Current render target or null
*/
getRenderTarget(): WebGLRenderTarget | null;
/**
* Set render target
* @param renderTarget - Render target or null for canvas
* @param activeCubeFace - Active cube face (for cube targets)
* @param activeMipmapLevel - Active mipmap level
*/
setRenderTarget(
renderTarget: WebGLRenderTarget | null,
activeCubeFace?: number,
activeMipmapLevel?: number
): void;
/**
* Read pixels from framebuffer
* @param x - X coordinate
* @param y - Y coordinate
* @param width - Read width
* @param height - Read height
* @param buffer - Target buffer
* @param activeCubeFaceIndex - Cube face index (optional)
*/
readRenderTargetPixels(
renderTarget: WebGLRenderTarget,
x: number,
y: number,
width: number,
height: number,
buffer: any,
activeCubeFaceIndex?: number
): void;
/**
* Copy framebuffer to texture
* @param texture - Target texture
* @param position - Copy position
* @param srcRegion - Source region (optional)
*/
copyFramebufferToTexture(texture: Texture, position: Vector2, srcRegion?: Vector4): void;
/**
* Copy texture to texture
* @param srcTexture - Source texture
* @param dstTexture - Destination texture
* @param srcRegion - Source region (optional)
* @param dstPosition - Destination position (optional)
* @param level - Mipmap level (optional)
*/
copyTextureToTexture(
srcTexture: Texture,
dstTexture: Texture,
srcRegion?: Vector4,
dstPosition?: Vector2,
level?: number
): void;
/**
* Copy texture to 3D texture
* @param srcTexture - Source texture
* @param dstTexture - Destination 3D texture
* @param srcRegion - Source region (optional)
* @param dstPosition - Destination position (optional)
* @param level - Mipmap level (optional)
*/
copyTextureToTexture3D(
srcTexture: Texture,
dstTexture: Texture,
srcRegion?: Vector4,
dstPosition?: Vector3,
level?: number
): void;
/**
* Initialize texture
* @param texture - Texture to initialize
*/
initTexture(texture: Texture): void;
/**
* Reset GL state
*/
resetState(): void;
}Usage Examples:
import { WebGLRenderer, Scene, PerspectiveCamera, Color } from 'three';
// Basic renderer setup
const renderer = new WebGLRenderer({
antialias: true,
alpha: true
});
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setPixelRatio(window.devicePixelRatio);
document.body.appendChild(renderer.domElement);
// Rendering configuration
renderer.setClearColor(new Color(0x000000), 0);
renderer.shadowMap.enabled = true;
renderer.shadowMap.type = THREE.PCFSoftShadowMap;
renderer.outputColorSpace = THREE.SRGBColorSpace;
// Tone mapping
renderer.toneMapping = THREE.ACESFilmicToneMapping;
renderer.toneMappingExposure = 1.0;
// Render loop
function animate() {
renderer.render(scene, camera);
requestAnimationFrame(animate);
}
// Handle resize
function onWindowResize() {
camera.aspect = window.innerWidth / window.innerHeight;
camera.updateProjectionMatrix();
renderer.setSize(window.innerWidth, window.innerHeight);
}Render Targets
Framebuffer objects for off-screen rendering, post-processing, and render-to-texture effects.
import {
RenderTarget,
WebGLRenderTarget,
WebGL3DRenderTarget,
WebGLArrayRenderTarget,
WebGLCubeRenderTarget,
Texture,
DepthTexture,
EventDispatcher
} from 'three';
interface RenderTargetOptions {
/** Generate mipmaps */
generateMipmaps?: boolean;
/** Magnification filter */
magFilter?: number;
/** Minification filter */
minFilter?: number;
/** Texture format */
format?: number;
/** Texture type */
type?: number;
/** Internal format */
internalFormat?: string | null;
/** S-axis wrapping */
wrapS?: number;
/** T-axis wrapping */
wrapT?: number;
/** Anisotropy level */
anisotropy?: number;
/** Color space */
colorSpace?: string;
/** Enable depth buffer */
depthBuffer?: boolean;
/** Enable stencil buffer */
stencilBuffer?: boolean;
/** Resolve depth buffer */
resolveDepthBuffer?: boolean;
/** Resolve stencil buffer */
resolveStencilBuffer?: boolean;
/** Depth texture */
depthTexture?: DepthTexture | null;
/** MSAA samples */
samples?: number;
/** Color attachments count */
count?: number;
/** 3D texture depth */
depth?: number;
/** Multiview rendering */
multiview?: boolean;
}
/**
* Base render target class for off-screen rendering
*/
class RenderTarget extends EventDispatcher {
/** Type flag for render target detection */
readonly isRenderTarget: true;
/** Render target width */
width: number;
/** Render target height */
height: number;
/** Render target depth (for 3D targets) */
depth: number;
/** Scissor test region */
scissor: Vector4;
/** Enable scissor test */
scissorTest: boolean;
/** Viewport region */
viewport: Vector4;
/** Color attachments */
textures: Texture[];
/** Depth texture */
depthTexture: DepthTexture | null;
/** Number of MSAA samples */
samples: number;
/** Multiview flag */
multiview: boolean;
/**
* Create render target
* @param width - Target width (default: 1)
* @param height - Target height (default: 1)
* @param options - Configuration options
*/
constructor(width?: number, height?: number, options?: RenderTargetOptions);
/**
* Set size of render target
* @param width - New width
* @param height - New height
* @param depth - New depth (for 3D targets)
* @returns This render target for chaining
*/
setSize(width: number, height: number, depth?: number): this;
/**
* Clone render target
* @returns Cloned render target
*/
clone(): this;
/**
* Copy properties from another render target
* @param source - Source render target
* @returns This render target for chaining
*/
copy(source: RenderTarget): this;
/**
* Dispose render target resources
*/
dispose(): void;
}
/**
* WebGL render target for 2D off-screen rendering
*/
class WebGLRenderTarget extends RenderTarget {
/** Type flag for WebGL render target detection */
readonly isWebGLRenderTarget: true;
/**
* Create WebGL render target
* @param width - Target width (default: 1)
* @param height - Target height (default: 1)
* @param options - Configuration options
*/
constructor(width?: number, height?: number, options?: RenderTargetOptions);
}
/**
* WebGL 3D render target for volume rendering
*/
class WebGL3DRenderTarget extends WebGLRenderTarget {
/** Type flag for WebGL 3D render target detection */
readonly isWebGL3DRenderTarget: true;
/**
* Create WebGL 3D render target
* @param width - Target width (default: 1)
* @param height - Target height (default: 1)
* @param depth - Target depth (default: 1)
* @param options - Configuration options
*/
constructor(width?: number, height?: number, depth?: number, options?: RenderTargetOptions);
}
/**
* WebGL array render target for layered rendering
*/
class WebGLArrayRenderTarget extends WebGLRenderTarget {
/** Type flag for WebGL array render target detection */
readonly isWebGLArrayRenderTarget: true;
/**
* Create WebGL array render target
* @param width - Target width (default: 1)
* @param height - Target height (default: 1)
* @param depth - Array layers (default: 1)
* @param options - Configuration options
*/
constructor(width?: number, height?: number, depth?: number, options?: RenderTargetOptions);
}
/**
* WebGL cube render target for environment mapping
*/
class WebGLCubeRenderTarget extends WebGLRenderTarget {
/** Type flag for WebGL cube render target detection */
readonly isWebGLCubeRenderTarget: true;
/**
* Create WebGL cube render target
* @param size - Cube face size (default: 1)
* @param options - Configuration options
*/
constructor(size?: number, options?: RenderTargetOptions);
/**
* Convert to cube texture from equirectangular
* @param renderer - WebGL renderer
* @param texture - Source equirectangular texture
* @returns Converted cube texture
*/
fromEquirectangularTexture(renderer: WebGLRenderer, texture: Texture): this;
/**
* Clear render target
* @param renderer - WebGL renderer
* @param color - Clear color
* @param depth - Clear depth
* @param stencil - Clear stencil
*/
clear(renderer: WebGLRenderer, color?: boolean, depth?: boolean, stencil?: boolean): void;
}Usage Examples:
import {
WebGLRenderer,
WebGLRenderTarget,
WebGLCubeRenderTarget,
Scene,
Camera,
RGBAFormat,
FloatType,
LinearFilter
} from 'three';
// Basic render target for post-processing
const renderTarget = new WebGLRenderTarget(512, 512, {
format: RGBAFormat,
type: FloatType,
minFilter: LinearFilter,
magFilter: LinearFilter,
generateMipmaps: false
});
// Render to texture
renderer.setRenderTarget(renderTarget);
renderer.render(scene, camera);
renderer.setRenderTarget(null); // Back to canvas
// Use rendered texture
const renderedTexture = renderTarget.texture;
material.map = renderedTexture;
// Cube render target for environment mapping
const cubeRenderTarget = new WebGLCubeRenderTarget(256);
const cubeCamera = new CubeCamera(1, 1000, cubeRenderTarget);
// Update cube map
cubeCamera.position.copy(reflectiveObject.position);
cubeCamera.update(renderer, scene);
// Use environment map
material.envMap = cubeRenderTarget.texture;
// Multi-target rendering (WebGL2)
const colorTarget = new WebGLRenderTarget(512, 512);
const depthTarget = new WebGLRenderTarget(512, 512, {
format: DepthFormat,
type: UnsignedIntType
});
// HDR render target
const hdrTarget = new WebGLRenderTarget(1024, 1024, {
type: FloatType,
format: RGBAFormat,
generateMipmaps: false
});WebGL Utilities and Extensions
Supporting classes for WebGL functionality and extension management.
import {
WebGLCapabilities,
WebGLExtensions,
WebGLProperties,
WebGLState,
WebGLInfo
} from 'three';
/**
* WebGL capabilities detection and limits
*/
class WebGLCapabilities {
/** WebGL version (1 or 2) */
readonly isWebGL2: boolean;
/** Precision settings */
precision: string;
/** Maximum texture size */
maxTextures: number;
maxVertexTextures: number;
maxTextureSize: number;
maxCubemapSize: number;
maxAttributes: number;
maxVertexUniforms: number;
maxVaryings: number;
maxFragmentUniforms: number;
/** Feature support */
vertexTextures: boolean;
floatFragmentTextures: boolean;
floatVertexTextures: boolean;
maxSamples: number;
/**
* Get maximum precision
* @param precision - Requested precision
* @returns Supported precision
*/
getMaxPrecision(precision: string): string;
}
/**
* WebGL extensions manager
*/
class WebGLExtensions {
/**
* Get WebGL extension
* @param name - Extension name
* @returns Extension object or null
*/
get(name: string): any;
/**
* Check if extension exists
* @param name - Extension name
* @returns True if extension available
*/
has(name: string): boolean;
}
/**
* WebGL state management
*/
class WebGLState {
/** Current GL state */
buffers: {
color: WebGLColorBuffer;
depth: WebGLDepthBuffer;
stencil: WebGLStencilBuffer;
};
/**
* Enable GL capability
* @param id - GL constant
*/
enable(id: number): void;
/**
* Disable GL capability
* @param id - GL constant
*/
disable(id: number): void;
/**
* Set blend function
* @param src - Source factor
* @param dst - Destination factor
* @param srcAlpha - Source alpha factor
* @param dstAlpha - Destination alpha factor
*/
setBlending(
blending: number,
blendEquation?: number,
blendSrc?: number,
blendDst?: number,
blendEquationAlpha?: number,
blendSrcAlpha?: number,
blendDstAlpha?: number,
premultipliedAlpha?: boolean
): void;
/**
* Set material properties
* @param material - Material object
* @param frontFaceCW - Front face winding
*/
setMaterial(material: Material, frontFaceCW: boolean): void;
/**
* Set flip sided
* @param flipSided - Flip faces
*/
setFlipSided(flipSided: boolean): void;
/**
* Set cull face
* @param cullFace - Cull face mode
*/
setCullFace(cullFace: number): void;
/**
* Set line width
* @param width - Line width
*/
setLineWidth(width: number): void;
/**
* Set polygon offset
* @param polygonOffset - Enable offset
* @param factor - Offset factor
* @param units - Offset units
*/
setPolygonOffset(polygonOffset: boolean, factor?: number, units?: number): void;
/**
* Reset WebGL state
*/
reset(): void;
}
/**
* Renderer performance info
*/
class WebGLInfo {
/** Auto reset per frame */
autoReset: boolean;
/** Memory usage */
memory: {
geometries: number;
textures: number;
};
/** Render statistics */
render: {
frame: number;
calls: number;
triangles: number;
points: number;
lines: number;
};
/** Program count */
programs: WebGLProgram[] | null;
/**
* Update render statistics
* @param count - Triangle/point/line count
* @param mode - Drawing mode
* @param instanceCount - Instance count
*/
update(count: number, mode: number, instanceCount: number): void;
/**
* Reset statistics
*/
reset(): void;
}Usage Examples:
// Check WebGL capabilities
const capabilities = renderer.capabilities;
console.log('WebGL2:', capabilities.isWebGL2);
console.log('Max texture size:', capabilities.maxTextureSize);
console.log('Float textures:', capabilities.floatFragmentTextures);
// Check extensions
const extensions = renderer.extensions;
const vaoExt = extensions.get('OES_vertex_array_object');
const anisotropy = extensions.get('EXT_texture_filter_anisotropic');
// Monitor performance
const info = renderer.info;
console.log('Draw calls:', info.render.calls);
console.log('Triangles:', info.render.triangles);
console.log('Geometries in memory:', info.memory.geometries);
// Manual state management
const state = renderer.state;
state.setBlending(NoBlending);
state.setCullFace(CullFaceBack);
state.setLineWidth(2);Post-processing Support
import { PMREMGenerator, WebGLRenderer, Texture, CubeTexture } from 'three';
/**
* Pre-filtered environment map generator for IBL
*/
class PMREMGenerator {
/**
* Create PMREM generator
* @param renderer - WebGL renderer
*/
constructor(renderer: WebGLRenderer);
/**
* Generate PMREM from cube texture
* @param cubeTexture - Source cube texture
* @param samples - Sample count (optional)
* @returns Generated render target
*/
fromCubemap(cubeTexture: CubeTexture, samples?: number): WebGLRenderTarget;
/**
* Generate PMREM from equirectangular texture
* @param equirectangular - Source equirectangular texture
* @param samples - Sample count (optional)
* @returns Generated render target
*/
fromEquirectangular(equirectangular: Texture, samples?: number): WebGLRenderTarget;
/**
* Generate PMREM from scene
* @param scene - Source scene
* @param sigma - Roughness value
* @param near - Camera near plane
* @param far - Camera far plane
* @returns Generated render target
*/
fromScene(scene: Scene, sigma?: number, near?: number, far?: number): WebGLRenderTarget;
/**
* Compile equirectangular shader
* @returns Compiled shader
*/
compileCubemapShader(): void;
/**
* Compile equirectangular shader
* @returns Compiled shader
*/
compileEquirectangularShader(): void;
/**
* Dispose generator resources
*/
dispose(): void;
}Usage Examples:
// Environment map processing
const pmremGenerator = new PMREMGenerator(renderer);
pmremGenerator.compileEquirectangularShader();
// From equirectangular texture
const envMap = textureLoader.load('environment.hdr');
const envMapRT = pmremGenerator.fromEquirectangular(envMap);
scene.environment = envMapRT.texture;
// From cube texture
const cubeTexture = cubeLoader.load([...]);
const cubeRT = pmremGenerator.fromCubemap(cubeTexture);
scene.environment = cubeRT.texture;
// Cleanup
pmremGenerator.dispose();The rendering system provides comprehensive WebGL-based graphics output with extensive configuration options, off-screen rendering capabilities, and performance monitoring tools. The WebGL renderer serves as the primary interface for converting 3D scenes into rendered images with full material and lighting support.
Install with Tessl CLI
npx tessl i tessl/npm-three