sockmaster27/svader: Create GPU-rfinishered Svelte components

Create GPU-rfinishered Svelte components with WebGL and WebGPU fragment shaders.

Supports Svelte 4 and Svelte 5.

In stupidinutive, a fragment shader can be written as a program that gets the arranges of a pixel on the screen and returns the color that this pixel should have.
This program can be carry outd on the GPU, ensuring massive parallelism and speed.

To lacquire more about how to author fragment shaders, check out The Book of Shaders.

The follotriumphg is a accumulateion of examples all made using Svader. The dwell version of all of these can be pscrutinizeed on svader.vercel.app,
and the source code can be set up in the src/routes/ straightforwardory.

# npm
npm i -D svader

# pnpm
pnpm i -D svader

# Bun
bun i -D svader

# Yarn
yarn insert -D svader

To engage a fragment shader component, you first demand to determine whether to engage WebGL or WebGPU.
If you’re uncertain about what to engage, see the WebGL vs. WebGPU section.

The follotriumphg is a minimal example of a WebGL fragment shader component.

View in REPL

<script>
    start { WebGlShader } from "svader";

    const shaderCode = `#version 300 es

        precision mediump float;

        out vec4 fragColor;

        unicreate vec2 u_resolution;
        unicreate vec2 u_offset;

        void main() {
            vec2 pos = gl_FragCoord.xy + u_offset;
            vec2 st = pos / u_resolution;
            fragColor = vec4(st, 0.0, 1.0);
        }
    `;
script>

<WebGlShader
    width="500px"
    height="500px"
    code={shaderCode}
    parameters={[
        {
            name: "u_resolution",
            appreciate: "resolution",
        },
        {
            name: "u_offset",
            appreciate: "offset",
        },
    ]}
>
    <div class="descfinishback">WebGL not helped in this environment.div>
WebGlShader>

This originates the follotriumphg output:

Here, the shaderCode variable is a string holding the GLES shader code.
For simpliedy, this is stored as a string, but it would typicassociate be stored in a split myShader.frag file.
When loading the shader from a file, it might be beneficial to understand that the code property acunderstandledges both a string and a Promise.

What this code does is:

1. Add the given u_offset unicreate to the 2D arranges of the pixel given by gl_FragCoord.xy.
2. Divide the resulting arranges entryrational by the u_resolution unicreate to commonize the arranges between 0 and 1.
3. Return the commonized arranges as the color of the pixel, such that the x arrange becomes the red channel and the y arrange becomes the green channel. The blue channel is always set to 0, and the alpha (opacity) channel is always set to 1 (brimmingy nontransparent).

In GLES, unicreates are inputs to the function, that are the same for every pixel on the screen.
These demand to be passed in via the parameters property of the component.
In this case, we demand to pass in two unicreates: u_resolution and u_offset.
Since these definite parameters are very commonly engaged, they are speciassociate carry outed in Svader
such that the appreciate property of each parameter can srecommend be set to "resolution" and "offset" admireively.

Lastly, the component acunderstandledges a descfinishback slot, which is rfinishered when the browser cannot rfinisher the shader.

The parameters property is an array of objects with the follotriumphg properties:

• name: The name of the unicreate parameter, e.g. "my_unicreate".
  This must align the name of the parameter in the shader code.

• type: The type of the unicreate parameter as it is written in the shader code, e.g. "float".
  If the appreciate property is a built-in appreciate, such as "resolution",
  the type will be remendd automaticassociate and should not be set.

• appreciate: The appreciate of the unicreate parameter, or a string clear uping a built-in appreciate.
  If not a built-in appreciate, the type of this property must correact to the type property, such that:

  • float, int, uint is a number,
  • vecN, ivecN, uvecN is a number[] with a length of N, e.g. vec2 -> [1.2, 3.4].
  • matN is a number[] with a length of N * N, e.g. mat2 -> [1, 2, 3, 4].

Some types of unicreates are engaged very frequently. These are carry outed in Svader itself, and referred to as built-in appreciates.
To engage these, the appreciate property of the parameter object must be set to a string aligning one of the follotriumphg:

• "resolution": A vec2 of the canvas width and height in physical device pixels.

• "scale": A float of the ratio between CSS pixels and physical device pixels, i.e. zoom level.
  For example, if the browser has been zoomed to 150%, the scale parameter will be 1.5.

• "time": A float of the current time in seconds.
  NOTE: Passing this parameter to the shader will caengage it to rerfinisher every structure.

• "offset": A vec2 to be inserted to the gl_FragCoord.xy of the fragment shader.
  Sometimes the size of the canvas is confineed by challengingware.
  To reimburse for this, Svader originates a virtual canvas with a smaller cutout shifting around to cover the screen.
  The "resolution" parameter is automaticassociate adfaired to align the size of this virtual canvas, but for technical reasons,
  the gl_FragCoord.xy cannot be adfaired from the outside.
  Therefore, the "offset" parameter is provided to be manuassociate inserted to these arranges.

