Flutter Impeller
impeller::ContextMTL Class Referencefinal

#include <context_mtl.h>

Inheritance diagram for impeller::ContextMTL:
impeller::Context impeller::BackendCast< ContextMTL, Context >

Public Member Functions

 ~ContextMTL () override
 
BackendType GetBackendType () const override
 Get the graphics backend of an Impeller context. More...
 
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. More...
 
std::shared_ptr< AllocatorGetResourceAllocator () const override
 Returns the allocator used to create textures and buffers on the device. More...
 
std::shared_ptr< ShaderLibraryGetShaderLibrary () const override
 Returns the library of shaders used to specify the programmable stages of a pipeline. More...
 
std::shared_ptr< SamplerLibraryGetSamplerLibrary () const override
 Returns the library of combined image samplers used in shaders. More...
 
std::shared_ptr< PipelineLibraryGetPipelineLibrary () const override
 Returns the library of pipelines used by render or compute commands. More...
 
std::shared_ptr< CommandBufferCreateCommandBuffer () 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. More...
 
std::shared_ptr< CommandQueueGetCommandQueue () const override
 Return the graphics queue for submitting command buffers. More...
 
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. More...
 
RuntimeStageBackend GetRuntimeStageBackend () const override
 Retrieve the runtime stage for this context type. More...
 
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. More...
 
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 ()
 
- Public Member Functions inherited from impeller::Context
virtual ~Context ()
 Destroys an Impeller context. More...
 
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. More...
 
virtual bool FlushCommandBuffers ()
 Flush all pending command buffers. More...
 
virtual bool AddTrackingFence (const std::shared_ptr< Texture > &texture) const
 
virtual std::shared_ptr< const IdleWaiterGetIdleWaiter () const
 
virtual void ResetThreadLocalState () const
 
virtual bool SubmitOnscreen (std::shared_ptr< CommandBuffer > cmd_buffer)
 Submit the command buffer that renders to the onscreen surface. More...
 
const FlagsGetFlags () const
 

Static Public Member Functions

