Skia
2D Graphics Library
SkSurface.h
Go to the documentation of this file.
1 /*
2  * Copyright 2012 Google Inc.
3  *
4  * Use of this source code is governed by a BSD-style license that can be
5  * found in the LICENSE file.
6  */
7 
8 #ifndef SkSurface_DEFINED
9 #define SkSurface_DEFINED
10 
11 #include "include/core/SkImage.h"
12 #include "include/core/SkRefCnt.h"
14 
15 #include "include/gpu/GrTypes.h"
16 
17 #if defined(SK_BUILD_FOR_ANDROID) && __ANDROID_API__ >= 26
18 #include <android/hardware_buffer.h>
19 #endif
20 
21 #ifdef SK_METAL
22 #include "include/gpu/mtl/GrMtlTypes.h"
23 #endif
24 
25 class SkCanvas;
27 class SkPaint;
30 class GrBackendSemaphore;
31 class GrBackendTexture;
32 class GrContext;
33 class GrRecordingContext;
34 class GrRenderTarget;
35 
44 class SK_API SkSurface : public SkRefCnt {
45 public:
46 
68  static sk_sp<SkSurface> MakeRasterDirect(const SkImageInfo& imageInfo, void* pixels,
69  size_t rowBytes,
70  const SkSurfaceProps* surfaceProps = nullptr);
71 
96  static sk_sp<SkSurface> MakeRasterDirectReleaseProc(const SkImageInfo& imageInfo, void* pixels,
97  size_t rowBytes,
98  void (*releaseProc)(void* pixels, void* context),
99  void* context, const SkSurfaceProps* surfaceProps = nullptr);
100 
121  static sk_sp<SkSurface> MakeRaster(const SkImageInfo& imageInfo, size_t rowBytes,
122  const SkSurfaceProps* surfaceProps);
123 
140  static sk_sp<SkSurface> MakeRaster(const SkImageInfo& imageInfo,
141  const SkSurfaceProps* props = nullptr) {
142  return MakeRaster(imageInfo, 0, props);
143  }
144 
163  static sk_sp<SkSurface> MakeRasterN32Premul(int width, int height,
164  const SkSurfaceProps* surfaceProps = nullptr);
165 
167  typedef void* ReleaseContext;
168 
170  typedef void (*RenderTargetReleaseProc)(ReleaseContext releaseContext);
171 
173  typedef void (*TextureReleaseProc)(ReleaseContext releaseContext);
174 
198  static sk_sp<SkSurface> MakeFromBackendTexture(GrContext* context,
199  const GrBackendTexture& backendTexture,
200  GrSurfaceOrigin origin, int sampleCnt,
201  SkColorType colorType,
202  sk_sp<SkColorSpace> colorSpace,
203  const SkSurfaceProps* surfaceProps,
204  TextureReleaseProc textureReleaseProc = nullptr,
205  ReleaseContext releaseContext = nullptr);
206 
228  static sk_sp<SkSurface> MakeFromBackendRenderTarget(GrContext* context,
229  const GrBackendRenderTarget& backendRenderTarget,
230  GrSurfaceOrigin origin,
231  SkColorType colorType,
232  sk_sp<SkColorSpace> colorSpace,
233  const SkSurfaceProps* surfaceProps,
234  RenderTargetReleaseProc releaseProc = nullptr,
235  ReleaseContext releaseContext = nullptr);
236 
260  static sk_sp<SkSurface> MakeFromBackendTextureAsRenderTarget(GrContext* context,
261  const GrBackendTexture& backendTexture,
262  GrSurfaceOrigin origin,
263  int sampleCnt,
264  SkColorType colorType,
265  sk_sp<SkColorSpace> colorSpace,
266  const SkSurfaceProps* surfaceProps);
267 
268 #if defined(SK_BUILD_FOR_ANDROID) && __ANDROID_API__ >= 26
269 
288  static sk_sp<SkSurface> MakeFromAHardwareBuffer(GrContext* context,
289  AHardwareBuffer* hardwareBuffer,
290  GrSurfaceOrigin origin,
291  sk_sp<SkColorSpace> colorSpace,
292  const SkSurfaceProps* surfaceProps);
293 #endif
294 
295 #ifdef SK_METAL
296 
315  static sk_sp<SkSurface> MakeFromCAMetalLayer(GrContext* context,
316  GrMTLHandle layer,
317  GrSurfaceOrigin origin,
318  int sampleCnt,
319  SkColorType colorType,
320  sk_sp<SkColorSpace> colorSpace,
321  const SkSurfaceProps* surfaceProps,
322  GrMTLHandle* drawable);
323 
341  static sk_sp<SkSurface> MakeFromMTKView(GrContext* context,
342  GrMTLHandle mtkView,
343  GrSurfaceOrigin origin,
344  int sampleCnt,
345  SkColorType colorType,
346  sk_sp<SkColorSpace> colorSpace,
347  const SkSurfaceProps* surfaceProps)
348  SK_API_AVAILABLE(macos(10.11), ios(9.0));
349 #endif
350 
377  static sk_sp<SkSurface> MakeRenderTarget(GrContext* context, SkBudgeted budgeted,
378  const SkImageInfo& imageInfo,
379  int sampleCount, GrSurfaceOrigin surfaceOrigin,
380  const SkSurfaceProps* surfaceProps,
381  bool shouldCreateWithMips = false);
382 
405  const SkImageInfo& imageInfo, int sampleCount,
406  const SkSurfaceProps* surfaceProps) {
407  return MakeRenderTarget(context, budgeted, imageInfo, sampleCount,
408  kBottomLeft_GrSurfaceOrigin, surfaceProps);
409  }
410 
425  const SkImageInfo& imageInfo) {
426  if (!imageInfo.width() || !imageInfo.height()) {
427  return nullptr;
428  }
429  return MakeRenderTarget(context, budgeted, imageInfo, 0, kBottomLeft_GrSurfaceOrigin,
430  nullptr);
431  }
432 
440  static sk_sp<SkSurface> MakeRenderTarget(GrRecordingContext* context,
441  const SkSurfaceCharacterization& characterization,
442  SkBudgeted budgeted);
443 
463  static sk_sp<SkSurface> MakeFromBackendTexture(GrContext* context,
464  const SkSurfaceCharacterization& characterzation,
465  const GrBackendTexture& backendTexture,
466  TextureReleaseProc textureReleaseProc = nullptr,
467  ReleaseContext releaseContext = nullptr);
468 
478  bool isCompatible(const SkSurfaceCharacterization& characterization) const;
479 
489  static sk_sp<SkSurface> MakeNull(int width, int height);
490 
495  int width() const { return fWidth; }
496 
501  int height() const { return fHeight; }
502 
505  SkImageInfo imageInfo();
506 
515  uint32_t generationID();
516 
523  };
524 
532  void notifyContentWillChange(ContentChangeMode mode);
533 
538  };
539 
542  static const BackendHandleAccess kFlushRead_TextureHandleAccess =
543  kFlushRead_BackendHandleAccess;
544 
547  static const BackendHandleAccess kFlushWrite_TextureHandleAccess =
548  kFlushWrite_BackendHandleAccess;
549 
552  static const BackendHandleAccess kDiscardWrite_TextureHandleAccess =
553  kDiscardWrite_BackendHandleAccess;
554 
563  GrBackendTexture getBackendTexture(BackendHandleAccess backendHandleAccess);
564 
574  GrBackendRenderTarget getBackendRenderTarget(BackendHandleAccess backendHandleAccess);
575 
587  bool replaceBackendTexture(const GrBackendTexture& backendTexture,
588  GrSurfaceOrigin origin,
589  ContentChangeMode mode = kRetain_ContentChangeMode,
590  TextureReleaseProc textureReleaseProc = nullptr,
591  ReleaseContext releaseContext = nullptr);
592 
601  SkCanvas* getCanvas();
602 
616  sk_sp<SkSurface> makeSurface(const SkImageInfo& imageInfo);
617 
621  sk_sp<SkSurface> makeSurface(int width, int height);
622 
631  sk_sp<SkImage> makeImageSnapshot();
632 
644  sk_sp<SkImage> makeImageSnapshot(const SkIRect& bounds);
645 
659  void draw(SkCanvas* canvas, SkScalar x, SkScalar y, const SkPaint* paint);
660 
672  bool peekPixels(SkPixmap* pixmap);
673 
703  bool readPixels(const SkPixmap& dst, int srcX, int srcY);
704 
734  bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
735  int srcX, int srcY);
736 
767  bool readPixels(const SkBitmap& dst, int srcX, int srcY);
768 
771  public:
772  AsyncReadResult(const AsyncReadResult&) = delete;
773  AsyncReadResult(AsyncReadResult&&) = delete;
774  AsyncReadResult& operator=(const AsyncReadResult&) = delete;
775  AsyncReadResult& operator=(AsyncReadResult&&) = delete;
776 
777  virtual ~AsyncReadResult() = default;
778  virtual int count() const = 0;
779  virtual const void* data(int i) const = 0;
780  virtual size_t rowBytes(int i) const = 0;
781 
782  protected:
783  AsyncReadResult() = default;
784  };
785 
787  using ReadPixelsContext = void*;
788 
792  using ReadPixelsCallback = void(ReadPixelsContext, std::unique_ptr<const AsyncReadResult>);
793 
797  enum RescaleGamma : bool { kSrc, kLinear };
798 
828  void asyncRescaleAndReadPixels(const SkImageInfo& info, const SkIRect& srcRect,
829  RescaleGamma rescaleGamma, SkFilterQuality rescaleQuality,
830  ReadPixelsCallback callback, ReadPixelsContext context);
831 
859  void asyncRescaleAndReadPixelsYUV420(SkYUVColorSpace yuvColorSpace,
860  sk_sp<SkColorSpace> dstColorSpace,
861  const SkIRect& srcRect,
862  const SkISize& dstSize,
863  RescaleGamma rescaleGamma,
864  SkFilterQuality rescaleQuality,
865  ReadPixelsCallback callback,
867 
883  void writePixels(const SkPixmap& src, int dstX, int dstY);
884 
900  void writePixels(const SkBitmap& src, int dstX, int dstY);
901 
906  const SkSurfaceProps& props() const { return fProps; }
907 
914  void flush();
915 
916  enum class BackendSurfaceAccess {
917  kNoAccess,
918  kPresent,
919  };
920 
946  GrSemaphoresSubmitted flush(BackendSurfaceAccess access, const GrFlushInfo& info);
947 
951  int numSemaphores, GrBackendSemaphore signalSemaphores[],
952  GrGpuFinishedProc finishedProc = nullptr,
953  GrGpuFinishedContext finishedContext = nullptr);
954 
957  enum FlushFlags {
958  kNone_FlushFlags = 0,
959  // flush will wait till all submitted GPU work is finished before returning.
960  kSyncCpu_FlushFlag = 0x1,
961  };
963  int numSemaphores, GrBackendSemaphore signalSemaphores[]);
964 
967  GrSemaphoresSubmitted flushAndSignalSemaphores(int numSemaphores,
968  GrBackendSemaphore signalSemaphores[]);
969 
980  bool wait(int numSemaphores, const GrBackendSemaphore* waitSemaphores);
981 
994  bool characterize(SkSurfaceCharacterization* characterization) const;
995 
1007  bool draw(SkDeferredDisplayList* deferredDisplayList);
1008 
1009 protected:
1010  SkSurface(int width, int height, const SkSurfaceProps* surfaceProps);
1011  SkSurface(const SkImageInfo& imageInfo, const SkSurfaceProps* surfaceProps);
1012 
1013  // called by subclass if their contents have changed
1015  fGenerationID = 0;
1016  }
1017 
1018 private:
1019  const SkSurfaceProps fProps;
1020  const int fWidth;
1021  const int fHeight;
1022  uint32_t fGenerationID;
1023 
1024  typedef SkRefCnt INHERITED;
1025 };
1026 
1027 #endif
GrFlushFlags
Definition: GrTypes.h:228
SkCanvas provides an interface for drawing, and how the drawing is clipped and transformed.
Definition: SkCanvas.h:80
void dirtyGenerationID()
Definition: SkSurface.h:1014
Definition: GrBackendSurface.h:59
Describes pixel dimensions and encoding.
Definition: SkImageInfo.h:274
RescaleGamma
Controls the gamma that rescaling occurs in for asyncRescaleAndReadPixels() and asyncRescaleAndReadPi...
Definition: SkSurface.h:797
Describes properties and constraints of a given SkSurface.
Definition: SkSurfaceProps.h:51
SkPixmap provides a utility to pair SkImageInfo with pixels and row bytes.
Definition: SkPixmap.h:30
SkYUVColorSpace
Definition: SkImageInfo.h:151
#define SK_API
Definition: SkTypes.h:187
SkSurface is responsible for managing the pixels that a canvas draws into.
Definition: SkSurface.h:44
GrSurfaceOrigin
GPU SkImage and SkSurfaces can be stored such that (0, 0) in texture space may correspond to either t...
Definition: GrTypes.h:196
Definition: SkRefCnt.h:118
SkPaint controls options applied when drawing.
Definition: SkPaint.h:36
Definition: GrBackendSurface.h:52
void(ReadPixelsContext, std::unique_ptr< const AsyncReadResult >) ReadPixelsCallback
Client-provided callback to asyncRescaleAndReadPixels() or asyncRescaleAndReadPixelsYUV420() that is ...
Definition: SkSurface.h:792
back-end object must be overwritten
Definition: SkSurface.h:537
Definition: SkSurfaceCharacterization.h:205
Wrapper class for passing into and receiving data from Ganesh about a backend semaphore object...
Definition: GrBackendSemaphore.h:20
static sk_sp< SkSurface > MakeRaster(const SkImageInfo &imageInfo, const SkSurfaceProps *props=nullptr)
Allocates raster SkSurface.
Definition: SkSurface.h:140
static constexpr skcms_TransferFunction kLinear
Definition: SkColorSpace.h:48
SkBudgeted
Indicates whether an allocation should count against a cache budget.
Definition: SkTypes.h:612
static sk_sp< SkSurface > MakeRenderTarget(GrContext *context, SkBudgeted budgeted, const SkImageInfo &imageInfo, int sampleCount, const SkSurfaceProps *surfaceProps)
Returns SkSurface on GPU indicated by context.
Definition: SkSurface.h:404
SkBitmap describes a two-dimensional raster pixel array.
Definition: SkBitmap.h:47
Shared pointer class to wrap classes that support a ref()/unref() interface.
Definition: SkRefCnt.h:215
int width() const
Returns pixel count in each row.
Definition: SkImageInfo.h:443
SkColorType
Definition: SkImageInfo.h:70
The result from asyncRescaleAndReadPixels() or asyncRescaleAndReadPixelsYUV420(). ...
Definition: SkSurface.h:770
void * GrGpuFinishedContext
Definition: GrTypes.h:234
ContentChangeMode
Definition: SkSurface.h:520
Definition: GrContext.h:49
preserves surface on change
Definition: SkSurface.h:522
Definition: SkSize.h:13
BackendSurfaceAccess
Definition: SkSurface.h:916
void * ReadPixelsContext
Client-provided context that is passed to client-provided ReadPixelsContext.
Definition: SkSurface.h:787
back-end object is readable
Definition: SkSurface.h:535
discards surface on change
Definition: SkSurface.h:521
int height() const
Returns pixel row count; may be zero or greater.
Definition: SkSurface.h:501
FlushFlags
The below enum and flush call are deprecated.
Definition: SkSurface.h:957
Definition: SkDeferredDisplayList.h:30
int width() const
Returns pixel count in each row; may be zero or greater.
Definition: SkSurface.h:495
float SkScalar
Definition: SkScalar.h:16
static sk_sp< SkSurface > MakeRenderTarget(GrContext *context, SkBudgeted budgeted, const SkImageInfo &imageInfo)
Returns SkSurface on GPU indicated by context.
Definition: SkSurface.h:424
void(* GrGpuFinishedProc)(GrGpuFinishedContext finishedContext)
Definition: GrTypes.h:235
SkFilterQuality
Controls how much filtering to be done when scaling/transforming complex colors e.g.
Definition: SkFilterQuality.h:17
Struct to supply options to flush calls.
Definition: GrTypes.h:255
#define SK_API_AVAILABLE(...)
Definition: SkTypes.h:444
replaces destination
GrSemaphoresSubmitted
Enum used as return value when flush with semaphores so the client knows whether the semaphores were ...
Definition: GrTypes.h:267
SkIRect holds four 32-bit integer coordinates describing the upper and lower bounds of a rectangle...
Definition: SkRect.h:28
back-end object is writable
Definition: SkSurface.h:536
Definition: GrTypes.h:198
void * ReleaseContext
Caller data passed to RenderTarget/TextureReleaseProc; may be nullptr.
Definition: SkSurface.h:167
const SkSurfaceProps & props() const
Returns SkSurfaceProps for surface.
Definition: SkSurface.h:906
BackendHandleAccess
Definition: SkSurface.h:534
int height() const
Returns pixel row count.
Definition: SkImageInfo.h:449