impeller::SurfaceMTL Class Reference

#include <surface_mtl.h>

Inheritance diagram for impeller::SurfaceMTL:

Public Member Functions
	~SurfaceMTL () override
id< MTLDrawable >	drawable () const
IRect	coverage () const
void	PresentWithTransaction (bool present_with_transaction)
bool	PreparePresent () const
	Perform the final blit and trigger end of frame workloads.
bool	Present () const override
void	SetFrameBoundary (bool frame_boundary)
Public Member Functions inherited from impeller::Surface
	Surface ()
	Surface (const RenderTarget &target_desc)
virtual	~Surface ()
const ISize &	GetSize () const
bool	IsValid () const
const RenderTarget &	GetRenderTarget () const

Static Public Member Functions
static id< CAMetalDrawable >	GetMetalDrawableAndValidate (const std::shared_ptr< Context > &context, CAMetalLayer *layer)
	Wraps the current drawable of the given Metal layer to create a surface Impeller can render to. The surface must be created as late as possible and discarded immediately after rendering to it.
static std::unique_ptr< SurfaceMTL >	MakeFromMetalLayerDrawable (const std::shared_ptr< Context > &context, id< CAMetalDrawable > drawable, const std::shared_ptr< SwapchainTransientsMTL > &transients, std::optional< IRect > clip_rect=std::nullopt)
static std::unique_ptr< SurfaceMTL >	MakeFromTexture (const std::shared_ptr< Context > &context, id< MTLTexture > texture, const std::shared_ptr< SwapchainTransientsMTL > &transients, std::optional< IRect > clip_rect, id< CAMetalDrawable > drawable=nil)

Detailed Description

Definition at line 18 of file surface_mtl.h.

Constructor & Destructor Documentation

~SurfaceMTL()

impeller::SurfaceMTL::~SurfaceMTL ( )

overridedefault

Member Function Documentation

coverage()

IRect impeller::SurfaceMTL::coverage

(

)

const

Definition at line 212 of file surface_mtl.mm.

                                 {
  return IRect::MakeSize(resolve_texture_->GetSize());
}

References impeller::TRect< T >::MakeSize().

drawable()

id< MTLDrawable > impeller::SurfaceMTL::drawable ( ) const

inline

Definition at line 59 of file surface_mtl.h.

{ return drawable_; }

Referenced by MakeFromMetalLayerDrawable(), MakeFromTexture(), and Present().

GetMetalDrawableAndValidate()

id< CAMetalDrawable > impeller::SurfaceMTL::GetMetalDrawableAndValidate ( const std::shared_ptr< Context > &  context, CAMetalLayer *  layer  )

static

Wraps the current drawable of the given Metal layer to create a surface Impeller can render to. The surface must be created as late as possible and discarded immediately after rendering to it.

Parameters

[in]	context	The context
[in]	layer	The layer whose current drawable to wrap to create a surface.

Returns

A pointer to the wrapped surface or null.

Definition at line 29 of file surface_mtl.mm.

                         {
  TRACE_EVENT0("impeller", "SurfaceMTL::WrapCurrentMetalLayerDrawable");
 
  if (context == nullptr || !context->IsValid() || layer == nil) {
    return nullptr;
  }
 
  id<CAMetalDrawable> current_drawable = nil;
  {
    TRACE_EVENT0("impeller", "WaitForNextDrawable");
    current_drawable = [layer nextDrawable];
  }
 
  if (!current_drawable) {
    VALIDATION_LOG << "Could not acquire current drawable.";
    return nullptr;
  }
  return current_drawable;
}

References TRACE_EVENT0, and VALIDATION_LOG.

MakeFromMetalLayerDrawable()

std::unique_ptr< SurfaceMTL > impeller::SurfaceMTL::MakeFromMetalLayerDrawable ( const std::shared_ptr< Context > &  context, id< CAMetalDrawable >  drawable, const std::shared_ptr< SwapchainTransientsMTL > &  transients, std::optional< IRect >  clip_rect = std::nullopt  )

static

