常量与配置

本页文档介绍了 Three.js 中的常量系统,该系统提供了整个库中用于配置渲染行为、材质属性、纹理参数和其他 3D 场景管理方面的命名数值和字符串标识符。这些常量确保了类型安全的配置,并通过用语义名称替换魔数来提高代码可读性。

关于材质如何使用这些常量的信息,请参阅材质与纹理系统。关于渲染器特定配置,请参阅 WebGL 渲染管线。

用途和组织

Three.js 常量在单个源文件中定义并导出为数值或字符串。它们配置:

渲染管线行为(剔除、混合、深度测试)
纹理采样和包装模式
像素格式和数据类型
色彩空间转换
材质外观参数
动画和插值模式

所有常量都是可以从主 Three.js 模块导入的不可变导出。常量系统允许开发人员配置复杂的渲染行为,而无需记忆数值 WebGL 枚举值。

常量系统架构

100%

渲染配置常量

面剔除

根据环绕顺序控制渲染哪些三角形面。这些常量确定 GPU 级别的剔除优化。

Constant	Value	Description
`CullFaceNone`	`0`	Disables face culling (renders both sides)
`CullFaceBack`	`1`	Culls back faces (default behavior)
`CullFaceFront`	`2`	Culls front faces
`CullFaceFrontBack`	`3`	Culls both front and back faces

使用上下文: 设置在 Material.side 属性上作为 FrontSide、BackSide 或 DoubleSide,它们内部映射到剔除模式。

阴影贴图类型

定义具有不同质量和性能特征的阴影渲染算法。

Constant	Value	Description
`BasicShadowMap`	`0`	Unfiltered shadow maps (fastest)
`PCFShadowMap`	`1`	Percentage-Closer Filtering
`PCFSoftShadowMap`	`2`	PCF with better soft shadows
`VSMShadowMap`	`3`	Variance Shadow Maps

使用上下文: 设置在 WebGLRenderer.shadowMap.type 上以配置阴影渲染质量。

侧面常量

确定渲染几何体的哪些面。

Constant	Value	Description
`FrontSide`	`0`	Render only front-facing triangles
`BackSide`	`1`	Render only back-facing triangles
`DoubleSide`	`2`	Render both front and back faces

混合模式

100%

混合模式常量:

Constant	Value	Behavior
`NoBlending`	`0`	Disables alpha transparency
`NormalBlending`	`1`	Standard alpha blending (default)
`AdditiveBlending`	`2`	Adds source and destination colors
`SubtractiveBlending`	`3`	Subtracts destination from source
`MultiplyBlending`	`4`	Multiplies colors
`CustomBlending`	`5`	Requires manual equation/factor setup
`MaterialBlending`	`6`	Material-specific blending

使用上下文: 设置在 Material.blending 上以控制透明度行为。自定义混合需要通过 Material.blendEquation、Material.blendSrc 和 Material.blendDst 进行额外配置。

深度测试

控制片段如何通过或未通过深度缓冲区比较。

Constant	Value	Description
`NeverDepth`	`0`	Never pass depth test
`AlwaysDepth`	`1`	Always pass depth test
`LessDepth`	`2`	Pass if incoming < buffer
`LessEqualDepth`	`3`	Pass if incoming ≤ buffer (default)
`EqualDepth`	`4`	Pass if incoming == buffer
`GreaterEqualDepth`	`5`	Pass if incoming ≥ buffer
`GreaterDepth`	`6`	Pass if incoming > buffer
`NotEqualDepth`	`7`	Pass if incoming ≠ buffer

使用上下文: 设置在 Material.depthFunc 上以自定义深度测试行为。

纹理配置常量

纹理映射模式

定义纹理如何映射到几何体表面。

Constant	Value	Type	Description
`UVMapping`	`300`	number	Standard UV coordinate mapping
`CubeReflectionMapping`	`301`	number	Cube environment reflection
`CubeRefractionMapping`	`302`	number	Cube environment refraction
`EquirectangularReflectionMapping`	`303`	number	Equirectangular reflection
`EquirectangularRefractionMapping`	`304`	number	Equirectangular refraction
`CubeUVReflectionMapping`	`306`	number	PMREM cube UV reflection

