Merge remote-tracking branch 'erich666/master' into dev

docs/api/lights/DirectionalLight.html

@@ -103,7 +103,7 @@ scene.add( directionalLight );</code>
 
 		<h3>[property:Float shadowBias]</h3>
 		<div>
-			Shadow map bias.<br />
+			Shadow map bias, how much to add or subtract from the normalized depth when deciding whether a surface is in shadow.<br />
 			Default — *0*.
 		</div>
 
@@ -127,81 +127,76 @@ scene.add( directionalLight );</code>
 
 		<h3>[property:Boolean shadowCascade]</h3>
 		<div>
-			??? <br />
+			**Experimental** If true, use a series of shadow maps in a cascade. This can give better z-depth resolution for a directional light. <br />
 			Default — *false*.
 		</div>
 
-		<h3>[property:Vector3 shadowCascadeOffset]</h3>
+		<h3>[property:Integer shadowCascadeCount]</h3>
 		<div>
-			??? <br />
-			Default — *Three.Vector3( 0, 0, -1000 )*.
+			Number of shadow maps to allocate in a cascade (one after another). <br />
+			Default — *2*.
 		</div>
 
-		<h3>[property:Integer shadowCascadeCount]</h3>
+		<h3>[property:Vector3 shadowCascadeOffset]</h3>
 		<div>
-			??? <br />
-			Default — *2*.
+			A relative position to real camera where virtual shadow cameras are attached. A magic vector; scene and light orientation dependent. <br />
+			Default — *Three.Vector3( 0, 0, -1000 )*.
 		</div>
 
 		<h3>[property:Array shadowCascadeBias]</h3>
 		<div>
-			??? <br />
+			An array of shadowMapBias values for the corresponding shadow map in the cascade, near to far. <br />
 			Default — <strong>[ 0, 0, 0 ]</strong>.
 		</div>
 
 		<h3>[property:Array shadowCascadeWidth]</h3>
 		<div>
-			??? <br />
+			An array of shadowMapWidth values for the corresponding shadow map in the cascade, near to far. <br />
 			Default — <strong>[ 512, 512, 512 ]</strong>.
 		</div>
 
 		<h3>[property:Array shadowCascadeHeight]</h3>
 		<div>
-			??? <br />
+			An array of shadowMapHeight values for the corresponding shadow map in the cascade, near to far. <br />
 			Default — <strong>[ 512, 512, 512 ]</strong>.
 		</div>
 
 		<h3>[property:Array shadowCascadeNearZ]</h3>
 		<div>
-			??? <br />
+			An array of shadowMapNear values for the corresponding shadow map in the cascade, near to far. These typically start with -1.0 (near plane) and match with the previous shadowCascadeFarZ array value.<br />
 			Default — <strong>[ -1.000, 0.990, 0.998 ]</strong>.
 		</div>
 
 		<h3>[property:Array shadowCascadeFarZ]</h3>
 		<div>
-			??? <br />
+			An array of shadowMapFar values for the corresponding shadow map in the cascade, near to far. These typically match with the next shadowCascadeNearZ array value, ending in 1.0.<br />
 			Default — <strong>[ 0.990, 0.998, 1.000 ]</strong>.
 		</div>
 
 		<h3>[property:Array shadowCascadeArray]</h3>
 		<div>
-			??? <br />
-			Default — <strong>[ ]</strong>.
+			Array of size shadowCascadeCount of [page:DirectionalLight THREE.DirectionalLight] objects. This holds the series of separate shadow maps in a cascade, near to far. Created internally.
 		</div>
 
-		<h3>[property:RenderTarget shadowMap]</h3>
+		<h3>[property:Vector2 shadowMapSize]</h3>
 		<div>
-			??? <br />
-			Default — *null*.
-		</div>
+			The shadowMapWidth and shadowMapHeight stored in a [page:Vector2 THREE.Vector2]. Set internally during rendering.
+		</div> 
 
-		<h3>[property:Integer shadowMapSize]</h3>
+		<h3>[property:OrthographicCamera shadowCamera]</h3>
 		<div>
-			??? <br />
-			Default — *null*.
-		</div>
+			The shadow's view of the world. Computed internally during rendering from the shadowCamera* settings.
+		</div> 
 
-		<h3>[property:Camera shadowCamera]</h3>
+		<h3>[property:Matrix4 shadowMatrix]</h3>
 		<div>
-			??? <br />
-			Default — *null*.
-		</div>
+			Model to shadow camera space, to compute location and depth in shadow map. Computed internally during rendering.
+		</div> 
 
-		<h3>[property:Matrix shadowMatrix]</h3>
+		<h3>[property:WebGLRenderTarget shadowMap]</h3>
 		<div>
-			??? <br />
-			Default — *null*.
-		</div>
+		    The depth map generated using the shadowCamera; a location beyond a pixel's depth is in shadow. Computed internally during rendering.
+		</div> 
 		
 		<h2>Methods</h2>
 

docs/api/lights/SpotLight.html

