Add docs for command buffer.

engine/src/flutter/impeller/renderer/backend/metal/command_buffer_mtl.h

@@ -30,7 +30,7 @@ class CommandBufferMTL final : public CommandBuffer {
   bool IsValid() const override;
 
   // |CommandBuffer|
-  void Commit(CommitCallback callback) override;
+  void Commit(CompletionCallback callback) override;
 
   // |CommandBuffer|
   std::shared_ptr<RenderPass> CreateRenderPass(

engine/src/flutter/impeller/renderer/backend/metal/command_buffer_mtl.mm

@@ -22,27 +22,26 @@ bool CommandBufferMTL::IsValid() const {
   return is_valid_;
 }
 
-static CommandBuffer::CommitResult ToCommitResult(
-    MTLCommandBufferStatus status) {
+static CommandBuffer::Status ToCommitResult(MTLCommandBufferStatus status) {
   switch (status) {
     case MTLCommandBufferStatusCompleted:
-      return CommandBufferMTL::CommitResult::kCompleted;
+      return CommandBufferMTL::Status::kCompleted;
     case MTLCommandBufferStatusEnqueued:
-      return CommandBufferMTL::CommitResult::kPending;
+      return CommandBufferMTL::Status::kPending;
     default:
       break;
   }
-  return CommandBufferMTL::CommitResult::kError;
+  return CommandBufferMTL::Status::kError;
 }
 
-void CommandBufferMTL::Commit(CommitCallback callback) {
+void CommandBufferMTL::Commit(CompletionCallback callback) {
   if (!callback) {
     callback = [](auto) {};
   }
 
   if (!buffer_) {
     // Already committed. This is caller error.
-    callback(CommitResult::kError);
+    callback(Status::kError);
     return;
   }
 

engine/src/flutter/impeller/renderer/command_buffer.h

@@ -20,22 +20,44 @@ class RenderPassDescriptor;
 ///             execution. A command buffer is obtained from a graphics
 ///             `Context`.
 ///
+///             To submit commands to the GPU, acquire a `RenderPass` from the
+///             command buffer and record `Command`s into that pass. A
+///             `RenderPass` describes the configuration of the various
+///             attachments when the command is submitted.
+///
+///             A command buffer is only meant to be used on a single thread.
+///
 class CommandBuffer {
  public:
-  enum class CommitResult {
+  enum class Status {
     kPending,
     kError,
     kCompleted,
   };
 
-  using CommitCallback = std::function<void(CommitResult)>;
+  using CompletionCallback = std::function<void(Status)>;
 
   virtual ~CommandBuffer();
 
   virtual bool IsValid() const = 0;
 
-  virtual void Commit(CommitCallback callback) = 0;
+  //----------------------------------------------------------------------------
+  /// @brief      Schedule the command encoded by render passes within this
+  ///             command buffer on the GPU.
+  ///
+  ///             A command buffer may only be committed once.
+  ///
+  /// @param[in]  callback  The completion callback.
+  ///
+  virtual void Commit(CompletionCallback callback) = 0;
 
+  //----------------------------------------------------------------------------
+  /// @brief      Create a render pass to record render commands into.
+  ///
+  /// @param[in]  desc  The description of the render pass.
+  ///
+  /// @return     A valid render pass or null.
+  ///
   virtual std::shared_ptr<RenderPass> CreateRenderPass(
       const RenderPassDescriptor& desc) const = 0;
 

engine/src/flutter/impeller/renderer/renderer.cc

@@ -64,9 +64,9 @@ bool Renderer::Render(const Surface& surface,
   }
 
   command_buffer->Commit(
-      [sema = frames_in_flight_sema_](CommandBuffer::CommitResult result) {
+      [sema = frames_in_flight_sema_](CommandBuffer::Status result) {
         sema->Signal();
-        if (result != CommandBuffer::CommitResult::kCompleted) {
+        if (result != CommandBuffer::Status::kCompleted) {
           FML_LOG(ERROR) << "Could not commit command buffer.";
         }
       });