Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8258983

Add SpotLight to the selection of 3D light types

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: openjfx17
    • Component/s: javafx
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      source
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      All new public API is in a new class, so there should be virtually no compatibility risk.
    • Interface Kind:
      Java API
    • Scope:
      JDK

      Description

      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()
      }

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              nlisker Nir Lisker
              Reporter:
              nlisker Nir Lisker
              Reviewed By:
              Kevin Rushforth
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: