[Chromecast] Adding pause/resume operations to VideoPlaneController.

chromecast/base/cast_resource.h

 // Copyright 2015 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef CHROMECAST_BASE_CAST_RESOURCE_H_
 #define CHROMECAST_BASE_CAST_RESOURCE_H_
 
 #include "base/macros.h"
 
 namespace chromecast {
 
 // Interface for resources needed to run application.

[halliwell, 2016/01/12 03:25:06]

This comment is terrible, btw.

[esum, 2016/01/15 23:02:28]

Modified to be a little clearer for the  time being.

 class CastResource {
  public:
   // Resources necessary to run cast apps. CastResource may contain union of the
   // following types.
   // TODO(yucliu): Split video resources and graphic resources.
   enum Resource {
     kResourceNone = 0,
     // All resources necessary to render sounds, for example, audio pipeline,
     // speaker, etc.
     kResourceAudio = 1 << 0,
     // All resources necessary to render videos or images, for example, video
     // pipeline, primary graphics plane, display, etc.
     kResourceScreenPrimary = 1 << 1,
     // All resources necessary to render overlaid images, for example, secondary
     // graphics plane, LCD, etc.
     kResourceScreenSecondary = 1 << 2,
     // Collection of resources used for display only combined with bitwise or.
     kResourceDisplayOnly = (kResourceScreenPrimary | kResourceScreenSecondary),
     // Collection of all resources combined with bitwise or.
     kResourceAll =
         (kResourceAudio | kResourceScreenPrimary | kResourceScreenSecondary),
   };
 
   class Client {

[halliwell, 2016/01/12 03:25:07]

Could we clarify what a Client is?  It's very much not clear from just looking
at this header.

[esum, 2016/01/15 23:02:28]

Done.

    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 CastResource with client. CastResource should not be

[halliwell, 2016/01/12 03:25:06]

what does "should not be owned by client" mean?  Is that trying to say "Client
does not take ownership of CastResource?"

[esum, 2016/01/15 23:02:28]

Yes. Done.

+    // owned by Client. 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
     //                   invalid. Client can't call functions with that pointer.
     //   |remain| the unreleased resource of CastResource. If kResourceNone is
     //            returned, Client will remove the resource from its watching
     //            list.
     virtual void OnResourceReleased(CastResource* cast_resource,
                                     Resource remain) = 0;

[halliwell, 2016/01/12 03:25:06]

Not a comment on your changes, but I'm having trouble with the naming in this
header.  What is a "CastResource".  Why are there two types here?  A
"CastResource" is released, and 'Resource' remains ... we should clean up all
the naming and concepts here :)

[esum, 2016/01/15 23:02:28]

Discussed and will leave as is now. Will be renamed in coming refactor.

 
    protected:
     virtual ~Client() {}
   };
 
   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;
 
  protected:
   CastResource() : client_(nullptr) {}
   virtual ~CastResource() {}
 
-  void NotifyResourceAcquired();
+  void RegisterWithClient();
   void NotifyResourceReleased(Resource remain);
 
  private:
   Client* client_;
 
   DISALLOW_COPY_AND_ASSIGN(CastResource);
 };
 
 }  // namespace chromecast
 
 #endif