# Uniforms

Uniforms are optional numeric settings that a host applies to a QIP component before execution. They keep configuration separate from the main content or pixel input: the component receives the same data shape while callers select values such as column count, color, radius, or angle.

They are inspired by uniforms in GPU rendering: small values set by the host and read during execution instead of being embedded in the main input buffer.

Uniforms are a shared extension, not a component type. Content and Tile hosts currently apply them at the points defined below.

## Component Exports

For a query key named `<key>`, export a setter named `uniform_set_<key>`.

Each setter:

- Accepts exactly one parameter.
- Uses one of `i32`, `i64`, `f32`, or `f64`.
- Returns the clamped or applied value using the same type.

An `i32` uniform is treated as unsigned. Use `i64` when callers need to pass a signed integer value.

For example:

```zig
var color_rgba: u32 = 0x000000FF;

export fn uniform_set_color_rgba(value: u32) u32 {
    color_rgba = value;
    return color_rgba;
}
```

Packed values such as colors and flags fit naturally in `i32`. Fractional image parameters like opacity commonly use `f32`.

## Host Behavior

The host applies setters after instantiation and before `render`, or before tile execution in image mode. A host reusing an instance may call setters again before a later execution.

- A query key without a matching `uniform_set_<key>` export is an error.
- A value that cannot be parsed as the setter's parameter type is an error.
- Hexadecimal integers require a `0x` or `0X` prefix and are parsed as unsigned bit patterns.
- Keys are applied in sorted key order.
- Setters must not depend on their call order for related state changes.

Returning the applied value lets a host observe clamping or normalization. A setter for a range-limited value should store and return the value the component will actually use.

## CLI Syntax

Put the quoted query argument immediately after its component path:

```bash
qip run module.wasm '?key=value'
qip run module.wasm '?width=900&height=400&font_size=48'
qip image -i in.jpg -o out.png filter.wasm '?radius=2.0&angle=0.26'
```

Quote the entire query in a shell so `&` is not interpreted as a command separator.

Examples from this repository:

```bash
# i32 uniform
qip run components/utf8/text-to-bmp.wasm '?cols=120'

# f32 uniforms
qip image -i in.jpg -o out.png \
  components/rgba/color-halftone.wasm '?max_radius=2.0&angle_c=0.26'

# 0xRRGGBBAA passed as the raw bits of an i32
qip run components/image/svg+xml/svg-recolor-current-color.wasm \
  '?color_rgba=0xff5511ff'
```

## Host-Managed Tile Size

Image components may export `uniform_set_width_and_height(width: f32, height: f32)`. This two-parameter function is a host-managed Tile hook, not a query uniform, despite sharing the `uniform_set_` prefix.

The image host calls it with the full input dimensions. Callers cannot set it through query arguments.