Turns a colour source's brightness into a field weight — the bridge that lets a paper texture or ramp act as a mask for shading and colour.
JavaScript API:
ColorSourceField
This is the texture-driven member of the SpatialField family: like every
field it turns where into how much — a scalar weight that a shader consumer
uses to modulate what it does — but instead of computing weight from geometry, it
reads a ColorSource's relative luminance, so a procedural colour source
becomes a mask. Like any field it is a by-id resource: give it an id, and a
consumer (a sk-tonemap, a colour-map, or a material) points its field at
it with field="#id".
Key attributes. source names the ColorSource to sample by #id.
strength scales the mask around mid-grey (weight = clamp(0.5 + (luma − 0.5) ×
strength, 0, 1)): at 1 a full-range source passes through unchanged, while a
subtle source needs more — the paper texture's ±0.1 swing around mid-grey wants
strength ≈ 3–5 to read. The inherited remap-curve can reshape or invert the
weight. Point the field at the SAME source a material renders (its
base-color-source) and the mask lines up pixel-for-pixel with the visible
texture, so ink density follows the paper's relief rather than an unrelated field.
Supported sources. It samples the parameter-backed colour sources whose
evaluator reads only the params buffer this field forwards — a
sk-paper-texture-color-source, a sk-color-map-source, or a
composite of those. A source that needs its own texture or data buffer (a raster
image, a compute-buffer source) is rejected, because that private resource cannot
be routed into the host consumer's bind group.
GPU-only. The weight needs the source's shader evaluator, so it works only in
the shader-backed field slots — a material, sk-tonemap, or colour-map
field. Evaluated on the CPU (as a sk-field-constraint does) it returns a
neutral weight, so it has no effect there; in a compute-evaluated per-clone point
constraint it is rejected outright. This field masks shading and colour — it does
not drive geometry.
Related. Its source is a sk-paper-texture-color-source or
sk-color-map-source (see ColorSource); its usual consumer is a
sk-tonemap masked by the source's luminance.
Serve these docs to run the live example.
WebGPU needs a secure context — open this page via grunt serve
rather than double-clicking the file. The Markup tab works from disk.
<!-- Two identical tan-paper spheres under the same halftone line-screen. The
difference is the field: RIGHT applies the ink uniformly (no field); LEFT
gates the same tonemap with a color-source-field built from the paper, so
the ink density follows the visible paper relief — heavy in the tooth,
light on the smooth areas. The color-source-field is a by-id resource: give
it an `id`, then point the tonemap's `field` at it. -->
<sk-scene>
<!-- Shared paper texture (the tan grain), halftone screen, and the mask. -->
<sk-paper-texture-color-source id="paper" mottle="6" mottle-scale="164"
tooth="10" tooth-scale="2" fine="4.2" speck="5.4" contrast="1"></sk-paper-texture-color-source>
<sk-color-source-field id="ink-mask" source="#paper" strength="4"></sk-color-source-field>
<sk-halftone-dither-color-map id="screen" shape="circle" min-dot="0.4" softness="0.2"
low-color="rgba(0,0,0,1)" high-color="rgba(0,0,0,0)"></sk-halftone-dither-color-map>
<!-- LEFT: the tonemap is GATED by the color-source-field — ink follows relief. -->
<sk-tonemap id="tm-masked" color-map="#screen" field="#ink-mask"></sk-tonemap>
<sk-plain-material id="mat-masked" base-color="#c9b28c" base-color-source="#paper"
base-color-source-blend-mode="overlay" tonemap="#tm-masked" tonemap-blend-mode="multiply"></sk-plain-material>
<sk-sphere x="-3.4" radius="2.6" segments="5">
<sk-surface-paint material="#mat-masked"></sk-surface-paint>
</sk-sphere>
<!-- RIGHT: the SAME tonemap with NO field — ink applies uniformly. -->
<sk-tonemap id="tm-plain" color-map="#screen"></sk-tonemap>
<sk-plain-material id="mat-plain" base-color="#c9b28c" base-color-source="#paper"
base-color-source-blend-mode="overlay" tonemap="#tm-plain" tonemap-blend-mode="multiply"></sk-plain-material>
<sk-sphere x="3.4" radius="2.6" segments="5">
<sk-surface-paint material="#mat-plain"></sk-surface-paint>
</sk-sphere>
</sk-scene>| Attribute | Type | Default | Description |
|---|---|---|---|
id |
<id> |
— | The element's unique identifier — the standard HTML global id attribute. |
remap-curveanimatable |
<remap-curve> |
— | Optional remapping curve to reshape the field's [0, 1] output. |
remap-phaseanimatable |
<number> |
0 |
Horizontal remap phase — an animatable scalar that translates a present |
source |
<id-ref> |
— | The color source whose luminance drives the weight — an instance, or reference by id |
strengthanimatable |
<number> |
1 |
Gain applied to the sample's deviation from mid-gray. Default 1. |