reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 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 "SkRefCnt.h" |
| 12 | #include "SkImage.h" |
reed | 4a8126e | 2014-09-22 07:29:03 -0700 | [diff] [blame] | 13 | #include "SkSurfaceProps.h" |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 14 | |
| 15 | class SkCanvas; |
| 16 | class SkPaint; |
reed@google.com | 5d4ba88 | 2012-07-31 15:45:27 +0000 | [diff] [blame] | 17 | class GrContext; |
| 18 | class GrRenderTarget; |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 19 | |
| 20 | /** |
| 21 | * SkSurface represents the backend/results of drawing to a canvas. For raster |
| 22 | * drawing, the surface will be pixels, but (for example) when drawing into |
| 23 | * a PDF or Picture canvas, the surface stores the recorded commands. |
| 24 | * |
| 25 | * To draw into a canvas, first create the appropriate type of Surface, and |
| 26 | * then request the canvas from the surface. |
reed | b2497c2 | 2014-12-31 12:31:43 -0800 | [diff] [blame] | 27 | * |
| 28 | * SkSurface always has non-zero dimensions. If there is a request for a new surface, and either |
| 29 | * of the requested dimensions are zero, then NULL will be returned. |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 30 | */ |
junov@chromium.org | 96447be | 2013-04-18 13:28:19 +0000 | [diff] [blame] | 31 | class SK_API SkSurface : public SkRefCnt { |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 32 | public: |
| 33 | /** |
bsalomon | afe3005 | 2015-01-16 07:32:33 -0800 | [diff] [blame] | 34 | * Indicates whether a new surface or image should count against a cache budget. Currently this |
| 35 | * is only used by the GPU backend (sw-raster surfaces and images are never counted against the |
| 36 | * resource cache budget.) |
| 37 | */ |
| 38 | enum Budgeted { |
| 39 | /** The surface or image does not count against the cache budget. */ |
| 40 | kNo_Budgeted, |
| 41 | /** The surface or image counts against the cache budget. */ |
| 42 | kYes_Budgeted |
| 43 | }; |
| 44 | |
| 45 | /** |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 46 | * Create a new surface, using the specified pixels/rowbytes as its |
| 47 | * backend. |
| 48 | * |
| 49 | * If the requested surface cannot be created, or the request is not a |
| 50 | * supported configuration, NULL will be returned. |
| 51 | */ |
reed | 4a8126e | 2014-09-22 07:29:03 -0700 | [diff] [blame] | 52 | static SkSurface* NewRasterDirect(const SkImageInfo&, void* pixels, size_t rowBytes, |
| 53 | const SkSurfaceProps* = NULL); |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 54 | |
| 55 | /** |
reed | 982542d | 2014-06-27 06:48:14 -0700 | [diff] [blame] | 56 | * The same as NewRasterDirect, but also accepts a call-back routine, which is invoked |
| 57 | * when the surface is deleted, and is passed the pixel memory and the specified context. |
| 58 | */ |
| 59 | static SkSurface* NewRasterDirectReleaseProc(const SkImageInfo&, void* pixels, size_t rowBytes, |
| 60 | void (*releaseProc)(void* pixels, void* context), |
reed | 4a8126e | 2014-09-22 07:29:03 -0700 | [diff] [blame] | 61 | void* context, const SkSurfaceProps* = NULL); |
reed | 982542d | 2014-06-27 06:48:14 -0700 | [diff] [blame] | 62 | |
| 63 | /** |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 64 | * Return a new surface, with the memory for the pixels automatically |
| 65 | * allocated. |
| 66 | * |
| 67 | * If the requested surface cannot be created, or the request is not a |
| 68 | * supported configuration, NULL will be returned. |
| 69 | */ |
reed | 4a8126e | 2014-09-22 07:29:03 -0700 | [diff] [blame] | 70 | static SkSurface* NewRaster(const SkImageInfo&, const SkSurfaceProps* = NULL); |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 71 | |
| 72 | /** |
reed@google.com | 2bd8b81 | 2013-11-01 13:46:54 +0000 | [diff] [blame] | 73 | * Helper version of NewRaster. It creates a SkImageInfo with the |
reed@google.com | 636d87a | 2013-09-17 20:03:43 +0000 | [diff] [blame] | 74 | * specified width and height, and populates the rest of info to match |
| 75 | * pixels in SkPMColor format. |
| 76 | */ |
reed | 3054be1 | 2014-12-10 07:24:28 -0800 | [diff] [blame] | 77 | static SkSurface* NewRasterN32Premul(int width, int height, const SkSurfaceProps* props = NULL) { |
| 78 | return NewRaster(SkImageInfo::MakeN32Premul(width, height), props); |
| 79 | } |
reed@google.com | 636d87a | 2013-09-17 20:03:43 +0000 | [diff] [blame] | 80 | |
| 81 | /** |
reed | 29c857d | 2014-09-21 10:25:07 -0700 | [diff] [blame] | 82 | * Return a new surface using the specified render target. |
reed | 29c857d | 2014-09-21 10:25:07 -0700 | [diff] [blame] | 83 | */ |
reed | 4a8126e | 2014-09-22 07:29:03 -0700 | [diff] [blame] | 84 | static SkSurface* NewRenderTargetDirect(GrRenderTarget*, const SkSurfaceProps*); |
mtklein | 2766c00 | 2015-06-26 11:45:03 -0700 | [diff] [blame] | 85 | |
reed | 4a8126e | 2014-09-22 07:29:03 -0700 | [diff] [blame] | 86 | static SkSurface* NewRenderTargetDirect(GrRenderTarget* target) { |
| 87 | return NewRenderTargetDirect(target, NULL); |
| 88 | } |
bsalomon | e4579ad | 2015-04-08 08:38:40 -0700 | [diff] [blame] | 89 | |
| 90 | /** |
bsalomon | d3e259a | 2015-06-30 12:04:40 -0700 | [diff] [blame^] | 91 | * Used to wrap a pre-existing backend 3D API texture as a SkSurface. The kRenderTarget flag |
| 92 | * must be set on GrBackendTextureDesc for this to succeed. Skia will not assume ownership |
| 93 | * of the texture and the client must ensure the texture is valid for the lifetime of the |
| 94 | * SkSurface. |
bsalomon | e4579ad | 2015-04-08 08:38:40 -0700 | [diff] [blame] | 95 | */ |
bsalomon | d3e259a | 2015-06-30 12:04:40 -0700 | [diff] [blame^] | 96 | static SkSurface* NewFromBackendTexture(GrContext*, const GrBackendTextureDesc&, |
| 97 | const SkSurfaceProps*); |
| 98 | // Legacy alias |
| 99 | static SkSurface* NewWrappedRenderTarget(GrContext* ctx, const GrBackendTextureDesc& desc, |
| 100 | const SkSurfaceProps* props) { |
| 101 | return NewFromBackendTexture(ctx, desc, props); |
| 102 | } |
| 103 | |
| 104 | |
| 105 | /** |
| 106 | * Used to wrap a pre-existing 3D API rendering target as a SkSurface. Skia will not assume |
| 107 | * ownership of the render target and the client must ensure the render target is valid for the |
| 108 | * lifetime of the SkSurface. |
| 109 | */ |
| 110 | static SkSurface* NewFromBackendRenderTarget(GrContext*, const GrBackendRenderTargetDesc&, |
| 111 | const SkSurfaceProps*); |
mtklein | 2766c00 | 2015-06-26 11:45:03 -0700 | [diff] [blame] | 112 | |
reed | 29c857d | 2014-09-21 10:25:07 -0700 | [diff] [blame] | 113 | /** |
| 114 | * Return a new surface whose contents will be drawn to an offscreen |
| 115 | * render target, allocated by the surface. |
| 116 | */ |
bsalomon | afe3005 | 2015-01-16 07:32:33 -0800 | [diff] [blame] | 117 | static SkSurface* NewRenderTarget(GrContext*, Budgeted, const SkImageInfo&, int sampleCount, |
reed | 4a8126e | 2014-09-22 07:29:03 -0700 | [diff] [blame] | 118 | const SkSurfaceProps* = NULL); |
| 119 | |
bsalomon | afe3005 | 2015-01-16 07:32:33 -0800 | [diff] [blame] | 120 | static SkSurface* NewRenderTarget(GrContext* gr, Budgeted b, const SkImageInfo& info) { |
| 121 | return NewRenderTarget(gr, b, info, 0, NULL); |
reed | 4a8126e | 2014-09-22 07:29:03 -0700 | [diff] [blame] | 122 | } |
reed | 29c857d | 2014-09-21 10:25:07 -0700 | [diff] [blame] | 123 | |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 124 | int width() const { return fWidth; } |
| 125 | int height() const { return fHeight; } |
| 126 | |
| 127 | /** |
| 128 | * Returns a unique non-zero, unique value identifying the content of this |
| 129 | * surface. Each time the content is changed changed, either by drawing |
| 130 | * into this surface, or explicitly calling notifyContentChanged()) this |
| 131 | * method will return a new value. |
| 132 | * |
| 133 | * If this surface is empty (i.e. has a zero-dimention), this will return |
| 134 | * 0. |
| 135 | */ |
reed@google.com | 97af1a6 | 2012-08-28 12:19:02 +0000 | [diff] [blame] | 136 | uint32_t generationID(); |
rmistry@google.com | fbfcd56 | 2012-08-23 18:09:54 +0000 | [diff] [blame] | 137 | |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 138 | /** |
commit-bot@chromium.org | c4c9870 | 2013-04-22 14:28:01 +0000 | [diff] [blame] | 139 | * Modes that can be passed to notifyContentWillChange |
| 140 | */ |
| 141 | enum ContentChangeMode { |
skia.committer@gmail.com | e36a168 | 2013-04-23 07:01:29 +0000 | [diff] [blame] | 142 | /** |
commit-bot@chromium.org | c4c9870 | 2013-04-22 14:28:01 +0000 | [diff] [blame] | 143 | * Use this mode if it is known that the upcoming content changes will |
| 144 | * clear or overwrite prior contents, thus making them discardable. |
| 145 | */ |
| 146 | kDiscard_ContentChangeMode, |
skia.committer@gmail.com | e36a168 | 2013-04-23 07:01:29 +0000 | [diff] [blame] | 147 | /** |
commit-bot@chromium.org | c4c9870 | 2013-04-22 14:28:01 +0000 | [diff] [blame] | 148 | * Use this mode if prior surface contents need to be preserved or |
| 149 | * if in doubt. |
| 150 | */ |
| 151 | kRetain_ContentChangeMode, |
| 152 | }; |
| 153 | |
| 154 | /** |
| 155 | * Call this if the contents are about to change. This will (lazily) force a new |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 156 | * value to be returned from generationID() when it is called next. |
reed | fa5e68e | 2015-06-29 07:37:01 -0700 | [diff] [blame] | 157 | * |
| 158 | * CAN WE DEPRECATE THIS? |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 159 | */ |
commit-bot@chromium.org | c4c9870 | 2013-04-22 14:28:01 +0000 | [diff] [blame] | 160 | void notifyContentWillChange(ContentChangeMode mode); |
rmistry@google.com | fbfcd56 | 2012-08-23 18:09:54 +0000 | [diff] [blame] | 161 | |
reed | fa5e68e | 2015-06-29 07:37:01 -0700 | [diff] [blame] | 162 | enum TextureHandleAccess { |
| 163 | kFlushRead_TextureHandleAccess, //!< caller may read from the texture |
| 164 | kFlushWrite_TextureHandleAccess, //!< caller may write to the texture |
| 165 | kDiscardWrite_TextureHandleAccess, //!< caller must over-write the entire texture |
| 166 | }; |
| 167 | /** |
| 168 | * Retrieves the backend API handle of the texture used by this surface, or 0 if the surface |
| 169 | * is not backed by a GPU texture. |
| 170 | * |
| 171 | * The returned texture-handle is only valid until the next draw-call into the surface, |
| 172 | * or the surface is deleted. |
| 173 | */ |
| 174 | GrBackendObject getTextureHandle(TextureHandleAccess); |
| 175 | |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 176 | /** |
reed@google.com | 9ea5a3b | 2012-07-30 21:03:46 +0000 | [diff] [blame] | 177 | * Return a canvas that will draw into this surface. This will always |
| 178 | * return the same canvas for a given surface, and is manged/owned by the |
| 179 | * surface. It should not be used when its parent surface has gone out of |
| 180 | * scope. |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 181 | */ |
reed@google.com | 9ea5a3b | 2012-07-30 21:03:46 +0000 | [diff] [blame] | 182 | SkCanvas* getCanvas(); |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 183 | |
| 184 | /** |
| 185 | * Return a new surface that is "compatible" with this one, in that it will |
| 186 | * efficiently be able to be drawn into this surface. Typical calling |
| 187 | * pattern: |
| 188 | * |
| 189 | * SkSurface* A = SkSurface::New...(); |
| 190 | * SkCanvas* canvasA = surfaceA->newCanvas(); |
| 191 | * ... |
| 192 | * SkSurface* surfaceB = surfaceA->newSurface(...); |
| 193 | * SkCanvas* canvasB = surfaceB->newCanvas(); |
| 194 | * ... // draw using canvasB |
| 195 | * canvasA->drawSurface(surfaceB); // <--- this will always be optimal! |
| 196 | */ |
reed@google.com | 2bd8b81 | 2013-11-01 13:46:54 +0000 | [diff] [blame] | 197 | SkSurface* newSurface(const SkImageInfo&); |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 198 | |
| 199 | /** |
| 200 | * Returns an image of the current state of the surface pixels up to this |
| 201 | * point. Subsequent changes to the surface (by drawing into its canvas) |
bsalomon | eaaaf0b | 2015-01-23 08:08:04 -0800 | [diff] [blame] | 202 | * will not be reflected in this image. If a copy must be made the Budgeted |
| 203 | * parameter controls whether it counts against the resource budget |
| 204 | * (currently for the gpu backend only). |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 205 | */ |
bsalomon | eaaaf0b | 2015-01-23 08:08:04 -0800 | [diff] [blame] | 206 | SkImage* newImageSnapshot(Budgeted = kYes_Budgeted); |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 207 | |
| 208 | /** |
bsalomon | eaaaf0b | 2015-01-23 08:08:04 -0800 | [diff] [blame] | 209 | * Though the caller could get a snapshot image explicitly, and draw that, |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 210 | * it seems that directly drawing a surface into another canvas might be |
| 211 | * a common pattern, and that we could possibly be more efficient, since |
| 212 | * we'd know that the "snapshot" need only live until we've handed it off |
| 213 | * to the canvas. |
| 214 | */ |
| 215 | void draw(SkCanvas*, SkScalar x, SkScalar y, const SkPaint*); |
| 216 | |
commit-bot@chromium.org | c3bd8af | 2014-02-13 17:14:46 +0000 | [diff] [blame] | 217 | /** |
| 218 | * If the surface has direct access to its pixels (i.e. they are in local |
| 219 | * RAM) return the const-address of those pixels, and if not null, return |
| 220 | * the ImageInfo and rowBytes. The returned address is only valid while |
| 221 | * the surface object is in scope, and no API call is made on the surface |
| 222 | * or its canvas. |
| 223 | * |
| 224 | * On failure, returns NULL and the info and rowBytes parameters are |
| 225 | * ignored. |
| 226 | */ |
| 227 | const void* peekPixels(SkImageInfo* info, size_t* rowBytes); |
| 228 | |
reed | 7543aa2 | 2014-12-09 14:39:44 -0800 | [diff] [blame] | 229 | /** |
| 230 | * Copy the pixels from the surface into the specified buffer (pixels + rowBytes), |
reed | 96472de | 2014-12-10 09:53:42 -0800 | [diff] [blame] | 231 | * converting them into the requested format (dstInfo). The surface pixels are read |
| 232 | * starting at the specified (srcX,srcY) location. |
reed | 7543aa2 | 2014-12-09 14:39:44 -0800 | [diff] [blame] | 233 | * |
| 234 | * The specified ImageInfo and (srcX,srcY) offset specifies a source rectangle |
| 235 | * |
| 236 | * srcR.setXYWH(srcX, srcY, dstInfo.width(), dstInfo.height()); |
| 237 | * |
| 238 | * srcR is intersected with the bounds of the base-layer. If this intersection is not empty, |
| 239 | * then we have two sets of pixels (of equal size). Replace the dst pixels with the |
| 240 | * corresponding src pixels, performing any colortype/alphatype transformations needed |
| 241 | * (in the case where the src and dst have different colortypes or alphatypes). |
| 242 | * |
| 243 | * This call can fail, returning false, for several reasons: |
| 244 | * - If srcR does not intersect the surface bounds. |
reed | 96472de | 2014-12-10 09:53:42 -0800 | [diff] [blame] | 245 | * - If the requested colortype/alphatype cannot be converted from the surface's types. |
reed | 7543aa2 | 2014-12-09 14:39:44 -0800 | [diff] [blame] | 246 | */ |
| 247 | bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes, |
| 248 | int srcX, int srcY); |
| 249 | |
reed | 4a8126e | 2014-09-22 07:29:03 -0700 | [diff] [blame] | 250 | const SkSurfaceProps& props() const { return fProps; } |
| 251 | |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 252 | protected: |
reed | 4a8126e | 2014-09-22 07:29:03 -0700 | [diff] [blame] | 253 | SkSurface(int width, int height, const SkSurfaceProps*); |
| 254 | SkSurface(const SkImageInfo&, const SkSurfaceProps*); |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 255 | |
reed@google.com | 97af1a6 | 2012-08-28 12:19:02 +0000 | [diff] [blame] | 256 | // called by subclass if their contents have changed |
| 257 | void dirtyGenerationID() { |
| 258 | fGenerationID = 0; |
| 259 | } |
| 260 | |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 261 | private: |
reed | 4a8126e | 2014-09-22 07:29:03 -0700 | [diff] [blame] | 262 | const SkSurfaceProps fProps; |
| 263 | const int fWidth; |
| 264 | const int fHeight; |
| 265 | uint32_t fGenerationID; |
skia.committer@gmail.com | a27096b | 2012-08-30 14:38:00 +0000 | [diff] [blame] | 266 | |
reed@google.com | 7edfb49 | 2012-08-28 12:48:35 +0000 | [diff] [blame] | 267 | typedef SkRefCnt INHERITED; |
reed@google.com | 889b09e | 2012-07-27 21:10:42 +0000 | [diff] [blame] | 268 | }; |
| 269 | |
| 270 | #endif |