Merge pull request #15059 from Mugen87/dev19

Docs: Added manual page about WebGL 2

Merge pull request #15059 from Mugen87/dev19
Docs: Added manual page about WebGL 2
1590aeec · Mr.doob · GitHub · feb480aa · 15b0d2b6 · 1590aeec
3 changed file
--- a/docs/list.js
+++ b/docs/list.js
@@ -10,6 +10,7 @@ var list = {
 				"Browser support": "manual/en/introduction/Browser-support",
 				"WebGL compatibility check": "manual/en/introduction/WebGL-compatibility-check",
 				"How to run things locally": "manual/en/introduction/How-to-run-things-locally",
+				"How to use WebGL 2": "manual/en/introduction/How-to-use-WebGL2",
 				"Drawing lines": "manual/en/introduction/Drawing-lines",
 				"Creating text": "manual/en/introduction/Creating-text",
 				"Loading 3D models": "manual/en/introduction/Loading-3D-models",
@@ -436,6 +437,7 @@ var list = {
 				"浏览器支持": "manual/zh/introduction/Browser-support",
 				"WebGL兼容性检查": "manual/zh/introduction/WebGL-compatibility-check",
 				"如何在本地运行Three.js": "manual/zh/introduction/How-to-run-things-locally",
+				"How to use WebGL 2": "manual/zh/introduction/How-to-use-WebGL2",
 				"画线": "manual/zh/introduction/Drawing-lines",
 				"创建文字": "manual/zh/introduction/Creating-text",
 				"载入3D模型": "manual/zh/introduction/Loading-3D-models",
@@ -757,7 +759,7 @@ var list = {
 				"CompressedTexture": "api/zh/textures/CompressedTexture",
 				"CubeTexture": "api/zh/textures/CubeTexture",
 				"DataTexture": "api/zh/textures/DataTexture",
-				"DataTexture3D": "api/en/textures/DataTexture3D",
+				"DataTexture3D": "api/zh/textures/DataTexture3D",
 				"DepthTexture": "api/zh/textures/DepthTexture",
 				"Texture": "api/zh/textures/Texture",
 				"VideoTexture": "api/zh/textures/VideoTexture"

--- a/docs/manual/en/introduction/How-to-use-WebGL2.html
+++ b/docs/manual/en/introduction/How-to-use-WebGL2.html
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+	<meta charset="utf-8">
+	<base href="../../../" />
+	<script src="list.js"></script>
+	<script src="page.js"></script>
+	<link type="text/css" rel="stylesheet" href="page.css" />
+</head>
+
+<body>
+	<h1>[name]</h1>
+	<br />
+
+	<p>
+		Starting with three.js R95, the engine supports rendering with a WebGL 2 context. By default three.js always uses a
+		WebGL 1 context when creating an instance of *WebGLRenderer*. If you want use a WebGL 2 context, please have a look
+		at the following workflow.
+	</p>
+
+	<h2>Workflow</h2>
+
+	<p>
+		Since WebGL 2 is not supported by all devices that support WebGL 1, it's important to check the respective availability.
+		To do so, please include [link:https://github.com/mrdoob/three.js/blob/master/examples/js/WebGL.js WebGL.js] into your project.
+	</p>
+
+	<code>
+&lt;script src="/path/to/WebGL.js"&gt;&lt;/script&gt;
+	</code>
+
+	<p>
+		Next, use a code similar to the following in order to perform the availability check.
+	</p>
+
+	<code>
+
+if ( WEBGL.isWebGL2Available() === false ) {
+
+	document.body.appendChild( WEBGL.getWebGL2ErrorMessage() );
+
+}
+	</code>
+
+	<p>
+		Now it's time to create the renderer by applying the HTML5 canvas element and the respective WebGL 2 context
+		to the constructor of *WebGLRenderer*. As a result, three.js will internally use the given context for rendering and
+		automatically convert the built-in material's shader code to GLSL ES 3.00.
+	</p>
+
+	<code>
+var canvas = document.createElement( 'canvas' );
+var context = canvas.getContext( 'webgl2' );
+var renderer = new THREE.WebGLRenderer( { canvas: canvas, context: context } );
+	</code>
+
+	<p>
+		Sometimes it is necessary to write custom shader code. Use the following code template as a basis for your own
+		implementation. First, the GLSL ES 3.00 code.
+	</p>
+
+	<code>
+&lt;script id="vs" type="x-shader/x-vertex"&gt;
+#version 300 es
+
+void main() {
+
+	gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
+
+}
+&lt;/script&gt;
+&lt;script id="fs" type="x-shader/x-fragment"&gt;
+#version 300 es
+
+precision highp float;
+precision highp int;
+out vec4 out_FragColor;
+
+void main() {
+
+	out_FragColor = vec4( 1.0 );
+
+}
+&lt;/script&gt;
+	</code>
+	<p>
+		Second, the corresponding material creation in JavaScript.
+	</p>
+	<code>
+var material = new THREE.ShaderMaterial( {
+	vertexShader: document.getElementById( 'vs' ).textContent.trim(),
+	fragmentShader: document.getElementById( 'fs' ).textContent.trim()
+} );
+	</code>
+
+	<h2>Next Steps</h2>
+
+	<p>
+		Have a look at one of the official examples in order to see WebGL 2 features in action.<br /><br />
+
+		[example:webgl2_materials_texture3d WebGL2 / materials / texture3d]<br />
+		[example:webgl2_materials_texture3d_volume WebGL2 / materials / texture3d / volume]<br />
+	</p>
+
+	<h2>Supported features</h2>
+
+	<p>
+		Right now, the engine does only support a subset of all existing WebGL 2 features. The following list provides an
+		overview about what's already available in the latest version of three.js.
+		<ul>
+			<li>3D Textures</li>
+		</ul>
+
+	</p>
+
+</body>
+
+</html>
--- a/docs/manual/zh/introduction/How-to-use-WebGL2.html
+++ b/docs/manual/zh/introduction/How-to-use-WebGL2.html
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+	<meta charset="utf-8">
+	<base href="../../../" />
+	<script src="list.js"></script>
+	<script src="page.js"></script>
+	<link type="text/css" rel="stylesheet" href="page.css" />
+</head>
+
+<body>
+	<h1>[name]</h1>
+	<br />
+
+	<p>
+		Starting with three.js R95, the engine supports rendering with a WebGL 2 context. By default three.js always uses a
+		WebGL 1 context when creating an instance of *WebGLRenderer*. If you want use a WebGL 2 context, please have a look
+		at the following workflow.
+	</p>
+
+	<h2>Workflow</h2>
+
+	<p>
+		Since WebGL 2 is not supported by all devices that support WebGL 1, it's important to check the respective availability.
+		To do so, please include [link:https://github.com/mrdoob/three.js/blob/master/examples/js/WebGL.js WebGL.js] into your project.
+	</p>
+
+	<code>
+&lt;script src="/path/to/WebGL.js"&gt;&lt;/script&gt;
+	</code>
+
+	<p>
+		Next, use a code similar to the following in order to perform the availability check.
+	</p>
+
+	<code>
+
+if ( WEBGL.isWebGL2Available() === false ) {
+
+	document.body.appendChild( WEBGL.getWebGL2ErrorMessage() );
+
+}
+	</code>
+
+	<p>
+		Now it's time to create the renderer by applying the HTML5 canvas element and the respective WebGL 2 context
+		to the constructor of *WebGLRenderer*. As a result, three.js will internally use the given context for rendering and
+		automatically convert the built-in material's shader code to GLSL ES 3.00.
+	</p>
+
+	<code>
+var canvas = document.createElement( 'canvas' );
+var context = canvas.getContext( 'webgl2' );
+var renderer = new THREE.WebGLRenderer( { canvas: canvas, context: context } );
+	</code>
+
+	<p>
+		Sometimes it is necessary to write custom shader code. Use the following code template as a basis for your own
+		implementation. First, the GLSL ES 3.00 code.
+	</p>
+
+	<code>
+&lt;script id="vs" type="x-shader/x-vertex"&gt;
+#version 300 es
+
+void main() {
+
+	gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
+
+}
+&lt;/script&gt;
+&lt;script id="fs" type="x-shader/x-fragment"&gt;
+#version 300 es
+
+precision highp float;
+precision highp int;
+out vec4 out_FragColor;
+
+void main() {
+
+	out_FragColor = vec4( 1.0 );
+
+}
+&lt;/script&gt;
+	</code>
+	<p>
+		Second, the corresponding material creation in JavaScript.
+	</p>
+	<code>
+var material = new THREE.ShaderMaterial( {
+	vertexShader: document.getElementById( 'vs' ).textContent.trim(),
+	fragmentShader: document.getElementById( 'fs' ).textContent.trim()
+} );
+	</code>
+
+	<h2>Next Steps</h2>
+
+	<p>
+		Have a look at one of the official examples in order to see WebGL 2 features in action.<br /><br />
+
+		[example:webgl2_materials_texture3d WebGL2 / materials / texture3d]<br />
+		[example:webgl2_materials_texture3d_volume WebGL2 / materials / texture3d / volume]<br />
+	</p>
+
+	<h2>Supported features</h2>
+
+	<p>
+		Right now, the engine does only support a subset of all existing WebGL 2 features. The following list provides an
+		overview about what's already available in the latest version of three.js.
+		<ul>
+			<li>3D Textures</li>
+		</ul>
+
+	</p>
+
+</body>
+
+</html>