1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/gfx/skia/trunk/include/core/SkSurface.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,180 @@
1.4 +/*
1.5 + * Copyright 2012 Google Inc.
1.6 + *
1.7 + * Use of this source code is governed by a BSD-style license that can be
1.8 + * found in the LICENSE file.
1.9 + */
1.10 +
1.11 +#ifndef SkSurface_DEFINED
1.12 +#define SkSurface_DEFINED
1.13 +
1.14 +#include "SkRefCnt.h"
1.15 +#include "SkImage.h"
1.16 +
1.17 +class SkCanvas;
1.18 +class SkPaint;
1.19 +class GrContext;
1.20 +class GrRenderTarget;
1.21 +
1.22 +/**
1.23 + * SkSurface represents the backend/results of drawing to a canvas. For raster
1.24 + * drawing, the surface will be pixels, but (for example) when drawing into
1.25 + * a PDF or Picture canvas, the surface stores the recorded commands.
1.26 + *
1.27 + * To draw into a canvas, first create the appropriate type of Surface, and
1.28 + * then request the canvas from the surface.
1.29 + */
1.30 +class SK_API SkSurface : public SkRefCnt {
1.31 +public:
1.32 + SK_DECLARE_INST_COUNT(SkSurface)
1.33 +
1.34 + /**
1.35 + * Create a new surface, using the specified pixels/rowbytes as its
1.36 + * backend.
1.37 + *
1.38 + * If the requested surface cannot be created, or the request is not a
1.39 + * supported configuration, NULL will be returned.
1.40 + */
1.41 + static SkSurface* NewRasterDirect(const SkImageInfo&, void* pixels, size_t rowBytes);
1.42 +
1.43 + /**
1.44 + * Return a new surface, with the memory for the pixels automatically
1.45 + * allocated.
1.46 + *
1.47 + * If the requested surface cannot be created, or the request is not a
1.48 + * supported configuration, NULL will be returned.
1.49 + */
1.50 + static SkSurface* NewRaster(const SkImageInfo&);
1.51 +
1.52 + /**
1.53 + * Helper version of NewRaster. It creates a SkImageInfo with the
1.54 + * specified width and height, and populates the rest of info to match
1.55 + * pixels in SkPMColor format.
1.56 + */
1.57 + static SkSurface* NewRasterPMColor(int width, int height) {
1.58 + return NewRaster(SkImageInfo::MakeN32Premul(width, height));
1.59 + }
1.60 +
1.61 + /**
1.62 + * Return a new surface whose contents will be recorded into a picture.
1.63 + * When this surface is drawn into another canvas, its contents will be
1.64 + * "replayed" into that canvas.
1.65 + */
1.66 + static SkSurface* NewPicture(int width, int height);
1.67 +
1.68 + /**
1.69 + * Return a new surface using the specified render target.
1.70 + */
1.71 + static SkSurface* NewRenderTargetDirect(GrRenderTarget*);
1.72 +
1.73 + /**
1.74 + * Return a new surface whose contents will be drawn to an offscreen
1.75 + * render target, allocated by the surface.
1.76 + */
1.77 + static SkSurface* NewRenderTarget(GrContext*, const SkImageInfo&, int sampleCount = 0);
1.78 +
1.79 + int width() const { return fWidth; }
1.80 + int height() const { return fHeight; }
1.81 +
1.82 + /**
1.83 + * Returns a unique non-zero, unique value identifying the content of this
1.84 + * surface. Each time the content is changed changed, either by drawing
1.85 + * into this surface, or explicitly calling notifyContentChanged()) this
1.86 + * method will return a new value.
1.87 + *
1.88 + * If this surface is empty (i.e. has a zero-dimention), this will return
1.89 + * 0.
1.90 + */
1.91 + uint32_t generationID();
1.92 +
1.93 + /**
1.94 + * Modes that can be passed to notifyContentWillChange
1.95 + */
1.96 + enum ContentChangeMode {
1.97 + /**
1.98 + * Use this mode if it is known that the upcoming content changes will
1.99 + * clear or overwrite prior contents, thus making them discardable.
1.100 + */
1.101 + kDiscard_ContentChangeMode,
1.102 + /**
1.103 + * Use this mode if prior surface contents need to be preserved or
1.104 + * if in doubt.
1.105 + */
1.106 + kRetain_ContentChangeMode,
1.107 + };
1.108 +
1.109 + /**
1.110 + * Call this if the contents are about to change. This will (lazily) force a new
1.111 + * value to be returned from generationID() when it is called next.
1.112 + */
1.113 + void notifyContentWillChange(ContentChangeMode mode);
1.114 +
1.115 + /**
1.116 + * Return a canvas that will draw into this surface. This will always
1.117 + * return the same canvas for a given surface, and is manged/owned by the
1.118 + * surface. It should not be used when its parent surface has gone out of
1.119 + * scope.
1.120 + */
1.121 + SkCanvas* getCanvas();
1.122 +
1.123 + /**
1.124 + * Return a new surface that is "compatible" with this one, in that it will
1.125 + * efficiently be able to be drawn into this surface. Typical calling
1.126 + * pattern:
1.127 + *
1.128 + * SkSurface* A = SkSurface::New...();
1.129 + * SkCanvas* canvasA = surfaceA->newCanvas();
1.130 + * ...
1.131 + * SkSurface* surfaceB = surfaceA->newSurface(...);
1.132 + * SkCanvas* canvasB = surfaceB->newCanvas();
1.133 + * ... // draw using canvasB
1.134 + * canvasA->drawSurface(surfaceB); // <--- this will always be optimal!
1.135 + */
1.136 + SkSurface* newSurface(const SkImageInfo&);
1.137 +
1.138 + /**
1.139 + * Returns an image of the current state of the surface pixels up to this
1.140 + * point. Subsequent changes to the surface (by drawing into its canvas)
1.141 + * will not be reflected in this image.
1.142 + */
1.143 + SkImage* newImageSnapshot();
1.144 +
1.145 + /**
1.146 + * Thought the caller could get a snapshot image explicitly, and draw that,
1.147 + * it seems that directly drawing a surface into another canvas might be
1.148 + * a common pattern, and that we could possibly be more efficient, since
1.149 + * we'd know that the "snapshot" need only live until we've handed it off
1.150 + * to the canvas.
1.151 + */
1.152 + void draw(SkCanvas*, SkScalar x, SkScalar y, const SkPaint*);
1.153 +
1.154 + /**
1.155 + * If the surface has direct access to its pixels (i.e. they are in local
1.156 + * RAM) return the const-address of those pixels, and if not null, return
1.157 + * the ImageInfo and rowBytes. The returned address is only valid while
1.158 + * the surface object is in scope, and no API call is made on the surface
1.159 + * or its canvas.
1.160 + *
1.161 + * On failure, returns NULL and the info and rowBytes parameters are
1.162 + * ignored.
1.163 + */
1.164 + const void* peekPixels(SkImageInfo* info, size_t* rowBytes);
1.165 +
1.166 +protected:
1.167 + SkSurface(int width, int height);
1.168 + SkSurface(const SkImageInfo&);
1.169 +
1.170 + // called by subclass if their contents have changed
1.171 + void dirtyGenerationID() {
1.172 + fGenerationID = 0;
1.173 + }
1.174 +
1.175 +private:
1.176 + const int fWidth;
1.177 + const int fHeight;
1.178 + uint32_t fGenerationID;
1.179 +
1.180 + typedef SkRefCnt INHERITED;
1.181 +};
1.182 +
1.183 +#endif
