Merge remote-tracking branch 'mrdoob/dev' into gltf_loader_lazy

mrdoob · Mar 6, 2020 · 540ba6d · 540ba6d
2 parents ccf11ec + 40188b6
commit 540ba6d
Show file tree

Hide file tree

Showing 62 changed files with 1,952 additions and 1,672 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -25,3 +25,6 @@ jobs:
       env: FORCE_COLOR=0 CI=2
     - <<: *e2e
       env: FORCE_COLOR=0 CI=3
+
+allow_fails:
+  - e2e
diff --git a/build/three.js b/build/three.js
diff --git a/build/three.min.js b/build/three.min.js
diff --git a/build/three.module.js b/build/three.module.js
diff --git a/docs/api/en/materials/MeshPhysicalMaterial.html b/docs/api/en/materials/MeshPhysicalMaterial.html
@@ -13,9 +13,30 @@
 		<h1>[name]</h1>
 
 		<p class="desc">
-			An extension of the [page:MeshStandardMaterial] that allows for greater control over reflectivity.<br /><br />
+			An extension of the [page:MeshStandardMaterial], providing more advanced physically-based rendering properties:
+		</p>
+
+		<ul>
+			<li>
+				<b>Clearcoat:</b> Some materials — like car paints, carbon fiber, and wet surfaces — require a
+				clear, reflective layer on top of another layer that may be irregular or rough. Clearcoat
+				approximates this effect, without the need for a separate transparent surface.
+			</li>
+			<li>
+				<b>Physically-based transparency:</b> One limitation of [page:Material.opacity .opacity] is
+				that highly transparent materials are less reflective. Physically-based [page:.transparency]
+				provides a more realistic option for thin, transparent surfaces like glass.
+			</li>
+			<li>
+				<b>Advanced reflectivity:</b> More flexible reflectivity for non-metallic materials.
+			</li>
+		</ul>
 
-			Note that for best results you should always specify an [page:.envMap environment map] when using this material.
+		<p>
+			As a result of these complex shading features, MeshPhysicalMaterial has a higher performance
+			cost, per pixel, than other three.js materials. Most effects are disabled by default, and add
+			cost as they are enabled. For best results, always specify an [page:.envMap environment map]
+			when using this material.
 		</p>
 
 		<iframe id="scene" src="scenes/material-browser.html#MeshPhysicalMaterial"></iframe>
@@ -61,9 +82,14 @@ <h2>Properties</h2>
 
 		<h3>[property:Float clearcoat]</h3>
 		<p>
-		Represents the thickness of the clear coat layer, from *0.0* to *1.0*. You can use clear coat related properties to enable multilayer
-		materials that have a thin translucent layer over the base layer. Typical examples for this model are car paints or acrylic.
-		Default is *0.0*.
+		Represents the thickness of the clear coat layer, from *0.0* to *1.0*. Use clear coat related properties to enable multilayer
+		materials that have a thin translucent layer over the base layer. Default is *0.0*.
+		</p>
+
+		<h3>[property:Texture clearcoatMap]</h3>
+		<p>
+		The red channel of this texture is multiplied against [page:.clearcoat], for per-pixel control
+		over a coating's thickness. Default is *null*.
 		</p>
 
 		<h3>[property:Float clearcoatNormalMap]</h3>
@@ -75,6 +101,12 @@ <h3>[property:Vector2 clearcoatNormalScale]</h3>
 		<h3>[property:Float clearcoatRoughness]</h3>
 		<p>Roughness of the clear coat layer, from *0.0* to *1.0*. Default is *0.0*.</p>
 
+		<h3>[property:Texture clearcoatRoughnessMap]</h3>
+		<p>
+		The green channel of this texture is multiplied against [page:.clearcoatRoughness], for per-pixel control
+		over a coating's roughness. Default is *null*.
+		</p>
+
 		<h3>[property:Object defines]</h3>
 		<p>An object of the form:
 			<code>
