#include <context_mtl.h>

Inheritance diagram for impeller::ContextMTL:

Public Member Functions
	~ContextMTL () override

BackendType	GetBackendType () const override
	Get the graphics backend of an Impeller context.

id< MTLDevice >	GetMTLDevice () const

std::string	DescribeGpuModel () const override

bool	IsValid () const override
	Determines if a context is valid. If the caller ever receives an invalid context, they must discard it and construct a new context. There is no recovery mechanism to repair a bad context.

std::shared_ptr< Allocator >	GetResourceAllocator () const override
	Returns the allocator used to create textures and buffers on the device.

std::shared_ptr< ShaderLibrary >	GetShaderLibrary () const override
	Returns the library of shaders used to specify the programmable stages of a pipeline.

std::shared_ptr< SamplerLibrary >	GetSamplerLibrary () const override
	Returns the library of combined image samplers used in shaders.

std::shared_ptr< PipelineLibrary >	GetPipelineLibrary () const override
	Returns the library of pipelines used by render or compute commands.

std::shared_ptr< CommandBuffer >	CreateCommandBuffer () const override
	Create a new command buffer. Command buffers can be used to encode graphics, blit, or compute commands to be submitted to the device.

std::shared_ptr< CommandQueue >	GetCommandQueue () const override
	Return the graphics queue for submitting command buffers.

const std::shared_ptr< const Capabilities > &	GetCapabilities () const override
	Get the capabilities of Impeller context. All optionally supported feature of the platform, client-rendering API, and device can be queried using the `Capabilities`.

RuntimeStageBackend	GetRuntimeStageBackend () const override
	Retrieve the runtime stage for this context type.

void	SetCapabilities (const std::shared_ptr< const Capabilities > &capabilities)

bool	UpdateOffscreenLayerPixelFormat (PixelFormat format) override

void	Shutdown () override
	Force all pending asynchronous work to finish. This is achieved by deleting all owned concurrent message loops.

id< MTLCommandBuffer >	CreateMTLCommandBuffer (const std::string &label) const

std::shared_ptr< const fml::SyncSwitch >	GetIsGpuDisabledSyncSwitch () const

void	StoreTaskForGPU (const fml::closure &task, const fml::closure &failure) override

void	FlushTasksAwaitingGPU ()

bool	FinishQueue () override
	Wait until all previously submitted command buffers are processed and displayed by the GPU.

Public Member Functions inherited from impeller::Context
virtual	~Context ()
	Destroys an Impeller context.

virtual void	InitializeCommonlyUsedShadersIfNeeded () const

virtual void	DisposeThreadLocalCachedResources ()

virtual bool	EnqueueCommandBuffer (std::shared_ptr< CommandBuffer > command_buffer)
	Enqueue command_buffer for submission by the end of the frame.

virtual bool	FlushCommandBuffers ()
	Flush all pending command buffers.

virtual bool	AddTrackingFence (const std::shared_ptr< Texture > &texture) const

virtual std::shared_ptr< const IdleWaiter >	GetIdleWaiter () const

virtual void	ResetThreadLocalState () const

virtual bool	SubmitOnscreen (std::shared_ptr< CommandBuffer > cmd_buffer)
	Submit the command buffer that renders to the onscreen surface.

const Flags &	GetFlags () const

Static Public Member Functions
static std::shared_ptr< ContextMTL >	Create (const Flags &flags, const std::vector< std::string > &shader_library_paths, std::shared_ptr< const fml::SyncSwitch > is_gpu_disabled_sync_switch)

static std::shared_ptr< ContextMTL >	Create (const Flags &flags, const std::vector< std::shared_ptr< fml::Mapping > > &shader_libraries_data, std::shared_ptr< const fml::SyncSwitch > is_gpu_disabled_sync_switch, const std::string &label, std::optional< PixelFormat > pixel_format_override=std::nullopt)

static std::shared_ptr< ContextMTL >	Create (const Flags &flags, id< MTLDevice > device, id< MTLCommandQueue > command_queue, const std::vector< std::shared_ptr< fml::Mapping > > &shader_libraries_data, std::shared_ptr< const fml::SyncSwitch > is_gpu_disabled_sync_switch, const std::string &label)

Static Public Member Functions inherited from impeller::BackendCast< ContextMTL, Context >
static ContextMTL &	Cast (Context &base)

