#include <rasterizer.h>

Inheritance diagram for flutter::Rasterizer:

Classes
class	Delegate
	Used to forward events from the rasterizer to interested subsystems. Currently, the shell sets itself up as the rasterizer delegate to listen for frame rasterization events. It can then forward these events to the engine. More...

struct	Screenshot
	A POD type used to return the screenshot data along with the size of the frame. More...

Public Types
enum class	MakeGpuImageBehavior { kGpu , kBitmap }
	How to handle calls to MakeSkiaGpuImage. More...

enum class	ScreenshotType { SkiaPicture , UncompressedImage , CompressedImage , SurfaceData }
	The type of the screenshot to obtain of the previously rendered layer tree. More...

enum class	ScreenshotFormat { kUnknown , kR8G8B8A8UNormInt , kB8G8R8A8UNormInt , kR16G16B16A16Float }

Public Member Functions
	Rasterizer (Delegate &delegate, MakeGpuImageBehavior gpu_image_behavior=MakeGpuImageBehavior::kGpu)
	Creates a new instance of a rasterizer. Rasterizers may only be created on the raster task runner. Rasterizers are currently only created by the shell (which also sets itself up as the rasterizer delegate).

	~Rasterizer ()
	Destroys the rasterizer. This must happen on the raster task runner. All GPU resources are collected before this call returns. Any context set up by the embedder to hold these resources can be immediately collected as well.

void	SetImpellerContext (std::shared_ptr< impeller::ImpellerContextFuture > impeller_context)

void	Setup (std::unique_ptr< Surface > surface)
	Rasterizers may be created well before an on-screen surface is available for rendering. Shells usually create a rasterizer in their constructors. Once an on-screen surface is available however, one may be provided to the rasterizer using this call. No rendering may occur before this call. The surface is held till the balancing call to `Rasterizer::Teardown` is made. Calling a setup before tearing down the previous surface (if this is not the first time the surface has been set up) is user error.

void	Teardown ()
	Releases the previously set up on-screen render surface and collects associated resources. No more rendering may occur till the next call to `Rasterizer::Setup` with a new render surface. Calling a teardown without a setup is user error. Calling this method multiple times is safe.

void	TeardownExternalViewEmbedder ()
	Releases any resource used by the external view embedder. For example, overlay surfaces or Android views. On Android, this method post a task to the platform thread, and waits until it completes.

void	NotifyLowMemoryWarning () const
	Notifies the rasterizer that there is a low memory situation and it must purge as many unnecessary resources as possible. Currently, the Skia context associated with onscreen rendering is told to free GPU resources.

fml::TaskRunnerAffineWeakPtr< Rasterizer >	GetWeakPtr () const
	Gets a weak pointer to the rasterizer. The rasterizer may only be accessed on the raster task runner.

fml::TaskRunnerAffineWeakPtr< SnapshotDelegate >	GetSnapshotDelegate () const

void	CollectView (int64_t view_id)
	Deallocate the resources for displaying a view.

flutter::LayerTree *	GetLastLayerTree (int64_t view_id)
	Returns the last successfully drawn layer tree for the given view, or nullptr if there isn't any. This is useful during `DrawLastLayerTrees` and computing frame damage.

void	DrawLastLayerTrees (std::unique_ptr< FrameTimingsRecorder > frame_timings_recorder)
	Draws the last layer trees with their last configuration. This may seem entirely redundant at first glance. After all, on surface loss and re-acquisition, the framework generates a new layer tree. Otherwise, why render the same contents to the screen again? This is used as an optimization in cases where there are external textures (video or camera streams for example) in referenced in the layer tree. These textures may be updated at a cadence different from that of the Flutter application. Flutter can re-render the layer tree with just the updated textures instead of waiting for the framework to do the work to generate the layer tree describing the same contents.

GrDirectContext *	GetGrContext () override

std::shared_ptr< flutter::TextureRegistry >	GetTextureRegistry () override
	Gets the registry of external textures currently in use by the rasterizer. These textures may be updated at a cadence different from that of the Flutter application. When an external texture is referenced in the Flutter layer tree, that texture is composited within the Flutter layer tree.

DrawStatus	Draw (const std::shared_ptr< FramePipeline > &pipeline)
	Takes the next item from the layer tree pipeline and executes the raster thread frame workload for that pipeline item to render a frame on the on-screen surface.

Screenshot	ScreenshotLastLayerTree (ScreenshotType type, bool base64_encode)
	Screenshots the last layer tree to one of the supported screenshot types and optionally Base 64 encodes that data for easier transmission and packaging (usually over the service protocol for instrumentation tools running on the host).

void	SetNextFrameCallback (const fml::closure &callback)
	Sets a callback that will be executed when the next layer tree in rendered to the on-screen surface. This is used by embedders to listen for one time operations like listening for when the first frame is rendered so that they may hide splash screens.

