From cf6a062cebcb7bda52f5c24d82bccdbbba9efa48 Mon Sep 17 00:00:00 2001 From: Chinmay Garde Date: Mon, 3 Jul 2023 15:43:28 -0700 Subject: [PATCH 1/2] [Impeller] Document `impeller::Context`. --- impeller/renderer/context.h | 94 ++++++++++++++++++++++++++++++++++++- 1 file changed, 92 insertions(+), 2 deletions(-) diff --git a/impeller/renderer/context.h b/impeller/renderer/context.h index 554b496893844..d8a3c21cc6dd4 100644 --- a/impeller/renderer/context.h +++ b/impeller/renderer/context.h @@ -19,31 +19,121 @@ class CommandBuffer; class PipelineLibrary; class Allocator; +//------------------------------------------------------------------------------ +/// @brief Do 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 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`. class Context { public: + //---------------------------------------------------------------------------- + /// @brief Destroys an Impeller context. + /// virtual ~Context(); + // TODO(129920): Refactor and move to capabilities. virtual std::string DescribeGpuModel() const = 0; + //---------------------------------------------------------------------------- + /// @brief 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. + /// + /// @return If the context is valid. + /// virtual bool IsValid() const = 0; + //---------------------------------------------------------------------------- + /// @brief Get the capabilities of Impeller context. All optionally + /// supported feature of the platform, client-rendering API, and + /// device can be queried using the `Capabilities`. + /// + /// @return The capabilities. Can never be `nullptr` for a valid context. + /// virtual const std::shared_ptr& GetCapabilities() const = 0; + // TODO(129920): Refactor and move to capabilities. virtual bool UpdateOffscreenLayerPixelFormat(PixelFormat format); + //---------------------------------------------------------------------------- + /// @brief Returns the allocator used to create textures and buffers on + /// the device. + /// + /// @return The resource allocator. Can never be `nullptr` for a valid + /// context. + /// virtual std::shared_ptr GetResourceAllocator() const = 0; + //---------------------------------------------------------------------------- + /// @brief Returns the library of shaders used to specify the + /// programmable stages of a pipeline. + /// + /// @return The shader library. Can never be `nullptr` for a valid + /// context. + /// virtual std::shared_ptr GetShaderLibrary() const = 0; + //---------------------------------------------------------------------------- + /// @brief Returns the library of combined image samplers used in + /// shaders. + /// + /// @return The sampler library. Can never be `nullptr` for a valid + /// context. + /// virtual std::shared_ptr GetSamplerLibrary() const = 0; + //---------------------------------------------------------------------------- + /// @brief Returns the library of pipelines used by render or compute + /// commands. + /// + /// @return The pipeline library. Can never be `nullptr` for a valid + /// context. + /// virtual std::shared_ptr GetPipelineLibrary() const = 0; + //---------------------------------------------------------------------------- + /// @brief 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. + /// + /// @return A new command buffer. + /// virtual std::shared_ptr CreateCommandBuffer() const = 0; - /// @brief Force all pending async work to finish by deleting any owned - /// concurrent message loops. + //---------------------------------------------------------------------------- + /// @brief Force all pending asynchronous work to finish. This is + /// achieved by deleting all owned concurrent message loops. + /// virtual void Shutdown() = 0; protected: From 591d7581f9257298e84eeeaa08536625de34b867 Mon Sep 17 00:00:00 2001 From: Chinmay Garde Date: Mon, 3 Jul 2023 16:27:06 -0700 Subject: [PATCH 2/2] PR comments. --- impeller/renderer/context.h | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/impeller/renderer/context.h b/impeller/renderer/context.h index d8a3c21cc6dd4..c4cbd1e3555ef 100644 --- a/impeller/renderer/context.h +++ b/impeller/renderer/context.h @@ -20,7 +20,7 @@ class PipelineLibrary; class Allocator; //------------------------------------------------------------------------------ -/// @brief Do do anything rendering related with Impeller, you need a +/// @brief To do anything rendering related with Impeller, you need a /// context. /// /// Contexts are expensive to construct and typically you only need @@ -34,8 +34,9 @@ class Allocator; /// OpenGL ES, etc..). /// /// Contexts are thread-safe. They may be created, used, and -/// collected on any thread. They may also be accessed -/// simultaneously from multiple threads. +/// 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