static const ContextMTL &	Cast (const Context &base)

static ContextMTL *	Cast (Context *base)

static const ContextMTL *	Cast (const Context *base)

Additional Inherited Members
Public Types inherited from impeller::Context
enum class	BackendType { kMetal , kOpenGLES , kVulkan }

Static Public Attributes inherited from impeller::Context
static constexpr int32_t	kMaxTasksAwaitingGPU = 1024

Protected Member Functions inherited from impeller::Context
	Context (const Flags &flags)

Protected Attributes inherited from impeller::Context
Flags	flags_

std::vector< std::function< void()> >	per_frame_task_

Detailed Description

Definition at line 65 of file context_mtl.h.

Constructor & Destructor Documentation

◆ ~ContextMTL()

impeller::ContextMTL::~ContextMTL ( )

override

Definition at line 324 of file context_mtl.mm.

                        {
  is_gpu_disabled_sync_switch_->RemoveObserver(sync_switch_observer_.get());
}

Member Function Documentation

◆ Create() [1/3]

std::shared_ptr< ContextMTL > impeller::ContextMTL::Create	(	const Flags &	flags,
		const std::vector< std::shared_ptr< fml::Mapping > > &	shader_libraries_data,
		std::shared_ptr< const fml::SyncSwitch >	is_gpu_disabled_sync_switch,
		const std::string &	label,
		std::optional< PixelFormat >	pixel_format_override = `std::nullopt`
	)

static

Definition at line 282 of file context_mtl.mm.

                                                    {
  auto device = CreateMetalDevice();
  auto command_queue = CreateMetalCommandQueue(device);
  if (!command_queue) {
    return nullptr;
  }
  auto context = std::shared_ptr<ContextMTL>(new ContextMTL(
      flags, device, command_queue,
      MTLShaderLibraryFromFileData(device, shader_libraries_data,
                                   library_label),
      std::move(is_gpu_disabled_sync_switch), pixel_format_override));
  if (!context->IsValid()) {
    FML_LOG(ERROR) << "Could not create Metal context.";
    return nullptr;
  }
  return context;
}

References context, impeller::CreateMetalCommandQueue(), impeller::CreateMetalDevice(), device, FML_LOG, and impeller::MTLShaderLibraryFromFileData().

◆ Create() [2/3]

std::shared_ptr< ContextMTL > impeller::ContextMTL::Create	(	const Flags &	flags,
		const std::vector< std::string > &	shader_library_paths,
		std::shared_ptr< const fml::SyncSwitch >	is_gpu_disabled_sync_switch
	)

static

Definition at line 262 of file context_mtl.mm.

                                                                    {
  auto device = CreateMetalDevice();
  auto command_queue = CreateMetalCommandQueue(device);
  if (!command_queue) {
    return nullptr;
  }
  auto context = std::shared_ptr<ContextMTL>(new ContextMTL(
      flags, device, command_queue,
      MTLShaderLibraryFromFilePaths(device, shader_library_paths),
      std::move(is_gpu_disabled_sync_switch)));
  if (!context->IsValid()) {
    FML_LOG(ERROR) << "Could not create Metal context.";
    return nullptr;
  }
  return context;
}

References context, impeller::CreateMetalCommandQueue(), impeller::CreateMetalDevice(), device, FML_LOG, and impeller::MTLShaderLibraryFromFilePaths().

Referenced by impeller::interop::ContextMTL::Create(), FlutterDarwinContextMetalImpeller::createExternalTextureWithIdentifier:texture:, flutter::testing::CreateImpellerContext(), CreateImpellerContext(), flutter::EmbedderSurfaceMetalImpeller::EmbedderSurfaceMetalImpeller(), flutter::TesterContextMTL::Initialize(), and impeller::PlaygroundImplMTL::PlaygroundImplMTL().

◆ Create() [3/3]

std::shared_ptr< ContextMTL > impeller::ContextMTL::Create	(	const Flags &	flags,
		id< MTLDevice >	device,
		id< MTLCommandQueue >	command_queue,
		const std::vector< std::shared_ptr< fml::Mapping > > &	shader_libraries_data,
		std::shared_ptr< const fml::SyncSwitch >	is_gpu_disabled_sync_switch,
		const std::string &	label
	)

static

