SkPaint.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 SkPaint_DEFINED
#define SkPaint_DEFINED

#include "SkColor.h"
#include "SkFilterQuality.h"
#include "SkMatrix.h"
#include "SkXfermode.h"

class SkAutoDescriptor;
class SkAutoGlyphCache;
class SkColorFilter;
class SkData;
class SkDescriptor;
class SkDrawLooper;
class SkReadBuffer;
class SkWriteBuffer;
class SkGlyph;
struct SkRect;
class SkGlyphCache;
class SkImageFilter;
class SkMaskFilter;
class SkPath;
class SkPathEffect;
struct SkPoint;
class SkRasterizer;
struct SkScalerContextEffects;
class SkShader;
class SkSurfaceProps;
class SkTextBlob;
class SkTypeface;

#define kBicubicFilterBitmap_Flag kHighQualityFilterBitmap_Flag

class SK_API SkPaint {
public:
    SkPaint();
    SkPaint(const SkPaint& paint);
    SkPaint(SkPaint&& paint);
    ~SkPaint();

    SkPaint& operator=(const SkPaint&);
    SkPaint& operator=(SkPaint&&);

    SK_API friend bool operator==(const SkPaint& a, const SkPaint& b);
    friend bool operator!=(const SkPaint& a, const SkPaint& b) {
        return !(a == b);
    }

    uint32_t getHash() const;

    void flatten(SkWriteBuffer&) const;
    void unflatten(SkReadBuffer&);

    void reset();

    enum Hinting {
        kNo_Hinting            = 0,
        kSlight_Hinting        = 1,
        kNormal_Hinting        = 2,     
        kFull_Hinting          = 3
    };

    Hinting getHinting() const {
        return static_cast<Hinting>(fBitfields.fHinting);
    }

    void setHinting(Hinting hintingLevel);

    enum Flags {
        kAntiAlias_Flag       = 0x01,   
        kDither_Flag          = 0x04,   
        kUnderlineText_Flag   = 0x08,   
        kStrikeThruText_Flag  = 0x10,   
        kFakeBoldText_Flag    = 0x20,   
        kLinearText_Flag      = 0x40,   
        kSubpixelText_Flag    = 0x80,   
        kDevKernText_Flag     = 0x100,  
        kLCDRenderText_Flag   = 0x200,  
        kEmbeddedBitmapText_Flag = 0x400, 
        kAutoHinting_Flag     = 0x800,  
        kVerticalText_Flag    = 0x1000,
        kGenA8FromLCD_Flag    = 0x2000, // hack for GDI -- do not use if you can help it
        // when adding extra flags, note that the fFlags member is specified
        // with a bit-width and you'll have to expand it.

        kAllFlags = 0xFFFF
    };

    uint32_t getFlags() const { return fBitfields.fFlags; }

    void setFlags(uint32_t flags);

    bool isAntiAlias() const {
        return SkToBool(this->getFlags() & kAntiAlias_Flag);
    }

    void setAntiAlias(bool aa);

    bool isDither() const {
        return SkToBool(this->getFlags() & kDither_Flag);
    }

    void setDither(bool dither);

    bool isLinearText() const {
        return SkToBool(this->getFlags() & kLinearText_Flag);
    }

    void setLinearText(bool linearText);

    bool isSubpixelText() const {
        return SkToBool(this->getFlags() & kSubpixelText_Flag);
    }

    void setSubpixelText(bool subpixelText);

    bool isLCDRenderText() const {
        return SkToBool(this->getFlags() & kLCDRenderText_Flag);
    }

    void setLCDRenderText(bool lcdText);

    bool isEmbeddedBitmapText() const {
        return SkToBool(this->getFlags() & kEmbeddedBitmapText_Flag);
    }

    void setEmbeddedBitmapText(bool useEmbeddedBitmapText);

    bool isAutohinted() const {
        return SkToBool(this->getFlags() & kAutoHinting_Flag);
    }

    void setAutohinted(bool useAutohinter);

    bool isVerticalText() const {
        return SkToBool(this->getFlags() & kVerticalText_Flag);
    }

    void setVerticalText(bool);

