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. Each Size is a width/height in pixels for its plane.
+     *
+     *  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]);
+
+    /**
+     *  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(), it is legal to pass the logical sizes
+     *  (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);
 
     /**
      *  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);
+    // logicalSizes and optimalAllocationSizes will be non-null
+    virtual bool onQueryYUV8(SkISize logicalSizes[3], SkISize optimalAllocationSizes[3]);
+    // logicalSizes and optimalAllocationSizes and planes will be non-null.
+    // colorSpace may still be null.
+    virtual bool onGetYUV8(const SkISize allocationSizes[3], void* planes[3],
+                           SkYUVColorSpace* colorSpace);
+#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