Add more documentation around layers. (#45648)

packages/flutter/lib/src/rendering/binding.dart

@@ -182,11 +182,12 @@ mixin RendererBinding on BindingBase, ServicesBinding, SchedulerBinding, Gesture
   @protected
   void handleTextScaleFactorChanged() { }
 
-  /// {@template on_platform_brightness_change}
   /// Called when the platform brightness changes.
   ///
-  /// The current platform brightness can be queried either from a Flutter
-  /// binding, or from a [MediaQuery] widget.
+  /// The current platform brightness can be queried from a Flutter binding or
+  /// from a [MediaQuery] widget. The latter is preferred from widgets because
+  /// it causes the widget to be automatically rebuilt when the brightness
+  /// changes.
   ///
   /// {@tool sample}
   /// Querying [Window.platformBrightness].
@@ -197,7 +198,7 @@ mixin RendererBinding on BindingBase, ServicesBinding, SchedulerBinding, Gesture
   /// {@end-tool}
   ///
   /// {@tool sample}
-  /// Querying [MediaQuery] directly.
+  /// Querying [MediaQuery] directly. Preferred.
   ///
   /// ```dart
   /// final Brightness brightness = MediaQuery.platformBrightnessOf(context);
@@ -214,7 +215,6 @@ mixin RendererBinding on BindingBase, ServicesBinding, SchedulerBinding, Gesture
   /// {@end-tool}
   ///
   /// See [Window.onPlatformBrightnessChanged].
-  /// {@endtemplate}
   @protected
   void handlePlatformBrightnessChanged() { }
 

packages/flutter/lib/src/rendering/layer.dart

@@ -1673,6 +1673,11 @@ class OpacityLayer extends ContainerLayer {
 }
 
 /// A composited layer that applies a shader to its children.
+///
+/// The shader is only applied inside the given [maskRect]. The shader itself
+/// uses the top left of the [maskRect] as its origin.
+///
+/// The [maskRect] does not affect the positions of any child layers.
 class ShaderMaskLayer extends ContainerLayer {
   /// Creates a shader mask layer.
   ///
@@ -1688,8 +1693,16 @@ class ShaderMaskLayer extends ContainerLayer {
 
   /// The shader to apply to the children.
   ///
+  /// The origin of the shader (e.g. of the coordinate system used by the `from`
+  /// and `to` arguments to [ui.Gradient.linear]) is at the top left of the
+  /// [maskRect].
+  ///
   /// The scene must be explicitly recomposited after this property is changed
   /// (as described at [Layer]).
+  ///
+  /// See also:
+  ///
+  ///  * [ui.Gradient] and [ui.ImageShader], two shader types that can be used.
   Shader get shader => _shader;
   Shader _shader;
   set shader(Shader value) {
@@ -1699,7 +1712,10 @@ class ShaderMaskLayer extends ContainerLayer {
     }
   }
 
-  /// The size of the shader.
+  /// The position and size of the shader.
+  ///
+  /// The [shader] is only rendered inside this rectangle, using the top left of
+  /// the rectangle as its origin.
   ///
   /// The scene must be explicitly recomposited after this property is changed
   /// (as described at [Layer]).
@@ -1730,6 +1746,7 @@ class ShaderMaskLayer extends ContainerLayer {
     assert(shader != null);
     assert(maskRect != null);
     assert(blendMode != null);
+    assert(layerOffset != null);
     final Rect shiftedMaskRect = layerOffset == Offset.zero ? maskRect : maskRect.shift(layerOffset);
     engineLayer = builder.pushShaderMask(shader, shiftedMaskRect, blendMode, oldLayer: _engineLayer);
     addChildrenToScene(builder, layerOffset);

packages/flutter/lib/src/rendering/object.dart

@@ -344,8 +344,8 @@ class PaintingContext extends ClipContext {
   ///
   /// See also:
   ///
-  ///  * [pushLayer], for adding a layer and using its canvas to paint with that
-  ///    layer.
+  ///  * [pushLayer], for adding a layer and painting further contents within
+  ///    it.
   void addLayer(Layer layer) {
     stopRecordingIfNeeded();
     appendLayer(layer);
@@ -360,17 +360,24 @@ class PaintingContext extends ClipContext {
   /// object, rather than reusing an existing layer, satisfies that
   /// requirement.)
   ///
-  /// The `offset` is the offset to pass to the `painter`.
+  /// {@template flutter.rendering.object.pushLayer.offset}
+  /// The `offset` is the offset to pass to the `painter`. In particular, it is
+  /// not an offset applied to the layer itself. Layers conceptually by default
+  /// have no position or size, though they can transform their contents. For
+  /// example, an [OffsetLayer] applies an offset to its children.
+  /// {@endtemplate}
   ///
   /// If the `childPaintBounds` are not specified then the current layer's paint
   /// bounds are used. This is appropriate if the child layer does not apply any
   /// transformation or clipping to its contents. The `childPaintBounds`, if
-  /// specified, must be in the coordinate system of the new layer, and should
-  /// not go outside the current layer's paint bounds.
+  /// specified, must be in the coordinate system of the new layer (i.e. as seen
+  /// by its children after it applies whatever transform to its contents), and
+  /// should not go outside the current layer's paint bounds.
   ///
   /// See also:
   ///
-  ///  * [addLayer], for pushing a leaf layer whose canvas is not used.
+  ///  * [addLayer], for pushing a layer without painting further contents
+  ///    within it.
   void pushLayer(ContainerLayer childLayer, PaintingContextCallback painter, Offset offset, { Rect childPaintBounds }) {
     assert(painter != null);
     // If a layer is being reused, it may already contain children. We remove
@@ -385,7 +392,9 @@ class PaintingContext extends ClipContext {
     childContext.stopRecordingIfNeeded();
   }
 
-  /// Creates a compatible painting context to paint onto [childLayer].
+  /// Creates a painting context configured to paint into [childLayer].
+  ///
+  /// The `bounds` are estimated paint bounds for debugging purposes.
   @protected
   PaintingContext createChildContext(ContainerLayer childLayer, Rect bounds) {
     return PaintingContext(childLayer, bounds);
@@ -394,28 +403,40 @@ class PaintingContext extends ClipContext {
   /// Clip further painting using a rectangle.
   ///
   /// {@template flutter.rendering.object.needsCompositing}
-  /// * `needsCompositing` is whether the child needs compositing. Typically
-  ///   matches the value of [RenderObject.needsCompositing] for the caller. If
-  ///   false, this method returns null, indicating that a layer is no longer
-  ///   necessary. If a render object calling this method stores the `oldLayer`
-  ///   in its [RenderObject.layer] field, it should set that field to null.
-  /// {@end template}
-  /// * `offset` is the offset from the origin of the canvas' coordinate system
-  ///   to the origin of the caller's coordinate system.
-  /// * `clipRect` is rectangle (in the caller's coordinate system) to use to
-  ///   clip the painting done by [painter].
-  /// * `painter` is a callback that will paint with the [clipRect] applied. This
-  ///   function calls the [painter] synchronously.
-  /// * `clipBehavior` controls how the rectangle is clipped.
+  /// The `needsCompositing` argument specifies whether the child needs
+  /// compositing. Typically this matches the value of
+  /// [RenderObject.needsCompositing] for the caller. If false, this method
+  /// returns null, indicating that a layer is no longer necessary. If a render
+  /// object calling this method stores the `oldLayer` in its
+  /// [RenderObject.layer] field, it should set that field to null.
+  ///
+  /// When `needsCompositing` is false, this method will use a more efficient
+  /// way to apply the layer effect than actually creating a layer.
+  /// {@endtemplate}
+  ///
+  /// {@template flutter.rendering.object.pushClipLayer.offset}
+  /// The `offset` argument is the offset from the origin of the canvas'
+  /// coordinate system to the origin of the caller's coordinate system.
+  /// {@endtemplate}
+  ///
+  /// The `clipRect` is the rectangle (in the caller's coordinate system) to use
+  /// to clip the painting done by [painter]. It should not include the
+  /// `offset`.
+  ///
+  /// The `painter` callback will be called while the `clipRect` is applied. It
+  /// is called synchronously during the call to [pushClipRect].
+  ///
+  /// The `clipBehavior` argument controls how the rectangle is clipped.
+  ///
   /// {@template flutter.rendering.object.oldLayer}
-  /// * `oldLayer` is the layer created in the previous frame. Specifying the
-  ///   old layer gives the engine more information for performance
-  ///   optimizations. Typically this is the value of [RenderObject.layer] that
-  ///   a render object creates once, then reuses for all subsequent frames
-  ///   until a layer is no longer needed (e.g. the render object no longer
-  ///   needs compositing) or until the render object changes the type of the
-  ///   layer (e.g. from opacity layer to a clip rect layer).
-  /// {@end template}
+  /// For the `oldLayer` argument, specify the layer created in the previous
+  /// frame. This gives the engine more information for performance
+  /// optimizations. Typically this is the value of [RenderObject.layer] that a
+  /// render object creates once, then reuses for all subsequent frames until a
+  /// layer is no longer needed (e.g. the render object no longer needs
+  /// compositing) or until the render object changes the type of the layer
+  /// (e.g. from opacity layer to a clip rect layer).
+  /// {@endtemplate}
   ClipRectLayer pushClipRect(bool needsCompositing, Offset offset, Rect clipRect, PaintingContextCallback painter, { Clip clipBehavior = Clip.hardEdge, ClipRectLayer oldLayer }) {
     final Rect offsetClipRect = clipRect.shift(offset);
     if (needsCompositing) {
@@ -434,15 +455,21 @@ class PaintingContext extends ClipContext {
   /// Clip further painting using a rounded rectangle.
   ///
   /// {@macro flutter.rendering.object.needsCompositing}
-  /// * `offset` is the offset from the origin of the canvas' coordinate system
-  ///   to the origin of the caller's coordinate system.
-  /// * `bounds` is the region of the canvas (in the caller's coordinate system)
-  ///   into which `painter` will paint in.
-  /// * `clipRRect` is the rounded-rectangle (in the caller's coordinate system)
-  ///   to use to clip the painting done by `painter`.
-  /// * `painter` is a callback that will paint with the `clipRRect` applied. This
-  ///   function calls the `painter` synchronously.
-  /// * `clipBehavior` controls how the path is clipped.
+  ///
+  /// {@macro flutter.rendering.object.pushClipLayer.offset}
+  ///
+  /// The `bounds` argument is used to specify the region of the canvas (in the
+  /// caller's coordinate system) into which `painter` will paint.
+  ///
+  /// The `clipRRect` argument specifies the rounded-rectangle (in the caller's
+  /// coordinate system) to use to clip the painting done by `painter`. It
+  /// should not include the `offset`.
+  ///
+  /// The `painter` callback will be called while the `clipRRect` is applied. It
+  /// is called synchronously during the call to [pushClipRRect].
+  ///
+  /// The `clipBehavior` argument controls how the rounded rectangle is clipped.
+  ///
   /// {@macro flutter.rendering.object.oldLayer}
   ClipRRectLayer pushClipRRect(bool needsCompositing, Offset offset, Rect bounds, RRect clipRRect, PaintingContextCallback painter, { Clip clipBehavior = Clip.antiAlias, ClipRRectLayer oldLayer }) {
     assert(clipBehavior != null);
@@ -464,15 +491,21 @@ class PaintingContext extends ClipContext {
   /// Clip further painting using a path.
   ///
   /// {@macro flutter.rendering.object.needsCompositing}
-  /// * `offset` is the offset from the origin of the canvas' coordinate system
-  ///   to the origin of the caller's coordinate system.
-  /// * `bounds` is the region of the canvas (in the caller's coordinate system)
-  ///   into which `painter` will paint in.
-  /// * `clipPath` is the path (in the coordinate system of the caller) to use to
-  ///   clip the painting done by `painter`.
-  /// * `painter` is a callback that will paint with the `clipPath` applied. This
-  ///   function calls the `painter` synchronously.
-  /// * `clipBehavior` controls how the rounded rectangle is clipped.
+  ///
+  /// {@macro flutter.rendering.object.pushClipLayer.offset}
+  ///
+  /// The `bounds` argument is used to specify the region of the canvas (in the
+  /// caller's coordinate system) into which `painter` will paint.
+  ///
+  /// The `clipPath` argument specifies the [Path] (in the caller's coordinate
+  /// system) to use to clip the painting done by `painter`. It should not
+  /// include the `offset`.
+  ///
+  /// The `painter` callback will be called while the `clipPath` is applied. It
+  /// is called synchronously during the call to [pushClipPath].
+  ///
+  /// The `clipBehavior` argument controls how the path is clipped.
+  ///
   /// {@macro flutter.rendering.object.oldLayer}
   ClipPathLayer pushClipPath(bool needsCompositing, Offset offset, Rect bounds, Path clipPath, PaintingContextCallback painter, { Clip clipBehavior = Clip.antiAlias, ClipPathLayer oldLayer }) {
     assert(clipBehavior != null);
@@ -493,12 +526,14 @@ class PaintingContext extends ClipContext {
 
   /// Blend further painting with a color filter.
   ///
-  /// * `offset` is the offset from the origin of the canvas' coordinate system
-  ///   to the origin of the caller's coordinate system.
-  /// * `colorFilter` is the [ColorFilter] value to use when blending the
-  ///   painting done by `painter`.
-  /// * `painter` is a callback that will paint with the `colorFilter` applied.
-  ///   This function calls the `painter` synchronously.
+  /// {@macro flutter.rendering.object.pushLayer.offset}
+  ///
+  /// The `colorFilter` argument is the [ColorFilter] value to use when blending
+  /// the painting done by `painter`.
+  ///
+  /// The `painter` callback will be called while the `colorFilter` is applied.
+  /// It is called synchronously during the call to [pushColorFilter].
+  ///
   /// {@macro flutter.rendering.object.oldLayer}
   ///
   /// A [RenderObject] that uses this function is very likely to require its
@@ -516,11 +551,17 @@ class PaintingContext extends ClipContext {
   /// Transform further painting using a matrix.
   ///
   /// {@macro flutter.rendering.object.needsCompositing}
-  /// * `offset` is the offset from the origin of the canvas' coordinate system
-  ///   to the origin of the caller's coordinate system.
-  /// * `transform` is the matrix to apply to the painting done by `painter`.
-  /// * `painter` is a callback that will paint with the `transform` applied. This
-  ///   function calls the `painter` synchronously.
+  ///
+  /// The `offset` argument is the offset to pass to `painter` and the offset to
+  /// the origin used by `transform`.
+  ///
+  /// The `transform` argument is the [Matrix4] with which to transform the
+  /// coordinate system while calling `painter`. It should not include `offset`.
+  /// It is applied effectively after applying `offset`.
+  ///
+  /// The `painter` callback will be called while the `transform` is applied. It
+  /// is called synchronously during the call to [pushTransform].
+  ///
   /// {@macro flutter.rendering.object.oldLayer}
   TransformLayer pushTransform(bool needsCompositing, Offset offset, Matrix4 transform, PaintingContextCallback painter, { TransformLayer oldLayer }) {
     final Matrix4 effectiveTransform = Matrix4.translationValues(offset.dx, offset.dy, 0.0)
@@ -548,13 +589,16 @@ class PaintingContext extends ClipContext {
 
   /// Blend further painting with an alpha value.
   ///
-  /// * `offset` is the offset from the origin of the canvas' coordinate system
-  ///   to the origin of the caller's coordinate system.
-  /// * `alpha` is the alpha value to use when blending the painting done by
-  ///   `painter`. An alpha value of 0 means the painting is fully transparent
-  ///   and an alpha value of 255 means the painting is fully opaque.
-  /// * `painter` is a callback that will paint with the `alpha` applied. This
-  ///   function calls the `painter` synchronously.
+  /// The `offset` argument indicates an offset to apply to all the children
+  /// (the rendering created by `painter`).
+  ///
+  /// The `alpha` argument is the alpha value to use when blending the painting
+  /// done by `painter`. An alpha value of 0 means the painting is fully
+  /// transparent and an alpha value of 255 means the painting is fully opaque.
+  ///
+  /// The `painter` callback will be called while the `alpha` is applied. It
+  /// is called synchronously during the call to [pushOpacity].
+  ///
   /// {@macro flutter.rendering.object.oldLayer}
   ///
   /// A [RenderObject] that uses this function is very likely to require its

packages/flutter/lib/src/rendering/proxy_box.dart

@@ -968,6 +968,9 @@ class RenderShaderMask extends RenderProxyBox {
   ///
   /// The shader callback is called with the current size of the child so that
   /// it can customize the shader to the size and location of the child.
+  ///
+  /// The rectangle will always be at the origin when called by
+  /// [RenderShaderMask].
   // TODO(abarth): Use the delegate pattern here to avoid generating spurious
   // repaints when the ShaderCallback changes identity.
   ShaderCallback get shaderCallback => _shaderCallback;

packages/flutter/lib/src/widgets/binding.dart

@@ -214,7 +214,9 @@ abstract class WidgetsBindingObserver {
   ///    boilerplate.
   void didChangeTextScaleFactor() { }
 
-  /// {@macro on_platform_brightness_change}
+  /// Called when the platform brightness changes.
+  ///
+  /// This method exposes notifications from [Window.onPlatformBrightnessChanged].
   void didChangePlatformBrightness() { }
 
   /// Called when the system tells the app that the user's locale has