RenderObject provides the basic infrastructure for managing a tree of visual elements. Render objects define a general protocol for performing layout, painting, and compositing. This protocol is largely abstract, deferring to subclasses to determine the inputs and outputs of layout, how hit testing is performed (though all render objects are
HitTestTargets), and how the render object hierarchy is modeled (
AbstractNode, which doesn't specify a concrete child model).
Constraints represent the immutable inputs to layout. The definition is flexible provided that constraints can indicate whether they represent a single configuration (
Constraints.isTight), are expressed in the canonical form (
Constraints.isNormalized), and can be compared for equality (via
ParentData represents opaque data stored in a child by its parent. This data is typically considered an implementation detail of the parent and should therefore not be accessed by the child. Parent data is flexibly defined and only includes a single method (
ParentData.detach, which allows instances to react to their render object being removed from the tree).
RendererBinding establishes a
PipelineOwner as part of
RendererBinding.initInstances (i.e., the binding’s “constructor”). The pipeline owner serves as the render tree's
AbstractNode.owner (set by
AbstractNode.attach and propagated by
PipelineOwner is analogous to the
BuildOwner, tracking which render objects need compositing bits, layout, painting, or semantics updates. Objects mark themselves as being dirty by adding themselves to specific lists (e.g.,
PipeplineOwner._nodesNeedingPaint). All dirty objects are later cleaned by a corresponding “flush” method (e.g,
PipelineOwner.flushPaint). These methods initiate the corresponding rendering process and are invoked every frame as needed (via
Rendering takes place by flushing dirty render objects in a specific sequence:
PipelineOwner.flushLayout lays out all dirty render objects (laying out dirty children recursively, based on each
PipelineOwner.flushCompositingBits updates a cache used to indicate whether descendant render objects create new layers. If so, because painting is often interlaced (i.e., a render object paints before and after its children), certain operations may need to be implemented differently. If all descendants paint into the same layer, an operation (like clipping) can be performed using a single painting context. If not, some effects can only be achieved by inserting new layers. These bits determine which option will be used when painting.
PipelineOwner.flushPaint paints all dirty render objects (painting dirty children recursively, based on each
PipelineOwner.flushSemantics compiles semantic data for all dirty render objects.
Whenever an object marks itself dirty, it will generally also invoke
PipelineOwner.requestVisualUpdate to schedule a frame and eventually update the user interface. Requesting a visual update invokes the visual update handler that was bound when the
PipelineOwner was constructed by
The default handler invokes
RendererBinding.ensureVisualUpdate which schedules a frame (via
SchedulerBinding.scheduleFrame) if it's not possible to apply the visual update during the current frame (e.g., during post frame callbacks).
When a render object is attached to the
RenderObject.attach), it adds itself to all relevant dirty lists (e.g.,
Typically, a newly created render object will be dirty at this point since most of the dirty bits are initialized to true (e.g.,
RenderObject._needsPaint). Several other bits depend on the configuration of the node (e.g.,
RenderObject._needsCompositing) but will be true if they're applicable.
The render object may also be dirty if it had been previously detached, mutated, and is now being re-attached.
As an exception, the very first painting, layout, and semantics passes are driven by a different flow (via
RenderObject.scheduleInitialSemantics). This flow occurs when the
RenderView is first constructed (via
RendererBinding.initRenderView). This process calls
RenderView.prepareInitialFrame, which schedules initial layout and painting for the
RenderView (semantics follows a slightly different flow). Marking the root node as being dirty causes the entire tree to perform layout, painting, and semantics as needed.
During a hot reload, the renderer invokes
RendererBinding.performReassemble) which cascades down the render tree. By default, render objects mark themselves as being dirty for layout, compositing bits, painting, and semantics (via
The render tree is composed of
RenderObject instances, a subclass of
RenderObject.dropChild must be called whenever a child is added or removed, respectively. Modifying the child model marks the subtree dirty for layout, painting, semantics, and compositing bits.
RenderObject.redepthChild must be called whenever a child's depth changes.
Render objects must be attached to the
RenderObject.attach) and detached when they should no longer be rendered (via
PipelineOwner maintains a reference to a root node (
PipelineOwner.rootNode). This field is set to the application's
RenderView when initializing the
RendererBinding.initRenderView which sets
RendererBinding.renderView and, via a setter,
PipelineOwner.rootNode). This automatically detaches the old render object (if any) and attaches the new one.
Children are automatically attached and detached when they are adopted or dropped.
However, since parents may be attached and detached arbitrarily, render objects are responsible for calling the corresponding method on their children.
Subclasses that introduce a child model (e.g.,
ContainerRenderObjectMixin) must override
RenderObject.redepthChildren to call
RenderObject.redepthChild on each child.
Render objects have a parent (
RenderObject.parent) and an attached state (
RenderObject.attached), indicating whether they'll contribute to rendering.
Parent data may be associated with a child using a
ParentData subclass; this data may only be assigned using
RenderObject.setupParentData. By convention, this data is considered opaque to the child, though a protocol is free to alter this rule (but shouldn’t). The parent data may then be mutated (e.g., via
ContainerRenderObjectMixin uses this field to implement a linked list of children.
RenderObjects implement the visitor pattern via
RenderObject.RenderObject.visitChildren which invokes a
RenderObjectVisitor once per child.
When adding or removing a child, call
RenderObject.detach methods must call their counterpart on each child.
RenderObject.visitChildren methods must recursively call
RenderObject.redepthChild and the visitor argument on each child, respectively.
RenderObjectWithChildMixin stores a single child reference within a render object.
A child setter (
RenderObjectWithChildMixin.child) adopts and drops the child as appropriate (i.e., when adding and removing a child).
Updating the child marks the render object as needing layout and therefore painting.
Attaching, detaching, recomputing depths, and iterating are overridden to incorporate the child.
ContainerRenderObjectMixin uses each child’s parent data (which must implement
ContainerParentDataMixin) to maintain a doubly linked list of children (via
The underlying linked list supports insertions and removals (via
ContainerParentDataMixin._removeFromChildList). Insertions can be positional using an optional preceding child argument.
A variety of container-type methods are exposed (e.g.,
ContainerRenderObjectMixin.remove). These adopt and drop children as needed. A move operation is provided to avoid unnecessarily dropping and re-adopting a child.
Updating (or reordering) the child list marks the render object as needing layout and therefore painting.
These adopt, drop, attach, and detach children appropriately. Additionally, when the child list changes,
RenderObject.markNeedsLayout is invoked (as this may alter layout).
Attaching, detaching, recomputing depths, and iterating are overridden to incorporate all children.
The first child (
ContainerRenderObjectMixin.firstChild), last child (
ContainerRenderObjectMixin.lastChild), and total number of children (
ContainerRenderObjectMixin.childCount) is accessible via the render object.
Render objects mark themselves as needing layout (via
RenderObject.markNeedsLayout); this schedules a layout pass during the next frame.
Layout is performed by
PipelineOwner.flushLayout when the corresponding dirty list is non-empty (
RenderObject.layout is invoked with a
Constraints subclass as input; some subclasses incorporate other out-of-band input, too. The layout method applies input to produce geometry (generally a size, though the type is unconstrained).
If a protocol uses out-of-band input, and this input changes, the affected render objects must be marked dirty (e.g., a parent that uses its child baseline to perform layout must repeat layout whenever the child's baseline changes).
If a parent depends on the child’s layout, it must pass the
parentUsesSize argument to layout.
RenderObjects that solely determine their sizing using the input constraints set
RenderObject.sizedByParent to true and perform all layout in
Layout cannot depend on anything other than the incoming constraints; this includes the render object's position (which is generally determined by the parent render object and stored in
Compositing is the process by which painting (via
RenderObject.paint) is divided into layers (
Layer) before being rasterized and uploaded to the engine. Some render objects share the current layer whereas others introduce one or more new layers.
A repaint boundary corresponds to a render object that always paints into a new
OffsetLayer (stored in
RenderObject.layer). This allows the subtree rooted at this node to paint separately from its parent. Moreover, the offset layer can be re-used (and translated) to avoid unnecessary repainting.
Other render objects that produce new layers can store the root-most layer in
RenderObject.layer to allow future painting operations to update the existing layer rather than creating a new one.
This is possible because
Layer preserves a reference to any underlying
SceneBuilder accepts an
oldLayer argument when building a new scene.
Certain graphical operations are implemented differently depending on whether they're being applied within a single layer or across multiple layers (e.g., clipping).
Render objects often interlace their own painting with their children's painting.
Therefore, to apply these graphical operations correctly, the framework must track which render objects introduce new layers into the scene.
needsCompositing indicates whether the subtree rooted at a render object (e.g., the object and its descendants) may introduce new layers. This indicates to the
PaintingContext that certain operations (e.g., clipping) will need to be implemented differently.
Render objects that always insert layers (e.g., a video) should override
The compositing bits should be marked dirty (via
RenderObject.markNeedsCompositingBitsUpdate) whenever the render tree is mutated; children that are added may introduce layers whereas children that are removed may allow a single layer to be shared.
RenderObject.dropChild always call this method.
All ancestors are marked dirty until reaching a repaint boundary or a node with a repaint boundary parent. In this case, all upstream objects will already have the correct compositing bits (i.e., repaint boundary status cannot change; thus, all upstream compositing bits will have been configured when the render object was added).
Updates are performed by
PipelineOwner.flushCompositingBits when the corresponding dirty list is non-empty (
PipelineOwner._nodesNeedingCompositingBitesUpdate). The update must be applied before painting.
Dirty render objects are sorted from back to front (using
RenderObject.depth) then updated (via
RenderObject._updateCompositingBits). This method performs a depth-first traversal of the render tree, marking each render object as needing compositing if any of its children need compositing (or it's a repaint boundary or always needs compositing).
If the compositing bits are updated, the node is marked as needing repainting, too.
Render objects mark themselves as needing paint (via
RenderObject.markNeedsPaint); this schedules a painting pass during the next frame.
Painting is performed by
PipelineOwner.flushPaint when the corresponding dirty list is non-empty (
Dirty render objects are sorted from back to front (using
RenderObject.depth) then painted (via
PaintingContext.repaintCompositedChild). This requires the render object to have an associated layer (only render objects that are repaint boundaries are added to this list).
If a render object's layer isn't attached (i.e., isn't being composited), painting must wait until it's reattached. The framework iterates through all ancestor render objects to find the nearest repaint boundary with an attached layer (via
RenderObject._skippedPaintingOnLayer). Each is marked dirty to ensure that it's eventually painted.
If necessary, a new
PaintingContext is created for the render object and forwarded to
This method ensures that layout has been performed and, if so, invokes
RenderObject.paint with the provided context.
RenderObject.paintBounds provides an estimate of how large a region this render object will paint (as a
Rect in local coordinates). This doesn't need to match the render object's layout geometry.
RenderObject.applyPaintTransform captures how a render object transforms its children by applying the same transformation to a provided matrix (e.x., if the child is painted at
(x, y), the matrix is translated by
(x, y)). This allows the framework to assemble a sequence of transformations to map between any two render object's coordinate systems (via
RenderObject.getTransformTo). This process allows local coordinates to be mapped to global coordinates and vice versa.
Render objects implement
HitTestTarget and can therefore process incoming pointer events (via
RenderObject.handleEvent). However, render objects do not support hit testing: there is no builtin mechanism for a render object to subscribe to a pointer. This functionality is introduced by
GestureBinding receives pointer events from the engine (via
Window.onPointerDataPacket). These are queued (via
GestureBinding._handlePointerDataPacket), which is flushed immediate (via
GestureBinding._flushPointerEventQueue) or when events are unlocked (via
GestureBinding.unlocked, which is called by the
Events are locked during reassembly and the initial warmup frame.
GestureBinding._handlePointerEvent processes each queued event in sequence using a table of hit test results (
GestureBinding._hitTests) and a pointer router (
The pointer router is a
PointerRouter instance that maps an integral pointer ID to an event handler callback (
PointerRoute, a function that accepts a
PointerEvent). The router also captures a transform matrix to map from screen coordinates to local coordinates.
The hit testing table maps from an integral pointer ID to a record of all successful hits (
HitTestResult). Each entry (
HitTestEntry) records the recipient object (
HitTestTarget) and the transform needed to map from global coordinates to local coordinates (
HitTestTarget is an object that can handle pointer events (via
HitTestTarget.handleEvent). Render objects are hit test targets.
Initiating events (
PointerSignalEvent) trigger a hit test (via
GestureBinding.hitTest). Ongoing events (
PointerMoveEvent) are forwarded to the path associated with the initiating event. Terminating events (
PointerCancelEvent) remove the entry.
Hit test results are stored in the hit test table so that they can be retrieved for subsequent events associated with the same pointer. Hit tests are performed on
HitTestable objects (via
GestureBinding defines a default override that adds itself to the
HitTestResult; invoking this also invokes any overrides mixed into the bindings. The binding processes events to resolve gesture recognizers using the gesture arena (via
RendererBinding provides an override that tests the render view first (via
RenderView.hitTest, called by
RendererBinding). This is the entry point for hit testing in the render tree.
The render view tests its render box child (via
RenderBox.hitTest) before adding itself to the result.
HitTestable but do provide a compatible interface (used by
RenderObject does not participate in hit testing by default.
HitTestable is only used at the binding level. All other hit testing is implementation dependent.
If the hit succeeds, the event is unconditionally forwarded to each
HitTestEntry in the
GestureBinding.dispatchEvent) in depth-first order.
GestureBinding is a
Each entry along the path is mapped to a target which handles the event (via
HitTestTarget.processEvent). As a
HitTestTarget, render objects are eligible to process pointers. However, there is no mechanism for them to participate in hit testing.
Events are also forwarded via the pointer router to support gesture recognition, a more select event handling mechanism.
Visual transforms are implemented in
RenderObject.paint. The same transform is applied logically (i.e., when hit testing, computing semantics, mapping coordinates, etc.) via
RenderObject.applyPaintTransform. This method applies the child transformation to the provided matrix (
providedMatrix * childTransform).
RenderObject.transformTo chains paint transformation matrices mapping from the current coordinate space to an ancestor’s coordinate space.
If an ancestor isn't provided, the transformation will map to global coordinates (i.e., the coordinates of the render object just below the
RenderView; to obtain physical screen coordinates, these coordinates must be further transformed by
RenderView receives a
ViewConfiguration from the platform that specifies the screen's dimensions (
ViewConfiguration.size) and the pixel depth (
RenderView.performLayout adopts this size (
RenderView.size) and, if present, lays out the render box child with tight constraints corresponding to the screen's dimensions (
RenderView.hitTest delegate to the child, if present; the render view always adds itself to the hit test result.
When the configuration is set (via
RenderView.configuration), the layer tree's root is replaced with a
RenderView._updateMatricesAndCreateNewRootLayer) that converts physical pixels to logical pixels. This allows all descendant render objects to be isolated from changes to screen resolution.
RenderView.applyPaintTransform applies the resolution transform (
RenderView._rootTransform) to map from logical global coordinates to physical screen coordinates.
RenderView.compositeFrame implements the final stage of the rendering pipeline, compositing all painted layers and uploading the resulting scene to the engine for rasterization (via
If system UI customization is enabled (
RenderView._updateSystemChrome will query the layer tree to find
SystemUiOverlayStyle instances associated with the very top and very bottom of the screen (this is the mechanism used to determine how to tint system UI like the status bar or Android's bottom navigation bar). If found, the appropriate settings are communicated to the platform (using
SystemChrome platform methods).