    bool isUnderlineText() const {
        return SkToBool(this->getFlags() & kUnderlineText_Flag);
    }

    void setUnderlineText(bool underlineText);

    bool isStrikeThruText() const {
        return SkToBool(this->getFlags() & kStrikeThruText_Flag);
    }

    void setStrikeThruText(bool strikeThruText);

    bool isFakeBoldText() const {
        return SkToBool(this->getFlags() & kFakeBoldText_Flag);
    }

    void setFakeBoldText(bool fakeBoldText);

    bool isDevKernText() const {
        return SkToBool(this->getFlags() & kDevKernText_Flag);
    }

    void setDevKernText(bool devKernText);

    SkFilterQuality getFilterQuality() const {
        return (SkFilterQuality)fBitfields.fFilterQuality;
    }

    void setFilterQuality(SkFilterQuality quality);

    enum Style {
        kFill_Style,            
        kStroke_Style,          
        kStrokeAndFill_Style,   
    };
    enum {
        kStyleCount = kStrokeAndFill_Style + 1
    };

    Style getStyle() const { return (Style)fBitfields.fStyle; }

    void setStyle(Style style);

    SkColor getColor() const { return fColor; }

    void setColor(SkColor color);

    uint8_t getAlpha() const { return SkToU8(SkColorGetA(fColor)); }

    void setAlpha(U8CPU a);

    void setARGB(U8CPU a, U8CPU r, U8CPU g, U8CPU b);

    SkScalar getStrokeWidth() const { return fWidth; }

    void setStrokeWidth(SkScalar width);

    SkScalar getStrokeMiter() const { return fMiterLimit; }

    void setStrokeMiter(SkScalar miter);

    enum Cap {
        kButt_Cap,      
        kRound_Cap,     
        kSquare_Cap,    

        kLast_Cap = kSquare_Cap,
        kDefault_Cap = kButt_Cap
    };
    static constexpr int kCapCount = kLast_Cap + 1;

    enum Join {
        kMiter_Join,    
        kRound_Join,    
        kBevel_Join,    

        kLast_Join = kBevel_Join,
        kDefault_Join = kMiter_Join
    };
    static constexpr int kJoinCount = kLast_Join + 1;

    Cap getStrokeCap() const { return (Cap)fBitfields.fCapType; }

    void setStrokeCap(Cap cap);

    Join getStrokeJoin() const { return (Join)fBitfields.fJoinType; }

    void setStrokeJoin(Join join);

    bool getFillPath(const SkPath& src, SkPath* dst, const SkRect* cullRect,
                     SkScalar resScale = 1) const;

    bool getFillPath(const SkPath& src, SkPath* dst) const {
        return this->getFillPath(src, dst, NULL, 1);
    }

    SkShader* getShader() const { return fShader.get(); }

    void setShader(sk_sp<SkShader>);
#ifdef SK_SUPPORT_LEGACY_CREATESHADER_PTR
    SkShader* setShader(SkShader* shader);
#endif

    SkColorFilter* getColorFilter() const { return fColorFilter.get(); }

#ifdef SK_SUPPORT_LEGACY_COLORFILTER_PTR
    SkColorFilter* setColorFilter(SkColorFilter* filter);
#endif
    void setColorFilter(sk_sp<SkColorFilter>);

    SkXfermode* getXfermode() const { return fXfermode.get(); }

    void setXfermode(sk_sp<SkXfermode>);
#ifdef SK_SUPPORT_LEGACY_XFERMODE_PTR
    SkXfermode* setXfermode(SkXfermode* xfermode);
#endif

    SkXfermode* setXfermodeMode(SkXfermode::Mode);

    SkPathEffect* getPathEffect() const { return fPathEffect.get(); }

    void setPathEffect(sk_sp<SkPathEffect>);
#ifdef SK_SUPPORT_LEGACY_PATHEFFECT_PTR
    SkPathEffect* setPathEffect(SkPathEffect* effect);
#endif

    SkMaskFilter* getMaskFilter() const { return fMaskFilter.get(); }

#ifdef SK_SUPPORT_LEGACY_MASKFILTER_PTR
    SkMaskFilter* setMaskFilter(SkMaskFilter* maskfilter);
#endif
    void setMaskFilter(sk_sp<SkMaskFilter>);