纹理包装

控制纹理坐标超出 [0, 1] 范围时的行为。

Constant	Value	Description
`RepeatWrapping`	`1000`	Texture repeats infinitely
`ClampToEdgeWrapping`	`1001`	Edge pixels stretch to boundary
`MirroredRepeatWrapping`	`1002`	Texture repeats with mirroring

使用上下文: 设置在 Texture.wrapS 和 Texture.wrapT 属性上。

纹理过滤

100%

过滤常量:

Constant	Value	Description
`NearestFilter`	`1003`	Point sampling (no interpolation)
`NearestMipmapNearestFilter`	`1004`	Nearest mip level, point sample
`NearestMipmapLinearFilter`	`1005`	Interpolate between mip levels, point sample
`LinearFilter`	`1006`	Bilinear interpolation
`LinearMipmapNearestFilter`	`1007`	Nearest mip level, bilinear sample
`LinearMipmapLinearFilter`	`1008`	Trilinear filtering (best quality)

纹理数据类型

定义纹理像素分量的数据类型。

常量	值	描述
`UnsignedByteType`	`1009`	8 位无符号整数
`ByteType`	`1010`	8 位有符号整数
`ShortType`	`1011`	16 位有符号整数
`UnsignedShortType`	`1012`	16 位无符号整数
`IntType`	`1013`	32 位有符号整数
`UnsignedIntType`	`1014`	32 位无符号整数
`FloatType`	`1015`	32 位浮点数
`HalfFloatType`	`1016`	16 位浮点数
`UnsignedShort4444Type`	`1017`	打包 4-4-4-4 格式
`UnsignedShort5551Type`	`1018`	打包 5-5-5-1 格式
`UnsignedInt248Type`	`1020`	打包深度-模板格式
`UnsignedInt5999Type`	`35902`	打包 5-9-9-9 HDR 格式
`UnsignedInt101111Type`	`35899`	打包 10-11-11 格式

使用上下文: 设置在 Texture.type 上以指定像素分量精度和编码。

纹理格式

定义通道布局和压缩的广泛格式常量:

类别	示例常量	值范围
基本格式	`AlphaFormat`、`RGBFormat`、`RGBAFormat`	`1021-1023`
深度格式	`DepthFormat`、`DepthStencilFormat`	`1026-1027`
整数格式	`RedIntegerFormat`、`RGBAIntegerFormat`	`1029-1033`
压缩 DXT	`RGB_S3TC_DXT1_Format`、`RGBA_S3TC_DXT5_Format`	`33776-33779`
压缩 PVRTC	`RGB_PVRTC_4BPPV1_Format`、`RGBA_PVRTC_2BPPV1_Format`	`35840-35843`
压缩 ETC	`RGB_ETC1_Format`、`RGBA_ETC2_EAC_Format`	`36196-37496`
压缩 ASTC	`RGBA_ASTC_4x4_Format` ... `RGBA_ASTC_12x12_Format`	`37808-37821`
压缩 BPTC	`RGBA_BPTC_Format`、`RGB_BPTC_UNSIGNED_Format`	`36492-36495`
压缩 RGTC	`RED_RGTC1_Format`、`RED_GREEN_RGTC2_Format`	`36283-36286`

材质配置常量

法线贴图类型

Constant	Value	Description
`TangentSpaceNormalMap`	`0`	Normals relative to surface (default)
`ObjectSpaceNormalMap`	`1`	Normals relative to object

法线贴图打包

常量	值	类型	描述
`NoNormalPacking`	`""`	string	无特殊打包
`NormalRGPacking`	`"rg"`	string	RG 通道中的法线
`NormalGAPacking`	`"ga"`	string	GA 通道中的法线

深度打包

定义渲染时深度值的编码方式。

常量	值	描述
`BasicDepthPacking`	`3200`	反向深度 (1.0 - z)
`RGBADepthPacking`	`3201`	32 位 RGBA 编码
`RGBDepthPacking`	`3202`	24 位 RGB 编码
`RGDepthPacking`	`3203`	16 位 RG 编码

