SoTimeCounter(3IV)

NAME
     SoTimeCounter - timed integer counter

INHERITS FROM
     SoBase > SoFieldContainer > SoEngine > SoTimeCounter

SYNOPSIS
     #include <Inventor/engines/SoTimeCounter.h>

          Inputs from class SoTimeCounter:

     SoSFTime            timeIn
     SoSFShort           min
     SoSFShort           max
     SoSFShort           step
     SoSFBool            on
     SoSFFloat           frequency
     SoMFFloat           duty
     SoSFShort           reset
     SoSFTrigger         syncIn

          Outputs from class SoTimeCounter:

     (SoSFShort)         output
     (SoSFTrigger)       syncOut

          Methods from class SoTimeCounter:

                         SoTimeCounter()

          Methods from class SoEngine:

     static SoType       getClassTypeId()
     virtual int         getOutputs(SoEngineOutputList &list) const
     SoEngineOutput *    getOutput(const SbName &outputName) const
     SbBool              getOutputName(const SoEngineOutput *output, SbName
                              &outputName) const
     SoEngine *          copy() const
     static SoEngine *   getByName(const SbName &name)
     static int          getByName(const SbName &name, SoEngineList &list)

          Methods from class SoFieldContainer:

     void                setToDefaults()
     SbBool              hasDefaultValues() const
     SbBool              fieldsAreEqual(const SoFieldContainer *fc) const
     void                copyFieldValues(const SoFieldContainer *fc, SbBool
                              copyConnections = FALSE)
     SbBool              set(const char *fieldDataString)
     void                get(SbString &fieldDataString)
     virtual int         getFields(SoFieldList &resultList) const

     virtual SoField *   getField(const SbName &fieldName) const
     SbBool              getFieldName(const SoField *field, SbName &fieldName)
                              const
     SbBool              isNotifyEnabled() const
     SbBool              enableNotify(SbBool flag)

          Methods from class SoBase:

     void                ref()
     void                unref() const
     void                unrefNoDelete() const
     void                touch()
     virtual SoType      getTypeId() const
     SbBool              isOfType(SoType type) const
     virtual void        setName(const SbName &name)
     virtual SbName      getName() const


DESCRIPTION
     This engine is a counter that outputs numbers, starting at a minimum
     value, increasing by a step value, and ending with a number that does not
     exceed the maximum value. When the maximum number is reached, it starts
     counting from the beginning again.

     The difference between this engine and the SoCounter engine, is that this
     engine also has a timeIn input, which allows the counting cycles to be
     timed. This engine counts automatically over time; it does not need to be
     triggered to go to the next step. By default, the timeIn input is
     connected to the realTime global field. It can, however, be connected to
     any time source.

     The frequency input field controls how many min-to-max cycles are
     performed per second. For example, a frequency value of 0.5 means that it
     will take 2 seconds to complete a single min-to-max cycle.

     The steps in the count cycle do not necessarily all have the same
     duration. Using the duty input field, you can arbitrarily split the time
     period of the count cycle between the steps. For example, if there are 5
     steps in the cycle, a duty input of (1., 2., 2., 2., 1.) will make the
     second, third, and fourth steps take twice as long as the first and last
     steps.

     At any time the counter can be reset to a specific value. If you set the
     reset input field to a value, the engine will continue counting from
     there. Note that the counter will always output numbers based on the min,
     max and step values, and setting the reset value does not affect the
     those input fields. If the reset value is not a legal counter value, the
     counter will still behave as though it is:

          If reset is greater than max, the counter is set to max.
          If reset is less than min, the counter is set to min.
          If reset is between step values, the counter is set to the lower step.
     Each time a counting cycle is started, the syncOut output is triggered.
     This output can be used to synchronize some other event with the counting
     cycle. Other events can also synchronize the counter by triggering the
     syncIn input.

     You can pause the engine, by setting the on input to FALSE, and it will
     stop updating the output field. When you turn off the pause, by setting
     on to TRUE, it will start counting again from where it left off.

INPUTS
     SoSFTime            timeIn
          Running time.

     SoSFShort           min
          Minimum value for the counter.

     SoSFShort           max
          Maximum value for the counter.

     SoSFShort           step
          Counter step value.

     SoSFBool            on
          Counter pauses if this is set to FALSE.

     SoSFFloat           frequency
          Number of min-to-max cycles per second.

     SoMFFloat           duty
          Duty cycle values.

     SoSFShort           reset
          Reset the counter to the specified value.

     SoSFTrigger         syncIn
          Restart at the beginning of the cycle.


OUTPUTS
     (SoSFShort)         output
          Counts min-to-max, in step increments.

     (SoSFTrigger)       syncOut
          Triggers at cycle start.


METHODS
                         SoTimeCounter()
          Constructor

FILE FORMAT/DEFAULTS
     TimeCounter {
          min        0
          max        1
          step       1
          on         TRUE
          frequency  1
          duty       1
          timeIn     <current time>
          syncIn
          reset      0
     }

SEE ALSO
     SoCounter, SoElapsedTime, SoEngineOutput