Improved documentation for WebGLRenderer (#10030)

* added missing methods

* Finished add methods

* redid changed to WebGLRenderer.html

docs/api/renderers/WebGLRenderer.html

@@ -26,7 +26,7 @@
 		canvas — A [link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas canvas] where the renderer draws its output.
 		This corresponds to the [page:WebGLRenderer.domElement .domElement] property below.<br />
 
-		context — This can be used to attach the renderer to an existing <a href="https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext">RenderingContext</a>.<br />
+		context — This can be used to attach the renderer to an existing [link:https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext RenderingContext].<br />
 
 		precision — Shader precision. Can be *"highp"*, *"mediump"* or *"lowp"*. Defaults to *"highp"* if supported by the device.<br />
 
@@ -65,16 +65,16 @@
 
 		<h3>[property:Object capabilities]</h3>
 		<div>
-		An object containing details about the capabilities of the current <a href="https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext">RenderingContext</a>.<br />
+		An object containing details about the capabilities of the current [link:https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext RenderingContext].<br />
 
-		- [property:Boolean floatFragmentTextures]: whether the context supports the <a href="https://developer.mozilla.org/en-US/docs/Web/API/OES_texture_float">OES_texture_float</a> extension.
-			According to <a href="https://webglstats.com/">WebGLStats</a>, as of February 2016 over 95% of WebGL enabled devices support this.<br />
+		- [property:Boolean floatFragmentTextures]: whether the context supports the [link:https://developer.mozilla.org/en-US/docs/Web/API/OES_texture_float OES_texture_float] extension.
+			According to [link:https://webglstats.com/ WebGLStats], as of February 2016 over 95% of WebGL enabled devices support this.<br />
 		- [property:Boolean floatVertexTextures]: *true* if [property:Boolean floatFragmentTextures] and [property:Boolean vertexTextures] are both true.<br />
 		- [property:Method getMaxAnisotropy](): see [page:WebGLRenderer.getMaxAnisotropy getMaxAnisotropy] below. <br />
 		- [property:Method getMaxPrecision](): see [page:WebGLRenderer.getMaxPrecision getMaxPrecision] below. <br />
-		- [property:Boolean logarithmicDepthBuffer]: *true* if the [property:parameter logarithmicDepthBuffer] was set to true in the constructor,
-		the context supports the <a href="https://developer.mozilla.org/en-US/docs/Web/API/EXT_frag_depth">EXT_frag_depth</a> extension.
-			According to <a href="https://webglstats.com/">WebGLStats</a>, as of February 2016 around 66% of WebGL enabled devices support this.<br />
+		- [property:Boolean logarithmicDepthBuffer]: *true* if the [property:parameter logarithmicDepthBuffer] was set to true in the constructor and
+		the context supports the [link:https://developer.mozilla.org/en-US/docs/Web/API/EXT_frag_depth EXT_frag_depth] extension.
+			According to [link:https://webglstats.com/ WebGLStats], as of February 2016 around 66% of WebGL enabled devices support this.<br />
 		- [property:Integer maxAttributes]: The value of *gl.MAX_VERTEX_ATTRIBS*.<br />
 		- [property:Integer maxCubemapSize]: The value of *gl.MAX_CUBE_MAP_TEXTURE_SIZE*.
 		Maximum height * width of cube map textures that a shader can use.<br />
@@ -103,9 +103,9 @@
 
 		<h3>[property:WebGLRenderingContext context]</h3>
 		<div>
-		The renderer obtains a <a href="https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext">RenderingContext</a> context
+		The renderer obtains a [link:https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext RenderingContext] context
 		  from its [page:WebGLRenderer.domElement domElement][page:WebGLRenderer.domElement domElement] by default, using
-			<a href="https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext">HTMLCanvasElement.getContext()</a>.<br /><br />
+			[link:https://developer.mozilla.org/en/docs/Web/API/HTMLCanvasElement/getContext HTMLCanvasElement.getContext]()</a>.<br /><br />
 
 		You can create this manually, however it must correspond to the
 		[page:WebGLRenderer.domElement domElement] in order to render to the screen.
@@ -123,8 +123,8 @@
 
 		<h3>[property:Object extensions]</h3>
 		<div>
-		A wrapper for the [page:WebGLRenderer.extensions.get .extensions.get] method, used internally to check whether
-		various extensions are supported and set parameters accordingly.
+		A wrapper for the [page:WebGLRenderer.extensions.get .extensions.get] method, used to check whether
+		various WebGL extensions are supported.
 		</div>
 
 		<h3>[property:Boolean gammaFactor]</h3>
@@ -221,7 +221,7 @@
 		Note: Sorting is used to attempt to properly render objects that have some degree of transparency.
 		By definition, sorting objects may not work in all cases.  Depending on the needs of application,
 		it may be neccessary to turn off sorting and use other methods to deal with transparency
-		rendering e.g. manually determining the object rendering order.
+		rendering e.g. manually determining each object's rendering order.
 		</div>
 
 		<h3>[property:Object state]</h3>
@@ -246,170 +246,197 @@
 
 		<h2>Methods</h2>
 
-		<h3>[method:Object extensions.get]( [page:String extensionName] )</h3>
+		<h3>[method:Integer allocTextureUnit]</h3>
 		<div>
-		Used internally to check whether various extensions are supported and set parameters accordingly.<br /><br />
+		Attempt to allocate a texture unit for use by a shader. Will warn if trying to allocate
+		more texture units than the GPU supports. This is mainly used internally.
+		See [page:WebGLRenderer.capabilities capabilities.maxTextures].
 		</div>
 
-		<h3>[method:WebGLRenderingContext getContext]()</h3>
+		<h3>[method:null clear]( [page:Boolean color], [page:Boolean depth], [page:Boolean stencil] )</h3>
 		<div>
-		Return the WebGL context.
+		Tells the renderer to clear its color, depth or stencil drawing buffer(s).
+			This method initializes the color buffer to the current clear color value.<br />
+		Arguments default to *true*.
 		</div>
 
-		<h3>[method:WebGLContextAttributes getContextAttributes]()</h3>
+		<h3>[method:null clearColor]( )</h3>
+		<div>Clear the color buffer. Equivalent to calling [page:WebGLRenderer.clear .clear]( true, false, false ).</div>
+
+		<h3>[method:null clearDepth]( )</h3>
+		<div>Clear the depth buffer. Equivalent to calling [page:WebGLRenderer.clear .clear]( false, true, false ).</div>
+
+		<h3>[method:null clearStencil]( )</h3>
+		<div>Clear the stencil buffers. Equivalent to calling [page:WebGLRenderer.clear .clear]( false, false, true ).</div>
+
+		<h3>[method:null clearTarget]([page:WebGLRenderTarget renderTarget], [page:boolean color], [page:boolean depth], [page:boolean stencil])</h3>
 		<div>
-		Returns an object that describes the attributes set on the WebGL context when it was created.
+		renderTarget -- The [page:WebGLRenderTarget renderTarget] that needs to be cleared.<br />
+		color -- If set, then the color gets cleared. <br />
+		depth -- If set, then the depth gets cleared. <br />
+		stencil -- If set, then the stencil gets cleared.
 		</div>
-
-		<h3>[method:Boolean supportsVertexTextures]()</h3>
 		<div>
-		Return a [page:Boolean] true if the context supports vertex textures.
+		This method clears a rendertarget. To do this, it activates the rendertarget.
 		</div>
 
-		<h3>[method:number getPixelRatio]()</h3>
-		<div>Returns current device pixel ratio used.</div>
+		<h3>[method:null dispose]( )</h3>
+		<div>Dispose of the current rendering context.</div>
 
-		<h3>[method:null setPixelRatio]( [page:number value] )</h3>
-		<div>Sets device pixel ratio. This is usually used for HiDPI device to prevent bluring output canvas.</div>
+		<h3>[method:Object extensions.get]( [page:String extensionName] )</h3>
+		<div>
+		Used to check whether various extensions are supported and returns an object with details of the extension if available.
+		This method can check for the following extensions:<br /><br />
 
-		<h3>[method:Object getSize]()</h3>
-		<div>Returns an object containing the width and height of the renderer's output canvas, in pixels.</div>
+		- *WEBGL_depth_texture*<br />
+		- *EXT_texture_filter_anisotropic*<br />
+		- *WEBGL_compressed_texture_s3tc*<br />
+		- *WEBGL_compressed_texture_pvrtc*<br />
+		- *WEBGL_compressed_texture_etc1*
+		</div>
 
-		<h3>[method:null setSize]( [page:Integer width], [page:Integer height], [page:Boolean updateStyle] )</h3>
-		<div>Resizes the output canvas to (width, height) with device pixel ratio taken into account, and also sets the viewport to fit that size, starting in (0, 0). Setting updateStyle to true adds explicit pixel units to the output canvas style.</div>
+		<h3>[method:null forceContextLoss]( )</h3>
+		<div>
+		Simulate loss of the WebGL context. This requires support for the
+			[link:https://developer.mozilla.org/en-US/docs/Web/API/WEBGL_lose_context WEBGL_lose_context] extensions.
+		According to [link:https://webglstats.com/ WebGLStats], as of February 2016 90% of WebGL enabled devices support this.
+		</div>
 
-		<h3>[method:null setViewport]( [page:Integer x], [page:Integer y], [page:Integer width], [page:Integer height] )</h3>
-		<div>Sets the viewport to render from (x, y) to (x + width, y + height).</div>
+		<h3>[method:Float getClearAlpha]()</h3>
+		<div>Returns a [page:Float float] with the current clear alpha. Ranges from 0 to 1.</div>
 
+		<h3>[method:Color getClearColor]()</h3>
+		<div>Returns a [page:Color THREE.Color] instance with the current clear color.</div>
 
-		<h3>[method:null setScissor]( [page:Integer x], [page:Integer y], [page:Integer width], [page:Integer height] )</h3>
-		<div>Sets the scissor area from (x, y) to (x + width, y + height).</div>
+		<h3>[method:WebGLRenderingContext getContext]()</h3>
+		<div>Return the current WebGL context.</div>
 
-		<div>NOTE: The point (x, y) is the lower left corner of the area to be set for both of these methods. The area is defined from left to right in width but bottom to top in height. The sense of the vertical definition is opposite to the fill direction of an HTML canvas element.</div>
+		<h3>[method:WebGLContextAttributes getContextAttributes]()</h3>
+		<div>Returns an object that describes the attributes set on the WebGL context when it was created.</div>
 
-		<h3>[method:null setScissorTest]( [page:Boolean boolean] )</h3>
-		<div>Enable or disable the scissor test. When this is enabled, only the pixels within the defined scissor area will be affected by further renderer actions.</div>
+		<h3>[method:RenderTarget getCurrentRenderTarget](  )</h3>
+		<div>Returns the current RenderTarget, if any.</div>
 
-		<h3>[method:null setClearColor]( [page:Color color], [page:Float alpha] )</h3>
-		<div>Sets the clear color and opacity.</div>
+		<h3>[method:Number getMaxAnisotropy]()</h3>
+		<div>This returns the anisotropy level of the textures.</div>
 
-		<code>// Creates a renderer with red background
-		var renderer = new THREE.WebGLRenderer();
-		renderer.setSize( 200, 100 );
-		renderer.setClearColor( 0xff0000 );
-		</code>
+		<h3>[method:number getPixelRatio]()</h3>
+		<div>Returns current device pixel ratio used.</div>
 
-		<h3>[method:Color getClearColor]()</h3>
-		<div>Returns a [page:Color THREE.Color] instance with the current clear color.</div>
+		<h3>[method:string getPrecision]()</h3>
+		<div>This gets the precision used by the shaders. It returns "highp","mediump" or "lowp".</div>
 
-		<h3>[method:Float getClearAlpha]()</h3>
-		<div>Returns a [page:Float float] with the current clear alpha. Ranges from 0 to 1.</div>
+		<h3>[method:Object getSize]()</h3>
+		<div>Returns an object containing the width and height of the renderer's output canvas, in pixels.</div>
 
-		<h3>[method:null clear]( [page:Boolean color], [page:Boolean depth], [page:Boolean stencil] )</h3>
-		<div>Tells the renderer to clear its color, depth or stencil drawing buffer(s). This method initializes the color buffer to the current clear color value.</div>
-		<div>Arguments default to true.</div>
+		<h3>[method:null resetGLState]( )</h3>
+		<div>Reset the GL state to default. Called internally if the WebGL context is lost.</div>
 
-		<h3>[method:null renderBufferImmediate]( [page:Object3D object], [page:shaderprogram program], [page:Material shading] )</h3>
-		<div>object — an instance of [page:Object3D]<br />
-		program — an instance of shaderProgram<br />
-		shading — an instance of Material<br />
-		</div>
-		<div>
-		Render an immediate buffer. Gets called by renderImmediateObject.
+		<h3>[method:null readRenderTargetPixels]( [page:WebGLRenderTarget renderTarget], [page:Float x], [page:Float y], [page:Float width], [page:Float height], buffer )</h3>
+		<div>Reads the pixel data from the renderTarget into the buffer you pass in.
+			Buffer should be a Javascript Uint8Array instantiated with
+			new Uint8Array( renderTargetWidth * renderTargetWidth * 4 ) to account for size and color
+			information. This is a wrapper around gl.readPixels.<br />
+		See the [example:webgl_interactive_cubes_gpu interactive / cubes / gpu] example.
 		</div>
 
+		<h3>[method:null render]( [page:Scene scene], [page:Camera camera], [page:WebGLRenderTarget renderTarget], [page:Boolean forceClear] )</h3>
+		<div>
+			Render a [page:Scene scene] using a [page:Camera camera].<br />
 
-		<h3>[method:null renderBufferDirect]( [page:Camera camera], [page:Array lights], [page:Fog fog], [page:Material material], [page:Object geometryGroup], [page:Object3D object] )</h3>
-		<div>Render a buffer geometry group using the camera and with the correct material.</div>
+			The render is done to the [page:WebGLRenderTarget renderTarget] (if specified) or to the canvas as usual.<br />
 
+			If [page:Boolean forceClear] is *true*, the depth, stencil and color buffers will be cleared
+			before rendering even if the renderer's [page:WebGLRenderer.autoClear autoClear] property is false.<br />
 
-		<h3>[method:null renderBuffer]( [page:Camera camera], [page:Array lights], [page:Fog fog], [page:Material material], [page:Object geometryGroup], [page:Object3D object] )</h3>
-		<div>Render a geometry group using the camera and with the correct material.</div>
+			Even with forceClear set to true you can prevent certain buffers being cleared by setting
+			either the [page:WebGLRenderer.autoClearColor autoClearColor], [page:WebGLRenderer.autoClearStencil autoClearStencil] or [page:WebGLRenderer.autoClearDepth autoClearDepth] properties to false.
+		</div>
 
+		<h3>[method:null renderBufferDirect]( [page:Camera camera], [page:Array lights], [page:Fog fog], [page:Material material], [page:Object geometryGroup], [page:Object3D object] )</h3>
+		<div>Render a buffer geometry group using the camera and with the specified material.</div>
 
-		<h3>[method:null render]( [page:Scene scene], [page:Camera camera], [page:WebGLRenderTarget renderTarget], [page:Boolean forceClear] )</h3>
-		<div>Render a scene using a camera.</div>
-		<div>The render is done to the renderTarget (if specified) or to the canvas as usual.</div>
-		<div>If forceClear is true, the depth, stencil and color buffers will be cleared before rendering even if the renderer's autoClear property is false.</div>
-		<div>Even with forceClear set to true you can prevent certain buffers being cleared by setting either the .autoClearColor, .autoClearStencil or .autoClearDepth properties to false.</div>
+		<h3>[method:null renderBufferImmediate]( [page:Object3D object], [page:shaderprogram program], [page:Material shading] )</h3>
+		<div>object — an instance of [page:Object3D]<br />
+		program — an instance of shaderProgram<br />
+		shading — an instance of Material<br /><br />
 
-		<h3>[method:null readRenderTargetPixels]( [page:WebGLRenderTarget renderTarget], [page:Float x], [page:Float y], [page:Float width], [page:Float height], buffer )</h3>
-		<div>Reads the pixel data from the renderTarget into the buffer you pass in. Buffer should be a Javascript Uint8Array instantiated with new Uint8Array( renderTargetWidth * renderTargetWidth * 4 ) to account for size and color information. This is a wrapper around gl.readPixels.</div>
+		Render an immediate buffer. Gets called by renderImmediateObject.
+		</div>
 
-		<h3>[method:null renderImmediateObject]( camera, lights, fog, material, object )</h3>
-		<div>Renders an immediate Object using a camera.</div>
+		<h3>[method:null setClearAlpha]( [page:Float alpha] )</h3>
+		<div>Sets the clear alpha. Valid input is a float between *0.0* and *1.0*.</div>
 
+		<h3>[method:null setClearColor]( [page:Color color], [page:Float alpha] )</h3>
+		<div>Sets the clear color and opacity.</div>
 
-		<h3>[method:null setFaceCulling]( cullFace, frontFace )</h3>
+		<h3>[method:null setFaceCulling]( [page:Renderer cullFace], [page:Renderer frontFace] )</h3>
 		<div>
-		See [page:WebGLRenderer WebGLRenderer constants] for all possible values for [page:String cullFace] and [page:String frontFace].<br />
+		See [page:Renderer WebGLRenderer constants] for all possible values for [page:Renderer cullFace] and [page:Renderer frontFace].<br />
 		Used for setting the gl.frontFace and gl.cullFace states in the GPU, thus enabling/disabling face culling when rendering.<br />
-		If cullFace is set to THREE.[page:String CullFaceNone], culling will be disabled.<br />
+		If cullFace is set to [page:Renderer CullFaceNone], culling will be disabled.<br />
 		</div>
 
-
-
-		<h3>[method:null setTexture]( [page:Texture texture], [page:number slot] )</h3>
-		<div>
-		texture -- The [page:Texture texture] that needs to be set.<br />
-		slot -- The number indicating which slot should be used by the texture.
-		</div>
-		<div>
-		This method sets the correct texture to the correct slot for the wegl shader. The slot number can be found as a value of the uniform of the sampler.
-		</div>
+		<h3>[method:null setPixelRatio]( [page:number value] )</h3>
+		<div>Sets device pixel ratio. This is usually used for HiDPI device to prevent bluring output canvas.</div>
 
 		<h3>[method:null setRenderTarget]( [page:WebGLRenderTarget renderTarget] )</h3>
 		<div>
-		renderTarget -- The [page:WebGLRenderTarget renderTarget] that needs to be activated (optional).<br />
-		</div>
-		<div>
+		renderTarget -- The [page:WebGLRenderTarget renderTarget] that needs to be activated (optional).<br /><br />
 		This method sets the active rendertarget. If the parameter is omitted the canvas is set as the active rendertarget.
 		</div>
 
-		<h3>[method:boolean supportsCompressedTextureS3TC]()</h3>
+		<h3>[method:null setScissor]( [page:Integer x], [page:Integer y], [page:Integer width], [page:Integer height] )</h3>
 		<div>
-		This method returns true if the webgl implementation supports compressed textures of the format S3TC.
+		Sets the scissor area from (x, y) to (x + width, y + height)
 		</div>
 
-		<h3>[method:number getMaxAnisotropy]()</h3>
+		<h3>[method:null setScissorTest]( [page:Boolean boolean] )</h3>
 		<div>
-		This returns the anisotropy level of the textures.
-		</div>
+		Enable or disable the scissor test. When this is enabled, only the pixels within
+			the defined scissor area will be affected by further renderer actions..<br /><br />
 
-		<h3>[method:string getPrecision]()</h3>
-		<div>
-		This gets the precision used by the shaders. It returns "highp","mediump" or "lowp".
+		NOTE: The point (x, y) is the lower left corner of the area to be set for both of these methods.
+			The area is defined from left to right in width but bottom to top in height.
+			The sense of the vertical definition is opposite to the fill direction of an HTML canvas element.
 		</div>
 
-		<h3>[method:null setMaterialFaces]([page:Material material])</h3>
-		<div>
-		material -- The [page:Material material] with side that shouldn't be culled.
-		</div>
+		<h3>[method:Boolean supportsVertexTextures]()</h3>
 		<div>
-		This sets which side needs to be culled in the webgl renderer.
+		Return a [page:Boolean] true if the context supports vertex textures.
+		This has been deprecated in favour of [page:WebGLRenderer.capabilities capabilities.vertexTexures].
 		</div>
 
-		<h3>[method:boolean supportsStandardDerivatives]()</h3>
+		<h3>[method:null setSize]( [page:Integer width], [page:Integer height], [page:Boolean updateStyle] )</h3>
 		<div>
-		This method returns true if the webgl implementation supports standard derivatives.
+		Resizes the output canvas to (width, height) with device pixel ratio taken into account,
+			and also sets the viewport to fit that size, starting in (0, 0).
+			Setting [page:Boolean updateStyle] to true adds explicit pixel units to the output canvas style.
 		</div>
 
-		<h3>[method:boolean supportsFloatTextures]()</h3>
+		<h3>[method:null setTexture2D]( [page:Texture texture], [page:number slot] )</h3>
 		<div>
-		This method returns true if the webgl implementation supports float textures.
-		</div>
+		texture -- The [page:Texture texture] that needs to be set.<br />
+		slot -- The number indicating which slot should be used by the texture.<br /><br />
 
-		<h3>[method:null clearTarget]([page:WebGLRenderTarget renderTarget], [page:boolean color], [page:boolean depth], [page:boolean stencil])</h3>
-		<div>
-		renderTarget -- The [page:WebGLRenderTarget renderTarget] that needs to be cleared.<br />
-		color -- If set, then the color gets cleared. <br />
-		depth -- If set, then the depth gets cleared. <br />
-		stencil -- If set, then the stencil gets cleared.
+		This method sets the correct texture to the correct slot for the WebGL shader.
+		The slot number can be found as a value of the uniform of the sampler.<br /><br />
+
+		Note: This method replaces the older [method:null setTexture] method.
 		</div>
+
+		<h3>[method:null setTextureCube]( [page:CubeTexture cubeTexture], [page:Number slot] )</h3>
 		<div>
-		This method clears a rendertarget. To do this, it activates the rendertarget.
+		texture -- The [page:CubeTexture cubeTexture] that needs to be set.<br />
+		slot -- The number indicating which slot should be used by the texture.<br /><br />
+
+		This method sets the correct texture to the correct slot for the WebGL shader.
+		The slot number can be found as a value of the uniform of the sampler.
 		</div>
 
+		<h3>[method:null setViewport]( [page:Integer x], [page:Integer y], [page:Integer width], [page:Integer height] )</h3>
+		<div>Sets the viewport to render from (x, y) to (x + width, y + height).</div>
+
 		<h2>Source</h2>
 
 		[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]