Skip to content
php-baremetal REGISTRY
Publish a package

php-baremetal/ext-slate

bm-ext MIT

Slate for php-baremetal: a retained-mode 2D scene graph and compositor for display panels, with a software graphics layer. Platform-neutral.

ext-slate · PHP API

Elements

RoundRect, Circle, Arc, Line, Text, Group, Canvas and Image: constructors, properties, colors, and a component of your own built from them.

Every element extends the abstract Baremetal\Slate\Element. Its properties are public and typed: read them, write them, use += and ++ on them; each write becomes a change of the scene, shown at the next frame after it is handed over (see Scenes and pages).

Common properties

Property Type Meaning
$x, $y int|float Position relative to the parent group (the scene for a top element), -32767 to 32767. Fractions are drawn anti-aliased.
$visible bool false hides the element (a group with its children). Default true.
$opacity float 0 (transparent) to 1 (opaque). A group's opacity applies to the group as a whole. Default 1.
$touchable bool The element takes touches (onPress()..onCancel(), the callbacks of on()): see Touch. Default false (Scroll: true).
$hitPad int Pixels added to the touch area on every side, 0 to 64. Default 0.
$holdMs int Milliseconds before Hold, 0 to 10000 (0: none). Default 500.
Element::set(mixed ...$props): static

Returns static.

Several properties at once, by name: $el->set(x: 40, opacity: 0.5). Positional arguments throw \ArgumentCountError, an unknown name \Error. Returns the element. The properties are assigned in the order given, each validated on its own (so set(w: 40, h: 30, clip: true) works and set(clip: true, w: 40, h: 30) on a group without a box throws at clip; the ones before stay assigned), with PHP's usual conversions of typed properties (a script's strict_types does not apply inside set()).

Element::animate(array $props, int $ms = 300, Ease $ease = Ease::OutCubic, int $delay = 0, int $repeat = 0, bool $yoyo = false): Tween

Returns Tween.

Moves properties to new values over time, in the compositor: $el->animate(['x' => 200, 'opacity' => 0.5]). The properties read their final values at once; the returned Tween tells when it ends. See Animations, which also lists the animatable properties of each element.

Element::ease(array $props, int $ms = 300, Ease $ease = Ease::OutCubic): static

Returns static.

From now on, writes of the named properties slide to their values instead of jumping: $el->ease(['x', 'y']); ease([]) makes them jump again. See Animations.

Element::on(TouchType $type, \Closure $fn): static

Returns static.

The callback of one kind of touch (TouchType::Tap, ...); the element then takes touches. off(TouchType $type) removes it. The methods onPress(Touch $t), onMove(), onRelease(), onTap(), onHold() and onCancel() are empty, for a component of your own to override. See Touch.

Positions and coordinates

