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...
 
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 std::function< void()> &task) override
 
- Public Member Functions inherited from impeller::Context
virtual ~Context ()
 Destroys an Impeller context. More...
 
virtual void InitializeCommonlyUsedShadersIfNeeded () const
 

Static Public Member Functions

static std::shared_ptr< ContextMTLCreate (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 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 std::shared_ptr< ContextMTLCreate (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  BackendType {
  BackendType::kMetal,
  BackendType::kOpenGLES,
  BackendType::kVulkan
}
 
- Public Attributes inherited from impeller::Context
CaptureContext capture
 
- Static Public Attributes inherited from impeller::Context
static constexpr int32_t kMaxTasksAwaitingGPU = 10
 
- Protected Member Functions inherited from impeller::Context
 Context ()
 
- Protected Attributes inherited from impeller::Context
std::vector< std::function< void()> > per_frame_task_
 

Detailed Description

Definition at line 35 of file context_mtl.h.

Constructor & Destructor Documentation

◆ ~ContextMTL()

impeller::ContextMTL::~ContextMTL ( )
override

Definition at line 277 of file context_mtl.mm.

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

Member Function Documentation

◆ Create() [1/3]

std::shared_ptr< ContextMTL > impeller::ContextMTL::Create ( 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 238 of file context_mtl.mm.

241  {
242  auto device = CreateMetalDevice();
243  auto command_queue = CreateMetalCommandQueue(device);
244  if (!command_queue) {
245  return nullptr;
246  }
247  auto context = std::shared_ptr<ContextMTL>(
248  new ContextMTL(device, command_queue,
249  MTLShaderLibraryFromFileData(device, shader_libraries_data,
250  library_label),
251  std::move(is_gpu_disabled_sync_switch)));
252  if (!context->IsValid()) {
253  FML_LOG(ERROR) << "Could not create Metal context.";
254  return nullptr;
255  }
256  return context;
257 }

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

◆ Create() [2/3]

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

Definition at line 219 of file context_mtl.mm.

221  {
222  auto device = CreateMetalDevice();
223  auto command_queue = CreateMetalCommandQueue(device);
224  if (!command_queue) {
225  return nullptr;
226  }
227  auto context = std::shared_ptr<ContextMTL>(new ContextMTL(
228  device, command_queue,
229  MTLShaderLibraryFromFilePaths(device, shader_library_paths),
230  std::move(is_gpu_disabled_sync_switch)));
231  if (!context->IsValid()) {
232  FML_LOG(ERROR) << "Could not create Metal context.";
233  return nullptr;
234  }
235  return context;
236 }

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

◆ Create() [3/3]

std::shared_ptr< ContextMTL > impeller::ContextMTL::Create ( 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 259 of file context_mtl.mm.

264  {
265  auto context = std::shared_ptr<ContextMTL>(
266  new ContextMTL(device, command_queue,
267  MTLShaderLibraryFromFileData(device, shader_libraries_data,
268  library_label),
269  std::move(is_gpu_disabled_sync_switch)));
270  if (!context->IsValid()) {
271  FML_LOG(ERROR) << "Could not create Metal context.";
272  return nullptr;
273  }
274  return context;
275 }

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

311  {
312  return CreateCommandBufferInQueue(command_queue_);
313 }

◆ CreateMTLCommandBuffer()

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

Definition at line 366 of file context_mtl.mm.

367  {
368  auto buffer = [command_queue_ commandBuffer];
369  if (!label.empty()) {
370  [buffer setLabel:@(label.data())];
371  }
372  return buffer;
373 }

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

◆ DescribeGpuModel()

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

Implements impeller::Context.

Definition at line 286 of file context_mtl.mm.

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

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

281  {
283 }

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

351  {
352  return device_capabilities_;
353 }

◆ GetCommandQueue()

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

Return the graphics queue for submitting command buffers.

Implements impeller::Context.

Definition at line 400 of file context_mtl.mm.

400  {
401  return command_queue_ip_;
402 }

◆ GetIsGpuDisabledSyncSwitch()

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

Definition at line 324 of file context_mtl.mm.

325  {
326  return is_gpu_disabled_sync_switch_;
327 }

◆ GetMTLDevice()

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

Definition at line 347 of file context_mtl.mm.

347  {
348  return device_;
349 }

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

301  {
302  return pipeline_library_;
303 }

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

343  {
344  return resource_allocator_;
345 }

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

306  {
307  return sampler_library_;
308 }

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

296  {
297  return shader_library_;
298 }

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

291  {
292  return is_valid_;
293 }

◆ SetCapabilities()

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

Definition at line 355 of file context_mtl.mm.

356  {
357  device_capabilities_ = capabilities;
358 }

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

316 {}

◆ StoreTaskForGPU()

void impeller::ContextMTL::StoreTaskForGPU ( const std::function< void()> &  task)
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.

Threadsafe.

task will be executed on the platform thread.

Reimplemented from impeller::Context.

Definition at line 375 of file context_mtl.mm.

375  {
376  tasks_awaiting_gpu_.emplace_back(task);
377  while (tasks_awaiting_gpu_.size() > kMaxTasksAwaitingGPU) {
378  tasks_awaiting_gpu_.front()();
379  tasks_awaiting_gpu_.pop_front();
380  }
381 }

◆ UpdateOffscreenLayerPixelFormat()

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

Reimplemented from impeller::Context.

Definition at line 361 of file context_mtl.mm.

361  {
362  device_capabilities_ = InferMetalCapabilities(device_, format);
363  return true;
364 }

References impeller::InferMetalCapabilities().


The documentation for this class was generated from the following files:
impeller::MTLShaderLibraryFromFileData
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:162
impeller::CreateMetalCommandQueue
static id< MTLCommandQueue > CreateMetalCommandQueue(id< MTLDevice > device)
Definition: context_mtl.mm:209
impeller::CreateMetalDevice
static id< MTLDevice > CreateMetalDevice()
Definition: context_mtl.mm:205
impeller::InferMetalCapabilities
static std::unique_ptr< Capabilities > InferMetalCapabilities(id< MTLDevice > device, PixelFormat color_format)
Definition: context_mtl.mm:53
impeller::Context::BackendType::kMetal
@ kMetal
impeller::MTLShaderLibraryFromFilePaths
static NSArray< id< MTLLibrary > > * MTLShaderLibraryFromFilePaths(id< MTLDevice > device, const std::vector< std::string > &libraries_paths)
Definition: context_mtl.mm:139
impeller::Context::kMaxTasksAwaitingGPU
static constexpr int32_t kMaxTasksAwaitingGPU
Definition: context.h:60