Extract most of the mutable state of SkShader into a separate Context object.

include/core/SkShader.h

 /*
  * Copyright 2006 The Android Open Source Project
  *
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 
 #ifndef SkShader_DEFINED
 #define SkShader_DEFINED
@@ skipping 19 matching lines @@
  *  to be modified.
  */
 class SK_API SkShader : public SkFlattenable {
 public:
     SK_DECLARE_INST_COUNT(SkShader)
 
     SkShader();
     virtual ~SkShader();
 
     /**
-     * Returns true if the local matrix is not an identity matrix.
+     *  Returns true if the local matrix is not an identity matrix.
+     *  FIXME: local matrix is moving to SkPaint.

[scroggo, 2014/04/07 13:44:31]

I know I originally wrote this, and this is what we were thinking at the time,
but I've talked it over mtklein, and we no longer think this will move to
SkPaint. See
https://docs.google.com/a/google.com/document/d/13HHTH6O9QL_gTBNBRZCBzCP8JwsG...

[Dominik Grewe, 2014/04/07 14:04:52]

Okay, cool. I'll delete the comment (and the ones below).
Were you planning to make the changes proposed in the doc any time soon? Or
would you mind me having a go?

      */
     bool hasLocalMatrix() const { return !fLocalMatrix.isIdentity(); }
 
     /**
      *  Returns the local matrix.
+     *  FIXME: local matrix is moving to SkPaint.
      */
     const SkMatrix& getLocalMatrix() const { return fLocalMatrix; }
 
     /**
      *  Set the shader's local matrix.
      *  @param localM   The shader's new local matrix.
+     *
+     *  FIXME: local matrix is moving to SkPaint.
      */
     void setLocalMatrix(const SkMatrix& localM) { fLocalMatrix = localM; }
 
     /**
      *  Reset the shader's local matrix to identity.
+     *
+     *  FIXME: local matrix is moving to SkPaint.
      */
     void resetLocalMatrix() { fLocalMatrix.reset(); }
 
     enum TileMode {
         /** replicate the edge color if the shader draws outside of its
          *  original bounds
          */
         kClamp_TileMode,
 
         /** repeat the shader's image horizontally and vertically */
@@ skipping 21 matching lines @@
         //! set if this shader's shadeSpan16() method can be called
         kHasSpan16_Flag = 0x02,
 
         /** Set this bit if the shader's native data type is instrinsically 16
             bit, meaning that calling the 32bit shadeSpan() entry point will
             mean the the impl has to up-sample 16bit data into 32bit. Used as a
             a means of clearing a dither request if the it will have no effect
         */
         kIntrinsicly16_Flag = 0x04,
 
-        /** set (after setContext) if the spans only vary in X (const in Y).
+        /** set if the spans only vary in X (const in Y).
             e.g. an Nx1 bitmap that is being tiled in Y, or a linear-gradient
             that varies from left-to-right. This flag specifies this for
             shadeSpan().
          */
         kConstInY32_Flag = 0x08,
 
         /** same as kConstInY32_Flag, but is set if this is true for shadeSpan16
             which may not always be the case, since shadeSpan16 may be
             predithered, which would mean it was not const in Y, even though
             the 32bit shadeSpan() would be const.
          */
         kConstInY16_Flag = 0x10
     };
 
     /**
-     *  Called sometimes before drawing with this shader. Return the type of
-     *  alpha your shader will return. The default implementation returns 0.
-     *  Your subclass should override if it can (even sometimes) report a
-     *  non-zero value, since that will enable various blitters to perform
-     *  faster.
-     */
-    virtual uint32_t getFlags() { return 0; }
-
-    /**
      *  Returns true if the shader is guaranteed to produce only opaque
      *  colors, subject to the SkPaint using the shader to apply an opaque
      *  alpha value. Subclasses should override this to allow some
-     *  optimizations.  isOpaque() can be called at any time, unlike getFlags,
-     *  which only works properly when the context is set.
+     *  optimizations.
      */
     virtual bool isOpaque() const { return false; }
 
-    /**
-     *  Return the alpha associated with the data returned by shadeSpan16(). If
-     *  kHasSpan16_Flag is not set, this value is meaningless.
-     */
-    virtual uint8_t getSpan16Alpha() const { return fPaintAlpha; }
+    class Context : public SkNoncopyable {
+    public:
+        Context(const SkShader& shader, const SkBitmap& device,
+                const SkPaint& paint, const SkMatrix& matrix);
+
+        virtual ~Context();
+
+        /**
+         *  Called sometimes before drawing with this shader. Return the type of
+         *  alpha your shader will return. The default implementation returns 0.
+         *  Your subclass should override if it can (even sometimes) report a
+         *  non-zero value, since that will enable various blitters to perform
+         *  faster.
+         */
+        virtual uint32_t getFlags() const { return 0; }
+
+        /**
+         *  Return the alpha associated with the data returned by shadeSpan16(). If
+         *  kHasSpan16_Flag is not set, this value is meaningless.
+         */
+        virtual uint8_t getSpan16Alpha() const { return fPaintAlpha; }
+
+        /**
+         *  Called for each span of the object being drawn. Your subclass should
+         *  set the appropriate colors (with premultiplied alpha) that correspond
+         *  to the specified device coordinates.
+         */
+        virtual void shadeSpan(int x, int y, SkPMColor[], int count) = 0;
+
+        typedef void (*ShadeProc)(void* ctx, int x, int y, SkPMColor[], int count);
+        virtual ShadeProc asAShadeProc(void** ctx);
+
+        /**
+         *  Called only for 16bit devices when getFlags() returns
+         *  kOpaqueAlphaFlag | kHasSpan16_Flag
+         */
+        virtual void shadeSpan16(int x, int y, uint16_t[], int count);
+
+        /**
+         *  Similar to shadeSpan, but only returns the alpha-channel for a span.
+         *  The default implementation calls shadeSpan() and then extracts the alpha
+         *  values from the returned colors.
+         */
+        virtual void shadeSpanAlpha(int x, int y, uint8_t alpha[], int count);
+
+        /**
+         *  Helper function that returns true if this shader's shadeSpan16() method
+         *  can be called.
+         */
+        bool canCallShadeSpan16() {
+            return SkShader::CanCallShadeSpan16(this->getFlags());
+        }
+
+    protected:
+        // Reference to generator, so we don't have to dupe information.
+        const SkShader& fShader;
+
+        enum MatrixClass {
+            kLinear_MatrixClass,            // no perspective
+            kFixedStepInX_MatrixClass,      // fast perspective, need to call fixedStepInX() each
+                                            // scanline
+            kPerspective_MatrixClass        // slow perspective, need to mappoints each pixel
+        };
+        static MatrixClass ComputeMatrixClass(const SkMatrix&);
+
+        uint8_t             getPaintAlpha() const { return fPaintAlpha; }
+        const SkMatrix&     getTotalInverse() const { return fTotalInverse; }
+        MatrixClass         getInverseClass() const { return (MatrixClass)fTotalInverseClass; }
+    private:
+        SkMatrix            fTotalInverse;
+        uint8_t             fPaintAlpha;
+        uint8_t             fTotalInverseClass;
+    };
 
     /**
-     *  Called once before drawing, with the current paint and device matrix.
-     *  Return true if your shader supports these parameters, or false if not.
-     *  If false is returned, nothing will be drawn. If true is returned, then
-     *  a balancing call to endContext() will be made before the next call to
-     *  setContext.
-     *
-     *  Subclasses should be sure to call their INHERITED::setContext() if they
-     *  override this method.
+     *  Subclasses should be sure to call their INHERITED::validContext() if
+     *  they override this method.
      */
-    virtual bool setContext(const SkBitmap& device, const SkPaint& paint,
-                            const SkMatrix& matrix);
+    virtual bool validContext(const SkBitmap& device, const SkPaint& paint,
+                              const SkMatrix& matrix, SkMatrix* totalInverse = NULL) const;
 
     /**
-     *  Assuming setContext returned true, endContext() will be called when
-     *  the draw using the shader has completed. It is an error for setContext
-     *  to be called twice w/o an intervening call to endContext().
-     *
-     *  Subclasses should be sure to call their INHERITED::endContext() if they
-     *  override this method.
+     *  Called internally to create the actual object that does the shading.
+     *  Only valid if validContext() returned true.
+     *  Size of storage must be >= contextSize.
      */
-    virtual void endContext();
-
-    SkDEBUGCODE(bool setContextHasBeenCalled() const { return SkToBool(fInSetContext); })
+    virtual Context* createContext(const SkBitmap& device,
+                                   const SkPaint& paint,
+                                   const SkMatrix& matrix,
+                                   void* storage) const = 0;
 
     /**
-     *  Called for each span of the object being drawn. Your subclass should
-     *  set the appropriate colors (with premultiplied alpha) that correspond
-     *  to the specified device coordinates.
+     *  Return the size of a Context returned by createContext.
      */
-    virtual void shadeSpan(int x, int y, SkPMColor[], int count) = 0;
-
-    typedef void (*ShadeProc)(void* ctx, int x, int y, SkPMColor[], int count);
-    virtual ShadeProc asAShadeProc(void** ctx);
-
-    /**
-     *  Called only for 16bit devices when getFlags() returns
-     *  kOpaqueAlphaFlag | kHasSpan16_Flag
-     */
-    virtual void shadeSpan16(int x, int y, uint16_t[], int count);
-
-    /**
-     *  Similar to shadeSpan, but only returns the alpha-channel for a span.
-     *  The default implementation calls shadeSpan() and then extracts the alpha
-     *  values from the returned colors.
-     */
-    virtual void shadeSpanAlpha(int x, int y, uint8_t alpha[], int count);
-
-    /**
-     *  Helper function that returns true if this shader's shadeSpan16() method
-     *  can be called.
-     */
-    bool canCallShadeSpan16() {
-        return SkShader::CanCallShadeSpan16(this->getFlags());
-    }
+    virtual size_t contextSize() const = 0;
 
     /**
      *  Helper to check the flags to know if it is legal to call shadeSpan16()
      */
     static bool CanCallShadeSpan16(uint32_t flags) {
         return (flags & kHasSpan16_Flag) != 0;
     }
 
     /**
      Gives method bitmap should be read to implement a shader.
@@ skipping 112 matching lines @@
         uint32_t    fGradientFlags; //!< see SkGradientShader::Flags
     };
 
     virtual GradientType asAGradient(GradientInfo* info) const;
 
     /**
      *  If the shader subclass has a GrEffect implementation, this resturns the effect to install.
      *  The incoming color to the effect has r=g=b=a all extracted from the SkPaint's alpha.
      *  The output color should be the computed SkShader premul color modulated by the incoming
      *  color. The GrContext may be used by the effect to create textures. The GPU device does not
-     *  call setContext. Instead we pass the SkPaint here in case the shader needs paint info.
+     *  call createContext. Instead we pass the SkPaint here in case the shader needs paint info.
      */
     virtual GrEffectRef* asNewEffect(GrContext* context, const SkPaint& paint) const;
 
     //////////////////////////////////////////////////////////////////////////
     //  Factory methods for stock shaders
 
     /** Call this to create a new shader that will draw with the specified bitmap.
      *
      *  If the bitmap cannot be used (e.g. has no pixels, or its dimensions
      *  exceed implementation limits (currently at 64K - 1)) then SkEmptyShader
      *  may be returned.
      *
      *  If the src is kA8_Config then that mask will be colorized using the color on
      *  the paint.
      *
      *  @param src  The bitmap to use inside the shader
      *  @param tmx  The tiling mode to use when sampling the bitmap in the x-direction.
      *  @param tmy  The tiling mode to use when sampling the bitmap in the y-direction.
      *  @return     Returns a new shader object. Note: this function never returns null.
     */
     static SkShader* CreateBitmapShader(const SkBitmap& src,
                                         TileMode tmx, TileMode tmy);
 
     SK_TO_STRING_VIRT()
     SK_DEFINE_FLATTENABLE_TYPE(SkShader)
 
 protected:
-    enum MatrixClass {
-        kLinear_MatrixClass,            // no perspective
-        kFixedStepInX_MatrixClass,      // fast perspective, need to call fixedStepInX() each scanline
-        kPerspective_MatrixClass        // slow perspective, need to mappoints each pixel
-    };
-    static MatrixClass ComputeMatrixClass(const SkMatrix&);
-
-    // These can be called by your subclass after setContext() has been called
-    uint8_t             getPaintAlpha() const { return fPaintAlpha; }
-    const SkMatrix&     getTotalInverse() const { return fTotalInverse; }
-    MatrixClass         getInverseClass() const { return (MatrixClass)fTotalInverseClass; }
 
     SkShader(SkReadBuffer& );
     virtual void flatten(SkWriteBuffer&) const SK_OVERRIDE;
+
 private:
+    // FIXME: Move to SkPaint.
     SkMatrix            fLocalMatrix;
-    SkMatrix            fTotalInverse;
-    uint8_t             fPaintAlpha;
-    uint8_t             fTotalInverseClass;
-    SkDEBUGCODE(SkBool8 fInSetContext;)
+
+    bool computeTotalInverse(const SkMatrix& matrix, SkMatrix* totalInverse) const;
 
     typedef SkFlattenable INHERITED;
 };
 
 #endif