Flutter Impeller
impeller::Context Class Referenceabstract

To do anything rendering related with Impeller, you need a context. More...

#include <context.h>

Inheritance diagram for impeller::Context:
impeller::ContextGLES impeller::ContextMTL impeller::ContextVK impeller::SurfaceContextVK

Public Types

enum class  BackendType {
  kMetal ,
  kOpenGLES ,
  kVulkan
}
 

Public Member Functions

virtual ~Context ()
 Destroys an Impeller context. More...
 
virtual BackendType GetBackendType () const =0
 Get the graphics backend of an Impeller context. More...
 
virtual std::string DescribeGpuModel () const =0
 
virtual bool IsValid () const =0
 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...
 
virtual const std::shared_ptr< const Capabilities > & GetCapabilities () const =0
 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...
 
virtual bool UpdateOffscreenLayerPixelFormat (PixelFormat format)
 
virtual std::shared_ptr< AllocatorGetResourceAllocator () const =0
 Returns the allocator used to create textures and buffers on the device. More...
 
virtual std::shared_ptr< ShaderLibraryGetShaderLibrary () const =0
 Returns the library of shaders used to specify the programmable stages of a pipeline. More...
 
virtual std::shared_ptr< SamplerLibraryGetSamplerLibrary () const =0
 Returns the library of combined image samplers used in shaders. More...
 
virtual std::shared_ptr< PipelineLibraryGetPipelineLibrary () const =0
 Returns the library of pipelines used by render or compute commands. More...
 
virtual std::shared_ptr< CommandBufferCreateCommandBuffer () const =0
 Create a new command buffer. Command buffers can be used to encode graphics, blit, or compute commands to be submitted to the device. More...
 
virtual std::shared_ptr< CommandQueueGetCommandQueue () const =0
 Return the graphics queue for submitting command buffers. More...
 
virtual void Shutdown ()=0
 Force all pending asynchronous work to finish. This is achieved by deleting all owned concurrent message loops. More...
 
virtual void StoreTaskForGPU (const fml::closure &task, const fml::closure &failure)
 
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 RuntimeStageBackend GetRuntimeStageBackend () const =0
 Retrieve the runtime stage for this context type. More...
 
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 Attributes

static constexpr int32_t kMaxTasksAwaitingGPU = 1024
 

Protected Member Functions

 Context (const Flags &flags)
 

Protected Attributes

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

Detailed Description

To do anything rendering related with Impeller, you need a context.

Contexts are expensive to construct and typically you only need one in the process. The context represents a connection to a graphics or compute accelerator on the device.

If there are multiple context in a process, it would typically be for separation of concerns (say, use with multiple engines in Flutter), talking to multiple accelerators, or talking to the same accelerator using different client APIs (Metal, Vulkan, OpenGL ES, etc..).

Contexts are thread-safe. They may be created, used, and collected (though not from a thread used by an internal pool) on any thread. They may also be accessed simultaneously from multiple threads.

Contexts are abstract and a concrete instance must be created using one of the subclasses of Context in //impeller/renderer/backend.

Definition at line 65 of file context.h.

Member Enumeration Documentation

◆ BackendType

Enumerator
kMetal 
kOpenGLES 
kVulkan 

Definition at line 67 of file context.h.

Constructor & Destructor Documentation

◆ ~Context()

impeller::Context::~Context ( )
virtualdefault

Destroys an Impeller context.

◆ Context()

impeller::Context::Context ( const Flags flags)
explicitprotected

Definition at line 27 of file context.cc.

27 : flags_(flags) {}

Member Function Documentation

◆ AddTrackingFence()

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

Definition at line 50 of file context.cc.

50  {
51  return false;
52 }

◆ CreateCommandBuffer()

virtual std::shared_ptr<CommandBuffer> impeller::Context::CreateCommandBuffer ( ) const
pure virtual

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.

Implemented in impeller::SurfaceContextVK, impeller::ContextVK, and impeller::ContextMTL.

Referenced by impeller::TypographerContextSkia::CreateGlyphAtlas(), and impeller::testing::CreateTestYUVTextures().

◆ DescribeGpuModel()

virtual std::string impeller::Context::DescribeGpuModel ( ) const
pure virtual

