onLoad — Will be called when load completes. The argument will be the loaded [page:Object3D object].<br/>
onLoad — Will be called when load completes. The argument will be the loaded [page:Object3D].<br/>
onProgress — Will be called while load progresses. The argument will be the XmlHttpRequest instance, that contain .[page:Integer total] and .[page:Integer loaded] bytes.<br/>
onError — Will be called when load errors.<br/>
</div>
...
...
@@ -39,19 +39,42 @@
Begin loading from url and call onLoad with the parsed response content.
Parse a <em>JSON</em> structure and returns an [page:Object3D object] or a [page:Scene scene].<br/>
Found objects are converted to [page:Mesh meshs] with a [page:BufferGeometry BufferGeometry] and a default [page:MeshPhongMaterial MeshPhongMaterial].<br/>
Found objects are converted to [page:Mesh] with a [page:BufferGeometry] and a default [page:MeshPhongMaterial].<br/>
onLoad — Will be called when load completes. The argument will be the loaded [page:BufferGeometry].<br/>
onProgress — Will be called while load progresses. The argument will be the XmlHttpRequest instance, that contain .[page:Integer total] and .[page:Integer loaded] bytes.<br/>
onError — Will be called when load errors.<br/>
</div>
<div>
Begin loading from url and call onLoad with the parsed response content.
onLoad — Will be called when load completes. The argument will be the loaded [page:MTLLoaderMaterialCreator MTLLoader.MaterialCreator] instance.<br/>
onProgress — Will be called while load progresses. The argument will be the XmlHttpRequest instance, that contain .[page:Integer total] and .[page:Integer loaded] bytes.<br/>
onError — Will be called when load errors.<br/>
</div>
<div>
Begin loading from url and return the loaded material.
</div>
<h3>.parse([page:String text])</h3>
<div>
text — The textual <em>obj</em> structure to parse.
</div>
<div>
Parse a <em>mtl</em> text structure and returns a [page:MTLLoaderMaterialCreator MTLLoader.MaterialCreator] instance.<br/>
onLoad — Will be called when load completes. The argument will be the loaded [page:MTLLoaderMaterialCreator MTLLoader.MaterialCreator] instance.<br/>
onProgress — Will be called while load progresses. The argument will be the XmlHttpRequest instance, that contain .[page:Integer total] and .[page:Integer loaded] bytes.<br/>
onError — Will be called when load errors.<br/>
</div>
<div>
Begin loading from url and return the loaded material.
onLoad — Will be called when load completes. The argument will be the loaded [page:Object3D object].<br/>
onLoad — Will be called when load completes. The argument will be the loaded [page:Object3D].<br/>
onProgress — Will be called while load progresses. The argument will be the XmlHttpRequest instance, that contain .[page:Integer total] and .[page:Integer loaded] bytes.<br/>
onError — Will be called when load errors.<br/>
</div>
...
...
@@ -44,8 +44,8 @@
text — The textual <em>obj</em> structure to parse.
</div>
<div>
Parse an <em>obj</em> text structure and returns an [page:Object3D object].<br/>
Found objects are converted to [page:Mesh meshs] with a [page:BufferGeometry BufferGeometry] and a default [page:MeshLambertMaterial MeshLambertMaterial].
Parse an <em>obj</em> text structure and returns a [page:Object3D].<br/>
Found objects are converted to [page:Mesh] with a [page:BufferGeometry] and a default [page:MeshLambertMaterial].
<divclass="desc">Material rendered with custom shaders. A shader is a small program written in [link:https://www.opengl.org/documentation/glsl/ GLSL] to run on the GPU. You may want to use a custom shader if you need to:
<divclass="desc">Material rendered with custom shaders. A shader is a small program written in [link:https://www.opengl.org/documentation/glsl/ GLSL] to run on the GPU. You may want to use a custom shader if you need to:
<ul>
<li>implement an effect not included with any of the built-in [page:Material materials]</li>
<li>combine many objects into a single [page:Geometry] or [page:BufferGeometry] in order to improve performance</li>
<li>associate custom data with individual vertices ("custom attributes")</li>
</ul>
Note that a ShaderMaterial will only be rendered properly by [page:WebGLRenderer], since the GLSL code in the vertexShader and fragmentShader properties must be compiled and run on the GPU using WebGL.
Note that a ShaderMaterial will only be rendered properly by [page:WebGLRenderer], since the GLSL code in the vertexShader and fragmentShader properties must be compiled and run on the GPU using WebGL.
</div>
<h3>Example</h3>
...
...
@@ -39,7 +39,7 @@
</code>
<h3>Vertex shaders and fragment shaders</h3>
<p>You can specify two different types of shaders for each material:
<p>You can specify two different types of shaders for each material:
<ul>
<li>The *vertex shader* runs first; it recieves *attributes*, calculates/manipulates the position of each individual vertex, and passes additional data (*varying*s) to the fragment shader.</li>
<li>The *fragment shader* runs second; it sets the color of each individual "fragment" (pixel) rendered to the screen.</li>
...
...
@@ -69,13 +69,13 @@
Custom attributes and uniforms must be declared both in your GLSL shader code (within *vertexShader* and/or *fragmentShader*), <emph>and</emph> in the *attributes* and *uniforms* properties of your ShaderMaterial. The declaration in the material is necessary to ensure [page:WebGLRenderer] passes your attribute/uniform data in a buffer to the GPU when the shader is run. Note that *varying*s only need to be declared within the shader code (not within the material).
</p>
<p>
To declare a custom attribute, use the *attributes* property of the material:
To declare a custom attribute, use the *attributes* property of the material:
<code>
attributes: {
vertexOpacity: { type: 'f', value: [] }
}
</code>
Each attribute must have a *type* property and a *value* property.
Each attribute must have a *type* property and a *value* property.
The way attribute data is stored depends on whether you're using [page:BufferGeometry] or [page:Geometry]:
The way attribute data is stored depends on whether you're using [page:BufferGeometry] or [page:Geometry]:
<ul>
<li>When using [page:Geometry], attribute data is stored directly on the <emph>material</emph>, using the attribute's *value* array; each element of *value* should correspond to one vertex. To update an attribute, set the *needsUpdate* flag to true on the material attribute:
<code>
...
...
@@ -135,7 +135,7 @@
time: { type: "f", value: 1.0 },
resolution: { type: "v2", value: new THREE.Vector2() }
}
</code>
</code>
Each uniform must have a <ahref="#uniform-types">*type*</a> and a *value*:
where *type* is a <ahref="#uniform-types">uniform type string</a>, and *value* is the value of the uniform. Names must match the name of the uniform, as defined in the GLSL code. Note that uniforms are refreshed on every frame, so updating the value of the uniform will immediately update the value available to the GLSL code.
</div>
</div>
<h3>[property:Object attributes]</h3>
<div>
...
...
@@ -230,12 +230,12 @@
<code>
{ type: 'f', value: [1.0, 0.5, 2.0, ...] }
</code>
where *type* is an <ahref="#attribute-types">attribute type string</a>, and *value* is an array containing an attribute value for each vertex in the geometry (or *undefined* if using [page:BufferGeometry]). Names must match the name of the attribute, as defined in the GLSL code.
where *type* is an <ahref="#attribute-types">attribute type string</a>, and *value* is an array containing an attribute value for each vertex in the geometry (or *undefined* if using [page:BufferGeometry]). Names must match the name of the attribute, as defined in the GLSL code.
</p>
<p>
Note that attribute buffers are <emph>not</emph> refreshed automatically when their values change; if using [page:Geometry], set <code>needsUpdate = true</code> on the attribute definition. If using [page:BufferGeometry], set <code>needsUpdate = true</code> on the [page:BufferAttribute].
</p>
</div>
</div>
<h3>[property:Object defines]</h3>
<div>
...
...
@@ -251,49 +251,49 @@
#define FOO 15
#define BAR true
</code>
in the GLSL code.
</div>
in the GLSL code.
</div>
<h3>[property:String fragmentShader]</h3>
<div>
Fragment shader GLSL code. This is the actual code for the shader. In the example above, the *vertexShader* and *fragmentShader* code is extracted from the DOM; it could be passed as a string directly or loaded via AJAX instead.
</div>
</div>
<h3>[property:String vertexShader]</h3>
<div>
Vertex shader GLSL code. This is the actual code for the shader. In the example above, the *vertexShader* and *fragmentShader* code is extracted from the DOM; it could be passed as a string directly or loaded via AJAX instead.
</div>
</div>
<h3>[property:Boolean lights]</h3>
<div>
Defines whether this material uses lighting; true to pass uniform data related to lighting to this shader
</div>
</div>
<h3>[property:Boolean morphTargets]</h3>
<div>
Defines whether the material uses morphTargets; true morphTarget attributes to this shader
</div>
</div>
<h3>[property:Boolean morphNormals]</h3>
<div>
Defines whether the material uses morphNormals; true to pass morphNormal attributes to this shader
</div>
</div>
<h3>[property:Boolean wireframe]</h3>
<div>
Render geometry as wireframe (using GL_LINES instead of GL_TRIANGLES). Default is false (i.e. render as flat polygons).
</div>
</div>
<h3>[property:Number vertexColors]</h3>
<div>
Define how the vertices are colored, by defining how the *colors* attribute gets populated. Possible values are [page:Materials THREE.NoColors], [page:Materials THREE.FaceColors] and [page:Materials THREE.VertexColors]. Default is THREE.NoColors.
</div>
<h3>[property:Boolean skinning]</h3>
<div>
Define whether the material uses skinning; true to pass skinning attributes to the shader. Default is false.
</div>
</div>
<h3>[property:Boolean fog]</h3>
<div>Define whether the material color is affected by global fog settings; true to pass fog uniforms to the shader. Default is false.</div>
...
...
@@ -302,7 +302,7 @@
<h3>[property:Number shading]</h3>
<div>
Define shading type, which determines whether normals are smoothed between vertices; possible values are [page:Materials THREE.SmoothShading] or [page:Materials THREE.FlatShading]. Default is THREE.SmoothShading.
</div>
</div>
<h3>[property:Number linewidth]</h3>
<div>Controls line thickness; only effective if the material is attached to a [page:Line]. Default is 1.</div>
...
...
@@ -321,7 +321,7 @@
<h3>[method:todo clone]()</h3>
<div>
Generates a shallow copy of this material. Note that the vertexShader and fragmentShader are copied <emph>by reference</emph>, as are the definitions of the *attributes*; this means that clones of the material will share the same compiled [page:WebGLProgram]. However, the *uniforms* are copied <emph>by value</emph>, which allows you to have different sets of uniforms for different copies of the material.
Generates a shallow copy of this material. Note that the vertexShader and fragmentShader are copied <emph>by reference</emph>, as are the definitions of the *attributes*; this means that clones of the material will share the same compiled [page:WebGLProgram]. However, the *uniforms* are copied <emph>by value</emph>, which allows you to have different sets of uniforms for different copies of the material.
