From 9f1b55605364462d4ca5e1ebfe0f09f47b1af30f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABtan=20Renaudeau?= Date: Tue, 18 Aug 2015 22:05:00 +0200 Subject: [PATCH] writing the documentation --- docs/api/README.md | 16 +++++++++ docs/api/Shaders.create.md | 35 +++++++++++++++++++ docs/api/Target.md | 24 +++++++++++++ docs/api/View.md | 70 ++++++++++++++++++++++++++++++++++++++ index.js | 1 - 5 files changed, 145 insertions(+), 1 deletion(-) create mode 100644 docs/api/Shaders.create.md create mode 100644 docs/api/Target.md create mode 100644 docs/api/View.md diff --git a/docs/api/README.md b/docs/api/README.md index fa33708..deb35cb 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -1 +1,17 @@ # The API + +```js +var GL = require("gl-react-native"); +``` + +## [GL.Shaders.create](Shaders.create.md) + +`GL.Shaders.create(spec)` allows to create shaders that can be used later in GL.View component. + +## [GL.View](View.md) + +`GL.View` is a React Component that renders a given shader with uniforms (parameters to send to the shader). + +## [GL.Target](Target.md) + +*(advanced)* `GL.Target` allows to render a shader with any content (any React Native component rasterized as a uniform texture). diff --git a/docs/api/Shaders.create.md b/docs/api/Shaders.create.md new file mode 100644 index 0000000..049a16e --- /dev/null +++ b/docs/api/Shaders.create.md @@ -0,0 +1,35 @@ +# GL.Shaders.create + +`GL.Shaders.create(spec)` allows to create shaders that can be used later in *GL.View* component. + + +**Example usage:** + +```js +var shaders = GL.Shaders.create({ + myEffect: { + frag: ` +void main () { + gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0); // red +} + ` + }, + ... +}) + +// Use it later: + +``` + +There are two kinds of OpenGL Shaders: vertex and fragment shaders. +The vertex shader iterates over polygons and computes a position, the fragment shaders iterates over pixels and computes a color. + +In current version of `gl-react-native`, the vertex shader is implemented for you +and you only have to implement the fragment shader. + +> This documentation assumes you know the basics of GLSL, the OpenGL Shading Language, if not, feel free to learn [shader-school](https://www.npmjs.com/package/shader-school), read the [specification](https://www.opengl.org/documentation/glsl/) or learn from the examples. + + +`GL.Shaders.create` is inspired from ReactNative's `StyleSheet.create`: it creates an object with key-value and will returns an object with the same keys and where the values can be used in the Virtual DOM. + +The value of each Shader is an object with a `frag` field: the fragment GLSL code. diff --git a/docs/api/Target.md b/docs/api/Target.md new file mode 100644 index 0000000..ec98b9e --- /dev/null +++ b/docs/api/Target.md @@ -0,0 +1,24 @@ +# GL.Target + +`GL.Target` allows to render a shader with any content (any React Native component rasterized as a uniform texture). + +> **N.B.** This feature is advanced and experimental. It current does not yet support subviews content refreshing (like Image load event,...). + +**Example:** + +```js +render () { + return + + + ...any React Native components + + + ; +} +``` + +## Props + +- **`uniform`** *string* **(required)**: The name of the shader texture uniform to use for rendering the content. diff --git a/docs/api/View.md b/docs/api/View.md new file mode 100644 index 0000000..4ff93a2 --- /dev/null +++ b/docs/api/View.md @@ -0,0 +1,70 @@ +# GL.View + +`GL.View` is a React Component that renders a given shader with uniforms (parameters to send to the shader). + +**Quick Examples:** + +Renders a "standalone" shader: + +```js +render () { + return ; +} +``` + +Renders a shader with uniform parameters: + +```js +render () { + return ; + /* + // in myEffect2: + uniform float floatValue; + uniform vec3 vec3Value; + */ +} +``` + +Renders a shader with an image (texture): + +```js +render () { + return ; + /* + // in myEffect3: + uniform sampler2D textureName; + */ +} +``` + + +## Props + +- **`shader`** *id created by GL.Shaders.create* **(required)**: The shader to use for rendering the `GL.View`. +- **`width`** and **`height`** *Number* **(required)**: the size of the view. +- **`uniforms`**: an object that contains all uniform parameters to send to the shader. The key is the uniform name and the value is whatever value that makes sense for the uniform's type (see below). +- **`opaque`**: specify if the view should be opaque. By default, it is true, meaning that the GL View won't support texture opacity and alpha channel. + +## Uniform types + +Here is the correspondance of GLSL and JavaScript types. + +- `int`, `float`, `bool` : Number (e.g: `42`). +- `sampler2D` : an object with an `uri` (`require("image!id")` is also supported), exactly like the `source` prop of `React.Image`. +- `vecN`,`ivecN`,`bvecN` where N is {2,3,4} : an array of N Number (e.g: `[1, 2, 3.5]` for a `vec3`) + +Complex struct types and uniform array **are not** currently supported. + +## Note on textures + +Images given to uniforms props are always loaded as they are. If you want resize/crop features, you can use an `React.Image` inside a `GL.Target`. diff --git a/index.js b/index.js index fd3c9a0..b7d61a8 100644 --- a/index.js +++ b/index.js @@ -111,7 +111,6 @@ GLView.propTypes = { width: PropTypes.number.isRequired, height: PropTypes.number.isRequired, uniforms: PropTypes.object, - childrenUniform: PropTypes.string, opaque: PropTypes.bool }; GLView.defaultProps = { -- 2.26.2