    // These attributes are for text/fonts

    SkTypeface* getTypeface() const { return fTypeface.get(); }

    void setTypeface(sk_sp<SkTypeface>);
#ifdef SK_SUPPORT_LEGACY_TYPEFACE_PTR
    SkTypeface* setTypeface(SkTypeface* typeface);
#endif

    SkRasterizer* getRasterizer() const { return fRasterizer.get(); }

#ifdef SK_SUPPORT_LEGACY_MINOR_EFFECT_PTR
    SkRasterizer* setRasterizer(SkRasterizer* rasterizer);
#endif
    void setRasterizer(sk_sp<SkRasterizer>);

    SkImageFilter* getImageFilter() const { return fImageFilter.get(); }
    SkImageFilter* setImageFilter(SkImageFilter*);
    void setImageFilter(sk_sp<SkImageFilter>);

    SkDrawLooper* getLooper() const { return fLooper.get(); }

#ifdef SK_SUPPORT_LEGACY_MINOR_EFFECT_PTR
    SkDrawLooper* setLooper(SkDrawLooper* looper);
#endif
    void setLooper(sk_sp<SkDrawLooper>);

    enum Align {
        kLeft_Align,
        kCenter_Align,
        kRight_Align,
    };
    enum {
        kAlignCount = 3
    };

    Align   getTextAlign() const { return (Align)fBitfields.fTextAlign; }

    void    setTextAlign(Align align);

    SkScalar getTextSize() const { return fTextSize; }

    void setTextSize(SkScalar textSize);

    SkScalar getTextScaleX() const { return fTextScaleX; }

    void setTextScaleX(SkScalar scaleX);

    SkScalar getTextSkewX() const { return fTextSkewX; }

    void setTextSkewX(SkScalar skewX);

    enum TextEncoding {
        kUTF8_TextEncoding,     
        kUTF16_TextEncoding,    
        kUTF32_TextEncoding,    
        kGlyphID_TextEncoding   
    };

    TextEncoding getTextEncoding() const {
      return (TextEncoding)fBitfields.fTextEncoding;
    }

    void setTextEncoding(TextEncoding encoding);

    struct FontMetrics {
        enum FontMetricsFlags {
            kUnderlineThinknessIsValid_Flag = 1 << 0,
            kUnderlinePositionIsValid_Flag = 1 << 1,
        };

        uint32_t    fFlags;       
        SkScalar    fTop;       
        SkScalar    fAscent;    
        SkScalar    fDescent;   
        SkScalar    fBottom;    
        SkScalar    fLeading;   
        SkScalar    fAvgCharWidth;  
        SkScalar    fMaxCharWidth;  
        SkScalar    fXMin;      
        SkScalar    fXMax;      
        SkScalar    fXHeight;   
        SkScalar    fCapHeight;  
        SkScalar    fUnderlineThickness; 

        SkScalar    fUnderlinePosition; 

        bool hasUnderlineThickness(SkScalar* thickness) const {
            if (SkToBool(fFlags & kUnderlineThinknessIsValid_Flag)) {
                *thickness = fUnderlineThickness;
                return true;
            }
            return false;
        }

        bool hasUnderlinePosition(SkScalar* position) const {
            if (SkToBool(fFlags & kUnderlinePositionIsValid_Flag)) {
                *position = fUnderlinePosition;
                return true;
            }
            return false;
        }

    };

    SkScalar getFontMetrics(FontMetrics* metrics, SkScalar scale = 0) const;

    SkScalar getFontSpacing() const { return this->getFontMetrics(NULL, 0); }

    int textToGlyphs(const void* text, size_t byteLength,
                     SkGlyphID glyphs[]) const;

    bool containsText(const void* text, size_t byteLength) const;

    void glyphsToUnichars(const SkGlyphID glyphs[], int count, SkUnichar text[]) const;

    int countText(const void* text, size_t byteLength) const {
        return this->textToGlyphs(text, byteLength, NULL);
    }

    SkScalar measureText(const void* text, size_t length, SkRect* bounds) const;

    SkScalar measureText(const void* text, size_t length) const {
        return this->measureText(text, length, NULL);
    }

    size_t  breakText(const void* text, size_t length, SkScalar maxWidth,
                      SkScalar* measuredWidth = NULL) const;

    int getTextWidths(const void* text, size_t byteLength, SkScalar widths[],
                      SkRect bounds[] = NULL) const;

    void getTextPath(const void* text, size_t length, SkScalar x, SkScalar y,
                     SkPath* path) const;

    void getPosTextPath(const void* text, size_t length,
                        const SkPoint pos[], SkPath* path) const;

    int getTextIntercepts(const void* text, size_t length, SkScalar x, SkScalar y,
                          const SkScalar bounds[2], SkScalar* intervals) const;

    int getPosTextIntercepts(const void* text, size_t length, const SkPoint pos[],
                             const SkScalar bounds[2], SkScalar* intervals) const;

    int getPosTextHIntercepts(const void* text, size_t length, const SkScalar xpos[],
                              SkScalar constY, const SkScalar bounds[2], SkScalar* intervals) const;

    int getTextBlobIntercepts(const SkTextBlob* blob, const SkScalar bounds[2],
                              SkScalar* intervals) const;

    SkRect getFontBounds() const;

    // returns true if the paint's settings (e.g. xfermode + alpha) resolve to
    // mean that we need not draw at all (e.g. SrcOver + 0-alpha)
    bool nothingToDraw() const;

    // would prefer to make these private...

    bool canComputeFastBounds() const;

    const SkRect& computeFastBounds(const SkRect& orig, SkRect* storage) const {
        SkPaint::Style style = this->getStyle();
        // ultra fast-case: filling with no effects that affect geometry
        if (kFill_Style == style) {
            uintptr_t effects = reinterpret_cast<uintptr_t>(this->getLooper());
            effects |= reinterpret_cast<uintptr_t>(this->getMaskFilter());
            effects |= reinterpret_cast<uintptr_t>(this->getPathEffect());
            effects |= reinterpret_cast<uintptr_t>(this->getImageFilter());
            if (!effects) {
                return orig;
            }
        }

        return this->doComputeFastBounds(orig, storage, style);
    }

    const SkRect& computeFastStrokeBounds(const SkRect& orig,
                                          SkRect* storage) const {
        return this->doComputeFastBounds(orig, storage, kStroke_Style);
    }

    // Take the style explicitly, so the caller can force us to be stroked
    // without having to make a copy of the paint just to change that field.
    const SkRect& doComputeFastBounds(const SkRect& orig, SkRect* storage,
                                      Style) const;

    static SkMatrix* SetTextMatrix(SkMatrix* matrix, SkScalar size,
                                   SkScalar scaleX, SkScalar skewX) {
        matrix->setScale(size * scaleX, size);
        if (skewX) {
            matrix->postSkew(skewX, 0);
        }
        return matrix;
    }

    SkMatrix* setTextMatrix(SkMatrix* matrix) const {
        return SetTextMatrix(matrix, fTextSize, fTextScaleX, fTextSkewX);
    }

    typedef const SkGlyph& (*GlyphCacheProc)(SkGlyphCache*, const char**);

    SK_TO_STRING_NONVIRT()

private:
    sk_sp<SkTypeface>     fTypeface;
    sk_sp<SkPathEffect>   fPathEffect;
    sk_sp<SkShader>       fShader;
    sk_sp<SkXfermode>     fXfermode;
    sk_sp<SkMaskFilter>   fMaskFilter;
    sk_sp<SkColorFilter>  fColorFilter;
    sk_sp<SkRasterizer>   fRasterizer;
    sk_sp<SkDrawLooper>   fLooper;
    sk_sp<SkImageFilter>  fImageFilter;

    SkScalar        fTextSize;
    SkScalar        fTextScaleX;
    SkScalar        fTextSkewX;
    SkColor         fColor;
    SkScalar        fWidth;
    SkScalar        fMiterLimit;
    union {
        struct {
            // all of these bitfields should add up to 32
            unsigned        fFlags : 16;
            unsigned        fTextAlign : 2;
            unsigned        fCapType : 2;
            unsigned        fJoinType : 2;
            unsigned        fStyle : 2;
            unsigned        fTextEncoding : 2;  // 3 values
            unsigned        fHinting : 2;
            unsigned        fFilterQuality : 2;
            //unsigned      fFreeBits : 2;
        } fBitfields;
        uint32_t fBitfieldsUInt;
    };

    static GlyphCacheProc GetGlyphCacheProc(TextEncoding encoding,
                                            bool isDevKern,
                                            bool needFullMetrics);

    SkScalar measure_text(SkGlyphCache*, const char* text, size_t length,
                          int* count, SkRect* bounds) const;

    enum ScalerContextFlags : uint32_t {
        kNone_ScalerContextFlags = 0,

        kFakeGamma_ScalerContextFlag = 1 << 0,
        kBoostContrast_ScalerContextFlag = 1 << 1,

        kFakeGammaAndBoostContrast_ScalerContextFlags =
            kFakeGamma_ScalerContextFlag | kBoostContrast_ScalerContextFlag,
    };

    /*
     * Allocs an SkDescriptor on the heap and return it to the caller as a refcnted
     * SkData.  Caller is responsible for managing the lifetime of this object.
     */
    void getScalerContextDescriptor(SkScalerContextEffects*, SkAutoDescriptor*,
                                    const SkSurfaceProps& surfaceProps,
                                    uint32_t scalerContextFlags, const SkMatrix*) const;

    SkGlyphCache* detachCache(const SkSurfaceProps* surfaceProps, uint32_t scalerContextFlags,
                              const SkMatrix*) const;

    void descriptorProc(const SkSurfaceProps* surfaceProps, uint32_t scalerContextFlags,
                        const SkMatrix* deviceMatrix,
                        void (*proc)(SkTypeface*, const SkScalerContextEffects&,
                                     const SkDescriptor*, void*),
                        void* context) const;

    /*
     * The luminance color is used to determine which Gamma Canonical color to map to.  This is
     * really only used by backends which want to cache glyph masks, and need some way to know if
     * they need to generate new masks based off a given color.
     */
    SkColor computeLuminanceColor() const;

    enum {
        /*  This is the size we use when we ask for a glyph's path. We then
         *  post-transform it as we draw to match the request.
         *  This is done to try to re-use cache entries for the path.
         *
         *  This value is somewhat arbitrary. In theory, it could be 1, since
         *  we store paths as floats. However, we get the path from the font
         *  scaler, and it may represent its paths as fixed-point (or 26.6),
         *  so we shouldn't ask for something too big (might overflow 16.16)
         *  or too small (underflow 26.6).
         *
         *  This value could track kMaxSizeForGlyphCache, assuming the above
         *  constraints, but since we ask for unhinted paths, the two values
         *  need not match per-se.
         */
        kCanonicalTextSizeForPaths  = 64,

        /*
         *  Above this size (taking into account CTM and textSize), we never use
         *  the cache for bits or metrics (we might overflow), so we just ask
         *  for a caononical size and post-transform that.
         */
        kMaxSizeForGlyphCache       = 256,
    };

    static bool TooBigToUseCache(const SkMatrix& ctm, const SkMatrix& textM);

    // Set flags/hinting/textSize up to use for drawing text as paths.
    // Returns scale factor to restore the original textSize, since will will
    // have change it to kCanonicalTextSizeForPaths.
    SkScalar setupForAsPaths();

    static SkScalar MaxCacheSize2() {
        static const SkScalar kMaxSize = SkIntToScalar(kMaxSizeForGlyphCache);
        static const SkScalar kMag2Max = kMaxSize * kMaxSize;
        return kMag2Max;
    }

    friend class SkAutoGlyphCache;
    friend class SkAutoGlyphCacheNoGamma;
    friend class SkCanvas;
    friend class SkDraw;
    friend class SkPDFDevice;
    friend class GrAtlasTextBlob;
    friend class GrAtlasTextContext;
    friend class GrStencilAndCoverTextContext;
    friend class GrPathRendering;
    friend class GrTextUtils;
    friend class GrGLPathRendering;
    friend class SkScalerContext;
    friend class SkTextBaseIter;
    friend class SkCanonicalizePaint;
};

#endif