56.2 Changing color, width, and opacity🔗ℹ

Change appearance without changing the object’s identity.

When target is a Visual value it must implement both gen:visual and gen:stroke-width-visual. When it is a symbol, scene-play checks the resolved Visual while compiling the request. Compilation validates the getter value, calls visual-with-stroke-width with the requested endpoint, requires the result to remain a stroke-width Visual with the same identity, and checks that the endpoint was installed exactly.

Stroke width is its own animation component. It may run simultaneously with translation, rotation, scale, opacity, or path-geometry changes for the same identity. Two overlapping same-target stroke-width requests conflict after schedule expansion; touching requests may chain through a succession or other nonoverlapping schedule.

The numeric interpolation follows the leaf easing like movement and ordinary opacity animation. With an easing whose endpoint is one, the exact requested numeric width is installed at the leaf endpoint even when the starting width or schedule arithmetic is inexact. For custom Visuals, compilation also rejects a setter that changes the exact/inexact representation of that requested endpoint.

The semantic width domain is renderer-independent. The default Pict/racket/draw backend accepts cosmetic pen widths from 0 through 255 pixels and reports a renderer error for larger values. Within that backend, width zero is a device-dependent hairline rather than an instruction to remove the stroke.

Compatible solid colours, linear gradients, radial gradients, and checker patterns interpolate through paint-lerp. At exact progress zero and one, the exact source and destination paint objects are installed. Different paint kinds (or gradients with unequal stop counts) are rejected during scene compilation; use an explicit cross-fade of two Visuals for that change.

Fill color owns the 'fill-color animation component. It may overlap same-target movement, rotation, scaling, opacity, stroke width, stroke color, and path geometry. Overlapping same-target fill-color leaves conflict after schedule expansion; touching leaves are legal.

When target is a Visual value, it must implement both gen:visual and gen:opacity-visual. When it is a symbol, scene-play checks the current Visual with that identity while compiling the request. A missing target or a Visual without valid semantic opacity raises an exception.

The request changes only the opacity component. It preserves identity, position, affine transform, geometry, style, drawing order, and group child order. It may run at the same time as movement, rotation, scaling, or path morphing for the same identity. It conflicts with another same-target request that changes opacity, including fade-in and fade-out.

fade-to does not add or remove the target. Its endpoint follows the easing result, like movement and morphing. An unusual easing procedure that returns zero at the end therefore leaves the starting opacity in place.

This operation is composition syntax rather than a new interpolation primitive. It expands to fill-color-to, stroke-color-to, stroke-width-to, and fade-to leaves for exactly the properties that were supplied. Those leaves share one assigned interval and preserve their existing semantic protocol validation, exact endpoints, easing, and renderer behavior.

Because expansion occurs before scheduler conflict checking, the properties do not collapse into one coarse 'style component. For example, a fill-only style-to may overlap a same-target stroke-width-to or fade-to, while an overlapping fill-color-to conflicts normally on 'fill-color.

When target is a direct Visual, each supplied property’s primitive constructor validates the required optional Visual protocol immediately. A symbolic target defers those same checks until scene-play resolves the target. A #f keyword value means omitted; it is not a request to remove paint. A current #f fill or stroke therefore cannot be color-interpolated.

style-to counts as one direct child for parent composition timing and then expands its primitive leaves in parallel inside the interval it receives. It may be used directly by scene-play, wrapped with timed, or nested inside succession, animation-group, and lagged-start.