Document the new binding hooks for SceneBuilder, PictureRecorder, Can…

…vas (flutter#52374)

See flutter/flutter#147271 for context.

Do not land until flutter/flutter#147271 has landed.

lib/ui/compositing.dart

@@ -233,6 +233,18 @@ class ShaderMaskEngineLayer extends _EngineLayerWrapper {
 /// To draw graphical operations onto a [Scene], first create a
 /// [Picture] using a [PictureRecorder] and a [Canvas], and then add
 /// it to the scene using [addPicture].
+///
+/// ## Use with the Flutter framework
+///
+/// The Flutter framework's [RendererBinding] provides a hook for creating
+/// [SceneBuilder] objects ([RendererBinding.createSceneBuilder]) that allows
+/// tests to hook into the scene creation logic. When creating a [SceneBuilder]
+/// in the context of the Flutter framework, consider calling
+/// [RendererBinding.createSceneBuilder] instead of calling the
+/// [SceneBuilder.new] constructor directly.
+///
+/// This does not apply when using the `dart:ui` API directly, without using the
+/// Flutter framework bindings, `flutter_test` framework, et al.
 abstract class SceneBuilder {
   factory SceneBuilder() = _NativeSceneBuilder;
 

lib/ui/painting.dart

@@ -4964,6 +4964,18 @@ enum ClipOp {
 ///
 /// The current transform and clip can be saved and restored using the stack
 /// managed by the [save], [saveLayer], and [restore] methods.
+///
+/// ## Use with the Flutter framework
+///
+/// The Flutter framework's [RendererBinding] provides a hook for creating
+/// [Canvas] objects ([RendererBinding.createCanvas]) that allows tests to hook
+/// into the scene creation logic. When creating a [Canvas] that will be used
+/// with a [PictureLayer] as part of the [Scene] in the context of the Flutter
+/// framework, consider calling [RendererBinding.createCanvas] instead of
+/// calling the [Canvas.new] constructor directly.
+///
+/// This does not apply when using a canvas to generate a bitmap for other
+/// purposes, e.g. for generating a PNG image using [Picture.toImage].
 abstract class Canvas {
   /// Creates a canvas for recording graphical operations into the
   /// given picture recorder.
@@ -6415,6 +6427,19 @@ base class _NativePicture extends NativeFieldWrapperClass1 implements Picture {
 ///
 /// To begin recording, construct a [Canvas] to record the commands.
 /// To end recording, use the [PictureRecorder.endRecording] method.
+///
+/// ## Use with the Flutter framework
+///
+/// The Flutter framework's [RendererBinding] provides a hook for creating
+/// [PictureRecorder] objects ([RendererBinding.createPictureRecorder]) that
+/// allows tests to hook into the scene creation logic. When creating a
+/// [PictureRecorder] and [Canvas] that will be used with a [PictureLayer] as
+/// part of the [Scene] in the context of the Flutter framework, consider
+/// calling [RendererBinding.createPictureRecorder] instead of calling the
+/// [PictureRecorder.new] constructor directly.
+///
+/// This does not apply when using a canvas to generate a bitmap for other
+/// purposes, e.g. for generating a PNG image using [Picture.toImage].
 abstract class PictureRecorder {
   /// Creates a new idle PictureRecorder. To associate it with a
   /// [Canvas] and begin recording, pass this [PictureRecorder] to the