Package jmri

Interface VariableLight

All Superinterfaces:
AnalogIO, Comparable<NamedBean>, DigitalIO, Light, NamedBean, PropertyChangeProvider
All Known Implementing Classes:
AbstractVariableLight, AnymaDMX_UsbLight, BiDiBLight, MqttLight, SerialLight, SerialX10Light, SpecificDmxLight, SpecificInsteonLight, SpecificInsteonLight, SpecificLight, SpecificLight, SpecificLight, SpecificX10Light, SpecificX10Light
public interface VariableLight extends Light, AnalogIO
Represent a single visible Variable Light on the physical layout.

Each Light may have one or more control mechanisms. Control mechanism types are defined here. If a Light has any controls, the information is contained in LightControl objects, which are referenced via that Light.

Lights have a state and an intensity.

The intensity of the hardware output is represented by the range from 0.0 to 1.0, with 1.0 being brightest.

The primary states are:

  • ON, corresponding to maximum intensity
  • INTERMEDIATE, some value between maximum and minimum
  • OFF, corresponding to minimum intensity
The underlying hardware may provide just the ON/OFF two levels, or have a semi-continuous intensity setting with some number of steps.

The light has a TargetIntensity property which can be set directly. In addition, it has a CurrentIntensity property which may differ from TargetIntensity while the Light is being moved from one intensity to another.

Intensity is limited by MinIntensity and MaxIntensity parameters. Setting the state to ON sets the TargetIntensity to MinIntensity, and to OFF sets the TargetIntensity to MaxIntensity. Attempting to directly set the TargetIntensity outside the values of MinIntensity and MaxIntensity (inclusive) will result in the TargetIntensity being set to the relevant limit.

Because the actual light hardware has only finite resolution, the intensity value is mapped to the nearest setting. For example, in the special case of a two-state (on/off) Light, setting a TargetIntensity of more than 0.5 will turn the Light on, less than 0.5 will turn the light off.

Specific implementations will describe how the settings map to the particular hardware commands.

The transition rate is absolute; the intensity changes at a constant rate regardless of whether the change is a big one or a small one.

This file is part of JMRI.

JMRI is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation. See the "COPYING" file for a copy of this license.

JMRI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

  • Field Details

  • Method Details

    • requestUpdateFromLayout

      @InvokeOnLayoutThread default void requestUpdateFromLayout()
      Request an update from the layout soft/hardware. May not even happen, and if it does it will happen later; listen for the result.
      Specified by:
      requestUpdateFromLayout in interface AnalogIO
      Specified by:
      requestUpdateFromLayout in interface DigitalIO
      Specified by:
      requestUpdateFromLayout in interface Light

    • isConsistentState

      default boolean isConsistentState()
      Show whether state is stable. For turnouts, a consistent state is one you can safely run trains over. For lights, it's a state which is either on or off, not in between.
      Specified by:
      isConsistentState in interface DigitalIO
      Specified by:
      isConsistentState in interface Light
      Returns:
      true if state is valid and the known state is the same as commanded

    • isConsistentValue

      default boolean isConsistentValue()
      Show whether the analog value is stable.
      Specified by:
      isConsistentValue in interface AnalogIO
      Returns:
      true if the analog value is stable

    • setTargetIntensity

      @InvokeOnLayoutThread void setTargetIntensity(double intensity)
      Set the intended new intensity value for the Light. If transitions are in use, they will be applied.

      Bound property between 0 and 1.

      A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.

      Attempting to set a value below the MinIntensity property value will result in MinIntensity being set. Similarly, setting a value above MaxIntensity will result in MaxINtensity being set.

      Setting the intensity to the value of the MinIntensity property will result in the Light going to the OFF state at the end of the transition. Similarly, setting the intensity to the MaxIntensity value will result in the Light going to the ON state at the end of the transition.

      All others result in the INTERMEDIATE state.

      Light implementations with isIntensityVariable false may not have their TargetIntensity set to values between MinIntensity and MaxIntensity, which would result in the INTERMEDIATE state, as that is invalid for them.

      If a non-zero value is set in the transitionTime property, the state will be one of TRANSITIONTOFULLON, TRANSITIONHIGHER, TRANSITIONLOWER or TRANSITIONTOFULLOFF until the transition is complete.

      Parameters:
      intensity - the desired brightness
      Throws:
      IllegalArgumentException - when intensity is less than 0.0 or more than 1.0
      IllegalArgumentException - if isIntensityVariable is false and the new value is between MaxIntensity and MinIntensity

    • getCurrentIntensity

      double getCurrentIntensity()
      Get the current intensity value. If the Light is currently transitioning, this may be either an intermediate or final value.

      A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.

      Returns:
      the current brightness

    • getTargetIntensity

      double getTargetIntensity()
      Get the target intensity value for the current transition, if any. If the Light is not currently transitioning, this is the current intensity value.

      A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.

      Bound property

      Returns:
      the desired brightness

    • setMaxIntensity

      @InvokeOnLayoutThread void setMaxIntensity(double intensity)
      Set the value of the maxIntensity property.

      Bound property between 0 and 1.

      A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.

      Parameters:
      intensity - the maximum brightness
      Throws:
      IllegalArgumentException - when intensity is less than 0.0 or more than 1.0
      IllegalArgumentException - when intensity is not greater than the current value of the minIntensity property

    • getMaxIntensity

      double getMaxIntensity()
      Get the current value of the maxIntensity property.

      A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.

      Returns:
      the maximum brightness

    • setMinIntensity

      @InvokeOnLayoutThread void setMinIntensity(double intensity)
      Set the value of the minIntensity property.

      Bound property between 0 and 1.

      A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.

      Parameters:
      intensity - the minimum brightness
      Throws:
      IllegalArgumentException - when intensity is less than 0.0 or more than 1.0
      IllegalArgumentException - when intensity is not less than the current value of the maxIntensity property

    • getMinIntensity

      double getMinIntensity()
      Get the current value of the minIntensity property.

      A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.

      Returns:
      the minimum brightness

    • isTransitionAvailable

      boolean isTransitionAvailable()
      Can the Light change its intensity setting slowly?

      If true, this Light supports a non-zero value of the transitionTime property, which controls how long the Light will take to change from one intensity level to another.

      Unbound property

      Returns:
      true if brightness can fade between two states; false otherwise

    • setTransitionTime

      @InvokeOnLayoutThread void setTransitionTime(double minutes)
      Set the fast-clock duration for a transition from full ON to full OFF or vice-versa.

      Note there is no guarantee of how this scales when other changes in intensity take place. In particular, some Light implementations will change at a constant fraction per fastclock minute and some will take a fixed duration regardless of the size of the intensity change.

      Bound property

      Parameters:
      minutes - time to fade
      Throws:
      IllegalArgumentException - if isTransitionAvailable() is false and minutes is not 0.0
      IllegalArgumentException - if minutes is negative

    • getTransitionTime

      double getTransitionTime()
      Get the number of fastclock minutes taken by a transition from full ON to full OFF or vice versa.
      Returns:
      0.0 if the output intensity transition is instantaneous

    • isTransitioning

      boolean isTransitioning()
      Convenience method for checking if the intensity of the light is currently changing due to a transition.

      Bound property so that listeners can conveniently learn when the transition is over.

      Returns:
      true if light is between two states; false otherwise