@@ -99,11 +131,11 @@ <h3>[property:Float reflectivity]</h3>
 		<h3>[property:Float transparency]</h3>
 		<p>
 		Degree of transparency, from *0.0* to *1.0*. Default is *0.0*.<br />
-		
+
 		Thin, transparent or semitransparent, plastic or glass materials remain largely reflective even if they are mostly transparent.
-		
+
 		The transparency property can be used to model these materials.<br />
-		
+
 		When transparency is non-zero, [page:Material.opacity opacity] should be set to *1*.
 		</p>
 

diff --git a/docs/api/en/objects/InstancedMesh.html b/docs/api/en/objects/InstancedMesh.html
@@ -17,6 +17,9 @@ <h1>[name]</h1>
 		objects with the same geometry and material but with different world transformations. The usage of [name] will help you
 		to reduce the number of draw calls and thus improve the overall rendering performance in your application.
 		</p>
+		<p>
+		The current implementation requires that materials are not shared between [name] and other 3D objects.
+		</p>
 
 		<h3>Examples</h3>
 

diff --git a/docs/api/zh/materials/MeshPhysicalMaterial.html b/docs/api/zh/materials/MeshPhysicalMaterial.html
@@ -16,6 +16,29 @@ <h1>物理网格材质([name])</h1>
 			请注意，为了获得最佳效果，您在使用此材质时应始终指定环境贴图。
 		</p>
 
+		<ul>
+			<li>
+				<b>Clearcoat:</b> Some materials — like car paints, carbon fiber, and wet surfaces — require a
+				clear, reflective layer on top of another layer that may be irregular or rough. Clearcoat
+				approximates this effect, without the need for a separate transparent surface.
+			</li>
+			<li>
+				<b>Physically-based transparency:</b> One limitation of [page:Material.opacity .opacity] is
+				that highly transparent materials are less reflective. Physically-based [page:.transparency]
+				provides a more realistic option for thin, transparent surfaces like glass.
+			</li>
+			<li>
+				<b>Advanced reflectivity:</b> More flexible reflectivity for non-metallic materials.
+			</li>
+		</ul>
+
+		<p>
+			As a result of these complex shading features, MeshPhysicalMaterial has a higher performance
+			cost, per pixel, than other three.js materials. Most effects are disabled by default, and add
+			cost as they are enabled. For best results, always specify an [page:.envMap environment map]
+			when using this material.
+		</p>
+
 		<iframe id="scene" src="scenes/material-browser.html#MeshPhysicalMaterial"></iframe>
 
 		<script>
@@ -57,9 +80,14 @@ <h2>属性(Properties)</h2>
 
 		<h3>[property:Float clearcoat]</h3>
 		<p>
-		Represents the thickness of the clear coat layer, from *0.0* to *1.0*. You can use clear coat related properties to enable multilayer
-		materials that have a thin translucent layer over the base layer. Typical examples for this model are car paints or acrylic.
-		Default is *0.0*.
+		Represents the thickness of the clear coat layer, from *0.0* to *1.0*. Use clear coat related properties to enable multilayer
+		materials that have a thin translucent layer over the base layer. Default is *0.0*.
+		</p>
+
+		<h3>[property:Texture clearcoatMap]</h3>
+		<p>
+		The red channel of this texture is multiplied against [page:.clearcoat], for per-pixel control
+		over a coating's thickness. Default is *null*.
 		</p>
 
 		<h3>[property:Float clearcoatNormalMap]</h3>
@@ -71,6 +99,12 @@ <h3>[property:Vector2 clearcoatNormalScale]</h3>
 		<h3>[property:Float clearcoatRoughness]</h3>
 		<p>Roughness of the clear coat layer, from *0.0* to *1.0*. Default is *0.0*.</p>
 
+		<h3>[property:Texture clearcoatRoughnessMap]</h3>
+		<p>
+		The green channel of this texture is multiplied against [page:.clearcoatRoughness], for per-pixel control
+		over a coating's roughness. Default is *null*.
+		</p>
+
 		<h3>[property:Object defines]</h3>
 		<p> 如下形式的对象:
 			<code>
