Summary

Add attenuation properties to javafx.scene.PointLight to control its intensity over distance.

Problem

javafx.scene.PointLight lacks attenuation properties to control its intensity over distance. This makes the class inflexible and does not allow realistic scenes to be created.

Solution

Add 3 attenuation properties + 1 range property.

Specification

The following methods are added to javafx.scene.PointLight, in addition to changes to its class documentation:

/**
 * A light source that radiates light equally in all directions away from itself. The location of the light
 * source is a single point in space. Any pixel within the range of the light will be illuminated by it,
 * unless it belongs to a {@code Shape3D} outside of its {@code scope}.
 * <p>
 * The light's intensity can be set to decrease over distance by attenuating it. The attenuation formula
 * <p>
 * {@code attn = 1 / (ca + la * dist + qa * dist^2)}
 * <p>
 * defines 3 coefficients: {@code ca}, {@code la}, and {@code qa}, which control the constant, linear, and
 * quadratic behaviors of intensity falloff over distance, respectively. The effective color of the light
 * at a given point in space is {@code color * attn}. It is possible, albeit unrealistic, to specify negative
 * values to attenuation coefficients. This allows the resulting attenuation factor to be negative, which
 * results in the light's color being subtracted from the material instead of added to it, thus creating a
 * "shadow caster".
 * <p>
 * For a realistic effect, {@code maxRange} should be set to a distance at which the attenuation is close to 0
 * as this will give a soft cutoff.
 *
 * @since JavaFX 8.0
 * @see PhongMaterial
 */
public class PointLight extends LightBase

    /**
     * The maximum range of this {@code PointLight}. For a pixel to be affected by this light, its distance to the
     * light source must be less than or equal to the light's maximum range. Any negative value will be treated as 0.
     * <p>
     * Lower {@code maxRange} values can give better performance as pixels outside the range of the light
     * will not require complex calculation. The attenuation formula can be used to calculate a realistic
     * {@code maxRange} value by finding the distance where the attenuation is close enough to 0.
     * <p>
     * Nodes that are inside the light's range can still be excluded from the light's effect by removing them from
     * its {@link #getScope() scope} (or including them in its {@link #getExclusionScope() exclusion scope}). If a
     * node is known to always be outside of the light's range, it is more performant to exclude it from its scope.
     *
     * @defaultValue {@code Double.POSITIVE_INFINITY}
     * @since 16
     */
    public final DoubleProperty maxRangeProperty()

    public final void setMaxRange(double value)

    public final double getMaxRange()

    /**
     * The constant attenuation coefficient. This is the term {@code ca} in the attenuation formula:
     * <p>
     * {@code attn = 1 / (ca + la * dist + qa * dist^2)}
     * <p>
     * where {@code dist} is the distance between the light source and the pixel.
     *
     * @defaultValue 1
     * @since 16
     */
    public final DoubleProperty constantAttenuationProperty()

    public final void setConstantAttenuation(double value)

    public final double getConstantAttenuation()

    /**
     * The linear attenuation coefficient. This is the term {@code la} in the attenuation formula:
     * <p>
     * {@code attn = 1 / (ca + la * dist + qa * dist^2)}
     * <p>
     * where {@code dist} is the distance between the light source and the pixel.
     *
     * @defaultValue 0
     * @since 16
     */
    public final DoubleProperty linearAttenuationProperty()

    public final void setLinearAttenuation(double value)

    public final double getLinearAttenuation()

    /**
     * The quadratic attenuation coefficient. This is the term {@code qa} in the attenuation formula:
     * <p>
     * {@code attn = 1 / (ca + la * dist + qa * dist^2)}
     * <p>
     * where {@code dist} is the distance between the light source and the pixel.
     *
     * @defaultValue 0
     * @since 16
     */
    public final DoubleProperty quadraticAttenuationProperty()

    public final void setQuadraticAttenuation(double value)

    public final double getQuadraticAttenuation()
}