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

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