Definition at line 305 of file context_mtl.mm.

                                    {
  auto context = std::shared_ptr<ContextMTL>(
      new ContextMTL(flags, device, command_queue,
                     MTLShaderLibraryFromFileData(device, shader_libraries_data,
                                                  library_label),
                     std::move(is_gpu_disabled_sync_switch)));
  if (!context->IsValid()) {
    FML_LOG(ERROR) << "Could not create Metal context.";
    return nullptr;
  }
  return context;
}

References context, device, FML_LOG, and impeller::MTLShaderLibraryFromFileData().

◆ CreateCommandBuffer()

std::shared_ptr< CommandBuffer > impeller::ContextMTL::CreateCommandBuffer ( ) const

overridevirtual

Create a new command buffer. Command buffers can be used to encode graphics, blit, or compute commands to be submitted to the device.

A command buffer can only be used on a single thread. Multi-threaded render, blit, or compute passes must create a new command buffer on each thread.

Returns: A new command buffer.

Implements impeller::Context.

Definition at line 358 of file context_mtl.mm.

                                                                   {
  return CreateCommandBufferInQueue(command_queue_);
}

Referenced by impeller::SurfaceMTL::PreparePresent().

◆ CreateMTLCommandBuffer()

id< MTLCommandBuffer > impeller::ContextMTL::CreateMTLCommandBuffer ( const std::string & label ) const

Definition at line 413 of file context_mtl.mm.

                                  {
  auto buffer = [command_queue_ commandBuffer];
  if (!label.empty()) {
    [buffer setLabel:@(label.data())];
  }
  return buffer;
}

Referenced by impeller::SurfaceMTL::Present().

◆ DescribeGpuModel()

std::string impeller::ContextMTL::DescribeGpuModel ( ) const

overridevirtual

Implements impeller::Context.

Definition at line 333 of file context_mtl.mm.

                                             {
  return std::string([[device_ name] UTF8String]);
}

References name.

◆ FinishQueue()

bool impeller::ContextMTL::FinishQueue ( )

overridevirtual

Wait until all previously submitted command buffers are processed and displayed by the GPU.

WARNING: This method call is unnecessary for nearly all use cases since asynchronous workloads are the expected norm and calling this method can negatively affect application performance. Its only use is for cases like benchmarking where proper performance metrics can only be collected by including all background processing of the GPU.

Outstanding unflushed command buffers are not committed, submitted, or enqueued by this method and such buffers should have already been flushed before this method is called. The method will only wait for work to be done that has already been submitted to the GPU.

Returns: True if the queue was successfully processed, otherwise false if there was an error or if the backend does not support synchronous reporting of completion. Implementations intended entirely for testing might simply return false, but they would not be used for benchmarking or other situations where we might measure GPU performance.

Implements impeller::Context.

Definition at line 477 of file context_mtl.mm.

                             {
  id<MTLCommandBuffer> command_buffer =
      ContextMTL::Cast(this)->CreateMTLCommandBuffer("Finish Queue Waiter");
  [command_buffer commit];
  // clang-format off
  // This isn't documented in the method, but there are places where they
  // imply that they will wait even for an empty buffer...
  //
  // See https://developer.apple.com/documentation/metalperformanceshaders/tuning-hints
  // clang-format on
  [command_buffer waitUntilCompleted];
  return true;
}

References command_buffer.

◆ FlushTasksAwaitingGPU()

void impeller::ContextMTL::FlushTasksAwaitingGPU ( )

Definition at line 448 of file context_mtl.mm.

                                       {
  std::deque<PendingTasks> tasks_awaiting_gpu;
  {
    Lock lock(tasks_awaiting_gpu_mutex_);
    std::swap(tasks_awaiting_gpu, tasks_awaiting_gpu_);
  }
  std::vector<PendingTasks> tasks_to_queue;
  for (const auto& task : tasks_awaiting_gpu) {
    is_gpu_disabled_sync_switch_->Execute(fml::SyncSwitch::Handlers()
                                              .SetIfFalse([&] { task.task(); })
                                              .SetIfTrue([&] {
                                                // Lost access to the GPU
                                                // immediately after it was
                                                // activated. This may happen if
                                                // the app was quickly
                                                // foregrounded/backgrounded
                                                // from a push notification.
                                                // Store the tasks on the
                                                // context again.
                                                tasks_to_queue.push_back(task);
                                              }));
  }
  if (!tasks_to_queue.empty()) {
    Lock lock(tasks_awaiting_gpu_mutex_);
    tasks_awaiting_gpu_.insert(tasks_awaiting_gpu_.end(),
                               tasks_to_queue.begin(), tasks_to_queue.end());
  }
}

