Raster Components

Overview of bitmap-based controls: film strip (sprite sheet) components and image-based components, with guidelines for asset usage.

Raster components use bitmap graphics instead of SVG to render controls. They fall into two categories: film strip controls (sprite sheets) and image controls (single or paired bitmaps). Use them when you need a fixed visual style, assets from VST tools, or bitmap-only designs.

Because their appearance comes from bitmap assets, raster components are not themable like the built-in vector components. They do not respond to theme changes (e.g. primary color, roundness). They do benefit from the rest of AudioUI: the sizing system, interaction system, audio parameter model, layout, and accessibility all apply.

Note:

AudioUI will provide props to supply separate assets for light and dark mode. (Feature coming soon.)

Two Categories

Film Strip Components

Film strip controls display one frame at a time from a sprite sheet: a single image file where multiple frames are stacked vertically or horizontally. Each frame corresponds to a value state (continuous position, discrete option, or boolean on/off).

Image Components

Image controls use one or two bitmap images that are rotated or swapped by value. They do not use sprite sheets.

Film Strips (Sprite Sheets)

A film strip is a bitmap where every frame has the same size and frames are arranged in a single row or column. This format is an industry standard for VST and audio plugin GUIs: many plugins and authoring tools export controls as sprite sheets so the host or UI can show the correct frame for the current parameter value.

The format is widely supported by tools such as WebKnobMan, which lets you design knobs and switches and export them as PNG (or other bitmap) sprite sheets. You can also find ready-made assets in the WebKnobMan gallery, where users share knob and strip designs; from there you can download project files and use the EasyRendering function to export images with the frame size and count you need.

Guidelines for Film Strip Assets

Frame dimensions, frame count, and orientation are fixed by the asset. They are determined when the image is created (e.g. in WebKnobMan or another tool). Do not change them in code to match a different number of options or a different layout; that will break the display.

  • Frame dimensions: frameWidth and frameHeight must match the width and height of one frame in the sprite sheet. If the asset has 120×80 pixel frames, use frameWidth={120} and frameHeight={80}.
  • Frame count: frameCount must equal the total number of frames in the image. For a boolean strip that is 2 frames, use frameCount={2}. For a discrete strip with 8 states, use frameCount={8}. The number of options (or value range) in your component must match this count where applicable (e.g. discrete control options map 1:1 to frames).
  • Orientation: Frames are either stacked vertically (top to bottom) or horizontally (left to right). Set orientation to match how your sprite sheet is laid out. Default is "vertical".
  • One asset, one configuration: When you use a given film strip image, use the same frameWidth, frameHeight, frameCount, and orientation everywhere that image is used. Do not reuse the same image with different frame counts or dimensions for different examples or screens.

The look of each raster control is defined entirely by its bitmap; for theme-driven styling (color, roundness, etc.), use the vector components instead and see Theming Features.

Performance

Raster components follow the same performance priorities as the rest of AudioUI; for the overall approach, see Introduction (Performance First). Bitmap-based rendering also has specific advantages in dense UIs.

  • Bitmap compositing: The browser draws a region of a decoded image (or sprite sheet) instead of recalculating vector paths. Updating the displayed frame or rotation is a cheap operation (e.g. changing which region is visible or applying a transform), so value changes do not trigger full redraws.
  • Image reuse: Controls that use the same imageHref (or the same film strip) share one decoded bitmap. The browser decodes and caches the image once; multiple instances on the page reuse that resource. This helps when you have many knobs or switches from the same asset.
  • Film strips: A single sprite sheet holds all frames. One network request and one decode serve every frame; switching value only changes which part of the image is shown. That keeps memory and draw cost predictable even with many discrete or continuous raster controls.
  • Re-renders: As with other AudioUI components, raster controls re-render only when their props or value change. The interaction system uses refs for high-frequency state during drag or wheel so that the rest of the tree is not updated on every move.

For UIs with many identical-looking controls (e.g. a mixer strip of film strip faders or image knobs), raster components can be a good fit: one asset, one decode, and cheap updates per control.

Completeness and roadmap

Raster components are basically complete: all variants of film strip and image-based controls are covered.

Next Steps