tree: 0993437bfc5557e9e1ff37c508c209a6e031ecf4 [path history] [tgz]
  1. GrGradientBitmapCache.cpp
  2. GrGradientBitmapCache.h
  3. GrGradientShader.cpp
  4. GrGradientShader.h
  5. README.md
src/gpu/gradients/README.md

Gradients on the GPU

Gradients can be thought of, at a very high level, as three pieces:

  1. A color interpolator ("colorizer") that is one dimensional, returning a color for an interpolant value "t" within the range [0.0, 1.0]. This encapsulates the definition of specific color stops and how to wrap, tile, or clamp out of bound inputs. A color interpolator will be named GrXxxxxGradientColorizer.
  2. A layout that converts from 2D geometry/position to the one dimensional domain of the color interpolator. This is how a linear or radial gradient distinguishes itself. When designing a new gradient shape, this is the component that will need to be implemented. A layout will generally be named GrYyyyyGradientLayout.
  3. A top-level effect that composes the layout and color interpolator together. This processor is also responsible for implementing the clamping behavior, which is abstracted away from both the layout and colorization.

GrClampedGradientEffect handles clamped and decal tile modes, while GrTiledGradientEffect implements repeat and mirror tile modes. The GrClampedGradientEffect requires border colors to be specified outside of its colorizer child, but these border colors may be defined by the gradient color stops. Both of these top-level effects delegate calculating the t interpolant to the layout child processor, then perform their respective tile mode operations, and finally convert the tiled t value (guaranteed to be within 0 and 1) into an output color using the colorizer child processor.

Fragment processors only support returning colors; conceptually, however, layout processors need to generate an interpolant, not a color. So the layout processor encodes its result into a color as follows:

  • sk_OutColor.r: computed t interpolant [0.0, 1.0], untiled
  • sk_OutColor.g: Positive value = render, negative value = discard pixel.
  • sk_OutColor.b: unused
  • sk_OutColor.a: unused

Layouts can report "invalid gradient location" by outputting a negative value into the sk_OutColor.g component. (Currently, the two-point conical gradient does this.) When this happens, the top-level effect immediately returns transparent black and does not invoke the colorizer at all. When the gradient location is valid, the top-level effect samples from the colorizer at the explicit coordinate (t, 0). The y coordinate will always be zero and can be ignored by the colorizer.

There are several hand-written colorizers for analytic color cases; these are evaluated directly in the shader. Generated texture maps can also be used to colorize a gradient; in this case, a GrTextureEffect will be used as the colorizer.

GrGradientShader provides static factory functions to create GrFragmentProcessor graphs that reproduce a particular SkGradientShader.

Optimization Flags

At an abstract level, gradient shaders are compatible with coverage as alpha and, under certain conditions, preserve opacity when the inputs are opaque. To reduce the amount of duplicate code and boilerplate, these optimization decisions are implemented in the top-level effects and not in the colorizers. It is assumed that all colorizer FPs will be compatible with coverage as alpha and will preserve opacity if input colors are opaque. Since this is assumed by the top-level effects, they do not need to report these optimizations or check input opacity (this does mean if the colorizers are used independently from the top-level effect shader that the reported flags might not be optimal, but since that is unlikely, this convention really simplifies the colorizer implementations).

Unlike colorizers, which do not need to report any optimization flags, layout FPs should report opacity preserving optimizations because they can impact the opacity of a pixel outside of how the gradient would otherwise color it. Layouts that potentially reject pixels (i.e. could output a negative y value) must not report kPreservesOpaqueInput_OptimizationFlag. Layouts that never reject a pixel should report kPreservesOpaqueInput_OptimizationFlag since the top-level effects can optimize away checking if the layout rejects a pixel.