An opaque reference to a compositing layer owned by the canvas.
A HANDLE, not a scope. save_layer(...) / restore() is a statement PAIR: the layer exists only between the two calls and is composited exactly once, at the restore. That shape cannot express the thing a retained compositor actually needs — rendering a subtree into a texture ONCE and reusing that texture on later frames, or drawing it several times at different transforms. A handle can:
// Frame N and every frame after:
if (!canvas.layer_valid(cached_)) { // survives across frames
canvas.begin_layer(bounds, /*cacheable=*‍/true);
draw_expensive_contents(canvas);
cached_ = canvas.end_layer(); // seals it
}
canvas.draw_layer(cached_, alpha); // cheap, every frame
...
canvas.invalidate_layer(cached_); // when contents change
id == 0 is the null handle, which every operation ignores.
1.15.0