Module picture 

A picture represents a dynamically rendered image.

Overview

Pictures consists of:

• A number of primitives that are drawn onto the picture.
• A composite operation describing how to composite this picture into its parent.
• A configuration describing how to draw the primitives on this picture (e.g. in screen space or local space).

The tree of pictures are generated during scene building.

Depending on their composite operations pictures can be rendered into intermediate targets or folded into their parent picture.

Picture caching

Pictures can be cached to reduce the amount of rasterization happening per frame.

When picture caching is enabled, the scene is cut into a small number of slices, typically:

• content slice
• UI slice
• background UI slice which is hidden by the other two slices most of the time.

Each of these slice is made up of fixed-size large tiles of 2048x512 pixels (or 128x128 for the UI slice).

Tiles can be either cached rasterized content into a texture or “clear tiles” that contain only a solid color rectangle rendered directly during the composite pass.

Invalidation

Each tile keeps track of the elements that affect it, which can be:

• primitives
• clips
• image keys
• opacity bindings
• transforms

These dependency lists are built each frame and compared to the previous frame to see if the tile changed.

The tile’s primitive dependency information is organized in a quadtree, each node storing an index buffer of tile primitive dependencies.

The union of the invalidated leaves of each quadtree produces a per-tile dirty rect which defines the scissor rect used when replaying the tile’s drawing commands and can be used for partial present.

Display List shape

WR will first look for an iframe item in the root stacking context to apply picture caching to. If that’s not found, it will apply to the entire root stacking context of the display list. Apart from that, the format of the display list is not important to picture caching. Each time a new scroll root is encountered, a new picture cache slice will be created. If the display list contains more than some arbitrary number of slices (currently 8), the content will all be squashed into a single slice, in order to save GPU memory and compositing performance.

Compositor Surfaces

Sometimes, a primitive would prefer to exist as a native compositor surface. This allows a large and/or regularly changing primitive (such as a video, or webgl canvas) to be updated each frame without invalidating the content of tiles, and can provide a significant performance win and battery saving.

Since drawing a primitive as a compositor surface alters the ordering of primitives in a tile, we use ‘overlay tiles’ to ensure correctness. If a tile has a compositor surface, and that tile has primitives that overlap the compositor surface rect, the tile switches to be drawn in alpha mode.

We rely on only promoting compositor surfaces that are opaque primitives. With this assumption, the tile(s) that intersect the compositor surface get a ‘cutout’ in the rectangle where the compositor surface exists (not the entire tile), allowing that tile to be drawn as an alpha tile after the compositor surface.

Tiles are only drawn in overlay mode if there is content that exists on top of the compositor surface. Otherwise, we can draw the tiles in the normal fast path before the compositor surface is drawn. Use of the per-tile valid and dirty rects ensure that we do a minimal amount of per-pixel work here to blend the overlay tile (this is not always optimal right now, but will be improved as a follow up).

Re-exports

pub use crate::surface::SurfaceIndex;

pub use crate::surface::SurfaceInfo;

pub use crate::surface::SubpixelMode;

pub use crate::surface::calculate_screen_uv;

pub use crate::picture_composite_mode::PictureCompositeMode;

pub use crate::picture_composite_mode::prepare_composite_mode;

Structs

BlitReason

A set of flags describing why a picture may need a backing surface.

ClusterFlags

A set of flags describing why a picture may need a backing surface.

OrderedPictureChild

Information about a preserve-3D hierarchy child that has been plane-split and ordered according to the view direction.

PictureFlags

Flags describing properties for a given PictureInstance

PictureInstance

PictureScratch

Per-frame scratch data for a Picture primitive. Pushed in take_context and read by both prepare and batch through the scratch_handle carried on PrimitiveKind::Picture.

PictureScratchBuffer

PrimitiveCluster

Descriptor for a cluster of primitives. For now, this is quite basic but will be extended to handle more spatial clustering of primitives.

PrimitiveList

A list of primitive instances that are added to a picture This ensures we can keep a list of primitives that are pictures, for a fast initial traversal of the picture tree without walking the instance list.

RasterConfig

Enums

Picture3DContext

Enum value describing the place of a picture in a 3D context.

ResolvedSurfaceTexture

This is the same as a SurfaceTextureDescriptor but has been resolved into a texture cache handle (if appropriate) that can be used by the batching and compositing code in the renderer.

SurfaceTextureDescriptor

A descriptor for the kind of texture that a picture cache tile will be drawn into.

Constants

MAX_BLUR_RADIUS 🔒

MAX_COMPOSITOR_SURFACES_SIZE

Maximum size of a compositor surface.

Functions

clamp

clampf

compute_subpixel_mode 🔒

get_relative_scale_offset

prepare_tiled_picture_surface 🔒

Update dirty rects, ensure that tiles have backing surfaces and build the tile render tasks.