void	SetExternalViewEmbedder (const std::shared_ptr< ExternalViewEmbedder > &view_embedder)
	Set the External View Embedder. This is done on shell initialization. This is non-null on platforms that support embedding externally composited views.

void	SetSnapshotSurfaceProducer (std::unique_ptr< SnapshotSurfaceProducer > producer)
	Set the snapshot surface producer. This is done on shell initialization. This is non-null on platforms that support taking GPU accelerated raster snapshots in the background.

flutter::CompositorContext *	compositor_context ()
	Returns a pointer to the compositor context used by this rasterizer. This pointer will never be `nullptr`.

fml::RefPtr< fml::RasterThreadMerger >	GetRasterThreadMerger ()
	Returns the raster thread merger used by this rasterizer. This may be `nullptr`.

void	SetResourceCacheMaxBytes (size_t max_bytes, bool from_user)
	Skia has no notion of time. To work around the performance implications of this, it may cache GPU resources to reference them from one frame to the next. Using this call, embedders may set the maximum bytes cached by Skia in its caches dedicated to on-screen rendering.

std::optional< size_t >	GetResourceCacheMaxBytes () const
	The current value of Skia's resource cache size, if a surface is present.

void	EnableThreadMergerIfNeeded ()
	Enables the thread merger if the external view embedder supports dynamic thread merging.

void	DisableThreadMergerIfNeeded ()
	Disables the thread merger if the external view embedder supports dynamic thread merging.

bool	IsTornDown ()
	Returns whether TearDown has been called.

std::optional< DrawSurfaceStatus >	GetLastDrawStatus (int64_t view_id)
	Returns the last status of drawing the specific view.

Public Member Functions inherited from flutter::SnapshotController::Delegate
virtual	~Delegate ()=default

Detailed Description

The rasterizer is a component owned by the shell that resides on the raster task runner. Each shell owns exactly one instance of a rasterizer. The rasterizer may only be created, used and collected on the raster task runner.

The rasterizer owns the instance of the currently active on-screen render surface. On this surface, it renders the contents of layer trees submitted to it by the Engine (which lives on the UI task runner).

The primary components owned by the rasterizer are the compositor context and the on-screen render surface. The compositor context has all the GPU state necessary to render frames to the render surface.

Definition at line 114 of file rasterizer.h.

Member Enumeration Documentation

◆ MakeGpuImageBehavior

enum class flutter::Rasterizer::MakeGpuImageBehavior

strong

How to handle calls to MakeSkiaGpuImage.

Enumerator
kGpu	MakeSkiaGpuImage returns a GPU resident image, if possible.
kBitmap	MakeSkiaGpuImage returns a checkerboard bitmap. This is useful in test contexts where no GPU surface is available.

Definition at line 178 of file rasterizer.h.

                                  {
    /// MakeSkiaGpuImage returns a GPU resident image, if possible.
    kGpu,
    /// MakeSkiaGpuImage returns a checkerboard bitmap. This is useful in test
    /// contexts where no GPU surface is available.
    kBitmap,
  };

◆ ScreenshotFormat

enum class flutter::Rasterizer::ScreenshotFormat

strong

Enumerator
kUnknown
kR8G8B8A8UNormInt
kB8G8R8A8UNormInt
kR16G16B16A16Float

Definition at line 384 of file rasterizer.h.

                              {
    // Unknown format, or Skia default.
    kUnknown,
    // RGBA 8 bits per channel.
    kR8G8B8A8UNormInt,
    // BGRA 8 bits per channel.
    kB8G8R8A8UNormInt,
    // RGBA 16 bit floating point per channel.
    kR16G16B16A16Float,
  };

◆ ScreenshotType

enum class flutter::Rasterizer::ScreenshotType

strong

The type of the screenshot to obtain of the previously rendered layer tree.

Enumerator
SkiaPicture	A format used to denote a Skia picture. A Skia picture is a serialized representation of an `SkPicture` that can be used to introspect the series of commands used to draw that picture. Skia pictures are typically stored as files with the .skp extension on disk. These files may be viewed in an interactive debugger available at https://debugger.skia.org/
UncompressedImage	A format used to denote uncompressed image data. For Skia, this format is 32 bits per pixel, 8 bits per component and denoted by the `kN32_SkColorType` Skia color type. For Impeller, its format is specified in Screenshot::pixel_format.
CompressedImage	A format used to denote compressed image data. The PNG compressed container is used.
SurfaceData	Reads the data directly from the Rasterizer's surface. The pixel format is determined from the surface. This is the only way to read wide gamut color data, but isn't supported everywhere.

