v0.7.1 (build 925)
Koya home

UI/Renderable: Circle

Circle/arc renderable with optional ring thickness and angle range.

What this page covers #

circle draws filled circles, ellipses, arcs, and ring-style shapes with optional texture/shader overrides.

By task #

Ellipse or arc segment fitted to an AABB, with optional inner inset (ring thickness), colour tint, and optional texture/shader override.

Import #

import * as UI from 'Helix/UserInterface';

Definition #

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

CircleRenderable
Circle/arc renderable with optional ring thickness and angle range.
  • type 'circle' - Renderable type identifier.
  • aabb { min: { x, y }, max: { x, y } } optional - Outer bounds. Square gives a circle; non-square gives an ellipse. Default { min:{x:0,y:0}, max:{x:0,y:0} }.
  • inset number optional - Ring thickness. 0 = filled, > 0 = ring. Default 0.
  • start number optional - Start angle in degrees. Default 0.
  • end number optional - End angle in degrees. Default 360.
  • resolution number optional - Sides used to approximate the circle. Default 32.
  • 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:0,y:0} }
  • inset: 0
  • start: 0
  • end: 360
  • resolution: 32
  • colour: [1,1,1,1]

Notes #

  • Fast updates: changing only start/end rebuilds indices without touching vertices for best performance.
  • Geometry: aabb defines the outer bounds. A square aabb gives a circle; a non-square aabb gives an ellipse.
  • Inset: when inset > 0, renders a ring inset from the outer ellipse. When inset == 0, renders a filled circle/ellipse/arc.
  • Pivot: 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.
  • All circle-specific properties can be updated at runtime via the setters listed below.

Runtime setters #

After creation, individual circle properties can be changed without rebuilding the entire renderable. These are available on both the raw Helix/UserInterface module and the Element standard-library wrapper.

setCircleColour
Sets the tint colour. Accepts [r, g, b, a] or { r, g, b, a }.
UI.setCircleColour(windowId, elementId, colour) / element.setCircleColour(colour)
setCircleInset
Sets the ring thickness. 0 = filled, > 0 = ring.
UI.setCircleInset(windowId, elementId, inset) / element.setCircleInset(inset)
setCircleStart
Sets the start angle in degrees.
UI.setCircleStart(windowId, elementId, degrees) / element.setCircleStart(degrees)
setCircleEnd
Sets the end angle in degrees.
UI.setCircleEnd(windowId, elementId, degrees) / element.setCircleEnd(degrees)
setCircleResolution
Sets the number of sides used to approximate the circle.
UI.setCircleResolution(windowId, elementId, resolution) / element.setCircleResolution(resolution)
setCircleRect
Sets the outer bounds AABB. Expects { min: { x, y }, max: { x, y } }.
UI.setCircleRect(windowId, elementId, aabb) / element.setCircleRect(aabb)

Top-level element options #

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

UI.createElement(win, {
  renderable: { type: 'circle', /* ... */ },
  contentAlign?: { x?: 'start'|'center'|'end', y?: 'start'|'center'|'end' }
})

Example: arc gauge #

Builds a 270-degree arc ring and spins it continuously with a rotation animation. This pattern is the basis for progress gauges, radial meters, and loading indicators.

import * as UI from 'Helix/UserInterface';

const id = await UI.createElement(win, {
  renderable: {
    type: 'circle',
    aabb: { min: { x: 52, y: 52 }, max: { x: 148, y: 148 } },
    inset: 6,
    start: 135,
    end: 405,
    resolution: 64,
    colour: [0.2, 0.8, 0.6, 1]
  }
});
await UI.attachRoot(win, id);

const spin = await UI.addAnimation(win, id, [
  { time: 0.0, rotation: 0 },
  { time: 1.5, rotation: 360, looping: true }
]);
await UI.startAnimation(win, id, spin);
<- UI/Renderable: MeshUI/Renderable: Panel ->