@@ -92,11 +126,11 @@ <h3>[property:Float reflectivity]</h3>
 		<h3>[property:Float transparency]</h3>
 		<p>
 		Degree of transparency, from *0.0* to *1.0*. Default is *0.0*.<br />
-		
+
 		Thin, transparent or semitransparent, plastic or glass materials remain largely reflective even if they are mostly transparent.
-		
+
 		The transparency property can be used to model these materials.<br />
-		
+
 		When transparency is non-zero, [page:Material.opacity opacity] should be set to *1*.
 		</p>
 

diff --git a/docs/api/zh/objects/InstancedMesh.html b/docs/api/zh/objects/InstancedMesh.html
@@ -17,6 +17,9 @@ <h1>[name]</h1>
 		objects with the same geometry and material but with different world transformations. The usage of [name] will help you
 		to reduce the number of draw calls and thus improve the overall rendering performance in your application.
 		</p>
+		<p>
+		The current implementation requires that materials are not shared between [name] and other 3D objects.
+		</p>
 
 		<h3>Examples</h3>
 

diff --git a/docs/examples/en/math/convexhull/ConvexHull.html b/docs/examples/en/math/convexhull/ConvexHull.html
@@ -20,6 +20,7 @@ <h2>Constructor</h2>
 
 		<h3>[name]()</h3>
 		<p>
+			Creates a new instance of [name].
 		</p>
 
 		<h2>Properties</h2>
@@ -57,28 +58,35 @@ <h3>[property:Array vertices]</h3>
 		<h2>Methods</h2>
 
 		<h3>[method:HalfEdge addAdjoiningFace]( [param:VertexNode eyeVertex], [param:HalfEdge horizonEdge] )</h3>
-		[page:VertexNode eyeVertex] - The vertex that is added to the hull.<br /><br />
-		[page:HalfEdge horizonEdge] - A single edge of the horizon.<br /><br />
+		<p>
+			[page:VertexNode eyeVertex] - The vertex that is added to the hull.<br />
+			[page:HalfEdge horizonEdge] - A single edge of the horizon.<br /><br />
 
-		<p>Creates a face with the vertices 'eyeVertex.point', 'horizonEdge.tail' and 'horizonEdge.head' in CCW order.
-			All the half edges are created in CCW order thus the face is always pointing outside the hull</p>
+			Creates a face with the vertices 'eyeVertex.point', 'horizonEdge.tail' and 'horizonEdge.head' in CCW order.
+			All the half edges are created in CCW order thus the face is always pointing outside the hull
+		</p>
 
 		<h3>[method:ConvexHull addNewFaces]( [param:VertexNode eyeVertex], [param:HalfEdge horizonEdge] )</h3>
-		[page:VertexNode eyeVertex] - The vertex that is added to the hull.<br /><br />
-		[page:HalfEdge horizon] - An array of half-edges that form the horizon.<br /><br />
+		<p>
+			[page:VertexNode eyeVertex] - The vertex that is added to the hull.<br />
+			[page:HalfEdge horizon] - An array of half-edges that form the horizon.<br /><br />
 
-		<p>Adds 'horizon.length' faces to the hull, each face will be linked with the horizon opposite face and the face on the left/right.</p>
+			Adds 'horizon.length' faces to the hull, each face will be linked with the horizon opposite face and the face on the left/right.
+		</p>
 
 		<h3>[method:ConvexHull addVertexToFace]( [param:VertexNode vertex], [param:Face face]	)</h3>
-		[page:VertexNodeNode vertex] - The vertex to add.<br /><br />
-		[page:Face face] - The target face.<br /><br />
+		<p>
+			[page:VertexNodeNode vertex] - The vertex to add.<br />
+			[page:Face face] - The target face.<br /><br />
 
