Three.js API手册

动画
AnimationAction AnimationClip AnimationMixer AnimationObjectGroup AnimationUtils KeyframeTrack PropertyBinding PropertyMixer
动画 / 轨道
BooleanKeyframeTrack ColorKeyframeTrack NumberKeyframeTrack QuaternionKeyframeTrack StringKeyframeTrack VectorKeyframeTrack
音频
Audio AudioAnalyser AudioContext AudioListener PositionalAudio
摄像机
ArrayCamera Camera CubeCamera OrthographicCamera PerspectiveCamera StereoCamera
常量
Animation Core CustomBlendingEquation DrawModes Materials Renderer Textures
核心
BufferAttribute BufferGeometry Clock DirectGeometry EventDispatcher Face3 Geometry InstancedBufferAttribute InstancedBufferGeometry InstancedInterleavedBuffer InterleavedBuffer InterleavedBufferAttribute Layers Object3D Raycaster Uniform
核心 / BufferAttributes
BufferAttribute_Types
弃用列表
DeprecatedList
附件
Earcut ShapeUtils
附件 / 核心
Curve CurvePath Font Interpolations Path Shape ShapePath
附件 / 曲线
ArcCurve CatmullRomCurve3 CubicBezierCurve CubicBezierCurve3 EllipseCurve LineCurve LineCurve3 QuadraticBezierCurve QuadraticBezierCurve3 SplineCurve
附件 / 物体
ImmediateRenderObject
几何体
BoxBufferGeometry BoxGeometry CircleBufferGeometry CircleGeometry ConeBufferGeometry ConeGeometry CylinderBufferGeometry CylinderGeometry DodecahedronBufferGeometry DodecahedronGeometry EdgesGeometry ExtrudeBufferGeometry ExtrudeGeometry IcosahedronBufferGeometry IcosahedronGeometry LatheBufferGeometry LatheGeometry OctahedronBufferGeometry OctahedronGeometry ParametricBufferGeometry ParametricGeometry PlaneBufferGeometry PlaneGeometry PolyhedronBufferGeometry PolyhedronGeometry RingBufferGeometry RingGeometry ShapeBufferGeometry ShapeGeometry SphereBufferGeometry SphereGeometry TetrahedronBufferGeometry TetrahedronGeometry TextBufferGeometry TextGeometry TorusBufferGeometry TorusGeometry TorusKnotBufferGeometry TorusKnotGeometry TubeBufferGeometry TubeGeometry WireframeGeometry
辅助对象
ArrowHelper AxesHelper BoxHelper Box3Helper CameraHelper DirectionalLightHelper FaceNormalsHelper GridHelper PolarGridHelper PositionalAudioHelper HemisphereLightHelper PlaneHelper PointLightHelper RectAreaLightHelper SkeletonHelper SpotLightHelper VertexNormalsHelper
灯光
AmbientLight DirectionalLight HemisphereLight Light PointLight RectAreaLight SpotLight
灯光 / 阴影
DirectionalLightShadow LightShadow SpotLightShadow
加载器
AnimationLoader AudioLoader BufferGeometryLoader Cache CompressedTextureLoader CubeTextureLoader DataTextureLoader FileLoader FontLoader ImageBitmapLoader ImageLoader Loader LoaderUtils MaterialLoader ObjectLoader TextureLoader
加载器 / 管理器
DefaultLoadingManager LoadingManager
材质
LineBasicMaterial LineDashedMaterial Material MeshBasicMaterial MeshDepthMaterial MeshDistanceMaterial MeshLambertMaterial MeshMatcapMaterial MeshNormalMaterial MeshPhongMaterial MeshPhysicalMaterial MeshStandardMaterial MeshToonMaterial PointsMaterial RawShaderMaterial ShaderMaterial ShadowMaterial SpriteMaterial
数学库
Box2 Box3 Color Cylindrical Euler Frustum Interpolant Line3 Math Matrix3 Matrix4 Plane Quaternion Ray Sphere Spherical Triangle Vector2 Vector3 Vector4
数学库 / 插值
CubicInterpolant DiscreteInterpolant LinearInterpolant QuaternionLinearInterpolant
物体
Bone Group Line LineLoop LineSegments LOD Mesh Points Skeleton SkinnedMesh Sprite
渲染器
WebGLMultisampleRenderTarget WebGLRenderer WebGLRenderTarget WebGLRenderTargetCube
渲染器 / 着色器
ShaderChunk ShaderLib UniformsLib UniformsUtils
场景
Fog FogExp2 Scene
纹理贴图
CanvasTexture CompressedTexture CubeTexture DataTexture DataTexture3D DepthTexture Texture VideoTexture
在线工具推荐: Three.js AI纹理开发包 - YOLO合成数据生成器 - GLTF/GLB在线编辑 - 3D模型格式在线转换 - 可编程3D场景编辑器