@@ -121,7 +121,7 @@ scene.add( spotLight );</code>
 		
 		<h3>[property:Float shadowBias]</h3>
 		<div>
-			Shadow map bias.<br />
+			Shadow map bias, how much to add or subtract from the normalized depth when deciding whether a surface is in shadow.<br />
 			Default — *0*.
 		</div>
 
@@ -143,49 +143,24 @@ scene.add( spotLight );</code>
 			Default — *512*.
 		</div>
 		
-		<h3>[property:Float shadowBias]</h3>
-		<div>
-			Shadow map bias.<br />
-			Default — *0*.
-		</div>
-
-		<h3>[property:Float shadowDarkness]</h3>
-		<div>
-			Darkness of shadow casted by this light (from *0* to *1*).<br />
-			Default — *0.5*.
-		</div>
-
-		<h3>[property:Integer shadowMapWidth]</h3>
-		<div>
-			Shadow map texture width in pixels.<br />
-			Default — *512*.
-		</div>
-
-		<h3>[property:Integer shadowMapHeight]</h3>
-		<div>
-			Shadow map texture height in pixels.<br />
-			Default — *512*.
-		</div>
-
-
-		<h3>[property:object shadowMatrix]</h3>
+		<h3>[property:Vector2 shadowMapSize]</h3>
 		<div>
-		todo
+			The shadowMapWidth and shadowMapHeight stored in a [page:Vector2 THREE.Vector2]. Set internally during rendering.
 		</div> 
 
-		<h3>[property:object shadowMapSize]</h3>
+		<h3>[property:PerspectiveCamera shadowCamera]</h3>
 		<div>
-		todo
+			The shadow's view of the world. Computed internally during rendering from the shadowCamera* settings.
 		</div> 
 
-		<h3>[property:object shadowCamera]</h3>
+		<h3>[property:Matrix4 shadowMatrix]</h3>
 		<div>
-		todo
+			Model to shadow camera space, to compute location and depth in shadow map. Computed internally during rendering.
 		</div> 
 
-		<h3>[property:object shadowMap]</h3>
+		<h3>[property:WebGLRenderTarget shadowMap]</h3>
 		<div>
-		todo
+		    The depth map generated using the shadowCamera; a location beyond a pixel's depth is in shadow. Computed internally during rendering.
 		</div> 
 
 		<h2>Methods</h2>		

examples/webgl_morphtargets_md2_control.html

@@ -109,14 +109,23 @@
 				light.shadowMapWidth = 1024;
 				light.shadowMapHeight = 1024;
 				light.shadowMapDarkness = 0.95;
+				// by turning on the frustum, you can see where the light's
+				// shadow volume is located:
 				//light.shadowCameraVisible = true;
-
-				light.shadowCascade = true;
-				light.shadowCascadeCount = 3;
-				light.shadowCascadeNearZ = [ -1.000, 0.995, 0.998 ];
-				light.shadowCascadeFarZ  = [  0.995, 0.998, 1.000 ];
-				light.shadowCascadeWidth = [ 1024, 1024, 1024 ];
-				light.shadowCascadeHeight = [ 1024, 1024, 1024 ];
+				light.shadowCameraNear = 100;
+				light.shadowCameraFar = 1200;
+				light.shadowCameraTop = 400;
+				light.shadowCameraBottom = -250;
+				light.shadowCameraRight = 900;
+				light.shadowCameraLeft = -1000;
+
+				// cascaded shadows don't appear to be working, and add little
+				// light.shadowCascade = true;
+				//light.shadowCascadeCount = 3;
+				//light.shadowCascadeNearZ = [ -1.000, 0.995, 0.998 ];
+				//light.shadowCascadeFarZ  = [  0.995, 0.998, 1.000 ];
+				//light.shadowCascadeWidth = [ 1024, 1024, 1024 ];
+				//light.shadowCascadeHeight = [ 1024, 1024, 1024 ];
 
 				scene.add( light );
 
@@ -131,6 +140,7 @@
 				ground.rotation.x = - Math.PI / 2;
 				ground.material.map.repeat.set( 64, 64 );
 				ground.material.map.wrapS = ground.material.map.wrapT = THREE.RepeatWrapping;
+				// note that because the ground does not cast a shadow, .castShadow is left false
 				ground.receiveShadow = true;
 
 				scene.add( ground );
@@ -149,8 +159,8 @@
 				renderer.gammaOutput = true;
 				renderer.shadowMapEnabled = true;
 
-				renderer.shadowMapCascade = true;
-				renderer.shadowMapType = THREE.PCFSoftShadowMap;
+				//renderer.shadowMapCascade = true;
+				//renderer.shadowMapType = THREE.PCFSoftShadowMap;
 				//renderer.shadowMapDebug = true;
 
 				// STATS
@@ -226,6 +236,7 @@
 
 							cloneCharacter.shareParts( baseCharacter );
 
+							// cast and receive shadows
 							cloneCharacter.enableShadows( true );
 
 							cloneCharacter.setWeapon( 0 );