Definition at line 348 of file rasterizer.h.

                            {
    // NOLINTBEGIN(readability-identifier-naming)
    //--------------------------------------------------------------------------
    /// A format used to denote a Skia picture. A Skia picture is a serialized
    /// representation of an `SkPicture` that can be used to introspect the
    /// series of commands used to draw that picture.
    ///
    /// Skia pictures are typically stored as files with the .skp extension on
    /// disk. These files may be viewed in an interactive debugger available at
    /// https://debugger.skia.org/
    ///
    SkiaPicture,
 
    //--------------------------------------------------------------------------
    /// A format used to denote uncompressed image data. For Skia, this format
    /// is 32 bits per pixel, 8 bits per component and
    /// denoted by the `kN32_SkColorType ` Skia color type. For Impeller, its
    /// format is specified in Screenshot::pixel_format.
    ///
    UncompressedImage,
 
    //--------------------------------------------------------------------------
    /// A format used to denote compressed image data. The PNG compressed
    /// container is used.
    ///
    CompressedImage,
 
    //--------------------------------------------------------------------------
    /// Reads the data directly from the Rasterizer's surface. The pixel format
    /// is determined from the surface. This is the only way to read wide gamut
    /// color data, but isn't supported everywhere.
    SurfaceData,
    // NOLINTEND(readability-identifier-naming)
  };

Constructor & Destructor Documentation

◆ Rasterizer()

flutter::Rasterizer::Rasterizer	(	Delegate &	delegate,
		MakeGpuImageBehavior	gpu_image_behavior = `MakeGpuImageBehavior::kGpu`
	)

explicit

Creates a new instance of a rasterizer. Rasterizers may only be created on the raster task runner. Rasterizers are currently only created by the shell (which also sets itself up as the rasterizer delegate).

Parameters

[in]	delegate	The rasterizer delegate.
[in]	gpu_image_behavior	How to handle calls to MakeSkiaGpuImage.

Definition at line 54 of file rasterizer.cc.

    : delegate_(delegate),
      gpu_image_behavior_(gpu_image_behavior),
      compositor_context_(std::make_unique<flutter::CompositorContext>(*this)),
      snapshot_controller_(
          SnapshotController::Make(*this, delegate.GetSettings())),
      weak_factory_(this) {
  FML_DCHECK(compositor_context_);
}

References FML_DCHECK.

◆ ~Rasterizer()

flutter::Rasterizer::~Rasterizer ( )

default

Destroys the rasterizer. This must happen on the raster task runner. All GPU resources are collected before this call returns. Any context set up by the embedder to hold these resources can be immediately collected as well.

Member Function Documentation

◆ CollectView()

void flutter::Rasterizer::CollectView ( int64_t view_id )

Deallocate the resources for displaying a view.

        This method must be called on the raster task runner when a
        view is removed from the engine.

        When the rasterizer is requested to draw an unrecognized view,
        it implicitly allocates necessary resources. These resources
        must be explicitly deallocated.

Parameters

[in] view_id The ID of the view.

Definition at line 194 of file rasterizer.cc.

                                            {
  if (external_view_embedder_) {
    external_view_embedder_->CollectView(view_id);
  }
  view_records_.erase(view_id);
}

References view_id.

◆ compositor_context()

flutter::CompositorContext * flutter::Rasterizer::compositor_context ( )

inline

Returns a pointer to the compositor context used by this rasterizer. This pointer will never be nullptr.

Returns: The compositor context used by this rasterizer.

Definition at line 516 of file rasterizer.h.

                                                 {
    return compositor_context_.get();
  }

◆ DisableThreadMergerIfNeeded()

void flutter::Rasterizer::DisableThreadMergerIfNeeded ( )

Disables the thread merger if the external view embedder supports dynamic thread merging.

Attention: This method is thread-safe. When the thread merger is disabled, the raster task queue will continue to run in the same thread until |EnableThreadMergerIfNeeded| is called.

See also: ExternalViewEmbedder

Definition at line 167 of file rasterizer.cc.

                                             {
  if (raster_thread_merger_) {
    raster_thread_merger_->Disable();
  }
}

References fml::RasterThreadMerger::Disable().

◆ Draw()

DrawStatus flutter::Rasterizer::Draw ( const std::shared_ptr< FramePipeline > & pipeline )

Takes the next item from the layer tree pipeline and executes the raster thread frame workload for that pipeline item to render a frame on the on-screen surface.

Why does the draw call take a layer tree pipeline and not the layer tree directly?

The pipeline is the way book-keeping of frame workloads distributed across the multiple threads is managed. The rasterizer deals with the pipelines directly (instead of layer trees which is what it actually renders) because the pipeline consumer's workload must be accounted for within the pipeline itself. If the rasterizer took the layer tree directly, it would have to be taken out of the pipeline. That would signal the end of the frame workload and the pipeline would be ready for new frames. But the last frame has not been rendered by the frame yet! On the other hand, the pipeline must own the layer tree it renders because it keeps a reference to the last layer tree around till a new frame is rendered. So a simple reference wont work either. The Rasterizer::DoDraw method actually performs the GPU operations within the layer tree pipeline.