◆ DisposeThreadLocalCachedResources()

virtual void impeller::Context::DisposeThreadLocalCachedResources ( )
inlinevirtual

Dispose resources that are cached on behalf of the current thread.

Some backends such as Vulkan may cache resources that can be reused while executing a rendering operation. This API can be called after the operation completes in order to clear the cache.

Reimplemented in impeller::SurfaceContextVK, and impeller::ContextVK.

Definition at line 223 of file context.h.

223 {}

◆ EnqueueCommandBuffer()

bool impeller::Context::EnqueueCommandBuffer ( std::shared_ptr< CommandBuffer command_buffer)
virtual

Enqueue command_buffer for submission by the end of the frame.

Certain backends may immediately flush the command buffer if batch submission is not supported. This functionality is not thread safe and should only be used via the ContentContext for rendering a 2D workload.

Returns true if submission has succeeded. If the buffer is enqueued then no error may be returned until FlushCommandBuffers is called.

Reimplemented in impeller::SurfaceContextVK, and impeller::ContextVK.

Definition at line 33 of file context.cc.

34  {
35  return GetCommandQueue()->Submit({std::move(command_buffer)}).ok();
36 }
virtual std::shared_ptr< CommandQueue > GetCommandQueue() const =0
Return the graphics queue for submitting command buffers.

References GetCommandQueue().

Referenced by impeller::TypographerContextSkia::CreateGlyphAtlas(), and SubmitOnscreen().

◆ FlushCommandBuffers()

bool impeller::Context::FlushCommandBuffers ( )
virtual

Flush all pending command buffers.

Returns whether or not submission was successful. This functionality is not threadsafe and should only be used via the ContentContext for rendering a 2D workload.

Reimplemented in impeller::SurfaceContextVK, and impeller::ContextVK.

Definition at line 38 of file context.cc.

38  {
39  return true;
40 }

◆ GetBackendType()

virtual BackendType impeller::Context::GetBackendType ( ) const
pure virtual

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.

Implemented in impeller::SurfaceContextVK, impeller::ContextVK, impeller::ContextMTL, and impeller::ContextGLES.

Referenced by impeller::TypographerContextSkia::CreateGlyphAtlas().

◆ GetCapabilities()

virtual const std::shared_ptr<const Capabilities>& impeller::Context::GetCapabilities ( ) const
pure virtual

◆ GetCommandQueue()

virtual std::shared_ptr<CommandQueue> impeller::Context::GetCommandQueue ( ) const
pure virtual

Return the graphics queue for submitting command buffers.

Implemented in impeller::SurfaceContextVK, impeller::ContextVK, and impeller::ContextMTL.

Referenced by impeller::testing::CreateTestYUVTextures(), and EnqueueCommandBuffer().

◆ GetFlags()

const Flags& impeller::Context::GetFlags ( ) const
inline

Definition at line 267 of file context.h.

267 { return flags_; }

References flags_.

◆ GetIdleWaiter()

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

Reimplemented in impeller::SurfaceContextVK, and impeller::ContextVK.

Definition at line 42 of file context.cc.

42  {
43  return nullptr;
44 }

◆ GetPipelineLibrary()

virtual std::shared_ptr<PipelineLibrary> impeller::Context::GetPipelineLibrary ( ) const
pure virtual

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

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

Implemented in impeller::SurfaceContextVK, impeller::ContextVK, and impeller::ContextMTL.

Referenced by impeller::CreatePipelineFuture().

◆ GetResourceAllocator()

virtual std::shared_ptr<Allocator> impeller::Context::GetResourceAllocator ( ) const
pure virtual

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

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

Implemented in impeller::SurfaceContextVK, impeller::ContextVK, and impeller::ContextMTL.

Referenced by impeller::TypographerContextSkia::CreateGlyphAtlas(), and impeller::testing::CreateTestYUVTextures().

◆ GetRuntimeStageBackend()

virtual RuntimeStageBackend impeller::Context::GetRuntimeStageBackend ( ) const
pure virtual

Retrieve the runtime stage for this context type.

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

Implemented in impeller::SurfaceContextVK, impeller::ContextVK, and impeller::ContextMTL.

◆ GetSamplerLibrary()

