@frapx/glsl-flowmap

glsl-* — GLSL snippet Not a runtime — plain GLSL strings you concatenate into your own fragment. Requires WebGL2 (#version 300 es).

Decodes frapx-convention RG-encoded flowmap textures and applies a three-phase advection distortion to a base texture.

pnpm add @frapx/fx-canvas @frapx/glsl-flowmap

import { createShaderBackground, glsl } from "@frapx/fx-canvas";
import { flowDecode, flowDistort } from "@frapx/glsl-flowmap";

createShaderBackground({
  target: "#canvas-container",
  textures: {
    // flipY: true is the default — matches the frapx flowmap encoding convention
    flow: "flowmap.png",
    base: "water.jpg"
  },
  uniforms: { flowSpeed: 0.3, flowStrength: 0.15, tiling: 2.0 },
  fragment: glsl`#version 300 es
    precision highp float;

    in vec2 v_uv;
    out vec4 fragColor;

    uniform sampler2D u_flow;
    uniform sampler2D u_base;
    uniform float u_time;
    uniform float u_flowSpeed;
    uniform float u_flowStrength;
    uniform float u_tiling;

    ${flowDecode}
    ${flowDistort}

    void main() {
      vec2 flow = frapx_flowDecode(u_flow, v_uv);
      vec2 baseUv = v_uv * u_tiling;
      fragColor = frapx_flowDistort(
        u_base, flow, baseUv, v_uv,
        u_time, u_flowSpeed, u_flowStrength
      );
    }
  `
});

Encoding convention

Flowmap textures must follow the frapx RG convention:

Channel	Value
R byte	round(127.5 + dx * 127.5)
G byte	round(127.5 - dy * 127.5) (canvas Y negated to match WebGL Y-up)
Neutral (no flow)	rgb(128, 128, 0)

Textures painted with the frapx-flowmap-painter demo already follow this convention. If you upload a flow texture yourself, @frapx/fx-canvas uploads with flipY: true by default, matching the table above — set UNPACK_FLIP_Y_WEBGL accordingly if you upload manually.

API

flowDecode — vec2 frapx_flowDecode(sampler2D flowTex, vec2 uv) → signed velocity in [-1, 1]².

flowDistort — three-phase advection, self-contained (no other frapx_ snippet required):

vec4 frapx_flowDistort(
  sampler2D base,
  vec2 flow,      // from frapx_flowDecode
  vec2 baseUv,    // base texture coords (apply tiling before calling)
  vec2 phaseUv,   // untiled coords used for phase decorrelation
  float time,     // e.g. u_time
  float speed,
  float strength
) → vec4

A six-argument signature (frapx_flowDistort(base, flow, baseUv, time, speed, strength)) remains available for compatibility, using baseUv as the phase coordinate.

Full quality notes and version history: CHANGELOG on GitHub.