UI/Renderable: Box

What this page covers #

box is the foundational rectangle renderable, used for fills, cards, rings, and textured quads with optional shader overrides.

By task #

Create a simple filled/rounded rectangle: see Definition
Tune defaults and geometry behaviour: see Defaults
Build borders/rings: see Border/ring using inset
Configure slot alignment around boxes: see Top-level element options

Rounded rectangle with optional texture and shader override.

Import #

Definition #

Renderable options object passed to UI.createElement(..., { renderable: { ... } }):

BoxRenderable

Rounded rectangle with optional texture and shader.

type 'box' - Renderable type identifier.
aabb { min: { x, y }, max: { x, y } } optional - Bounding box. Default { min:{x:0,y:0}, max:{x:64,y:64} }.
cornerRadius number | { t?, r?, b?, l? } | [tl, tr, br, bl] optional - Corner radius. Default 0.
cornerResolution number | { t?, r?, b?, l? } | [tl, tr, br, bl] optional - Segments per corner arc. Default 3.
inset number optional - Uniform inner offset; renders a ring when > 0. Default 0.
colour [r, g, b, a] optional - Tint colour. Default [1,1,1,1].
texture string optional - Path to image asset.
shader { vert: string, frag: string } optional - Optional SPIR-V shader override.

Defaults #

aabb: { min:{x:0,y:0}, max:{x:64,y:64} }
cornerRadius: 0
cornerResolution: 3
colour: [1,1,1,1]
inset: 0

Notes #

If texture is provided, the engine attempts to load it from the window's texture pool. Paths like /rom/button_dark.png refer to bundled assets.
If shader is provided, both vert and frag must be valid SPIR-V files (.spv) available to the renderer. Missing files cause a RangeError.
Element transform pivot is renderable.origin at creation (runtime: UI.setOrigin).
You can update resources at runtime via UI.setTexture, UI.clearTexture, UI.setShader, UI.clearShader.

Top-level element options #

Pass these alongside renderable in UI.createElement (see also UI/Renderable: Shared properties):

Example #

Creates a textured rounded box with asymmetric corner radii and applies a custom shader after attaching it to the window. Demonstrates the typical create-attach-customise workflow for styled card or button backgrounds.

import * as UI from 'Helix/UserInterface';

const id = await UI.createElement(win, {
  renderable: {
    type: 'box',
    aabb: { min: { x:0, y:0 }, max: { x:96, y:32 } },
    cornerRadius: { tl: 12, tr: 12, br: 2, bl: 2 },
    cornerResolution: { tl: 12, tr: 12, br: 6, bl: 6 },
    colour: [0.15, 0.7, 0.4, 1],
    texture: '/rom/button_dark.png',
    position: { x: 10, y: 10 }
  }
});
await UI.attachRoot(win, id);

await UI.setShader(win, id, {
  vert: '/rom/shaders/texture_only.vert.spv',
  frag: '/rom/shaders/texture_only.frag.spv'
});

Border/ring using inset #

UI.createElement(win, {
  renderable: {
    type: 'box',
    aabb: { min: { x:0, y:0 }, max: { x:120, y:40 } },
    colour: [0.9, 0.9, 0.9, 1],
    inset: 2,
    cornerRadius: { t: 6, r: 6, b: 6, l: 6 }
  }
});

<- UI/Renderable: Shared properties UI/Renderable: Mesh ->