kitepdf-core/io.github.yuroyami.kitepdf.core.render/KiteShading

KiteShading

A PDF shading (ISO 32000-1 §8.7.4). Shadings define smooth color transitions used as fills via the sh content-stream operator or via a shading pattern referenced by SCN/scn.

KitePDF renders:

Type 1 function-based: a colour function over a 2D domain, rasterized as a grid of cells
Type 2 axial: a linear gradient between two points
Type 3 radial: a radial gradient between two circles
Types 4/5 Gouraud triangle meshes: the colour is interpolated across each triangle
Types 6/7 Coons and tensor-product patches: the exact tensor-product surface, split into small triangles in device space

Types 1/4/5/6/7 render through paintComplexShading, shared by every backend: type 1 as a grid of fillPath cells, and a mesh as one image drawn with drawImage. Types 2/3 keep the backends' native gradient brushes. Unparseable shadings become Unsupported and paint nothing.

Inheritors

Types

Axial

data class Axial(val colorSpace: KiteColorSpace, val background: RgbColor?, val bbox: KiteRectangle?, val coords: DoubleArray, val domain: DoubleArray, val function: KiteFunction, val extendStart: Boolean, val extendEnd: Boolean) : KiteShading

Type 2 axial shading. Linear gradient between (x0, y0) and (x1, y1) with t running across domain. function supplies a colour per t value; we sample it at a fixed number of stops and hand those to the backend.

Companion

object Companion

FunctionBased

class FunctionBased(val colorSpace: KiteColorSpace, val background: RgbColor?, val bbox: KiteRectangle?, val domain: DoubleArray, val matrix: KiteMatrix, function: KiteFunction) : KiteShading

Type 1: colour as a function of (x, y) over domain (x0 x1 y0 y1), mapped into user space by matrix. Rendered as a grid of coloured cells by paintComplexShading.

MeshColorTable

class MeshColorTable(val t0: Double, val t1: Double, val colors: Array<RgbColor>)

The colours of the parametric value t in a mesh with a /Function: the function sampled at 256 even steps from t0 to t1, the /Decode range of t, as MuPDF samples it. A point of the mesh interpolates t first and then looks its colour up here.

MeshPatch

class MeshPatch(val x: DoubleArray, val y: DoubleArray, val colors: Array<RgbColor>, val t: DoubleArray? = null)

One patch of a type 6 or 7 mesh as a tensor-product surface (ISO 32000-1, 8.7.4.5.8). x and y hold the 16 control points in shading space, p(i, j) at index 4 i + j, and colors the colours of the corners p(0,0), p(0,3), p(3,3) and p(3,0). A Coons patch of type 6 gets its 4 interior points from its boundary, by the equations of 8.7.4.5.8, and the tensor-product surface of those points is the Coons surface.

MeshTriangle

class MeshTriangle(val x: DoubleArray, val y: DoubleArray, val colors: Array<RgbColor>, val t: DoubleArray? = null)

One Gouraud triangle: three shading-space vertices with colours. In a mesh with a /Function, t holds the parametric value of each vertex. A point inside the triangle then takes its colour from the interpolated t, not from the interpolated colors (ISO 32000-1, 8.7.4.5.5).

PatchMesh

class PatchMesh(val colorSpace: KiteColorSpace, val background: RgbColor?, val bbox: KiteRectangle?, val patches: List<KiteShading.MeshPatch>, val colorTable: KiteShading.MeshColorTable? = null) : KiteShading

Types 6/7: a mesh of Coons or tensor-product patches (ISO 32000-1, 8.7.4.5.7 and 8.7.4.5.8).

Radial

data class Radial(val colorSpace: KiteColorSpace, val background: RgbColor?, val bbox: KiteRectangle?, val coords: DoubleArray, val domain: DoubleArray, val function: KiteFunction, val extendStart: Boolean, val extendEnd: Boolean) : KiteShading

Type 3 radial shading. Gradient between two circles: (x0, y0, r0) and (x1, y1, r1) with t running across domain.

TriangleMesh

class TriangleMesh(val colorSpace: KiteColorSpace, val background: RgbColor?, val bbox: KiteRectangle?, val triangles: List<KiteShading.MeshTriangle>, val colorTable: KiteShading.MeshColorTable? = null) : KiteShading

Types 4/5: a triangle mesh with per-vertex colours (ISO 32000-1, 8.7.4.5.5 and 8.7.4.5.6).

Unsupported

data class Unsupported(val type: Int, val colorSpace: KiteColorSpace, val background: RgbColor?, val bbox: KiteRectangle?) : KiteShading

Shading type we don't render; sampleStops returns null, so nothing paints.

Properties

background

abstract val background: RgbColor?

Optional /Background colour, used for regions outside the shading domain when Extend is false on the relevant side. Per spec the background is in colorSpace; we eager-convert to RGB.

bbox

abstract val bbox: KiteRectangle?

Optional clipping rectangle (/BBox) in shading-space.

colorSpace

abstract val colorSpace: KiteColorSpace

The shading's colour space (DeviceGray / DeviceRGB / DeviceCMYK / Indexed).

Functions

sampleStops

fun KiteShading.sampleStops(count: Int = 256): GradientStops?

Sample a KiteShading.Axial or KiteShading.Radial at evenly-spaced stops between domain[0] and domain[1]. Returns parallel t and RGB arrays the backend uses to build a gradient brush. The default of 256 matches MuPDF, so a function with many narrow bands keeps them all (#153).

spreadOver

fun KiteShading.spreadOver(spread: KiteGradientSpread, region: KiteRectangle): KiteShading

This axial or radial shading continued past its ends by spread, over a region whose bounds in shading space are region. The result is an ordinary shading that every canvas paints: its geometry grows to cover the region, and a stitching function (ISO 32000-1, 7.10.4) repeats or mirrors the colours once per period.