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

## Static Public Member Functions
static std::shared_ptr< ContextMTL > | Create (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 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 (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 | BackendType { BackendType::kMetal, BackendType::kOpenGLES, BackendType::kVulkan }
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 65 of file context_mtl.h.

## Constructor & Destructor Documentation

## ◆ ~ContextMTL()

impeller::ContextMTL::~ContextMTL | ( |  | ) |
| override

Definition at line 284 of file context_mtl.mm.

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

## 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,
|  | std::optional< PixelFormat > | pixel_format_override = `std::nullopt`
| ) |  |
| static

Definition at line 244 of file context_mtl.mm.

248 {
249 auto device = CreateMetalDevice();
250 auto command_queue = CreateMetalCommandQueue(device);
251 if (!command_queue) {
252 return nullptr;
253 }
254 auto context = std::shared_ptr<ContextMTL>(new ContextMTL(
255 device, command_queue,
256 MTLShaderLibraryFromFileData(device, shader_libraries_data,
257 library_label),
258 std::move(is_gpu_disabled_sync_switch), pixel_format_override));
259 if (!context->IsValid()) {
260 FML_LOG(ERROR) << "Could not create Metal context.";
261 return nullptr;
262 }
263 return context;
264 }

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

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

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

271 {
272 auto context = std::shared_ptr<ContextMTL>(
273 new ContextMTL(device, command_queue,
274 MTLShaderLibraryFromFileData(device, shader_libraries_data,
275 library_label),
276 std::move(is_gpu_disabled_sync_switch)));
277 if (!context->IsValid()) {
278 FML_LOG(ERROR) << "Could not create Metal context.";
279 return nullptr;
280 }
281 return context;
282 }

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

318 {
319 return CreateCommandBufferInQueue(command_queue_);
320 }

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

## ◆ CreateMTLCommandBuffer()

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

Definition at line 373 of file context_mtl.mm.

374 {
375 auto buffer = [command_queue_ commandBuffer];
376 if (!label.empty()) {
377 [buffer setLabel:@(label.data())];
378 }
379 return buffer;
380 }

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

## ◆ DescribeGpuModel()

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

Implements impeller::Context.

Definition at line 293 of file context_mtl.mm.

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

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

288 {
289 return Context::BackendType::kMetal;
290 }

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

358 {
359 return device_capabilities_;
360 }

## ◆ GetCommandQueue()

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

Return the graphics queue for submitting command buffers.

Implements impeller::Context.

Definition at line 429 of file context_mtl.mm.

429 {
430 return command_queue_ip_;
431 }

## ◆ GetIsGpuDisabledSyncSwitch()

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

Definition at line 331 of file context_mtl.mm.

332 {
333 return is_gpu_disabled_sync_switch_;
334 }

## ◆ GetMTLDevice()

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

Definition at line 354 of file context_mtl.mm.

354 {
355 return device_;
356 }

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

308 {
309 return pipeline_library_;
310 }

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

350 {
351 return resource_allocator_;
352 }

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

313 {
314 return sampler_library_;
315 }

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

303 {
304 return shader_library_;
305 }

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

298 {
299 return is_valid_;
300 }

## ◆ SetCapabilities()

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

Definition at line 362 of file context_mtl.mm.

363 {
364 device_capabilities_ = capabilities;
365 }

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

323 {}

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

383 {
384 std::vector<PendingTasks> failed_tasks;
385 {
386 Lock lock(tasks_awaiting_gpu_mutex_);
387 tasks_awaiting_gpu_.push_back(PendingTasks{task, failure});
388 int32_t failed_task_count =
389 tasks_awaiting_gpu_.size() - kMaxTasksAwaitingGPU;
390 if (failed_task_count > 0) {
391 failed_tasks.reserve(failed_task_count);
392 failed_tasks.insert(failed_tasks.end(),
393 std::make_move_iterator(tasks_awaiting_gpu_.begin()),
394 std::make_move_iterator(tasks_awaiting_gpu_.begin() +
395 failed_task_count));
396 tasks_awaiting_gpu_.erase(
397 tasks_awaiting_gpu_.begin(),
398 tasks_awaiting_gpu_.begin() + failed_task_count);
399 }
400 }
401 for (const PendingTasks& task : failed_tasks) {
402 if (task.failure) {
403 task.failure();
404 }
405 }
406 }

## ◆ UpdateOffscreenLayerPixelFormat()

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

Reimplemented from impeller::Context.

Definition at line 368 of file context_mtl.mm.

368 {
369 device_capabilities_ = InferMetalCapabilities(device_, format);
370 return true;
371 }

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

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:168
impeller::CreateMetalCommandQueue
static id< MTLCommandQueue > CreateMetalCommandQueue(id< MTLDevice > device)
Definition: context_mtl.mm:215
impeller::CreateMetalDevice
static id< MTLDevice > CreateMetalDevice()
Definition: context_mtl.mm:211
impeller::InferMetalCapabilities
static std::unique_ptr< Capabilities > InferMetalCapabilities(id< MTLDevice > device, PixelFormat color_format)
Definition: context_mtl.mm:54
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:145
impeller::Context::kMaxTasksAwaitingGPU
static constexpr int32_t kMaxTasksAwaitingGPU
Definition: context.h:60