include/core/SkSurface.h - skia - Git at Google

 /*
  * 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

 #include "SkRefCnt.h"
 #include "SkImage.h"
 #include "SkSurfaceProps.h"

 #include "GrTypes.h"

 class SkCanvas;
 class SkDeferredDisplayList;
 class SkPaint;
 class SkSurfaceCharacterization;
 class GrBackendRenderTarget;
 class GrBackendSemaphore;
 class GrContext;
 class GrRenderTarget;

 /**
  *  SkSurface is responsible for managing the pixels that a canvas draws into. The pixels can be
  *  allocated either in CPU memory (a Raster surface) or on the GPU (a RenderTarget surface).
  *
  *  SkSurface takes care of allocating a SkCanvas that will draw into the surface. Call
  *  surface->getCanvas() to use that canvas (but don't delete it, it is owned by 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
      *  backend.
      *
      *  If the requested surface cannot be created, or the request is not a
      *  supported configuration, NULL will be returned.
      *
      *  Callers are responsible for initialiazing the surface pixels.
      */
     static sk_sp<SkSurface> MakeRasterDirect(const SkImageInfo& imageInfo, void* pixels,
                                              size_t rowBytes,
                                              const SkSurfaceProps* surfaceProps = 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& imageInfo, void* pixels,
                                     size_t rowBytes,
                                     void (*releaseProc)(void* pixels, void* context),
                                     void* context, const SkSurfaceProps* surfaceProps = nullptr);

     /**
      *  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
      *  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& imageInfo, size_t rowBytes,
                                        const SkSurfaceProps* surfaceProps);

     /**
      *  Allocate a new surface, automatically computing the rowBytes.
      */
     static sk_sp<SkSurface> MakeRaster(const SkImageInfo& imageInfo,
                                        const SkSurfaceProps* props = nullptr) {
         return MakeRaster(imageInfo, 0, props);
     }

     /**
      *  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* surfaceProps = nullptr) {
         return MakeRaster(SkImageInfo::MakeN32Premul(width, height), surfaceProps);
     }

     /**
      *  Used to wrap a pre-existing backend 3D API texture as a SkSurface. Skia will not assume
      *  ownership of the texture and the client must ensure the texture is valid for the lifetime
      *  of the SkSurface. If sampleCnt > 1, then we will create an intermediate mssa surface which
      *  we will use for rendering. We then resolve into the passed in texture.
      */
     static sk_sp<SkSurface> MakeFromBackendTexture(GrContext* context,
                                                    const GrBackendTexture& backendTexture,
                                                    GrSurfaceOrigin origin, int sampleCnt,
                                                    sk_sp<SkColorSpace> colorSpace,
                                                    const SkSurfaceProps* surfaceProps);

     /**
      *  Used to wrap a pre-existing backend 3D API texture as a SkSurface. Skia will not assume
      *  ownership of the texture and the client must ensure the texture is valid for the lifetime
      *  of the SkSurface. If sampleCnt > 1, then we will create an intermediate mssa surface which
      *  we will use for rendering. We then resolve into the passed in texture.
      *
      *  The GrBackendTexture must have a valid backend format supplied (GrGLTextureInfo::fFormat,
      *  GrVkImageInfo::fFormat, etc.) in it. The passed in SkColorType informs skia how it should
      *  interpret the backend format supplied by the GrBackendTexture. If the format in the
      *  GrBackendTexture is not compatible with the sampleCnt, SkColorType, and SkColorSpace we
      *  will return nullptr.
      */
     static sk_sp<SkSurface> MakeFromBackendTexture(GrContext* context,
                                                    const GrBackendTexture& backendTexture,
                                                    GrSurfaceOrigin origin, int sampleCnt,
                                                    SkColorType colorType,
                                                    sk_sp<SkColorSpace> colorSpace,
                                                    const SkSurfaceProps* surfaceProps);

     static sk_sp<SkSurface> MakeFromBackendRenderTarget(GrContext* context,
                                                 const GrBackendRenderTarget& backendRenderTarget,
                                                 GrSurfaceOrigin origin,
                                                 sk_sp<SkColorSpace> colorSpace,
                                                 const SkSurfaceProps* surfaceProps);

     /**
      *  The GrBackendRenderTarget must have a valid backend format set (GrGLTextureInfo::fFormat,
      *  GrVkImageInfo::fFormat, etc.) in it. The passed in SkColorType informs skia how it should
      *  interpret the backend format supplied by the GrBackendRenderTarget. If the format in the
      *  GrBackendRenderTarget is not compatible with the sampleCnt, SkColorType, and SkColorSpace
      *  we will return nullptr.
      */
     static sk_sp<SkSurface> MakeFromBackendRenderTarget(GrContext* context,
                                                 const GrBackendRenderTarget& backendRenderTarget,
                                                 GrSurfaceOrigin origin,
                                                 SkColorType colorType,
                                                 sk_sp<SkColorSpace> colorSpace,
                                                 const SkSurfaceProps* surfaceProps);

     /**
      *  Used to wrap a pre-existing 3D API texture as a SkSurface. Skia will treat the texture as
      *  a rendering target only, but unlike NewFromBackendRenderTarget, Skia will manage and own
      *  the associated render target objects (but not the provided texture). Skia will not assume
      *  ownership of the texture and the client must ensure the texture is valid for the lifetime
      *  of the SkSurface.
      */
     static sk_sp<SkSurface> MakeFromBackendTextureAsRenderTarget(GrContext* context,
                                                             const GrBackendTexture& backendTexture,
                                                             GrSurfaceOrigin origin,
                                                             int sampleCnt,
                                                             sk_sp<SkColorSpace> colorSpace,
                                                             const SkSurfaceProps* surfaceProps);

     /**
      *  Used to wrap a pre-existing 3D API texture as a SkSurface. Skia will treat the texture as
      *  a rendering target only, but unlike NewFromBackendRenderTarget, Skia will manage and own
      *  the associated render target objects (but not the provided texture). Skia will not assume
      *  ownership of the texture and the client must ensure the texture is valid for the lifetime
      *  of the SkSurface.
      *
      *  The GrBackendTexture must have a valid backend format supplied (GrGLTextureInfo::fFormat,
      *  GrVkImageInfo::fFormat, etc.) in it. The passed in SkColorType informs skia how it should
      *  interpret the backend format supplied by the GrBackendTexture. If the format in the
      *  GrBackendTexture is not compatible with the sampleCnt, SkColorType, and SkColorSpace we
      *  will return nullptr.
      */
     static sk_sp<SkSurface> MakeFromBackendTextureAsRenderTarget(GrContext* context,
                                                             const GrBackendTexture& backendTexture,
                                                             GrSurfaceOrigin origin,
                                                             int sampleCnt,
                                                             SkColorType colorType,
                                                             sk_sp<SkColorSpace> colorSpace,
                                                             const SkSurfaceProps* surfaceProps);

     /**
      *  Return a new surface whose contents will be drawn to an offscreen
      *  render target, allocated by the surface. The optional shouldCreateWithMips flag is a hint
      *  that this surface may be snapped to an SkImage which will be used with mip maps so we should
      *  create the backend gpu RenderTarget with mips to avoid a copy later on.
      */
     static sk_sp<SkSurface> MakeRenderTarget(GrContext* context, SkBudgeted budgeted,
                                              const SkImageInfo& imageInfo,
                                              int sampleCount, GrSurfaceOrigin surfaceOrigin,
                                              const SkSurfaceProps* surfaceProps,
                                              bool shouldCreateWithMips = false);

     static sk_sp<SkSurface> MakeRenderTarget(GrContext* context, SkBudgeted budgeted,
                                              const SkImageInfo& imageInfo, int sampleCount,
                                              const SkSurfaceProps* props) {
         return MakeRenderTarget(context, budgeted, imageInfo, sampleCount,
                                 kBottomLeft_GrSurfaceOrigin, props);
     }

     static sk_sp<SkSurface> MakeRenderTarget(GrContext* context, SkBudgeted budgeted,
                                              const SkImageInfo& imageInfo) {
         if (!imageInfo.width() || !imageInfo.height()) {
             return nullptr;
         }
         return MakeRenderTarget(context, budgeted, imageInfo, 0, kBottomLeft_GrSurfaceOrigin,
                                 nullptr);
     }

     /**
      *  Returns a surface that stores no pixels. It can be drawn to via its canvas, but that
      *  canvas does not draw anything. Calling makeImageSnapshot() will return nullptr.
      */
     static sk_sp<SkSurface> MakeNull(int width, int height);

     int width() const { return fWidth; }
     int height() const { return fHeight; }

     /**
      *  Returns a unique non-zero, unique value identifying the content of this
      *  surface. Each time the content is changed changed, either by drawing
      *  into this surface, or explicitly calling notifyContentChanged()) this
      *  method will return a new value.
      *
      *  If this surface is empty (i.e. has a zero-dimention), this will return
      *  0.
      */
     uint32_t generationID();

     /**
      *  Modes that can be passed to notifyContentWillChange
      */
     enum ContentChangeMode {
         /**
          *  Use this mode if it is known that the upcoming content changes will
          *  clear or overwrite prior contents, thus making them discardable.
          */
         kDiscard_ContentChangeMode,
         /**
          *  Use this mode if prior surface contents need to be preserved or
          *  if in doubt.
          */
         kRetain_ContentChangeMode,
     };

     /**
      *  Call this if the contents are about to change. This will (lazily) force a new
      *  value to be returned from generationID() when it is called next.
      *
      *  CAN WE DEPRECATE THIS?
      */
     void notifyContentWillChange(ContentChangeMode mode);

     enum BackendHandleAccess {
         kFlushRead_BackendHandleAccess,     //!< caller may read from the backend object
         kFlushWrite_BackendHandleAccess,    //!< caller may write to the backend object
         kDiscardWrite_BackendHandleAccess,  //!< caller must over-write the entire backend object
     };

     /*
      * These are legacy aliases which will be removed soon
      */
     static const BackendHandleAccess kFlushRead_TextureHandleAccess =
             kFlushRead_BackendHandleAccess;
     static const BackendHandleAccess kFlushWrite_TextureHandleAccess =
             kFlushWrite_BackendHandleAccess;
     static const BackendHandleAccess kDiscardWrite_TextureHandleAccess =
             kDiscardWrite_BackendHandleAccess;


     /**
      *  Retrieves the backend API handle of the texture used by this surface, or 0 if the surface
      *  is not backed by a GPU texture.
      *
      *  The returned texture-handle is only valid until the next draw-call into the surface,
      *  or the surface is deleted.
      */
     GrBackendObject getTextureHandle(BackendHandleAccess backendHandleAccess);

     /**
      *  Retrieves the backend API handle of the RenderTarget backing this surface.  Callers must
      *  ensure this function returns 'true' or else the GrBackendObject will be invalid
      *
      *  In OpenGL this will return the FramebufferObject ID.
      */
     bool getRenderTargetHandle(GrBackendObject* backendObject,
                                BackendHandleAccess backendHandleAccess);

     /**
      *  Return a canvas that will draw into this surface. This will always
      *  return the same canvas for a given surface, and is manged/owned by the
      *  surface. It should not be used when its parent surface has gone out of
      *  scope.
      */
     SkCanvas* getCanvas();

     /**
      *  Return a new surface that is "compatible" with this one, in that it will
      *  efficiently be able to be drawn into this surface. Typical calling
      *  pattern:
      *
      *  SkSurface* A = SkSurface::New...();
      *  SkCanvas* canvasA = surfaceA->newCanvas();
      *  ...
      *  SkSurface* surfaceB = surfaceA->newSurface(...);
      *  SkCanvas* canvasB = surfaceB->newCanvas();
      *  ... // draw using canvasB
      *  canvasA->drawSurface(surfaceB); // <--- this will always be optimal!
      */
     sk_sp<SkSurface> makeSurface(const SkImageInfo& imageInfo);

     /**
      *  Returns an image of the current state of the surface pixels up to this
      *  point. Subsequent changes to the surface (by drawing into its canvas)
      *  will not be reflected in this image. For the GPU-backend, the budgeting
      *  decision for the snapped image will match that of the surface.
      */
     sk_sp<SkImage> makeImageSnapshot();

     /**
      *  Though the caller could get a snapshot image explicitly, and draw that,
      *  it seems that directly drawing a surface into another canvas might be
      *  a common pattern, and that we could possibly be more efficient, since
      *  we'd know that the "snapshot" need only live until we've handed it off
      *  to the canvas.
      */
     void draw(SkCanvas* canvas, SkScalar x, SkScalar y, const SkPaint* paint);

     /**
      *  If the surface has direct access to its pixels (i.e. they are in local
      *  RAM) return true, and if not null, set the pixmap parameter to point to the information
      *  about the surface's pixels. The pixel address in the pixmap is only valid while
      *  the surface object is in scope, and no API call is made on the surface
      *  or its canvas.
      *
      *  On failure, returns false and the pixmap parameter is ignored.
      */
     bool peekPixels(SkPixmap* pixmap);

     /**
      *  Copy the pixels from the surface into the specified pixmap,
      *  converting them into the pixmap's format. The surface pixels are read
      *  starting at the specified (srcX,srcY) location.
      *
      *  The pixmap and (srcX,srcY) offset specifies a source rectangle
      *
      *      srcR.setXYWH(srcX, srcY, pixmap.width(), pixmap.height());
      *
      *  srcR is intersected with the bounds of the base-layer. If this intersection is not empty,
      *  then we have two sets of pixels (of equal size). Replace the dst pixels with the
      *  corresponding src pixels, performing any colortype/alphatype transformations needed
      *  (in the case where the src and dst have different colortypes or alphatypes).
      *
      *  This call can fail, returning false, for several reasons:
      *  - If srcR does not intersect the surface bounds.
      *  - If the requested colortype/alphatype cannot be converted from the surface's types.
      */
     bool readPixels(const SkPixmap& dst, int srcX, int srcY);
     bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
                     int srcX, int srcY);
     bool readPixels(const SkBitmap& dst, int srcX, int srcY);

     const SkSurfaceProps& props() const { return fProps; }

     /**
      * Issue any pending surface IO to the current backend 3D API and resolve any surface MSAA.
      *
      * The flush calls below are the new preferred way to flush calls to a surface, and this call
      * will eventually be removed.
      */
     void prepareForExternalIO();

     /**
      * Issue any pending surface IO to the current backend 3D API
      */
     void flush();

     /**
      * Issue any pending surface IO to the current backend 3D API. After issuing all commands,
      * numSemaphore semaphores will be signaled by the gpu. The client passes in an array of
      * numSemaphores GrBackendSemaphores. In general these GrBackendSemaphore's can be either
      * initialized or not. If they are initialized, the backend uses the passed in semaphore.
      * If it is not initialized, a new semaphore is created and the GrBackendSemaphore object
      * is initialized with that semaphore.
      *
      * The client will own and be responsible for deleting the underlying semaphores that are stored
      * and returned in initialized GrBackendSemaphore objects. The GrBackendSemaphore objects
      * themselves can be deleted as soon as this function returns.
      *
      * If the backend API is OpenGL only uninitialized GrBackendSemaphores are supported.
      * If the backend API is Vulkan either initialized or unitialized semaphores are supported.
      * If unitialized, the semaphores which are created will be valid for use only with the VkDevice
      * with which they were created.
      *
      * If this call returns GrSemaphoresSubmited::kNo, the GPU backend will not have created or
      * added any semaphores to signal on the GPU. Thus the client should not have the GPU wait on
      * any of the semaphores. However, any pending surface IO will still be flushed.
      */
     GrSemaphoresSubmitted flushAndSignalSemaphores(int numSemaphores,
                                                    GrBackendSemaphore signalSemaphores[]);

     /**
      * Inserts a list of GPU semaphores that the current backend 3D API must wait on before
      * executing any more commands on the GPU for this surface. Skia will take ownership of the
      * underlying semaphores and delete them once they have been signaled and waited on.
      *
      * If this call returns false, then the GPU backend will not wait on any passed in semaphores,
      * and the client will still own the semaphores.
      */
     bool wait(int numSemaphores, const GrBackendSemaphore* waitSemaphores);

     /**
      * This creates a characterization of this SkSurface's properties that can
      * be used to perform gpu-backend preprocessing in a separate thread (via
      * the SkDeferredDisplayListRecorder).
      * It will return false on failure (e.g., if the SkSurface is cpu-backed).
      */
     bool characterize(SkSurfaceCharacterization* characterization) const;

     /**
      * Draw a deferred display list (created via SkDeferredDisplayListRecorder).
      * The draw will be skipped if the characterization stored in the display list
      * isn't compatible with this surface.
      */
     bool draw(SkDeferredDisplayList* deferredDisplayList);

 protected:
     SkSurface(int width, int height, const SkSurfaceProps* surfaceProps);
     SkSurface(const SkImageInfo& imageInfo, const SkSurfaceProps* surfaceProps);

     // called by subclass if their contents have changed
     void dirtyGenerationID() {
         fGenerationID = 0;
     }

 private:
     const SkSurfaceProps fProps;
     const int            fWidth;
     const int            fHeight;
     uint32_t             fGenerationID;

     typedef SkRefCnt INHERITED;
 };

 #endif
	/*
	* 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

	#include "SkRefCnt.h"
	#include "SkImage.h"
	#include "SkSurfaceProps.h"

	#include "GrTypes.h"

	class SkCanvas;
	class SkDeferredDisplayList;
	class SkPaint;
	class SkSurfaceCharacterization;
	class GrBackendRenderTarget;
	class GrBackendSemaphore;
	class GrContext;
	class GrRenderTarget;

	/**
	* SkSurface is responsible for managing the pixels that a canvas draws into. The pixels can be
	* allocated either in CPU memory (a Raster surface) or on the GPU (a RenderTarget surface).
	*
	* SkSurface takes care of allocating a SkCanvas that will draw into the surface. Call
	* surface->getCanvas() to use that canvas (but don't delete it, it is owned by 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
	* backend.
	*
	* If the requested surface cannot be created, or the request is not a
	* supported configuration, NULL will be returned.
	*
	* Callers are responsible for initialiazing the surface pixels.
	*/
	static sk_sp<SkSurface> MakeRasterDirect(const SkImageInfo& imageInfo, void* pixels,
	size_t rowBytes,
	const SkSurfaceProps* surfaceProps = 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& imageInfo, void* pixels,
	size_t rowBytes,
	void (releaseProc)(void pixels, void* context),
	void* context, const SkSurfaceProps* surfaceProps = nullptr);

	/**
	* 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
	* 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& imageInfo, size_t rowBytes,
	const SkSurfaceProps* surfaceProps);

	/**
	* Allocate a new surface, automatically computing the rowBytes.
	*/
	static sk_sp<SkSurface> MakeRaster(const SkImageInfo& imageInfo,
	const SkSurfaceProps* props = nullptr) {
	return MakeRaster(imageInfo, 0, props);
	}

	/**
	* 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* surfaceProps = nullptr) {
	return MakeRaster(SkImageInfo::MakeN32Premul(width, height), surfaceProps);
	}

	/**
	* Used to wrap a pre-existing backend 3D API texture as a SkSurface. Skia will not assume
	* ownership of the texture and the client must ensure the texture is valid for the lifetime
	* of the SkSurface. If sampleCnt > 1, then we will create an intermediate mssa surface which
	* we will use for rendering. We then resolve into the passed in texture.
	*/
	static sk_sp<SkSurface> MakeFromBackendTexture(GrContext* context,
	const GrBackendTexture& backendTexture,
	GrSurfaceOrigin origin, int sampleCnt,
	sk_sp<SkColorSpace> colorSpace,
	const SkSurfaceProps* surfaceProps);

	/**
	* Used to wrap a pre-existing backend 3D API texture as a SkSurface. Skia will not assume
	* ownership of the texture and the client must ensure the texture is valid for the lifetime
	* of the SkSurface. If sampleCnt > 1, then we will create an intermediate mssa surface which
	* we will use for rendering. We then resolve into the passed in texture.
	*
	* The GrBackendTexture must have a valid backend format supplied (GrGLTextureInfo::fFormat,
	* GrVkImageInfo::fFormat, etc.) in it. The passed in SkColorType informs skia how it should
	* interpret the backend format supplied by the GrBackendTexture. If the format in the
	* GrBackendTexture is not compatible with the sampleCnt, SkColorType, and SkColorSpace we
	* will return nullptr.
	*/
	static sk_sp<SkSurface> MakeFromBackendTexture(GrContext* context,
	const GrBackendTexture& backendTexture,
	GrSurfaceOrigin origin, int sampleCnt,
	SkColorType colorType,
	sk_sp<SkColorSpace> colorSpace,
	const SkSurfaceProps* surfaceProps);

	static sk_sp<SkSurface> MakeFromBackendRenderTarget(GrContext* context,
	const GrBackendRenderTarget& backendRenderTarget,
	GrSurfaceOrigin origin,
	sk_sp<SkColorSpace> colorSpace,
	const SkSurfaceProps* surfaceProps);

	/**
	* The GrBackendRenderTarget must have a valid backend format set (GrGLTextureInfo::fFormat,
	* GrVkImageInfo::fFormat, etc.) in it. The passed in SkColorType informs skia how it should
	* interpret the backend format supplied by the GrBackendRenderTarget. If the format in the
	* GrBackendRenderTarget is not compatible with the sampleCnt, SkColorType, and SkColorSpace
	* we will return nullptr.
	*/
	static sk_sp<SkSurface> MakeFromBackendRenderTarget(GrContext* context,
	const GrBackendRenderTarget& backendRenderTarget,
	GrSurfaceOrigin origin,
	SkColorType colorType,
	sk_sp<SkColorSpace> colorSpace,
	const SkSurfaceProps* surfaceProps);

	/**
	* Used to wrap a pre-existing 3D API texture as a SkSurface. Skia will treat the texture as
	* a rendering target only, but unlike NewFromBackendRenderTarget, Skia will manage and own
	* the associated render target objects (but not the provided texture). Skia will not assume
	* ownership of the texture and the client must ensure the texture is valid for the lifetime
	* of the SkSurface.
	*/
	static sk_sp<SkSurface> MakeFromBackendTextureAsRenderTarget(GrContext* context,
	const GrBackendTexture& backendTexture,
	GrSurfaceOrigin origin,
	int sampleCnt,
	sk_sp<SkColorSpace> colorSpace,
	const SkSurfaceProps* surfaceProps);

	/**
	* Used to wrap a pre-existing 3D API texture as a SkSurface. Skia will treat the texture as
	* a rendering target only, but unlike NewFromBackendRenderTarget, Skia will manage and own
	* the associated render target objects (but not the provided texture). Skia will not assume
	* ownership of the texture and the client must ensure the texture is valid for the lifetime
	* of the SkSurface.
	*
	* The GrBackendTexture must have a valid backend format supplied (GrGLTextureInfo::fFormat,
	* GrVkImageInfo::fFormat, etc.) in it. The passed in SkColorType informs skia how it should
	* interpret the backend format supplied by the GrBackendTexture. If the format in the
	* GrBackendTexture is not compatible with the sampleCnt, SkColorType, and SkColorSpace we
	* will return nullptr.
	*/
	static sk_sp<SkSurface> MakeFromBackendTextureAsRenderTarget(GrContext* context,
	const GrBackendTexture& backendTexture,
	GrSurfaceOrigin origin,
	int sampleCnt,
	SkColorType colorType,
	sk_sp<SkColorSpace> colorSpace,
	const SkSurfaceProps* surfaceProps);

	/**
	* Return a new surface whose contents will be drawn to an offscreen
	* render target, allocated by the surface. The optional shouldCreateWithMips flag is a hint
	* that this surface may be snapped to an SkImage which will be used with mip maps so we should
	* create the backend gpu RenderTarget with mips to avoid a copy later on.
	*/
	static sk_sp<SkSurface> MakeRenderTarget(GrContext* context, SkBudgeted budgeted,
	const SkImageInfo& imageInfo,
	int sampleCount, GrSurfaceOrigin surfaceOrigin,
	const SkSurfaceProps* surfaceProps,
	bool shouldCreateWithMips = false);

	static sk_sp<SkSurface> MakeRenderTarget(GrContext* context, SkBudgeted budgeted,
	const SkImageInfo& imageInfo, int sampleCount,
	const SkSurfaceProps* props) {
	return MakeRenderTarget(context, budgeted, imageInfo, sampleCount,
	kBottomLeft_GrSurfaceOrigin, props);
	}

	static sk_sp<SkSurface> MakeRenderTarget(GrContext* context, SkBudgeted budgeted,
	const SkImageInfo& imageInfo) {
	if (!imageInfo.width() \|\| !imageInfo.height()) {
	return nullptr;
	}
	return MakeRenderTarget(context, budgeted, imageInfo, 0, kBottomLeft_GrSurfaceOrigin,
	nullptr);
	}

	/**
	* Returns a surface that stores no pixels. It can be drawn to via its canvas, but that
	* canvas does not draw anything. Calling makeImageSnapshot() will return nullptr.
	*/
	static sk_sp<SkSurface> MakeNull(int width, int height);

	int width() const { return fWidth; }
	int height() const { return fHeight; }

	/**
	* Returns a unique non-zero, unique value identifying the content of this
	* surface. Each time the content is changed changed, either by drawing
	* into this surface, or explicitly calling notifyContentChanged()) this
	* method will return a new value.
	*
	* If this surface is empty (i.e. has a zero-dimention), this will return
	* 0.
	*/
	uint32_t generationID();

	/**
	* Modes that can be passed to notifyContentWillChange
	*/
	enum ContentChangeMode {
	/**
	* Use this mode if it is known that the upcoming content changes will
	* clear or overwrite prior contents, thus making them discardable.
	*/
	kDiscard_ContentChangeMode,
	/**
	* Use this mode if prior surface contents need to be preserved or
	* if in doubt.
	*/
	kRetain_ContentChangeMode,
	};

	/**
	* Call this if the contents are about to change. This will (lazily) force a new
	* value to be returned from generationID() when it is called next.
	*
	* CAN WE DEPRECATE THIS?
	*/
	void notifyContentWillChange(ContentChangeMode mode);

	enum BackendHandleAccess {
	kFlushRead_BackendHandleAccess, //!< caller may read from the backend object
	kFlushWrite_BackendHandleAccess, //!< caller may write to the backend object
	kDiscardWrite_BackendHandleAccess, //!< caller must over-write the entire backend object
	};

	/*
	* These are legacy aliases which will be removed soon
	*/
	static const BackendHandleAccess kFlushRead_TextureHandleAccess =
	kFlushRead_BackendHandleAccess;
	static const BackendHandleAccess kFlushWrite_TextureHandleAccess =
	kFlushWrite_BackendHandleAccess;
	static const BackendHandleAccess kDiscardWrite_TextureHandleAccess =
	kDiscardWrite_BackendHandleAccess;


	/**
	* Retrieves the backend API handle of the texture used by this surface, or 0 if the surface
	* is not backed by a GPU texture.
	*
	* The returned texture-handle is only valid until the next draw-call into the surface,
	* or the surface is deleted.
	*/
	GrBackendObject getTextureHandle(BackendHandleAccess backendHandleAccess);

	/**
	* Retrieves the backend API handle of the RenderTarget backing this surface. Callers must
	* ensure this function returns 'true' or else the GrBackendObject will be invalid
	*
	* In OpenGL this will return the FramebufferObject ID.
	*/
	bool getRenderTargetHandle(GrBackendObject* backendObject,
	BackendHandleAccess backendHandleAccess);

	/**
	* Return a canvas that will draw into this surface. This will always
	* return the same canvas for a given surface, and is manged/owned by the
	* surface. It should not be used when its parent surface has gone out of
	* scope.
	*/
	SkCanvas* getCanvas();

	/**
	* Return a new surface that is "compatible" with this one, in that it will
	* efficiently be able to be drawn into this surface. Typical calling
	* pattern:
	*
	* SkSurface* A = SkSurface::New...();
	* SkCanvas* canvasA = surfaceA->newCanvas();
	* ...
	* SkSurface* surfaceB = surfaceA->newSurface(...);
	* SkCanvas* canvasB = surfaceB->newCanvas();
	* ... // draw using canvasB
	* canvasA->drawSurface(surfaceB); // <--- this will always be optimal!
	*/
	sk_sp<SkSurface> makeSurface(const SkImageInfo& imageInfo);

	/**
	* Returns an image of the current state of the surface pixels up to this
	* point. Subsequent changes to the surface (by drawing into its canvas)
	* will not be reflected in this image. For the GPU-backend, the budgeting
	* decision for the snapped image will match that of the surface.
	*/
	sk_sp<SkImage> makeImageSnapshot();

	/**
	* Though the caller could get a snapshot image explicitly, and draw that,
	* it seems that directly drawing a surface into another canvas might be
	* a common pattern, and that we could possibly be more efficient, since
	* we'd know that the "snapshot" need only live until we've handed it off
	* to the canvas.
	*/
	void draw(SkCanvas* canvas, SkScalar x, SkScalar y, const SkPaint* paint);

	/**
	* If the surface has direct access to its pixels (i.e. they are in local
	* RAM) return true, and if not null, set the pixmap parameter to point to the information
	* about the surface's pixels. The pixel address in the pixmap is only valid while
	* the surface object is in scope, and no API call is made on the surface
	* or its canvas.
	*
	* On failure, returns false and the pixmap parameter is ignored.
	*/
	bool peekPixels(SkPixmap* pixmap);

	/**
	* Copy the pixels from the surface into the specified pixmap,
	* converting them into the pixmap's format. The surface pixels are read
	* starting at the specified (srcX,srcY) location.
	*
	* The pixmap and (srcX,srcY) offset specifies a source rectangle
	*
	* srcR.setXYWH(srcX, srcY, pixmap.width(), pixmap.height());
	*
	* srcR is intersected with the bounds of the base-layer. If this intersection is not empty,
	* then we have two sets of pixels (of equal size). Replace the dst pixels with the
	* corresponding src pixels, performing any colortype/alphatype transformations needed
	* (in the case where the src and dst have different colortypes or alphatypes).
	*
	* This call can fail, returning false, for several reasons:
	* - If srcR does not intersect the surface bounds.
	* - If the requested colortype/alphatype cannot be converted from the surface's types.
	*/
	bool readPixels(const SkPixmap& dst, int srcX, int srcY);
	bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
	int srcX, int srcY);
	bool readPixels(const SkBitmap& dst, int srcX, int srcY);

	const SkSurfaceProps& props() const { return fProps; }

	/**
	* Issue any pending surface IO to the current backend 3D API and resolve any surface MSAA.
	*
	* The flush calls below are the new preferred way to flush calls to a surface, and this call
	* will eventually be removed.
	*/
	void prepareForExternalIO();

	/**
	* Issue any pending surface IO to the current backend 3D API
	*/
	void flush();

	/**
	* Issue any pending surface IO to the current backend 3D API. After issuing all commands,
	* numSemaphore semaphores will be signaled by the gpu. The client passes in an array of
	* numSemaphores GrBackendSemaphores. In general these GrBackendSemaphore's can be either
	* initialized or not. If they are initialized, the backend uses the passed in semaphore.
	* If it is not initialized, a new semaphore is created and the GrBackendSemaphore object
	* is initialized with that semaphore.
	*
	* The client will own and be responsible for deleting the underlying semaphores that are stored
	* and returned in initialized GrBackendSemaphore objects. The GrBackendSemaphore objects
	* themselves can be deleted as soon as this function returns.
	*
	* If the backend API is OpenGL only uninitialized GrBackendSemaphores are supported.
	* If the backend API is Vulkan either initialized or unitialized semaphores are supported.
	* If unitialized, the semaphores which are created will be valid for use only with the VkDevice
	* with which they were created.
	*
	* If this call returns GrSemaphoresSubmited::kNo, the GPU backend will not have created or
	* added any semaphores to signal on the GPU. Thus the client should not have the GPU wait on
	* any of the semaphores. However, any pending surface IO will still be flushed.
	*/
	GrSemaphoresSubmitted flushAndSignalSemaphores(int numSemaphores,
	GrBackendSemaphore signalSemaphores[]);

	/**
	* Inserts a list of GPU semaphores that the current backend 3D API must wait on before
	* executing any more commands on the GPU for this surface. Skia will take ownership of the
	* underlying semaphores and delete them once they have been signaled and waited on.
	*
	* If this call returns false, then the GPU backend will not wait on any passed in semaphores,
	* and the client will still own the semaphores.
	*/
	bool wait(int numSemaphores, const GrBackendSemaphore* waitSemaphores);

	/**
	* This creates a characterization of this SkSurface's properties that can
	* be used to perform gpu-backend preprocessing in a separate thread (via
	* the SkDeferredDisplayListRecorder).
	* It will return false on failure (e.g., if the SkSurface is cpu-backed).
	*/
	bool characterize(SkSurfaceCharacterization* characterization) const;

	/**
	* Draw a deferred display list (created via SkDeferredDisplayListRecorder).
	* The draw will be skipped if the characterization stored in the display list
	* isn't compatible with this surface.
	*/
	bool draw(SkDeferredDisplayList* deferredDisplayList);

	protected:
	SkSurface(int width, int height, const SkSurfaceProps* surfaceProps);
	SkSurface(const SkImageInfo& imageInfo, const SkSurfaceProps* surfaceProps);

	// called by subclass if their contents have changed
	void dirtyGenerationID() {
	fGenerationID = 0;
	}

	private:
	const SkSurfaceProps fProps;
	const int fWidth;
	const int fHeight;
	uint32_t fGenerationID;

	typedef SkRefCnt INHERITED;
	};

	#endif