README.md
1 Gradients on the GPU 2 ==================== 3 4 Gradients can be thought of, at a very high level, as three pieces: 5 6 1. A color interpolator that is one dimensional, returning a color for an input 7 within the range [0.0, 1.0]. This obfuscates the the definition of specific 8 color stops and how to wrap, tile, or clamp out of bound inputs. A color 9 interpolator will be named GrYGradientColorizer 10 2. A layout that converts from 2D geometry/position to the one dimensional 11 domain of the color interpolator. This is how a linear or radial gradient 12 distinguishes itself. When designing a new gradient, this is the component 13 that you have to implement. A layout will generally be named 14 GrXGradientLayout 15 3. A master effect that composes the layout and color interpolator together. It 16 is also responsible for implementing the clamping behavior that can be 17 abstracted away from both the layout and colorization. 18 19 20 GrClampedGradientEffect handles clamped and decal tile modes, while 21 GrTiledGradientEffect implements repeat and mirror tile modes. The 22 GrClampedGradientEffect requires border colors to be specified outside of its 23 colorizer child, but these border colors may be defined by the gradient color 24 stops. Both of these master effects delegate calculating a t interpolant to a 25 child process, perform their respective tile mode operations, and possibly 26 convert the tiled t value (guaranteed to be within 0 and 1) into an output 27 color using their child colorizer process. 28 29 Because of how child processors are currently defined, where they have a single 30 half4 input and a single half4 output, their is a type mismatch between the 1D 31 t value and the 4D inputs/outputs of the layout and colorizer processes. For 32 now, the master effect assumes an untiled t is output in sk_OutColor.x by the 33 layout and it tiles solely off of that value. 34 35 However, layouts can output a negative value in the y component to invalidate 36 the gradient location (currently on the two point conical gradient does this). 37 When invalidated, the master effect outputs transparent black and does not 38 invoke the child processor. Other than this condition, any value in y, z, or w 39 are passed into the colorizer unmodified. The colorizer should assume that the 40 valid tiled t value is in sk_InColor.x and can safely ignore y, z, and w. 41 42 Currently there are color interpolators (colorizers) for analytic color cases 43 (evaluated directly on the GPU) and sampling a generated texture map. 44 45 GrGradientShader provides static factory functions to create 46 GrFragmentProcessor graphs that reproduce a particular SkGradientShader. 47 48 Optimization Flags 49 ================== 50 51 At an abstract level, gradient shaders are compatible with coverage as alpha 52 and, under certain conditions, preserve opacity when the inputs are opaque. To 53 reduce the amount of duplicate code and boilerplate, these optimization 54 decisions are implemented in the master effects and not in the colorizers. It 55 is assumed that all colorizer FPs will be compatible with coverage as alpha and 56 will preserve opacity if input colors are opaque. Since this is assumed by the 57 master effects, they do not need to report these optimizations or check input 58 opacity (this does mean if the colorizers are used independently from the 59 master effect shader that the reported flags might not be optimal, but since 60 that is unlikely, this convention really simplifies the colorizer 61 implementations). 62 63 Unlike colorizers, which do not need to report any optimization flags, layout 64 FPs should report opacity preserving optimizations because they can impact the 65 opacity of a pixel outside of how the gradient would otherwise color it. 66 Layouts that potentially reject pixels (i.e. could output a negative y value) 67 must not report kPreservesOpaqueInput_OptimizationFlag. Layouts that never 68 reject a pixel should report kPreservesOpaqueInput_OptimizationFlag since the 69 master effects can optimize away checking if the layout rejects a pixel. 70 71 72