References fml::SyncSwitch::Handlers::SetIfFalse().

◆ GetBackendType()

Context::BackendType impeller::ContextMTL::GetBackendType ( ) const

overridevirtual

Get the graphics backend of an Impeller context.

        This is useful for cases where a renderer needs to track and
        lookup backend-specific resources, like shaders or uniform
        layout information.

        It's not recommended to use this as a substitute for
        per-backend capability checking. Instead, check for specific
        capabilities via `GetCapabilities()`.

Returns: The graphics backend of the Context.

Implements impeller::Context.

Definition at line 328 of file context_mtl.mm.

                                                    {
  return Context::BackendType::kMetal;
}

◆ GetCapabilities()

const std::shared_ptr< const Capabilities > & impeller::ContextMTL::GetCapabilities ( ) const

overridevirtual

Get the capabilities of Impeller context. All optionally supported feature of the platform, client-rendering API, and device can be queried using the Capabilities.

Returns: The capabilities. Can never be nullptr for a valid context.

Implements impeller::Context.

Definition at line 398 of file context_mtl.mm.

                                                                           {
  return device_capabilities_;
}

◆ GetCommandQueue()

std::shared_ptr< CommandQueue > impeller::ContextMTL::GetCommandQueue ( ) const

overridevirtual

Return the graphics queue for submitting command buffers.

Implements impeller::Context.

Definition at line 501 of file context_mtl.mm.

                                                              {
  return command_queue_ip_;
}

◆ GetIsGpuDisabledSyncSwitch()

std::shared_ptr< const fml::SyncSwitch > impeller::ContextMTL::GetIsGpuDisabledSyncSwitch ( ) const

Definition at line 371 of file context_mtl.mm.

          {
  return is_gpu_disabled_sync_switch_;
}

◆ GetMTLDevice()

id< MTLDevice > impeller::ContextMTL::GetMTLDevice ( ) const

Definition at line 394 of file context_mtl.mm.

                                             {
  return device_;
}

Referenced by impeller::PlaygroundImplMTL::PlaygroundImplMTL().

◆ GetPipelineLibrary()

std::shared_ptr< PipelineLibrary > impeller::ContextMTL::GetPipelineLibrary ( ) const

overridevirtual

Returns the library of pipelines used by render or compute commands.

Returns: The pipeline library. Can never be nullptr for a valid context.

Implements impeller::Context.

Definition at line 348 of file context_mtl.mm.

                                                                    {
  return pipeline_library_;
}

◆ GetResourceAllocator()

std::shared_ptr< Allocator > impeller::ContextMTL::GetResourceAllocator ( ) const

overridevirtual

Returns the allocator used to create textures and buffers on the device.

Returns: The resource allocator. Can never be nullptr for a valid context.

Implements impeller::Context.

Definition at line 390 of file context_mtl.mm.

                                                                {
  return resource_allocator_;
}

◆ GetRuntimeStageBackend()

RuntimeStageBackend impeller::ContextMTL::GetRuntimeStageBackend ( ) const

overridevirtual

Retrieve the runtime stage for this context type.

This is used by the engine shell and other subsystems for loading the correct shader types.

Implements impeller::Context.

Definition at line 506 of file context_mtl.mm.

                                                             {
  return RuntimeStageBackend::kMetal;
}

References impeller::kMetal.

◆ GetSamplerLibrary()

std::shared_ptr< SamplerLibrary > impeller::ContextMTL::GetSamplerLibrary ( ) const

overridevirtual

Returns the library of combined image samplers used in shaders.

Returns: The sampler library. Can never be nullptr for a valid context.

Implements impeller::Context.

Definition at line 353 of file context_mtl.mm.

                                                                  {
  return sampler_library_;
}

◆ GetShaderLibrary()

std::shared_ptr< ShaderLibrary > impeller::ContextMTL::GetShaderLibrary ( ) const

overridevirtual

Returns the library of shaders used to specify the programmable stages of a pipeline.

Returns: The shader library. Can never be nullptr for a valid context.

