three.js WebGLRenderer

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

構(gòu)造器

WebGLRenderer( parameters : Object )

parameters - (可選) 該對象的屬性定義了渲染器的行為。也可以完全不傳參數(shù)。在所有情況下，當(dāng)缺少參數(shù)時，它將采用合理的默認(rèn)值。 以下是合法參數(shù)：

canvas - 一個供渲染器繪制其輸出的canvas 它和下面的domElement屬性對應(yīng)。 如果沒有傳這個參數(shù)，會創(chuàng)建一個新canvas
context - 可用于將渲染器附加到已有的渲染環(huán)境(RenderingContext)中。默認(rèn)值是null
precision - 著色器精度. 可以是 "highp", "mediump" 或者 "lowp". 如果設(shè)備支持，默認(rèn)為"highp" .
alpha - 控制默認(rèn)的透明 alpha 值。當(dāng)設(shè)置為 true 時，值為 0。否則為 1。默認(rèn)值為 false。

premultipliedAlpha - renderer是否假設(shè)顏色有 premultiplied alpha. 默認(rèn)為true
antialias - 是否執(zhí)行抗鋸齒。默認(rèn)為false.
stencil - 繪圖緩存是否有一個至少8位的模板緩存(stencil buffer)。默認(rèn)為true
preserveDrawingBuffer -是否保留緩直到手動清除或被覆蓋。 默認(rèn)false.
powerPreference - 提示用戶代理怎樣的配置更適用于當(dāng)前WebGL環(huán)境。 可能是"high-performance", "low-power" 或 "default"。默認(rèn)是"default". 
failIfMajorPerformanceCaveat - 檢測渲染器是否會因性能過差而創(chuàng)建失敗。默認(rèn)為false。
depth - 繪圖緩存是否有一個至少6位的深度緩存(depth buffer )。 默認(rèn)是true.
logarithmicDepthBuffer - 是否使用對數(shù)深度緩存。如果要在單個場景中處理巨大的比例差異，就有必要使用。 請注意，此設(shè)置使用 gl_FragDepth（如果可用），它會禁用早期片段測試優(yōu)化并可能導(dǎo)致性能下降。 默認(rèn)是false。

屬性

.autoClear : Boolean

定義渲染器是否在渲染每一幀之前自動清除其輸出。

.autoClearColor : Boolean

如果autoClear為true, 定義renderer是否清除顏色緩存。 默認(rèn)是true

.autoClearDepth : Boolean

如果autoClear是true, 定義renderer是否清除深度緩存。 默認(rèn)是true

.autoClearStencil : Boolean

如果autoClear是true, 定義renderer是否清除模板緩存. 默認(rèn)是true

.debug : Object

- checkShaderErrors: 如果為true，定義是否檢查材質(zhì)著色器程序 編譯和鏈接過程中的錯誤。 禁用此檢查生產(chǎn)以獲得性能增益可能很有用。 強(qiáng)烈建議在開發(fā)期間保持啟用這些檢查。 如果著色器沒有編譯和鏈接 - 它將無法工作，并且相關(guān)材料將不會呈現(xiàn)。 默認(rèn)是true

.capabilities : Object

一個包含當(dāng)前渲染環(huán)境(RenderingContext)的功能細(xì)節(jié)的對象。

- floatFragmentTextures: 環(huán)境是否支持OES_texture_float擴(kuò)展
- floatVertexTextures: 如果floatFragmentTextures和vertexTextures都是true， 則此值為true
- getMaxAnisotropy(): 返回最大可用各向異性。
- getMaxPrecision(): 返回頂點(diǎn)著色器和片元著色器的最大可用精度。
- isWebGL2: 如果使用的上下文是 WebGL2RenderingContext 對象，則為true。

- logarithmicDepthBuffer: 如果logarithmicDepthBuffer在構(gòu)造器中被設(shè)為true且 環(huán)境支持EXT_frag_depth擴(kuò)展，則此值為true
- maxAttributes: gl.MAX_VERTEX_ATTRIBS的值
- maxCubemapSize: gl.MAX_CUBE_MAP_TEXTURE_SIZE 的值，著色器可使用的立方體貼圖紋理的最大寬度*高度
- maxFragmentUniforms: gl.MAX_FRAGMENT_UNIFORM_VECTORS的值，片元著色器可使用的全局變量(uniforms)數(shù)量
- maxSamples: gl.MAX_SAMPLES 的值。多重采樣抗鋸齒 (MSAA) 上下文中的最大采樣數(shù)。

- maxTextureSize: gl.MAX_TEXTURE_SIZE的值，著色器可使用紋理的最大寬度*高度
- maxTextures: gl.MAX_TEXTURE_IMAGE_UNITS的值，著色器可使用的紋理數(shù)量
- maxVaryings: gl.MAX_VARYING_VECTORS的值，著色器可使用矢量的數(shù)量
- maxVertexTextures: gl.MAX_VERTEX_TEXTURE_IMAGE_UNITS的值，頂點(diǎn)著色器可使用的紋理數(shù)量。
- maxVertexUniforms: gl.MAX_VERTEX_UNIFORM_VECTORS的值，頂點(diǎn)著色器可使用的全局變量(uniforms)數(shù)量
- precision: 渲染器當(dāng)前使用的著色器的精度
- vertexTextures: 如果 .maxVertexTextures : Integer大于0，此值為true (即可以使用頂點(diǎn)紋理)

.clippingPlanes : Array

用戶自定義的剪裁平面，在世界空間中被指定為THREE.Plane對象。 這些平面全局使用?？臻g中與該平面點(diǎn)積為負(fù)的點(diǎn)將被切掉。 默認(rèn)值是[]

.domElement : DOMElement

一個canvas，渲染器在其上繪制輸出。

渲染器的構(gòu)造函數(shù)會自動創(chuàng)建(如果沒有傳入canvas參數(shù));你需要做的僅僅是像下面這樣將它加頁面里去:

document.body.appendChild( renderer.domElement );

.extensions : Object

- get( extensionName : String ): 用于檢查是否支持各種擴(kuò)展，并返回一個對象，其中包含擴(kuò)展的詳細(xì)信息。 該方法檢查以下擴(kuò)展：

• WEBGL_depth_texture
• EXT_texture_filter_anisotropic
• WEBGL_compressed_texture_s3tc
• WEBGL_compressed_texture_pvrtc
• WEBGL_compressed_texture_etc1

.outputEncoding : number

定義渲染器的輸出編碼。默認(rèn)為THREE.LinearEncoding

如果渲染目標(biāo)已經(jīng)使用 .setRenderTarget、之后將直接使用renderTarget.texture.encoding

.info : Object

一個對象，包含有關(guān)圖形板內(nèi)存和渲染過程的一系列統(tǒng)計(jì)信息。這些信息可用于調(diào)試或僅僅滿足下好奇心。該對象包含以下字段:

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

默認(rèn)情況下，這些字段在每次渲染調(diào)用時都會重置，但是當(dāng)每幀有多個渲染通道時（例如，使用后處理時），最好使用自定義模式重置。先將 autoReset 設(shè)置為 false.

renderer.info.autoReset = false;

然后在單個幀時渲染完成后調(diào)用 reset().

renderer.info.reset();

.localClippingEnabled : Boolean

定義渲染器是否考慮對象級剪切平面。 默認(rèn)為false.

.physicallyCorrectLights : Boolean

是否使用物理上正確的光照模式。 默認(rèn)是false。 示例：lights / physical

.properties : Object

渲染器內(nèi)部使用，以跟蹤各種子對象屬性。

.renderLists : WebGLRenderLists

在內(nèi)部用于處理場景渲染對象的排序。

.shadowMap : WebGLShadowMap

如果使用，它包含陰影貼圖的引用。

- enabled: 如果設(shè)置開啟，允許在場景中使用陰影貼圖。默認(rèn)是 false。
- autoUpdate: 啟用場景中的陰影自動更新。默認(rèn)是true
如果不需要動態(tài)光照/陰影, 則可以在實(shí)例化渲染器時將之設(shè)為false
- needsUpdate: 當(dāng)被設(shè)為true, 場景中的陰影貼圖會在下次render調(diào)用時刷新。默認(rèn)是false
如果你已經(jīng)禁用了陰影貼圖的自動更新(shadowMap.autoUpdate = false), 那么想要在下一次渲染時更新陰影的話就需要將此值設(shè)為true
- type: 定義陰影貼圖類型 (未過濾, 關(guān)閉部分過濾, 關(guān)閉部分雙線性過濾), 可選值有:

