src/third_party/skia/include/gpu/GrContext.h

   1 /*
   2  * Copyright 2010 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 GrContext_DEFINED
   9 #define GrContext_DEFINED
  10
  11 #include "GrClipData.h"
  12 #include "GrColor.h"
  13 #include "GrPaint.h"
  14 #include "GrPathRendererChain.h"
  15 #include "GrPoint.h"
  16 #include "GrRenderTarget.h"
  17 #include "GrTexture.h"
  18 #include "SkMatrix.h"
  19 #include "SkTypes.h"
  20
  21 class GrAARectRenderer;
  22 class GrAutoScratchTexture;
  23 class GrCacheable;
  24 class GrDrawState;
  25 class GrDrawTarget;
  26 class GrEffect;
  27 class GrFontCache;
  28 class GrGpu;
  29 class GrIndexBuffer;
  30 class GrIndexBufferAllocPool;
  31 class GrInOrderDrawBuffer;
  32 class GrLayerCache;
  33 class GrOvalRenderer;
  34 class GrPath;
  35 class GrPathRenderer;
  36 class GrResourceEntry;
  37 class GrResourceCache;
  38 class GrStencilBuffer;
  39 class GrTestTarget;
  40 class GrTextureParams;
  41 class GrVertexBuffer;
  42 class GrVertexBufferAllocPool;
  43 class GrSoftwarePathRenderer;
  44 class SkStrokeRec;
  45
  46 class SK_API GrContext : public SkRefCnt {
  47 public:
  48     SK_DECLARE_INST_COUNT(GrContext)
  49
  50     /**
  51      * Creates a GrContext for a backend context.
  52      */
  53     static GrContext* Create(GrBackend, GrBackendContext);
  54
  55     virtual ~GrContext();
  56
  57     /**
  58      * The GrContext normally assumes that no outsider is setting state
  59      * within the underlying 3D API's context/device/whatever. This call informs
  60      * the context that the state was modified and it should resend. Shouldn't
  61      * be called frequently for good performance.
  62      * The flag bits, state, is dpendent on which backend is used by the
  63      * context, either GL or D3D (possible in future).
  64      */
  65     void resetContext(uint32_t state = kAll_GrBackendState);
  66
  67     /**
  68      * Callback function to allow classes to cleanup on GrContext destruction.
  69      * The 'info' field is filled in with the 'info' passed to addCleanUp.
  70      */
  71     typedef void (*PFCleanUpFunc)(const GrContext* context, void* info);
  72
  73     /**
  74      * Add a function to be called from within GrContext's destructor.
  75      * This gives classes a chance to free resources held on a per context basis.
  76      * The 'info' parameter will be stored and passed to the callback function.
  77      */
  78     void addCleanUp(PFCleanUpFunc cleanUp, void* info) {
  79         CleanUpData* entry = fCleanUpData.push();
  80
  81         entry->fFunc = cleanUp;
  82         entry->fInfo = info;
  83     }
  84
  85     /**
  86      * Abandons all GPU resources, assumes 3D API state is unknown. Call this
  87      * if you have lost the associated GPU context, and thus internal texture,
  88      * buffer, etc. references/IDs are now invalid. Should be called even when
  89      * GrContext is no longer going to be used for two reasons:
  90      *  1) ~GrContext will not try to free the objects in the 3D API.
  91      *  2) If you've created GrGpuObjects that outlive the GrContext they will
  92      *     be marked as invalid (GrGpuObjects::isValid()) and won't attempt to
  93      *     free their underlying resource in the 3D API.
  94      * Content drawn since the last GrContext::flush() may be lost.
  95      */
  96     void contextLost();
  97
  98     /**
  99      * Similar to contextLost, but makes no attempt to reset state.
 100      * Use this method when GrContext destruction is pending, but
 101      * the graphics context is destroyed first.
 102      */
 103     void contextDestroyed();
 104
 105     /**
 106      * Frees GPU created by the context. Can be called to reduce GPU memory
 107      * pressure.
 108      */
 109     void freeGpuResources();
 110
 111     /**
 112      * Returns the number of bytes of GPU memory hosted by the texture cache.
 113      */
 114     size_t getGpuTextureCacheBytes() const;
 115
 116     /**
 117      * Returns the number of resources hosted by the texture cache.
 118      */
 119     int getGpuTextureCacheResourceCount() const;
 120
 121     ///////////////////////////////////////////////////////////////////////////
 122     // Textures
 123
 124     /**
 125      * Creates a new entry, based on the specified key and texture and returns it. The caller owns a
 126      * ref on the returned texture which must be balanced by a call to unref.
 127      *
 128      * @param params    The texture params used to draw a texture may help determine
 129      *                  the cache entry used. (e.g. different versions may exist
 130      *                  for different wrap modes on GPUs with limited NPOT
 131      *                  texture support). NULL implies clamp wrap modes.
 132      * @param desc      Description of the texture properties.
 133      * @param cacheID Cache-specific properties (e.g., texture gen ID)
 134      * @param srcData   Pointer to the pixel values.
 135      * @param rowBytes  The number of bytes between rows of the texture. Zero
 136      *                  implies tightly packed rows.
 137      * @param cacheKey  (optional) If non-NULL, we'll write the cache key we used to cacheKey.
 138      */
 139     GrTexture* createTexture(const GrTextureParams* params,
 140                              const GrTextureDesc& desc,
 141                              const GrCacheID& cacheID,
 142                              void* srcData,
 143                              size_t rowBytes,
 144                              GrResourceKey* cacheKey = NULL);
 145
 146     /**
 147      * Search for an entry based on key and dimensions. If found, ref it and return it. The return
 148      * value will be NULL if not found. The caller must balance with a call to unref.
 149      *
 150      *  @param desc     Description of the texture properties.
 151      *  @param cacheID Cache-specific properties (e.g., texture gen ID)
 152      *  @param params   The texture params used to draw a texture may help determine
 153      *                  the cache entry used. (e.g. different versions may exist
 154      *                  for different wrap modes on GPUs with limited NPOT
 155      *                  texture support). NULL implies clamp wrap modes.
 156      */
 157     GrTexture* findAndRefTexture(const GrTextureDesc& desc,
 158                                  const GrCacheID& cacheID,
 159                                  const GrTextureParams* params);
 160     /**
 161      * Determines whether a texture is in the cache. If the texture is found it
 162      * will not be locked or returned. This call does not affect the priority of
 163      * the texture for deletion.
 164      */
 165     bool isTextureInCache(const GrTextureDesc& desc,
 166                           const GrCacheID& cacheID,
 167                           const GrTextureParams* params) const;
 168
 169     /**
 170      * Enum that determines how closely a returned scratch texture must match
 171      * a provided GrTextureDesc.
 172      */
 173     enum ScratchTexMatch {
 174         /**
 175          * Finds a texture that exactly matches the descriptor.
 176          */
 177         kExact_ScratchTexMatch,
 178         /**
 179          * Finds a texture that approximately matches the descriptor. Will be
 180          * at least as large in width and height as desc specifies. If desc
 181          * specifies that texture is a render target then result will be a
 182          * render target. If desc specifies a render target and doesn't set the
 183          * no stencil flag then result will have a stencil. Format and aa level
 184          * will always match.
 185          */
 186         kApprox_ScratchTexMatch
 187     };
 188
 189     /**
 190      * Returns a texture matching the desc. It's contents are unknown. Subsequent
 191      * requests with the same descriptor are not guaranteed to return the same
 192      * texture. The same texture is guaranteed not be returned again until it is
 193      * unlocked. Call must be balanced with an unlockTexture() call. The caller
 194      * owns a ref on the returned texture and must balance with a call to unref.
 195      *
 196      * Textures created by createAndLockTexture() hide the complications of
 197      * tiling non-power-of-two textures on APIs that don't support this (e.g.
 198      * unextended GLES2). Tiling a NPOT texture created by lockScratchTexture on
 199      * such an API will create gaps in the tiling pattern. This includes clamp
 200      * mode. (This may be addressed in a future update.)
 201      */
 202     GrTexture* lockAndRefScratchTexture(const GrTextureDesc&, ScratchTexMatch match);
 203
 204     /**
 205      *  When done with an entry, call unlockScratchTexture(entry) on it, which returns
 206      *  it to the cache, where it may be purged. This does not unref the texture.
 207      */
 208     void unlockScratchTexture(GrTexture* texture);
 209
 210     /**
 211      * This method should be called whenever a GrTexture is unreffed or
 212      * switched from exclusive to non-exclusive. This
 213      * gives the resource cache a chance to discard unneeded textures.
 214      * Note: this entry point will be removed once totally ref-driven
 215      * cache maintenance is implemented
 216      */
 217     void purgeCache();
 218
 219     /**
 220      * Purge all the unlocked resources from the cache.
 221      * This entry point is mainly meant for timing texture uploads
 222      * and is not defined in normal builds of Skia.
 223      */
 224     void purgeAllUnlockedResources();
 225
 226     /**
 227      * Creates a texture that is outside the cache. Does not count against
 228      * cache's budget.
 229      */
 230     GrTexture* createUncachedTexture(const GrTextureDesc& desc,
 231                                      void* srcData,
 232                                      size_t rowBytes);
 233
 234     /**
 235      * Returns true if the specified use of an indexed texture is supported.
 236      * Support may depend upon whether the texture params indicate that the
 237      * texture will be tiled. Passing NULL for the texture params indicates
 238      * clamp mode.
 239      */
 240     bool supportsIndex8PixelConfig(const GrTextureParams*,
 241                                    int width,
 242                                    int height) const;
 243
 244     /**
 245      *  Return the current texture cache limits.
 246      *
 247      *  @param maxTextures If non-null, returns maximum number of textures that
 248      *                     can be held in the cache.
 249      *  @param maxTextureBytes If non-null, returns maximum number of bytes of
 250      *                         texture memory that can be held in the cache.
 251      */
 252     void getTextureCacheLimits(int* maxTextures, size_t* maxTextureBytes) const;
 253
 254     /**
 255      *  Specify the texture cache limits. If the current cache exceeds either
 256      *  of these, it will be purged (LRU) to keep the cache within these limits.
 257      *
 258      *  @param maxTextures The maximum number of textures that can be held in
 259      *                     the cache.
 260      *  @param maxTextureBytes The maximum number of bytes of texture memory
 261      *                         that can be held in the cache.
 262      */
 263     void setTextureCacheLimits(int maxTextures, size_t maxTextureBytes);
 264
 265     /**
 266      *  Return the max width or height of a texture supported by the current GPU.
 267      */
 268     int getMaxTextureSize() const;
 269
 270     /**
 271      *  Temporarily override the true max texture size. Note: an override
 272      *  larger then the true max texture size will have no effect.
 273      *  This entry point is mainly meant for testing texture size dependent
 274      *  features and is only available if defined outside of Skia (see
 275      *  bleed GM.
 276      */
 277     void setMaxTextureSizeOverride(int maxTextureSizeOverride);
 278
 279     ///////////////////////////////////////////////////////////////////////////
 280     // Render targets
 281
 282     /**
 283      * Sets the render target.
 284      * @param target    the render target to set.
 285      */
 286     void setRenderTarget(GrRenderTarget* target) {
 287         fRenderTarget.reset(SkSafeRef(target));
 288     }
 289
 290     /**
 291      * Gets the current render target.
 292      * @return the currently bound render target.
 293      */
 294     const GrRenderTarget* getRenderTarget() const { return fRenderTarget.get(); }
 295     GrRenderTarget* getRenderTarget() { return fRenderTarget.get(); }
 296
 297     GrAARectRenderer* getAARectRenderer() { return fAARectRenderer; }
 298
 299     /**
 300      * Can the provided configuration act as a color render target?
 301      */
 302     bool isConfigRenderable(GrPixelConfig config, bool withMSAA) const;
 303
 304     /**
 305      * Return the max width or height of a render target supported by the
 306      * current GPU.
 307      */
 308     int getMaxRenderTargetSize() const;
 309
 310     /**
 311      * Returns the max sample count for a render target. It will be 0 if MSAA
 312      * is not supported.
 313      */
 314     int getMaxSampleCount() const;
 315
 316     /**
 317      * Returns the recommended sample count for a render target when using this
 318      * context.
 319      *
 320      * @param  config the configuration of the render target.
 321      * @param  dpi the display density in dots per inch.
 322      *
 323      * @return sample count that should be perform well and have good enough
 324      *         rendering quality for the display. Alternatively returns 0 if
 325      *         MSAA is not supported or recommended to be used by default.
 326      */
 327     int getRecommendedSampleCount(GrPixelConfig config, SkScalar dpi) const;
 328
 329     ///////////////////////////////////////////////////////////////////////////
 330     // Backend Surfaces
 331
 332     /**
 333      * Wraps an existing texture with a GrTexture object.
 334      *
 335      * OpenGL: if the object is a texture Gr may change its GL texture params
 336      *         when it is drawn.
 337      *
 338      * @param  desc     description of the object to create.
 339      *
 340      * @return GrTexture object or NULL on failure.
 341      */
 342     GrTexture* wrapBackendTexture(const GrBackendTextureDesc& desc);
 343
 344     /**
 345      * Wraps an existing render target with a GrRenderTarget object. It is
 346      * similar to wrapBackendTexture but can be used to draw into surfaces
 347      * that are not also textures (e.g. FBO 0 in OpenGL, or an MSAA buffer that
 348      * the client will resolve to a texture).
 349      *
 350      * @param  desc     description of the object to create.
 351      *
 352      * @return GrTexture object or NULL on failure.
 353      */
 354      GrRenderTarget* wrapBackendRenderTarget(const GrBackendRenderTargetDesc& desc);
 355
 356     ///////////////////////////////////////////////////////////////////////////
 357     // Matrix state
 358
 359     /**
 360      * Gets the current transformation matrix.
 361      * @return the current matrix.
 362      */
 363     const SkMatrix& getMatrix() const { return fViewMatrix; }
 364
 365     /**
 366      * Sets the transformation matrix.
 367      * @param m the matrix to set.
 368      */
 369     void setMatrix(const SkMatrix& m) { fViewMatrix = m; }
 370
 371     /**
 372      * Sets the current transformation matrix to identity.
 373      */
 374     void setIdentityMatrix() { fViewMatrix.reset(); }
 375
 376     /**
 377      * Concats the current matrix. The passed matrix is applied before the
 378      * current matrix.
 379      * @param m the matrix to concat.
 380      */
 381     void concatMatrix(const SkMatrix& m) { fViewMatrix.preConcat(m); }
 382
 383
 384     ///////////////////////////////////////////////////////////////////////////
 385     // Clip state
 386     /**
 387      * Gets the current clip.
 388      * @return the current clip.
 389      */
 390     const GrClipData* getClip() const { return fClip; }
 391
 392     /**
 393      * Sets the clip.
 394      * @param clipData  the clip to set.
 395      */
 396     void setClip(const GrClipData* clipData) { fClip = clipData; }
 397
 398     ///////////////////////////////////////////////////////////////////////////
 399     // Draws
 400
 401     /**
 402      * Clear the entire or rect of the render target, ignoring any clips.
 403      * @param rect  the rect to clear or the whole thing if rect is NULL.
 404      * @param color the color to clear to.
 405      * @param canIgnoreRect allows partial clears to be converted to whole
 406      *                      clears on platforms for which that is cheap
 407      * @param target if non-NULL, the render target to clear otherwise clear
 408      *               the current render target
 409      */
 410     void clear(const SkIRect* rect, GrColor color, bool canIgnoreRect,
 411                GrRenderTarget* target = NULL);
 412
 413     /**
 414      *  Draw everywhere (respecting the clip) with the paint.
 415      */
 416     void drawPaint(const GrPaint& paint);
 417
 418     /**
 419      *  Draw the rect using a paint.
 420      *  @param paint        describes how to color pixels.
 421      *  @param stroke       the stroke information (width, join, cap).
 422      *                      If stroke == NULL, then the rect is filled.
 423      *                      Otherwise, if stroke width == 0, then the stroke
 424      *                      is always a single pixel thick, else the rect is
 425      *                      mitered/beveled stroked based on stroke width.
 426      *  @param matrix       Optional matrix applied to the rect. Applied before
 427      *                      context's matrix or the paint's matrix.
 428      *  The rects coords are used to access the paint (through texture matrix)
 429      */
 430     void drawRect(const GrPaint& paint,
 431                   const SkRect&,
 432                   const SkStrokeRec* stroke = NULL,
 433                   const SkMatrix* matrix = NULL);
 434
 435     /**
 436      * Maps a rect of local coordinates onto the a rect of destination
 437      * coordinates. Each rect can optionally be transformed. The localRect
 438      * is stretched over the dstRect. The dstRect is transformed by the
 439      * context's matrix. Additional optional matrices for both rects can be
 440      * provided by parameters.
 441      *
 442      * @param paint         describes how to color pixels.
 443      * @param dstRect       the destination rect to draw.
 444      * @param localRect     rect of local coordinates to be mapped onto dstRect
 445      * @param dstMatrix     Optional matrix to transform dstRect. Applied before context's matrix.
 446      * @param localMatrix   Optional matrix to transform localRect.
 447      */
 448     void drawRectToRect(const GrPaint& paint,
 449                         const SkRect& dstRect,
 450                         const SkRect& localRect,
 451                         const SkMatrix* dstMatrix = NULL,
 452                         const SkMatrix* localMatrix = NULL);
 453
 454     /**
 455      *  Draw a roundrect using a paint.
 456      *
 457      *  @param paint        describes how to color pixels.
 458      *  @param rrect        the roundrect to draw
 459      *  @param stroke       the stroke information (width, join, cap)
 460      */
 461     void drawRRect(const GrPaint& paint, const SkRRect& rrect, const SkStrokeRec& stroke);
 462
 463     /**
 464      *  Shortcut for drawing an SkPath consisting of nested rrects using a paint.
 465      *  Does not support stroking. The result is undefined if outer does not contain
 466      *  inner.
 467      *
 468      *  @param paint        describes how to color pixels.
 469      *  @param outer        the outer roundrect
 470      *  @param inner        the inner roundrect
 471      */
 472     void drawDRRect(const GrPaint& paint, const SkRRect& outer, const SkRRect& inner);
 473
 474
 475     /**
 476      * Draws a path.
 477      *
 478      * @param paint         describes how to color pixels.
 479      * @param path          the path to draw
 480      * @param stroke        the stroke information (width, join, cap)
 481      */
 482     void drawPath(const GrPaint& paint, const SkPath& path, const SkStrokeRec& stroke);
 483
 484     /**
 485      * Draws vertices with a paint.
 486      *
 487      * @param   paint           describes how to color pixels.
 488      * @param   primitiveType   primitives type to draw.
 489      * @param   vertexCount     number of vertices.
 490      * @param   positions       array of vertex positions, required.
 491      * @param   texCoords       optional array of texture coordinates used
 492      *                          to access the paint.
 493      * @param   colors          optional array of per-vertex colors, supercedes
 494      *                          the paint's color field.
 495      * @param   indices         optional array of indices. If NULL vertices
 496      *                          are drawn non-indexed.
 497      * @param   indexCount      if indices is non-null then this is the
 498      *                          number of indices.
 499      */
 500     void drawVertices(const GrPaint& paint,
 501                       GrPrimitiveType primitiveType,
 502                       int vertexCount,
 503                       const SkPoint positions[],
 504                       const SkPoint texs[],
 505                       const GrColor colors[],
 506                       const uint16_t indices[],
 507                       int indexCount);
 508
 509     /**
 510      * Draws an oval.
 511      *
 512      * @param paint         describes how to color pixels.
 513      * @param oval          the bounding rect of the oval.
 514      * @param stroke        the stroke information (width, style)
 515      */
 516     void drawOval(const GrPaint& paint,
 517                   const SkRect& oval,
 518                   const SkStrokeRec& stroke);
 519
 520     ///////////////////////////////////////////////////////////////////////////
 521     // Misc.
 522
 523     /**
 524      * Flags that affect flush() behavior.
 525      */
 526     enum FlushBits {
 527         /**
 528          * A client may reach a point where it has partially rendered a frame
 529          * through a GrContext that it knows the user will never see. This flag
 530          * causes the flush to skip submission of deferred content to the 3D API
 531          * during the flush.
 532          */
 533         kDiscard_FlushBit                    = 0x2,
 534     };
 535
 536     /**
 537      * Call to ensure all drawing to the context has been issued to the
 538      * underlying 3D API.
 539      * @param flagsBitfield     flags that control the flushing behavior. See
 540      *                          FlushBits.
 541      */
 542     void flush(int flagsBitfield = 0);
 543
 544    /**
 545     * These flags can be used with the read/write pixels functions below.
 546     */
 547     enum PixelOpsFlags {
 548         /** The GrContext will not be flushed. This means that the read or write may occur before
 549             previous draws have executed. */
 550         kDontFlush_PixelOpsFlag = 0x1,
 551         /** The src for write or dst read is unpremultiplied. This is only respected if both the
 552             config src and dst configs are an RGBA/BGRA 8888 format. */
 553         kUnpremul_PixelOpsFlag  = 0x2,
 554     };
 555
 556     /**
 557      * Reads a rectangle of pixels from a render target.
 558      * @param target        the render target to read from. NULL means the current render target.
 559      * @param left          left edge of the rectangle to read (inclusive)
 560      * @param top           top edge of the rectangle to read (inclusive)
 561      * @param width         width of rectangle to read in pixels.
 562      * @param height        height of rectangle to read in pixels.
 563      * @param config        the pixel config of the destination buffer
 564      * @param buffer        memory to read the rectangle into.
 565      * @param rowBytes      number of bytes bewtween consecutive rows. Zero means rows are tightly
 566      *                      packed.
 567      * @param pixelOpsFlags see PixelOpsFlags enum above.
 568      *
 569      * @return true if the read succeeded, false if not. The read can fail because of an unsupported
 570      *         pixel config or because no render target is currently set and NULL was passed for
 571      *         target.
 572      */
 573     bool readRenderTargetPixels(GrRenderTarget* target,
 574                                 int left, int top, int width, int height,
 575                                 GrPixelConfig config, void* buffer,
 576                                 size_t rowBytes = 0,
 577                                 uint32_t pixelOpsFlags = 0);
 578
 579     /**
 580      * Copy the src pixels [buffer, row bytes, pixel config] into a render target at the specified
 581      * rectangle.
 582      * @param target        the render target to write into. NULL means the current render target.
 583      * @param left          left edge of the rectangle to write (inclusive)
 584      * @param top           top edge of the rectangle to write (inclusive)
 585      * @param width         width of rectangle to write in pixels.
 586      * @param height        height of rectangle to write in pixels.
 587      * @param config        the pixel config of the source buffer
 588      * @param buffer        memory to read the rectangle from.
 589      * @param rowBytes      number of bytes between consecutive rows. Zero means rows are tightly
 590      *                      packed.
 591      * @param pixelOpsFlags see PixelOpsFlags enum above.
 592      *
 593      * @return true if the write succeeded, false if not. The write can fail because of an
 594      *         unsupported combination of target and pixel configs.
 595      */
 596     bool writeRenderTargetPixels(GrRenderTarget* target,
 597                                  int left, int top, int width, int height,
 598                                  GrPixelConfig config, const void* buffer,
 599                                  size_t rowBytes = 0,
 600                                  uint32_t pixelOpsFlags = 0);
 601
 602     /**
 603      * Reads a rectangle of pixels from a texture.
 604      * @param texture       the texture to read from.
 605      * @param left          left edge of the rectangle to read (inclusive)
 606      * @param top           top edge of the rectangle to read (inclusive)
 607      * @param width         width of rectangle to read in pixels.
 608      * @param height        height of rectangle to read in pixels.
 609      * @param config        the pixel config of the destination buffer
 610      * @param buffer        memory to read the rectangle into.
 611      * @param rowBytes      number of bytes between consecutive rows. Zero means rows are tightly
 612      *                      packed.
 613      * @param pixelOpsFlags see PixelOpsFlags enum above.
 614      *
 615      * @return true if the read succeeded, false if not. The read can fail because of an unsupported
 616      *         pixel config.
 617      */
 618     bool readTexturePixels(GrTexture* texture,
 619                            int left, int top, int width, int height,
 620                            GrPixelConfig config, void* buffer,
 621                            size_t rowBytes = 0,
 622                            uint32_t pixelOpsFlags = 0);
 623
 624     /**
 625      * Writes a rectangle of pixels to a texture.
 626      * @param texture       the render target to read from.
 627      * @param left          left edge of the rectangle to write (inclusive)
 628      * @param top           top edge of the rectangle to write (inclusive)
 629      * @param width         width of rectangle to write in pixels.
 630      * @param height        height of rectangle to write in pixels.
 631      * @param config        the pixel config of the source buffer
 632      * @param buffer        memory to read pixels from
 633      * @param rowBytes      number of bytes between consecutive rows. Zero
 634      *                      means rows are tightly packed.
 635      * @param pixelOpsFlags see PixelOpsFlags enum above.
 636      * @return true if the write succeeded, false if not. The write can fail because of an
 637      *         unsupported combination of texture and pixel configs.
 638      */
 639     bool writeTexturePixels(GrTexture* texture,
 640                             int left, int top, int width, int height,
 641                             GrPixelConfig config, const void* buffer,
 642                             size_t rowBytes,
 643                             uint32_t pixelOpsFlags = 0);
 644
 645
 646     /**
 647      * Copies a rectangle of texels from src to dst. The size of dst is the size of the rectangle
 648      * copied and topLeft is the position of the rect in src. The rectangle is clipped to src's
 649      * bounds.
 650      * @param src           the texture to copy from.
 651      * @param dst           the render target to copy to.
 652      * @param topLeft       the point in src that will be copied to the top-left of dst. If NULL,
 653      *                      (0, 0) will be used.
 654      */
 655     void copyTexture(GrTexture* src, GrRenderTarget* dst, const SkIPoint* topLeft = NULL);
 656
 657     /**
 658      * Resolves a render target that has MSAA. The intermediate MSAA buffer is
 659      * down-sampled to the associated GrTexture (accessible via
 660      * GrRenderTarget::asTexture()). Any pending draws to the render target will
 661      * be executed before the resolve.
 662      *
 663      * This is only necessary when a client wants to access the object directly
 664      * using the backend API directly. GrContext will detect when it must
 665      * perform a resolve to a GrTexture used as the source of a draw or before
 666      * reading pixels back from a GrTexture or GrRenderTarget.
 667      */
 668     void resolveRenderTarget(GrRenderTarget*);
 669
 670     /**
 671      * Provides a perfomance hint that the render target's contents are allowed
 672      * to become undefined.
 673      */
 674     void discardRenderTarget(GrRenderTarget*);
 675
 676 #ifdef SK_DEVELOPER
 677     void dumpFontCache() const;
 678 #endif
 679
 680     ///////////////////////////////////////////////////////////////////////////
 681     // Helpers
 682
 683     class AutoRenderTarget : public ::SkNoncopyable {
 684     public:
 685         AutoRenderTarget(GrContext* context, GrRenderTarget* target) {
 686             fPrevTarget = context->getRenderTarget();
 687             SkSafeRef(fPrevTarget);
 688             context->setRenderTarget(target);
 689             fContext = context;
 690         }
 691         AutoRenderTarget(GrContext* context) {
 692             fPrevTarget = context->getRenderTarget();
 693             SkSafeRef(fPrevTarget);
 694             fContext = context;
 695         }
 696         ~AutoRenderTarget() {
 697             if (NULL != fContext) {
 698                 fContext->setRenderTarget(fPrevTarget);
 699             }
 700             SkSafeUnref(fPrevTarget);
 701         }
 702     private:
 703         GrContext*      fContext;
 704         GrRenderTarget* fPrevTarget;
 705     };
 706
 707     /**
 708      * Save/restore the view-matrix in the context. It can optionally adjust a paint to account
 709      * for a coordinate system change. Here is an example of how the paint param can be used:
 710      *
 711      * A GrPaint is setup with GrEffects. The stages will have access to the pre-matrix source
 712      * geometry positions when the draw is executed. Later on a decision is made to transform the
 713      * geometry to device space on the CPU. The effects now need to know that the space in which
 714      * the geometry will be specified has changed.
 715      *
 716      * Note that when restore is called (or in the destructor) the context's matrix will be
 717      * restored. However, the paint will not be restored. The caller must make a copy of the
 718      * paint if necessary. Hint: use SkTCopyOnFirstWrite if the AutoMatrix is conditionally
 719      * initialized.
 720      */
 721     class AutoMatrix : public ::SkNoncopyable {
 722     public:
 723         AutoMatrix() : fContext(NULL) {}
 724
 725         ~AutoMatrix() { this->restore(); }
 726
 727         /**
 728          * Initializes by pre-concat'ing the context's current matrix with the preConcat param.
 729          */
 730         void setPreConcat(GrContext* context, const SkMatrix& preConcat, GrPaint* paint = NULL) {
 731             SkASSERT(NULL != context);
 732
 733             this->restore();
 734
 735             fContext = context;
 736             fMatrix = context->getMatrix();
 737             this->preConcat(preConcat, paint);
 738         }
 739
 740         /**
 741          * Sets the context's matrix to identity. Returns false if the inverse matrix is required to
 742          * update a paint but the matrix cannot be inverted.
 743          */
 744         bool setIdentity(GrContext* context, GrPaint* paint = NULL) {
 745             SkASSERT(NULL != context);
 746
 747             this->restore();
 748
 749             if (NULL != paint) {
 750                 if (!paint->localCoordChangeInverse(context->getMatrix())) {
 751                     return false;
 752                 }
 753             }
 754             fMatrix = context->getMatrix();
 755             fContext = context;
 756             context->setIdentityMatrix();
 757             return true;
 758         }
 759
 760         /**
 761          * Replaces the context's matrix with a new matrix. Returns false if the inverse matrix is
 762          * required to update a paint but the matrix cannot be inverted.
 763          */
 764         bool set(GrContext* context, const SkMatrix& newMatrix, GrPaint* paint = NULL) {
 765             if (NULL != paint) {
 766                 if (!this->setIdentity(context, paint)) {
 767                     return false;
 768                 }
 769                 this->preConcat(newMatrix, paint);
 770             } else {
 771                 this->restore();
 772                 fContext = context;
 773                 fMatrix = context->getMatrix();
 774                 context->setMatrix(newMatrix);
 775             }
 776             return true;
 777         }
 778
 779         /**
 780          * If this has been initialized then the context's matrix will be further updated by
 781          * pre-concat'ing the preConcat param. The matrix that will be restored remains unchanged.
 782          * The paint is assumed to be relative to the context's matrix at the time this call is
 783          * made, not the matrix at the time AutoMatrix was first initialized. In other words, this
 784          * performs an incremental update of the paint.
 785          */
 786         void preConcat(const SkMatrix& preConcat, GrPaint* paint = NULL) {
 787             if (NULL != paint) {
 788                 paint->localCoordChange(preConcat);
 789             }
 790             fContext->concatMatrix(preConcat);
 791         }
 792
 793         /**
 794          * Returns false if never initialized or the inverse matrix was required to update a paint
 795          * but the matrix could not be inverted.
 796          */
 797         bool succeeded() const { return NULL != fContext; }
 798
 799         /**
 800          * If this has been initialized then the context's original matrix is restored.
 801          */
 802         void restore() {
 803             if (NULL != fContext) {
 804                 fContext->setMatrix(fMatrix);
 805                 fContext = NULL;
 806             }
 807         }
 808
 809     private:
 810         GrContext*  fContext;
 811         SkMatrix    fMatrix;
 812     };
 813
 814     class AutoClip : public ::SkNoncopyable {
 815     public:
 816         // This enum exists to require a caller of the constructor to acknowledge that the clip will
 817         // initially be wide open. It also could be extended if there are other desirable initial
 818         // clip states.
 819         enum InitialClip {
 820             kWideOpen_InitialClip,
 821         };
 822
 823         AutoClip(GrContext* context, InitialClip initialState)
 824         : fContext(context) {
 825             SkASSERT(kWideOpen_InitialClip == initialState);
 826             fNewClipData.fClipStack = &fNewClipStack;
 827
 828             fOldClip = context->getClip();
 829             context->setClip(&fNewClipData);
 830         }
 831
 832         AutoClip(GrContext* context, const SkRect& newClipRect)
 833         : fContext(context)
 834         , fNewClipStack(newClipRect) {
 835             fNewClipData.fClipStack = &fNewClipStack;
 836
 837             fOldClip = fContext->getClip();
 838             fContext->setClip(&fNewClipData);
 839         }
 840
 841         ~AutoClip() {
 842             if (NULL != fContext) {
 843                 fContext->setClip(fOldClip);
 844             }
 845         }
 846     private:
 847         GrContext*        fContext;
 848         const GrClipData* fOldClip;
 849
 850         SkClipStack       fNewClipStack;
 851         GrClipData        fNewClipData;
 852     };
 853
 854     class AutoWideOpenIdentityDraw {
 855     public:
 856         AutoWideOpenIdentityDraw(GrContext* ctx, GrRenderTarget* rt)
 857             : fAutoClip(ctx, AutoClip::kWideOpen_InitialClip)
 858             , fAutoRT(ctx, rt) {
 859             fAutoMatrix.setIdentity(ctx);
 860             // should never fail with no paint param.
 861             SkASSERT(fAutoMatrix.succeeded());
 862         }
 863
 864     private:
 865         AutoClip fAutoClip;
 866         AutoRenderTarget fAutoRT;
 867         AutoMatrix fAutoMatrix;
 868     };
 869
 870     ///////////////////////////////////////////////////////////////////////////
 871     // Functions intended for internal use only.
 872     GrGpu* getGpu() { return fGpu; }
 873     const GrGpu* getGpu() const { return fGpu; }
 874     GrFontCache* getFontCache() { return fFontCache; }
 875     GrLayerCache* getLayerCache() { return fLayerCache.get(); }
 876     GrDrawTarget* getTextTarget();
 877     const GrIndexBuffer* getQuadIndexBuffer() const;
 878
 879     // Called by tests that draw directly to the context via GrDrawTarget
 880     void getTestTarget(GrTestTarget*);
 881
 882     // Functions for managing gpu trace markers
 883     bool isGpuTracingEnabled() const { return fGpuTracingEnabled; }
 884     void enableGpuTracing() { fGpuTracingEnabled = true; }
 885     void disableGpuTracing() { fGpuTracingEnabled = false; }
 886
 887     /**
 888      * Stencil buffers add themselves to the cache using addStencilBuffer. findStencilBuffer is
 889      * called to check the cache for a SB that matches an RT's criteria.
 890      */
 891     void addStencilBuffer(GrStencilBuffer* sb);
 892     GrStencilBuffer* findStencilBuffer(int width, int height, int sampleCnt);
 893
 894     GrPathRenderer* getPathRenderer(
 895                     const SkPath& path,
 896                     const SkStrokeRec& stroke,
 897                     const GrDrawTarget* target,
 898                     bool allowSW,
 899                     GrPathRendererChain::DrawType drawType = GrPathRendererChain::kColor_DrawType,
 900                     GrPathRendererChain::StencilSupport* stencilSupport = NULL);
 901
 902     /**
 903      * Stores a custom resource in the cache, based on the specified key.
 904      */
 905     void addResourceToCache(const GrResourceKey&, GrCacheable*);
 906
 907     /**
 908      * Finds a resource in the cache, based on the specified key. This is intended for use in
 909      * conjunction with addResourceToCache(). The return value will be NULL if not found. The
 910      * caller must balance with a call to unref().
 911      */
 912     GrCacheable* findAndRefCachedResource(const GrResourceKey&);
 913
 914 #if GR_CACHE_STATS
 915     void printCacheStats() const;
 916 #endif
 917
 918 private:
 919     // Used to indicate whether a draw should be performed immediately or queued in fDrawBuffer.
 920     enum BufferedDraw {
 921         kYes_BufferedDraw,
 922         kNo_BufferedDraw,
 923     };
 924     BufferedDraw fLastDrawWasBuffered;
 925
 926     GrGpu*                          fGpu;
 927     SkMatrix                        fViewMatrix;
 928     SkAutoTUnref<GrRenderTarget>    fRenderTarget;
 929     const GrClipData*               fClip;  // TODO: make this ref counted
 930     GrDrawState*                    fDrawState;
 931
 932     GrResourceCache*                fTextureCache;
 933     GrFontCache*                    fFontCache;
 934     SkAutoTDelete<GrLayerCache>     fLayerCache;
 935
 936     GrPathRendererChain*            fPathRendererChain;
 937     GrSoftwarePathRenderer*         fSoftwarePathRenderer;
 938
 939     GrVertexBufferAllocPool*        fDrawBufferVBAllocPool;
 940     GrIndexBufferAllocPool*         fDrawBufferIBAllocPool;
 941     GrInOrderDrawBuffer*            fDrawBuffer;
 942
 943     // Set by OverbudgetCB() to request that GrContext flush before exiting a draw.
 944     bool                            fFlushToReduceCacheSize;
 945
 946     GrAARectRenderer*               fAARectRenderer;
 947     GrOvalRenderer*                 fOvalRenderer;
 948
 949     bool                            fDidTestPMConversions;
 950     int                             fPMToUPMConversion;
 951     int                             fUPMToPMConversion;
 952
 953     struct CleanUpData {
 954         PFCleanUpFunc fFunc;
 955         void*         fInfo;
 956     };
 957
 958     SkTDArray<CleanUpData>          fCleanUpData;
 959
 960     int                             fMaxTextureSizeOverride;
 961
 962     bool                            fGpuTracingEnabled;
 963
 964     GrContext(); // init must be called after the constructor.
 965     bool init(GrBackend, GrBackendContext);
 966
 967     void setupDrawBuffer();
 968
 969     class AutoRestoreEffects;
 970     class AutoCheckFlush;
 971     /// Sets the paint and returns the target to draw into. The paint can be NULL in which case the
 972     /// draw state is left unmodified.
 973     GrDrawTarget* prepareToDraw(const GrPaint*, BufferedDraw, AutoRestoreEffects*, AutoCheckFlush*);
 974
 975     void internalDrawPath(GrDrawTarget* target, bool useAA, const SkPath& path,
 976                           const SkStrokeRec& stroke);
 977
 978     GrTexture* createResizedTexture(const GrTextureDesc& desc,
 979                                     const GrCacheID& cacheID,
 980                                     void* srcData,
 981                                     size_t rowBytes,
 982                                     bool filter);
 983
 984     // Needed so GrTexture's returnToCache helper function can call
 985     // addExistingTextureToCache
 986     friend class GrTexture;
 987     friend class GrStencilAndCoverPathRenderer;
 988
 989     // Add an existing texture to the texture cache. This is intended solely
 990     // for use with textures released from an GrAutoScratchTexture.
 991     void addExistingTextureToCache(GrTexture* texture);
 992
 993     /**
 994      * These functions create premul <-> unpremul effects if it is possible to generate a pair
 995      * of effects that make a readToUPM->writeToPM->readToUPM cycle invariant. Otherwise, they
 996      * return NULL.
 997      */
 998     const GrEffectRef* createPMToUPMEffect(GrTexture* texture,
 999                                            bool swapRAndB,
1000                                            const SkMatrix& matrix);
1001     const GrEffectRef* createUPMToPMEffect(GrTexture* texture,
1002                                            bool swapRAndB,
1003                                            const SkMatrix& matrix);
1004
1005     /**
1006      *  This callback allows the resource cache to callback into the GrContext
1007      *  when the cache is still overbudget after a purge.
1008      */
1009     static bool OverbudgetCB(void* data);
1010
1011     /** Creates a new gpu path, based on the specified path and stroke and returns it.
1012      * The caller owns a ref on the returned path which must be balanced by a call to unref.
1013      *
1014      * @param skPath the path geometry.
1015      * @param stroke the path stroke.
1016      * @return a new path or NULL if the operation is not supported by the backend.
1017      */
1018     GrPath* createPath(const SkPath& skPath, const SkStrokeRec& stroke);
1019
1020     typedef SkRefCnt INHERITED;
1021 };
1022
1023 /**
1024  * Gets and locks a scratch texture from a descriptor using either exact or approximate criteria.
1025  * Unlocks texture in the destructor.
1026  */
1027 class GrAutoScratchTexture : public ::SkNoncopyable {
1028 public:
1029     GrAutoScratchTexture()
1030         : fContext(NULL)
1031         , fTexture(NULL) {
1032     }
1033
1034     GrAutoScratchTexture(GrContext* context,
1035                          const GrTextureDesc& desc,
1036                          GrContext::ScratchTexMatch match = GrContext::kApprox_ScratchTexMatch)
1037       : fContext(NULL)
1038       , fTexture(NULL) {
1039       this->set(context, desc, match);
1040     }
1041
1042     ~GrAutoScratchTexture() {
1043         this->reset();
1044     }
1045
1046     void reset() {
1047         if (NULL != fContext && NULL != fTexture) {
1048             fContext->unlockScratchTexture(fTexture);
1049             fTexture->unref();
1050             fTexture = NULL;
1051         }
1052     }
1053
1054     /*
1055      * When detaching a texture we do not unlock it in the texture cache but
1056      * we do set the returnToCache flag. In this way the texture remains
1057      * "locked" in the texture cache until it is freed and recycled in
1058      * GrTexture::internal_dispose. In reality, the texture has been removed
1059      * from the cache (because this is in AutoScratchTexture) and by not
1060      * calling unlockScratchTexture we simply don't re-add it. It will be
1061      * reattached in GrTexture::internal_dispose.
1062      *
1063      * Note that the caller is assumed to accept and manage the ref to the
1064      * returned texture.
1065      */
1066     GrTexture* detach() {
1067         if (NULL == fTexture) {
1068             return NULL;
1069         }
1070         GrTexture* texture = fTexture;
1071         fTexture = NULL;
1072
1073         // This GrAutoScratchTexture has a ref from lockAndRefScratchTexture, which we give up now.
1074         // The cache also has a ref which we are lending to the caller of detach(). When the caller
1075         // lets go of the ref and the ref count goes to 0 internal_dispose will see this flag is
1076         // set and re-ref the texture, thereby restoring the cache's ref.
1077         SkASSERT(texture->getRefCnt() > 1);
1078         texture->setFlag((GrTextureFlags) GrTexture::kReturnToCache_FlagBit);
1079         texture->unref();
1080         SkASSERT(NULL != texture->getCacheEntry());
1081
1082         return texture;
1083     }
1084
1085     GrTexture* set(GrContext* context,
1086                    const GrTextureDesc& desc,
1087                    GrContext::ScratchTexMatch match = GrContext::kApprox_ScratchTexMatch) {
1088         this->reset();
1089
1090         fContext = context;
1091         if (NULL != fContext) {
1092             fTexture = fContext->lockAndRefScratchTexture(desc, match);
1093             if (NULL == fTexture) {
1094                 fContext = NULL;
1095             }
1096             return fTexture;
1097         } else {
1098             return NULL;
1099         }
1100     }
1101
1102     GrTexture* texture() { return fTexture; }
1103
1104 private:
1105     GrContext*                    fContext;
1106     GrTexture*                    fTexture;
1107 };
1108
1109 #endif