SkSurface is responsible for managing the pixels that a canvas draws into. More...

#include <SkSurface.h>

Inheritance diagram for SkSurface:

Public Types
enum	ContentChangeMode { kDiscard_ContentChangeMode, kRetain_ContentChangeMode }
	Modes that can be passed to notifyContentWillChange. More...

enum	BackendHandleAccess { kFlushRead_BackendHandleAccess, kFlushWrite_BackendHandleAccess, kDiscardWrite_BackendHandleAccess }

Public Member Functions
int	width () const

int	height () const

uint32_t	generationID ()
	Returns a unique non-zero, unique value identifying the content of this surface. More...

void	notifyContentWillChange (ContentChangeMode mode)
	Call this if the contents are about to change. More...

GrBackendObject	getTextureHandle (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. More...

bool	getRenderTargetHandle (GrBackendObject *, BackendHandleAccess)
	Retrieves the backend API handle of the RenderTarget backing this surface. More...

SkCanvas *	getCanvas ()
	Return a canvas that will draw into this surface. More...

sk_sp< SkSurface >	makeSurface (const SkImageInfo &)
	Return a new surface that is "compatible" with this one, in that it will efficiently be able to be drawn into this surface. More...

sk_sp< SkImage >	makeImageSnapshot ()
	Returns an image of the current state of the surface pixels up to this point. More...

void	draw (SkCanvas , SkScalar x, SkScalar y, const SkPaint )
	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.

bool	peekPixels (SkPixmap *)
	If the surface has direct access to its pixels (i.e. More...

bool	readPixels (const SkImageInfo &dstInfo, void *dstPixels, size_t dstRowBytes, int srcX, int srcY)
	Copy the pixels from the surface into the specified buffer (pixels + rowBytes), converting them into the requested format (dstInfo). More...

const SkSurfaceProps &	props () const

void	prepareForExternalIO ()
	Issue any pending surface IO to the current backend 3D API and resolve any surface MSAA. More...

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

bool	flushAndSignalSemaphores (int numSemaphores, GrBackendSemaphore *signalSemaphores)
	Issue any pending surface IO to the current backend 3D API. More...

bool	wait (int numSemaphores, const GrBackendSemaphore *waitSemaphores)
	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. More...

Public Member Functions inherited from SkRefCntBase
	SkRefCntBase ()
	Default construct, initializing the reference count to 1.

virtual	~SkRefCntBase ()
	Destruct, asserting that the reference count is 1.

int32_t	getRefCnt () const
	Return the reference count. More...

void	validate () const

bool	unique () const
	May return true if the caller is the only owner. More...

void	ref () const
	Increment the reference count. More...

void	unref () const
	Decrement the reference count. More...

Static Public Member Functions
static sk_sp< SkSurface >	MakeRasterDirect (const SkImageInfo &, void pixels, size_t rowBytes, const SkSurfaceProps =nullptr)
	Create a new surface, using the specified pixels/rowbytes as its backend. More...

static sk_sp< SkSurface >	MakeRasterDirectReleaseProc (const SkImageInfo &, void pixels, size_t rowBytes, void(releaseProc)(void pixels, void context), void context, 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 >	MakeRaster (const SkImageInfo &, size_t rowBytes, const SkSurfaceProps *)
	Return a new surface, with the memory for the pixels automatically allocated and zero-initialized, but respecting the specified rowBytes. More...

static sk_sp< SkSurface >	MakeRaster (const SkImageInfo &info, const SkSurfaceProps *props=nullptr)
	Allocate a new surface, automatically computing the rowBytes.

static sk_sp< SkSurface >	MakeRasterN32Premul (int width, int height, const SkSurfaceProps *props=nullptr)
	Helper version of NewRaster. More...

static sk_sp< SkSurface >	MakeFromBackendTexture (GrContext , const GrBackendTextureDesc &, sk_sp< SkColorSpace >, const SkSurfaceProps )
	Used to wrap a pre-existing backend 3D API texture as a SkSurface. More...

static sk_sp< SkSurface >	MakeFromBackendTexture (GrContext , const GrBackendTexture &, GrSurfaceOrigin origin, int sampleCnt, sk_sp< SkColorSpace >, const SkSurfaceProps )
	Used to wrap a pre-existing backend 3D API texture as a SkSurface. More...

static sk_sp< SkSurface >	MakeFromBackendRenderTarget (GrContext , const GrBackendRenderTargetDesc &, sk_sp< SkColorSpace >, const SkSurfaceProps )
	Used to wrap a pre-existing 3D API rendering target as a SkSurface. More...

static sk_sp< SkSurface >	MakeFromBackendRenderTarget (GrContext , const GrBackendRenderTarget &, GrSurfaceOrigin origin, sk_sp< SkColorSpace >, const SkSurfaceProps )

static sk_sp< SkSurface >	MakeFromBackendTextureAsRenderTarget (GrContext , const GrBackendTextureDesc &, sk_sp< SkColorSpace >, const SkSurfaceProps )
	Used to wrap a pre-existing 3D API texture as a SkSurface. More...

static sk_sp< SkSurface >	MakeFromBackendTextureAsRenderTarget (GrContext , const GrBackendTexture &, GrSurfaceOrigin origin, int sampleCnt, sk_sp< SkColorSpace >, const SkSurfaceProps )

static sk_sp< SkSurface >	MakeFromBackendTexture (GrContext ctx, const GrBackendTextureDesc &desc, const SkSurfaceProps props)
	Legacy versions of the above factories, without color space support. More...

static sk_sp< SkSurface >	MakeFromBackendRenderTarget (GrContext ctx, const GrBackendRenderTargetDesc &desc, const SkSurfaceProps props)

static sk_sp< SkSurface >	MakeFromBackendTextureAsRenderTarget (GrContext ctx, const GrBackendTextureDesc &desc, const SkSurfaceProps props)

static sk_sp< SkSurface >	MakeRenderTarget (GrContext , SkBudgeted, const SkImageInfo &, int sampleCount, GrSurfaceOrigin, const SkSurfaceProps )
	Return a new surface whose contents will be drawn to an offscreen render target, allocated by the surface.

static sk_sp< SkSurface >	MakeRenderTarget (GrContext context, SkBudgeted budgeted, const SkImageInfo &info, int sampleCount, const SkSurfaceProps props)

static sk_sp< SkSurface >	MakeRenderTarget (GrContext *gr, SkBudgeted b, const SkImageInfo &info)

Static Public Attributes
static const BackendHandleAccess	kFlushRead_TextureHandleAccess

static const BackendHandleAccess	kFlushWrite_TextureHandleAccess

static const BackendHandleAccess	kDiscardWrite_TextureHandleAccess

Protected Member Functions
	SkSurface (int width, int height, const SkSurfaceProps *)

	SkSurface (const SkImageInfo &, const SkSurfaceProps *)

void	dirtyGenerationID ()

Protected Member Functions inherited from SkRefCntBase
void	internal_dispose_restore_refcnt_to_1 () const
	Allow subclasses to call this if they've overridden internal_dispose so they can reset fRefCnt before the destructor is called or if they choose not to call the destructor (e.g. More...

Private Types
typedef SkRefCnt	INHERITED

Private Attributes
const SkSurfaceProps	fProps

const int	fWidth

const int	fHeight

uint32_t	fGenerationID

Detailed Description

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.

Member Enumeration Documentation

enum SkSurface::BackendHandleAccess

Enumerator
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

enum SkSurface::ContentChangeMode

Modes that can be passed to notifyContentWillChange.

Enumerator
kDiscard_ContentChangeMode	Use this mode if it is known that the upcoming content changes will clear or overwrite prior contents, thus making them discardable.
kRetain_ContentChangeMode	Use this mode if prior surface contents need to be preserved or if in doubt.

Member Function Documentation

bool SkSurface::flushAndSignalSemaphores	(	int	numSemaphores,
		GrBackendSemaphore *	signalSemaphores
	)

Issue any pending surface IO to the current backend 3D API.

After issuing all commands, we will issue numSemaphore semaphores for the gpu to signal. We will then fill in the array signalSemaphores with the info on the semaphores we submitted. The client is reposonsible for allocating enough space in signalSemaphores to handle numSemaphores of GrBackendSemaphores. The client will also take ownership of the returned underlying backend semaphores.

If this call returns false, the GPU backend will not have created or added any semaphores to signal. Thus the array of semaphores will remain uninitialized. However, we will still flush any pending surface IO.

uint32_t SkSurface::generationID ( )

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.

SkCanvas* SkSurface::getCanvas ( )

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.

bool SkSurface::getRenderTargetHandle	(	GrBackendObject *	,
		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.

GrBackendObject SkSurface::getTextureHandle ( 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.

static sk_sp<SkSurface> SkSurface::MakeFromBackendRenderTarget	(	GrContext *	,
		const GrBackendRenderTargetDesc &	,
		sk_sp< SkColorSpace >	,
		const SkSurfaceProps *
	)

static

Used to wrap a pre-existing 3D API rendering target as a SkSurface.

Skia will not assume ownership of the render target and the client must ensure the render target is valid for the lifetime of the SkSurface.

static sk_sp<SkSurface> SkSurface::MakeFromBackendTexture	(	GrContext *	,
		const GrBackendTextureDesc &	,
		sk_sp< SkColorSpace >	,
		const SkSurfaceProps *
	)

static

Used to wrap a pre-existing backend 3D API texture as a SkSurface.

The kRenderTarget flag must be set on GrBackendTextureDesc for this to succeed. 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> SkSurface::MakeFromBackendTexture	(	GrContext *	,
		const GrBackendTexture &	,
		GrSurfaceOrigin	origin,
		int	sampleCnt,
		sk_sp< SkColorSpace >	,
		const SkSurfaceProps *
	)

static

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 > 0, 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> SkSurface::MakeFromBackendTexture	(	GrContext *	ctx,
		const GrBackendTextureDesc &	desc,
		const SkSurfaceProps *	props
	)

inlinestatic

Legacy versions of the above factories, without color space support.

These create "legacy" surfaces that operate without gamma correction or color management.

static sk_sp<SkSurface> SkSurface::MakeFromBackendTextureAsRenderTarget	(	GrContext *	,
		const GrBackendTextureDesc &	,
		sk_sp< SkColorSpace >	,
		const SkSurfaceProps *
	)

static

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). The kRenderTarget flag must be set on GrBackendTextureDesc for this to succeed. Skia will not assume ownership of the texture and the client must ensure the texture is valid for the lifetime of the SkSurface.

sk_sp<SkImage> SkSurface::makeImageSnapshot ( )

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.

static sk_sp<SkSurface> SkSurface::MakeRaster	(	const SkImageInfo &	,
		size_t	rowBytes,
		const SkSurfaceProps *
	)

static

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> SkSurface::MakeRasterDirect	(	const SkImageInfo &	,
		void *	pixels,
		size_t	rowBytes,
		const SkSurfaceProps *	= `nullptr`
	)

static

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> SkSurface::MakeRasterN32Premul	(	int	width,
		int	height,
		const SkSurfaceProps *	props = `nullptr`
	)

inlinestatic

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.

sk_sp<SkSurface> SkSurface::makeSurface ( const SkImageInfo & )

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!

void SkSurface::notifyContentWillChange ( ContentChangeMode mode )

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?

bool SkSurface::peekPixels ( SkPixmap * )

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.

void SkSurface::prepareForExternalIO ( )

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.

bool SkSurface::readPixels	(	const SkImageInfo &	dstInfo,
		void *	dstPixels,
		size_t	dstRowBytes,
		int	srcX,
		int	srcY
	)

Copy the pixels from the surface into the specified buffer (pixels + rowBytes), converting them into the requested format (dstInfo).

The surface pixels are read starting at the specified (srcX,srcY) location.

The specified ImageInfo and (srcX,srcY) offset specifies a source rectangle

srcR.setXYWH(srcX, srcY, dstInfo.width(), dstInfo.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 SkSurface::wait	(	int	numSemaphores,
		const GrBackendSemaphore *	waitSemaphores
	)

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.

Member Data Documentation

const BackendHandleAccess SkSurface::kDiscardWrite_TextureHandleAccess

static

Initial value:

=

kDiscardWrite_BackendHandleAccess

const BackendHandleAccess SkSurface::kFlushRead_TextureHandleAccess

static

Initial value:

=

kFlushRead_BackendHandleAccess

const BackendHandleAccess SkSurface::kFlushWrite_TextureHandleAccess

static

Initial value:

=

kFlushWrite_BackendHandleAccess

The documentation for this class was generated from the following file:

include/core/SkSurface.h

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Private Types

Private Attributes

Detailed Description

Member Enumeration Documentation

Member Function Documentation

Member Data Documentation