See also: Rasterizer::DoDraw

Parameters

[in] pipeline The layer tree pipeline to take the next layer tree to render from.

Definition at line 248 of file rasterizer.cc.

                                                                        {
  TRACE_EVENT0("flutter", "GPURasterizer::Draw");
  if (raster_thread_merger_ &&
      !raster_thread_merger_->IsOnRasterizingThread()) {
    // we yield and let this frame be serviced on the right thread.
    return DrawStatus::kYielded;
  }
  FML_DCHECK(delegate_.GetTaskRunners()
                 .GetRasterTaskRunner()
                 ->RunsTasksOnCurrentThread());
 
  DoDrawResult draw_result;
  FramePipeline::Consumer consumer = [&draw_result,
                                      this](std::unique_ptr<FrameItem> item) {
    draw_result = DoDraw(std::move(item->frame_timings_recorder),
                         std::move(item->layer_tree_tasks));
  };
 
  PipelineConsumeResult consume_result = pipeline->Consume(consumer);
  if (consume_result == PipelineConsumeResult::NoneAvailable) {
    return DrawStatus::kPipelineEmpty;
  }
  // if the raster status is to resubmit the frame, we push the frame to the
  // front of the queue and also change the consume status to more available.
 
  bool should_resubmit_frame = ShouldResubmitFrame(draw_result);
  if (should_resubmit_frame) {
    FML_CHECK(draw_result.resubmitted_item);
    auto front_continuation = pipeline->ProduceIfEmpty();
    PipelineProduceResult pipeline_result =
        front_continuation.Complete(std::move(draw_result.resubmitted_item));
    if (pipeline_result.success) {
      consume_result = PipelineConsumeResult::MoreAvailable;
    }
  } else if (draw_result.status == DoDrawStatus::kEnqueuePipeline) {
    consume_result = PipelineConsumeResult::MoreAvailable;
  }
 
  // EndFrame should perform cleanups for the external_view_embedder.
  if (external_view_embedder_ && external_view_embedder_->GetUsedThisFrame()) {
    external_view_embedder_->SetUsedThisFrame(false);
    external_view_embedder_->EndFrame(should_resubmit_frame,
                                      raster_thread_merger_);
  }
 
  // Consume as many pipeline items as possible. But yield the event loop
  // between successive tries.
  switch (consume_result) {
    case PipelineConsumeResult::MoreAvailable: {
      delegate_.GetTaskRunners().GetRasterTaskRunner()->PostTask(
          [weak_this = weak_factory_.GetWeakPtr(), pipeline]() {
            if (weak_this) {
              weak_this->Draw(pipeline);
            }
          });
      break;
    }
    default:
      break;
  }
 
  return ToDrawStatus(draw_result.status);
}

References FML_CHECK, FML_DCHECK, flutter::TaskRunners::GetRasterTaskRunner(), flutter::Rasterizer::Delegate::GetTaskRunners(), fml::RasterThreadMerger::IsOnRasterizingThread(), flutter::kPipelineEmpty, flutter::kYielded, flutter::MoreAvailable, flutter::NoneAvailable, pipeline, fml::TaskRunner::PostTask(), fml::TaskRunner::RunsTasksOnCurrentThread(), flutter::PipelineProduceResult::success, and TRACE_EVENT0.

◆ DrawLastLayerTrees()

void flutter::Rasterizer::DrawLastLayerTrees ( std::unique_ptr< FrameTimingsRecorder > frame_timings_recorder )

Draws the last layer trees with their last configuration. This may seem entirely redundant at first glance. After all, on surface loss and re-acquisition, the framework generates a new layer tree. Otherwise, why render the same contents to the screen again? This is used as an optimization in cases where there are external textures (video or camera streams for example) in referenced in the layer tree. These textures may be updated at a cadence different from that of the Flutter application. Flutter can re-render the layer tree with just the updated textures instead of waiting for the framework to do the work to generate the layer tree describing the same contents.

Calling this method clears all last layer trees (GetLastLayerTree).

