# hyprtile-wallpaperd Shader API

`hyprtile-wallpaperd` exposes a small runtime shader API for standalone procedural wallpapers, image/video post-processing and multi-pass shader packs.

## Built-in uniforms

A fragment shader may declare any of these; unused uniforms cost nothing.

```glsl
uniform float u_time;               // seconds since wallpaperd start
uniform float u_delta_time;         // seconds since previous rendered frame, clamped to 0..0.25
uniform float u_frame;              // rendered frame counter
uniform vec2  u_resolution;         // current pass output size
uniform sampler2D u_tex;            // current pass input texture
uniform int   u_has_tex;
uniform vec2  u_tex_resolution;     // current input texture size
uniform vec4  u_draw_rect;          // media placement rectangle
uniform int   u_pass_index;
uniform int   u_pass_count;

uniform sampler2D u_noise_tex;      // built-in 256x256 filtered repeating RGBA noise
uniform vec2  u_noise_resolution;

uniform vec4  u_mouse;              // x,y in monitor pixels (bottom-left origin), z=left button, w=valid
uniform int   u_monitor_index;      // wallpaperd output/surface index
uniform vec2  u_monitor_resolution; // physical size of the monitor surface used by this pass
uniform float u_random_seed;        // stable 0..1 random seed for this wallpaperd process
```

`u_mouse.w` is `1` while Wayland routes pointer focus to the background layer. It is `0` otherwise and x/y are `-1`. The wallpaper remains a normal background-layer surface; mouse input is not polled through external processes.

## Temporal history

With `--history N` (up to 8 frames), shaders can use:

```glsl
uniform sampler2D u_prev_frame;
uniform sampler2D u_prev_frame_1;
uniform sampler2D u_prev_frame_2;
uniform sampler2D u_prev_frame_3;
uniform int u_has_prev_frame;
uniform int u_history_count;
uniform vec2 u_history_resolution;
```

## Custom params

A pass can load a `.params` file. Names map directly to GLSL uniforms and accept one to four floats:

```ini
strength=0.75
tint=1.0,0.5,0.2
```

becomes `u_strength` and `u_tint` unless the file already uses the `u_` prefix.

## FBO / UV orientation

`hyprtile-wallpaperd` keeps one stable logical UV orientation through the entire offscreen pipeline. `v_uv.y = 0` is the logical top and `v_uv.y = 1` the logical bottom for media input as well as for every subsequent FBO pass. Shader packs must not add a special `1.0 - uv.y` correction merely because they are later in a chain. The engine performs the single GL/display orientation conversion only at final presentation.

This means the same shader can safely be chained once, twice or many times without alternating vertical flips.

## Multi-pass pipeline

Up to 16 passes are supported. Each pass receives the previous pass as `u_tex`. Per-pass scale and opacity are supported.

## Shader-pack manifests

A `.wallpaper` file describes a complete pipeline:

```ini
name=Alpine Cinematic / balanced
fps=30
history=0
pass=scene.frag|scene.params|1.0|1.0
pass=motionblur.frag|motionblur.params|1.0|1.0
```

`pass=` fields are:

```text
fragment|params|opacity|scale
```

Fragment and params paths are relative to the manifest file. `params` may be `-` when omitted.

Optional global manifest keys:

```ini
fps=30
history=4
mix=0.65
brightness=0.90
vertex=custom.vert
```

`mix` is a global final-chain blend against the untouched input image/video:

- `mix=0.0` = original media only
- `mix=0.5` = 50% original + 50% completed shader chain
- `mix=1.0` = full shader result

For procedural shader-only wallpapers without an image/video source, `mix` is treated as `1.0`.

`brightness` is applied after the complete chain and after `mix`:

- `brightness=1.0` = unchanged
- `brightness=0.8` = 20% darker
- `brightness=1.2` = 20% brighter

The command-line equivalents are `--mix` and `--brightness`.

A manifest can be started directly:

```bash
hyprtile-wallpaperd --pack /path/to/look.wallpaper
```

Installed packs can be addressed by symbolic name and preset:

```bash
hyprtile-wallpaperd --pack alpine-cinematic:balanced
hyprtile-wallpaperd --pack mountain-flight:hq-fast
hyprtile-wallpaperd --image ~/Pictures/wallpaper.jpg --pack raindrops:default
hyprtile-wallpaperd --image video.mp4 --pack ascii:green
hyprtile-wallpaperd --image wallpaper.png --pack gaussian-blur
```

Pack lookup searches the user's `~/.hyprtile/shader/wallpaperd`, the system install under `/usr/local/share/hyprtile/shader/wallpaperd`, and `./shader/wallpaperd` when running from the source tree.

Command-line options placed after `--pack` can still override settings such as `--fps`, `--history`, `--mix` or `--brightness`.

Examples:

```bash
hyprtile-wallpaperd --image wallpaper.jpg --pack ascii:amber --mix 0.35
hyprtile-wallpaperd --image wallpaper.jpg --pack ascii:amber --mix 0.60 --brightness 0.82
hyprtile-wallpaperd --pack alpine-cinematic:balanced --brightness 0.75
```

Final processing order:

```text
input media -> shader pass 1 -> ... -> shader pass N
       \________________________________________/
                         mix
                          |
                     brightness
                          |
                        output
```
