Module image_layer 

One shell-supplied picture drawn over the frame, behind the non-default text feature beside the text layer it composites with.

The shell hands the renderer an RGBA8 image with Renderer::set_overlay_image, which is the only upload: the bytes go into a texture the layer keeps, and every later frame that wants the picture queues a rectangle with Renderer::queue_image, the way it queues TextRuns. The draw rides the pass that draws the text, before the text, so a label can sit on top of the picture.

A renderer that never sets an image holds no GPU object for this layer. The pipeline, sampler, rectangle uniform, texture and bind group are all built on the first set, so the cost of the layer while unused is one Option test per frame. A frame that sets an image and queues nothing encodes no draw; a frame that only queues writes no texture and, while the rectangle is unchanged, writes nothing at all.

The texture is Rgba8UnormSrgb, the format a headless capture reads back from, so bytes a capture wrote are sRGB-encoded exactly as this texture expects: sampling decodes them to linear light and the sRGB surface encodes them again on the way out, and a picture drawn at its own size reads back as the bytes it was set from. An Rgba8Unorm texture here would apply the surface’s encode to bytes that already carry it, and the picture would come out washed pale.

Structs

ImageRect

Where the set image is drawn this frame, in device pixels from the target’s top-left — the coordinate space TextRun uses. The image is stretched to fill it; the caller chooses a rectangle of the image’s own aspect if it wants none.

OverlayImage

An image the shell hands the renderer: width * height pixels of RGBA8, rows top first, no row padding — a CaptureImage’s own layout. The bytes are copied into a texture; the borrow ends with the call.

Enums

OverlayImageError

Why Renderer::set_overlay_image refused an image. Nothing changes on a refusal: an image already set stays set.