# [name]

WebGL Render 用[link:https://en.wikipedia.org/wiki/WebGL WebGL]渲染出你精心制作的场景。

## 构造器

### [name]( [param:Object parameters] )

[page:Object parameters] - (可选) 该对象的属性定义了渲染器的行为。也可以完全不传参数。在所有情况下，当缺少参数时，它将采用合理的默认值。 以下是合法参数：
[page:DOMElement canvas] - 一个供渲染器绘制其输出的[link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas canvas] 它和下面的[page:WebGLRenderer.domElement domElement]属性对应。 如果没有传这个参数，会创建一个新canvas
[page:WebGLRenderingContext context] - 可用于将渲染器附加到已有的渲染环境([link:https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext RenderingContext])中。默认值是null
[page:String precision] - 着色器精度. 可以是 *"highp"*, *"mediump"* 或者 *"lowp"*. 如果设备支持，默认为*"highp"* .
[page:Boolean alpha] - controls the default clear alpha value. When set to *true*, the value is *0*. Otherwise it's *1*. Default is *false*.
[page:Boolean premultipliedAlpha] - renderer是否假设颜色有 [link:https://en.wikipedia.org/wiki/Glossary_of_computer_graphics#Premultiplied_alpha premultiplied alpha]. 默认为*true*
[page:Boolean antialias] - 是否执行抗锯齿。默认为*false*.
[page:Boolean stencil] - 绘图缓存是否有一个至少8位的模板缓存([link:https://en.wikipedia.org/wiki/Stencil_buffer stencil buffer])。默认为*false*
[page:Boolean preserveDrawingBuffer] -是否保留缓直到手动清除或被覆盖。 默认*false*.
[page:String powerPreference] - 提示用户代理怎样的配置更适用于当前WebGL环境。 可能是*"high-performance"*, *"low-power"* 或 *"default"*。默认是*"default"*. 详见[link:https://www.khronos.org/registry/webgl/specs/latest/1.0/#5.14.12 WebGL spec]
[page:Boolean failIfMajorPerformanceCaveat] - 检测渲染器是否会因性能过差而创建失败。默认为false。详见 [link:https://www.khronos.org/registry/webgl/specs/latest/1.0/#5.14.12 WebGL spec] for details.
[page:Boolean depth] - 绘图缓存是否有一个至少6位的深度缓存([link:https://en.wikipedia.org/wiki/Z-buffering depth buffer] )。 默认是*true*.
[page:Boolean logarithmicDepthBuffer] - 是否使用对数深度缓存。如果要在单个场景中处理巨大的比例差异，就有必要使用。 Note that this setting uses gl_FragDepth if available which disables the [link:https://www.khronos.org/opengl/wiki/Early_Fragment_Test Early Fragment Test] optimization and can cause a decrease in performance. 默认是*false*。 示例：[example:webgl_camera_logarithmicdepthbuffer camera / logarithmicdepthbuffer]

## 属性

### [property:Boolean autoClear]

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

### [property:Boolean autoClearColor]

如果[page:.autoClear autoClear]为true, 定义renderer是否清除颜色缓存。 默认是*true*

### [property:Boolean autoClearDepth]

如果[page:.autoClear autoClear]是true, 定义renderer是否清除深度缓存。 默认是*true*

### [property:Boolean autoClearStencil]

如果[page:.autoClear autoClear]是true, 定义renderer是否清除模板缓存. 默认是*true*

### [property:Object debug]

- [page:Boolean checkShaderErrors]: 如果为true，定义是否检查材质着色器程序 编译和链接过程中的错误。 禁用此检查生产以获得性能增益可能很有用。 强烈建议在开发期间保持启用这些检查。 如果着色器没有编译和链接 - 它将无法工作，并且相关材料将不会呈现。 默认是*true* - [page:Function onShaderError]( gl, program, glVertexShader, glFragmentShader ): A callback function that can be used for custom error reporting. The callback receives the WebGL context, an instance of WebGLProgram as well two instances of WebGLShader representing the vertex and fragment shader. Assigning a custom function disables the default error reporting. Default is `null`.

### [property:Object capabilities]

一个包含当前渲染环境([link:https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext RenderingContext])的功能细节的对象。
- [page:Boolean floatFragmentTextures]: 环境是否支持[link:https://developer.mozilla.org/en-US/docs/Web/API/OES_texture_float OES_texture_float]扩展
- [page:Boolean floatVertexTextures]: 如果[page:Boolean floatFragmentTextures]和[page:Boolean vertexTextures]都是true， 则此值为*true*
- [page:Method getMaxAnisotropy](): 返回最大可用各向异性。
- [page:Method getMaxPrecision](): 返回顶点着色器和片元着色器的最大可用精度。
- [page:Boolean isWebGL2]: *true* if the context in use is a WebGL2RenderingContext object.
- [page:Boolean logarithmicDepthBuffer]: 如果[page:parameter logarithmicDepthBuffer]在构造器中被设为true且 环境支持[link:https://developer.mozilla.org/en-US/docs/Web/API/EXT_frag_depth EXT_frag_depth]扩展，则此值为*true*
- [page:Integer maxAttributes]: *gl.MAX_VERTEX_ATTRIBS*的值
- [page:Integer maxCubemapSize]: *gl.MAX_CUBE_MAP_TEXTURE_SIZE* 的值，着色器可使用的立方体贴图纹理的最大宽度*高度
- [page:Integer maxFragmentUniforms]: *gl.MAX_FRAGMENT_UNIFORM_VECTORS*的值，片元着色器可使用的全局变量(uniforms)数量
- [page:Integer maxSamples]: The value of *gl.MAX_SAMPLES*. Maximum number of samples in context of Multisample anti-aliasing (MSAA).
- [page:Integer maxTextureSize]: *gl.MAX_TEXTURE_SIZE*的值，着色器可使用纹理的最大宽度*高度
- [page:Integer maxTextures]: *gl.MAX_TEXTURE_IMAGE_UNITS的值，着色器可使用的纹理数量
- [page:Integer maxVaryings]: *gl.MAX_VARYING_VECTORS*的值，着色器可使用矢量的数量
- [page:Integer maxVertexTextures]: *gl.MAX_VERTEX_TEXTURE_IMAGE_UNITS*的值，顶点着色器可使用的纹理数量。
- [page:Integer maxVertexUniforms]: *gl.MAX_VERTEX_UNIFORM_VECTORS*的值，顶点着色器可使用的全局变量(uniforms)数量
- [page:String precision]: 渲染器当前使用的着色器的精度
- [page:Boolean vertexTextures]: 如果[property:Integer maxVertexTextures]大于0，此值为*true* (即可以使用顶点纹理)

### [property:Array clippingPlanes]

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

### [property:DOMElement domElement]

一个[link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas canvas]，渲染器在其上绘制输出。
渲染器的构造函数会自动创建(如果没有传入canvas参数);你需要做的仅仅是像下面这样将它加页面里去:
`document.body.appendChild( renderer.domElement );`

### [property:Object extensions]

- [page:Object get]( [param:String extensionName] ): 用于检查是否支持各种扩展，并返回一个对象，其中包含扩展的详细信息。 该方法检查以下扩展：

- *WEBGL_depth_texture*
- *EXT_texture_filter_anisotropic*
- *WEBGL_compressed_texture_s3tc*
- *WEBGL_compressed_texture_pvrtc*
- *WEBGL_compressed_texture_etc1*

### [property:string outputColorSpace]

定义渲染器的输出编码。默认为[page:Textures THREE.SRGBColorSpace]

如果渲染目标已经使用 [page:WebGLRenderer.setRenderTarget .setRenderTarget]、之后将直接使用renderTarget.texture.colorSpace

查看[page:Textures texture constants]页面以获取其他格式细节

### [property:Object info]

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

- memory:
  - geometries
  - textures
- render:
  - calls
  - triangles
  - points
  - lines
  - frame
- programs

默认情况下，这些字段在每次渲染调用时都会重置，但是当每帧有多个渲染通道时（例如，使用后处理时），最好使用自定义模式重置。先将 autoReset 设置为 false. `renderer.info.autoReset = false;` 然后在单个帧时渲染完成后调用 reset(). `renderer.info.reset();`

### [property:Boolean localClippingEnabled]

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

### [property:Object properties]

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

### [property:WebGLRenderLists renderLists]

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

### [property:WebGLShadowMap shadowMap]

如果使用，它包含阴影贴图的引用。
- [page:Boolean enabled]: 如果设置开启，允许在场景中使用阴影贴图。默认是 *false*。
- [page:Boolean autoUpdate]: 启用场景中的阴影自动更新。默认是*true*
如果不需要动态光照/阴影, 则可以在实例化渲染器时将之设为false
- [page:Boolean needsUpdate]: 当被设为*true*, 场景中的阴影贴图会在下次*render*调用时刷新。默认是*false*
如果你已经禁用了阴影贴图的自动更新(*shadowMap.autoUpdate = false*), 那么想要在下一次渲染时更新阴影的话就需要将此值设为*true*
- [page:Integer type]: 定义阴影贴图类型 (未过滤, 关闭部分过滤, 关闭部分双线性过滤), 可选值有:

- THREE.BasicShadowMap
- THREE.PCFShadowMap (默认)
- THREE.PCFSoftShadowMap
- THREE.VSMShadowMap

详见[page:Renderer Renderer constants]

### [property:Boolean sortObjects]

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

### [property:Object state]

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

### [property:Constant toneMapping]

默认是[page:Renderer NoToneMapping]。查看[page:Renderer Renderer constants]以获取其它备选项

### [property:Number toneMappingExposure]

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

### [property:WebXRManager xr]

Provides access to the WebXR related [page:WebXRManager interface] of the renderer.

## 方法

### [method:undefined clear]( [param:Boolean color], [param:Boolean depth], [param:Boolean stencil] )

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

### [method:undefined clearColor]( )

清除颜色缓存。 相当于调用[page:WebGLRenderer.clear .clear]( true, false, false )

### [method:undefined clearDepth]( )

清除深度缓存。相当于调用[page:WebGLRenderer.clear .clear]( false, true, false )

### [method:undefined clearStencil]( )

清除模板缓存。相当于调用[page:WebGLRenderer.clear .clear]( false, false, true )

### [method:Set compile]( [param:Object3D scene], [param:Camera camera], [param:Scene targetScene] )

使用相机编译场景中的所有材质。这对于在首次渲染之前预编译着色器很有用。 如果要将 3D 对象添加到现有场景，请使用第三个可选参数来应用目标场景。
请注意，在调用此方法之前应配置场景的照明。

### [method:Promise compileAsync]( [param:Object3D scene], [param:Camera camera], [param:Scene targetScene] )

[page:WebGLRenderer.compile .compile]() 的异步版本。该方法返回一个 Promise。它解决了何时可以渲染给定的 3D 对象或场景，而不会因着色器编译而出现不必要的停顿。
此方法利用 *KHR_parallel_shader_compile*。

### [method:undefined copyFramebufferToTexture]( [param:FramebufferTexture texture], [param:Vector2 position], [param:Number level] )

将当前WebGLFramebuffer中的像素复制到2D纹理中。可访问[link:https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/copyTexImage2D WebGLRenderingContext.copyTexImage2D].

### [method:undefined copyTextureToTexture]( [param:Texture srcTexture], [param:Texture dstTexture], [param:Box2 srcRegion], [param:Vector2 dstPosition], [param:Number level] )

Copies the pixels of a texture in the bounds '[page:Box2 srcRegion]' in the destination texture starting from the given position. Enables access to [link:https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/texSubImage2D WebGLRenderingContext.texSubImage2D].

### [method:undefined copyTextureToTexture3D]( [param:Texture srcTexture], [param:Texture dstTexture], [param:Box3 srcRegion], [param:Vector3 dstPosition], [param:Number level] )

Copies the pixels of a texture in the bounds '[page:Box3 srcRegion]' in the destination texture starting from the given position. Enables access to [link:https://developer.mozilla.org/en-US/docs/Web/API/WebGL2RenderingContext/texSubImage3D WebGL2RenderingContext.texSubImage3D].

### [method:undefined dispose]( )

处理当前的渲染环境

### [method:undefined forceContextLoss]()

模拟WebGL环境的丢失。需要支持 [link:https://developer.mozilla.org/en-US/docs/Web/API/WEBGL_lose_context WEBGL_lose_context] 扩展才能用。

### [method:undefined forceContextRestore]( )

模拟WebGL环境的恢复。需要支持 [link:https://developer.mozilla.org/en-US/docs/Web/API/WEBGL_lose_context WEBGL_lose_context] 扩展才能用。

### [method:Float getClearAlpha]()

返回一个表示当前alpha值的[page:Float float]，范围0到1

### [method:Color getClearColor]( [param:Color target] )

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

### [method:WebGL2RenderingContext getContext]()

返回当前WebGL环境

### [method:WebGLContextAttributes getContextAttributes]()

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

### [method:Integer getActiveCubeFace]()

Returns the current active cube face.

### [method:Integer getActiveMipmapLevel]()

Returns the current active mipmap level.

### [method:RenderTarget getRenderTarget]()

如果当前存在[page:RenderTarget RenderTarget]，则返回该值；否则返回*null*。

### [method:RenderTarget getCurrentViewport]()

返回当前视口

### [method:Object getDrawingBufferSize]()

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

### [method:number getPixelRatio]()

返回当前使用设备像素比

### [method:Vector2 getSize]( [param:Vector2 target] )

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

### [method:undefined initTexture]( [param:Texture texture] )

初始化给定的纹理。用于预加载纹理而不是等到第一次渲染（可能会由于解码和 GPU 上传的开销而导致明显的延迟）.

### [method:undefined resetGLState]( )

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

### [method:undefined readRenderTargetPixels]( [param:WebGLRenderTarget renderTarget], [param:Float x], [param:Float y], [param:Float width], [param:Float height], [param:TypedArray buffer], [param:Integer activeCubeFaceIndex] )

buffer - Uint8Array is the only destination type supported in all cases, other types are renderTarget and platform dependent. See [link:https://www.khronos.org/registry/webgl/specs/latest/1.0/#5.14.12 WebGL spec] for details.

将renderTarget中的像素数据读取到传入的缓冲区中。这是[link:https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/readPixels WebGLRenderingContext.readPixels]()的包装器
示例：[example:webgl_interactive_cubes_gpu interactive / cubes / gpu]

For reading out a [page:WebGLCubeRenderTarget WebGLCubeRenderTarget] use the optional parameter activeCubeFaceIndex to determine which face should be read.

### [method:undefined render]( [param:Object3D scene], [param:Camera camera] )

用相机([page:Camera camera])渲染一个场景([page:Scene scene])或是其它类型的[page:Object3D object]。
渲染一般是在canvas上完成的，或者是[page:WebGLRenderTarget renderTarget](通过[page:WebGLRenderer.setRenderTarget .setRenderTarget]指定)。
默认情况下渲染缓存是会被清除的，但是你可以通过设置[page:WebGLRenderer.autoClear autoClear] 属性的值为false来阻止渲染缓存被清除。 如果你想阻止某个指定的缓存被清空，可以设置[page:WebGLRenderer.autoClearColor autoClearColor]、[page:WebGLRenderer.autoClearStencil autoClearStencil]或[page:WebGLRenderer.autoClearDepth autoClearDepth]属性的值为false来阻止其被清除。 如果想要强制清除一个或多个缓存，可以调用[page:WebGLRenderer.clear .clear]。

### [method:undefined resetState]()

可用于重置内部 WebGL 状态。此方法主要与跨多个 WebGL 库共享单个 WebGL 上下文的应用程序相关。

### [method:undefined setAnimationLoop]( [param:Function callback] )

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

可用来代替[link:https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame requestAnimationFrame]的内置函数. 对于WebXR项目，必须使用此函数。

### [method:undefined setClearAlpha]( [param:Float alpha] )

设置alpha。合法参数是一个*0.0*到 *1.0*之间的浮点数

### [method:undefined setClearColor]( [param:Color color], [param:Float alpha] )

设置颜色及其透明度

### [method:undefined setPixelRatio]( [param:number value] )

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

### [method:undefined setRenderTarget]( [param:WebGLRenderTarget renderTarget], [param:Integer activeCubeFace], [param:Integer activeMipmapLevel] )

renderTarget -- 需要被激活的[page:WebGLRenderTarget renderTarget](可选)。若此参数为空，则将canvas设置成活跃render target。
activeCubeFace -- Specifies the active cube side (PX 0, NX 1, PY 2, NY 3, PZ 4, NZ 5) of [page:WebGLCubeRenderTarget]. When passing a [page:WebGLArrayRenderTarget] or [page:WebGL3DRenderTarget] this indicates the z layer to render in to (optional).
activeMipmapLevel -- Specifies the active mipmap level (optional).
该方法设置活跃rendertarget。

### [method:undefined setScissor]( [param:Integer x], [param:Integer y], [param:Integer width], [param:Integer height] )

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

### [method:undefined setScissorTest]( [param:Boolean boolean] )

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

### [method:undefined setSize]( [param:Integer width], [param:Integer height], [param:Boolean updateStyle] )

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

### [method:undefined setViewport]( [param:Integer x], [param:Integer y], [param:Integer width], [param:Integer height] )

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

## 源码

[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]