Definition at line 221 of file rasterizer.cc.

                                                                {
  if (!surface_) {
    return;
  }
  std::vector<std::unique_ptr<LayerTreeTask>> tasks;
  for (auto& [view_id, view_record] : view_records_) {
    if (view_record.last_successful_task) {
      tasks.push_back(std::move(view_record.last_successful_task));
    }
  }
  if (tasks.empty()) {
    return;
  }
 
  DoDrawResult result =
      DrawToSurfaces(*frame_timings_recorder, std::move(tasks));
 
  // EndFrame should perform cleanups for the external_view_embedder.
  if (external_view_embedder_ && external_view_embedder_->GetUsedThisFrame()) {
    bool should_resubmit_frame = ShouldResubmitFrame(result);
    external_view_embedder_->SetUsedThisFrame(false);
    external_view_embedder_->EndFrame(should_resubmit_frame,
                                      raster_thread_merger_);
  }
}

References view_id.

◆ EnableThreadMergerIfNeeded()

void flutter::Rasterizer::EnableThreadMergerIfNeeded ( )

Enables the thread merger if the external view embedder supports dynamic thread merging.

Attention: This method is thread-safe. When the thread merger is enabled, the raster task queue can run in the platform thread at any time.

See also: ExternalViewEmbedder

Definition at line 161 of file rasterizer.cc.

                                            {
  if (raster_thread_merger_) {
    raster_thread_merger_->Enable();
  }
}

References fml::RasterThreadMerger::Enable().

◆ GetGrContext()

GrDirectContext * flutter::Rasterizer::GetGrContext ( )

overridevirtual

Implements flutter::SnapshotDelegate.

Definition at line 205 of file rasterizer.cc.

                                          {
  return surface_ ? surface_->GetContext() : nullptr;
}

◆ GetLastDrawStatus()

std::optional< DrawSurfaceStatus > flutter::Rasterizer::GetLastDrawStatus ( int64_t view_id )

Returns the last status of drawing the specific view.

        This method is used only in unit tests.

Definition at line 151 of file rasterizer.cc.

                     {
  auto found = view_records_.find(view_id);
  if (found != view_records_.end()) {
    return found->second.last_draw_status;
  } else {
    return std::optional<DrawSurfaceStatus>();
  }
}

References view_id.

◆ GetLastLayerTree()

flutter::LayerTree * flutter::Rasterizer::GetLastLayerTree ( int64_t view_id )

Returns the last successfully drawn layer tree for the given view, or nullptr if there isn't any. This is useful during DrawLastLayerTrees and computing frame damage.

Returns: A pointer to the last layer or nullptr if this rasterizer has never rendered a frame to the given view.

Definition at line 209 of file rasterizer.cc.

                                                              {
  auto found = view_records_.find(view_id);
  if (found == view_records_.end()) {
    return nullptr;
  }
  auto& last_task = found->second.last_successful_task;
  if (last_task == nullptr) {
    return nullptr;
  }
  return last_task->layer_tree.get();
}

References view_id.

◆ GetRasterThreadMerger()

fml::RefPtr< fml::RasterThreadMerger > flutter::Rasterizer::GetRasterThreadMerger ( )

Returns the raster thread merger used by this rasterizer. This may be nullptr.

Returns: The raster thread merger used by this rasterizer.

Definition at line 1154 of file rasterizer.cc.

                                                                   {
  return raster_thread_merger_;
}

◆ GetResourceCacheMaxBytes()

std::optional< size_t > flutter::Rasterizer::GetResourceCacheMaxBytes ( ) const

The current value of Skia's resource cache size, if a surface is present.

Attention: This cache does not describe the entirety of GPU resources that may be cached. The RasterCache also holds very large GPU resources.

See also: RasterCache

Returns: The size of Skia's resource cache, if available.

Definition at line 1195 of file rasterizer.cc.

                                                               {
#if SLIMPELLER
  return std::nullopt;
#else   // SLIMPELLER
  if (!surface_) {
    return std::nullopt;
  }
  GrDirectContext* context = surface_->GetContext();
  if (context) {
    return context->getResourceCacheLimit();
  }
  return std::nullopt;
#endif  //  SLIMPELLER
}

References context, and surface_.

◆ GetSnapshotDelegate()

fml::TaskRunnerAffineWeakPtr< SnapshotDelegate > flutter::Rasterizer::GetSnapshotDelegate ( ) const

Definition at line 71 of file rasterizer.cc.

          {
  return weak_factory_.GetWeakPtr();
}

◆ GetTextureRegistry()

std::shared_ptr< flutter::TextureRegistry > flutter::Rasterizer::GetTextureRegistry ( )

overridevirtual

Gets the registry of external textures currently in use by the rasterizer. These textures may be updated at a cadence different from that of the Flutter application. When an external texture is referenced in the Flutter layer tree, that texture is composited within the Flutter layer tree.

Returns: A pointer to the external texture registry.

Implements flutter::SnapshotDelegate.

Definition at line 201 of file rasterizer.cc.

                                                                     {
  return compositor_context_->texture_registry();
}

◆ GetWeakPtr()

fml::TaskRunnerAffineWeakPtr< Rasterizer > flutter::Rasterizer::GetWeakPtr ( ) const