virtual std::shared_ptr<SamplerLibrary> impeller::Context::GetSamplerLibrary ( ) const
pure virtual

Returns the library of combined image samplers used in shaders.

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

Implemented in impeller::SurfaceContextVK, impeller::ContextVK, and impeller::ContextMTL.

◆ GetShaderLibrary()

virtual std::shared_ptr<ShaderLibrary> impeller::Context::GetShaderLibrary ( ) const
pure virtual

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.

Implemented in impeller::SurfaceContextVK, impeller::ContextVK, and impeller::ContextMTL.

Referenced by impeller::ComputePipelineBuilder< ComputeShader_ >::InitializePipelineDescriptorDefaults(), and impeller::PipelineBuilder< VertexShader_, FragmentShader_ >::InitializePipelineDescriptorDefaults().

◆ InitializeCommonlyUsedShadersIfNeeded()

virtual void impeller::Context::InitializeCommonlyUsedShadersIfNeeded ( ) const
inlinevirtual

Run backend specific additional setup and create common shader variants.

This bootstrap is intended to improve the performance of several first frame benchmarks that are tracked in the flutter device lab. The workload includes initializing commonly used but not default shader variants, as well as forcing driver initialization.

Reimplemented in impeller::SurfaceContextVK, and impeller::ContextVK.

Definition at line 216 of file context.h.

216 {}

◆ IsValid()

virtual bool impeller::Context::IsValid ( ) const
pure virtual

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.

Implemented in impeller::SurfaceContextVK, impeller::ContextVK, and impeller::ContextMTL.

Referenced by impeller::CreatePipelineFuture().

◆ ResetThreadLocalState()

void impeller::Context::ResetThreadLocalState ( ) const
virtual

Resets any thread local state that may interfere with embedders.

Today, only the OpenGL backend can trample on thread local state that the embedder can access. This call puts the GL state in a sane "clean" state.

Impeller itself is resilient to a dirty thread local state table.

Definition at line 46 of file context.cc.

46  {
47  // Nothing to do.
48 }

◆ Shutdown()

virtual void impeller::Context::Shutdown ( )
pure virtual

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

Implemented in impeller::SurfaceContextVK, impeller::ContextVK, and impeller::ContextMTL.

◆ StoreTaskForGPU()

virtual void impeller::Context::StoreTaskForGPU ( const fml::closure &  task,
const fml::closure &  failure 
)
inlinevirtual

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 in impeller::ContextMTL.

Definition at line 205 of file context.h.

206  {
207  FML_CHECK(false && "not supported in this context");
208  }

◆ SubmitOnscreen()

bool impeller::Context::SubmitOnscreen ( std::shared_ptr< CommandBuffer cmd_buffer)
virtual

Submit the command buffer that renders to the onscreen surface.

Reimplemented in impeller::SurfaceContextVK, and impeller::ContextVK.

Definition at line 54 of file context.cc.

54  {
55  return EnqueueCommandBuffer(std::move(cmd_buffer));
56 }
virtual bool EnqueueCommandBuffer(std::shared_ptr< CommandBuffer > command_buffer)
Enqueue command_buffer for submission by the end of the frame.
Definition: context.cc:33

References EnqueueCommandBuffer().

◆ UpdateOffscreenLayerPixelFormat()

bool impeller::Context::UpdateOffscreenLayerPixelFormat ( PixelFormat  format)
virtual

Reimplemented in impeller::ContextMTL.

Definition at line 29 of file context.cc.

29  {
30  return false;
31 }

Member Data Documentation

◆ flags_

Flags impeller::Context::flags_
protected

Definition at line 272 of file context.h.

Referenced by GetFlags().

◆ kMaxTasksAwaitingGPU

constexpr int32_t impeller::Context::kMaxTasksAwaitingGPU = 1024
staticconstexpr

The maximum number of tasks that should ever be stored for StoreTaskForGPU.

This number was arbitrarily chosen. The idea is that this is a somewhat rare situation where tasks happen to get executed in that tiny amount of time while an app is being backgrounded but still executing.

Definition at line 79 of file context.h.

◆ per_frame_task_

std::vector<std::function<void()> > impeller::Context::per_frame_task_
protected

Definition at line 273 of file context.h.


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