Generalize Pepper ImageData caching.

This changes some method names and comments for ImageData caching. Other APIs could reuse
this machinery.

BUG=230980
TEST=none

Review URL: https://chromiumcodereview.appspot.com/14126004

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@194923 0039d316-1c4b-4281-b951-d872f2087c98

6 files changed, 33 insertions, 34 deletions

diff --git a/ppapi/proxy/graphics_2d_resource.cc b/ppapi/proxy/graphics_2d_resource.cc
index b07db46..4dc00ba 100644
--- a/ppapi/proxy/graphics_2d_resource.cc
+++ b/ppapi/proxy/graphics_2d_resource.cc
@@ -93,7 +93,7 @@ void Graphics2DResource::ReplaceContents(PP_Resource image_data) {
         "Graphics2DResource.PaintImageData: Bad image resource.");
     return;
   }
-  enter_image.object()->SetUsedInReplaceContents();
+  enter_image.object()->SetIsCandidateForReuse();
 
   Post(RENDERER, PpapiHostMsg_Graphics2D_ReplaceContents(
       image_object->host_resource()));
diff --git a/ppapi/proxy/ppb_image_data_proxy.cc b/ppapi/proxy/ppb_image_data_proxy.cc
index b2ede29..0262855 100644
--- a/ppapi/proxy/ppb_image_data_proxy.cc
+++ b/ppapi/proxy/ppb_image_data_proxy.cc
@@ -43,39 +43,37 @@ namespace {
 // How ImageData re-use works
 // --------------------------
 //
-// When a plugin does ReplaceContents, it transfers the ImageData to the system
-// for use as the backing store for the instance. When animating plugins (like
-// video) re-creating image datas for each frame and mapping the memory has a
-// high overhead. So we try to re-use these when possible.
+// When animating plugins (like video), re-creating image datas for each frame
+// and mapping the memory has a high overhead. So we try to re-use these when
+// possible.
 //
-// 1. Plugin does ReplaceContents and Flush and the proxy queues up an
-//    asynchronous request to the renderer.
+// 1. Plugin makes an asynchronous call that transfers an ImageData to the
+//    implementation of some API.
 // 2. Plugin frees its ImageData reference. If it doesn't do this we can't
 //    re-use it.
 // 3. When the last plugin ref of an ImageData is released, we don't actually
 //    delete it. Instead we put it on a queue where we hold onto it in the
 //    plugin process for a short period of time.
-// 4. When the Flush for the Graphics2D.ReplaceContents is executed, the proxy
-//    will request the old ImageData. This is the one that's being replaced by
-//    the new contents so is being abandoned, and without our caching system it
-//    would get deleted at this point.
+// 4. The API implementation that received the ImageData finishes using it.
+//    Without our caching system it would get deleted at this point.
 // 5. The proxy in the renderer will send NotifyUnusedImageData back to the
 //    plugin process. We check if the given resource is in the queue and mark
 //    it as usable.
 // 6. When the plugin requests a new image data, we check our queue and if there
 //    is a usable ImageData of the right size and format, we'll return it
-//    instead of making a new one. Since when you're doing full frame
-//    animations, generally the size doesn't change so cache hits should be
-//    high.
+//    instead of making a new one. It's important that caching is only requested
+//    when the size is unlikely to change, so cache hits are high.
 //
 // Some notes:
 //
-//  - We only re-use image datas when the plugin does ReplaceContents on them.
-//    Theoretically we could re-use them in other cases but the lifetime
+//  - We only re-use image data when the plugin and host are rapidly exchanging
+//    them and the size is likely to remain constant. It should be clear that
+//    the plugin is promising that it's done with the image.
+//
+//  - Theoretically we could re-use them in other cases but the lifetime
 //    becomes more difficult to manage. The plugin could have used an ImageData
 //    in an arbitrary number of queued up PaintImageData calls which we would
-//    have to check. By doing ReplaceContents, the plugin is promising that it's
-//    done with the image, so this is a good signal.
+//    have to check.
 //
 //  - If a flush takes a long time or there are many released image datas
 //    accumulating in our queue such that some are deleted, we will have
@@ -314,7 +312,7 @@ ImageData::ImageData(const HostResource& resource,
                      ImageHandle handle)
     : Resource(OBJECT_IS_PROXY, resource),
       desc_(desc),
-      used_in_replace_contents_(false) {
+      is_candidate_for_reuse_(false) {
 #if defined(OS_WIN)
   transport_dib_.reset(TransportDIB::CreateWithHandle(handle));
 #else
@@ -331,7 +329,7 @@ ImageData::ImageData(const HostResource& resource,
       shm_(handle, false /* read_only */),
       size_(desc.size.width * desc.size.height * 4),
       map_count_(0),
-      used_in_replace_contents_(false) {
+      is_candidate_for_reuse_(false) {
 }
 #endif  // else, !defined(OS_NACL)
 
@@ -346,7 +344,7 @@ void ImageData::LastPluginRefWasDeleted() {
   // The plugin no longer needs this ImageData, add it to our cache if it's
   // been used in a ReplaceContents. These are the ImageDatas that the renderer
   // will send back ImageDataUsable messages for.
-  if (used_in_replace_contents_)
+  if (is_candidate_for_reuse_)
     ImageDataCache::GetInstance()->Add(this);
 }
 
@@ -413,12 +411,12 @@ SkCanvas* ImageData::GetCanvas() {
 #endif
 }
 
-void ImageData::SetUsedInReplaceContents() {
-  used_in_replace_contents_ = true;
+void ImageData::SetIsCandidateForReuse() {
+  is_candidate_for_reuse_ = true;
 }
 
 void ImageData::RecycleToPlugin(bool zero_contents) {
-  used_in_replace_contents_ = false;
+  is_candidate_for_reuse_ = false;
   if (zero_contents) {
     void* data = Map();
     memset(data, 0, desc_.stride * desc_.size.height);
diff --git a/ppapi/proxy/ppb_image_data_proxy.h b/ppapi/proxy/ppb_image_data_proxy.h
index fdc921d..a58d15a 100644
--- a/ppapi/proxy/ppb_image_data_proxy.h
+++ b/ppapi/proxy/ppb_image_data_proxy.h
@@ -64,7 +64,7 @@ class PPAPI_PROXY_EXPORT ImageData
   virtual int32_t GetSharedMemory(int* handle, uint32_t* byte_count) OVERRIDE;
   virtual SkCanvas* GetPlatformCanvas() OVERRIDE;
   virtual SkCanvas* GetCanvas() OVERRIDE;
-  virtual void SetUsedInReplaceContents() OVERRIDE;
+  virtual void SetIsCandidateForReuse() OVERRIDE;
 
   const PP_ImageDataDesc& desc() const { return desc_; }
 
@@ -91,9 +91,8 @@ class PPAPI_PROXY_EXPORT ImageData
   scoped_ptr<SkCanvas> mapped_canvas_;
 #endif
 
-  // Set to true when this ImageData has been used in a call to
-  // Graphics2D.ReplaceContents. This is used to signal that it can be cached.
-  bool used_in_replace_contents_;
+  // Set to true when this ImageData is a good candidate for reuse.
+  bool is_candidate_for_reuse_;
 
   DISALLOW_COPY_AND_ASSIGN(ImageData);
 };
diff --git a/ppapi/thunk/ppb_image_data_api.h b/ppapi/thunk/ppb_image_data_api.h
index 9546304..f916ede 100644
--- a/ppapi/thunk/ppb_image_data_api.h
+++ b/ppapi/thunk/ppb_image_data_api.h
@@ -43,10 +43,12 @@ class PPB_ImageData_API {
   //   * Within untrusted code (which does not have skia).
   virtual SkCanvas* GetCanvas() = 0;
 
-  // Sets whether this image was used in a ReplaceContents call. If the
-  // current implementation supports image data recycling (only supported
-  // out-of-process then it will be marked for potential re-use.
-  virtual void SetUsedInReplaceContents() = 0;
+  // Signal that this image is a good candidate for reuse. Call this from APIs
+  // that receive ImageData resources of a fixed size and where the plugin will
+  // release its reference to the ImageData. If the current implementation
+  // supports image data reuse (only supported out-of-process) then the
+  // ImageData will be marked and potentially cached for re-use.
+  virtual void SetIsCandidateForReuse() = 0;
 };
 
 }  // namespace thunk
diff --git a/webkit/plugins/ppapi/ppb_image_data_impl.cc b/webkit/plugins/ppapi/ppb_image_data_impl.cc
index 2d28f5e..8e2951c 100644
--- a/webkit/plugins/ppapi/ppb_image_data_impl.cc
+++ b/webkit/plugins/ppapi/ppb_image_data_impl.cc
@@ -128,7 +128,7 @@ SkCanvas* PPB_ImageData_Impl::GetCanvas() {
   return backend_->GetCanvas();
 }
 
-void PPB_ImageData_Impl::SetUsedInReplaceContents() {
+void PPB_ImageData_Impl::SetIsCandidateForReuse() {
   // Nothing to do since we don't support image data re-use in-process.
 }
 
diff --git a/webkit/plugins/ppapi/ppb_image_data_impl.h b/webkit/plugins/ppapi/ppb_image_data_impl.h
index f2dc043..bbcf7e6 100644
--- a/webkit/plugins/ppapi/ppb_image_data_impl.h
+++ b/webkit/plugins/ppapi/ppb_image_data_impl.h
@@ -91,7 +91,7 @@ class WEBKIT_PLUGINS_EXPORT PPB_ImageData_Impl
   virtual int32_t GetSharedMemory(int* handle, uint32_t* byte_count) OVERRIDE;
   virtual SkCanvas* GetPlatformCanvas() OVERRIDE;
   virtual SkCanvas* GetCanvas() OVERRIDE;
-  virtual void SetUsedInReplaceContents() OVERRIDE;
+  virtual void SetIsCandidateForReuse() OVERRIDE;
 
   const SkBitmap* GetMappedBitmap() const;