xref: /third_party/skia/include/core/SkShader.h (revision cb93a386) 
1/*
2 * Copyright 2006 The Android Open Source Project
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 SkShader_DEFINED
9#define SkShader_DEFINED
10
11#include "include/core/SkBlendMode.h"
12#include "include/core/SkColor.h"
13#include "include/core/SkFlattenable.h"
14#include "include/core/SkImageInfo.h"
15#include "include/core/SkMatrix.h"
16#include "include/core/SkTileMode.h"
17
18class SkArenaAlloc;
19class SkBitmap;
20class SkBlender;
21class SkColorFilter;
22class SkColorSpace;
23class SkImage;
24class SkPath;
25class SkPicture;
26class SkRasterPipeline;
27class GrFragmentProcessor;
28
29/** \class SkShader
30 *
31 *  Shaders specify the source color(s) for what is being drawn. If a paint
32 *  has no shader, then the paint's color is used. If the paint has a
33 *  shader, then the shader's color(s) are use instead, but they are
34 *  modulated by the paint's alpha. This makes it easy to create a shader
35 *  once (e.g. bitmap tiling or gradient) and then change its transparency
36 *  w/o having to modify the original shader... only the paint's alpha needs
37 *  to be modified.
38 */
39class SK_API SkShader : public SkFlattenable {
40public:
41    /**
42     *  Returns true if the shader is guaranteed to produce only opaque
43     *  colors, subject to the SkPaint using the shader to apply an opaque
44     *  alpha value. Subclasses should override this to allow some
45     *  optimizations.
46     */
47    virtual bool isOpaque() const { return false; }
48
49    /**
50     *  Iff this shader is backed by a single SkImage, return its ptr (the caller must ref this
51     *  if they want to keep it longer than the lifetime of the shader). If not, return nullptr.
52     */
53    SkImage* isAImage(SkMatrix* localMatrix, SkTileMode xy[2]) const;
54
55    bool isAImage() const {
56        return this->isAImage(nullptr, (SkTileMode*)nullptr) != nullptr;
57    }
58
59    /**
60     *  If the shader subclass can be represented as a gradient, asAGradient
61     *  returns the matching GradientType enum (or kNone_GradientType if it
62     *  cannot). Also, if info is not null, asAGradient populates info with
63     *  the relevant (see below) parameters for the gradient.  fColorCount
64     *  is both an input and output parameter.  On input, it indicates how
65     *  many entries in fColors and fColorOffsets can be used, if they are
66     *  non-NULL.  After asAGradient has run, fColorCount indicates how
67     *  many color-offset pairs there are in the gradient.  If there is
68     *  insufficient space to store all of the color-offset pairs, fColors
69     *  and fColorOffsets will not be altered.  fColorOffsets specifies
70     *  where on the range of 0 to 1 to transition to the given color.
71     *  The meaning of fPoint and fRadius is dependant on the type of gradient.
72     *
73     *  None:
74     *      info is ignored.
75     *  Color:
76     *      fColorOffsets[0] is meaningless.
77     *  Linear:
78     *      fPoint[0] and fPoint[1] are the end-points of the gradient
79     *  Radial:
80     *      fPoint[0] and fRadius[0] are the center and radius
81     *  Conical:
82     *      fPoint[0] and fRadius[0] are the center and radius of the 1st circle
83     *      fPoint[1] and fRadius[1] are the center and radius of the 2nd circle
84     *  Sweep:
85     *      fPoint[0] is the center of the sweep.
86     */
87
88    enum GradientType {
89        kNone_GradientType,
90        kColor_GradientType,
91        kLinear_GradientType,
92        kRadial_GradientType,
93        kSweep_GradientType,
94        kConical_GradientType,
95        kLast_GradientType = kConical_GradientType,
96    };
97
98    struct GradientInfo {
99        int         fColorCount;    //!< In-out parameter, specifies passed size
100                                    //   of fColors/fColorOffsets on input, and
101                                    //   actual number of colors/offsets on
102                                    //   output.
103        SkColor*    fColors;        //!< The colors in the gradient.
104        SkScalar*   fColorOffsets;  //!< The unit offset for color transitions.
105        SkPoint     fPoint[2];      //!< Type specific, see above.
106        SkScalar    fRadius[2];     //!< Type specific, see above.
107        SkTileMode  fTileMode;
108        uint32_t    fGradientFlags; //!< see SkGradientShader::Flags
109    };
110
111    // DEPRECATED. skbug.com/8941
112    virtual GradientType asAGradient(GradientInfo* info) const;
113
114    //////////////////////////////////////////////////////////////////////////
115    //  Methods to create combinations or variants of shaders
116
117    /**
118     *  Return a shader that will apply the specified localMatrix to this shader.
119     *  The specified matrix will be applied before any matrix associated with this shader.
120     */
121    sk_sp<SkShader> makeWithLocalMatrix(const SkMatrix&) const;
122
123    /**
124     *  Create a new shader that produces the same colors as invoking this shader and then applying
125     *  the colorfilter.
126     */
127    sk_sp<SkShader> makeWithColorFilter(sk_sp<SkColorFilter>) const;
128
129private:
130    SkShader() = default;
131    friend class SkShaderBase;
132
133    using INHERITED = SkFlattenable;
134};
135
136class SK_API SkShaders {
137public:
138    static sk_sp<SkShader> Empty();
139    static sk_sp<SkShader> Color(SkColor);
140    static sk_sp<SkShader> Color(const SkColor4f&, sk_sp<SkColorSpace>);
141    static sk_sp<SkShader> Blend(SkBlendMode mode, sk_sp<SkShader> dst, sk_sp<SkShader> src);
142    static sk_sp<SkShader> Blend(sk_sp<SkBlender>, sk_sp<SkShader> dst, sk_sp<SkShader> src);
143
144private:
145    SkShaders() = delete;
146};
147
148#endif
149