new API for retrieving YUV data

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 "SkColor.h"
 #include "SkImageInfo.h"
 
+//#define SK_SUPPORT_LEGACY_IMAGEGENERATOR_YUV_API
+
 class SkBitmap;
 class SkData;
 class SkImageGenerator;
 
 /**
  *  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.
  *
@@ skipping 76 matching lines @@
      *          unsupported.
      */
     bool getPixels(const SkImageInfo& info, void* pixels, size_t rowBytes,
                    SkPMColor ctable[], int* ctableCount);
 
     /**
      *  Simplified version of getPixels() that asserts that info is NOT kIndex8_SkColorType.
      */
     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
      *  return YUV planar data. If it cannot, it should return false. Note that either planes and
      *  rowBytes are both fully defined and non NULL/non 0 or they are both NULL or have NULL or 0
      *  entries only. Having only partial planes/rowBytes information is not supported.
      *
      *  If all planes and rowBytes entries are non NULL or non 0, then it should copy the
      *  associated YUV data into those planes of memory supplied by the caller. It should validate
      *  that the sizes match what it expected. If the sizes do not match, it should return false.
      */
     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
      *  this returns a new ImageGenerator for it. Otherwise this returns NULL. Either way
      *  the caller is still responsible for managing their ownership of the data.
      */
     static SkImageGenerator* NewFromData(SkData*);
 
 protected:
     virtual SkData* onRefEncodedData();
     virtual bool onGetInfo(SkImageInfo* info);
     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