Summary

Add a SpotLight to the JavaFX 3D API.

Problem

JavaFX contains only an AmbientLight and a PointLight. A SpotLight is a common light that isn't provided by JavaFX currently.

Solution

Add a SpotLight implementation.

Specification

/**
 * A {@code SpotLight} is a {@code PointLight} that radiates light in a cone in a specific direction.
 * The direction is defined by the {@link #directionProperty() direction} vector property of the light. The direction
 * can be rotated by setting a rotation transform on the {@code SpotLight}. For example, if the direction vector is
 * {@code (1, 1, 1)} and the light is not rotated, it will point in the {@code (1, 1, 1)} direction, and if the light is
 * rotated 90 degrees on the y axis, it will point in the {@code (1, 1, -1)} direction.
 * <p>
 * In addition to the factors that control the light intensity of a {@code PointLight}, a {@code SpotLight} has a
 * light-cone attenuation factor, {@code spot}, that is determined by 3 properties:
 * <ul>
 * <li> {@link #innerAngleProperty() innerAngle}: the angle of the inner cone (see image below)
 * <li> {@link #outerAngleProperty() outerAngle}: the angle of the outer cone (see image below)
 * <li> {@link #falloffProperty() falloff}: the factor that controls the light's intensity drop inside the outer cone
 * </ul>
 * The valid ranges for these properties are {@code 0 <= innerAngle <= outerAngle <= 180} and {@code falloff >= 0};
 * values outside either of these ranges can produce unexpected results.
 * <p>
 * The angle of a point to the light is defined as the angle between its vector to the light's position and the
 * direction of the light. For such an angle {@code theta}, if
 * <ul>
 * <li>{@code theta < innerAngle} then {@code spot = 1}
 * <li>{@code theta > outerAngle} then {@code spot = 0}
 * <li>{@code innerAngle <= theta <= outerAngle} then
 *
 * <pre>spot = pow((cos(theta) - cos(outer)) / (cos(inner) - cos(outer)), falloff)</pre>
 *
 * which represents a drop in intensity from the inner angle to the outer angle.
 * </ul>
 * As a result, {@code 0 <= spot <= 1}. The overall intensity of the light is {@code I = lambert * atten * spot}.
 * <p>
 * <img src="doc-files/spotlight.png" alt="Image of the Spotlight">
 *
 * @since 17
 * @see PhongMaterial
 */
public class SpotLight extends PointLight {

    /**
     * Creates a new instance of {@code SpotLight} class with a default {@code Color.WHITE} light source.
     */
    public SpotLight()

    /**
     * Creates a new instance of {@code SpotLight} class using the specified color.
     *
     * @param color the color of the light source
     */
    public SpotLight(Color color)


    /**
     * The direction vector of the spotlight. It can be rotated by setting a rotation transform on the
     * {@code SpotLight}. The vector need not be normalized.
     *
     * @defaultValue {@code Point3D(0, 0, 1)}
     */
    public final ObjectProperty<Point3D> directionProperty()

    public final void setDirection(Point3D value)

    public final Point3D getDirection()


    /**
     * The angle of the spotlight's inner cone, in degrees. A point whose angle to the light is less than this angle is
     * not attenuated by the spotlight factor ({@code spot = 1}). At larger angles, the light intensity starts to drop.
     * See the class doc for more information.
     * <p>
     * The valid range is {@code 0 <= innerAngle <= outerAngle}; values outside of this range can produce unexpected
     * results.
     *
     * @defaultValue 0
     */
    public final DoubleProperty innerAngleProperty()

    public final void setInnerAngle(double value)

    public final double getInnerAngle()


    /**
     * The angle of the spotlight's outer cone, in degrees (as shown in the class doc image). A point whose angle to the
     * light is greater than this angle receives no light ({@code spot = 0}). A point whose angle to the light is less
     * than the outer angle but greater than the inner angle receives partial intensity governed by the falloff factor.
     * See the class doc for more information.
     * <p>
     * The valid range is {@code innerAngle <= outerAngle <= 180}; values outside of this range can produce unexpected
     * results.
     *
     * @defaultValue 30
     */
    public final DoubleProperty outerAngleProperty()

    public final void setOuterAngle(double value)

    public final double getOuterAngle()


    /**
     * The intensity falloff factor of the spotlight's outer cone. A point whose angle to the light is
     * greater than the inner angle but less than the outer angle receives partial intensity governed by this factor.
     * The larger the falloff, the sharper the drop in intensity from the inner cone. A falloff factor of 1 gives a
     * linear drop in intensity, values greater than 1 give a convex drop, and values smaller than 1 give a concave
     * drop. See the class doc for more information.
     * <p>
     * The valid range is {@code 0 <= falloff}; values outside of this range can produce unexpected results.
     *
     * @defaultValue 1
     */
    public final DoubleProperty falloffProperty()

    public final void setFalloff(double value)

    public final double getFalloff()
}