Gets a weak pointer to the rasterizer. The rasterizer may only be accessed on the raster task runner.

Returns: The weak pointer to the rasterizer.

Definition at line 67 of file rasterizer.cc.

                                                                    {
  return weak_factory_.GetWeakPtr();
}

◆ IsTornDown()

bool flutter::Rasterizer::IsTornDown ( )

Returns whether TearDown has been called.

        This method is used only in unit tests.

Definition at line 147 of file rasterizer.cc.

                            {
  return is_torn_down_;
}

◆ NotifyLowMemoryWarning()

void flutter::Rasterizer::NotifyLowMemoryWarning ( ) const

Notifies the rasterizer that there is a low memory situation and it must purge as many unnecessary resources as possible. Currently, the Skia context associated with onscreen rendering is told to free GPU resources.

Definition at line 173 of file rasterizer.cc.

                                              {
#if !SLIMPELLER
  if (!surface_) {
    FML_DLOG(INFO)
        << "Rasterizer::NotifyLowMemoryWarning called with no surface.";
    return;
  }
  auto context = surface_->GetContext();
  if (!context) {
    FML_DLOG(INFO)
        << "Rasterizer::NotifyLowMemoryWarning called with no GrContext.";
    return;
  }
  auto context_switch = surface_->MakeRenderContextCurrent();
  if (!context_switch->GetResult()) {
    return;
  }
  context->performDeferredCleanup(std::chrono::milliseconds(0));
#endif  //  !SLIMPELLER
}

References context, and FML_DLOG.

◆ ScreenshotLastLayerTree()

Rasterizer::Screenshot flutter::Rasterizer::ScreenshotLastLayerTree	(	Rasterizer::ScreenshotType	type,
		bool	base64_encode
	)

Screenshots the last layer tree to one of the supported screenshot types and optionally Base 64 encodes that data for easier transmission and packaging (usually over the service protocol for instrumentation tools running on the host).

Parameters

[in]	type	The type of the screenshot to gather.
[in]	base64_encode	Whether Base 64 encoding must be applied to the data after a screenshot has been captured.

Returns: A non-empty screenshot if one could be captured. A screenshot capture may fail if there were no layer trees previously rendered by this rasterizer, or, due to an unspecified internal error. Internal error will be logged to the console.

Definition at line 1075 of file rasterizer.cc.

                        {
  if (delegate_.GetSettings().enable_impeller &&
      type == ScreenshotType::SkiaPicture) {
    FML_DCHECK(false);
    FML_LOG(ERROR) << "Last layer tree cannot be screenshotted as a "
                      "SkiaPicture when using Impeller.";
    return {};
  }
  // TODO(dkwingsmt): Support screenshotting all last layer trees
  // when the shell protocol supports multi-views.
  // https://github.com/flutter/flutter/issues/135534
  // https://github.com/flutter/flutter/issues/135535
  auto* layer_tree = GetLastLayerTree(kFlutterImplicitViewId);
  if (layer_tree == nullptr) {
    FML_LOG(ERROR) << "Last layer tree was null when screenshotting.";
    return {};
  }
 
  std::pair<sk_sp<SkData>, ScreenshotFormat> data{nullptr,
                                                  ScreenshotFormat::kUnknown};
  std::string format;
 
  switch (type) {
    case ScreenshotType::SkiaPicture:
      format = "ScreenshotType::SkiaPicture";
      data.first =
          ScreenshotLayerTreeAsPicture(layer_tree, *compositor_context_);
      break;
    case ScreenshotType::UncompressedImage:
      format = "ScreenshotType::UncompressedImage";
      data =
          ScreenshotLayerTreeAsImage(layer_tree, *compositor_context_, false);
      break;
    case ScreenshotType::CompressedImage:
      format = "ScreenshotType::CompressedImage";
      data = ScreenshotLayerTreeAsImage(layer_tree, *compositor_context_, true);
      break;
    case ScreenshotType::SurfaceData: {
      Surface::SurfaceData surface_data = surface_->GetSurfaceData();
      format = surface_data.pixel_format;
      data.first = surface_data.data;
      break;
    }
  }
 
  if (data.first == nullptr) {
    FML_LOG(ERROR) << "Screenshot data was null.";
    return {};
  }
 
  if (base64_encode) {
    size_t b64_size = Base64::EncodedSize(data.first->size());
    auto b64_data = SkData::MakeUninitialized(b64_size);
    Base64::Encode(data.first->data(), data.first->size(),
                   b64_data->writable_data());
    return Rasterizer::Screenshot{b64_data, layer_tree->frame_size(), format,
                                  data.second};
  }
 
  return Rasterizer::Screenshot{data.first, layer_tree->frame_size(), format,
                                data.second};
}

