new API for retrieving YUV data

include/core/SkImageGenerator.h

Index: include/core/SkImageGenerator.h
diff --git a/include/core/SkImageGenerator.h b/include/core/SkImageGenerator.h
index 2967974c7845cb95cfb6c5b7f2e3b0815fde9f88..ffd68ff9f67ab13c0ce14d5a797fb2be87052d96 100644
--- a/include/core/SkImageGenerator.h
+++ b/include/core/SkImageGenerator.h
@@ -11,6 +11,8 @@
 #include "SkColor.h"
 #include "SkImageInfo.h"
 
+//#define SK_SUPPORT_LEGACY_IMAGEGENERATOR_YUV_API
+
 class SkBitmap;
 class SkData;
 class SkImageGenerator;
@@ -107,6 +109,7 @@ public:
      */
     bool getPixels(const SkImageInfo& info, void* pixels, size_t rowBytes);
 
+#ifdef SK_SUPPORT_LEGACY_IMAGEGENERATOR_YUV_API
     /**
      *  If planes or rowBytes is NULL or if any entry in planes is NULL or if any entry in rowBytes
      *  is 0, this imagegenerator should output the sizes and return true if it can efficiently
@@ -120,6 +123,36 @@ public:
      */
     bool getYUV8Planes(SkISize sizes[3], void* planes[3], size_t rowBytes[3],
                        SkYUVColorSpace* colorSpace);
+#endif
+
+    /**
+     *  If this generator supports returning planar YUV data, return true, and return
+     *  the logicalSizes (if not NULL) and the optimalAllocationSizes (if not NULL), where each
+     *  array represents [0]=Y, [1]=U, [2]=V
+     *
+     *  The optimalAllocationSizes may be the same as the logicalSizes, but they may also be larger
+     *  if that will aid the generator (for performance).
+     *
+     *  If this returns false, the value of the (optional) sizes parameters is undefined.
+     */
+    bool queryYUV8(SkISize logicalSizes[3], SkISize optimalAllocationSizes[3]);

[scroggo, 2015/01/22 19:47:47]

It's interesting to me that optimalAllocationSizes is a set of SkISizes. What
are the units? bytes? Pixels? Would it be reasonable to make it a set of
size_ts?

[reed1, 2015/01/27 18:42:40]

width/height in pixels -- will document.

+
+    /**
+     *  If this generator supports returning planar YUV data, and can fulfill the requested
+     *  sizes for each plane, return true and write the YUV data into the planes.
+     *
+     *  Calling queryYUV8() will return both the logical sizes (W/H) and the optimal-allocation
+     *  sizes for the 3 planes. For getYUV8(), tt is legal to pass the logical sizes

[scroggo, 2015/01/22 19:47:46]

it*

[reed1, 2015/01/27 18:42:40]

Done.

+     *  (though smaller than those will return false). However, this may
+     *  (depending on the implementation) be slower than passing in the optimal-allocation sizes
+     *  (or larger). The extra space may allow the implementation to run faster at the cost of
+     *  slightly more ram being allocated. There should be no performance penalty for the
+     *  allocationSizes to larger than the values in optimalAllocationSizes, as they are just the
+     *  minimum sizes for best performance.
+     *
+     *  If colorSpace is not NULL, return the corresponding colorSpace for the YUV data.
+     */
+    bool getYUV8(const SkISize allocationSizes[3], void* planes[3], SkYUVColorSpace* colorSpace);

[scroggo, 2015/01/22 19:47:46]

Can the color space be known in queryYUV8?

[reed1, 2015/01/27 18:42:39]

Yea, good question. Seems like its a slightly more onerous constraint on the
codec, so I was going to leave it off until someone made a case for knowing it
sooner. Do you think we should push for it to be at the query step?

[scroggo, 2015/01/27 18:59:18]

It would make sense to me if it was known at the query step, but I don't know
enough about JPEG to know when we could know that.

Our jpeg decoder only uses one color space, so our implementation could easily
specify it at the query step.

VideoImageGenerator in Chromium checks a VideoFrame's ::format() to determine
the colorspace
(https://code.google.com/p/chromium/codesearch#chromium/src/media/filters/skca...).
It appears that the format is constant
(https://code.google.com/p/chromium/codesearch#chromium/src/media/base/video_f...).

So at least for the existing implementations, putting it at the query step is
not a problem.

That said, if we were ever to support the other SkYUVColorSpace,
kRec601_SkYUVColorSpace, I don't know how soon we can know the color space.
sugoi?

 
     /**
      *  If the default image decoder system can interpret the specified (encoded) data, then
@@ -134,9 +167,14 @@ protected:
     virtual bool onGetPixels(const SkImageInfo& info,
                              void* pixels, size_t rowBytes,
                              SkPMColor ctable[], int* ctableCount);
+    virtual bool onQueryYUV8(SkISize logicalSizes[3], SkISize optimalAllocationSizes[3]);

[scroggo, 2015/01/22 19:47:47]

Should we have documentation for implementors that the parameters will not be
NULL when calling the virtual functions?

[reed1, 2015/01/27 18:42:40]

Done.

+    virtual bool onGetYUV8(const SkISize allocationSizes[3], void* planes[3],
+                           SkYUVColorSpace*);
+#ifdef SK_SUPPORT_LEGACY_IMAGEGENERATOR_YUV_API
     virtual bool onGetYUV8Planes(SkISize sizes[3], void* planes[3], size_t rowBytes[3]);
     virtual bool onGetYUV8Planes(SkISize sizes[3], void* planes[3], size_t rowBytes[3],
                                  SkYUVColorSpace* colorSpace);
+#endif
 };
 
 #endif  // SkImageGenerator_DEFINED