• THREE.BasicShadowMap
• THREE.PCFShadowMap (默認(rèn))
• THREE.PCFSoftShadowMap
• THREE.VSMShadowMap

.sortObjects : Boolean

定義渲染器是否應(yīng)對對象進(jìn)行排序。默認(rèn)是true.

說明: 排序用于嘗試正確渲染出具有一定透明度的對象。根據(jù)定義，排序可能不總是有用。根據(jù)應(yīng)用的需求，可能需要關(guān)閉排序并使其他方法來處理透明度的渲染，例如， 手動確定每個對象的渲染順序。

.state : Object

包含設(shè)置WebGLRenderer.context狀態(tài)的各種屬性的函數(shù)。

.toneMapping : Constant

默認(rèn)是NoToneMapping。

.toneMappingExposure : Number

色調(diào)映射的曝光級別。默認(rèn)是1

.xr : WebXRManager

提供對渲染器的 WebXR 相關(guān)接口的訪問。

方法

.clear ( color : Boolean, depth : Boolean, stencil : Boolean ) : undefined

告訴渲染器清除顏色、深度或模板緩存. 此方法將顏色緩存初始化為當(dāng)前顏色。參數(shù)們默認(rèn)都是true

.clearColor ( ) : undefined

清除顏色緩存。 相當(dāng)于調(diào)用.clear( true, false, false )

.clearDepth ( ) : undefined

清除深度緩存。相當(dāng)于調(diào)用.clear( false, true, false )

.clearStencil ( ) : undefined

清除模板緩存。相當(dāng)于調(diào)用.clear( false, false, true )

.compile ( scene : Object3D, camera : Camera ) : undefined

使用相機(jī)編譯場景中的所有材質(zhì)。這對于在首次渲染之前預(yù)編譯著色器很有用。

.copyFramebufferToTexture ( position : Vector2, texture : FramebufferTexture, level : Number ) : undefined

將當(dāng)前WebGLFramebuffer中的像素復(fù)制到2D紋理中。

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

將紋理的所有像素復(fù)制到一個已有的從給定位置開始的紋理中。

.dispose ( ) : undefined

處理當(dāng)前的渲染環(huán)境

.forceContextLoss () : undefined

模擬WebGL環(huán)境的丟失。需要支持 WEBGL_lose_context 擴(kuò)展才能用。

.forceContextRestore ( ) : undefined

模擬WebGL環(huán)境的恢復(fù)。需要支持 WEBGL_lose_context 擴(kuò)展才能用。

.getClearAlpha () : Float

返回一個表示當(dāng)前alpha值的float，范圍0到1

.getClearColor ( target : Color ) : Color

返回一個表示當(dāng)前顏色值的THREE.Color實(shí)例

.getContext () : WebGL2RenderingContext

返回當(dāng)前WebGL環(huán)境

.getContextAttributes () : WebGLContextAttributes

返回一個對象，這個對象中存有在WebGL環(huán)境在創(chuàng)建的時候所設(shè)置的屬性

.getActiveCubeFace () : Integer

返回當(dāng)前活動的立方體面。

.getActiveMipmapLevel () : Integer

返回當(dāng)前活動的 mipmap 級別。

.getRenderTarget () : RenderTarget

如果當(dāng)前存在RenderTarget，則返回該值；否則返回null。

.getCurrentViewport () : RenderTarget

返回當(dāng)前視口

.getDrawingBufferSize () : Object

返回一個包含渲染器繪圖緩存寬度和高度(單位像素)的對象。

.getPixelRatio () : number

返回當(dāng)前使用設(shè)備像素比

.getSize ( target : Vector2 ) : Vector2

返回包含渲染器輸出canvas的寬度和高度(單位像素)的對象。

.initTexture ( texture : Texture ) : undefined

初始化給定的紋理。用于預(yù)加載紋理而不是等到第一次渲染（可能會由于解碼和 GPU 上傳的開銷而導(dǎo)致明顯的延遲）.

