Skip to content

Commit 97408c5

Browse files
erich666erich666
committed
Documented shadow map settings, fixed demo
Documented shadow map settings for directional and spotlights, and duplicate entries removed. AlteredQualia's experimental cascaded shadow code, currently broken, has been labeled as "experimental" - in the long-term it should either be fixed or deleted. Fixed demo's (missing) shadows by turning off cascading and using tight bounds on a standard shadow map; added comments. Original demo on AlteredQualia's site still works, if anyone wants to find the regressions and fix them. Original is here: http://alteredqualia.com/three/examples/webgl_morphtargets_md2_control.html
1 parent ca14c79 commit 97408c5

3 files changed

Lines changed: 55 additions & 74 deletions

File tree

‎docs/api/lights/DirectionalLight.html‎

Lines changed: 26 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,7 @@ <h3>[property:Boolean shadowCameraVisible]</h3>
103103

104104
<h3>[property:Float shadowBias]</h3>
105105
<div>
106-
Shadow map bias.<br />
106+
Shadow map bias, how much to add or subtract from the normalized depth when deciding whether a surface is in shadow.<br />
107107
Default — *0*.
108108
</div>
109109

@@ -127,81 +127,76 @@ <h3>[property:Integer shadowMapHeight]</h3>
127127

128128
<h3>[property:Boolean shadowCascade]</h3>
129129
<div>
130-
??? <br />
130+
**Experimental** If true, use a series of shadow maps in a cascade. This can give better z-depth resolution for a directional light. <br />
131131
Default — *false*.
132132
</div>
133133

134-
<h3>[property:Vector3 shadowCascadeOffset]</h3>
134+
<h3>[property:Integer shadowCascadeCount]</h3>
135135
<div>
136-
??? <br />
137-
Default — *Three.Vector3( 0, 0, -1000 )*.
136+
Number of shadow maps to allocate in a cascade (one after another). <br />
137+
Default — *2*.
138138
</div>
139139

140-
<h3>[property:Integer shadowCascadeCount]</h3>
140+
<h3>[property:Vector3 shadowCascadeOffset]</h3>
141141
<div>
142-
??? <br />
143-
Default — *2*.
142+
A relative position to real camera where virtual shadow cameras are attached. A magic vector; scene and light orientation dependent. <br />
143+
Default — *Three.Vector3( 0, 0, -1000 )*.
144144
</div>
145145

146146
<h3>[property:Array shadowCascadeBias]</h3>
147147
<div>
148-
??? <br />
148+
An array of shadowMapBias values for the corresponding shadow map in the cascade, near to far. <br />
149149
Default — <strong>[ 0, 0, 0 ]</strong>.
150150
</div>
151151

152152
<h3>[property:Array shadowCascadeWidth]</h3>
153153
<div>
154-
??? <br />
154+
An array of shadowMapWidth values for the corresponding shadow map in the cascade, near to far. <br />
155155
Default — <strong>[ 512, 512, 512 ]</strong>.
156156
</div>
157157

158158
<h3>[property:Array shadowCascadeHeight]</h3>
159159
<div>
160-
??? <br />
160+
An array of shadowMapHeight values for the corresponding shadow map in the cascade, near to far. <br />
161161
Default — <strong>[ 512, 512, 512 ]</strong>.
162162
</div>
163163

164164
<h3>[property:Array shadowCascadeNearZ]</h3>
165165
<div>
166-
??? <br />
166+
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 />
167167
Default — <strong>[ -1.000, 0.990, 0.998 ]</strong>.
168168
</div>
169169

170170
<h3>[property:Array shadowCascadeFarZ]</h3>
171171
<div>
172-
??? <br />
172+
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 />
173173
Default — <strong>[ 0.990, 0.998, 1.000 ]</strong>.
174174
</div>
175175

176176
<h3>[property:Array shadowCascadeArray]</h3>
177177
<div>
178-
??? <br />
179-
Default — <strong>[ ]</strong>.
178+
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.
180179
</div>
181180

182-
<h3>[property:RenderTarget shadowMap]</h3>
181+
<h3>[property:Vector2 shadowMapSize]</h3>
183182
<div>
184-
??? <br />
185-
Default — *null*.
186-
</div>
183+
The shadowMapWidth and shadowMapHeight stored in a [page:Vector2 THREE.Vector2]. Set internally during rendering.
184+
</div>
187185

188-
<h3>[property:Integer shadowMapSize]</h3>
186+
<h3>[property:OrthographicCamera shadowCamera]</h3>
189187
<div>
190-
??? <br />
191-
Default — *null*.
192-
</div>
188+
The shadow's view of the world. Computed internally during rendering from the shadowCamera* settings.
189+
</div>
193190

194-
<h3>[property:Camera shadowCamera]</h3>
191+
<h3>[property:Matrix4 shadowMatrix]</h3>
195192
<div>
196-
??? <br />
197-
Default — *null*.
198-
</div>
193+
Model to shadow camera space, to compute location and depth in shadow map. Computed internally during rendering.
194+
</div>
199195

200-
<h3>[property:Matrix shadowMatrix]</h3>
196+
<h3>[property:WebGLRenderTarget shadowMap]</h3>
201197
<div>
202-
??? <br />
203-
Default — *null*.
204-
</div>
198+
The depth map generated using the shadowCamera; a location beyond a pixel's depth is in shadow. Computed internally during rendering.
199+
</div>
205200

206201
<h2>Methods</h2>
207202