static std::shared_ptr< ContextMTLCreate (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< ContextMTLCreate (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< ContextMTLCreate (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 ContextMTLCast (Context &base)
 
static const ContextMTLCast (const Context &base)
 
static ContextMTLCast (Context *base)
 
static const ContextMTLCast (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 291 of file context_mtl.mm.

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

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 249 of file context_mtl.mm.

254  {
255  auto device = CreateMetalDevice();
256  auto command_queue = CreateMetalCommandQueue(device);
257  if (!command_queue) {
258  return nullptr;
259  }
260  auto context = std::shared_ptr<ContextMTL>(new ContextMTL(
261  flags, device, command_queue,
262  MTLShaderLibraryFromFileData(device, shader_libraries_data,
263  library_label),
264  std::move(is_gpu_disabled_sync_switch), pixel_format_override));
265  if (!context->IsValid()) {
266  FML_LOG(ERROR) << "Could not create Metal context.";
267  return nullptr;
268  }
269  return context;
270 }
static NSArray< id< MTLLibrary > > * MTLShaderLibraryFromFileData(id< MTLDevice > device, const std::vector< std::shared_ptr< fml::Mapping >> &libraries_data, const std::string &label)
Definition: context_mtl.mm:172
static id< MTLDevice > CreateMetalDevice()
Definition: context_mtl.mm:215
static id< MTLCommandQueue > CreateMetalCommandQueue(id< MTLDevice > device)
Definition: context_mtl.mm:219

References impeller::CreateMetalCommandQueue(), impeller::CreateMetalDevice(), 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 229 of file context_mtl.mm.

232  {
233  auto device = CreateMetalDevice();
234  auto command_queue = CreateMetalCommandQueue(device);
235  if (!command_queue) {
236  return nullptr;
237  }
238  auto context = std::shared_ptr<ContextMTL>(new ContextMTL(
239  flags, device, command_queue,
240  MTLShaderLibraryFromFilePaths(device, shader_library_paths),
241  std::move(is_gpu_disabled_sync_switch)));
242  if (!context->IsValid()) {
243  FML_LOG(ERROR) << "Could not create Metal context.";
244  return nullptr;
245  }
246  return context;
247 }
static NSArray< id< MTLLibrary > > * MTLShaderLibraryFromFilePaths(id< MTLDevice > device, const std::vector< std::string > &libraries_paths)
Definition: context_mtl.mm:149

References impeller::CreateMetalCommandQueue(), impeller::CreateMetalDevice(), and impeller::MTLShaderLibraryFromFilePaths().

Referenced by impeller::interop::ContextMTL::Create(), 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 272 of file context_mtl.mm.

278  {
279  auto context = std::shared_ptr<ContextMTL>(
280  new ContextMTL(flags, device, command_queue,
281  MTLShaderLibraryFromFileData(device, shader_libraries_data,
282  library_label),
283  std::move(is_gpu_disabled_sync_switch)));
284  if (!context->IsValid()) {
285  FML_LOG(ERROR) << "Could not create Metal context.";
286  return nullptr;
287  }
288  return context;
289 }

References 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 325 of file context_mtl.mm.

325  {
326  return CreateCommandBufferInQueue(command_queue_);
327 }

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

◆ CreateMTLCommandBuffer()

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

Definition at line 380 of file context_mtl.mm.

381  {
382  auto buffer = [command_queue_ commandBuffer];
383  if (!label.empty()) {
384  [buffer setLabel:@(label.data())];
385  }
386  return buffer;
387 }

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

◆ DescribeGpuModel()

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

Implements impeller::Context.

Definition at line 300 of file context_mtl.mm.

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

◆ FlushTasksAwaitingGPU()

void impeller::ContextMTL::FlushTasksAwaitingGPU ( )

Definition at line 415 of file context_mtl.mm.

415  {
416  std::deque<PendingTasks> tasks_awaiting_gpu;
417  {
418  Lock lock(tasks_awaiting_gpu_mutex_);
419  std::swap(tasks_awaiting_gpu, tasks_awaiting_gpu_);
420  }
421  std::vector<PendingTasks> tasks_to_queue;
422  for (const auto& task : tasks_awaiting_gpu) {
423  is_gpu_disabled_sync_switch_->Execute(fml::SyncSwitch::Handlers()
424  .SetIfFalse([&] { task.task(); })
425  .SetIfTrue([&] {
426  // Lost access to the GPU
427  // immediately after it was
428  // activated. This may happen if
429  // the app was quickly
430  // foregrounded/backgrounded
431  // from a push notification.
432  // Store the tasks on the
433  // context again.
434  tasks_to_queue.push_back(task);
435  }));
436  }
437  if (!tasks_to_queue.empty()) {
438  Lock lock(tasks_awaiting_gpu_mutex_);
439  tasks_awaiting_gpu_.insert(tasks_awaiting_gpu_.end(),
440  tasks_to_queue.begin(), tasks_to_queue.end());
441  }
442 }

◆ 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 295 of file context_mtl.mm.

◆ 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 365 of file context_mtl.mm.

365  {
366  return device_capabilities_;
367 }

◆ GetCommandQueue()

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

Return the graphics queue for submitting command buffers.

Implements impeller::Context.

Definition at line 454 of file context_mtl.mm.

454  {
455  return command_queue_ip_;
456 }

◆ GetIsGpuDisabledSyncSwitch()

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

Definition at line 338 of file context_mtl.mm.

339  {
340  return is_gpu_disabled_sync_switch_;
341 }

◆ GetMTLDevice()

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

Definition at line 361 of file context_mtl.mm.

361  {
362  return device_;
363 }

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 315 of file context_mtl.mm.

315  {
316  return pipeline_library_;
317 }

◆ 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 357 of file context_mtl.mm.

357  {
358  return resource_allocator_;
359 }

◆ 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 459 of file context_mtl.mm.

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 320 of file context_mtl.mm.

320  {
321  return sampler_library_;
322 }

◆ 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 310 of file context_mtl.mm.

310  {
311  return shader_library_;
312 }

◆ 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 305 of file context_mtl.mm.

305  {
306  return is_valid_;
307 }

◆ SetCapabilities()

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

Definition at line 369 of file context_mtl.mm.

370  {
371  device_capabilities_ = capabilities;
372 }

◆ 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 330 of file context_mtl.mm.

330 {}

◆ 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 389 of file context_mtl.mm.

390  {
391  std::vector<PendingTasks> failed_tasks;
392  {
393  Lock lock(tasks_awaiting_gpu_mutex_);
394  tasks_awaiting_gpu_.push_back(PendingTasks{task, failure});
395  int32_t failed_task_count =
396  tasks_awaiting_gpu_.size() - kMaxTasksAwaitingGPU;
397  if (failed_task_count > 0) {
398  failed_tasks.reserve(failed_task_count);
399  failed_tasks.insert(failed_tasks.end(),
400  std::make_move_iterator(tasks_awaiting_gpu_.begin()),
401  std::make_move_iterator(tasks_awaiting_gpu_.begin() +
402  failed_task_count));
403  tasks_awaiting_gpu_.erase(
404  tasks_awaiting_gpu_.begin(),
405  tasks_awaiting_gpu_.begin() + failed_task_count);
406  }
407  }
408  for (const PendingTasks& task : failed_tasks) {
409  if (task.failure) {
410  task.failure();
411  }
412  }
413 }
static constexpr int32_t kMaxTasksAwaitingGPU
Definition: context.h:79

◆ UpdateOffscreenLayerPixelFormat()

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

Reimplemented from impeller::Context.

Definition at line 375 of file context_mtl.mm.

375  {
376  device_capabilities_ = InferMetalCapabilities(device_, format);
377  return true;
378 }
static std::unique_ptr< Capabilities > InferMetalCapabilities(id< MTLDevice > device, PixelFormat color_format)
Definition: context_mtl.mm:49

References impeller::InferMetalCapabilities().


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