-		<p>Adds a vertex to the 'assigned' list of vertices and assigns it to the given face.</p>
+			Adds a vertex to the 'assigned' list of vertices and assigns it to the given face.
+		</p>
 
 		<h3>[method:ConvexHull addVertexToHull]( [param:VertexNode eyeVertex] )</h3>
-		[page:VertexNode eyeVertex] - The vertex that is added to the hull.<br /><br />
+		<p>
+			[page:VertexNode eyeVertex] - The vertex that is added to the hull.<br /><br />
 
-		<p>Adds a vertex to the hull with the following algorithm
+			Adds a vertex to the hull with the following algorithm
 			<ul>
 				<li>Compute the 'horizon' which is a chain of half edges. For an edge to belong to this group it must be the edge connecting a face that can see 'eyeVertex' and a face which cannot see 'eyeVertex'.</li>
 				<li>All the faces that can see 'eyeVertex' have its visible vertices removed from the assigned vertex list.</li>
@@ -100,27 +108,32 @@ <h3>[method:Object computeExtremes]()</h3>
 		<p>Computes the extremes values (min/max vectors) which will be used to compute the inital hull.</p>
 
 		<h3>[method:ConvexHull computeHorizon]( [param:Vector3 eyePoint], [param:HalfEdge crossEdge], [param:Face face], [param:Array horizon]	)</h3>
-		[page:Vector3 eyePoint] - The 3D-coordinates of a point.<br /><br />
-		[page:HalfEdge crossEdge] - The edge used to jump to the current face.<br /><br />
-		[page:Face face] - The current face being tested.<br /><br />
-		[page:Array horizon] - The edges that form part of the horizon in CCW order.<br /><br />
+		<p>
+			[page:Vector3 eyePoint] - The 3D-coordinates of a point.<br />
+			[page:HalfEdge crossEdge] - The edge used to jump to the current face.<br />
+			[page:Face face] - The current face being tested.<br />
+			[page:Array horizon] - The edges that form part of the horizon in CCW order.<br /><br />
 
-		<p>Computes a chain of half edges in CCW order called the 'horizon'. For an edge to be part of the horizon it must join a face that can see 'eyePoint' and a face that cannot see 'eyePoint'.</p>
+			Computes a chain of half edges in CCW order called the 'horizon'. For an edge to be part of the horizon it must join a face that can see 'eyePoint' and a face that cannot see 'eyePoint'.
+		</p>
 
 		<h3>[method:ConvexHull computeInitialHull]()</h3>
 
 		<p>Computes the initial simplex assigning to its faces all the points that are candidates to form part of the hull.</p>
 
 		<h3>[method:ConvexHull containsPoint]( [param:Vector3 point] )</h3>
-		[page:Vector3 point] - A point in 3D space.<br /><br />
+		<p>
+			[page:Vector3 point] - A point in 3D space.<br /><br />
 
-		<p>Returns *true* if the given point is inside this convex hull.</p>
+			Returns *true* if the given point is inside this convex hull.
+		</p>
 
 		<h3>[method:ConvexHull deleteFaceVertices]( [param:Face face], [param:Face absorbingFace]	)</h3>
-		[page:Face face] - The given face.<br /><br />
-		[page:Face absorbingFace] - An optional face that tries to absorb the vertices of the first face.<br /><br />
+		<p>
+			[page:Face face] - The given face.<br />
+			[page:Face absorbingFace] - An optional face that tries to absorb the vertices of the first face.<br /><br />
 
-		<p>Removes all the visible vertices that 'face' is able to see.
+			Removes all the visible vertices that 'face' is able to see.
 			<ul>
 				<li>If 'absorbingFace' doesn't exist, then all the removed vertices will be added to the 'unassigned' vertex list.</li>
 				<li>If 'absorbingFace' exists, then this method will assign all the vertices of 'face' that can see 'absorbingFace'.</li>
