| Flutter Impeller |

Classes | Public Member Functions | Static Public Member Functions | List of all members
impeller::ContextMTL Class Referencefinal

`#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. 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< Allocator > | GetResourceAllocator () const override
| Returns the allocator used to create textures and buffers on the device. More...
std::shared_ptr< ShaderLibrary > | GetShaderLibrary () const override
| Returns the library of shaders used to specify the programmable stages of a pipeline. More...
std::shared_ptr< SamplerLibrary > | GetSamplerLibrary () const override
| Returns the library of combined image samplers used in shaders. More...
std::shared_ptr< PipelineLibrary > | GetPipelineLibrary () const override
| Returns the library of pipelines used by render or compute commands. More...
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. More...
std::shared_ptr< CommandQueue > | GetCommandQueue () 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 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. More...
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 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 }
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:172
impeller::CreateMetalDevice
static id< MTLDevice > CreateMetalDevice()
Definition: context_mtl.mm:215
impeller::CreateMetalCommandQueue
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 }
impeller::MTLShaderLibraryFromFilePaths
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.

295 {
296 return Context::BackendType::kMetal;
297 }
impeller::Context::BackendType::kMetal
@ 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 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.

459 {
460 return RuntimeStageBackend::kMetal;
461 }
impeller::RuntimeStageBackend::kMetal
@ 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 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 }
impeller::Context::kMaxTasksAwaitingGPU
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 }
impeller::InferMetalCapabilities
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:

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