Document SkSurface::MakeRaster's memory initialization

include/core/SkSurface.h

 /*
  * Copyright 2012 Google Inc.
  *
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 #ifndef SkSurface_DEFINED
 #define SkSurface_DEFINED
 
@@ skipping 13 matching lines @@
  *
  *  To draw into a canvas, first create the appropriate type of Surface, and
  *  then request the canvas from the surface.
  *
  *  SkSurface always has non-zero dimensions. If there is a request for a new surface, and either
  *  of the requested dimensions are zero, then NULL will be returned.
  */
 class SK_API SkSurface : public SkRefCnt {
 public:
     /**
      *  Create a new surface, using the specified pixels/rowbytes as its

[reed1, 2016/07/01 20:11:42]

Lets document that do or do not zero-init this memory.

[f(malita), 2016/07/05 15:39:53]

Done.

      *  backend.
      *
      *  If the requested surface cannot be created, or the request is not a
      *  supported configuration, NULL will be returned.
      */
     static sk_sp<SkSurface> MakeRasterDirect(const SkImageInfo&, void* pixels, size_t rowBytes,
                                              const SkSurfaceProps* = nullptr);
 
     /**
      *  The same as NewRasterDirect, but also accepts a call-back routine, which is invoked
      *  when the surface is deleted, and is passed the pixel memory and the specified context.
      */
     static sk_sp<SkSurface> MakeRasterDirectReleaseProc(const SkImageInfo&, void* pixels, size_t rowBytes,
                                                  void (*releaseProc)(void* pixels, void* context),
                                                  void* context, const SkSurfaceProps* = nullptr);
 
     /**
-     *  Return a new surface, with the memory for the pixels automatically allocated, but respecting
-     *  the specified rowBytes. If rowBytes==0, then a default value will be chosen. If a non-zero
-     *  rowBytes is specified, then any images snapped off of this surface (via newImageSnapshot())
-     *  are guaranteed to have the same rowBytes.
+     *  Return a new surface, with the memory for the pixels automatically allocated and
+     *  zero-initialized, but respecting the specified rowBytes. If rowBytes==0, then a default

[reed1, 2016/06/15 15:30:35]

Do we consistently make this promise for surfaces (gpu backed as well)? That if
Skia allocates the buffer, it will *always* be initialized? If so, then lgtm

[f(malita), 2016/06/15 15:36:37]

Even if we only do this for raster, it's still worth documenting, no?

(the CL only makes this promise for Make*Raster* currently)

[bsalomon, 2016/06/15 16:18:23]

I believe we do this for GPU as well.

+     *  value will be chosen. If a non-zero rowBytes is specified, then any images snapped off of
+     *  this surface (via makeImageSnapshot()) are guaranteed to have the same rowBytes.
      *
      *  If the requested surface cannot be created, or the request is not a
      *  supported configuration, NULL will be returned.
      */
     static sk_sp<SkSurface> MakeRaster(const SkImageInfo&, size_t rowBytes, const SkSurfaceProps*);
 
     /**
      *  Allocate a new surface, automatically computing the rowBytes.
      */
     static sk_sp<SkSurface> MakeRaster(const SkImageInfo&, const SkSurfaceProps* = nullptr);

[reed1, 2016/07/01 20:11:42]

Maybe we should have this guy be inline, so that its obvious that the above
comment applies to us as well.

e.g.
{
    return MakeRaster(info, 0, props);
}

[f(malita), 2016/07/05 15:39:53]

Done.

 
     /**
      *  Helper version of NewRaster. It creates a SkImageInfo with the
      *  specified width and height, and populates the rest of info to match
      *  pixels in SkPMColor format.
      */
     static sk_sp<SkSurface> MakeRasterN32Premul(int width, int height,
                                                 const SkSurfaceProps* props = nullptr) {
         return MakeRaster(SkImageInfo::MakeN32Premul(width, height), props);
     }
@@ skipping 290 matching lines @@
 private:
     const SkSurfaceProps fProps;
     const int            fWidth;
     const int            fHeight;
     uint32_t             fGenerationID;
 
     typedef SkRefCnt INHERITED;
 };
 
 #endif