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/SkPixmap.h"
13 #include "include/core/SkRefCnt.h"
15 
16 #if SK_SUPPORT_GPU
17 #include "include/gpu/GrTypes.h"
18 #endif
19 
20 #if defined(SK_BUILD_FOR_ANDROID) && __ANDROID_API__ >= 26
21 #include <android/hardware_buffer.h>
22 #endif
23 
24 #if SK_SUPPORT_GPU && defined(SK_METAL)
25 #include "include/gpu/mtl/GrMtlTypes.h"
26 #endif
27 
28 class SkCanvas;
29 class SkCapabilities;
31 class SkPaint;
34 class GrBackendSemaphore;
35 class GrBackendTexture;
36 class GrDirectContext;
37 class GrRecordingContext;
38 class GrRenderTarget;
39 enum GrSurfaceOrigin: int;
40 
41 namespace skgpu {
42 class MutableTextureState;
43 }
44 
45 namespace skgpu::graphite {
46 class BackendTexture;
47 class Recorder;
48 }
49 
58 class SK_API SkSurface : public SkRefCnt {
59 public:
60 
82  static sk_sp<SkSurface> MakeRasterDirect(const SkImageInfo& imageInfo, void* pixels,
83  size_t rowBytes,
84  const SkSurfaceProps* surfaceProps = nullptr);
85 
87  const SkSurfaceProps* props = nullptr) {
88  return MakeRasterDirect(pm.info(), pm.writable_addr(), pm.rowBytes(), props);
89  }
90 
115  static sk_sp<SkSurface> MakeRasterDirectReleaseProc(const SkImageInfo& imageInfo, void* pixels,
116  size_t rowBytes,
117  void (*releaseProc)(void* pixels, void* context),
118  void* context, const SkSurfaceProps* surfaceProps = nullptr);
119 
140  static sk_sp<SkSurface> MakeRaster(const SkImageInfo& imageInfo, size_t rowBytes,
141  const SkSurfaceProps* surfaceProps);
142 
159  static sk_sp<SkSurface> MakeRaster(const SkImageInfo& imageInfo,
160  const SkSurfaceProps* props = nullptr) {
161  return MakeRaster(imageInfo, 0, props);
162  }
163 
182  static sk_sp<SkSurface> MakeRasterN32Premul(int width, int height,
183  const SkSurfaceProps* surfaceProps = nullptr);
184 
186  typedef void* ReleaseContext;
187 
189  typedef void (*RenderTargetReleaseProc)(ReleaseContext releaseContext);
190 
192  typedef void (*TextureReleaseProc)(ReleaseContext releaseContext);
193 
222  const GrBackendTexture& backendTexture,
223  GrSurfaceOrigin origin, int sampleCnt,
224  SkColorType colorType,
225  sk_sp<SkColorSpace> colorSpace,
226  const SkSurfaceProps* surfaceProps,
227  TextureReleaseProc textureReleaseProc = nullptr,
228  ReleaseContext releaseContext = nullptr);
229 
256  const GrBackendRenderTarget& backendRenderTarget,
257  GrSurfaceOrigin origin,
258  SkColorType colorType,
259  sk_sp<SkColorSpace> colorSpace,
260  const SkSurfaceProps* surfaceProps,
261  RenderTargetReleaseProc releaseProc = nullptr,
262  ReleaseContext releaseContext = nullptr);
263 
291  const SkImageInfo& imageInfo,
292  int sampleCount, GrSurfaceOrigin surfaceOrigin,
293  const SkSurfaceProps* surfaceProps,
294  bool shouldCreateWithMips = false);
295 
318  const SkImageInfo& imageInfo, int sampleCount,
319  const SkSurfaceProps* surfaceProps) {
320 #if SK_SUPPORT_GPU
321  return MakeRenderTarget(context, budgeted, imageInfo, sampleCount,
322  kBottomLeft_GrSurfaceOrigin, surfaceProps);
323 #else
324  // TODO(kjlubick, scroggo) Remove this once Android is updated.
325  return nullptr;
326 #endif
327  }
328 
343  const SkImageInfo& imageInfo) {
344 #if SK_SUPPORT_GPU
345  if (!imageInfo.width() || !imageInfo.height()) {
346  return nullptr;
347  }
348  return MakeRenderTarget(context, budgeted, imageInfo, 0, kBottomLeft_GrSurfaceOrigin,
349  nullptr);
350 #else
351  // TODO(kjlubick, scroggo) Remove this once Android is updated.
352  return nullptr;
353 #endif
354  }
355 
364  const SkSurfaceCharacterization& characterization,
365  SkBudgeted budgeted);
366 
367 
368 #if defined(SK_BUILD_FOR_ANDROID) && __ANDROID_API__ >= 26
390  static sk_sp<SkSurface> MakeFromAHardwareBuffer(GrDirectContext* context,
391  AHardwareBuffer* hardwareBuffer,
392  GrSurfaceOrigin origin,
393  sk_sp<SkColorSpace> colorSpace,
394  const SkSurfaceProps* surfaceProps
395 #ifdef SK_BUILD_FOR_ANDROID_FRAMEWORK
396  , bool fromWindow = false
397 #endif // SK_BUILD_FOR_ANDROID_FRAMEWORK
398  );
399 #endif
400 
401 #ifdef SK_GRAPHITE_ENABLED
408  static sk_sp<SkSurface> MakeGraphite(
409  skgpu::graphite::Recorder*,
410  const SkImageInfo& imageInfo,
411  skgpu::graphite::Mipmapped = skgpu::graphite::Mipmapped::kNo,
412  const SkSurfaceProps* surfaceProps = nullptr);
413 
427  static sk_sp<SkSurface> MakeGraphiteFromBackendTexture(skgpu::graphite::Recorder*,
428  const skgpu::graphite::BackendTexture&,
429  SkColorType colorType,
430  sk_sp<SkColorSpace> colorSpace,
431  const SkSurfaceProps* props);
432 
433 #endif // SK_GRAPHITE_ENABLED
434 
435 #if SK_SUPPORT_GPU && defined(SK_METAL)
455  static sk_sp<SkSurface> MakeFromCAMetalLayer(GrRecordingContext* context,
456  GrMTLHandle layer,
457  GrSurfaceOrigin origin,
458  int sampleCnt,
459  SkColorType colorType,
460  sk_sp<SkColorSpace> colorSpace,
461  const SkSurfaceProps* surfaceProps,
462  GrMTLHandle* drawable)
463  SK_API_AVAILABLE_CA_METAL_LAYER;
464 
482  static sk_sp<SkSurface> MakeFromMTKView(GrRecordingContext* context,
483  GrMTLHandle mtkView,
484  GrSurfaceOrigin origin,
485  int sampleCnt,
486  SkColorType colorType,
487  sk_sp<SkColorSpace> colorSpace,
488  const SkSurfaceProps* surfaceProps)
489  SK_API_AVAILABLE(macos(10.11), ios(9.0));
490 #endif
491 
501  bool isCompatible(const SkSurfaceCharacterization& characterization) const;
502 
512  static sk_sp<SkSurface> MakeNull(int width, int height);
513 
518  int width() const { return fWidth; }
519 
524  int height() const { return fHeight; }
525 
528  virtual SkImageInfo imageInfo() const { return SkImageInfo::MakeUnknown(fWidth, fHeight); }
529 
538  uint32_t generationID();
539 
546  };
547 
556 
562 
567  skgpu::graphite::Recorder* recorder();
568 
569 #if SK_SUPPORT_GPU
570  enum BackendHandleAccess {
571  kFlushRead_BackendHandleAccess,
572  kFlushWrite_BackendHandleAccess,
573  kDiscardWrite_BackendHandleAccess,
574  };
575 
578  static const BackendHandleAccess kFlushRead_TextureHandleAccess =
579  kFlushRead_BackendHandleAccess;
580 
583  static const BackendHandleAccess kFlushWrite_TextureHandleAccess =
584  kFlushWrite_BackendHandleAccess;
585 
588  static const BackendHandleAccess kDiscardWrite_TextureHandleAccess =
589  kDiscardWrite_BackendHandleAccess;
590 
599  GrBackendTexture getBackendTexture(BackendHandleAccess backendHandleAccess);
600 
610  GrBackendRenderTarget getBackendRenderTarget(BackendHandleAccess backendHandleAccess);
611 
627  bool replaceBackendTexture(const GrBackendTexture& backendTexture,
628  GrSurfaceOrigin origin,
629  ContentChangeMode mode = kRetain_ContentChangeMode,
630  TextureReleaseProc textureReleaseProc = nullptr,
631  ReleaseContext releaseContext = nullptr);
632 #endif
633 
643 
649 
664 
668  sk_sp<SkSurface> makeSurface(int width, int height);
669 
679 
692 
693 #ifdef SK_GRAPHITE_ENABLED
715  sk_sp<SkImage> asImage();
716 
717  sk_sp<SkImage> makeImageCopy(const SkIRect* subset = nullptr,
718  skgpu::graphite::Mipmapped mipmapped =
719  skgpu::graphite::Mipmapped::kNo);
720 #endif
721 
735  void draw(SkCanvas* canvas, SkScalar x, SkScalar y, const SkSamplingOptions& sampling,
736  const SkPaint* paint);
737 
738  void draw(SkCanvas* canvas, SkScalar x, SkScalar y, const SkPaint* paint = nullptr) {
739  this->draw(canvas, x, y, SkSamplingOptions(), paint);
740  }
741 
753  bool peekPixels(SkPixmap* pixmap);
754 
784  bool readPixels(const SkPixmap& dst, int srcX, int srcY);
785 
815  bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
816  int srcX, int srcY);
817 
848  bool readPixels(const SkBitmap& dst, int srcX, int srcY);
849 
851 
853  using ReadPixelsContext = void*;
854 
858  using ReadPixelsCallback = void(ReadPixelsContext, std::unique_ptr<const AsyncReadResult>);
859 
865 
897  const SkIRect& srcRect,
898  RescaleGamma rescaleGamma,
899  RescaleMode rescaleMode,
900  ReadPixelsCallback callback,
901  ReadPixelsContext context);
902 
933  sk_sp<SkColorSpace> dstColorSpace,
934  const SkIRect& srcRect,
935  const SkISize& dstSize,
936  RescaleGamma rescaleGamma,
937  RescaleMode rescaleMode,
938  ReadPixelsCallback callback,
939  ReadPixelsContext context);
940 
956  void writePixels(const SkPixmap& src, int dstX, int dstY);
957 
973  void writePixels(const SkBitmap& src, int dstX, int dstY);
974 
979  const SkSurfaceProps& props() const { return fProps; }
980 
989  void flushAndSubmit(bool syncCpu = false);
990 
991  enum class BackendSurfaceAccess {
992  kNoAccess,
993  kPresent,
994  };
995 
996 #if SK_SUPPORT_GPU
1008  void resolveMSAA();
1009 
1054  GrSemaphoresSubmitted flush(BackendSurfaceAccess access, const GrFlushInfo& info);
1055 
1100  GrSemaphoresSubmitted flush(const GrFlushInfo& info,
1101  const skgpu::MutableTextureState* newState = nullptr);
1102 #endif // SK_SUPPORT_GPU
1103 
1104  void flush();
1105 
1121  bool wait(int numSemaphores, const GrBackendSemaphore* waitSemaphores,
1122  bool deleteSemaphoresAfterWait = true);
1123 
1136  bool characterize(SkSurfaceCharacterization* characterization) const;
1137 
1154  bool draw(sk_sp<const SkDeferredDisplayList> deferredDisplayList,
1155  int xOffset = 0,
1156  int yOffset = 0);
1157 
1158 protected:
1159  SkSurface(int width, int height, const SkSurfaceProps* surfaceProps);
1160  SkSurface(const SkImageInfo& imageInfo, const SkSurfaceProps* surfaceProps);
1161 
1162  // called by subclass if their contents have changed
1164  fGenerationID = 0;
1165  }
1166 
1167 private:
1168  const SkSurfaceProps fProps;
1169  const int fWidth;
1170  const int fHeight;
1171  uint32_t fGenerationID;
1172 
1173  using INHERITED = SkRefCnt;
1174 };
1175 
1176 #endif
GrSurfaceOrigin
GPU SkImage and SkSurfaces can be stored such that (0, 0) in texture space may correspond to either t...
Definition: GrTypes.h:154
@ kBottomLeft_GrSurfaceOrigin
Definition: GrTypes.h:156
GrSemaphoresSubmitted
Enum used as return value when flush with semaphores so the client knows whether the valid semaphores...
Definition: GrTypes.h:239
SkColorType
Describes how pixel bits encode color.
Definition: SkColorType.h:19
SkYUVColorSpace
Definition: SkImageInfo.h:66
float SkScalar
Definition: SkScalar.h:16
#define SK_API_AVAILABLE(...)
Definition: SkTypes.h:437
SkBudgeted
Indicates whether an allocation should count against a cache budget.
Definition: SkTypes.h:620
#define SK_API
Definition: SkTypes.h:181
Definition: GrBackendSurface.h:76
Wrapper class for passing into and receiving data from Ganesh about a backend semaphore object.
Definition: GrBackendSemaphore.h:30
Definition: GrBackendSurface.h:69
Definition: GrDirectContext.h:54
Definition: GrRecordingContext.h:44
SkBitmap describes a two-dimensional raster pixel array.
Definition: SkBitmap.h:51
SkCanvas provides an interface for drawing, and how the drawing is clipped and transformed.
Definition: SkCanvas.h:102
Definition: SkCapabilities.h:22
Definition: SkDeferredDisplayList.h:31
The result from asyncRescaleAndReadPixels() or asyncRescaleAndReadPixelsYUV420().
Definition: SkImage.h:918
RescaleMode
Definition: SkImage.h:944
RescaleGamma
Definition: SkImage.h:942
SkPaint controls options applied when drawing.
Definition: SkPaint.h:40
SkPixmap provides a utility to pair SkImageInfo with pixels and row bytes.
Definition: SkPixmap.h:31
size_t rowBytes() const
Returns row bytes, the interval from one pixel row to the next.
Definition: SkPixmap.h:136
void * writable_addr() const
Returns writable base pixel address.
Definition: SkPixmap.h:474
const SkImageInfo & info() const
Returns width, height, SkAlphaType, SkColorType, and SkColorSpace.
Definition: SkPixmap.h:126
Definition: SkRefCnt.h:118
Definition: SkSurfaceCharacterization.h:216
Describes properties and constraints of a given SkSurface.
Definition: SkSurfaceProps.h:51
SkSurface is responsible for managing the pixels that a canvas draws into.
Definition: SkSurface.h:58
void dirtyGenerationID()
Definition: SkSurface.h:1163
ContentChangeMode
Definition: SkSurface.h:543
@ kDiscard_ContentChangeMode
discards surface on change
Definition: SkSurface.h:544
@ kRetain_ContentChangeMode
preserves surface on change
Definition: SkSurface.h:545
const SkSurfaceProps & props() const
Returns SkSurfaceProps for surface.
Definition: SkSurface.h:979
void flushAndSubmit(bool syncCpu=false)
Call to ensure all reads/writes of the surface have been issued to the underlying 3D API.
bool characterize(SkSurfaceCharacterization *characterization) const
Initializes SkSurfaceCharacterization that can be used to perform GPU back-end processing in a separa...
static sk_sp< SkSurface > MakeRenderTarget(GrRecordingContext *context, const SkSurfaceCharacterization &characterization, SkBudgeted budgeted)
Returns SkSurface on GPU indicated by context that is compatible with the provided characterization.
bool readPixels(const SkImageInfo &dstInfo, void *dstPixels, size_t dstRowBytes, int srcX, int srcY)
Copies SkRect of pixels from SkCanvas into dstPixels.
void(ReadPixelsContext, std::unique_ptr< const AsyncReadResult >) ReadPixelsCallback
Client-provided callback to asyncRescaleAndReadPixels() or asyncRescaleAndReadPixelsYUV420() that is ...
Definition: SkSurface.h:858
int width() const
Returns pixel count in each row; may be zero or greater.
Definition: SkSurface.h:518
sk_sp< const SkCapabilities > capabilities()
Returns SkCapabilities that describes the capabilities of the SkSurface's device.
sk_sp< SkSurface > makeSurface(const SkImageInfo &imageInfo)
Returns a compatible SkSurface, or nullptr.
void writePixels(const SkBitmap &src, int dstX, int dstY)
Copies SkRect of pixels from the src SkBitmap to the SkSurface.
static sk_sp< SkSurface > MakeFromBackendRenderTarget(GrRecordingContext *context, const GrBackendRenderTarget &backendRenderTarget, GrSurfaceOrigin origin, SkColorType colorType, sk_sp< SkColorSpace > colorSpace, const SkSurfaceProps *surfaceProps, RenderTargetReleaseProc releaseProc=nullptr, ReleaseContext releaseContext=nullptr)
Wraps a GPU-backed buffer into SkSurface.
bool isCompatible(const SkSurfaceCharacterization &characterization) const
Is this surface compatible with the provided characterization?
void draw(SkCanvas *canvas, SkScalar x, SkScalar y, const SkSamplingOptions &sampling, const SkPaint *paint)
Draws SkSurface contents to canvas, with its top-left corner at (x, y).
static sk_sp< SkSurface > MakeRenderTarget(GrRecordingContext *context, SkBudgeted budgeted, const SkImageInfo &imageInfo, int sampleCount, const SkSurfaceProps *surfaceProps)
Returns SkSurface on GPU indicated by context.
Definition: SkSurface.h:317
static sk_sp< SkSurface > MakeFromBackendTexture(GrRecordingContext *context, const GrBackendTexture &backendTexture, GrSurfaceOrigin origin, int sampleCnt, SkColorType colorType, sk_sp< SkColorSpace > colorSpace, const SkSurfaceProps *surfaceProps, TextureReleaseProc textureReleaseProc=nullptr, ReleaseContext releaseContext=nullptr)
Wraps a GPU-backed texture into SkSurface.
void asyncRescaleAndReadPixels(const SkImageInfo &info, const SkIRect &srcRect, RescaleGamma rescaleGamma, RescaleMode rescaleMode, ReadPixelsCallback callback, ReadPixelsContext context)
Makes surface pixel data available to caller, possibly asynchronously.
virtual SkImageInfo imageInfo() const
Returns an ImageInfo describing the surface.
Definition: SkSurface.h:528
GrRecordingContext * recordingContext()
Returns the recording context being used by the SkSurface.
static sk_sp< SkSurface > MakeRasterDirect(const SkPixmap &pm, const SkSurfaceProps *props=nullptr)
Definition: SkSurface.h:86
void draw(SkCanvas *canvas, SkScalar x, SkScalar y, const SkPaint *paint=nullptr)
Definition: SkSurface.h:738
static sk_sp< SkSurface > MakeRasterN32Premul(int width, int height, const SkSurfaceProps *surfaceProps=nullptr)
Allocates raster SkSurface.
bool peekPixels(SkPixmap *pixmap)
Copies SkSurface pixel address, row bytes, and SkImageInfo to SkPixmap, if address is available,...
static sk_sp< SkSurface > MakeNull(int width, int height)
Returns SkSurface without backing pixels.
sk_sp< SkSurface > makeSurface(int width, int height)
Calls makeSurface(ImageInfo) with the same ImageInfo as this surface, but with the specified width an...
static sk_sp< SkSurface > MakeRaster(const SkImageInfo &imageInfo, const SkSurfaceProps *props=nullptr)
Allocates raster SkSurface.
Definition: SkSurface.h:159
SkSurface(const SkImageInfo &imageInfo, const SkSurfaceProps *surfaceProps)
sk_sp< SkImage > makeImageSnapshot()
Returns SkImage capturing SkSurface contents.
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)
Allocates raster SkSurface.
bool draw(sk_sp< const SkDeferredDisplayList > deferredDisplayList, int xOffset=0, int yOffset=0)
Draws the deferred display list created via a SkDeferredDisplayListRecorder.
int height() const
Returns pixel row count; may be zero or greater.
Definition: SkSurface.h:524
static sk_sp< SkSurface > MakeRenderTarget(GrRecordingContext *context, SkBudgeted budgeted, const SkImageInfo &imageInfo, int sampleCount, GrSurfaceOrigin surfaceOrigin, const SkSurfaceProps *surfaceProps, bool shouldCreateWithMips=false)
Returns SkSurface on GPU indicated by context.
void flush()
bool readPixels(const SkBitmap &dst, int srcX, int srcY)
Copies SkRect of pixels from SkSurface into bitmap.
void asyncRescaleAndReadPixelsYUV420(SkYUVColorSpace yuvColorSpace, sk_sp< SkColorSpace > dstColorSpace, const SkIRect &srcRect, const SkISize &dstSize, RescaleGamma rescaleGamma, RescaleMode rescaleMode, ReadPixelsCallback callback, ReadPixelsContext context)
Similar to asyncRescaleAndReadPixels but performs an additional conversion to YUV.
BackendSurfaceAccess
Definition: SkSurface.h:991
static sk_sp< SkSurface > MakeRenderTarget(GrRecordingContext *context, SkBudgeted budgeted, const SkImageInfo &imageInfo)
Returns SkSurface on GPU indicated by context.
Definition: SkSurface.h:342
skgpu::graphite::Recorder * recorder()
Returns the recorder being used by the SkSurface.
SkSurface(int width, int height, const SkSurfaceProps *surfaceProps)
void writePixels(const SkPixmap &src, int dstX, int dstY)
Copies SkRect of pixels from the src SkPixmap to the SkSurface.
static sk_sp< SkSurface > MakeRaster(const SkImageInfo &imageInfo, size_t rowBytes, const SkSurfaceProps *surfaceProps)
Allocates raster SkSurface.
void notifyContentWillChange(ContentChangeMode mode)
Notifies that SkSurface contents will be changed by code outside of Skia.
void * ReleaseContext
Caller data passed to RenderTarget/TextureReleaseProc; may be nullptr.
Definition: SkSurface.h:186
bool wait(int numSemaphores, const GrBackendSemaphore *waitSemaphores, bool deleteSemaphoresAfterWait=true)
Inserts a list of GPU semaphores that the current GPU-backed API must wait on before executing any mo...
SkCanvas * getCanvas()
Returns SkCanvas that draws into SkSurface.
static sk_sp< SkSurface > MakeRasterDirect(const SkImageInfo &imageInfo, void *pixels, size_t rowBytes, const SkSurfaceProps *surfaceProps=nullptr)
Allocates raster SkSurface.
bool readPixels(const SkPixmap &dst, int srcX, int srcY)
Copies SkRect of pixels to dst.
void * ReadPixelsContext
Client-provided context that is passed to client-provided ReadPixelsContext.
Definition: SkSurface.h:853
sk_sp< SkImage > makeImageSnapshot(const SkIRect &bounds)
Like the no-parameter version, this returns an image of the current surface contents.
uint32_t generationID()
Returns unique value identifying the content of SkSurface.
Definition: SkRefCnt.h:224
Since Skia and clients can both modify gpu textures and their connected state, Skia needs a way for c...
Definition: MutableTextureState.h:33
Definition: SkCanvas.h:71
This file includes numerous public types that are used by all of our gpu backends.
Definition: SkCanvas.h:71
Struct to supply options to flush calls.
Definition: GrTypes.h:226
SkIRect holds four 32-bit integer coordinates describing the upper and lower bounds of a rectangle.
Definition: SkRect.h:28
Definition: SkSize.h:13
Describes pixel dimensions and encoding.
Definition: SkImageInfo.h:192
static SkImageInfo MakeUnknown()
Creates SkImageInfo from integral dimensions width and height set to zero, kUnknown_SkColorType,...
Definition: SkImageInfo.h:341
int width() const
Returns pixel count in each row.
Definition: SkImageInfo.h:349
int height() const
Returns pixel row count.
Definition: SkImageInfo.h:355
Definition: SkSamplingOptions.h:58