Update comments that seem to contradict the code and may confuse the reader

[fzyzcjy]

Original comment:

... So we flatten the layer tree into a picture and use that as the thread transport mechanism.

However, looking at the whole code:

Dart_Handle Picture::RasterizeToImage(sk_sp<DisplayList> display_list,
                                      std::shared_ptr<LayerTree> layer_tree,
                                      uint32_t width,
                                      uint32_t height,
                                      Dart_Handle raw_image_callback) {
  if (Dart_IsNull(raw_image_callback) || !Dart_IsClosure(raw_image_callback)) {
    return tonic::ToDart("Image callback was invalid");
  }

  if (width == 0 || height == 0) {
    return tonic::ToDart("Image dimensions for scene were invalid.");
  }

  auto* dart_state = UIDartState::Current();
  auto image_callback = std::make_unique<tonic::DartPersistentValue>(
      dart_state, raw_image_callback);
  auto unref_queue = dart_state->GetSkiaUnrefQueue();
  auto ui_task_runner = dart_state->GetTaskRunners().GetUITaskRunner();
  auto raster_task_runner = dart_state->GetTaskRunners().GetRasterTaskRunner();
  auto snapshot_delegate = dart_state->GetSnapshotDelegate();

  // We can't create an image on this task runner because we don't have a
  // graphics context. Even if we did, it would be slow anyway. Also, this
  // thread owns the sole reference to the layer tree. So we flatten the layer
  // tree into a picture and use that as the thread transport mechanism.

  auto picture_bounds = SkISize::Make(width, height);

  auto ui_task =
      // The static leak checker gets confused by the use of fml::MakeCopyable.
      // NOLINTNEXTLINE(clang-analyzer-cplusplus.NewDeleteLeaks)
      fml::MakeCopyable([image_callback = std::move(image_callback),
                         unref_queue](sk_sp<DlImage> image) mutable {
        auto dart_state = image_callback->dart_state().lock();
        if (!dart_state) {
          // The root isolate could have died in the meantime.
          return;
        }
        tonic::DartState::Scope scope(dart_state);

        if (!image) {
          tonic::DartInvoke(image_callback->Get(), {Dart_Null()});
          return;
        }

        if (image->skia_image()) {
          image =
              DlImageGPU::Make({image->skia_image(), std::move(unref_queue)});
        }

        auto dart_image = CanvasImage::Create();
        dart_image->set_image(image);
        auto* raw_dart_image = tonic::ToDart(std::move(dart_image));

        // All done!
        tonic::DartInvoke(image_callback->Get(), {raw_dart_image});

        // image_callback is associated with the Dart isolate and must be
        // deleted on the UI thread.
        image_callback.reset();
      });

  // Kick things off on the raster rask runner.
  fml::TaskRunner::RunNowOrPostTask(
      raster_task_runner,
      [ui_task_runner, snapshot_delegate, display_list, picture_bounds, ui_task,
       layer_tree = std::move(layer_tree)] {
        sk_sp<DlImage> image;
        if (layer_tree) {
          auto display_list = layer_tree->Flatten(
              SkRect::MakeWH(picture_bounds.width(), picture_bounds.height()),
              snapshot_delegate->GetTextureRegistry(),
              snapshot_delegate->GetGrContext());

          image = snapshot_delegate->MakeRasterSnapshot(display_list,
                                                        picture_bounds);
        } else {
          image = snapshot_delegate->MakeRasterSnapshot(display_list,
                                                        picture_bounds);
        }

        fml::TaskRunner::RunNowOrPostTask(
            ui_task_runner, [ui_task, image]() { ui_task(image); });
      });

  return Dart_Null();
}

It seems that, the layer_tree is directly moved into raster_task_runner callbacks. Then, inside the raster thread, layer_tree->Flatten is called and it is converted to a DisplayList. In other words, the "thread transport mechanism" seems to be the layer_tree (ui -> raster thread) and DlImage (raster -> ui thread), instead of the "flatten the layer tree into a picture and use that" (the flattened layer tree, i.e. the picture).

List which issues are fixed by this PR. You must list at least one issue.

If you had to change anything in the flutter/tests repo, include a link to the migration guide as per the breaking change policy.

Pre-launch Checklist

• [x] I read the Contributor Guide and followed the process outlined there for submitting PRs.
• [x] I read the Tree Hygiene wiki page, which explains my responsibilities.
• [x] I read and followed the Flutter Style Guide and the C++, Objective-C, Java style guides.
• [ ] I listed at least one issue that this PR fixes in the description above.
• [x] I added new tests to check the change I am making or feature I am adding, or Hixie said the PR is test-exempt. See testing the engine for instructions on writing and running engine tests.
• [x] I updated/added relevant documentation (doc comments with ///).
• [x] I signed the CLA.
• [ ] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

[flutter-dashboard[bot]]

It looks like this pull request may not have tests. Please make sure to add tests before merging. If you need an exemption to this rule, contact Hixie on the #hackers channel in Chat (don't just cc him here, he won't see it! He's on Discord!).

If you are not sure if you need tests, consider this rule of thumb: the purpose of a test is to make sure someone doesn't accidentally revert the fix. Ask yourself, is there anything in your PR that you feel it is important we not accidentally revert back to how it was before your fix?

Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing.

[fzyzcjy]

This only updates comments so seems no need for tests

[fzyzcjy]

This is an artifact of what the code used to do, but it has since been refactored to not do that :)

I guess so :) That is why I update it - otherwise it will mislead future readers