Pixel (i, j) is the square from (i, j) to (i + 1, j + 1): a RoundRect at integer coordinates has crisp edges. A Line's end points are pixel centres: a line from (0, 10) to (100, 10) of width 1 fills row 10 exactly. Angles are in degrees, 0 at 3 o'clock, growing clockwise (90 is 6 o'clock).

Colors

0xRRGGBB is opaque; 0xAARRGGBB with an alpha byte AA from 01 to FF is translucent (0x80000000 is half-transparent black). A value up to 0xFFFFFF has no alpha byte and is opaque, so 0x00RRGGBB cannot mean transparent: a fully transparent fill or border is null, and a transparent gradient stop is written [position, color, 0.0] (see Effects and build options). To hide an element, set $visible to false or $opacity to 0. On the board PHP integers have 32 bits and a literal above 0x7FFFFFFF is a float: the color properties are typed int|float and accept it.

$fill of RoundRect and Circle, and $color of Arc, also take a LinearGradient or a RadialGradient (see Effects and build options).

RoundRect

RoundRect::__construct(int|float $x, int|float $y, int|float $w, int|float $h, int|float $radius = 0, int|float|Gradient|null $fill = null, int|float $border = 0, int|float|null $borderColor = null, ?Shadow $shadow = null)

A rectangle with rounded corners; $radius 0 is a plain rectangle (clamped to half the shorter side). $border is a band of that width inside the outline, in $borderColor; the fill covers what is left. Properties: $w, $h, $radius, $fill, $border, $borderColor, $shadow.

Circle

Circle::__construct(int|float $cx, int|float $cy, int|float $r, int|float|Gradient|null $fill = null, int|float $border = 0, int|float|null $borderColor = null, ?Shadow $shadow = null)

A disc of centre ($cx, $cy), which are its $x and $y. Properties: $r, $fill, $border, $borderColor, $shadow.

Arc

Arc::__construct(int|float $cx, int|float $cy, int|float $r, int|float $from, int|float $to, int|float $width, int|float|Gradient $color, Caps $caps = Caps::Round)

A stroke of $width along the circle of radius $r around ($x, $y), from $from clockwise to $to degrees: the bar of a gauge or a progress ring. $to smaller than $from wraps round; a difference of 360 or more is the full ring; $from == $to draws nothing. $caps: Caps::Butt ends on the radius, Caps::Round adds half a disc. Properties: $r, $from, $to, $width, $color, $caps.

Line

Line::__construct(int|float $x0, int|float $y0, int|float $x1, int|float $y1, int|float $width = 1, int|float $color = 0xFFFFFF, Caps $caps = Caps::Butt)

A segment from ($x0, $y0), which is its $x and $y, to ($x1, $y1). The color is a plain color (no gradient). Properties: $x1, $y1, $width, $color, $caps.

Text

Text::__construct(int|float $x, int|float $y, string $text, string $font = 'default', int|float $color = 0xFFFFFF, Align $align = Align::Left, int $maxWidth = 0)

One line of UTF-8 text in a font of the firmware (the fonts that ext-display builds in: default when extra.baremetal.fonts.default is true, plus the project's fonts, see ext-display). $y is the top of the line; $align says what $x is: the left end, the centre or the right end. $maxWidth cuts the text to that many pixels (no wrap, no ellipsis); 0 is no limit. Extended fonts of 2 and 4 bits per pixel are drawn anti-aliased. An unknown font throws \ValueError listing the fonts of the firmware. Properties: $text, $font, $color, $align, $maxWidth.

Group

Group::__construct(int|float $x = 0, int|float $y = 0, int|float $w = 0, int|float $h = 0, float $opacity = 1.0, bool $clip = false, bool $cache = false, int $blur = 0, ?Shadow $shadow = null)

Its children are placed relative to ($x, $y). add(Element ...$e): static puts children on top, remove(Element ...$e): static takes them out.

Property Meaning
$w, $h The box (0, 0, w, h) in the group's own coordinates, used by $clip.
$clip Cut the children to the box. Needs $w and $h greater than 0, else \ValueError.
$cache Keep the group as an image and redraw it only when something inside changes (see Performance).
$blur Blur of the whole group in pixels, 0 to 765 (see Effects and build options).
$shadow A drop shadow of the group's content, or null.

An element is in one group at a time; a group cannot contain itself or one of its parents (\LogicException).

A Scroll is a group with a view over its children that the finger drags, with inertia, snapping and bars: see Scroll.

A component of your own

The compositor never calls PHP while it draws, so a component is a Group that composes the built-in elements and exposes methods that change them (a class that extends Element directly is refused with \LogicException):

php Gauge
<?php
use Baremetal\Slate\{Group, Arc, Text, Align};

final class Gauge extends Group
{
    private Arc $bar;
    private Text $label;

    public function __construct(int $x, int $y)
    {
        parent::__construct($x, $y);
        $this->add(
            new Arc(0, 0, 60, -90, 270, 8, 0x303840),
            $this->bar = new Arc(0, 0, 60, -90, -90, 8, 0xE0A040),
            $this->label = new Text(0, -8, '0', align: Align::Center),
        );
    }

    public function setValue(float $v): void       // 0..1
    {
        $this->bar->to = -90 + 360 * $v;
        $this->label->text = (string) round($v * 100);
    }
}

Canvas

Canvas::__construct(int|float $x, int|float $y, int $w, int $h)

Pixels of your own, $w x $h (1 to 1024 each), opaque, drawn immediately into a buffer on the PHP side with the primitives of ext-display. Nothing reaches the screen until dirty(), which sends the rectangle that changed since the previous call. Colors are 0xRRGGBB. Setting $w or $h resizes and clears it.

Method Draws
clear(int $color = 0): void The whole canvas.
pixel(int $x, int $y, int $color): void One pixel.
line(int $x0, int $y0, int $x1, int $y1, int $color): void A one-pixel line, both ends included.
rect(int $x, int $y, int $w, int $h, int $color): void An outline.
fillRect(int $x, int $y, int $w, int $h, int $color): void A filled rectangle.
circle(int $cx, int $cy, int $r, int $color): void An outline.
fillCircle(int $cx, int $cy, int $r, int $color): void A filled disc.
text(int $x, int $y, string $s, int $color, ?int $bg = null, string $font = 'default'): int One line, $y the top of the line; $bg null keeps what is under it. Returns the width.
dirty(): void Sends the changed rectangle to the compositor.
php A plot
$plot = new Canvas(40, 200, 280, 100);
$scene->add($plot);
$plot->clear(0x101418);
foreach ($samples as $i => $v) {
    $plot->pixel($i, 99 - (int) ($v * 99), 0x40E0A0);
}
$plot->dirty();

Image

Image::__construct(int|float $x, int|float $y, string $src, float $opacity = 1.0)

A picture from a file of the board, $src an absolute path to a .sli file (the project's PNG assets, converted by phpbm) or a .png decoded on the board: new Image(0, 0, '/app/assets/ui/bg.sli'). It is loaded in the background and drawn once it is there, at ($x, $y) rounded to whole pixels, times $opacity. Properties: $src, and read-only $w, $h, $loaded; wait(int $timeout_ms = 5000): bool waits for it. Loading, events, preloading and errors are in Images.

Enums

Enum Cases
Caps: string Butt ('butt'), Round ('round')
Align: string Left ('left'), Center ('center'), Right ('right')
ImageError: string NotFound ('not-found'), Unreadable ('unreadable'), BadFormat ('bad-format'), Unsupported ('unsupported'), NoMemory ('no-memory'), see Images
Ease Linear, InQuad, OutQuad, InOutQuad, InCubic, OutCubic, InOutCubic, OutBack, OutBounce, OutElastic (no values), see Animations

Caps::from('round') and Align::tryFrom($name) read them from strings; Ease is a pure enum (Ease::OutBack).

Errors

Thrown When
\ValueError A property that cannot be animated, in animate(), then() and ease() (see Animations).
\ValueError A value out of range: Baremetal\Slate\RoundRect::$opacity must be between 0 and 1, ...::$hitPad must be between 0 and 64, ...::$holdMs must be between 0 and 10000, ...::$w must be between 0 and 32767, ...::$x must be a finite number between -32767 and 32767, ...::$fill must be a color, 0xRRGGBB or 0xAARRGGBB, or a gradient, ...::$clip needs $w and $h greater than 0 (the clip box), an unknown font, an image path (Baremetal\Slate\Image::$src must be an absolute path, ...::$src must end in .sli or .png). The old value stays.
\TypeError A value of the wrong type (PHP's own message for typed properties).
\LogicException A second parent, or a group that would contain itself.
\RuntimeException The compositor failed (Slate: the panel did not finish a band within 2000 ms, Slate: the panel refused the bands (error 0x..)) or is out of memory for the changes.
\Error A write of a read-only property (Image::$w, $h, $loaded), unset() of a property, a reference to one (Cannot take a reference to ...), foreach by reference over an element (Cannot iterate ... by reference), clone of an element, set() with an unknown name.

Write properties directly or with set(). array_walk(), ArrayObject and ArrayIterator over an element write its properties without these checks: the compositor then refuses the change when the element is shown (with slate-debug, it counts as a command error) and the element keeps drawing as before.

Related