Draw control
Open the live demo · Read the source · View on GitHub
Three small controls over how a mesh is drawn. MeshNode.drawOrder decides
which of two nodes goes first, even when they share a material.
Material.alphaToCoverage smooths the edge of a masked surface where the
device can do it. And PassEncoder.draw can read a window of the bound index
buffer, so one buffer that holds every part of a model can be drawn a part at
a time.
On the left of this page, a red panel and a blue panel stand in exactly the same place. On the right is a grille cut from a small texture.
Step 1: Two meshes in one place #
The two panels use the same mesh and the same transform, so every pixel of one is also a pixel of the other, at the same depth. The scene pass keeps a fragment only when it is nearer than what is already there, and an equal depth is not nearer. So the first panel drawn keeps every shared pixel.
// Two panels of one mesh at one place: every pixel of one is a pixel of
// the other, at exactly the same depth. The depth test keeps the first
// fragment and refuses an equal one after it, so whichever is drawn first
// is the one seen.
_red = MeshNode(
_panel,
RenderMaterial(
name: 'red',
baseColor: LinearColor.fromSrgb(0.85, 0.2, 0.15, 1.0),
),
name: 'red panel',
)..setPosition(-0.9, 1.0, 0.0);
_blue = MeshNode(
_panel,
RenderMaterial(
name: 'blue',
baseColor: LinearColor.fromSrgb(0.15, 0.35, 0.9, 1.0),
),
name: 'blue panel',
)..setPosition(-0.9, 1.0, 0.0);
Step 2: Say which goes first #
Lower draws first. The node's drawOrder is added to its material's
drawBucket, and that sum is the first field of the sort key, ahead of the
pipeline, the material and the depth. The batching never merges a run of
identical draws across two orders, so a batch cannot undo the order either.
Switch Drawn first, and so seen and the other colour takes the panel.
// Lower draws first. The order is added to the material's `drawBucket`
// and outranks every other term of the sort, depth included.
_red.drawOrder = redFirst ? -1 : 0;
_blue.drawOrder = redFirst ? 0 : -1;
Step 3: A masked edge as coverage #
The grille is a 16 by 16 texture with a grid of round holes in its alpha,
drawn with MaterialAlphaMode.mask and a cutoff of a half. Without coverage
each pixel is either kept or cut, which leaves a staircase round every hole.
With alphaToCoverage the alpha is sharpened to about a pixel's width round
the cutoff and handed to the multisample resolve as coverage, so the holes
come out as smooth as a triangle's edge.
// A grille: a small texture whose alpha is a grid of round holes, cut at
// a half and turned into multisample coverage where the device can.
const int size = 16;
final Uint8List texels = Uint8List(size * size * 4);
for (var y = 0; y < size; y++) {
for (var x = 0; x < size; x++) {
final double dx = (x % 4) - 1.5;
final double dy = (y % 4) - 1.5;
final int i = (y * size + x) * 4;
texels.setAll(i, <int>[230, 230, 220, 255]);
texels[i + 3] = math.sqrt(dx * dx + dy * dy) < 1.4 ? 0 : 255;
}
}
_grille = RenderMaterial(
name: 'grille',
albedo: context.device.createTextureFromPixels(
width: size,
height: size,
format: TextureFormat.r8g8b8a8UNormInt,
pixels: ByteData.sublistView(texels),
),
alphaMode: MaterialAlphaMode.mask,
alphaCutoff: 0.5,
alphaToCoverage: coverage,
doubleSided: true,
);
Only WebGL2 and WebGPU can do this, and only in a scene pass that
multisamples. Impeller has no control for it and the software rasteriser
draws one sample, so there the grille is drawn with its hard cutoff and
FrameResult.alphaToCoverageDeclined is true.
Step 4: A window of the index buffer #
The meshes in a scene draw their whole index buffer. Code that encodes its
own pass, such as a PassContributor or a frame graph node, can call
PassEncoder.draw(firstIndex: ..., indexCount: ...) to draw part of it. A
cube's 36 indices are six faces of six, so each face is one window.
indexWindow is the rule all four backends apply to such a call: a window
that runs past the end of the binding is refused with a RangeError before
any driver sees it.
List<IndexWindow> _faces() => <IndexWindow>[
for (var face = 0; face < 6; face++)
indexWindow(_panel.indexCount, firstIndex: face * 6, indexCount: 6),
];
Step 5: What the page checks #
The sorted draw list has to put the panel with the lower order first. On a device without coverage, the frame has to say the grille's coverage was declined. The six windows have to cover the whole index buffer, and a window of twelve indices starting at the thirtieth has to be refused.
// The sorted list puts the panel with the lower order first.
final CameraView view = CameraView(camera: _camera);
final RenderList list = RenderList()
..build(
scene,
view,
viewMatrix: _camera.viewMatrix,
frustum: Frustum.matrix(
_camera.viewProjection(frame.frame.width / frame.frame.height),
),
)
..sort(view);
final List<MeshNode> drawn = <MeshNode>[
for (final int i in list.opaque) list.itemAt(i).requireNode,
];
final MeshNode first = redFirst ? _red : _blue;
final MeshNode second = redFirst ? _blue : _red;
if (!drawn.contains(first) ||
!drawn.contains(second) ||
drawn.indexOf(first) > drawn.indexOf(second)) {
throw StateError('${first.name} is not drawn before ${second.name}');
}
// A device without coverage draws the hard cutoff and says so.
if (coverage && !_device.features.has(DeviceFeature.alphaToCoverage)) {
if (!frame.alphaToCoverageDeclined) {
throw StateError('coverage was declined and the frame did not say so');
}
}
// Six windows tile the cube's 36 indices; one past the end is refused.
final List<IndexWindow> faces = _faces();
if (faces.last.first + faces.last.count != _panel.indexCount) {
throw StateError('the faces do not cover the index buffer');
}
try {
indexWindow(_panel.indexCount, firstIndex: 30, indexCount: 12);
throw StateError('a window past the binding was accepted');
} on RangeError {
// Refused before any driver sees it, which is the claim.
}
Note. The check reads the sorted list and the frame's flags, not the pixels, so which colour wins the shared panel is shown on screen rather than tested here. The page cannot show coverage working on the software device the tests use, only the refusal. Per-draw windows have no setting on
MeshNode: a scene mesh is always drawn whole, and a window is for code that writes its own pass.