RFR: 8332895: Support interpolation for backgrounds and borders [v3]

[Michael Strauß]

On Thu, 4 Jul 2024 19:40:57 GMT, Michael Strauß <mstrauss at openjdk.org> wrote:

>> This PR completes the CSS Transitions story (see #870) by adding interpolation support for backgrounds and borders, making them targetable by transitions.
>> 
>> `Background` and `Border` objects are deeply immutable, but not interpolatable. Consider the following `Background`, which describes the background of a `Region`:
>> 
>> 
>> Background {
>>     fills = [
>>         BackgroundFill {
>>             fill = Color.RED
>>         }
>>     ]
>> }
>> 
>> 
>> Since backgrounds are deeply immutable, changing the region's background to another color requires the construction of a new `Background`, containing a new `BackgroundFill`, containing the new `Color`.
>> 
>> Animating the background color using a CSS transition therefore requires the entire Background object graph to be interpolatable in order to generate intermediate backgrounds.
>> 
>> More specifically, the following types will now implement `Interpolatable`.
>> 
>> - `Insets`
>> - `Background`
>> - `BackgroundFill`
>> - `BackgroundImage`
>> - `BackgroundPosition`
>> - `BackgroundSize`
>> - `Border`
>> - `BorderImage`
>> - `BorderStroke`
>> - `BorderWidths`
>> - `CornerRadii`
>> - `ImagePattern`
>> - `LinearGradient`
>> - `RadialGradient`
>> - `Stop`
>> 
>> ## Interpolation of composite objects
>> 
>> As of now, only `Color`, `Point2D`, and `Point3D` are interpolatable. Each of these classes is an aggregate of `double` values, which are combined using linear interpolation. However, many of the new interpolatable classes comprise of not only `double` values, but a whole range of other types. This requires us to more precisely define what we mean by "interpolation".
>> 
>> Mirroring the CSS specification, the `Interpolatable` interface defines several types of component interpolation:
>> 
>> | Interpolation type | Description |
>> |---|---|
>> | default | Component types that implement `Interpolatable` are interpolated by calling the `interpolate(Object, double)}` method. |
>> | linear | Two components are combined by linear interpolation such that `t = 0` produces the start value, and `t = 1` produces the end value. This interpolation type is usually applicable for numeric components. |
>> | discrete | If two components cannot be meaningfully combined, the intermediate component value is equal to the start value for `t < 0.5` and equal to the end value for `t >= 0.5`. |
>> | pairwise | Two lists are combined by pairwise interpolation. If the start list has fewer elements than the target list, the missing elements are copied from the target li...
>
> Michael Strauß has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 13 additional commits since the last revision:
> 
>  - fix line separators
>  - add documentation to Point2D/3D
>  - change documentation
>  - add specification
>  - add exports
>  - revert change
>  - revert change
>  - added more tests
>  - added specification and tests
>  - Merge branch 'master' into feature/interpolatable
>  - ... and 3 more: https://git.openjdk.org/jfx/compare/60cc590f...08ed751b

modules/javafx.graphics/src/main/java/javafx/scene/paint/Stop.java line 267:

> 265:     public Stop(@NamedArg("offset") double offset, @NamedArg(value="color", defaultValue="BLACK") Color color) {
> 266:         this.offset = offset;
> 267:         this.color = Objects.requireNonNullElse(color, Color.TRANSPARENT);

Note that a `null` color is now treated as `TRANSPARENT` for the following reasons:
1. The previous implementation was broken: if a `Stop` is constructed with a `null` color, the `hashCode()` method throws a NPE because it doesn't check for `null`.
2. It doesn't make sense to have a stop with `null` color. What does it even mean?
3. When the stop list is normalized, an empty or null list is treated as a two-stop list with `TRANSPARENT` color (see `normalize()`). So we already have a scenario where `null` is treated as `TRANSPARENT`.

-------------

PR Review Comment: https://git.openjdk.org/jfx/pull/1471#discussion_r1666040056