WebGLRenderer

WebGL Render 用WebGL渲染出你精心制作的场景。

构造器

WebGLRenderer( parameters : Object )

parameters - (可选) 该对象的属性定义了渲染器的行为。也可以完全不传参数。在所有情况下,当缺少参数时,它将采用合理的默认值。 以下是合法参数:

canvas - 一个供渲染器绘制其输出的canvas 它和下面的domElement属性对应。 如果没有传这个参数,会创建一个新canvas
context - 可用于将渲染器附加到已有的渲染环境(RenderingContext)中。默认值是null
precision - 着色器精度. 可以是 "highp", "mediump" 或者 "lowp". 如果设备支持,默认为"highp" . 点击here 查看"应该避免的事"
alpha - canvas是否包含alpha (透明度)。默认为 false
premultipliedAlpha - renderer是否假设颜色有 premultiplied alpha. 默认为true
antialias - 是否执行抗锯齿。默认为false.
stencil - 绘图缓存是否有一个至少8位的模板缓存(stencil buffer)。默认为true
preserveDrawingBuffer -是否保留缓直到手动清除或被覆盖。 默认false.
powerPreference - 提示用户代理怎样的配置更适用于当前WebGL环境。 可能是"high-performance", "low-power""default"。默认是"default". 详见WebGL spec
depth - 绘图缓存是否有一个至少6位的深度缓存(depth buffer )。 默认是true.
logarithmicDepthBuffer - 是否使用对数深度缓存。如果要在单个场景中处理巨大的比例差异,就有必要使用。 默认是false。 示例:camera / logarithmicdepthbuffer

属性

# .autoClear : Boolean

定义渲染器是否在渲染每一帧之前自动清除其输出。

# .autoClearColor : Boolean

如果autoClear为true, 定义renderer是否清除颜色缓存。 默认是true

# .autoClearDepth : Boolean

如果autoClear是true, 定义renderer是否清除深度缓存。 默认是true

# .autoClearStencil : Boolean

如果autoClear是true, 定义renderer是否清除模板缓存. 默认是true

# .debug.checkShaderErrors : Boolean

如果checkShaderErrors为true,定义是否检查材质着色器程序 编译和链接过程中的错误。 禁用此检查生产以获得性能增益可能很有用。 强烈建议在开发期间保持启用这些检查。 如果着色器没有编译和链接 - 它将无法工作,并且相关材料将不会呈现。 默认是true

# .capabilities : Object

