add migration guide for upgrading from Lightning 3 v2.x to v3.0 (#623)

Author: wouterlucas

README.md

@@ -131,3 +131,7 @@ await stage.loadFont('sdf', {
 ```
 
 For more information see [Font Loading](./docs/fontLoading.md)
+
+## Migration Guide
+
+Upgrading from Lightning 3 v2.x? See the [Migration Guide](./docs/migration-2x-to-3.0.md) for detailed information about breaking changes and how to update your code.

docs/canvas-shader-types.md

@@ -0,0 +1,81 @@
+# Canvas ShaderTypes
+
+The [Canvas API](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) does not really have a concept called shaders, however for it to fit better into our architecture we are calling it shaders anyway. You can use the following properties to define your `CanvasShaderType`.
+
+## render
+
+The render property is the only `required` property for the CanvasShaderType. This property requires a function that draws the shader/effect.
+
+```js
+export const Border = {
+  render(ctx, quad, renderContext) {
+    //renders node context(if not called the context won't be drawn)
+    renderContext();
+
+    ctx.strokeStyle = 'green';
+    ctx.lineWidth = 10;
+    ctx.beginPath();
+    //draw an innerBorder
+    ctx.strokeRect(quad.tx + 5, quad.ty + 5, quad.width - 10, quad.height - 10);
+  },
+};
+```
+
+## update
+
+The update property is an `optional` property. We can use to computed and store some values we don't want to calculate / mutate everytime a quad is drawn with canvas.
+
+```js
+export const Border = {
+  props: {
+    color: 0x00ff00ff,
+    width: 20,
+  },
+  update() {
+    this.computed.borderColor = formatRGBAtoString(this.props.color);
+  },
+  render(ctx, quad, renderContext) {
+    //renders node context(if not called the context won't be drawn)
+    renderContext();
+    const borderWidth = this.props.width;
+    ctx.strokeStyle = this.computed.borderColor;
+    ctx.lineWidth = borderWidth;
+    const halfW = borderWidth * 0.5;
+    ctx.beginPath();
+    //draw an innerBorder
+    ctx.strokeRect(
+      quad.tx + halfW,
+      quad.ty + halfW,
+      quad.width - borderWidth,
+      quad.height - borderWidth,
+    );
+  },
+};
+```
+
+## saveAndRestore
+
+Generally when you are about to transform shape, rotation or clip with canvas methods you use `ctx.save` > apply methods > `ctx.restore`. Saving and restoring is very costly if used a lot. To reduce save and restore calls there is a property called `saveAndRestore` you can use to let the renderer know you need it to save and restore before and after this shader is executed.
+
+```js
+export const Rounded = {
+  render(ctx, quad, renderContext) {
+    const path = new Path2D();
+    roundRect(
+      path,
+      quad.tx,
+      quad.ty,
+      quad.width,
+      quad.height,
+      this.computed.radius!,
+    );
+    ctx.clip(path);
+    //renders node context(if not called the context won't be drawn)
+    renderContext()
+  }
+}
+```
+
+See following source to learn more about the Rounded canvas shader.
+
+You might still want to use `ctx.save` and `ctx.restore` in your render function. But this is only done when you want to more effects on top of a node. Just be careful not to overuse it.

docs/custom-shader-types.md

@@ -0,0 +1,62 @@
+# Custom Shaders
+
+To create your own shaders for the Lightning Renderer 3.x you'll have to define a `ShaderType`, this page contains basic knowledge for how Shader Types work.
+
+## ShaderType basics
+
+A ShaderType is a configuration object the renderer needs to create a shader node and optionally extra programs to make it actually render something on the screen.
+
+Any basic ShaderType can consist of the following optional properties
+
+### props
+
+Similar to Blits props, you can use specific values to alter the way an effect is rendered by the renderer. The main difference between the Blits props and ShaderType props is that theses props need a default value, therefor you can only use objects.
+
+```js
+const ShaderType = {
+  props: {
+    foo: 1,
+    fooToo: {
+      default: 1,
+    },
+  },
+};
+```
+
+#### pointer props
+
+You can also use "pointer" props to adjust other props. This is handy in cases you use arrays as value f.e;
+
+```js
+const ShaderType = {
+  props: {
+    foo: [0, 0, 0, 0],
+    fooOne: {
+      set(v, props) {
+        props.foo[1] = v;
+      },
+      get(props) {
+        return props.foo[1];
+      },
+    },
+  },
+};
+```
+
+### getCacheMarkers
+
+In some cases you might want to generate code based on the props you pass when using a specific ShaderType.
+
+## ShaderTypes for different render modes
+
+The Renderer that Blits uses makes use of different ShaderTypes for each render mode, [webgl](./webgl-shader-types.md) or [canvas](./canvas-shader-types.md). Blits(and the Renderer) by default use `webgl` ShaderTypes.
+
+## Including ShaderTypes to your project
+
+You can register ShaderTypes in the Launch settings of your App (in `src/index.js`). The `shaders`-key in the settings is an `Array` that specifies your custom shaders in your App.
+
+```js
+const renderer = new RendererMain();
+
+renderer.stage.shManager.registerShaderType('customShader', CustomShaderType);
+```