Repository: flutter
Issue: Confusion about RenderObject getTransformTo()
Labels: framework,d: api docs,P2,team-framework,triaged-framework

I'm looking at the implementation of `getTransformTo()` and I'm wondering whether the documentation is wrong, or if I'm misunderstanding part of it.

Here's the implementation:

```dart
  /// {@template flutter.rendering.RenderObject.getTransformTo}
  /// Applies the paint transform up the tree to `ancestor`.
  ///
  /// Returns a matrix that maps the local paint coordinate system to the
  /// coordinate system of `ancestor`.
  ///
  /// If `ancestor` is null, this method returns a matrix that maps from the
  /// local paint coordinate system to the coordinate system of the
  /// [PipelineOwner.rootNode].
  /// {@endtemplate}
  ///
  /// For the render tree owned by the [RendererBinding] (i.e. for the main
  /// render tree displayed on the device) this means that this method maps to
  /// the global coordinate system in logical pixels. To get physical pixels,
  /// use [applyPaintTransform] from the [RenderView] to further transform the
  /// coordinate.
  Matrix4 getTransformTo(RenderObject? ancestor) {
    final bool ancestorSpecified = ancestor != null;
    assert(attached);
    if (ancestor == null) {
      final AbstractNode? rootNode = owner!.rootNode;
      if (rootNode is RenderObject) {
        ancestor = rootNode;
      }
    }
    final List<RenderObject> renderers = <RenderObject>[];
    for (RenderObject renderer = this; renderer != ancestor; renderer = renderer.parent! as RenderObject) {
      renderers.add(renderer);
      assert(renderer.parent != null); // Failed to find ancestor in parent chain.
    }
    if (ancestorSpecified) {
      renderers.add(ancestor!);
    }
    final Matrix4 transform = Matrix4.identity();
    for (int index = renderers.length - 1; index > 0; index -= 1) {
      renderers[index].applyPaintTransform(renderers[index - 1], transform);
    }
    return transform;
  }
```

Notice in the documentation it says:
```dart
/// Applies the paint transform up the tree to `ancestor`.
```

But is this true? Let's look at the transform loop:

```dart
    final Matrix4 transform = Matrix4.identity();
    for (int index = renderers.length - 1; index > 0; index -= 1) {
      renderers[index].applyPaintTransform(renderers[index - 1], transform);
    }
    return transform;
```

The loop iterates from the end of the render object list to the beginning. And the list is ordered from deepest to most shallow render object, e.g., `[child3, child2, child1, root]`.

Therefore, the `applyPaintTransform()` is called like:

 1. root `applyPaintTransform` to child1
 2. child1 `applyPaintTransform` to child2
 3. child2 `applyPaintTransform` to child3

Doesn't that produce a transform that goes from ancestor down to descendant, NOT from descendent up to ancestor?

Lastly, is appropriate to say in the documentation that this method "applies the paint transform"? What are we "applying" it to? It seems more appropriate to me to say that this method "assembles a transform that maps a point in ancestor space to a point in the current render object's space". Or, if the existing documentation is truly accurate, then we might say "assembles a transform that maps a point in this render object's space to the given ancestor's space".