Shades a surface by how much light it receives — mapping full shadow to one color and full light to another through a referenced color-map — the way to author non-photographic, illustrative lighting instead of physically-fixed shading.
JavaScript API:
Tonemap
This is the concrete member of the AbstractTonemap family: like every
tonemap it turns the lighting parameter (0 = full shadow, 1 = full light) into
a color, so shading is authored rather than physically determined. It supplies
that light-driven t; the ColorMap it names turns t into the pixel
color; and an optional field can restrict where the tonemap applies.
Key attributes. color-map names the color-map to look up — it is
REQUIRED, and a tonemap with no resolvable color-map is inert (renders
nothing). field is an optional applicability mask: where its weight is 1 the
tonemap fully applies, and where its weight is 0 it drops out to the material's
effective base color shaded by light alone (without the color-map), so a field
can fade the illustrative shading in over part of a surface. The color-map's own
field, the tonemap's field, and the base-color compositing are each applied
exactly once — nothing is double-counted.
Driver remap. A tonemap carries its OWN remap-curve that reshapes the
light parameter t BEFORE it reaches the hosted color-map — inverse:linear
flips a screen so light ink grows toward the lit side. This composes with any
remap the color-map itself carries (t_map = mapCurve(driverCurve(t))), so
the two are independent stages: the tonemap's driver remap reshapes what the
color-map is asked to look up, and the color-map's remap reshapes its own
response. Both the curve VALUES and a remap-phase scalar (which slides the
lookup horizontally, remap(wrap(t − phase)), applied after inversion) are
animatable and data-only; remap-phase on the tonemap translates the DRIVER
stage, while remap-phase on the inner color-map translates the MAP stage,
and the two compose.
Related. The color-map it drives is any member of the color-map family —
sk-ramp-color-map (built from sk-color-stop children),
sk-composite-color-map, or a dither map such as
sk-halftone-dither-color-map. A material selects a tonemap with
tonemap="#id" (see sk-plain-material); for a base color that varies by
space rather than by light, its spatial counterpart is the
ColorSource family.
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.
<!-- The SAME dark-red -> gold ramp is driven two ways on two lit spheres.
LEFT: a plain tonemap — the light's terminator reads as a sweep from shadow
(dark red) to light (gold) across the whole surface. RIGHT: the identical
tonemap gated by a spherical field placed ABOVE the sphere, so the
illustrative color is strongest near the top and fades down toward the
bottom, where the surface returns to plainly-lit white. Compare the two to
see what the optional `field` mask does. -->
<sk-scene>
<sk-directional-light p="40deg" h="20deg" intensity="1.0"></sk-directional-light>
<sk-ambient-light intensity="0.35"></sk-ambient-light>
<!-- The shared color-map: shadow reads dark red, light reads gold. -->
<sk-ramp-color-map id="ramp">
<sk-color-stop stop-offset="0" stop-color="darkred"></sk-color-stop>
<sk-color-stop stop-offset="1" stop-color="gold"></sk-color-stop>
</sk-ramp-color-map>
<!-- LEFT: plain tonemap over the whole surface. -->
<sk-tonemap id="tm-plain" color-map="#ramp"></sk-tonemap>
<sk-plain-material id="mat-plain" base-color="white" tonemap="#tm-plain"></sk-plain-material>
<sk-sphere radius="1.6" x="-2.2" segments="6">
<sk-surface-paint material="#mat-plain"></sk-surface-paint>
</sk-sphere>
<!-- RIGHT: the SAME tonemap, gated by a field. A field is a scene node, so
its center is its own position; placing it at the sphere's top pole
(y=1.6) makes the weight fall from ~1 at the top to near 0 at the
bottom, fading the shading top-to-bottom. -->
<sk-spherical-gradient-field id="mask" x="2.2" y="1.6" inner-radius="0.3" outer-radius="3.0"></sk-spherical-gradient-field>
<sk-tonemap id="tm-masked" color-map="#ramp" field="#mask"></sk-tonemap>
<sk-plain-material id="mat-masked" base-color="white" tonemap="#tm-masked"></sk-plain-material>
<sk-sphere radius="1.6" x="2.2" segments="6">
<sk-surface-paint material="#mat-masked"></sk-surface-paint>
</sk-sphere>
</sk-scene>| Attribute | Type | Default | Description |
|---|---|---|---|
remap-curveanimatable |
<remap-curve> |
— | Optional DRIVER remap curve: reshapes the tone value handed to the |
remap-phaseanimatable |
<number> |
0 |
Horizontal driver remap phase — an animatable scalar that translates the |
id |
<id> |
— | The element's unique identifier — the standard HTML global id attribute. |
color-maprequired |
<id-ref> |
— | The referenced color-map, or null when unresolved. Setting it imperatively reference by id |
fieldanimatable |
<id-ref> |
— | Gets the optional field that modulates this tonemap's weight per-fragment. reference by id |