Implements impeller::Context.

Definition at line 343 of file context_mtl.mm.

                                                                {
  return shader_library_;
}

◆ IsValid()

bool impeller::ContextMTL::IsValid ( ) const

overridevirtual

Determines if a context is valid. If the caller ever receives an invalid context, they must discard it and construct a new context. There is no recovery mechanism to repair a bad context.

It is convention in Impeller to never return an invalid context from a call that returns an pointer to a context. The call implementation performs validity checks itself and return a null context instead of a pointer to an invalid context.

How a context goes invalid is backend specific. It could happen due to device loss, or any other unrecoverable error.

Returns: If the context is valid.

Implements impeller::Context.

Definition at line 338 of file context_mtl.mm.

                               {
  return is_valid_;
}

◆ SetCapabilities()

void impeller::ContextMTL::SetCapabilities ( const std::shared_ptr< const Capabilities > & capabilities )

Definition at line 402 of file context_mtl.mm.

                                                           {
  device_capabilities_ = capabilities;
}

◆ Shutdown()

void impeller::ContextMTL::Shutdown ( )

overridevirtual

Force all pending asynchronous work to finish. This is achieved by deleting all owned concurrent message loops.

Implements impeller::Context.

Definition at line 363 of file context_mtl.mm.

363{}

◆ StoreTaskForGPU()

void impeller::ContextMTL::StoreTaskForGPU	(	const fml::closure &	task,
		const fml::closure &	failure
	)

overridevirtual

Stores a task on the ContextMTL that is awaiting access for the GPU.

The task will be executed in the event that the GPU access has changed to being available or that the task has been canceled. The task should operate with the SyncSwitch to make sure the GPU is accessible.

If the queue of pending tasks is cleared without GPU access, then the failure callback will be invoked and the primary task function will not

Threadsafe.

task will be executed on the platform thread.

Reimplemented from impeller::Context.

Definition at line 422 of file context_mtl.mm.

                                                            {
  std::vector<PendingTasks> failed_tasks;
  {
    Lock lock(tasks_awaiting_gpu_mutex_);
    tasks_awaiting_gpu_.push_back(PendingTasks{task, failure});
    int32_t failed_task_count =
        tasks_awaiting_gpu_.size() - kMaxTasksAwaitingGPU;
    if (failed_task_count > 0) {
      failed_tasks.reserve(failed_task_count);
      failed_tasks.insert(failed_tasks.end(),
                          std::make_move_iterator(tasks_awaiting_gpu_.begin()),
                          std::make_move_iterator(tasks_awaiting_gpu_.begin() +
                                                  failed_task_count));
      tasks_awaiting_gpu_.erase(
          tasks_awaiting_gpu_.begin(),
          tasks_awaiting_gpu_.begin() + failed_task_count);
    }
  }
  for (const PendingTasks& task : failed_tasks) {
    if (task.failure) {
      task.failure();
    }
  }
}

◆ UpdateOffscreenLayerPixelFormat()

bool impeller::ContextMTL::UpdateOffscreenLayerPixelFormat ( PixelFormat format )

overridevirtual

Reimplemented from impeller::Context.

Definition at line 408 of file context_mtl.mm.

                                                                   {
  device_capabilities_ = InferMetalCapabilities(device_, format);
  return true;
}

References format, and impeller::InferMetalCapabilities().

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

impeller/renderer/backend/metal/context_mtl.h
impeller/renderer/backend/metal/context_mtl.mm

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ~ContextMTL()

Member Function Documentation

◆ Create() [1/3]

◆ Create() [2/3]

◆ Create() [3/3]

◆ CreateCommandBuffer()

◆ CreateMTLCommandBuffer()

◆ DescribeGpuModel()

◆ FinishQueue()

◆ FlushTasksAwaitingGPU()

◆ GetBackendType()

◆ GetCapabilities()

◆ GetCommandQueue()

◆ GetIsGpuDisabledSyncSwitch()

◆ GetMTLDevice()

◆ GetPipelineLibrary()

◆ GetResourceAllocator()

◆ GetRuntimeStageBackend()

◆ GetSamplerLibrary()

◆ GetShaderLibrary()

◆ IsValid()

◆ SetCapabilities()

◆ Shutdown()

◆ StoreTaskForGPU()

◆ UpdateOffscreenLayerPixelFormat()