Definition at line 113 of file surface_mtl.mm.

                                  {
  return SurfaceMTL::MakeFromTexture(context, drawable.texture, transients,
                                     clip_rect, drawable);
}

References drawable(), and MakeFromTexture().

MakeFromTexture()

std::unique_ptr< SurfaceMTL > impeller::SurfaceMTL::MakeFromTexture ( const std::shared_ptr< Context > &  context, id< MTLTexture >  texture, const std::shared_ptr< SwapchainTransientsMTL > &  transients, std::optional< IRect >  clip_rect, id< CAMetalDrawable >  drawable = nil  )

static

Definition at line 122 of file surface_mtl.mm.

                                  {
  bool partial_repaint_blit_required = ShouldPerformPartialRepaint(clip_rect);
 
  // The returned render target is the texture that Impeller will render the
  // root pass to. If partial repaint is in use, this may be a new texture which
  // is smaller than the given MTLTexture.
  auto render_target = WrapTextureWithRenderTarget(
      transients, texture, partial_repaint_blit_required, clip_rect);
  if (!render_target) {
    return nullptr;
  }
 
  // If partial repainting, set a "source" texture. The presence of a source
  // texture and clip rect instructs the surface to blit this texture to the
  // destination texture.
  auto source_texture = partial_repaint_blit_required
                            ? render_target->GetRenderTargetTexture()
                            : nullptr;
 
  // The final "destination" texture is the texture that will be presented. In
  // this case, it's always the given drawable.
  std::shared_ptr<Texture> destination_texture;
  if (partial_repaint_blit_required) {
    // If blitting for partial repaint, we need to wrap the drawable. Simply
    // reuse the texture descriptor that was already formed for the new render
    // target, but override the size with the drawable's size.
    auto destination_descriptor =
        render_target->GetRenderTargetTexture()->GetTextureDescriptor();
    destination_descriptor.size = {static_cast<ISize::Type>(texture.width),
                                   static_cast<ISize::Type>(texture.height)};
    destination_texture = TextureMTL::Wrapper(destination_descriptor, texture);
  } else {
    // When not partial repaint blit is needed, the render target texture _is_
    // the drawable texture.
    destination_texture = render_target->GetRenderTargetTexture();
  }
 
  return std::unique_ptr<SurfaceMTL>(new SurfaceMTL(
      context,                                  // context
      *render_target,                           // target
      render_target->GetRenderTargetTexture(),  // resolve_texture
      drawable,                                 // drawable
      source_texture,                           // source_texture
      destination_texture,                      // destination_texture
      partial_repaint_blit_required,            // requires_blit
      clip_rect                                 // clip_rect
      ));
}

References drawable(), texture, impeller::TextureMTL::Wrapper(), and impeller::WrapTextureWithRenderTarget().

Referenced by MakeFromMetalLayerDrawable().

PreparePresent()

bool impeller::SurfaceMTL::PreparePresent

(

)

const

Perform the final blit and trigger end of frame workloads.

Definition at line 216 of file surface_mtl.mm.

                                      {
  auto context = context_.lock();
  if (!context) {
    return false;
  }
 
#ifdef IMPELLER_DEBUG
  context->GetResourceAllocator()->DebugTraceMemoryStatistics();
  if (frame_boundary_) {
    ContextMTL::Cast(context.get())->GetCaptureManager()->FinishCapture();
  }
#endif  // IMPELLER_DEBUG
 
  if (requires_blit_) {
    if (!(source_texture_ && destination_texture_)) {
      return false;
    }
 
    auto blit_command_buffer = context->CreateCommandBuffer();
    if (!blit_command_buffer) {
      return false;
    }
    auto blit_pass = blit_command_buffer->CreateBlitPass();
    if (!clip_rect_.has_value()) {
      VALIDATION_LOG << "Missing clip rectangle.";
      return false;
    }
    blit_pass->AddCopy(source_texture_, destination_texture_, clip_rect_,
                       clip_rect_->GetOrigin());
    blit_pass->EncodeCommands();
    if (!context->GetCommandQueue()->Submit({blit_command_buffer}).ok()) {
      return false;
    }
  }
#ifdef IMPELLER_DEBUG
  ContextMTL::Cast(context.get())->GetGPUTracer()->MarkFrameEnd();
#endif  // IMPELLER_DEBUG
  prepared_ = true;
  return true;
}