References flutter::Surface::SurfaceData::data, flutter::data, delegate_, FML_DCHECK, FML_LOG, format, flutter::LayerTree::frame_size(), flutter::kFlutterImplicitViewId, flutter::Surface::SurfaceData::pixel_format, flutter::ScreenshotLayerTreeAsPicture(), surface_, and type.

◆ SetExternalViewEmbedder()

void flutter::Rasterizer::SetExternalViewEmbedder ( const std::shared_ptr< ExternalViewEmbedder > & view_embedder )

Set the External View Embedder. This is done on shell initialization. This is non-null on platforms that support embedding externally composited views.

Parameters

[in] view_embedder The external view embedder object.

Definition at line 1144 of file rasterizer.cc.

                                                              {
  external_view_embedder_ = view_embedder;
}

◆ SetImpellerContext()

void flutter::Rasterizer::SetImpellerContext ( std::shared_ptr< impeller::ImpellerContextFuture > impeller_context )

Definition at line 76 of file rasterizer.cc.

                                                                   {
  impeller_context_ = std::move(impeller_context);
}

◆ SetNextFrameCallback()

void flutter::Rasterizer::SetNextFrameCallback ( const fml::closure & callback )

Sets a callback that will be executed when the next layer tree in rendered to the on-screen surface. This is used by embedders to listen for one time operations like listening for when the first frame is rendered so that they may hide splash screens.

The callback is only executed once and dropped on the GPU thread when executed (lambda captures must be able to deal with the threading repercussions of this behavior).

Parameters

[in] callback The callback to execute when the next layer tree is rendered on-screen.

Definition at line 1140 of file rasterizer.cc.

                                                                {
  next_frame_callback_ = callback;
}

References callback.

◆ SetResourceCacheMaxBytes()

void flutter::Rasterizer::SetResourceCacheMaxBytes	(	size_t	max_bytes,
		bool	from_user
	)

Skia has no notion of time. To work around the performance implications of this, it may cache GPU resources to reference them from one frame to the next. Using this call, embedders may set the maximum bytes cached by Skia in its caches dedicated to on-screen rendering.

Attention: This cache setting will be invalidated when the surface is torn down via Rasterizer::Teardown. This call must be made again with new limits after surface re-acquisition.; This cache does not describe the entirety of GPU resources that may be cached. The RasterCache also holds very large GPU resources.

See also: RasterCache

Parameters

[in]	max_bytes	The maximum byte size of resource that may be cached for GPU rendering.
[in]	from_user	Whether this request was from user code, e.g. via the flutter/skia message channel, in which case it should not be overridden by the platform.

Definition at line 1168 of file rasterizer.cc.

                                                                          {
#if !SLIMPELLER
  user_override_resource_cache_bytes_ |= from_user;
 
  if (!from_user && user_override_resource_cache_bytes_) {
    // We should not update the setting here if a user has explicitly set a
    // value for this over the flutter/skia channel.
    return;
  }
 
  max_cache_bytes_ = max_bytes;
  if (!surface_) {
    return;
  }
 
  GrDirectContext* context = surface_->GetContext();
  if (context) {
    auto context_switch = surface_->MakeRenderContextCurrent();
    if (!context_switch->GetResult()) {
      return;
    }
 
    context->setResourceCacheLimit(max_bytes);
  }
#endif  //  !SLIMPELLER
}

References context, and surface_.

Referenced by Setup().

◆ SetSnapshotSurfaceProducer()

void flutter::Rasterizer::SetSnapshotSurfaceProducer ( std::unique_ptr< SnapshotSurfaceProducer > producer )

Set the snapshot surface producer. This is done on shell initialization. This is non-null on platforms that support taking GPU accelerated raster snapshots in the background.

Parameters

[in] producer A surface producer for raster snapshotting when the onscreen surface is not available.

Definition at line 1149 of file rasterizer.cc.

                                                     {
  snapshot_surface_producer_ = std::move(producer);
}

◆ Setup()

void flutter::Rasterizer::Setup ( std::unique_ptr< Surface > surface )

Rasterizers may be created well before an on-screen surface is available for rendering. Shells usually create a rasterizer in their constructors. Once an on-screen surface is available however, one may be provided to the rasterizer using this call. No rendering may occur before this call. The surface is held till the balancing call to Rasterizer::Teardown is made. Calling a setup before tearing down the previous surface (if this is not the first time the surface has been set up) is user error.

See also: Rasterizer::Teardown

Parameters

[in] surface The on-screen render surface.