.resetGLState ( ) : undefined

將GL狀態(tài)重置為默認(rèn)值。WebGL環(huán)境丟失時會內(nèi)部調(diào)用

.readRenderTargetPixels ( renderTarget : WebGLRenderTarget, x : Float, y : Float, width : Float, height : Float, buffer : TypedArray, activeCubeFaceIndex : Integer ) : undefined

buffer - Uint8Array 是唯一在所有情況下都受支持的目標(biāo)類型，其他類型取決于 renderTarget 和平臺。

將renderTarget中的像素?cái)?shù)據(jù)讀取到傳入的緩沖區(qū)中。這是WebGLRenderingContext.readPixels()的包裝器

示例：interactive / cubes / gpu

要讀取 WebGLCubeRenderTarget，請使用可選參數(shù) activeCubeFaceIndex 來確定應(yīng)讀取哪個面。

.render ( scene : Object3D, camera : Camera ) : undefined

用相機(jī)(camera)渲染一個場景(scene)或是其它類型的object。
渲染一般是在canvas上完成的，或者是renderTarget(如果有指定)
如果forceClear值是true，那么顏色、深度及模板緩存將會在渲染之前清除，即使渲染器的autoClear屬性值是false
即便forceClear設(shè)為true, 也可以通過將autoClearColor、autoClearStencil或autoClearDepth屬性的值設(shè)為false來阻止對應(yīng)緩存被清除。

.resetState () : undefined

可用于重置內(nèi)部 WebGL 狀態(tài)。此方法主要與跨多個 WebGL 庫共享單個 WebGL 上下文的應(yīng)用程序相關(guān)。

.setAnimationLoop ( callback : Function ) : undefined

callback — 每個可用幀都會調(diào)用的函數(shù)。 如果傳入‘null’,所有正在進(jìn)行的動畫都會停止。

可用來代替requestAnimationFrame的內(nèi)置函數(shù). 對于WebXR項(xiàng)目，必須使用此函數(shù)。

.setClearAlpha ( alpha : Float ) : undefined

設(shè)置alpha。合法參數(shù)是一個0.0到 1.0之間的浮點(diǎn)數(shù)

.setClearColor ( color : Color, alpha : Float ) : undefined

設(shè)置顏色及其透明度

.setPixelRatio ( value : number ) : undefined

設(shè)置設(shè)備像素比。通常用于避免HiDPI設(shè)備上繪圖模糊

.setRenderTarget ( renderTarget : WebGLRenderTarget, activeCubeFace : Integer, activeMipmapLevel : Integer ) : undefined

renderTarget -- 需要被激活的renderTarget(可選)。若此參數(shù)為空，則將canvas設(shè)置成活躍render target。
activeCubeFace -- 指定 WebGLCubeRenderTarget 的活動立方體面（PX 0、NX 1、PY 2、NY 3、PZ 4、NZ 5）。傳遞 WebGLArrayRenderTarget 或 WebGL3DRenderTarget 時，這表示要渲染到的 z 層（可選）。

activeMipmapLevel -- 指定活動的 mipmap 級別（可選）。

該方法設(shè)置活躍rendertarget。

.setScissor ( x : Integer, y : Integer, width : Integer, height : Integer ) : undefined

將剪裁區(qū)域設(shè)為(x, y)到(x + width, y + height) Sets the scissor area from

.setScissorTest ( boolean : Boolean ) : undefined

啟用或禁用剪裁檢測. 若啟用，則只有在所定義的裁剪區(qū)域內(nèi)的像素才會受之后的渲染器影響。

.setSize ( width : Integer, height : Integer, updateStyle : Boolean ) : undefined

將輸出canvas的大小調(diào)整為(width, height)并考慮設(shè)備像素比，且將視口從(0, 0)開始調(diào)整到適合大小 將updateStyle設(shè)置為false以阻止對canvas的樣式做任何改變。

.setViewport ( x : Integer, y : Integer, width : Integer, height : Integer ) : undefined

將視口大小設(shè)置為(x, y)到 (x + width, y + height).

源碼

src/renderers/WebGLRenderer.js