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
 
@@ skipping 104 matching lines @@
      *  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);
 
     /**
+     *  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.

[sugoi1, 2015/01/22 15:01:37]

What if the decoder failed completely and the logical sizes were also not set?
(maybe the image's header isn't fully downloaded yet because of a crappy
internet connection) I don't know if that's possible, just wondering.

[reed1, 2015/01/22 16:01:36]

To get to the stage of being an imagegenerator at all, we needed to have decoded
enough to know the "master" W/H. However, if we fail to get the next step of
querying the U/V plane sizes, then I think this should return false.

[scroggo, 2015/01/27 18:35:49]

In general, I would suggest that if it returns false, all output parameters
should be assumed to be undefined. (I think this matches our behavior
elsewhere.)

I'm also not sure why the logical sizes would be known by the decoder and not
the optimalAllocationSizes. All the information comes from the cinfo, which was
initilized when reading the header.

[reed1, 2015/01/27 18:44:03]

Agreed, will make that change.
Agreed.

+     */
+    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.
+     *
+     *  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);
     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  // SkImageGenerator_DEFINED