Skip to content

Better shader docs #3154

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 19 commits into from
Oct 18, 2017
Merged

Better shader docs #3154

Changes from 1 commit
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
c024413
Update material.md
machenmusik Oct 11, 2017
2f67e5a
Update material.md
machenmusik Oct 11, 2017
47e22ec
Update material.md
machenmusik Oct 11, 2017
6a370ca
Update material.md
machenmusik Oct 11, 2017
8d0c325
Update material.md
machenmusik Oct 11, 2017
948b2e2
Update material.md
machenmusik Oct 11, 2017
a387b47
Create shaders.md
machenmusik Oct 11, 2017
d6ac66a
Update shaders.md
machenmusik Oct 11, 2017
d0c268d
Update shaders.md
machenmusik Oct 11, 2017
b2459d1
Update shaders.md
machenmusik Oct 11, 2017
c3fc4d2
Update shaders.md
machenmusik Oct 11, 2017
a451ab4
Update material.md
machenmusik Oct 11, 2017
072cda2
Update material.md
machenmusik Oct 12, 2017
50966cd
Update material.md
machenmusik Oct 12, 2017
392f796
Update material.md
machenmusik Oct 12, 2017
9653524
remove separate shaders section per discussion on PR
machenmusik Oct 17, 2017
948b3d1
aframe-shadertoy-gallery is gone
machenmusik Oct 17, 2017
16ae6e5
add examples in header
machenmusik Oct 17, 2017
27c6ddb
[docs] add don's displacement shader example to material docs
ngokevin Oct 11, 2017
File filter

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Update material.md
  • Loading branch information
@machenmusik @ngokevin
machenmusik authored and ngokevin committed Oct 18, 2017
commit 47e22ecfd6e05c36303485a61d8a430a25eb6777
63 changes: 42 additions & 21 deletions docs/components/material.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -335,39 +335,53 @@ We can register custom shader materials for appearances and effects using
`AFRAME.registerShader`.

[example]: https://codepen.io/machenmusik/pen/WZyQNj
Here is an [example][example] CodePen with step-by-step commentary.
Let's walk through an [example CodePen][example] with step-by-step commentary.

As always, we need to include the A-Frame script.
Here, we use RawGit to include the latest master version.

```js
<!-- Include A-Frame latest master distribution, via RawGit. -->
<!-- Really should be in <head>; in CodePen body for simple viewing. -->
<script src="https://rawgit.com/aframevr/aframe/master/dist/aframe-master.min.js"></script>
Copy link
Member

@donmccurdy donmccurdy Oct 12, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any reason we need to be suggesting the master version in the docs?

@ngokevin do versions get automatically find/replaced when we do a release?
Copy link
Contributor Author

@machenmusik machenmusik Oct 12, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No reason other than not having to change it every release.
```

<!-- Components and shaders go after A-Frame, but before the scene declaration. -->
Next, we define any custom components and shaders we may want to use,
after A-Frame, but before the scene declaration.
Here, we begin our `my-custom` shader.
The schema declares any parameters for the shader.
```js
<script>
AFRAME.registerShader('my-custom', {
// The schema declares any parameters for the shader.
schema: {
// Where relevant, it is customary to support color.
// The A-Frame schema uses `type:'color'`, so it will parse string values like 'white' or 'red.
// `is:'uniform'` tells A-Frame this should appear as uniform value in the shader(s).
```
Where relevant, it is customary to support at least two data values:

- `color`: A-Frame uses `type:'color'`, so it will parse string values like 'white' or 'red.
- `opacity`: This is commonly used for fading in and out.

`is:'uniform'` tells A-Frame this should appear as uniform value in the shader(s).

```js
color: {type:'color', is:'uniform', default:'red'},
// It is customary to support opacity, for fading in and out.
opacity: {type:'number', is:'uniform', default:1.0}
},

// Setting raw to true uses THREE.RawShaderMaterial instead of ShaderMaterial,
// so your shader strings are used as-is, for advanced shader usage.
// Here, we want the usual prefixes with GLSL constants etc.,
// so we set it to false.
// (Which is also the default, so we could have omitted it).
```

Setting raw to true uses THREE.RawShaderMaterial instead of ShaderMaterial,
so your shader strings are used as-is, for advanced shader usage.
Copy link
Member

@donmccurdy donmccurdy Oct 12, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd link to the docs for THREE.RawShaderMaterial and ShaderMaterial here.

so your shader strings are used as-is, for advanced shader usage.

maybe better to be explicit: "so built-in uniforms and attributes are not automatically added to your shader code."
Copy link
Contributor Author

@machenmusik machenmusik Oct 12, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done
Here, we want the usual prefixes with GLSL constants etc.,
so we set it to false.
(Which is also the default, so we could have omitted it).
```js
raw: false,
```

Here, we're going to use the default vertex shader by omitting vertexShader.
But note that if your fragment shader cares about texture coordinates,
the vertex shader should set uniform values to use in the fragment shader.

// Here, we're going to use the default vertex shader by omitting vertexShader.
// But note that if your fragment shader cares about texture coordinates,
// the vertex shader should set uniform values to use in the fragment shader.

// Since almost every WebVR-capable browser supports ES6,
// define our fragment shader as a multi-line string.
Since almost every WebVR-capable browser supports ES6,
we define our fragment shader as a multi-line string.
```js
fragmentShader:
`
// Use medium precision.
Expand All @@ -391,7 +405,11 @@ AFRAME.registerShader('my-custom', {
`
});
</script>
```

Here is the A-Frame scene declaration that uses our `my-custom` shader:

```
<!-- Declaration of the A-Frame scene. -->
<a-scene>
<!-- Black skybox at effectively infinite distance. -->
Expand All @@ -406,6 +424,8 @@ AFRAME.registerShader('my-custom', {
</a-scene>
```

Again, here is a link to view the [example CodePen][example].

### `registerShader`

Like components, custom materials have schema and lifecycle handlers.
Expand Down Expand Up @@ -451,6 +471,7 @@ The uniform types supported by A-Frame are summarized in the table below.
Note that `time` can eliminate the need for a `tick()` handler in many cases.

| A-Frame Type | THREE Type | GLSL Shader Type |
|--------------|------------|------------------|
| array | v3 | vec3 |
| color | v3 | vec3 |
| int   | i | int |
Expand Down