References impeller::BackendCast< ContextMTL, Context >::Cast(), impeller::ContextMTL::CreateCommandBuffer(), and VALIDATION_LOG.

Referenced by Present().

Present()

bool impeller::SurfaceMTL::Present ( ) const

overridevirtual

Reimplemented from impeller::Surface.

Definition at line 258 of file surface_mtl.mm.

                               {
  if (!prepared_) {
    PreparePresent();
  }
  auto context = context_.lock();
  if (!context) {
    return false;
  }
 
  if (drawable_) {
    id<MTLCommandBuffer> command_buffer =
        ContextMTL::Cast(context.get())
            ->CreateMTLCommandBuffer("Present Waiter Command Buffer");
 
    id<CAMetalDrawable> metal_drawable =
        reinterpret_cast<id<CAMetalDrawable>>(drawable_);
    if ([metal_drawable conformsToProtocol:@protocol(FlutterMetalDrawable)]) {
      [(id<FlutterMetalDrawable>)metal_drawable
          flutterPrepareForPresent:command_buffer];
    }
 
    // Intel iOS simulators do not seem to give backpressure on Metal drawable
    // aquisition, which can result in Impeller running head of the GPU
    // workload by dozens of frames. Slow this process down by blocking
    // on submit until the last command buffer is at least scheduled.
#if defined(FML_OS_IOS_SIMULATOR) && defined(FML_ARCH_CPU_X86_64)
    constexpr bool alwaysWaitForScheduling = true;
#else
    constexpr bool alwaysWaitForScheduling = false;
#endif  // defined(FML_OS_IOS_SIMULATOR) && defined(FML_ARCH_CPU_X86_64)
 
    // If the threads have been merged, or there is a pending frame capture,
    // then block on cmd buffer scheduling to ensure that the
    // transaction/capture work correctly.
    if (present_with_transaction_ || [[NSThread currentThread] isMainThread] ||
        [[MTLCaptureManager sharedCaptureManager] isCapturing] ||
        alwaysWaitForScheduling) {
      TRACE_EVENT0("flutter", "waitUntilScheduled");
      [command_buffer commit];
#if defined(FML_OS_IOS_SIMULATOR) && defined(FML_ARCH_CPU_X86_64)
      [command_buffer waitUntilCompleted];
#else
      [command_buffer waitUntilScheduled];
#endif  // defined(FML_OS_IOS_SIMULATOR) && defined(FML_ARCH_CPU_X86_64)
      [drawable_ present];
    } else {
      // The drawable may come from a FlutterMetalLayer, so it can't be
      // presented through the command buffer.
      id<CAMetalDrawable> drawable = drawable_;
      [command_buffer addScheduledHandler:^(id<MTLCommandBuffer> buffer) {
        [drawable present];
      }];
      [command_buffer commit];
    }
  }
 
  return true;
}

References impeller::BackendCast< ContextMTL, Context >::Cast(), impeller::ContextMTL::CreateMTLCommandBuffer(), drawable(), PreparePresent(), and TRACE_EVENT0.

PresentWithTransaction()

void impeller::SurfaceMTL::PresentWithTransaction ( bool  present_with_transaction )

inline

Mark this surface as presenting with a transaction.

If true, [Present] will block on the scheduling of a command buffer.

Definition at line 67 of file surface_mtl.h.

                                                             {
    present_with_transaction_ = present_with_transaction;
  }

SetFrameBoundary()

void impeller::SurfaceMTL::SetFrameBoundary ( bool  frame_boundary )

inline

Definition at line 77 of file surface_mtl.h.

                                             {
    frame_boundary_ = frame_boundary;
  }

---

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

• impeller/renderer/backend/metal/surface_mtl.h
• impeller/renderer/backend/metal/surface_mtl.mm