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