@@ -129,15 +142,19 @@ <h3>[method:ConvexHull deleteFaceVertices]( [param:Face face], [param:Face absor
 		</p>
 
 		<h3>[method:Vector3 intersectRay]( [param:Ray ray], [param:Vector3 target] )</h3>
-		[page:Ray ray] - The given ray.<br /><br />
-		[page:Vector3 target] - The target vector representing the intersection point.<br /><br />
+		<p>
+			[page:Ray ray] - The given ray.<br />
+			[page:Vector3 target] - The target vector representing the intersection point.<br /><br />
 
-		<p>Performs a ray intersection test with this convext hull. If no intersection is found, *null* is returned.</p>
+			Performs a ray intersection test with this convext hull. If no intersection is found, *null* is returned.
+		</p>
 
 		<h3>[method:Boolean intersectsRay]( [param:Ray ray] )</h3>
-		[page:Ray ray] - The given ray.<br /><br />
+		<p>
+			[page:Ray ray] - The given ray.<br /><br />
 
-		<p>Returns *true* if the given ray intersects with this convex hull.</p>
+			Returns *true* if the given ray intersects with this convex hull.
+		</p>
 
 		<h3>[method:ConvexHull makeEmpty]()</h3>
 
@@ -158,31 +175,40 @@ <h3>[method:ConvexHull reindexFaces]()</h3>
 		<p>Removes inactive (e.g. deleted) faces from the internal face list.</p>
 
 		<h3>[method:VertexNode removeAllVerticesFromFace]( [param:Face face]	)</h3>
-		[page:Face face] - The given face.<br /><br />
+		<p>
+			[page:Face face] - The given face.<br /><br />
 
-		<p>Removes all the visible vertices that a given face is able to see which are stored in the 'assigned' vertext list.</p>
+			Removes all the visible vertices that a given face is able to see which are stored in the 'assigned' vertext list.
+		</p>
 
 		<h3>[method:ConvexHull removeVertexFromFace]( [param:VertexNode vertex], [param:Face face]	)</h3>
-		[page:VertexNode vertex] - The vertex to remove.<br /><br />
-		[page:Face face] - The target face.<br /><br />
+		<p>
+			[page:VertexNode vertex] - The vertex to remove.<br />
+			[page:Face face] - The target face.<br /><br />
 
-		<p>Removes a vertex from the 'assigned' list of vertices and from the given face. It also makes sure that the link from 'face' to the first vertex it sees in 'assigned' is linked correctly after the removal.</p>
+			Removes a vertex from the 'assigned' list of vertices and from the given face. It also makes sure that the link from 'face' to the first vertex it sees in 'assigned' is linked correctly after the removal.
+		</p>
 
 		<h3>[method:ConvexHull resolveUnassignedPoints]( [param:Array newFaces]	)</h3>
-		[page:Face newFaces] - An array of new faces.<br /><br />
+		<p>
+			[page:Face newFaces] - An array of new faces.<br /><br />
 
-		<p>Reassigns as many vertices as possible from the unassigned list to the new faces.</p>
+			Reassigns as many vertices as possible from the unassigned list to the new faces.
+		</p>
 
 		<h3>[method:ConvexHull setFromObject]( [param:Object3D object] )</h3>
-		[page:Object3D object] - [page:Object3D] to compute the convex hull of.<br /><br />
+		<p>
+			[page:Object3D object] - [page:Object3D] to compute the convex hull of.<br /><br />
 
-		<p>Computes the convex hull of an [page:Object3D] (including its children),
-		accounting for the world transforms of both the object and its childrens.</p>
+			Computes the convex hull of an [page:Object3D] (including its children),accounting for the world transforms of both the object and its childrens.
+		</p>
 
 		<h3>[method:ConvexHull setFromPoints]( [param:Array points] )</h3>
-		[page:Array points] - Array of [page:Vector3 Vector3s] that the resulting convex hull will contain.<br /><br />
+		<p>
+			[page:Array points] - Array of [page:Vector3 Vector3s] that the resulting convex hull will contain.<br /><br />
 
-		<p>Computes to convex hull for the given array of points.</p>
+			Computes to convex hull for the given array of points.
+		</p>
 
 		<h2>Source</h2>