Skip to content
This repository was archived by the owner on Feb 25, 2025. It is now read-only.

Commit 1f18f24

Browse files
committed
Various documentation improvements
1 parent 017de24 commit 1f18f24

File tree

3 files changed

+53
-13
lines changed

3 files changed

+53
-13
lines changed

lib/ui/compositing.dart

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -367,6 +367,10 @@ abstract class SceneBuilder {
367367
/// The given color is applied to the objects' rasterization using the given
368368
/// blend mode.
369369
///
370+
/// This method is a strict subset of [pushImageFilter] (because [ColorFilter]
371+
/// implements [ImageFilter]); it is always correct to use [pushImageFilter]
372+
/// where one might have used [pushColorFilter].
373+
///
370374
/// {@macro dart.ui.sceneBuilder.oldLayer}
371375
///
372376
/// {@macro dart.ui.sceneBuilder.oldLayerVsRetained}
@@ -379,8 +383,8 @@ abstract class SceneBuilder {
379383

380384
/// Pushes an image filter operation onto the operation stack.
381385
///
382-
/// The given filter is applied to the children's rasterization before compositing them into
383-
/// the scene.
386+
/// The given filter is applied to the children's rasterization before
387+
/// compositing them into the scene.
384388
///
385389
/// {@macro dart.ui.sceneBuilder.oldLayer}
386390
///

lib/ui/geometry.dart

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@
44

55
part of dart.ui;
66

7+
// Examples can assume:
8+
// RSTransfrom rst;
9+
710
/// Base class for [Size] and [Offset], which are both ways to describe
811
/// a distance as a two-dimensional axis-aligned vector.
912
abstract class OffsetBase {
@@ -1749,6 +1752,17 @@ class RRect {
17491752
///
17501753
/// Used by [Canvas.drawAtlas]. This is a more efficient way to represent these
17511754
/// simple transformations than a full matrix.
1755+
///
1756+
/// It is equivalent to a [Matrix4] built using the following parameters (where
1757+
/// `rst` is the corresponding `RSTransform` instance):
1758+
///
1759+
/// ```dart
1760+
/// // Matrix4's constructor arguments are in column-major order.
1761+
/// Matrix4(rst.scos, rst.ssin, 0, 0,
1762+
/// -rst.ssin, rst.scos, 0, 0,
1763+
/// 0, 0, 1, 0,
1764+
/// rst.tx, rst.ty, 0, 1);
1765+
/// ```
17521766
// Modeled after Skia's SkRSXform.
17531767
class RSTransform {
17541768
/// Creates an RSTransform.

lib/ui/painting.dart

Lines changed: 33 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5366,12 +5366,22 @@ abstract class Canvas {
53665366
void drawPath(Path path, Paint paint);
53675367

53685368
/// Draws the given [Image] into the canvas with its top-left corner at the
5369-
/// given [Offset]. The image is composited into the canvas using the given [Paint].
5369+
/// given [Offset].
5370+
///
5371+
/// The image is composited into the canvas using the given [Paint], by
5372+
/// applying the [Paint.color] (alpha channel only), [Paint.blendMode],
5373+
/// [Paint.colorFilter], [Paint.maskFilter], and [Paint.imageFilter]
5374+
/// properties of the `paint` argument (in that order).
53705375
void drawImage(Image image, Offset offset, Paint paint);
53715376

53725377
/// Draws the subset of the given image described by the `src` argument into
53735378
/// the canvas in the axis-aligned rectangle given by the `dst` argument.
53745379
///
5380+
/// The image is composited into the canvas using the given [Paint], by
5381+
/// applying the [Paint.color] (alpha channel only), [Paint.blendMode],
5382+
/// [Paint.colorFilter], [Paint.maskFilter], and [Paint.imageFilter]
5383+
/// properties of the `paint` argument (in that order).
5384+
///
53755385
/// This might sample from outside the `src` rect by up to half the width of
53765386
/// an applied filter.
53775387
///
@@ -5380,7 +5390,7 @@ abstract class Canvas {
53805390
/// performance.
53815391
void drawImageRect(Image image, Rect src, Rect dst, Paint paint);
53825392

5383-
/// Draws the given [Image] into the canvas using the given [Paint].
5393+
/// Draws the given [Image] into the canvas as a nine-patch image.
53845394
///
53855395
/// The image is drawn in nine portions described by splitting the image by
53865396
/// drawing two horizontal lines and two vertical lines, where the `center`
@@ -5393,6 +5403,15 @@ abstract class Canvas {
53935403
/// five regions are drawn by stretching them to fit such that they exactly
53945404
/// cover the destination rectangle while maintaining their relative
53955405
/// positions.
5406+
///
5407+
/// The image is composited into the canvas using the given [Paint], by
5408+
/// applying the [Paint.color] (alpha channel only), [Paint.blendMode],
5409+
/// [Paint.colorFilter], [Paint.maskFilter], and [Paint.imageFilter]
5410+
/// properties of the `paint` argument (in that order).
5411+
///
5412+
/// See also:
5413+
///
5414+
/// * <https://en.wikipedia.org/wiki/9-slice_scaling>
53965415
void drawImageNine(Image image, Rect center, Rect dst, Paint paint);
53975416

53985417
/// Draw the given picture onto the canvas. To create a picture, see
@@ -5499,15 +5518,18 @@ abstract class Canvas {
54995518
/// [blendMode] argument (if a color is specified). In this part of the operation,
55005519
/// the image part will be considered the source of the operation and the associated
55015520
/// color will be considered the destination.
5502-
/// - Blend the result from the first step onto the canvas using the translation,
5503-
/// rotation, and scale properties expressed in the associated entry in the
5504-
/// [transforms] list using the properties of the [Paint] object.
5505-
///
5506-
/// If the first stage of the operation which blends each part of the image with
5507-
/// a color is needed, then both the [colors] and [blendMode] arguments must
5508-
/// not be null and there must be an entry in the [colors] list for each
5509-
/// image part. If that stage is not needed, then the [colors] argument can
5510-
/// be either null or an empty list and the [blendMode] argument may also be null.
5521+
///
5522+
/// - Blend the result from the first step onto the canvas using the
5523+
/// translation, rotation, and scale properties expressed in the associated
5524+
/// entry in the [transforms] list, and the [Paint.color] (alpha channel
5525+
/// only), [Paint.blendMode], [Paint.colorFilter], [Paint.maskFilter], and
5526+
/// [Paint.imageFilter] properties of the `paint` argument (in that order).
5527+
///
5528+
/// If the first stage of the operation which blends each part of the image
5529+
/// with a color is needed, then both the [colors] and [blendMode] arguments
5530+
/// must not be null and there must be an entry in the [colors] list for each
5531+
/// image part. If the [colors] argument is null or empty, or if the
5532+
/// [blendMode] argument is null, then this stage is skipped.
55115533
///
55125534
/// The optional [cullRect] argument can provide an estimate of the bounds of the
55135535
/// coordinates rendered by all components of the atlas to be compared against

0 commit comments

Comments
 (0)