Add whitelist parameter to refEncodedData

include/core/SkImageGenerator.h

Index: include/core/SkImageGenerator.h
diff --git a/include/core/SkImageGenerator.h b/include/core/SkImageGenerator.h
index 1a46f6b9cd7dfc39c753170b7da6046ed0877bb2..3ed20a06613c94fa1ec9379703301a3ad6a3f18d 100644
--- a/include/core/SkImageGenerator.h
+++ b/include/core/SkImageGenerator.h
@@ -10,6 +10,7 @@
 
 #include "SkBitmap.h"
 #include "SkColor.h"
+#include "SkEncodedFormat.h"
 #include "SkImageInfo.h"
 #include "SkYUVSizeInfo.h"
 
@@ -26,7 +27,7 @@ class SkPicture;
 #ifdef SK_SUPPORT_LEGACY_REFENCODEDDATA_NOCTX
     #define SK_REFENCODEDDATA_CTXPARAM
 #else
-    #define SK_REFENCODEDDATA_CTXPARAM  GrContext* ctx
+    #define SK_REFENCODEDDATA_CTXPARAM  SkEncodedFormatQuery* query
 #endif
 
 /**
@@ -70,19 +71,23 @@ public:
     uint32_t uniqueID() const { return fUniqueID; }
 
     /**
-     *  Return a ref to the encoded (i.e. compressed) representation,
-     *  of this data. If the GrContext is non-null, then the caller is only interested in
-     *  gpu-specific formats, so the impl may return null even if they have encoded data,
-     *  assuming they know it is not suitable for the gpu.
+     *  Return a ref to the encoded (i.e. compressed) representation of the image, or null if
+     *  no such encoded form is readily available. This is not meant to trigger a full-blown
+     *  encoding step, as the caller can always perform that itself. This is meant to give the
+     *  caller quick access to the encoded version iff it is already available.
      *
-     *  If non-NULL is returned, the caller is responsible for calling
-     *  unref() on the data when it is finished.
+     *  If query is non-null, then the implementation may choose to query it (multiple times if
+     *  needed) to preflight if a given format is supported. That query takes a snippet from the
+     *  beginning of the encoded data. If the generator readily has the encoded data available,
+     *  it may ignore the bot and just return it. However, if there is a performance or other

[reed1, 2016/04/07 13:27:31]

"bot"?

[scroggo_chromium, 2016/04/08 18:16:36]

Oops, I replaced the first instance of "bot" in your original CL with "query",
but missed the others...

[scroggo_chromium, 2016/04/12 14:41:19]

Removed.

+     *  constraint on returning the encoded data, calling the bot allows the generator to discover

[reed1, 2016/04/07 13:27:31]

Slightly confusing dox, as the first paragraph says we only return it if its
"readily available", but now we're talking about a "performance constraint" for
some formats...

[scroggo_chromium, 2016/04/08 18:16:36]

Acknowledged.

[scroggo_chromium, 2016/04/12 14:41:19]

Agreed. I've updated the comment with an example (the case in Chrome).

This may bring up a larger question though - should DecodingImageGenerator
implement onRefEncodedData at all?

- None of the formats supported by DecodingImageGenerator today can be passed in
encoded form directly to the GPU (though perhaps this will change in the future)
- It does not necessarily have its data in contiguous form (though we could
check, by seeing if getSomeData() == size()). This goes against the original
intent of refEncodedData (which is still reflected in the first paragraph).
- If we're going to encode (the other client of refEncodedData), we definitely
want this data. Maybe there should be a different method which is more flexible.
It asks for the encoded data but does not require it to be contiguous. Both in
this case and for passing encoded pixels to the GPU we *could* call
refEncodedData first (return null for DecodingImageGenerator), then call the
more flexible version (which will consolidate it or use it directly, as
necessary, and can even bail early if the data is not desirable) and then fall
back if necessary (e.g. full decode). That approach is a bit more involved, but
maybe it's a better route?

+     *  if their format is not supported, in which case the generator should just return null.
      */
-    SkData* refEncodedData(GrContext* ctx = nullptr) {
+    SkData* refEncodedData(SkEncodedFormatQuery* query = nullptr) {
 #ifdef SK_SUPPORT_LEGACY_REFENCODEDDATA_NOCTX
         return this->onRefEncodedData();
 #else
-        return this->onRefEncodedData(ctx);
+        return this->onRefEncodedData(query);
 #endif
     }