Changelog
1.3.0
- Added: themes.
final class Themeholds the look of the controls: 14 colours ($bg,$surface,$raised,$well,$border,$borderStrong,$text,$textMuted,$textDim,$accent,$onAccent,$danger,$info,$success,0xRRGGBB),$radius(0..64, the radius ofShape::Rounded),$small,$medium,$large(24..128, the heights of the sizes) and five fonts of the firmware ($font,$fontSmall,$fontTitle,$fontMono,$fontDisplay), allpublic readonly, set by name in the constructor (the defaults are a neutral dark theme).Slate::theme(Theme $theme): staticsets it before the firstshow()(after it:\Errorthe theme is set before the first show());Slate::$theme(public readonly Theme) reads it,new Theme()untiltheme(). A control reads the theme when it is made. The enums of the controls:Size(Small,Medium,Large),Variant(Primary,Secondary,Ghost,Danger,Outline),Shape(Pill,Rounded) andChoiceStyle(Segmented,Chips,List,Nav).\ValueErrorBaremetal\Slate\Theme::$<token> must be a color, 0xRRGGBB,...::$radius must be between 0 and 64,...::$<small|medium|large> must be between 24 and 128,...::$<font> must be a font of the firmware: unknown font '<name>' (available: ...). - Added: controls.
abstract class Control extends Group: one PHP object whose parts live in the compositor without a PHP object each;public bool $touchable = true,public bool $enabled = true(false: drawn at 0.4 times$opacity, no new touch, a touch under way getsCancel),protected readonly Theme $theme(the running Slate's theme when it is made),onChange(mixed $value): void(empty) andchanged(?\Closure $fn): static(notified for the user's gestures only: method first, then the callback),protected notify(mixed $value): void,protected pressed(bool $down): void(trueatPress,falseatReleaseandCancel),add()/remove()for the controls of your own (a class that extendsControldirectly). A control needs a running Slate when it is made (\Error<Class> needs a running Slate: create the Slate before its controls);add()/remove()on Slate's controls throw\Error<Class>: a control builds its own parts; their$wand$hread the size laid out and cannot be written (\ErrorCannot modify <Class>::$w: the size of a control comes from its constructor and the theme).class Button extends Control:new Button(int|float $x, int|float $y, string $text, Variant $variant = Variant::Secondary, Size $size = Size::Medium, int $w = 0, Shape $shape = Shape::Rounded, ?string $icon = null),public string $text,public Variant $variant,public ?int $fill = null,public ?int $color = null; the height from the theme, the width given or the text plus paddings (16, 20, 24 px) and the icon (20 + 8 px), a square with an icon and no text; the pressed look (the fill 12 % toward white in 80 ms;GhostandOutline: the text colour at 6 %); a monochrome icon (an image file asImage::$src, drawn in the text colour; one that does not load stays empty, withImageFailed).\ValueErrorBaremetal\Slate\Button::$w must be between 0 and 32767,...::$icon must be an absolute path ending in .sli or .png,...::$fill must be a color, 0xRRGGBB(and$color). - Added:
Toggle(an on/off switch) andSlider(extends Control, not final).new Toggle(int|float $x, int|float $y, bool $on = false, Size $size = Size::Medium): a track (52 × 30, 62 × 36, 72 × 42) and a knob (24, 28, 34, 4 px from the ends); on:accenttrack andbgknob, off:borderStrongandtextMuted; a tap invertspublic bool $on(knob and colours slide in 250 ms) and notifiesonChange(bool); a write of$onfrom the code slides without a notification;public int $hitPad = 8.new Slider(int|float $x, int|float $y, int $w, int|float $min = 0, int|float $max = 100, int|float $value = 0, int|float $step = 1, Size $size = Size::Medium): an area as high as the size, a track 8 px high (well) filled to the value (accentorpublic ?int $fill), a knob of 24, 30, 34 px; the press moves the knob under the finger, on the step, and it follows the finger;onChange()only once the finger is past 8 px (or at the release), at most once per frame of the compositor;onCommit(int|float $value): voidandcommitted(?\Closure $fn): staticat the release, always; in a verticalScrolla vertical drag goes to theScroll(the slider getsCanceland goes back to its value of before the press, no notification). AnotherCancel($enabledfalse, another scene) does the same before anyonChange(); after one, the value stays andonCommit()runs.public int|float $value,$min,$max,$step: a write brings$valueinto the range and onto the step (rounded to the decimals of$stepand$min) without a notification;$valueis anintwhen$min,$maxand$stepare allint.\ValueErrorBaremetal\Slate\Slider::$w must be between 0 and 32767,...::$min must be less than $max,...::$step must be greater than 0,...::$<value|min|max|step> must be a finite number,...::$fill must be a color, 0xRRGGBB. - Added:
Choice(extends Control, not final).new Choice(int|float $x, int|float $y, array $labels, int|array $selected = 0, ChoiceStyle $style = ChoiceStyle::Segmented, int $w = 0, Size $size = Size::Medium, bool $multi = false, array $icons = []): one item (or several,multi: true) picked among the labels, in four styles:Segmented(equal segments in awellcontainer; selectedaccent+onAccent),Chips(pills 8 px apart that wrap withinw > 0; selectedaccent, the othersraisedwith aborder),List(rowswwide; selectedaccentat 12 % with a border at 35 % andaccenttext) andNav(equal parts ofw, an icon above afontSmalllabel; selectedaccentwith a 3 px bar that slides to it, the otherstextDim).$icons: one path per label, monochrome icons drawn in the item's text colour (required forNav). The colours slide in 200 ms; the item under the finger has the pressed look (80 ms; a fill that is not opaque getstextat 6 % laid over it). A tap selects an item and notifiesonChange(int)(a tap on the selected one does nothing); withmulti(pass[]to start with none) each tap turns an item on or off andonChange()gets the sorted list.public int|array $selected: a write from the code slides without a notification.\ValueErrorBaremetal\Slate\Choice::$labels must be a non-empty list of strings,...::$selected must be between 0 and <n-1>(multi:...::$selected must be a list of indexes between 0 and <n-1>),...::$icons must be empty or hold one path per label,...::$w must be between 0 and 32767,...: the List and Nav styles need w greater than 0,...: the Nav style needs an icon per label,...::$icons must hold absolute paths ending in .sli or .png. - Added:
SettingRow,Dialog,Scene::open(),Slate::toast().new SettingRow(int|float $x, int|float $y, int $w, string $label, string $sub = '', ?Element $control = null, string $value = ''): a row of a settings list, 60 high (72 with$sub, at least the control + 16), the label (font) and the subtitle (fontSmall,textMuted) on the left,$value(fontMono,textMuted) right-aligned, the control (a child of the row, with its own touches) at the right, left of the value, and a divider inborder; aSlidermade withw: 0is stretched between the label (at most 40 % of$w) and the value.public string $label,$sub,$value(a write lays the row out again);public bool $touchable = false(touchable: the pressed look,textat 4 %, andonTap()).new Dialog(string $title = '', string $text = '', int $w = 460, bool $stack = false): a scrim (black at 88 %) that takes every touch, and a panelmin($w, screen width - 32)wide (radius 26,surface,borderStrong, a shadow when shadows are built, padding 26) with the title (fontTitle), the text (font,textMuted; lines at"\n"only), the content ofadd()and the buttons ofbuttons(Button ...$b): static(one row of equal widths, or a column with$stack; the dialog sets their width and place), cut to the screen height - 32.Scene::open(Dialog $d): staticopens it above the scene (its shadow built first, then the scrim fades in and the panel, opaque, rises 14 px, 300 ms);close(): voidplays it backwards, then the dialog leaves the scene, thenonClose(): voidand the callback ofclosed(?\Closure $fn): static;public bool $dismissable = false(a tap on the scrim closes it). While a dialog is open only the top one and what is in it take a new touch, fromopen()on (also in the first frames, while the scrim is still clear); while it closes nothing in it takes a touch (a finger held on it getsCancel), the scrim still does;$enabled = falseon a dialog leaves its scrim without touches but still blocks what is under it; a dialog with$visible = falseblocks nothing, and its close (or a close under way when it is hidden) ends at once. A dialog stays with its scene acrossshow(); closed while its scene is not shown, or taken out withScene::remove(), it goes at once and still callsonClose(), as does one still closing when its scene is left;Scene::open()ends the touch under way (Cancel);add()of aDialogthrows\Error<Class> is opened with Scene::open(), not added;Scene::add()keeps the open dialogs on top.Slate::toast(string $text, int $ms = 2500): static: a pill (48 high,surface, anaccentdot, the text) above everything, also a transition, in a top layer of the compositor; it rises and fades in (300 ms), stays$ms, fades out (300 ms); a new toast replaces the one shown; it takes no touch; it is at most the screen's width - 64 (a longer text is cut).\ValueErrorBaremetal\Slate\SettingRow::$w must be between 1 and 32767(andDialog::$w),Baremetal\Slate\Dialog::$text must hold at most 100 lines,Baremetal\Slate\Slate::toast(): ms must be at least 500;\ErrorBaremetal\Slate\Dialog is already open. The controls' animations give noTweenDone; Slate's internalHoldDuenow also wakes the PHP task at the end of a dialog's close (no more watches of ext-events: with the controls built, a Slate without a touch device takes the one ofHoldDue). - Added:
ProgressRing,ProgressBar,Spinner,StepList(extends Control, not final; not touchable by default,public bool $touchable = false).new ProgressRing(int|float $cx, int|float $cy, int $r, float $value = 0.0, int $width = 12, bool $percent = false): a track inwelland an arc inaccentwith round ends from the top for$valuex 360 degrees, sliding in 200 ms;public float $value(0..1, a finite value outside is brought into the range),public bool $spinning = false(an arc of 25 % that turns, 900 ms a turn),public ?int $color = null;$percentshowsround($value x 100)(fontDisplay) and%(font,accent) in the middle.new ProgressBar(int|float $x, int|float $y, int $w, float $value = 0.0, int $h = 4): a track inwelland a fill inaccent(radiush / 2) sliding in 200 ms;public float $value,public bool $glow = false(a shadow of the fill's colour, blur 10; none when shadows are not built),public ?int $color = null.new Spinner(int|float $cx, int|float $cy, int $r = 12): an arc of 25 %, 3 px, turning (900 ms a turn) while it is shown;public ?int $color = null.new StepList(int|float $x, int|float $y, int $w, array $steps, int $active = 0): one row per step (48 high, 8 apart), done (asuccesscircle with a check,textMuted), active (a spinner, anaccentborder,text), to do (aborderStrongring,textDim);public int $active(0..count($steps); the steps that become done pop),public readonly array $steps(at most 21). The turns and the pops give noTweenDone.\ValueError<Class>::$r must be between 1 and 32767(ProgressRing,Spinner),...::$width must be between 1 and 32767,...::$w must be between 1 and 32767(ProgressBar,StepList),...::$h must be between 1 and 32767,...::$value must be a finite number,...::$color must be a color, 0xRRGGBB,...::$steps must be a non-empty list of strings,...::$steps must hold at most 21 steps,...::$active must be between 0 and <n>. - Changed: a tween of an element with
$visible = false, or inside a group with$visible = false, waits (its time stopped, itsTweenDoneand the tweens chained after it too) and goes on from where it was when the element is visible again, as one of a scene not shown does; only$visiblecounts (a fade-in from$opacity0 runs). A hiddenSpinnerno longer keeps the compositor waking at every refresh. A tween that draws nothing (its element out of aScroll's view, or at$opacity0) no longer makes the touch table be built again at every refresh. - Fixed: on a panel that refreshes top to bottom, a frame that changes more than half of the screen also races the
panel's refresh (no tearing) when its last band can still be written behind the refresh before the next TE pulse
(other refresh orders: as before). A
Scrollwhose view is just over half of the screen (280 x 232 on the 360 x 360 panel) tore while it scrolled: rows looked cut or squeezed for one refresh. A larger change that reaches the bottom of the scan (a whole screen) is sent as before. - Fixed: an element taken out of the scene (a
Dialogthat closes) kept its caches out of reach: they stayed in the cache budget until it was freed, so a later shadow, blur or cached group could find no room (the second dialog of the example was drawn without its shadow, and tried again at every frame). Such caches are still kept (a dialog opened again builds nothing), but they make room first when a cache does not fit, before those of the scenes left. - Changed: a
Dialog's panel fades element by element: each of its parts is drawn with its own opacity times the panel's (an internal flat group), instead of being composed apart as one image at every frame; halfway through, texts and buttons look washed out and the panel's background shows through them. Its shadow is blur 30 (was 80), and it is built before the opening starts (SLATE_CMD_PREPARE: the tweens pushed after it start once it is built), so the first frame is not a long one and the animation skips no step after it. On the 360 x 360 example: frames of 34 to 49 ms during the 300 ms (were 93 to 101 ms), 7 to 9 of them (were 4 or 5), and the first opening no longer has a frame of 160 to 173 ms: its shadow takes 31 to 36 ms before the animation starts. - Changed: the blur of a shadow 385 to 512 px wide or high (was up to 384), such as the mask of a
Dialogof the default width on a 360 x 360 screen (388 px), takes the faster path that reads and writes the image once per direction (about half the time with the image in PSRAM). - Added: the
slate-controlsbuild option (bool, defaulttrue). Withfalsethe theme, its enums,Control, the controls,Slate::theme(),Slate::$theme,Slate::toast()andScene::open()are not built. - Docs:
docs/usage/controls.mdanddocs/usage/theme.md(new),docs/usage/performance.md(Controls: the touch table, tinted icons, dialogs, latency, memory per control, firmware),effects-and-options.md,overview.md; IDE stub. The06-display/slate-controlsexample shows the controls and a theme on the round 360 x 360 panel.
1.2.0
- Added: touch on elements. An element takes the finger when
Element::$touchableistrue(bool, defaultfalse; a component of your own declarespublic bool $touchable = true;) or when it has a callback:Element::on(TouchType $type, \Closure $fn): static(one per kind, a new one replaces the old one) andElement::off(TouchType $type): static. The kinds reach the element's methodsonPress(),onMove(),onRelease(),onTap(),onHold(),onCancel()(public,(Touch $t): void, empty, for subclasses to override) and then its callback. The area is what the finger sees in the frame shown (a group with its children, a clipping group its whole clip box), grown byElement::$hitPad(0..64 px, default 0) and cut by the clips of its ancestors; the touchable drawn on top wins, and children that take no touch are part of their touchable ancestor.Presscaptures the finger (MoveandReleasecome wherever it goes);TapfollowsReleasewhen the finger stayed within 8 px of the press, noHoldcame and it came up on the area;Holdcomes once afterElement::$holdMs(0..10000 ms, default 500; 0: never) without a move past 8 px, and then noTap;Cancel(noRelease, noTap) when aScrollit is in takes the finger, the element or an ancestor is removed or hidden, the element stops taking touches, orSlate::show()shows another scene or starts a transition (a cause inside a touch handler: right after it returns;show(): at once, beforeonLeave()). An element hidden (also at$opacity0), made not touchable or removed takes no new touch at once, before the next frame. AScrolltakes the touches by itself (Scroll::$touchabledefaults totrue), with the state machine ofScroll::touch(): a press on its view drives it; a touchable element inside it that moves more than 8 px before aHold, on the axis the scroll can move (the larger movement), getsCanceland the scroll takes the touch from the press point and time, following the finger from the point past 8 px without a jump (no axis it can move: the element keeps it); a press while it moves is a catch (the element under the finger gets nothing); scrolls inside scrolls: the innermost that can move in that direction. A scroll's touch that ends without itsReleased(the causes ofCancel, or a newPressedfirst) stops its drag without speed (ScrollEndedfollows once a drag had started). A scroll hidden during a drag routed by hand withtouch()now ends it as well (at itsReleased: before, it stayed armed and the next press was a catch).Scroll::touch()stays for routing by hand ($touchable = false, or touches that hit nothing) and does nothing (returnsfalse) for a touch Slate routes to that scroll.final class Touch, made by Slate only (private constructor; read-onlyTouchType $type,Element $element,int $x,$y,$localX,$localYfrom the element's origin on the screen,int|float $timeasEvent::$time: ns on the base ofhrtime(true), a float on 32-bit PHP),enum TouchType(Press,Move,Release,Tap,Hold,Cancel). Changed:Scene::onTouch()now gets only the touches whosePressedhits no touchable element (a scene without touchable elements gets them all, as before); since aScrollis touchable by default, the touches that hit a scroll no longer reachScene::onTouch()(set$touchable = falseon it to keep routing them by hand withtouch()); nor does theGestureof a touch an element or a scroll took, which the touch controller may report after theReleased. Touches stay ignored during a transition. Slate takes one more of ext-events' eight watches (six: four for the touch events, one for theHoldtimer through the internal coalescing eventHoldDue, one forTransitionDone).\ValueErrorBaremetal\Slate\<Class>::$hitPad must be between 0 and 64,...::$holdMs must be between 0 and 10000,...::$<name> cannot be animatedfor the three properties;\RuntimeExceptionSlate: cannot take the touch: the table of ext-events' watches is full. A scene without touchable elements does no more work. Engine side: the propertiesSLATE_PROP_TOUCHABLEandSLATE_PROP_HIT_PAD, a table of the touchables' boxes published after each frame that changed something (src/hit.h; none with zero touchables),slate_engine_set_hit_pub, the statshit_builds,hit_entries,hit_nomem, and the scroll commandSLATE_SCROLL_OP_CANCEL(a release without velocity). Docs:docs/usage/touch.md,docs/usage/scroll.md(touch); IDE stub. The06-display/slate-scrollexample uses touchable rows instead of its own hit maths. - Added: animations, run by the compositor at the pace of the panel (no PHP timer).
Element::animate(array $props, int $ms = 300, Ease $ease = Ease::OutCubic, int $delay = 0, int $repeat = 0, bool $yoyo = false): Tweenmoves properties from their values on the screen to the ones given; the properties read their final values at once. Animatable:x,y,opacityof every element,Groupw,h,blur,RoundRectw,h,radius,border,fill,borderColor,Circler,border,fill,borderColor,Arcr,from,to,width,color,Linex1,y1,width,color,Textcolor(colours channel by channel).final class Tween: read-only$done,stop(bool $toEnd = false)(with the chain after it, no event),wait(int $timeout_ms = 5000)(hands the changes over, delivers no other event; false at once for a stopped tween orrepeat: -1),then(Element $e, array $props, int $ms = 300, Ease $ease = Ease::OutCubic): Tween(starts at its exact end).Element::ease(array $props, int $ms = 300, Ease $ease = Ease::OutCubic): static: writes of those properties slide (ease([])removes it). The eventTweenDone($tween, final), once per tween that ends by itself, never forrepeat: -1nor after a stop (unless the tween ended in the frame the stop arrived); a$donewhose event was dropped (a full event pool,init-loop) is set at the return to the event loop. The enumEase(Linear,InQuad,OutQuad,InOutQuad,InCubic,OutCubic,InOutCubic,OutBack,OutBounce,OutElastic). Tweens of a scene that is not shown wait for it;remove()of an element stops its tweens (aremove()andadd()in one delivery keeps them), and so does the end of its group or scene (a page dropped with its animations running leaks nothing); the tween of an element not drawn yet (made inbuild(), or beforeadd()) waits and starts when it is shown,then()after it too. Everything is checked before anything changes, with\ValueErrorBaremetal\Slate\<Class>::$<name> cannot be animated,...::$fill cannot be animated: it is a gradient(likewise$color),...::$fill cannot be animated: it is null(likewise$borderColor),ms must be at least 1,delay must be 0 or more,repeat must be -1 or more,props must name at least one property, or the property's own range message. A write of the value a property already holds is sent all the same on an element that was animated (the screen may show another value after a stop). Docs:docs/usage/animations.md; IDE stub 1.2.0. - Added: scroll.
class Scroll extends Group(not final): a view(0, 0, $w, $h), always clipped, over its children (the content, in content coordinates), drawn shifted by the scroll position.Scroll::__construct(int|float $x = 0, int|float $y = 0, int|float $w = 1, int|float $h = 1, ScrollAxis $axis = ScrollAxis::Both, bool $bounce = true, int $snapX = 0, int $snapY = 0, int $snapMax = 0, bool $indicators = true, int $contentW = 0, int $contentH = 0, float $opacity = 1.0, bool $cache = false). Properties:$contentW,$contentH(0..32767; 0: the box of the children from (0, 0), kept up to date),$axis,$bounce,$snapX,$snapY(0..32767, 0: none),$snapMax(0..32767, 0: no limit; at most that many snap steps per release, counted in the direction of the fling from the step at or behind the release position, per axis with a snap step, never back against the fling, the nearest step under 20 px/s:snapMax: 1moves a carousel one card per fling),$indicators,$scrollX,$scrollY(read: the position last drawn, the value written until it is drawn; written: a jump kept within0..max(0, content - view), which stops any motion and ends a drag),$clipalwaystrue,$w,$h1..32767;$cachekeeps the whole content as one image copied at each position (composed directly when it does not fit the cache; withslate-debugthe console says so once).touch(\Baremetal\Input\TouchEvent $e): bool: touches routed by hand (usually fromScene::onTouch(); a scroll also takes them by itself, see touch on elements);truewhen the touch is a drag of the scroll (past 8 px from the press on the axis allowed, withBoththe distance; the Released that ends it) or a catch (a press inside the view that stopped its motion, with every Moved and the Released of that touch);falsefor a press outside the view, a tap, aGestureand a scroll not in the scene shown. The compositor runs the drag (following the finger from the threshold point), the release velocity of the last 80 ms (at most 4000 px/s), the inertia (325 ms time constant), the rubber band past an edge (`d * (1 - 1 / (over * 0.55 / d- 1))
, at most half the view) with a critical spring back, the snap to a step (OutCubic, 150 to 600 ms; the end counts as a step) and the bars (3 px, 2 px from the right and bottom edges,view² / contentlong, at least 16 px; shown while the content moves, then 500 ms, then faded in 200 ms), at the frame's time; a motion pauses while its scene is not shown and goes on during a transition; a kept scene keeps its position.scrollTo(int|float $x, int|float $y, int $ms = 300, Ease $ease = Ease::OutCubic): Tween(ms0: a jump, the Tween done at once; a press, a write of the position or a new set-up stops it withoutTweenDone). The enumScrollAxis(Both,Vertical,Horizontal); the eventScrollEnded(final,Scroll $scroll,int $x,int $y): once when the content comes to rest after a release or at the end of ascrollTo()(after itsTweenDone), none for a scroll freed before its motion ends (one freed after its end was queued gets an event with a stand-inScroll).\ValueErrorBaremetal\Slate\Scroll::$w must be between 1 and 32767($h),...::$clip is always true,...::$snapX must be between 0 and 32767($snapY,$snapMax,$contentW,$contentH),...::$scrollX must be a finite number($scrollY, andscrollTo()'s$x,$y),...::$scrollX cannot be animated; use scrollTo()(animate()/ease()of$scrollX,$scrollY,$contentW,$contentH,$snapX,$snapY,$snapMax),ms must be 0 or more. A scene without a moving scroll does no more work per frame, and a still screen composes no frame. Engine side: the commandSLATE_CMD_SCROLL(slate_scroll_cmd_t), the position published without a lock (slate_scroll_pub_t),slate_engine_scroll_done, the statsscrolls_active,anim_ticksand the compositor'sscroll_nocache; the physics insrc/scroll.h(pure C). Docs:docs/usage/scroll.md`; IDE stub.
- 1))
- Added: the engine side of tweens (
src/tween.h: easing curves, sampling from the elapsed time, delay, repeat, yoyo, pause, chains;src/engine.h, Tweens: the commandsSLATE_CMD_TWEEN,SLATE_CMD_TWEEN_STOP,SLATE_CMD_EASE, the tick at the vsync time of the frame, a frame per pulse only while tweens run, tweens of a scene not shown paused, the done queueslate_engine_tween_done, drained by the PHP layer from the tween listener on the engine's task: one ext-events event per id). A scene without tweens does no more work per frame. Slate takes one of the four idle hooks of ext-events, shared by the running Slate, the images, the animations and the transitions. - Added: page transitions.
Slate::show(Scene $s, ?Transition $t = null): with$tthe new scene comes in while the compositor composes both scenes together.final class Transition(private constructor, no clone):Transition::fade(int $ms = 300, Ease $ease = Ease::OutCubic),Transition::push(Direction $d, int $ms = 300, Ease $ease = Ease::OutCubic),Transition::cover(...)andTransition::uncover(...)with the same parameters aspush()(\ValueErrorms must be at least 1,ms must be at most 2147483647); the enumDirection(Left,Right,Up,Down: the direction of the movement); the eventTransitionDone(final,Scene $from,Scene $to). Order:build()the first time andonEnter()of the new scene at once,onLeave()of the old one andTransitionDoneat the end (onLeave()runs from Slate's own watch of the event, before the listeners);scene()is the new scene meanwhile; the touch reaches no scene fromshow()to the end.show()of the scene shown (also of the one a transition goes to) does nothing;show()during a transition ends it first (onLeave()of the scene it leaves at once, itsTransitionDonefollows), then the new change starts. A transition from no scene (the firstshow()) comes in over the background, with noTransitionDone. When its event is not delivered (init-loop, a full pool) theonLeave()runs at the nextshow()orcommit(). When the Slate stops during a transition neither comes. A transition that cannot start (no memory for its layers) is a cut, still with itsonLeave()andTransitionDone.\RuntimeExceptionSlate: cannot run a transition: the table of ext-events' idle hooks is full(or... watches is full: Slate takes one of the eight watches of ext-events for TransitionDone, besides the four of the touch) andSlate: out of memory for the transition. Without$t,show()is instant as before. Docs:docs/usage/scenes.md(Transitions),docs/usage/animations.md; IDE stub. - Added: the engine side of transitions (
src/compose.h, Transitions:slate_pair_begin/slate_pair_at/slate_pair_end, two scene roots in layers under the screen root, each cut to its page, the top one over a curtain of its background, moved by whole pixels or composed offscreen with opacity in strips of the existing scratch: no new screen-sized buffer, both bands as before; caches built for their page and moved with it; the strips of a group sized for what its nested groups need;slate_compose_underlay_free()).src/cmd.h: a SHOW carries aslate_trans_t(kind, direction, ease, ms) next to the PIXELS rectangle;slate_trans_ok(); a bad transition makes the push returnSLATE_CMD_BAD_ARG.src/engine.h, Transitions: the start at the batch's time, the ticks with the tweens' (the whole screen dirty only when the layers moved), the end at its time also while the panel sleeps, a SHOW during a transition ending it first (a SHOW of the scene it goes to only changes the name and the background), REMOVE of either scene refused and FREE ending it, the underlay off meanwhile; the done queueslate_engine_transition_done()(the roots' ids, 64 waiting), drained from the tween listener; a transition that cannot begin (no memory for its layers) is a cut that still queues its done;slate_engine_in_transition();stats.transitionsandstats.transition_dones_lost. A scene without a transition does no more work per frame. - Changed: a scene left keeps its caches (cached groups, shadows, blurs) for a return to it while there is room:
showing it again (also with a transition) builds nothing.
Slate::$keepScenes(int, default 2; 0: every scene left drops its caches, as in 1.1),Slate::$keptBudget(?intKB, default null: only the cache budget; 0: nothing kept),Scene::$keepCache(protectedbool, default true; false: dropped when the scene is left, read at theshow()that leaves it). Past$keepScenesor$keptBudgetthe scene left first drops its caches at once, also when they are lowered. The kept caches stay in the existing cache budget in PSRAM (no internal RAM, no new pool): when the scene shown or the underlay needs room there, the scenes left drop theirs first, the one left first before the others. Images are outside that budget, but an image that cannot be loaded for lack of memory has the scenes left drop their caches and is loaded once more (only thenno-memory;docs/usage/images.md).\ValueErrorkeepScenes must be 0 or more,keptBudget must be 0 or more(the old value stays); neither can be taken by reference or unset. IDE stub anddocs/usage/scenes.md(Returning to a scene),docs/usage/performance.md. - Added: the engine side of the kept scenes (
src/engine.h, Kept scenes):slate_engine_set_keep(e, scenes, budget_bytes)(applied at the next wake-up; engine default 0, as before), the SHOW'skeepflag (src/cmd.h: the scene it leaves may keep its caches), the list of kept roots, oldest first; the engine'scache_alloctakes their room first, oldest first, only when that makes the block fit (in the budget or in external RAM); a SHOW of a kept root or an ADD of it into a group takes it off the list, FREE of a kept root (or of an element in one) and REMOVE of an element from one drop the caches under it first, an ADD into a kept scene counts the caches it brings; a SHOW applied afterslate_engine_set_keepalways uses the new limits; the image loader's reclaim (slate_images_set_reclaim()insrc/images.h, set by the engine at start: out of memory for an image, the loader sets a flag and kicks the engine, the engine drops every kept cache on its own task and answers on a queue, the loader waits at mostSLATE_RECLAIM_WAIT_MS(100 ms) and reads the file once more when something was freed or no answer came; only a block the store's allocator refused asks; without an engine, with one stopping, or with nothing kept, it fails at once as before;slate_engine_stopcuts the loader off first and waits, by the clock, for a request under way before it frees anything);stats.kept_scenes,stats.kept_bytes,stats.kept_dropped,stats.reclaims. No work per frame. - Fixed: waits that loop until another task is done now block at least
SLATE_NAP_MS(10 ms, one tick atCONFIG_FREERTOS_HZ = 100) per turn: with a 100 Hz tick a wait of 1 ms is 0 ticks, a busy loop that could starve a lower-priority task on the same core (the esp32 SDK runs a 1 kHz tick, where 1 ms blocks).sl_images_engine(NULL)(the stop of a Slate waiting for an image listener's kick under way) waited this way. - Fixed: the default cache budget is half of the largest external block within 1/16, no longer half of the power of
two below it. With 1 008 KB free in one block at start it was 256 KB, short of the underlay of a 360 x 360
screen (about 260 KB): the busy scene of
slate-stresslost its underlay and ran at 35 frames per second instead of 55. It is now 496 KB. On boards with about 1.1 to 2 MB free PSRAM in one block the default budget rises too (1.9 MB gives about 930 KB, it was 512 KB): more room for the live and kept caches, less headroom for images. - Fixed: when the stop of a Slate fails because an image load waiting for memory did not end in time, the warning
says so (
Slate: the compositor did not stop cleanly (an image load waiting for memory did not end in time); its memory stays) instead of blaming the panel. - Changed: the compositor's task has a 10 KB stack (
SLATE_ENGINE_STACK, it was 8 KB): a cached group with a shadow built inside the offscreen layer of a fade used 6.3 KB, and deeper nesting of cached and blurred groups needs more. About 2 KB more of internal RAM. - Fixed: a tween and a page transition of the same length started in one batch now start on the same time (the batch's, the panel pulse it came with) and end on the same frame; the tween started a little later before.
- Fixed: writing to an element of a scene that is kept but not shown no longer leaves the kept-cache count high, which made the cache budget evict the kept scenes for a block that did not fit anyway.
1.1.0
- Added: the PHP API of images.
Image(new Image($x, $y, $src, opacity: 1.0)), an element that draws a.slifile or a.pngdecoded on the board, loaded in the background:$src(an absolute path ending in.slior.png, in any case; checked at once with\ValueErrorBaremetal\Slate\Image::$src must be an absolute path,Baremetal\Slate\Image::$src must end in .sli or .png, orpng is not built in: add it to slate-images in composer.json), read-only$w,$h,$loaded(updated when the event is delivered, or bywait()),wait(int $timeout_ms = 5000): bool(blocks without delivering other events; false on timeout or failure). Images of one path are loaded once and shared; anImageof a path in memory is ready at once; the path of a failed image is loaded again by the nextImageor$srcof it.Images::preload(array $paths): Preloadkeeps the images in memory while thePreloadlives ($loaded,$total,$done,wait()). The eventsImageLoaded($path,$w,$h),ImageFailed($path,$error,$message),PreloadProgress($loaded,$total) andPreloadDone($failed) on the bus of ext-events, and the enumImageError(NotFound,Unreadable,BadFormat,Unsupported,NoMemory). The store's listener wakes the compositor when an image is done, so it is drawn without waiting for another change; ininit-loop(no events) the properties still follow at the end of eachloop(). Every Preload gets exactly one PreloadDone, also when a burst of images overflows the event pool (the images whose events were dropped are caught up at the return to the event loop, and a refused PreloadDone is raised again). Docs:docs/usage/images.md(assets, board paths/app/...and/sdcard/..., memory of images, which comes from the PSRAM the SDK leaves outside PHP: the esp32 SDK'sfirmware-reserve, and memory of on-board PNG), theslate-imagesoption, performance; IDE stub 1.1.0. - Added: .sli images, Slate's run-length image format (written by phpbm image:convert): a reader that checks a whole
file once (header, row table, every command, padding, the opaque flag) and a drawer that composes the image band
by band with the graphics layer's fill and copy entries, at any opacity and clip (
src/sli.h:slate_sli_open,slate_sli_draw). - Added: PNG files decoded on the board into .sli images, byte for byte what phpbm image:convert writes for the
same file (
src/png.h:slate_png_to_sli): colour types grey, RGB, palette, grey+alpha and RGBA at 8 bits (grey and palettes also at 1, 2 and 4),tRNS, the five filters, image data in any number of IDAT chunks, every CRC and the Adler-32 checked; 16-bit and interlaced images are reported as unsupported. The file is read as a stream through a small inflate written for Slate (src/inflate.h, no third-party code): the 32 KB window, two rows and the result, never the whole image. The .sli encoder is a C API of its own (src/sli_enc.h: new, row, finish, abort), and the load errors areslate_img_err_tinsrc/sli.h. - Added: the build option
slate-images(set ofpng, default["png"]): withoutpngthe PNG decoder and the inflate code are not built; .sli images are always supported. - Added: the image store and its loader task (
src/images.h): images shared by path with counted references (slate_image_get,slate_image_ref,slate_image_put, from any task), loaded one at a time by a low-priority task of the events HAL that starts with the first request and ends when nothing is left to load (6 KB of stack, only while it runs), read with the C standard I/O (.sli as it is, .png decoded) into external RAM, outside the cache budget; LOADING, then READY (immutable) or FAILED withslate_img_err_t; a listener called once for every image done, from the task (or fromslate_image_getwhen the task cannot start: NO_MEMORY); an image dropped while it loads is freed at the end, one dropped while it waits is never loaded; a failed image leaves the store, so the next request of its path loads it again. The extension (.png,.sli) is matched in any case. - Added: the IMAGE scene element (
SLATE_EL_IMAGE, propertySLATE_PROP_IMAGEwithslate_v_image): drawn at its rounded position withslate_sli_draw_ops(the table of the buffer it goes into, so also inside groups with opacity, caches and blur), times its opacity; an opaque image at opacity 1 covers what is under it; a still image that blends makes the underlay worth keeping. Nothing is drawn or covered until the engine sees the image ready (slate_el_image_sync): then only its box is composed again. Commands carrying an image hold a reference.
1.0.0
- First release: the PHP API
Baremetal\Slate(Slate,Scene, the elementsRoundRect,Circle,Arc,Line,Text,Group,Canvas, the enumsCapsandAlign,LinearGradient,RadialGradient,Shadow), the compositor task on the band path of ext-display 1.1, the software graphics layer with its C API (slate_gfx.h, overridable per entry), and the build optionsslate-effects(gradients,shadows,blur) andslate-debug. - Frames: paced on the panel's TE pulses (or its refresh rate without a TE pin); only the changed parts of the
screen are composed, in up to 32 dirty regions merged only when that costs fewer pixels; still elements at the
bottom of the scene are kept as a screen image (the underlay) and copied under the changes; element caches
(
$cache,$shadow,$blur) in PSRAM within a budget; a still screen costs no frame.set(x: .., y: ..)is one move. - No tearing on a panel with a TE pin and a known refresh order (ext-display 1.1
scan): a frame that changes at most half of the screen writes each band where the panel's refresh is not reading, and the whole frame shows in one refresh, with the same delay wherever it is on the screen. - Memory: the two band buffers come from the panel driver (internal RAM); the scratch area for groups with opacity
and cache builds (internal RAM, at most a band's worth, 43 KB on a 360-wide panel) is taken when a group needs
it and given back when no frame has needed all of it for a second or another scene is shown, so the rest of the
program (Wi-Fi) has that RAM meanwhile. The pixel code is compiled for speed (
-O2, GCC) whatever the project's optimization. Frame rates and full-screen times are in the Performance page. - The panel's
sleep()pauses the frames (the changes wait) andwake()resumes them; after awake()that re-initialised the panel (ext-display 1.1display_claim_ex(),display_invalidate()) the whole screen is sent again. - A panel that stops answering stops the compositor, and the next call that changes the scene throws
\RuntimeException:Slate: the panel did not finish a band within 2000 ms, orSlate: the panel refused the bands (error 0x..)when the driver marked the panel failed (BM_ERR_INVALID_STATE) or refused every band for 4 frames in a row. - Properties are validated on every write; references to them,
unset()andforeachby reference over an element throw\Error. Writes througharray_walk(),ArrayObjectorArrayIteratorover an element are not checked: the compositor refuses such a change when the element is shown. - With
slate-debug: an FPS counter on screen and one line of statistics per second on the console, printed outside the frames and their times. - Requires php-baremetal/ext-display ^1.1, php-baremetal/ext-events ^1.2 (the hooks that hand the changes over when PHP returns to the event loop), php-baremetal/ext-input ^1.0 and php-baremetal/bm-common ^1.1.