一个包含当前渲染环境(RenderingContext)的功能细节的对象。
- floatFragmentTextures: 环境是否支持OES_texture_float扩展。 根据WebGLStats, 截至2016年2月,超过95%的支持WebGL的设备支持此功能
- floatVertexTextures: 如果floatFragmentTextures和vertexTextures都是true, 则此值为true
- getMaxAnisotropy(): 返回最大可用各向异性。
- getMaxPrecision(): 返回顶点着色器和片元着色器的最大可用精度。
- logarithmicDepthBuffer: 如果logarithmicDepthBuffer在构造器中被设为true且 环境支持EXT_frag_depth扩展,则此值为true 根据WebGLStats, 截至2016年2月, 约66%的支持WebGL的设备支持此功能
- maxAttributes: gl.MAX_VERTEX_ATTRIBS的值
- maxCubemapSize: gl.MAX_CUBE_MAP_TEXTURE_SIZE 的值,着色器可使用的立方体贴图纹理的最大宽度*高度
- maxFragmentUniforms: gl.MAX_FRAGMENT_UNIFORM_VECTORS的值,片元着色器可使用的全局变量(uniforms)数量
- maxTextureSize: gl.MAX_TEXTURE_SIZE的值,着色器可使用纹理的最大宽度*高度
- maxTextures: *gl.MAX_TEXTURE_IMAGE_UNITS的值,着色器可使用的纹理数量
- maxVaryings: gl.MAX_VARYING_VECTORS的值,着色器可使用矢量的数量
- maxVertexTextures: gl.MAX_VERTEX_TEXTURE_IMAGE_UNITS的值,顶点着色器可使用的纹理数量。
- maxVertexUniforms: gl.MAX_VERTEX_UNIFORM_VECTORS的值,顶点着色器可使用的全局变量(uniforms)数量
- precision: 渲染器当前使用的着色器的精度
- vertexTextures: 如果# .maxVertexTextures : Integer大于0,此值为true (即可以使用顶点纹理)

# .clippingPlanes : Array

用户自定义的剪裁平面,在世界空间中被指定为THREE.Plane对象。 这些平面全局使用。空间中与该平面点积为负的点将被切掉。 默认值是[]

# .context : WebGLRenderingContext

