Add whitelist parameter to refEncodedData

include/core/SkImageGenerator.h

 /*
  * Copyright 2013 Google Inc.
  *
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 #ifndef SkImageGenerator_DEFINED
 #define SkImageGenerator_DEFINED
 
 #include "SkBitmap.h"
 #include "SkColor.h"
+#include "SkEncodedFormat.h"
 #include "SkImageInfo.h"
 #include "SkYUVSizeInfo.h"
 
 class GrContext;
 class GrTexture;
 class GrTextureParams;
 class SkBitmap;
 class SkData;
 class SkImageGenerator;
 class SkMatrix;
 class SkPaint;
 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
 
 /**
  *  Takes ownership of SkImageGenerator.  If this method fails for
  *  whatever reason, it will return false and immediatetely delete
  *  the generator.  If it succeeds, it will modify destination
  *  bitmap.
  *
  *  If generator is NULL, will safely return false.
  *
@@ skipping 23 matching lines @@
 public:
     /**
      *  The PixelRef which takes ownership of this SkImageGenerator
      *  will call the image generator's destructor.
      */
     virtual ~SkImageGenerator() { }
 
     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
     }
 
     /**
      *  Return the ImageInfo associated with this generator.
      */
     const SkImageInfo& getInfo() const { return fInfo; }
 
     /**
      *  Decode into the given pixels, a block of memory of size at
@@ skipping 186 matching lines @@
     const SkImageInfo fInfo;
     const uint32_t fUniqueID;
 
     // This is our default impl, which may be different on different platforms.
     // It is called from NewFromEncoded() after it has checked for any runtime factory.
     // The SkData will never be NULL, as that will have been checked by NewFromEncoded.
     static SkImageGenerator* NewFromEncodedImpl(SkData*);
 };
 
 #endif  // SkImageGenerator_DEFINED