Skip to content

Docs: Added manual page about WebGL 2 #15059

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 15, 2018
Merged

Docs: Added manual page about WebGL 2 #15059

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/list.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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"
Expand Down
119 changes: 119 additions & 0 deletions docs/manual/en/introduction/How-to-use-WebGL2.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
<!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>
119 changes: 119 additions & 0 deletions docs/manual/zh/introduction/How-to-use-WebGL2.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
<!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>