<GL.Surface> wrapper => make gl-react more "universal"

[gre]

There is an important API design decision to make, and this is something i've been thinking about for months now.

This issue depends on React 0.14+ being a dependency for react-dom and react-native ( facebook/react-native#2985 ) and therefore will only work with these upcoming versions. This will be a major semver release anyway.

Gist

Split <GL.View> in 2: <GL.Node> (abstract component, doesn't actually render() anything) and introduce a <GL.Surface> (contains the tree of GL.Node/GL component and renders the concrete impl's DOM Canvas / GLKView).

For instance, instead of doing:

<HelloGL width={511} height={341} blue={0.5} />

we will have to do:

<GL.Surface width={511} height={341}>
  <HelloGL blue={0.5} />
</GL.Surface>

This make things less magical and more explicit (final users of GL libraries have the responsability to "instanciate" a pipeline effects with GL.Surface). This will also simplify GL.View logic. Finally, this is the only way we can make GL.View fully universal (GL.Node is render-less so don't depend on the plateform specifics that is implemented by GL.Surface).

How current GL.View works

Currently, a GL.View is an unified component that can either be at the top-level of the tree (then it will render into a <canvas/>) or inside a GL.View (this it is not rendered but we use its props to build a data tree): we can use GL.View directly in the VDOM, it will be rendered into what we call internally a GLCanvas. But if you use a GL.View inside a GL.View it will be used differently: we will merge it with parents to make an unique tree of effects (resulting with only one rendering).

pros:

• it allows to define component that you can use without thinking about if it's contextual to a GL.View or not. e.g: you just do <Blur><Blur>...</Blur></Blur> directly, with wrapping it into a wrapper.

cons:

• complexity of the current code because of the unification
• bad separation of concerns. This makes an unclear semantic and GL.View is harder to explain.
• some props only make sense for the root node (the canvas).
• The current design prevent us from creating truely universal components: GL.View is provided by implementers (gl-react or gl-react-native) but not the shared lib (gl-react-core). The reason is just because at the root level, GL.View have to render into the concrete implementation, but that is not true for all GL.View children nodes which just describe some data.

Proposal 1

split current GL.View into 2 pieces: GL.Surface and GL.Node. A bit like in react-canvas, you have Surface and View.

API changes

GL.Node

• Props: { shader, uniforms?, width?, height?, preload? }
• Methods: none
• render() throws an exception that says something like "You need to wrap your GL Components / GL.Node into a GL.Surface".

GL.Surface

• Props: { width, height, children, opaque?, preload?, onLoad?, onProgress?, autoRedraw?, eventsThrough?, visibleContent? }
  • children must be a GL.Node or a GL Component.
  • NB: width and height are only ruling the View / canvas style, not the actual DrawingBuffer size which will be determined by the root GL.Node (and optionally be inherited)
• Methods: all current methods that are on GL.View

Library responsability

• gl-react-core exposes { Node, Shaders, Uniform, createComponent }
  • Shaders will need an event system so implementers can be in sync (RN impl will list() and then on("create",...) to sync shaders and upload to the ObjC)
• gl-react and gl-react-native exposes { Surface }. it will also still use gl-react-core helpers to create Surface with minimal effort.

Library renaming

• Rename gl-react lib to gl-react-dom
• Rename gl-react-core to gl-react.
  That way we are consistent with react naming. We will rename repository at the very end so we keep history.

[gre]

(implemented in 2.0.0 branch)