渲染器默认使用HTMLCanvasElement.getContext()从其 domElement获取渲染环境(RenderingContext

你可以手动创建创建它,但它必须与domElement对应,才能呈现到屏幕上。

# .domElement : DOMElement

一个canvas,渲染器在其上绘制输出。
渲染器的构造函数会自动创建(如果没有传入canvas参数);你需要做的仅仅是像下面这样将它加页面里去:
document.body.appendChild( renderer.domElement );

# .extensions : Object

.extensions.get方法的包装, 用于检查是否支持各种WebGL扩展

# .gammaFactor : Float

默认是 2.

# .gammaInput : Boolean

如果设置,那么所有的纹理和颜色都会预乘gamma。 默认值是false.

# .gammaOutput : Boolean

如果设置, 那么它期望所有纹理和颜色需要乘以gamma输出。 默认值false.

# .info : Object

一个对象,包含有关图形板内存和渲染过程的一系列统计信息。这些信息可用于调试或仅仅满足下好奇心。改对象包含以下字段:

  • memory:
    • geometries
    • textures
  • render:
    • calls
    • triangles
    • points
    • lines
  • programs

默认情况下,每次调用渲染时这些数据都会重置。 但当时用一个或多个镜像时,最好使用自定义模式重置它们: renderer.info.autoReset = false; renderer.info.reset();

# .localClippingEnabled : Boolean

定义渲染器是否考虑对象级剪切平面。 默认为false.

# .maxMorphTargets : Integer

默认是8。 一个着色器中允许的最大MorphTargets数。 切记标准材质只允许8个MorphTargets。

# .maxMorphNormals : Integer

默认是4。 色器中允许的最大MorphNormal数。 切记标准材质只允许4个MorphNormal。

# .physicallyCorrectLights : Boolean

是否使用物理上正确的光照模式。 默认是false。 示例:lights / physical

# .properties : Object

渲染器内部使用,以跟踪各种子对象属性。

# .renderLists : WebGLRenderLists

在内部用于处理场景渲染对象的排序。

# .shadowMap : WebGLShadowMap

如果使用,它包含阴影贴图的引用。

# .shadowMap.enabled : Boolean

如果设置, 请在场景中使用阴影贴图。 默认是 false

# .shadowMap.autoUpdate : Boolean

启用场景中的阴影自动更新。默认是true

如果不需要动态光照/阴影, 则可以在实例化渲染器时将之设为false

# .shadowMap.needsUpdate : Boolean

当被设为true, 场景中的阴影贴图会在下次render调用时刷新。默认是false

如果你已经禁用了阴影贴图的自动更新(shadowMap.autoUpdate = false), 那么想要在下一次渲染时更新阴影的话就需要将此值设为true

# .shadowMap.type : Integer

定义阴影贴图类型 (未过滤, 关闭部分过滤, 关闭部分双线性过滤)

可选值有THREE.BasicShadowMap, THREE.PCFShadowMap (默认), THREE.PCFSoftShadowMap。 详见Renderer constants

# .sortObjects : Boolean

定义渲染器是否应对对象进行排序。默认是true.

说明: 排序用于尝试正确渲染出具有一定透明度的对象。根据定义,排序可能不总是有用。根据应用的需求,可能需要关闭排序并使其他方法来处理透明度的渲染,例如, 手动确定每个对象的显然顺序。

# .state : Object

包含设置WebGLRenderer.context状态的各种属性的函数。

# .toneMapping : Constant

默认是LinearToneMapping。查看Renderer constants以获取其它备选项

# .toneMappingExposure : Number

色调映射的曝光级别。默认是1

# .toneMappingWhitePoint : Number

色调映射的白点。默认是1

方法

# .clear ( color : Boolean, depth : Boolean, stencil : Boolean ) : null

告诉渲染器清除颜色、深度或模板缓存. 此方法将颜色缓存初始化为当前颜色。参数们默认都是true

# .clearColor ( ) : null

清除颜色缓存。 相当于调用.clear( true, false, false )

# .clearDepth ( ) : null

清除深度缓存。相当于调用.clear( false, true, false )

# .clearStencil ( ) : null

清除模板缓存。相当于调用.clear( false, false, true )

# .clearTarget (renderTarget : WebGLRenderTarget, color : boolean, depth : boolean, stencil : boolean) : null

renderTarget -- 需要被清除的renderTarget
color -- 如果设置, 颜色会被清除
depth -- 如果设置, 深度缓存会被清除
stencil -- 如果设置, 模板缓存会被清除

该方法清楚了一个rendertarget。为此它会激活此endertarget

# .compile ( scene : Scene, camera : Camera ) : null

使用相机编译场景中的所有材质。这对于在首次渲染之前预编译着色器很有用。

# .copyFramebufferToTexture ( position : Vector2, texture : Texture, level : Number ) : null

将当前WebGLFramebuffer中的像素复制到2D纹理中。可访问WebGLRenderingContext.copyTexImage2D.

# .copyTextureToTexture ( position : Vector2, srcTexture : Texture, dstTexture : Texture, level : Number ) : null

将纹理的所有像素复制到一个已有的从给定位置开始的纹理中。可访问WebGLRenderingContext.texSubImage2D.

# .dispose ( ) : null

处理当前的渲染环境

# .extensions.get ( extensionName : String ) : Object

用于检查是否支持各种扩展,并返回一个对象,其中包含扩展的详细信息。 该方法检查以下扩展:

- WEBGL_depth_texture
- EXT_texture_filter_anisotropic
- WEBGL_compressed_texture_s3tc
- WEBGL_compressed_texture_pvrtc
- WEBGL_compressed_texture_etc1

# .forceContextLoss ( ) : null

模拟WebGL环境的丢失。需要支持 WEBGL_lose_context扩展才能用。 根据WebGLStats, as of February 2016 90% of WebGL enabled devices support this.

# .getClearAlpha () : Float

返回一个表示当前alpha值的float,范围0到1

# .getClearColor () : Color

返回一个表示当前颜色值的THREE.Color实例

# .getContext () : WebGLRenderingContext

返回当前WebGL环境

# .getContextAttributes () : WebGLContextAttributes

返回一个对象,这个对象中存有在WebGL环境在创建的时候所设置的属性

# .getRenderTarget () : RenderTarget

如果当前存在RenderTarget,返回当前它

# .getCurrentViewport () : RenderTarget

返回当前视口

# .getDrawingBufferSize () : Object

返回一个包含渲染器绘图缓存宽度和高度(单位像素)的对象。

# .getPixelRatio () : number

返回当前使用设备像素比

# .getSize () : Object

返回包含渲染器输出canvas的宽度和高度(单位像素)的对象。

# .resetGLState ( ) : null

将GL状态重置为默认值。WebGL环境丢失时会内部调用

# .readRenderTargetPixels ( renderTarget : WebGLRenderTarget, x : Float, y : Float, width : Float, height : Float, buffer ) : null

将enderTarget中的像素数据读取到传入的缓冲区中。这是WebGLRenderingContext.readPixels()的包装器
示例:interactive / cubes / gpu

# .render ( scene : Scene, camera : Camera, renderTarget : WebGLRenderTarget, forceClear : Boolean ) : null

用相机(camera)渲染一个场景(scene)
渲染一般是在canvas上完成的,或者是renderTarget(如果有指定)
如果forceClear值是true,那么颜色、深度及模板缓存将会在渲染之前清除,即使渲染器的autoClear属性值是false
即便forceClear设为true, 也可以通过将autoClearColor、autoClearStencil或autoClearDepth属性的值设为false来阻止对应缓存被清除。

# .renderBufferDirect ( camera : Camera, fog : Fog, geometry : Geometry, material : Material, object : Object3D, group : Object ) : null

使用相机和指定材质渲染缓冲几何组。

# .renderBufferImmediate ( object : Object3D, program : shaderprogram, shading : Material ) : null

object - 一个Object3D实例
program - 一个shaderProgram实例
shading - 一个Material实例

渲染即使缓冲,由enderImmediateObject对象调用

# .setAnimationLoop ( callback : Function ) : null

callback — 每个可用帧都会调用的函数。 如果传入‘null’,所有正在进行的动画都会停止。

可用来代替requestAnimationFrame的内置函数. 对于WebVR项目,必须使用此函数。

# .setClearAlpha ( alpha : Float ) : null

设置alpha。合法参数是一个0.01.0之间的浮点数

# .setClearColor ( color : Color, alpha : Float ) : null

设置颜色及其透明度

# .setPixelRatio ( value : number ) : null

设置设备像素比。通常用于避免HiDPI设备上绘图模糊

# .setRenderTarget ( renderTarget : WebGLRenderTarget, activeCubeFace : Integer, activeMipMapLevel : Integer ) : null

renderTarget -- 需要被激活的renderTarget(可选).
activeCubeFace -- Specifies the active cube side (PX 0, NX 1, PY 2, NY 3, PZ 4, NZ 5) of WebGLRenderTargetCube (optional).
activeMipMapLevel -- Specifies the active mipmap level (optional).

该方法设置活跃rendertarget. 参数缺省则将canvas设置成活跃rendertarget

# .setScissor ( x : Integer, y : Integer, width : Integer, height : Integer ) : null

将剪裁区域设为(x, y)到(x + width, y + height) Sets the scissor area from

# .setScissorTest ( boolean : Boolean ) : null

启用或禁用剪裁检测. 若启用,则只有在所定义的裁剪区域内的像素才会受之后的渲染器影响。

# .setSize ( width : Integer, height : Integer, updateStyle : Boolean ) : null

将输出canvas的大小调整为(width, height)并考虑设备像素比,且将视口从(0, 0)开始调整到适合大小 将updateStyle设置为false以阻止对canvas的样式做任何改变。

# .setViewport ( x : Integer, y : Integer, width : Integer, height : Integer ) : null

将视口大小设置为(x, y)到 (x + width, y + height).

源码

src/renderers/WebGLRenderer.js