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

Add attenuation for PointLight

    Details

    • Type: CSR
    • Status: Provisional
    • Priority: P3
    • Resolution: Unresolved
    • Fix Version/s: openjfx15
    • Component/s: javafx
    • Labels:
      None
    • Subcomponent:
    • Compatibility Risk:
      minimal

      Description

      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 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 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}. 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 13
       */
      private DoubleProperty maxRange;
      
      public final void setMaxRange(double value)
      
      public final double getMaxRange()
      
      public final DoubleProperty maxRangeProperty()
      
      /**
       * 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 13
       */
      private DoubleProperty constantAttenuation;
      
      public final void setConstantAttenuation(double value)
      
      public final double getConstantAttenuation()
      
      public final DoubleProperty constantAttenuationProperty()
      
      /**
       * 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 13
       */
      private DoubleProperty linearAttenuation;
      
      public final void setLinearAttenuation(double value)
      
      public final double getLinearAttenuation()
      
      public final DoubleProperty linearAttenuationProperty()
      
      /**
       * 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 13
       */
      private DoubleProperty quadraticAttenuation;
      
      public final void setQuadraticAttenuation(double value)
      
      public final double getQuadraticAttenuation()
      
      public final DoubleProperty quadraticAttenuationProperty()

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                nlisker Nir Lisker
                Reporter:
                nlisker Nir Lisker
              • Votes:
                0 Vote for this issue
                Watchers:
                3 Start watching this issue

                Dates

                • Created:
                  Updated: