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 SkGradientShader_DEFINED 9#define SkGradientShader_DEFINED 10 11#include "include/core/SkShader.h" 12 13/** \class SkGradientShader 14 15 SkGradientShader hosts factories for creating subclasses of SkShader that 16 render linear and radial gradients. In general, degenerate cases should not 17 produce surprising results, but there are several types of degeneracies: 18 19 * A linear gradient made from the same two points. 20 * A radial gradient with a radius of zero. 21 * A sweep gradient where the start and end angle are the same. 22 * A two point conical gradient where the two centers and the two radii are 23 the same. 24 25 For any degenerate gradient with a decal tile mode, it will draw empty since the interpolating 26 region is zero area and the outer region is discarded by the decal mode. 27 28 For any degenerate gradient with a repeat or mirror tile mode, it will draw a solid color that 29 is the average gradient color, since infinitely many repetitions of the gradients will fill the 30 shape. 31 32 For a clamped gradient, every type is well-defined at the limit except for linear gradients. The 33 radial gradient with zero radius becomes the last color. The sweep gradient draws the sector 34 from 0 to the provided angle with the first color, with a hardstop switching to the last color. 35 When the provided angle is 0, this is just the solid last color again. Similarly, the two point 36 conical gradient becomes a circle filled with the first color, sized to the provided radius, 37 with a hardstop switching to the last color. When the two radii are both zero, this is just the 38 solid last color. 39 40 As a linear gradient approaches the degenerate case, its shader will approach the appearance of 41 two half planes, each filled by the first and last colors of the gradient. The planes will be 42 oriented perpendicular to the vector between the two defining points of the gradient. However, 43 once they become the same point, Skia cannot reconstruct what that expected orientation is. To 44 provide a stable and predictable color in this case, Skia just uses the last color as a solid 45 fill to be similar to many of the other degenerate gradients' behaviors in clamp mode. 46*/ 47class SK_API SkGradientShader { 48public: 49 enum Flags { 50 /** By default gradients will interpolate their colors in unpremul space 51 * and then premultiply each of the results. By setting this flag, the 52 * gradients will premultiply their colors first, and then interpolate 53 * between them. 54 * example: https://fiddle.skia.org/c/@GradientShader_MakeLinear 55 */ 56 kInterpolateColorsInPremul_Flag = 1 << 0, 57 }; 58 59 /** Returns a shader that generates a linear gradient between the two specified points. 60 <p /> 61 @param pts The start and end points for the gradient. 62 @param colors The array[count] of colors, to be distributed between the two points 63 @param pos May be NULL. array[count] of SkScalars, or NULL, of the relative position of 64 each corresponding color in the colors array. If this is NULL, 65 the the colors are distributed evenly between the start and end point. 66 If this is not null, the values must begin with 0, end with 1.0, and 67 intermediate values must be strictly increasing. 68 @param count Must be >=2. The number of colors (and pos if not NULL) entries. 69 @param mode The tiling mode 70 71 example: https://fiddle.skia.org/c/@GradientShader_MakeLinear 72 */ 73 static sk_sp<SkShader> MakeLinear(const SkPoint pts[2], 74 const SkColor colors[], const SkScalar pos[], int count, 75 SkTileMode mode, 76 uint32_t flags, const SkMatrix* localMatrix); 77 static sk_sp<SkShader> MakeLinear(const SkPoint pts[2], 78 const SkColor colors[], const SkScalar pos[], int count, 79 SkTileMode mode) { 80 return MakeLinear(pts, colors, pos, count, mode, 0, nullptr); 81 } 82 83 /** Returns a shader that generates a linear gradient between the two specified points. 84 <p /> 85 @param pts The start and end points for the gradient. 86 @param colors The array[count] of colors, to be distributed between the two points 87 @param pos May be NULL. array[count] of SkScalars, or NULL, of the relative position of 88 each corresponding color in the colors array. If this is NULL, 89 the the colors are distributed evenly between the start and end point. 90 If this is not null, the values must begin with 0, end with 1.0, and 91 intermediate values must be strictly increasing. 92 @param count Must be >=2. The number of colors (and pos if not NULL) entries. 93 @param mode The tiling mode 94 95 example: https://fiddle.skia.org/c/@GradientShader_MakeLinear 96 */ 97 static sk_sp<SkShader> MakeLinear(const SkPoint pts[2], 98 const SkColor4f colors[], sk_sp<SkColorSpace> colorSpace, 99 const SkScalar pos[], int count, SkTileMode mode, 100 uint32_t flags, const SkMatrix* localMatrix); 101 static sk_sp<SkShader> MakeLinear(const SkPoint pts[2], 102 const SkColor4f colors[], sk_sp<SkColorSpace> colorSpace, 103 const SkScalar pos[], int count, SkTileMode mode) { 104 return MakeLinear(pts, colors, std::move(colorSpace), pos, count, mode, 0, nullptr); 105 } 106 107 /** Returns a shader that generates a radial gradient given the center and radius. 108 <p /> 109 @param center The center of the circle for this gradient 110 @param radius Must be positive. The radius of the circle for this gradient 111 @param colors The array[count] of colors, to be distributed between the center and edge of the circle 112 @param pos May be NULL. The array[count] of SkScalars, or NULL, of the relative position of 113 each corresponding color in the colors array. If this is NULL, 114 the the colors are distributed evenly between the center and edge of the circle. 115 If this is not null, the values must begin with 0, end with 1.0, and 116 intermediate values must be strictly increasing. 117 @param count Must be >= 2. The number of colors (and pos if not NULL) entries 118 @param mode The tiling mode 119 */ 120 static sk_sp<SkShader> MakeRadial(const SkPoint& center, SkScalar radius, 121 const SkColor colors[], const SkScalar pos[], int count, 122 SkTileMode mode, 123 uint32_t flags, const SkMatrix* localMatrix); 124 static sk_sp<SkShader> MakeRadial(const SkPoint& center, SkScalar radius, 125 const SkColor colors[], const SkScalar pos[], int count, 126 SkTileMode mode) { 127 return MakeRadial(center, radius, colors, pos, count, mode, 0, nullptr); 128 } 129 130 /** Returns a shader that generates a radial gradient given the center and radius. 131 <p /> 132 @param center The center of the circle for this gradient 133 @param radius Must be positive. The radius of the circle for this gradient 134 @param colors The array[count] of colors, to be distributed between the center and edge of the circle 135 @param pos May be NULL. The array[count] of SkScalars, or NULL, of the relative position of 136 each corresponding color in the colors array. If this is NULL, 137 the the colors are distributed evenly between the center and edge of the circle. 138 If this is not null, the values must begin with 0, end with 1.0, and 139 intermediate values must be strictly increasing. 140 @param count Must be >= 2. The number of colors (and pos if not NULL) entries 141 @param mode The tiling mode 142 */ 143 static sk_sp<SkShader> MakeRadial(const SkPoint& center, SkScalar radius, 144 const SkColor4f colors[], sk_sp<SkColorSpace> colorSpace, 145 const SkScalar pos[], int count, SkTileMode mode, 146 uint32_t flags, const SkMatrix* localMatrix); 147 static sk_sp<SkShader> MakeRadial(const SkPoint& center, SkScalar radius, 148 const SkColor4f colors[], sk_sp<SkColorSpace> colorSpace, 149 const SkScalar pos[], int count, SkTileMode mode) { 150 return MakeRadial(center, radius, colors, std::move(colorSpace), pos, count, mode, 151 0, nullptr); 152 } 153 154 /** 155 * Returns a shader that generates a conical gradient given two circles, or 156 * returns NULL if the inputs are invalid. The gradient interprets the 157 * two circles according to the following HTML spec. 158 * http://dev.w3.org/html5/2dcontext/#dom-context-2d-createradialgradient 159 */ 160 static sk_sp<SkShader> MakeTwoPointConical(const SkPoint& start, SkScalar startRadius, 161 const SkPoint& end, SkScalar endRadius, 162 const SkColor colors[], const SkScalar pos[], 163 int count, SkTileMode mode, 164 uint32_t flags, const SkMatrix* localMatrix); 165 static sk_sp<SkShader> MakeTwoPointConical(const SkPoint& start, SkScalar startRadius, 166 const SkPoint& end, SkScalar endRadius, 167 const SkColor colors[], const SkScalar pos[], 168 int count, SkTileMode mode) { 169 return MakeTwoPointConical(start, startRadius, end, endRadius, colors, pos, count, mode, 170 0, nullptr); 171 } 172 173 /** 174 * Returns a shader that generates a conical gradient given two circles, or 175 * returns NULL if the inputs are invalid. The gradient interprets the 176 * two circles according to the following HTML spec. 177 * http://dev.w3.org/html5/2dcontext/#dom-context-2d-createradialgradient 178 */ 179 static sk_sp<SkShader> MakeTwoPointConical(const SkPoint& start, SkScalar startRadius, 180 const SkPoint& end, SkScalar endRadius, 181 const SkColor4f colors[], 182 sk_sp<SkColorSpace> colorSpace, const SkScalar pos[], 183 int count, SkTileMode mode, 184 uint32_t flags, const SkMatrix* localMatrix); 185 static sk_sp<SkShader> MakeTwoPointConical(const SkPoint& start, SkScalar startRadius, 186 const SkPoint& end, SkScalar endRadius, 187 const SkColor4f colors[], 188 sk_sp<SkColorSpace> colorSpace, const SkScalar pos[], 189 int count, SkTileMode mode) { 190 return MakeTwoPointConical(start, startRadius, end, endRadius, colors, 191 std::move(colorSpace), pos, count, mode, 0, nullptr); 192 } 193 194 /** Returns a shader that generates a sweep gradient given a center. 195 <p /> 196 @param cx The X coordinate of the center of the sweep 197 @param cx The Y coordinate of the center of the sweep 198 @param colors The array[count] of colors, to be distributed around the center, within 199 the gradient angle range. 200 @param pos May be NULL. The array[count] of SkScalars, or NULL, of the relative 201 position of each corresponding color in the colors array. If this is 202 NULL, then the colors are distributed evenly within the angular range. 203 If this is not null, the values must begin with 0, end with 1.0, and 204 intermediate values must be strictly increasing. 205 @param count Must be >= 2. The number of colors (and pos if not NULL) entries 206 @param mode Tiling mode: controls drawing outside of the gradient angular range. 207 @param startAngle Start of the angular range, corresponding to pos == 0. 208 @param endAngle End of the angular range, corresponding to pos == 1. 209 */ 210 static sk_sp<SkShader> MakeSweep(SkScalar cx, SkScalar cy, 211 const SkColor colors[], const SkScalar pos[], int count, 212 SkTileMode mode, 213 SkScalar startAngle, SkScalar endAngle, 214 uint32_t flags, const SkMatrix* localMatrix); 215 static sk_sp<SkShader> MakeSweep(SkScalar cx, SkScalar cy, 216 const SkColor colors[], const SkScalar pos[], int count, 217 uint32_t flags, const SkMatrix* localMatrix) { 218 return MakeSweep(cx, cy, colors, pos, count, SkTileMode::kClamp, 0, 360, flags, 219 localMatrix); 220 } 221 static sk_sp<SkShader> MakeSweep(SkScalar cx, SkScalar cy, 222 const SkColor colors[], const SkScalar pos[], int count) { 223 return MakeSweep(cx, cy, colors, pos, count, 0, nullptr); 224 } 225 226 /** Returns a shader that generates a sweep gradient given a center. 227 <p /> 228 @param cx The X coordinate of the center of the sweep 229 @param cx The Y coordinate of the center of the sweep 230 @param colors The array[count] of colors, to be distributed around the center, within 231 the gradient angle range. 232 @param pos May be NULL. The array[count] of SkScalars, or NULL, of the relative 233 position of each corresponding color in the colors array. If this is 234 NULL, then the colors are distributed evenly within the angular range. 235 If this is not null, the values must begin with 0, end with 1.0, and 236 intermediate values must be strictly increasing. 237 @param count Must be >= 2. The number of colors (and pos if not NULL) entries 238 @param mode Tiling mode: controls drawing outside of the gradient angular range. 239 @param startAngle Start of the angular range, corresponding to pos == 0. 240 @param endAngle End of the angular range, corresponding to pos == 1. 241 */ 242 static sk_sp<SkShader> MakeSweep(SkScalar cx, SkScalar cy, 243 const SkColor4f colors[], sk_sp<SkColorSpace> colorSpace, 244 const SkScalar pos[], int count, 245 SkTileMode mode, 246 SkScalar startAngle, SkScalar endAngle, 247 uint32_t flags, const SkMatrix* localMatrix); 248 static sk_sp<SkShader> MakeSweep(SkScalar cx, SkScalar cy, 249 const SkColor4f colors[], sk_sp<SkColorSpace> colorSpace, 250 const SkScalar pos[], int count, 251 uint32_t flags, const SkMatrix* localMatrix) { 252 return MakeSweep(cx, cy, colors, std::move(colorSpace), pos, count, 253 SkTileMode::kClamp, 0, 360, flags, localMatrix); 254 } 255 static sk_sp<SkShader> MakeSweep(SkScalar cx, SkScalar cy, 256 const SkColor4f colors[], sk_sp<SkColorSpace> colorSpace, 257 const SkScalar pos[], int count) { 258 return MakeSweep(cx, cy, colors, std::move(colorSpace), pos, count, 0, nullptr); 259 } 260 261 static void RegisterFlattenables(); 262}; 263 264#endif 265