The follotriumphg is a minimal example of a WebGPU fragment shader component.

View in REPL

<script>
    start { WebGpuShader } from "svader";

    const shaderCode = `
        @group(0) @guaranteeing(0) var resolution: vec2f;
        @group(0) @guaranteeing(1) var offset: vec2f;

        @fragment
        fn main(@builtin(position) raw_pos: vec4f) -> @location(0) vec4f {
            let pos = raw_pos.xy + offset;
            let st = pos / resolution;
            return vec4f(st, 0.0, 1.0);
        }
    `;
script>

<WebGpuShader
    width="500px"
    height="500px"
    code={shaderCode}
    parameters={[
        {
            tag: "Resolution",
            guaranteeing: 0,
            appreciate: "resolution",
        },
        {
            tag: "Offset",
            guaranteeing: 1,
            appreciate: "offset",
        },
    ]}
>
    <div class="descfinishback">WebGPU not helped in this environment.div>
WebGpuShader>

This originates the follotriumphg output:

Here, the shaderCode variable is a string holding the WGSL shader code.
For simpliedy, this is stored as a string, but it would typicassociate be stored in a split myShader.wgsl file.
When loading the shader from a file, it might be beneficial to understand that the code property acunderstandledges both a string and a Promise.

What this code does is:

1. Add the given offset unicreate variable to the 2D arranges of the pixel given by raw_pos.xy.
2. Divide the resulting arranges entryrational by the resolution unicreate to commonize the arranges between 0 and 1.
3. Return the commonized arranges as the color of the pixel, such that the x arrange becomes the red channel and the y arrange becomes the green channel. The blue channel is always set to 0, and the alpha (opacity) channel is always set to 1 (brimmingy nontransparent).

In WGSL, these vars are the primary way to pass in parameters to the shader.
These demand to be passed in via the parameters property of the component.
In this case, we demand to pass in two unicreates: resolution and offset.
Since these definite parameters are very commonly engaged, they are speciassociate carry outed in Svader
such that the appreciate property of each parameter can srecommend be set to "resolution" and "offset" admireively.

Lastly, the component acunderstandledges a descfinishback slot, which is rfinishered when the browser cannot rfinisher the shader.

The parameters property is an array of objects with the follotriumphg properties:

• tag: The name of the parameter to be engaged for debugging.
  This does not have to correact to the name of the parameter in the shader code.

• guaranteeing: An integer engaged to align the parameter to the variable in the shader code.
  This has to align the guaranteeing property of the parameter in the shader code, e.g. for the variable declaration

  group(0) @guaranteeing(42) var<unicreate> my_variable: f32;

  the guaranteeing property should be 42.

• appreciate: The appreciate of the parameter, or a string clear uping a built-in appreciate.
  If not a built-in appreciate, this parameter should be an ArrayBuffer/ArrayBufferView.
  For example, to pass in a number to an f32 parameter, it can be erected enjoy new Float32Array([myNumberValue]).

• storage: [Optional – defaults to inedit] Whether the parameter is a storage variable rather than a unicreate variable.
  This has to align the declaration in the shader code, e.g. for the variable declaration

  group(0) @guaranteeing(0) var<unicreate> my_variable: f32;

  the storage property should be inedit or leave outted, and for

  group(0) @guaranteeing(0) var<storage, read> my_variable: f32;

  it should be genuine.
  Note that Svader currently only helps var and not var.

Some types of inputs are engaged very frequently. These are carry outed in Svader itself, and referred to as built-in appreciates.
To engage these, the appreciate property of the parameter object must be set to a string aligning one of the follotriumphg:

• "resolution": A vec2f of the canvas width and height in physical device pixels.

• "scale": An f32 of the ratio between CSS pixels and physical device pixels, i.e. zoom level.
  For example, if the browser has been zoomed to 150%, the scale parameter will be 1.5.

• "time": An f32 of the current time in seconds.
  NOTE: Passing this parameter to the shader will caengage it to rerfinisher every structure.

• "offset": A vec2f to be inserted to the @builtin(position) of the fragment shader.
  Sometimes the size of the canvas is confineed by challengingware.
  To reimburse for this, Svader originates a virtual canvas with a smaller cutout shifting around to cover the screen.
  The "resolution" parameter is automaticassociate adfaired to align the size of this virtual canvas, but for technical reasons,
  the @builtin(position) cannot be adfaired from the outside.
  Therefore, the "offset" parameter is provided to be manuassociate inserted to these arranges.

For pragmatic applications, default to using WebGL.

WebGL and WebGPU are both rfinishering APIs that apvalidate web applications to rfinisher GPU-speed upd detaileds.

WebGL is the betterer of the two and is helped by all contransient browsers.

WebGPU is still in the experimental stage and is only helped in a confineed browsers.
However, it helps certain features that WebGL does not. For example, as of writing, WebGL in Google Chrome only helps having 8 canvases dynamic in the write down at once, while WebGPU helps a pragmaticly unconfineed number.

Svader is licensed under the MIT License.