Sprites Shader Media Storage

Contents

The record in the data store is just the id and the data object. Everything a listing shows, the name and the size and layer-count summary, is the meta record, so this store carries only the picture.

Data

The data object carries the size the image renders at, the shared global code, the image wide parameters and the layer stack. A shader image holds no stored pixels: the width and height are the size the layers render into, not a buffer.

Globals

globals is a plain string of GLSL, the shared code every layer gets. When a layer's full source is assembled it is placed ahead of the layer's own code, so a function or constant defined in the globals can be called from any layer's LayerMain. It declares no main of its own; it holds helpers only. See Composition for where it lands in the assembled source.

Parameters

A parameter becomes a GLSL uniform passed into the shader. The image wide params are passed to every layer; a layer's own params are passed to that layer only. A parameter is { name, type, value }. The value is a tagged union: it carries one of optionalFloat, optionalVec2, optionalVec3 or optionalVec4, and which one is present is decided by the type. Exactly one field is set at a time; the rest are absent.

{ "name": "uCentre", "type": "vec2",  "value": { "optionalVec2": { "x": 0, "y": 0 } } }
{ "name": "uTint",   "type": "colour", "value": { "optionalVec4": { "x": 1, "y": 0.4, "z": 0.2, "w": 1 } } }

Layers

layers is an array of layer objects, bottom to top. Each layer renders into its own texture, taking the texture the layer below rendered as its input, so the layers compose like a chain of effects. The bottom layer's input is a blank, transparent texture. Each layer holds its name, a visible flag, its GLSL code and its own parameters.

Composition

A layer is never stored as complete GLSL; the stored code is just the layer's own part. The full source a layer compiles from is assembled in a fixed order, so the same stored fields always produce the same shader:

1. The built-in prelude: the GLSL version and precision, the built-in uniforms uInput, the texture the layer below rendered, and uResolution, the image size in pixels, the fragment output, and the built-in per-fragment values the code may read.
2. The image parameter uniform declarations, one uniform <type> <name>; per image parameter.
3. The layer parameter uniform declarations, the same for the layer's own parameters.
4. The shared globals, the globals string.
5. The layer code, the layer's code string, which defines LayerMain.
6. The built-in main, which fills the built-in per-fragment values, then composites LayerMain() over the layer below with a straight-alpha source-over and writes that to the fragment output. So a LayerMain that returns a lower alpha lets the layer below show through, and an opaque one replaces it; a layer need not sample uInput itself to stack over the one below, though it may for an effect.

The built-in per-fragment values the main fills, and the layer code may read, all take the top left as their origin, so +x runs right and +y runs down. They are: Resolution, the image size in pixels; Pixel, the fragment in pixels; Uv, the same as 0 to 1, for sampling uInput; and three centred coordinates sharing the image centre as origin, Unit, which runs -1 to 1 across the minor (shorter) axis so it stays square with the longer axis extending past 1, UnitMajor, which runs -1 to 1 across the major (longer) axis so the whole image fits within the unit square, and UnitScaled, which runs -1 to 1 on both axes independently, stretched to the aspect. This assembly is pure text and is performed by Sprites.Media.Shader.Source, so it follows the parameters, the shared code and the layer code reactively; the render driver recompiles when the assembled text changes.

Persistence

The record is structured-clone persisted in IndexedDB, the data store, keyed by id. The meta record, the name, the size and layer-count summary and the thumbnail, lives beside it under the same id in the meta store. Every field here is a plain string, number, boolean, array or object, so the record round-trips through structured clone and through a JSON export unchanged. See Sprites.Media.Shader for the editor and the model that read and write this format.

Full example

A 512×512 shader with one image parameter and two layers. The bottom layer lays down a gradient; the top layer reads the layer below through uInput and tints it, using an image parameter and a helper from the shared globals.

{
  "media": "shader",
  "w": 512,
  "h": 512,
  "globals": "float Circle(vec2 p, float r) { return 1.0 - smoothstep(r - 0.01, r, length(p)); }",
  "params": [
    { "name": "uTint", "type": "colour", "value": { "optionalVec4": { "x": 1, "y": 0.5, "z": 0.2, "w": 1 } } }
  ],
  "layers": [
    {
      "name": "Gradient",
      "visible": true,
      "code": "vec4 LayerMain() { return vec4(0.5 + 0.5 * Unit, 0.5, 1.0); }",
      "params": []
    },
    {
      "name": "Tint",
      "visible": true,
      "code": "vec4 LayerMain() { vec4 below = texture(uInput, Uv); float m = Circle(Unit, 0.6); return mix(below, below * uTint, m); }",
      "params": []
    }
  ]
}