# [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"* . 点击[link:https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/WebGL_best_practices here] 查看"应该避免的事"
[page:Boolean alpha] - canvas是否包含alpha (透明度)。默认为 *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])。默认为*true*
[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] - whether the renderer creation will fail upon low perfomance is detected. Default is *false*. See [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:Boolean debug.checkShaderErrors]

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

### [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]扩展。 根据[link:https://webglstats.com/ WebGLStats], 截至2016年2月，超过95％的支持WebGL的设备支持此功能
- [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* 根据[link:https://webglstats.com/ WebGLStats], 截至2016年2月， 约66%的支持WebGL的设备支持此功能
- [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 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:WebGLRenderer.extensions.get .extensions.get]方法的包装, 用于检查是否支持各种WebGL扩展

### [property:Float gammaFactor]

默认是 *2*.

### [property:Boolean gammaInput]

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

### [property:Boolean gammaOutput]

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

### [property:Object info]

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

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

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

### [property:Boolean localClippingEnabled]

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

### [property:Integer maxMorphTargets]

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

### [property:Integer maxMorphNormals]

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

### [property:Boolean physicallyCorrectLights]

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

### [property:Object properties]

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

### [property:WebGLRenderLists renderLists]

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

### [property:WebGLShadowMap shadowMap]

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

### [property:Boolean shadowMap.enabled]

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

### [property:Boolean shadowMap.autoUpdate]

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

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

### [property:Boolean shadowMap.needsUpdate]

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

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

### [property:Integer shadowMap.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 LinearToneMapping]。查看[page:Renderer Renderer constants]以获取其它备选项

### [property:Number toneMappingExposure]

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

### [property:Number toneMappingWhitePoint]

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

## 方法

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

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

### [method:null clearColor]( )

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

### [method:null clearDepth]( )

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

### [method:null clearStencil]( )

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

### [method:null clearTarget]([param:WebGLRenderTarget renderTarget], [param:boolean color], [param:boolean depth], [param:boolean stencil])

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

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

### [method:null compile]( [param:Scene scene], [param:Camera camera] )

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

### [method:null copyFramebufferToTexture]( [param:Vector2 position], [param:Texture texture], [param:Number level] )

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

### [method:null copyTextureToTexture]( [param:Vector2 position], [param:Texture srcTexture], [param:Texture dstTexture], [param:Number level] )

将纹理的所有像素复制到一个已有的从给定位置开始的纹理中。可访问[link:https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/texSubImage2D WebGLRenderingContext.texSubImage2D].

### [method:null dispose]( )

处理当前的渲染环境

### [method:Object extensions.get]( [param:String extensionName] )

用于检查是否支持各种扩展，并返回一个对象，其中包含扩展的详细信息。 该方法检查以下扩展：
- *WEBGL_depth_texture*
- *EXT_texture_filter_anisotropic*
- *WEBGL_compressed_texture_s3tc*
- *WEBGL_compressed_texture_pvrtc*
- *WEBGL_compressed_texture_etc1*

### [method:null forceContextLoss]( )

模拟WebGL环境的丢失。需要支持 [link:https://developer.mozilla.org/en-US/docs/Web/API/WEBGL_lose_context WEBGL_lose_context]扩展才能用。 根据[link:https://webglstats.com/ WebGLStats], as of February 2016 90% of WebGL enabled devices support this.

### [method:Float getClearAlpha]()

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

### [method:Color getClearColor]()

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

### [method:WebGLRenderingContext 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:Object getSize]()

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

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

Initializes the given texture. Useful for preloading a texture rather than waiting until first render (which can cause noticeable lags due to decode and GPU upload overhead).

### [method:null resetGLState]( )

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

### [method:null 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.

将enderTarget中的像素数据读取到传入的缓冲区中。这是[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:WebGLRenderTargetCube WebGLRenderTargetCube] use the optional parameter activeCubeFaceIndex to determine which face should be read.

### [method:null render]( [param:Scene scene], [param:Camera camera], [param:WebGLRenderTarget renderTarget], [param:Boolean forceClear] )

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

### [method:null renderBufferDirect]( [param:Camera camera], [param:Fog fog], [param:Geometry geometry], [param:Material material], [param:Object3D object], [param:Object group] )

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

### [method:null renderBufferImmediate]( [param:Object3D object], [param:shaderprogram program], [param:Material shading] )

object - 一个[page:Object3D]实例
program - 一个shaderProgram实例
shading - 一个Material实例
渲染即使缓冲，由enderImmediateObject对象调用

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

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

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

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

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

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

设置颜色及其透明度

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

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

### [method:null 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:WebGLRenderTargetCube] (optional).
activeMipmapLevel -- Specifies the active mipmap level (optional).
该方法设置活跃rendertarget。

### [method:null 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:null setScissorTest]( [param:Boolean boolean] )

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

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

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

### [method:null 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]