‎docs/api/lights/SpotLight.html‎

Lines changed: 9 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,7 @@ <h3>[property:Boolean shadowCameraVisible]</h3>
121121

122122
<h3>[property:Float shadowBias]</h3>
123123
<div>
124-
Shadow map bias.<br />
124+
Shadow map bias, how much to add or subtract from the normalized depth when deciding whether a surface is in shadow.<br />
125125
Default — *0*.
126126
</div>
127127

@@ -143,49 +143,24 @@ <h3>[property:Integer shadowMapHeight]</h3>
143143
Default — *512*.
144144
</div>
145145

146-
<h3>[property:Float shadowBias]</h3>
147-
<div>
148-
Shadow map bias.<br />
149-
Default — *0*.
150-
</div>
151-
152-
<h3>[property:Float shadowDarkness]</h3>
153-
<div>
154-
Darkness of shadow casted by this light (from *0* to *1*).<br />
155-
Default — *0.5*.
156-
</div>
157-
158-
<h3>[property:Integer shadowMapWidth]</h3>
159-
<div>
160-
Shadow map texture width in pixels.<br />
161-
Default — *512*.
162-
</div>
163-
164-
<h3>[property:Integer shadowMapHeight]</h3>
165-
<div>
166-
Shadow map texture height in pixels.<br />
167-
Default — *512*.
168-
</div>
169-
170-
171-
<h3>[property:object shadowMatrix]</h3>
146+
<h3>[property:Vector2 shadowMapSize]</h3>
172147
<div>
173-
todo
148+
The shadowMapWidth and shadowMapHeight stored in a [page:Vector2 THREE.Vector2]. Set internally during rendering.
174149
</div>
175150

176-
<h3>[property:object shadowMapSize]</h3>
151+
<h3>[property:PerspectiveCamera shadowCamera]</h3>
177152
<div>
178-
todo
153+
The shadow's view of the world. Computed internally during rendering from the shadowCamera* settings.
179154
</div>
180155

181-
<h3>[property:object shadowCamera]</h3>
156+
<h3>[property:Matrix4 shadowMatrix]</h3>
182157
<div>
183-
todo
158+
Model to shadow camera space, to compute location and depth in shadow map. Computed internally during rendering.
184159
</div>
185160

186-
<h3>[property:object shadowMap]</h3>
161+
<h3>[property:WebGLRenderTarget shadowMap]</h3>
187162
<div>
188-
todo
163+
The depth map generated using the shadowCamera; a location beyond a pixel's depth is in shadow. Computed internally during rendering.
189164
</div>
190165

191166
<h2>Methods</h2>

‎examples/webgl_morphtargets_md2_control.html‎

Lines changed: 20 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -109,14 +109,23 @@
109109
light.shadowMapWidth = 1024;
110110
light.shadowMapHeight = 1024;
111111
light.shadowMapDarkness = 0.95;
112+
// by turning on the frustum, you can see where the light's
113+
// shadow volume is located:
112114
//light.shadowCameraVisible = true;
113-
114-
light.shadowCascade = true;
115-
light.shadowCascadeCount = 3;
116-
light.shadowCascadeNearZ = [ -1.000, 0.995, 0.998 ];
117-
light.shadowCascadeFarZ = [ 0.995, 0.998, 1.000 ];
118-
light.shadowCascadeWidth = [ 1024, 1024, 1024 ];
119-
light.shadowCascadeHeight = [ 1024, 1024, 1024 ];
115+
light.shadowCameraNear = 100;
116+
light.shadowCameraFar = 1200;
117+
light.shadowCameraTop = 400;
118+
light.shadowCameraBottom = -250;
119+
light.shadowCameraRight = 900;
120+
light.shadowCameraLeft = -1000;
121+
122+
// cascaded shadows don't appear to be working, and add little
123+
// light.shadowCascade = true;
124+
//light.shadowCascadeCount = 3;
125+
//light.shadowCascadeNearZ = [ -1.000, 0.995, 0.998 ];
126+
//light.shadowCascadeFarZ = [ 0.995, 0.998, 1.000 ];
127+
//light.shadowCascadeWidth = [ 1024, 1024, 1024 ];
128+
//light.shadowCascadeHeight = [ 1024, 1024, 1024 ];
120129

121130
scene.add( light );
122131

@@ -131,6 +140,7 @@
131140
ground.rotation.x = - Math.PI / 2;
132141
ground.material.map.repeat.set( 64, 64 );
133142
ground.material.map.wrapS = ground.material.map.wrapT = THREE.RepeatWrapping;
143+
// note that because the ground does not cast a shadow, .castShadow is left false
134144
ground.receiveShadow = true;
135145

136146
scene.add( ground );
@@ -149,8 +159,8 @@
149159
renderer.gammaOutput = true;
150160
renderer.shadowMapEnabled = true;
151161

152-
renderer.shadowMapCascade = true;
153-
renderer.shadowMapType = THREE.PCFSoftShadowMap;
162+
//renderer.shadowMapCascade = true;
163+
//renderer.shadowMapType = THREE.PCFSoftShadowMap;
154164
//renderer.shadowMapDebug = true;
155165

156166
// STATS
@@ -226,6 +236,7 @@
226236

227237
cloneCharacter.shareParts( baseCharacter );
228238

239+
// cast and receive shadows
229240
cloneCharacter.enableShadows( true );
230241

231242
cloneCharacter.setWeapon( 0 );

0 commit comments

Comments
 (0)