| Flutter Impeller |

context.h
Go to the documentation of this file.
1 // Copyright 2013 The Flutter Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4
5 #pragma once
6
7 #include <memory>
8 #include <string>
9
10 #include "flutter/fml/macros.h"
11 #include "impeller/core/capture.h"
12 #include "impeller/core/formats.h"
13 #include "impeller/core/host_buffer.h"
14 #include "impeller/renderer/capabilities.h"
15 #include "impeller/renderer/pool.h"
16
17 namespace impeller {
18
19 class ShaderLibrary;
20 class SamplerLibrary;
21 class CommandBuffer;
22 class PipelineLibrary;
23 class Allocator;
24
25 //------------------------------------------------------------------------------
26 /// @brief To do anything rendering related with Impeller, you need a
27 /// context.
28 ///
29 /// Contexts are expensive to construct and typically you only need
30 /// one in the process. The context represents a connection to a
31 /// graphics or compute accelerator on the device.
32 ///
33 /// If there are multiple context in a process, it would typically
34 /// be for separation of concerns (say, use with multiple engines in
35 /// Flutter), talking to multiple accelerators, or talking to the
36 /// same accelerator using different client APIs (Metal, Vulkan,
37 /// OpenGL ES, etc..).
38 ///
39 /// Contexts are thread-safe. They may be created, used, and
40 /// collected (though not from a thread used by an internal pool) on
41 /// any thread. They may also be accessed simultaneously from
42 /// multiple threads.
43 ///
44 /// Contexts are abstract and a concrete instance must be created
45 /// using one of the subclasses of `Context` in
46 /// `//impeller/renderer/backend`.
47 class Context {
48 public:
49 enum class BackendType {
50 kMetal,
51 kOpenGLES,
52 kVulkan,
53 };
54
55 //----------------------------------------------------------------------------
56 /// @brief Destroys an Impeller context.
57 ///
58 virtual ~Context();
59
60 //----------------------------------------------------------------------------
61 /// @brief Get the graphics backend of an Impeller context.
62 ///
63 /// This is useful for cases where a renderer needs to track and
64 /// lookup backend-specific resources, like shaders or uniform
65 /// layout information.
66 ///
67 /// It's not recommended to use this as a substitute for
68 /// per-backend capability checking. Instead, check for specific
69 /// capabilities via `GetCapabilities()`.
70 ///
71 /// @return The graphics backend of the `Context`.
72 ///
73 virtual BackendType GetBackendType() const = 0;
74
75 // TODO(129920): Refactor and move to capabilities.
76 virtual std::string DescribeGpuModel() const = 0;
77
78 //----------------------------------------------------------------------------
79 /// @brief Determines if a context is valid. If the caller ever receives
80 /// an invalid context, they must discard it and construct a new
81 /// context. There is no recovery mechanism to repair a bad
82 /// context.
83 ///
84 /// It is convention in Impeller to never return an invalid
85 /// context from a call that returns an pointer to a context. The
86 /// call implementation performs validity checks itself and return
87 /// a null context instead of a pointer to an invalid context.
88 ///
89 /// How a context goes invalid is backend specific. It could
90 /// happen due to device loss, or any other unrecoverable error.
91 ///
92 /// @return If the context is valid.
93 ///
94 virtual bool IsValid() const = 0;
95
96 //----------------------------------------------------------------------------
97 /// @brief Get the capabilities of Impeller context. All optionally
98 /// supported feature of the platform, client-rendering API, and
99 /// device can be queried using the `Capabilities`.
100 ///
101 /// @return The capabilities. Can never be `nullptr` for a valid context.
102 ///
103 virtual const std::shared_ptr<const Capabilities>& GetCapabilities()
104 const = 0;
105
106 // TODO(129920): Refactor and move to capabilities.
107 virtual bool UpdateOffscreenLayerPixelFormat(PixelFormat format);
108
109 //----------------------------------------------------------------------------
110 /// @brief Returns the allocator used to create textures and buffers on
111 /// the device.
112 ///
113 /// @return The resource allocator. Can never be `nullptr` for a valid
114 /// context.
115 ///
116 virtual std::shared_ptr<Allocator> GetResourceAllocator() const = 0;
117
118 //----------------------------------------------------------------------------
119 /// @brief Returns the library of shaders used to specify the
120 /// programmable stages of a pipeline.
121 ///
122 /// @return The shader library. Can never be `nullptr` for a valid
123 /// context.
124 ///
125 virtual std::shared_ptr<ShaderLibrary> GetShaderLibrary() const = 0;
126
127 //----------------------------------------------------------------------------
128 /// @brief Returns the library of combined image samplers used in
129 /// shaders.
130 ///
131 /// @return The sampler library. Can never be `nullptr` for a valid
132 /// context.
133 ///
134 virtual std::shared_ptr<SamplerLibrary> GetSamplerLibrary() const = 0;
135
136 //----------------------------------------------------------------------------
137 /// @brief Returns the library of pipelines used by render or compute
138 /// commands.
139 ///
140 /// @return The pipeline library. Can never be `nullptr` for a valid
141 /// context.
142 ///
143 virtual std::shared_ptr<PipelineLibrary> GetPipelineLibrary() const = 0;
144
145 //----------------------------------------------------------------------------
146 /// @brief Create a new command buffer. Command buffers can be used to
147 /// encode graphics, blit, or compute commands to be submitted to
148 /// the device.
149 ///
150 /// A command buffer can only be used on a single thread.
151 /// Multi-threaded render, blit, or compute passes must create a
152 /// new command buffer on each thread.
153 ///
154 /// @return A new command buffer.
155 ///
156 virtual std::shared_ptr<CommandBuffer> CreateCommandBuffer() const = 0;
157
158 //----------------------------------------------------------------------------
159 /// @brief Force all pending asynchronous work to finish. This is
160 /// achieved by deleting all owned concurrent message loops.
161 ///
162 virtual void Shutdown() = 0;
163
164 //----------------------------------------------------------------------------
165 /// @brief Force the Vulkan presentation (submitKHR) to be performed on
166 /// the raster task runner.
167 ///
168 /// This is required for correct rendering on Android when using
169 /// the hybrid composition mode. This has no effect on other
170 /// backends.
171 virtual void SetSyncPresentation(bool value) {}
172
173 //----------------------------------------------------------------------------
174 /// @brief Accessor for a pool of HostBuffers.
175 Pool<HostBuffer>& GetHostBufferPool() const { return host_buffer_pool_; }
176
177 CaptureContext capture;
178
179 protected:
180 Context();
181
182 private:
183 mutable Pool<HostBuffer> host_buffer_pool_ = Pool<HostBuffer>(1'000'000);
184
185 FML_DISALLOW_COPY_AND_ASSIGN(Context);
186 };
187
188 } // namespace impeller
impeller::Context::GetPipelineLibrary
virtual std::shared_ptr< PipelineLibrary > GetPipelineLibrary() const =0
Returns the library of pipelines used by render or compute commands.
impeller::Context::capture
CaptureContext capture
Definition: context.h:177
host_buffer.h
capture.h
impeller::Context::~Context
virtual ~Context()
Destroys an Impeller context.
impeller::Context::BackendType
BackendType
Definition: context.h:49
impeller::Context::GetCapabilities
virtual const std::shared_ptr< const Capabilities > & GetCapabilities() const =0
Get the capabilities of Impeller context. All optionally supported feature of the platform,...
impeller::Context::GetShaderLibrary
virtual std::shared_ptr< ShaderLibrary > GetShaderLibrary() const =0
Returns the library of shaders used to specify the programmable stages of a pipeline.
formats.h
impeller::Context::GetBackendType
virtual BackendType GetBackendType() const =0
Get the graphics backend of an Impeller context.
impeller::CaptureContext
Definition: capture.h:263
impeller::Context::BackendType::kOpenGLES
@ kOpenGLES
pool.h
impeller::Pool
A thread-safe pool with a limited byte size.
Definition: pool.h:15
impeller::Context::Context
Context()
Definition: context.cc:13
capabilities.h
impeller::Context::GetSamplerLibrary
virtual std::shared_ptr< SamplerLibrary > GetSamplerLibrary() const =0
Returns the library of combined image samplers used in shaders.
impeller::Context::CreateCommandBuffer
virtual std::shared_ptr< CommandBuffer > CreateCommandBuffer() const =0
Create a new command buffer. Command buffers can be used to encode graphics, blit,...
impeller::Context::GetHostBufferPool
Pool< HostBuffer > & GetHostBufferPool() const
Accessor for a pool of HostBuffers.
Definition: context.h:175
impeller::Context::IsValid
virtual bool IsValid() const =0
Determines if a context is valid. If the caller ever receives an invalid context, they must discard i...
impeller::Context::BackendType::kVulkan
@ kVulkan
impeller::Context::BackendType::kMetal
@ kMetal
impeller::Context
To do anything rendering related with Impeller, you need a context.
Definition: context.h:47
impeller::Context::SetSyncPresentation
virtual void SetSyncPresentation(bool value)
Force the Vulkan presentation (submitKHR) to be performed on the raster task runner.
Definition: context.h:171
impeller::Context::Shutdown
virtual void Shutdown()=0
Force all pending asynchronous work to finish. This is achieved by deleting all owned concurrent mess...
impeller::PixelFormat
PixelFormat
The Pixel formats supported by Impeller. The naming convention denotes the usage of the component,...
Definition: formats.h:94
impeller::Context::DescribeGpuModel
virtual std::string DescribeGpuModel() const =0
impeller
Definition: aiks_context.cc:10
impeller::Context::GetResourceAllocator
virtual std::shared_ptr< Allocator > GetResourceAllocator() const =0
Returns the allocator used to create textures and buffers on the device.
impeller::Context::UpdateOffscreenLayerPixelFormat
virtual bool UpdateOffscreenLayerPixelFormat(PixelFormat format)
Definition: context.cc:15