色彩空间常量

Three.js 使用字符串标识符表示色彩空间,以匹配 CSS Color Module Level 4 和 WebGPU 规范。

100%

色彩空间常量:

Constant	Value	Description
`NoColorSpace`	`""`	No color space defined
`SRGBColorSpace`	`"srgb"`	Standard sRGB color space
`LinearSRGBColorSpace`	`"srgb-linear"`	Linear sRGB (no gamma curve)

传递函数常量:

常量	值	描述
`LinearTransfer`	`"linear"`	线性传递函数
`SRGBTransfer`	`"srgb"`	sRGB gamma 传递函数

使用上下文: 设置在 Texture.colorSpace 和 WebGLRenderer.outputColorSpace 上,以确保在整个渲染管线中正确的色彩管理。

色调映射常量

定义将 HDR 值映射到显示范围的算法。

Constant	Value	Description
`NoToneMapping`	`0`	No tone mapping applied
`LinearToneMapping`	`1`	Simple linear mapping
`ReinhardToneMapping`	`2`	Reinhard operator
`CineonToneMapping`	`3`	Cineon filmic curve
`ACESFilmicToneMapping`	`4`	ACES filmic curve
`CustomToneMapping`	`5`	User-defined in shader
`AgXToneMapping`	`6`	AgX tone mapper
`NeutralToneMapping`	`7`	Khronos neutral tone mapper

使用上下文: 设置在 WebGLRenderer.toneMapping 上以控制 HDR 到 LDR 的转换。

动画常量

循环模式

Constant	Value	Description
`LoopOnce`	`2200`	Play animation once
`LoopRepeat`	`2201`	Loop from end to start
`LoopPingPong`	`2202`	Alternate forward/backward

插值模式

Constant	Value	Description
`InterpolateDiscrete`	`2300`	No interpolation (stepped)
`InterpolateLinear`	`2301`	Linear interpolation
`InterpolateSmooth`	`2302`	Smooth cubic interpolation
`InterpolateBezier`	`2303`	Bezier curve interpolation

结束行为

Constant	Value	Description
`ZeroCurvatureEnding`	`2400`	Zero curvature at endpoints
`ZeroSlopeEnding`	`2401`	Zero slope at endpoints
`WrapAroundEnding`	`2402`	Wrap to beginning

混合模式

Constant	Value	Description
`NormalAnimationBlendMode`	`2500`	Standard blending (default)
`AdditiveAnimationBlendMode`	`2501`	Additive layer blending

模板操作常量

模板操作

Constant	Value	GL Enum	Description
`ZeroStencilOp`	`0`	-	Set stencil to 0
`KeepStencilOp`	`7680`	`GL_KEEP`	Keep current value
`ReplaceStencilOp`	`7681`	`GL_REPLACE`	Replace with reference
`IncrementStencilOp`	`7682`	`GL_INCR`	Increment (clamped)
`DecrementStencilOp`	`7683`	`GL_DECR`	Decrement (clamped)
`IncrementWrapStencilOp`	`34055`	`GL_INCR_WRAP`	Increment (wrapped)
`DecrementWrapStencilOp`	`34056`	`GL_DECR_WRAP`	Decrement (wrapped)
`InvertStencilOp`	`5386`	`GL_INVERT`	Bitwise invert

Stencil Comparison Functions

Constant	Value	GL Enum	Description
`NeverStencilFunc`	`512`	`GL_NEVER`	Never pass
`LessStencilFunc`	`513`	`GL_LESS`	Pass if ref < stencil
`EqualStencilFunc`	`514`	`GL_EQUAL`	Pass if ref == stencil
`LessEqualStencilFunc`	`515`	`GL_LEQUAL`	Pass if ref ≤ stencil
`GreaterStencilFunc`	`516`	`GL_GREATER`	Pass if ref > stencil
`NotEqualStencilFunc`	`517`	`GL_NOTEQUAL`	Pass if ref ≠ stencil
`GreaterEqualStencilFunc`	`518`	`GL_GEQUAL`	Pass if ref ≥ stencil
`AlwaysStencilFunc`	`519`	`GL_ALWAYS`	Always pass

