Event.h

Go to the documentation of this file.

#ifndef SimTK_SimTKCOMMON_EVENT_H_
#define SimTK_SimTKCOMMON_EVENT_H_

/* -------------------------------------------------------------------------- *
 *                      SimTK Core: SimTKcommon                               *
 * -------------------------------------------------------------------------- *
 * This is part of the SimTK Core biosimulation toolkit originating from      *
 * Simbios, the NIH National Center for Physics-Based Simulation of           *
 * Biological Structures at Stanford, funded under the NIH Roadmap for        *
 * Medical Research, grant U54 GM072970. See https://simtk.org.               *
 *                                                                            *
 * Portions copyright (c) 2008-9 Stanford University and the Authors.         *
 * Authors: Michael Sherman                                                   *
 * Contributors:                                                              *
 *                                                                            *
 * Permission is hereby granted, free of charge, to any person obtaining a    *
 * copy of this software and associated documentation files (the "Software"), *
 * to deal in the Software without restriction, including without limitation  *
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,   *
 * and/or sell copies of the Software, and to permit persons to whom the      *
 * Software is furnished to do so, subject to the following conditions:       *
 *                                                                            *
 * The above copyright notice and this permission notice shall be included in *
 * all copies or substantial portions of the Software.                        *
 *                                                                            *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR *
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,   *
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL    *
 * THE AUTHORS, CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,    *
 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR      *
 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE  *
 * USE OR OTHER DEALINGS IN THE SOFTWARE.                                     *
 * -------------------------------------------------------------------------- */

#include "SimTKcommon/basics.h"

namespace SimTK {

SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemEventIndex);
SimTK_DEFINE_UNIQUE_INDEX_TYPE(EventIndex);

SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemEventTriggerIndex);
SimTK_DEFINE_UNIQUE_INDEX_TYPE(EventTriggerIndex);

SimTK_DEFINE_UNIQUE_INDEX_TYPE(SystemEventTriggerByStageIndex);
SimTK_DEFINE_UNIQUE_INDEX_TYPE(EventTriggerByStageIndex);

class Event {
public:

    class Cause {
    public:
        enum Num {
            Initialization  = 1,
            Triggered       = 2,
            Scheduled       = 3,
            TimeAdvanced    = 4,
            Signaled        = 5,
            Termination     = 6,
            Invalid         = -1
        };

        Cause() : value(Invalid) {}
        Cause(Num n) : value(n) {}           // implicit conversion
        operator Num() const {return value;} // implicit conversion
        Cause& operator=(Num n) {value=n; return *this;}

        bool isValid() const {return Initialization<=value && value<=Termination;}

    private:
        Num value;
    };

    SimTK_SimTKCOMMON_EXPORT static const char* getCauseName(Cause);


    enum Trigger {
        NoEventTrigger          =0x0000,    // must be 0

        PositiveToNegative      =0x0001,    // 1
        NegativeToPositive      =0x0002,    // 2

        Falling                 =(PositiveToNegative), // 1
        Rising                  =(NegativeToPositive), // 2
        AnySignChange           =(PositiveToNegative|NegativeToPositive)    // 3
    };

    SimTK_SimTKCOMMON_EXPORT static std::string eventTriggerString(Trigger);


    static Trigger classifyTransition(int before, int after) {
        if (before==after)
            return NoEventTrigger;
        if (before==0)
            return NoEventTrigger; // Do not report transitions away from zero.
        if (before==1)
            return PositiveToNegative;
        // before==-1
        return NegativeToPositive;
    }

    static Trigger maskTransition(Trigger transition, Trigger mask) {
        return Trigger(transition & mask); // we're depending on NoEventTrigger==0
    }

private:
};

SimTK_DEFINE_UNIQUE_INDEX_TYPE(EventId);

class SimTK_SimTKCOMMON_EXPORT EventTriggerInfo {
public:
    EventTriggerInfo();
    explicit EventTriggerInfo(EventId eventId);
    ~EventTriggerInfo();
    EventTriggerInfo(const EventTriggerInfo&);
    EventTriggerInfo& operator=(const EventTriggerInfo&);

    EventId getEventId() const; // returns -1 if not set
    bool shouldTriggerOnRisingSignTransition()  const; // default=true
    bool shouldTriggerOnFallingSignTransition() const; // default=true
    Real getRequiredLocalizationTimeWindow()    const; // default=0.1

    // These return the modified 'this', like assignment operators.
    EventTriggerInfo& setEventId(EventId);
    EventTriggerInfo& setTriggerOnRisingSignTransition(bool);
    EventTriggerInfo& setTriggerOnFallingSignTransition(bool);
    EventTriggerInfo& setRequiredLocalizationTimeWindow(Real);

    Event::Trigger calcTransitionMask() const {
        unsigned mask = 0;
        if (shouldTriggerOnRisingSignTransition()) {
            mask |= Event::NegativeToPositive;
        }
        if (shouldTriggerOnFallingSignTransition()) {
            mask |= Event::PositiveToNegative;
        }
        return Event::Trigger(mask);
    }

    Event::Trigger calcTransitionToReport
       (Event::Trigger transitionSeen) const
    {
        // report -1 to 1 or 1 to -1 as appropriate
        if (transitionSeen & Event::Rising)
            return Event::NegativeToPositive;
        if (transitionSeen & Event::Falling)
            return Event::PositiveToNegative;
        assert(!"impossible event transition situation");
        return Event::NoEventTrigger;
    }

private:
    class EventTriggerInfoRep;

    // opaque implementation for binary compatibility
    EventTriggerInfoRep* rep;

    const EventTriggerInfoRep& getRep() const {assert(rep); return *rep;}
    EventTriggerInfoRep&       updRep()       {assert(rep); return *rep;}
};



} // namespace SimTK

#endif // SimTK_SimTKCOMMON_EVENT_H_