Definition at line 81 of file rasterizer.cc.

                                                     {
  surface_ = std::move(surface);
 
  if (max_cache_bytes_.has_value()) {
    SetResourceCacheMaxBytes(max_cache_bytes_.value(),
                             user_override_resource_cache_bytes_);
  }
 
  auto context_switch = surface_->MakeRenderContextCurrent();
  if (context_switch->GetResult()) {
    compositor_context_->OnGrContextCreated();
  }
 
  if (external_view_embedder_ &&
      external_view_embedder_->SupportsDynamicThreadMerging() &&
      !raster_thread_merger_) {
    const auto platform_id =
        delegate_.GetTaskRunners().GetPlatformTaskRunner()->GetTaskQueueId();
    const auto gpu_id =
        delegate_.GetTaskRunners().GetRasterTaskRunner()->GetTaskQueueId();
    raster_thread_merger_ = fml::RasterThreadMerger::CreateOrShareThreadMerger(
        delegate_.GetParentRasterThreadMerger(), platform_id, gpu_id);
  }
  if (raster_thread_merger_) {
    raster_thread_merger_->SetMergeUnmergeCallback([this]() {
      // Clear the GL context after the thread configuration has changed.
      if (surface_) {
        surface_->ClearRenderContext();
      }
    });
  }
}

References fml::RasterThreadMerger::CreateOrShareThreadMerger(), flutter::Rasterizer::Delegate::GetParentRasterThreadMerger(), flutter::TaskRunners::GetPlatformTaskRunner(), flutter::TaskRunners::GetRasterTaskRunner(), fml::TaskRunner::GetTaskQueueId(), flutter::Rasterizer::Delegate::GetTaskRunners(), fml::RasterThreadMerger::SetMergeUnmergeCallback(), SetResourceCacheMaxBytes(), and surface.

◆ Teardown()

void flutter::Rasterizer::Teardown ( )

Releases the previously set up on-screen render surface and collects associated resources. No more rendering may occur till the next call to Rasterizer::Setup with a new render surface. Calling a teardown without a setup is user error. Calling this method multiple times is safe.

Definition at line 120 of file rasterizer.cc.

                          {
  is_torn_down_ = true;
  if (surface_) {
    auto context_switch = surface_->MakeRenderContextCurrent();
    if (context_switch->GetResult()) {
      compositor_context_->OnGrContextDestroyed();
#if !SLIMPELLER
      if (auto* context = surface_->GetContext()) {
        context->purgeUnlockedResources(GrPurgeResourceOptions::kAllResources);
      }
#endif  //  !SLIMPELLER
    }
    context_switch.reset();
    surface_->ClearRenderContext();
    surface_.reset();
  }
 
  view_records_.clear();
 
  if (raster_thread_merger_.get() != nullptr &&
      raster_thread_merger_.get()->IsMerged()) {
    FML_DCHECK(raster_thread_merger_->IsEnabled());
    raster_thread_merger_->UnMergeNowIfLastOne();
    raster_thread_merger_->SetMergeUnmergeCallback(nullptr);
  }
}

References context, FML_DCHECK, fml::RefPtr< T >::get(), fml::RasterThreadMerger::IsEnabled(), fml::RasterThreadMerger::IsMerged(), fml::RasterThreadMerger::SetMergeUnmergeCallback(), and fml::RasterThreadMerger::UnMergeNowIfLastOne().

◆ TeardownExternalViewEmbedder()

void flutter::Rasterizer::TeardownExternalViewEmbedder ( )

Releases any resource used by the external view embedder. For example, overlay surfaces or Android views. On Android, this method post a task to the platform thread, and waits until it completes.

Definition at line 114 of file rasterizer.cc.

                                              {
  if (external_view_embedder_) {
    external_view_embedder_->Teardown();
  }
}

The documentation for this class was generated from the following files:

shell/common/rasterizer.h
shell/common/rasterizer.cc

Classes

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ MakeGpuImageBehavior

◆ ScreenshotFormat

◆ ScreenshotType

Constructor & Destructor Documentation

◆ Rasterizer()

◆ ~Rasterizer()

Member Function Documentation

◆ CollectView()

◆ compositor_context()

◆ DisableThreadMergerIfNeeded()

◆ Draw()

◆ DrawLastLayerTrees()

◆ EnableThreadMergerIfNeeded()

◆ GetGrContext()

◆ GetLastDrawStatus()

◆ GetLastLayerTree()

◆ GetRasterThreadMerger()

◆ GetResourceCacheMaxBytes()

◆ GetSnapshotDelegate()

◆ GetTextureRegistry()

◆ GetWeakPtr()

◆ IsTornDown()

◆ NotifyLowMemoryWarning()

◆ ScreenshotLastLayerTree()

◆ SetExternalViewEmbedder()

◆ SetImpellerContext()

◆ SetNextFrameCallback()

◆ SetResourceCacheMaxBytes()

◆ SetSnapshotSurfaceProducer()

◆ Setup()

◆ Teardown()

◆ TeardownExternalViewEmbedder()