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:

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:

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:

# 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.