Drawing Mode Constants

Defines how vertex data is interpreted for rendering.

Constant	Value	Description
`TrianglesDrawMode`	`0`	Every 3 vertices form a triangle
`TriangleStripDrawMode`	`1`	Strip of connected triangles
`TriangleFanDrawMode`	`2`	Fan of triangles from first vertex

使用上下文: 设置在 BufferGeometry.drawMode 上(已弃用)或用于自定义绘制调用。

杂项常量

绑定模式

Constant	Value	Type	Description
`AttachedBindMode`	`"attached"`	string	Skinned mesh shares skeleton space
`DetachedBindMode`	`"detached"`	string	Skinned mesh independent of skeleton

环境贴图操作

Constant	Value	Description
`MultiplyOperation`	`0`	Multiply env map with surface color
`MixOperation`	`1`	Blend using reflectivity
`AddOperation`	`2`	Add env map to surface color

Input Control Constants

Constant	Properties	Description
`MOUSE`	`{LEFT: 0, MIDDLE: 1, RIGHT: 2, ROTATE: 0, DOLLY: 1, PAN: 2}`	Mouse button mappings for controls
`TOUCH`	`{ROTATE: 0, PAN: 1, DOLLY_PAN: 2, DOLLY_ROTATE: 3}`	Touch gesture types

Version

Constant	Value	Description
`REVISION`	`"183dev"`	Current Three.js version string

使用模式

材质配置

// 典型材质设置示例
material.side = FrontSide;           // 仅渲染正面
material.blending = NormalBlending;  // 标准 alpha 混合
material.depthFunc = LessEqualDepth; // 默认深度测试
material.transparent = true;          // 启用 alpha 混合

常量通常作为命名导入访问:

import { 
    FrontSide, 
    DoubleSide,
    NormalBlending,
    AdditiveBlending,
    RepeatWrapping,
    LinearFilter
} from 'three';

纹理配置

// 典型纹理设置示例
texture.wrapS = RepeatWrapping;
texture.wrapT = RepeatWrapping;
texture.magFilter = LinearFilter;
texture.minFilter = LinearMipmapLinearFilter;
texture.colorSpace = SRGBColorSpace;

渲染器配置

// 典型渲染器设置示例
renderer.shadowMap.enabled = true;
renderer.shadowMap.type = PCFSoftShadowMap;
renderer.toneMapping = ACESFilmicToneMapping;
renderer.outputColorSpace = SRGBColorSpace;

常量与配置 ​

用途和组织 ​

常量系统架构 ​

渲染配置常量 ​

面剔除 ​

阴影贴图类型 ​

侧面常量 ​

混合模式 ​

深度测试 ​

纹理配置常量 ​

纹理映射模式 ​

纹理包装 ​

纹理过滤 ​

纹理数据类型 ​

纹理格式 ​

材质配置常量 ​

法线贴图类型 ​

法线贴图打包 ​

深度打包 ​

色彩空间常量 ​

色调映射常量 ​

动画常量 ​

循环模式 ​

插值模式 ​

结束行为 ​

混合模式 ​

模板操作常量 ​

模板操作 ​

Stencil Comparison Functions ​

Drawing Mode Constants ​

杂项常量 ​

绑定模式 ​

环境贴图操作 ​

Input Control Constants ​

Version ​

使用模式 ​

材质配置 ​

纹理配置 ​

渲染器配置 ​

常量与配置

用途和组织

常量系统架构

渲染配置常量

面剔除

阴影贴图类型

侧面常量

混合模式

深度测试

纹理配置常量

纹理映射模式

纹理包装

纹理过滤

纹理数据类型

纹理格式

材质配置常量

法线贴图类型

法线贴图打包

深度打包

色彩空间常量

色调映射常量

动画常量

循环模式

插值模式

结束行为

混合模式

模板操作常量

模板操作

Stencil Comparison Functions

Drawing Mode Constants

杂项常量

绑定模式

环境贴图操作

Input Control Constants

Version

使用模式

材质配置

纹理配置

渲染器配置