src/third_party/skia/include/core/SkDevice.h

   1 /*
   2  * Copyright 2010 The Android Open Source Project
   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 SkDevice_DEFINED
   9 #define SkDevice_DEFINED
  10
  11 #include "SkRefCnt.h"
  12 #include "SkBitmap.h"
  13 #include "SkCanvas.h"
  14 #include "SkColor.h"
  15 #include "SkDeviceProperties.h"
  16 #include "SkImageFilter.h"
  17
  18 class SkClipStack;
  19 class SkDraw;
  20 struct SkIRect;
  21 class SkMatrix;
  22 class SkMetaData;
  23 class SkRegion;
  24
  25 class GrRenderTarget;
  26
  27 class SK_API SkBaseDevice : public SkRefCnt {
  28 public:
  29     SK_DECLARE_INST_COUNT(SkBaseDevice)
  30
  31     /**
  32      *  Construct a new device.
  33     */
  34     SkBaseDevice();
  35
  36     /**
  37      *  Construct a new device.
  38     */
  39     SkBaseDevice(const SkDeviceProperties& deviceProperties);
  40
  41     virtual ~SkBaseDevice();
  42
  43     SkBaseDevice* createCompatibleDevice(const SkImageInfo&);
  44
  45     SkMetaData& getMetaData();
  46
  47     /** Return the image properties of the device. */
  48     virtual const SkDeviceProperties& getDeviceProperties() const {
  49         //Currently, all the properties are leaky.
  50         return fLeakyProperties;
  51     }
  52
  53     /**
  54      *  Return ImageInfo for this device. If the canvas is not backed by pixels
  55      *  (cpu or gpu), then the info's ColorType will be kUnknown_SkColorType.
  56      */
  57     virtual SkImageInfo imageInfo() const;
  58
  59     /**
  60      *  Return the bounds of the device in the coordinate space of the root
  61      *  canvas. The root device will have its top-left at 0,0, but other devices
  62      *  such as those associated with saveLayer may have a non-zero origin.
  63      */
  64     void getGlobalBounds(SkIRect* bounds) const {
  65         SkASSERT(bounds);
  66         const SkIPoint& origin = this->getOrigin();
  67         bounds->setXYWH(origin.x(), origin.y(), this->width(), this->height());
  68     }
  69
  70     int width() const {
  71         return this->imageInfo().width();
  72     }
  73
  74     int height() const {
  75         return this->imageInfo().height();
  76     }
  77
  78     bool isOpaque() const {
  79         return this->imageInfo().isOpaque();
  80     }
  81
  82     /** Return the bitmap associated with this device. Call this each time you need
  83         to access the bitmap, as it notifies the subclass to perform any flushing
  84         etc. before you examine the pixels.
  85         @param changePixels set to true if the caller plans to change the pixels
  86         @return the device's bitmap
  87     */
  88     const SkBitmap& accessBitmap(bool changePixels);
  89
  90     bool writePixels(const SkImageInfo&, const void*, size_t rowBytes, int x, int y);
  91
  92     void* accessPixels(SkImageInfo* info, size_t* rowBytes);
  93
  94     /**
  95      * Return the device's associated gpu render target, or NULL.
  96      */
  97     virtual GrRenderTarget* accessRenderTarget() { return NULL; }
  98
  99
 100     /**
 101      *  Return the device's origin: its offset in device coordinates from
 102      *  the default origin in its canvas' matrix/clip
 103      */
 104     const SkIPoint& getOrigin() const { return fOrigin; }
 105
 106     /**
 107      * onAttachToCanvas is invoked whenever a device is installed in a canvas
 108      * (i.e., setDevice, saveLayer (for the new device created by the save),
 109      * and SkCanvas' SkBaseDevice & SkBitmap -taking ctors). It allows the
 110      * devices to prepare for drawing (e.g., locking their pixels, etc.)
 111      */
 112     virtual void onAttachToCanvas(SkCanvas*) {
 113         SkASSERT(!fAttachedToCanvas);
 114         this->lockPixels();
 115 #ifdef SK_DEBUG
 116         fAttachedToCanvas = true;
 117 #endif
 118     };
 119
 120     /**
 121      * onDetachFromCanvas notifies a device that it will no longer be drawn to.
 122      * It gives the device a chance to clean up (e.g., unlock its pixels). It
 123      * is invoked from setDevice (for the displaced device), restore and
 124      * possibly from SkCanvas' dtor.
 125      */
 126     virtual void onDetachFromCanvas() {
 127         SkASSERT(fAttachedToCanvas);
 128         this->unlockPixels();
 129 #ifdef SK_DEBUG
 130         fAttachedToCanvas = false;
 131 #endif
 132     };
 133
 134 protected:
 135     enum Usage {
 136        kGeneral_Usage,
 137        kSaveLayer_Usage  // <! internal use only
 138     };
 139
 140     struct TextFlags {
 141         uint32_t            fFlags;     // SkPaint::getFlags()
 142         SkPaint::Hinting    fHinting;
 143     };
 144
 145     /**
 146      *  Device may filter the text flags for drawing text here. If it wants to
 147      *  make a change to the specified values, it should write them into the
 148      *  textflags parameter (output) and return true. If the paint is fine as
 149      *  is, then ignore the textflags parameter and return false.
 150      */
 151     virtual bool filterTextFlags(const SkPaint& paint, TextFlags*) { return false; }
 152
 153     /**
 154      *
 155      *  DEPRECATED: This will be removed in a future change. Device subclasses
 156      *  should use the matrix and clip from the SkDraw passed to draw functions.
 157      *
 158      *  Called with the correct matrix and clip before this device is drawn
 159      *  to using those settings. If your subclass overrides this, be sure to
 160      *  call through to the base class as well.
 161      *
 162      *  The clipstack is another view of the clip. It records the actual
 163      *  geometry that went into building the region. It is present for devices
 164      *  that want to parse it, but is not required: the region is a complete
 165      *  picture of the current clip. (i.e. if you regionize all of the geometry
 166      *  in the clipstack, you will arrive at an equivalent region to the one
 167      *  passed in).
 168      */
 169      virtual void setMatrixClip(const SkMatrix&, const SkRegion&,
 170                                 const SkClipStack&) {};
 171
 172     /** Clears the entire device to the specified color (including alpha).
 173      *  Ignores the clip.
 174      */
 175     virtual void clear(SkColor color) = 0;
 176
 177     SK_ATTR_DEPRECATED("use clear() instead")
 178     void eraseColor(SkColor eraseColor) { this->clear(eraseColor); }
 179
 180     /** These are called inside the per-device-layer loop for each draw call.
 181      When these are called, we have already applied any saveLayer operations,
 182      and are handling any looping from the paint, and any effects from the
 183      DrawFilter.
 184      */
 185     virtual void drawPaint(const SkDraw&, const SkPaint& paint) = 0;
 186     virtual void drawPoints(const SkDraw&, SkCanvas::PointMode mode, size_t count,
 187                             const SkPoint[], const SkPaint& paint) = 0;
 188     virtual void drawRect(const SkDraw&, const SkRect& r,
 189                           const SkPaint& paint) = 0;
 190     virtual void drawOval(const SkDraw&, const SkRect& oval,
 191                           const SkPaint& paint) = 0;
 192     virtual void drawRRect(const SkDraw&, const SkRRect& rr,
 193                            const SkPaint& paint) = 0;
 194
 195     // Default impl calls drawPath()
 196     virtual void drawDRRect(const SkDraw&, const SkRRect& outer,
 197                             const SkRRect& inner, const SkPaint&);
 198
 199     /**
 200      *  If pathIsMutable, then the implementation is allowed to cast path to a
 201      *  non-const pointer and modify it in place (as an optimization). Canvas
 202      *  may do this to implement helpers such as drawOval, by placing a temp
 203      *  path on the stack to hold the representation of the oval.
 204      *
 205      *  If prePathMatrix is not null, it should logically be applied before any
 206      *  stroking or other effects. If there are no effects on the paint that
 207      *  affect the geometry/rasterization, then the pre matrix can just be
 208      *  pre-concated with the current matrix.
 209      */
 210     virtual void drawPath(const SkDraw&, const SkPath& path,
 211                           const SkPaint& paint,
 212                           const SkMatrix* prePathMatrix = NULL,
 213                           bool pathIsMutable = false) = 0;
 214     virtual void drawBitmap(const SkDraw&, const SkBitmap& bitmap,
 215                             const SkMatrix& matrix, const SkPaint& paint) = 0;
 216     virtual void drawSprite(const SkDraw&, const SkBitmap& bitmap,
 217                             int x, int y, const SkPaint& paint) = 0;
 218
 219     /**
 220      *  The default impl. will create a bitmap-shader from the bitmap,
 221      *  and call drawRect with it.
 222      */
 223     virtual void drawBitmapRect(const SkDraw&, const SkBitmap&,
 224                                 const SkRect* srcOrNull, const SkRect& dst,
 225                                 const SkPaint& paint,
 226                                 SkCanvas::DrawBitmapRectFlags flags) = 0;
 227
 228     /**
 229      *  Does not handle text decoration.
 230      *  Decorations (underline and stike-thru) will be handled by SkCanvas.
 231      */
 232     virtual void drawText(const SkDraw&, const void* text, size_t len,
 233                           SkScalar x, SkScalar y, const SkPaint& paint) = 0;
 234     virtual void drawPosText(const SkDraw&, const void* text, size_t len,
 235                              const SkScalar pos[], SkScalar constY,
 236                              int scalarsPerPos, const SkPaint& paint) = 0;
 237     virtual void drawTextOnPath(const SkDraw&, const void* text, size_t len,
 238                                 const SkPath& path, const SkMatrix* matrix,
 239                                 const SkPaint& paint) = 0;
 240     virtual void drawVertices(const SkDraw&, SkCanvas::VertexMode, int vertexCount,
 241                               const SkPoint verts[], const SkPoint texs[],
 242                               const SkColor colors[], SkXfermode* xmode,
 243                               const uint16_t indices[], int indexCount,
 244                               const SkPaint& paint) = 0;
 245     // default implementation calls drawVertices
 246     virtual void drawPatch(const SkDraw&, const SkPoint cubics[12], const SkColor colors[4],
 247                            const SkPoint texCoords[4], SkXfermode* xmode, const SkPaint& paint);
 248     /** The SkDevice passed will be an SkDevice which was returned by a call to
 249         onCreateDevice on this device with kSaveLayer_Usage.
 250      */
 251     virtual void drawDevice(const SkDraw&, SkBaseDevice*, int x, int y,
 252                             const SkPaint&) = 0;
 253
 254     bool readPixels(const SkImageInfo&, void* dst, size_t rowBytes, int x, int y);
 255
 256     ///////////////////////////////////////////////////////////////////////////
 257
 258     /** Update as needed the pixel value in the bitmap, so that the caller can
 259         access the pixels directly.
 260         @return The device contents as a bitmap
 261     */
 262     virtual const SkBitmap& onAccessBitmap() = 0;
 263
 264     /** Called when this device is installed into a Canvas. Balanced by a call
 265         to unlockPixels() when the device is removed from a Canvas.
 266     */
 267     virtual void lockPixels() {}
 268     virtual void unlockPixels() {}
 269
 270     /**
 271      *  Returns true if the device allows processing of this imagefilter. If
 272      *  false is returned, then the filter is ignored. This may happen for
 273      *  some subclasses that do not support pixel manipulations after drawing
 274      *  has occurred (e.g. printing). The default implementation returns true.
 275      */
 276     virtual bool allowImageFilter(const SkImageFilter*) { return true; }
 277
 278     /**
 279      *  Override and return true for filters that the device can handle
 280      *  intrinsically. Doing so means that SkCanvas will pass-through this
 281      *  filter to drawSprite and drawDevice (and potentially filterImage).
 282      *  Returning false means the SkCanvas will have apply the filter itself,
 283      *  and just pass the resulting image to the device.
 284      */
 285     virtual bool canHandleImageFilter(const SkImageFilter*) { return false; }
 286
 287     /**
 288      *  Related (but not required) to canHandleImageFilter, this method returns
 289      *  true if the device could apply the filter to the src bitmap and return
 290      *  the result (and updates offset as needed).
 291      *  If the device does not recognize or support this filter,
 292      *  it just returns false and leaves result and offset unchanged.
 293      */
 294     virtual bool filterImage(const SkImageFilter*, const SkBitmap&,
 295                              const SkImageFilter::Context& ctx,
 296                              SkBitmap* result, SkIPoint* offset) {
 297         return false;
 298     }
 299
 300 protected:
 301     // default impl returns NULL
 302     virtual SkSurface* newSurface(const SkImageInfo&);
 303
 304     // default impl returns NULL
 305     virtual const void* peekPixels(SkImageInfo*, size_t* rowBytes);
 306
 307     /**
 308      *  The caller is responsible for "pre-clipping" the dst. The impl can assume that the dst
 309      *  image at the specified x,y offset will fit within the device's bounds.
 310      *
 311      *  This is explicitly asserted in readPixels(), the public way to call this.
 312      */
 313     virtual bool onReadPixels(const SkImageInfo&, void*, size_t, int x, int y);
 314
 315     /**
 316      *  The caller is responsible for "pre-clipping" the src. The impl can assume that the src
 317      *  image at the specified x,y offset will fit within the device's bounds.
 318      *
 319      *  This is explicitly asserted in writePixelsDirect(), the public way to call this.
 320      */
 321     virtual bool onWritePixels(const SkImageInfo&, const void*, size_t, int x, int y);
 322
 323     /**
 324      *  Default impl returns NULL.
 325      */
 326     virtual void* onAccessPixels(SkImageInfo* info, size_t* rowBytes);
 327
 328     /**
 329      *  Leaky properties are those which the device should be applying but it isn't.
 330      *  These properties will be applied by the draw, when and as it can.
 331      *  If the device does handle a property, that property should be set to the identity value
 332      *  for that property, effectively making it non-leaky.
 333      */
 334     SkDeviceProperties fLeakyProperties;
 335
 336     /**
 337      *  PRIVATE / EXPERIMENTAL -- do not call
 338      *  Construct an acceleration object and attach it to 'picture'
 339      */
 340     virtual void EXPERIMENTAL_optimize(const SkPicture* picture);
 341
 342     /**
 343      *  PRIVATE / EXPERIMENTAL -- do not call
 344      *  This entry point gives the backend an opportunity to take over the rendering
 345      *  of 'picture'. If optimization data is available (due to an earlier
 346      *  'optimize' call) this entry point should make use of it and return true
 347      *  if all rendering has been done. If false is returned, SkCanvas will
 348      *  perform its own rendering pass. It is acceptable for the backend
 349      *  to perform some device-specific warm up tasks and then let SkCanvas
 350      *  perform the main rendering loop (by return false from here).
 351      */
 352     virtual bool EXPERIMENTAL_drawPicture(SkCanvas*, const SkPicture*, const SkMatrix*,
 353                                           const SkPaint*);
 354
 355 private:
 356     friend class SkCanvas;
 357     friend struct DeviceCM; //for setMatrixClip
 358     friend class SkDraw;
 359     friend class SkDrawIter;
 360     friend class SkDeviceFilteredPaint;
 361     friend class SkDeviceImageFilterProxy;
 362     friend class SkDeferredDevice;    // for newSurface
 363
 364     friend class SkSurface_Raster;
 365
 366     // used to change the backend's pixels (and possibly config/rowbytes)
 367     // but cannot change the width/height, so there should be no change to
 368     // any clip information.
 369     // TODO: move to SkBitmapDevice
 370     virtual void replaceBitmapBackendForRasterSurface(const SkBitmap&) {}
 371
 372     // just called by SkCanvas when built as a layer
 373     void setOrigin(int x, int y) { fOrigin.set(x, y); }
 374     // just called by SkCanvas for saveLayer
 375     SkBaseDevice* createCompatibleDeviceForSaveLayer(const SkImageInfo&);
 376
 377     virtual SkBaseDevice* onCreateDevice(const SkImageInfo&, Usage) {
 378         return NULL;
 379     }
 380
 381     /** Causes any deferred drawing to the device to be completed.
 382      */
 383     virtual void flush() {}
 384
 385     virtual SkImageFilter::Cache* getImageFilterCache() { return NULL; }
 386
 387     SkIPoint    fOrigin;
 388     SkMetaData* fMetaData;
 389
 390 #ifdef SK_DEBUG
 391     bool        fAttachedToCanvas;
 392 #endif
 393
 394     typedef SkRefCnt INHERITED;
 395 };
 396
 397 #endif