[Chromecast] Adding pause/resume operations to VideoPlaneController.

chromecast/base/cast_resource.h

Index: chromecast/base/cast_resource.h
diff --git a/chromecast/base/cast_resource.h b/chromecast/base/cast_resource.h
index cd248d77edc26872e426c5c2a42ef54a2aac1e0a..67315ec392a4d60a09eb3907e6557095c35eee13 100644
--- a/chromecast/base/cast_resource.h
+++ b/chromecast/base/cast_resource.h
@@ -9,7 +9,13 @@
 
 namespace chromecast {
 
-// Interface for resources needed to run application.
+// A CastResource is a user of 1 or more Resources (primary screen, audio,
+// etc). As a user, it is responsible for doing any cast-specific component
+// initialization when the Resources it uses are granted. This initialization
+// is referred to as "acquiring" the Resources. Conversely, when the Resources
+// it uses are revoked, it must deinitialize these cast-specific components.
+// This deinitialization is referred to as "releasing" the Resources.
+// TODO(maclellant): RENAME/DESIGN THIS CLASS IN COMING REFACTOR.
 class CastResource {
  public:
   // Resources necessary to run cast apps. CastResource may contain union of the
@@ -33,11 +39,22 @@ class CastResource {
         (kResourceAudio | kResourceScreenPrimary | kResourceScreenSecondary),
   };
 
+  // A Client is responsible for notifying all registered CastResource's when
+  // Resources are granted/revoked so that they can acquire/release those
+  // Resources. When a CastResource is done acquiring/releasing, it responds
+  // to the Client that it has completed. A Client can have multiple registered
+  // CastResource's, but each CastResouce has 1 Client that it responds to.
   class Client {
    public:
-    // Called when resource is created. CastResource should not be owned by
-    // Client. It can be called from any thread.
-    virtual void OnResourceAcquired(CastResource* cast_resource) = 0;
+    // Called to register a CastResource with a Client. After registering, a
+    // CastResource will start getting notified when to acquire/release
+    // Resources. The Client does not take ownership of |cast_resource|. It can
+    // be called from any thread.
+    virtual void RegisterCastResource(CastResource* cast_resource) = 0;
+
+    // TODO(esum): Add OnResourceAcquired() here once AcquireResource is
+    // allowed to be asynchronous.
+
     // Called when part or all resources are released. It can be called from any
     // thread.
     //   |cast_resource| the CastResource that is released. The pointer may be
@@ -52,7 +69,17 @@ class CastResource {
     virtual ~Client() {}
   };
 
+  // Sets the Client for the CastResource to respond to when it is done with
+  // Acquire/ReleaseResource.
   void SetCastResourceClient(Client* client);
+  // Called to acquire resources after OEM has granted them, and before
+  // they start getting used by consumers. Implementation must be synchronous
+  // since consumers will start using the resource immediately afterwards.
+  // TODO(esum): We should allow this method to be asynchronous in case an
+  // implementer needs to make expensive calls and doesn't want to block the
+  // UI thread (b/26239576). For now, don't do anything expensive in your
+  // implementation; if you really need to, then this bug has to be resolved.
+  virtual void AcquireResource(Resource resource) = 0;
   // Called to release resources. Implementation should call
   // Client::OnResourceReleased when resource is released on its side.
   virtual void ReleaseResource(Resource resource) = 0;
@@ -61,7 +88,9 @@ class CastResource {
   CastResource() : client_(nullptr) {}
   virtual ~CastResource() {}
 
-  void NotifyResourceAcquired();
+  // For derived classes to register themselves with their Client through
+  // Client::RegisterCastResource.
+  void RegisterWithClient();
   void NotifyResourceReleased(Resource remain);
 
  private: