
 // -*- C++ -*-


 namespace Katabatic {

 /*! \class        AutoSegment
  *  \brief        Self-sizing segment (\b API).
  *
  *                AutoSegment provide an uniform way of accessing AutoHorizontal
  *                and AutoVertical self-sizing segments. AutoSegments mainly contains
  *                a pointer to the associated Horizontal/Vertical Hurricane segment.
  *                This is the Hurricane segment which is part of the ring of the
  *                AutoContact. Thus we can directly access the Hurricane segment
  *                from the AutoSegment, but for the othey around we uses a lookup
  *                table in the Katabatic \c ToolEngine (see the
  *                Katabatic::_Lookup() member function).
  *
  *                In order to inform the router of an AutoSegment state change,
  *                a callback function SegmentRevalidateCB can be positionned.
  *
  *                \c Segment associated to AutoSegment are automatically oriented
  *                in such a way that the source \c Hook is always \e lower than
  *                the target \c hook. For an Horizontal segment it means that
  *                the abcissa of the source is inferior to the abcsissa of the
  *                target. It goes the same way for Vertical segment with the
  *                ordinate.
  *
  *                KatabaticSession mechanism : this is fairly similar to the
  *                \c Hurricane updateSession one. When a segment is either moved
  *                by the router or resized by it's AutoContact it is invalidated
  *                with autoInvalidate() and put into the set of invalidated
  *                segments. When the KatabaticSession is closed the onRevalidate()
  *                member function is called on each segment, which in turn calls
  *                the router's callback. See Session::open(), Session::revalidate(),
  *                Session::close() and \ref katabaticSession.
  *
  * \remark        As this object uses the decorator Design Pattern, almost all
  *                functions are pure virtuals. Implementation take place in a
  *                derived class \c AutoSegmentConcrete which is not documented,
  *                (same specifications as AutoSegment).
  *
  * \see           AutoSegmentDecorator class.
  */

 /*! \typedef      AutoSegment::RevalidateCb_t ( AutoSegment* )
  *                Function type for the router callback. See AutoSegment::setRevalidateCb().
  */

 /*  \function     static AutoSegment::RevalidateCb_t* AutoSegment::setRevalidateCb ( RevalidateCb_t* cb );
  *  \param        cb The new router callback to install.
  *  \return       The previous router callback.
  *
  *                Install the callback to call when an AutoSegment is revalidated,
  *                The callback is called by onRevalidate() on closing the Katabatic
  *                update session.
  */

 /*! \function     bool AutoSegment::isHorizontal () const;
  *  \return       \true if the AutoSegment is horizontal.
  */

 /*! \function     bool AutoSegment::isVertical () const;
  *  \return       \true if the AutoSegment is vertical.
  */

 /*! \function     bool AutoSegment::isGlobal () const;
  *  \return       \true if the AutoSegment is global : source and target
  *                AutoContact are not in the same GCell.
  */

 /*! \function     bool AutoSegment::isLocal () const;
  *  \return       \true if the AutoSegment is local : source and target
  *                belongs to the same GCell.
  */

 /*! \function     bool AutoSegment::isTerminal () const;
  *  \return       \true if the AutoSegment is terminal : the only way
  *                to access a terminal AutoContact (may not be directly
  *                achored on that terminal).
  */

 /*! \function     bool AutoSegment::isCollapsed () const;
  *  \return       \true if the AutoSegment is collapsed : kept to zero-length.
  */

 /*! \function     bool AutoSegment::isCanonical () const;
  *  \return       \true if the AutoSegment is canonical that is, the leftmost
  *                (for horizontal) or lowest (for vertical) segment of a set
  *                of collapsed segments. The canonical segment must be used
  *                as the unique representant for the collapsed set.
  */

 /*! \function     bool AutoSegment::isFixed () const;
  *  \return       \true if the AutoSegment cannot be moved (through setAxis()).
  */

 /*! \function     bool AutoSegment::isAccountable () const;
  *  \return       \true if the AutoSegment is canonical and not collapsed.
  *                Normally those flags are mutually exclusives, but better safe
  *                than sorry.
  *
  */

 /*! \function     virtual GCell* AutoSegment::getGCell () const;
  *  \return       The GCell owning the source AutoContact.
  */

 /*! \function     Net* AutoSegment::getNet () const;
  *  \return       The net this AutoSegment is part of.
  */

 /*! \function     Layer* AutoSegment::getLayer () const;
  *  \return       The layer of the AutoSegment.
  */

 /*! \function     virtual Segment* AutoSegment::getSegment ();
  *  \return       The associated \c Hurricane segment.
  */

 /*! \function     virtual Segment* AutoSegment::getSegment () const;
  *  \return       The associated \c Hurricane segment.
  *
  *  This function is for use in const members.
  */

 /*! \function     virtual Segment* AutoSegment::getHorizontal ();
  *  \return       If the the associated segment is horizontal, returns it.
  *                Otherwise (vertical) returns \c NULL.
  */

 /*! \function     virtual Segment* AutoSegment::getVertical ();
  *  \return       If the the associated segment is vertical, returns it.
  *                Otherwise (horizontal) returns \c NULL.
  */

 /*! \function     DbU::Unit  AutoSegment::getAxis () const;
  *  \return       The segment axis : Y for horizontals and X for verticals.
  */

 /*! \function     AutoContact* AutoSegment::getSource () const;
  *  \return       The source AutoContact.
  */

 /*! \function     AutoContact* AutoSegment::getTarget () const;
  *  \return       The target AutoContact.
  */

 /*! \function     DbU::Unit  AutoSegment::getSourcePosition () const;
  *  \return       The lower bound of the segment into the routing track, equal
  *                the source coordinate minus the half pitch.
  */

 /*! \function     DbU::Unit  AutoSegment::getTargetPosition () const;
  *  \return       The upper bound of the segment into the routing track, equal
  *                the target coordinate plus the half pitch.
  */

 /*! \function     virtual void  AutoSegment::setAxis ( DbU::Unit axis, bool realignate=false, set<AutoSegment*>* processeds=NULL );
  *  \param        axis       New coordinate of the axis. For an horizontal segment
  *                           it will change the Y coordinate and for a vertical,
  *                           the X coordinate.
  *  \param        realignate It set to true, the new axis position will be propagated
  *                           to all collapsed segments, even if the current AutoSegment
  *                           don't need to be moved.
  *  \param        processeds The set of already processeds aligneds AutoSegments.
  *
  *                setAxis is the API frontend to the alignate function. It actually
  *                only checks if the segment has to be moved and if the move is to
  *                be propagated to the aligned AutoSegments.
  */

 /*! \function     virtual void  AutoSegment::orient ();
  *                sets the source and target \c Hook of the Hurricane segment so
  *                the source is always lower than the target.
  */

 /*! \function     virtual void  AutoSegment::invalidate ();
  *                adds the AutoSegment to the invalidate session. This will happens
  *                whenever a segment is moved by the router through setAxis() or
  *                resized by it's AutoContact.
  */

 /*  \function     virtual void  AutoSegment::onRevalidate ();
  *                This function is called at the time the AutoUpdate session is closed
  *                and calls the router's callback.
  */

 /*! \function     virtual void  AutoSegment::getConstraints ( DbU::Unit& constraintMin, DbU::Unit& constraintMax ) const;
  *  \param        constraintMin  Where to store the constraint lower bound.
  *  \param        constraintMax  Where to store the constraint upper bound.
  *  \return       Always \true (don't remember why...).
  *
  *                Constraints are deduced from the constraint box of the source
  *                AutoContact.
  *
  *  \see          \ref NetConstraints
  */

 /*! \function     virtual void  AutoSegment::getConstraints ( Interval& i ) const;
  *  \param        i  The constraint interval.
  *  \return       Always \true (don't remember why...).
  *
  *  \see          getConstraints(), \ref NetConstraints
  */

 /*! \function     DbU::Unit  AutoSegment::getSlack () const;
  *  \return       The length of the constraint interval.
  *
  *  \see          \ref NetOptimals
  */

 /*! \function     DbU::Unit  AutoSegment::getOptimalMin () const;
  *  \return       The lower bound of the optimal interval.
  *
  *  \see          \ref NetOptimals
  */

 /*! \function     DbU::Unit  AutoSegment::getOptimalMax () const;
  *  \return       The upper bound of the optimal interval.
  *
  *  \see          \ref NetOptimals
  */

 /*! \function     Interval&  AutoSegment::getOptimal ( Interval& i ) const;
  *  \param        i The optimal interval.
  *  \return       The interval given as argument.
  *
  *  \see          \ref NetOptimals
  */

 /*! \function     DbU::Unit  AutoSegment::getCost ( DbU::Unit axis ) const;
  *  \param        axis  An axis coordinate.
  *  \return       The distance from the nearest optimal interval bound.
  *
  *  \see          \ref NetOptimals
  */

 /*! \function     AutoSegment* AutoSegment::getCanonical ( DbU::Unit& sourcePosition, DbU::Unit& targetPosition );
  *  \param        sourcePosition  Lower bound of the super-AutoSegment.
  *  \param        targetPosition  Upper bound of the super-AutoSegment.
  *  \return       The canonical AutoSegment of the super-AutoSegment.
  *
  *                A super-AutoSegment is the set of all AutoSegment which have been
  *                bound together through (perpandicular) collapsed AutoSegment.
  *                They behave like one big AutoSegment. For algorithmic purpose we
  *                needs a canonical representant : it will be the lower AutoSegment
  *                (the one with the lower source coordinates).
  *                We also needs to know the real extend of the super-AutoSegment : it's
  *                returned through \c sourcePosition and \c targetPosition parameters.
  */

 /*! \function     AutoSegment* AutoSegment::getCanonical ( Interval& i );
  *  \param        i  interval of the super-AutoSegment.
  *  \return       The canonical AutoSegment of the super-AutoSegment.
  *
  *  \see          AutoSegment::getCanonical().
  */

 /*! \function     AutoSegments  AutoSegment::getCollapseds ( bool withPerpand=false );
  *  \return       The \Collection of AutoSegment that are collapsed to this one
  *                (i.e. linked through perpandicual collapsed ones). Together
  *                they forms one big virtual AutoSegment.
  */

 /*! \function     AutoSegments  AutoSegment::getCollapsedPerpandiculars ();
  *  \return       The \Collection of AutoSegment that are perpandicular to this
  *                one and it's collapsed fellows.
  *
  *                Note that this \Collection contains only \b GLOBAL perpandicular
  *                AutoSegment and \b Terminal perpandicular AutoSegment.
  */

 /*! \function     void  AutoSegment::setCanonical ( bool state );
  *  \param        state  sets the isCanonical() flag to this value.
  */

 /*! \function     void  AutoSegment::setTerminal ( bool state );
  *  \param        state  sets the isTerminal() flag to this value.
  */

 /*! \function     void  AutoSegment::setLayer ( const Layer* layer );
  *  \param        layer  Changes the \Hurricane segment layer.
  */

 /*! \function     void  AutoSegment::setPositions ();
  *                compute the positions of the AutoSegment into the routing track,
  *                from the \Hurricane segment extentions and the half-pitch.
  *
  *  \see          getSourcePosition() & getTargetPosition().
  */

 /*! \function     void  AutoSegment::collapse ();
  *                sets the AutoSegment into collapsed state (zero-length).
  */

 /*! \function     void  AutoSegment::expand ();
  *                Uncollapse the AutoSegment, re-compute the constraints on
  *                the splitted sets.
  */

 /*! \function     bool  AutoSegment::toConstraintAxis ( set<AutoSegment*>* processeds=NULL );
  *  \return       \True if the AutoSegment axis has been moved.
  *
  *                If the segment axis is outside the constraint interval, set it
  *                the nearest constraint interval bound.
  */

 /*! \function     bool  AutoSegment::toOptimalAxis ( set<AutoSegment*>* processeds=NULL );
  *  \return       \True if the AutoSegment axis has been moved.
  *
  *                If the segment axis is outside the optimal interval, set it
  *                the nearest optimal interval bound.
  */

 /*! \function     void  AutoSegment::alignate ( DbU::Unit axis );
  *  \param        axis  New axis's coordinate.
  *
  *                Move the segment axis to a new position. Adjust positions
  *                of the supporting Contact whenever they are anchored on terminals
  *                (i.e. RoutingPad).
  *                  This function is atomic and should not be called directly
  *                but rather through setAxis(). It's implemented in the
  *                derived classes AutoHorizontal & AutoVertical.
  */

 /*! \function     void  AutoSegment::setOptimalMin ( DbU::Unit  oMin );
  *  \param        oMin  sets the lower bound of the optimal interval.
  *
  *  \see          getOptimalMin(), getOptimalMax(), getCost().
  */

 /*! \function     void  AutoSegment::setOptimalMax ( DbU::Unit  oMin );
  *  \param        oMin  sets the upper bound of the optimal interval.
  *
  *  \see          getOptimalMin(), getOptimalMax(), getCost().
  */

 /*! \function     void  AutoSegment::checkPositions () const;
  *                check the coherency between the locally shadowed values
  *                of source \& target position and the real ones. If a discrepancy
  *                is found issue an error (but do not stop the program).
  *
  *                Note that discrepancies are legal while the AutoSegment is
  *                invalidated (see \ref katabaticSession).
  */

 /*! \function     void  AutoSegment::checkInvalidated () const;
  *                issue an error if the AutoSegment is invalidated. Mainly used
  *                to debug the Katabatic Session mechanism (\ref katabaticSession).
  */


 //! \addtogroup   NetOptimals
 //! \{

 /*! \function     virtual void  AutoSegment::computeOptimal ( set<AutoSegment*>* processeds=NULL );
  *                compute the AutoSegment optimal position interval.
  */

 /*! \function     virtual DbU::Unit  AutoSegment::getOrigin () const;
  *  \return       The lower bound of the GCell in which the AutoSegment is
  *                (\c YMin for horizontals, \c XMin for verticals).
  */

 /*! \function     virtual DbU::Unit  AutoSegment::getExtremity () const;
  *  \return       The upper bound of the GCell in which the AutoSegment is
  *                (\c YMax for horizontals, \c XMax for verticals).
  */

 //! \}


 //! \addtogroup   katabaticSession
 //! \{

 /*! \function     bool  AutoSegment::isInvalidated () const;
  *  \return       \True if the AutoSegment is invalidated, i.e. in the
  *                Katabatic Session, it's axis having being moved by the
  *                router.
  *
  *  \see          autoInvalidate().
  */

 /*! \function     bool  AutoSegment::setInvalidated ( bool state );
  *  \param        state  set the state of the AutoSegment regarding the
  *                       Katabatic Session. 
  *
  *  \see          autoInvalidate().
  */

 //! \}


 /*! \class        AutoHorizontal
  *  \brief        Horizontal AutoSegment (\b API).
  */

 /*! \function     static AutoHorizontal* AutoHorizontal::create ( Horizontal* horizontal, int type, bool terminal=false, bool collapsed=false );
  *  \param        horizontal The associated \c Hurricane segment.
  *  \param        type       Global, local or guessed kind.
  *  \param        terminal   Whether the segment is tightly linked to a terminal.
  *  \param        collapsed  Whether the segment must be kept of null length.
  *  \return       The newly created AutoSegment.
  */

 /*! \function     static AutoHorizontal* AutoHorizontal::create ( AutoContact* source, AutoContact* target, const Layer* layer, DbU::Unit y, DbU::Unit width, int type, bool terminal=false, bool collapsed=false );
  *  \param        source     The source \c Component.
  *  \param        target     The target \c Component.
  *  \param        layer      The segment's layer.
  *  \param        y          The segment's Y coordinate.
  *  \param        width      The segment's width.
  *  \param        type       Global, local or guessed kind.
  *  \param        terminal   Whether the segment is tightly linked to a terminal.
  *  \param        collapsed  Whether the segment must be kept of null length.
  *  \return       The newly created AutoSegment.
  *
  *                Allocate both \c Hurricane segment and Katabatic AutoSegment.
  */


 /*! \class        AutoVertical
  *  \brief        Vertical AutoSegment (\b API).
  */

 /*! \function     static AutoVertical* AutoVertical::create ( Vertical* vertical, int type, bool terminal=false, bool collapsed=false );
  *  \param        vertical   The associated \c Hurricane segment.
  *  \param        type       Global, local or guessed kind.
  *  \param        terminal   Whether the segment is tightly linked to a terminal.
  *  \param        collapsed  Whether the segment must be kept of null length.
  *  \return       The newly created AutoSegment.
  */

 /*! \function     static AutoVertical* AutoVertical::create ( AutoContact* source, AutoContact* target, const Layer* layer, DbU::Unit x, DbU::Unit width, int type, bool terminal=false, bool collapsed=false );
  *  \param        source     The source \c Component.
  *  \param        target     The target \c Component.
  *  \param        layer      The segment's layer.
  *  \param        x          The segment's X coordinate.
  *  \param        width      The segment's width.
  *  \param        type       Global, local or guessed kind.
  *  \param        terminal   Whether the segment is tightly linked to a terminal.
  *  \param        collapsed  Whether the segment must be kept of null length.
  *  \return       The newly created AutoSegment.
  *
  *                Allocate both \c Hurricane segment and Katabatic AutoSegment.
  */


 /*! \function     AutoSegment* AutoSegment::create ( AutoContact* source, AutoContact* target, unsigned int dir, int type, bool terminal=false, bool collapsed=false );
  *  \param        source    The source AutoContact.
  *  \param        target    The target AutoContact.
  *  \param        dir       The AutoSegment direction (\b H / \b V).
  *  \param        type      Whether the AutoSegment is \b LOCAL, \b GLOBAL or must be guessed.
  *  \param        terminal  The AutoSegment is used to connect a terminal.
  *  \param        collapsed The AutoSegment is collapsed.
  *  \return       A new AutoSegment.
  *
  *                create the AutoSegment between \c source and \c target, update the GCell
  *                density if needed.
  *
  *                If the \c dir parameter do not contains the \b HORIZONTAL or \b VERTICAL
  *                boolean flags an error will be thrown.
  */


 /*! \enum         AutoSegment::Type
  *                This enumeration is used to hints AutoSegment constructor about
  *                the kind of segment we are about to create. Once created, the
  *                kind of AutoSegment is stored in a single boolean telling
  *                wether it's \b GLOBAL or \b LOCAL (see AutoSegment::isGlobal()).
  *
  *                It is always best to avoid using AutoSegment::Guess as it implies findind
  *                and checking source and target anchors (through ring access).
  *                And in most cases we already known the kind of segment because
  *                we created the source and target AutoContact just before...
  *                See GCellConfiguration related functions.
  */

 /*! \var          AutoSegment::Global
  *                The AutosSegment crosses at least one GCell boundary (i.e.
  *                source and target AutoContact do not belong to the same GCell).
  */

 /*! \var          AutoSegment::Local
  *                The AutoSegment is fully included in one GCell.
  */

 /*! \var          AutoSegment::Guess
  *                The AutoSegment constructor will guess the kind of AutoSegment
  *                by examining source and target anchors.
  */

 /*! \defgroup     collapseCanonical 3. AutoSegment collapse & Canonical (internal)
  *
  *  \section      AlignedAS Collapsing AutoSegment
  *
  *                A set of AutoSegment can be aligned together. The set will
  *                behave like one big AutoSegment, especially, moving one
  *                AutoSegment through setAxis() will move the whole set.
  *
  *                For each set of aligned AutoSegment, we provide a canonical
  *                AutoSegment : the leftmost (for horizontal) or lowermost for
  *                verticals.
  *
  *                There are two ways AutoSegments could be aligned :
  *                <ul>
  *                  <li>Through a collapsed perpandicular AutoSegment.
  *                  <li>Through a locked AutoContact. 
  *                </ul>
  *
  * \subsection    AlignedByCollapsed Aligned through collapsed AutoSegment
  *
  *                When an AutoSegment is collapsed, all perpandicular AutoSegment
  *                to it's source and target AutoContact are aligneds. Collapsing
  *                an AutoSegment means that it should be kept to zero length and
  *                thus not managed by the overlying router.
  *
  *                \image html  AutoSegmentCollapse-5.png "collapse by AutoSegment"
  *                \image latex AutoSegmentCollapse-5.pdf "collapse by AutoSegment" width=0.4\textwidth
  *
  * \subsection    AlignedByAutoContact Aligned through collapsed AutoContact
  *
  *                With the setHAlignate() and setVAlignate() the alignment of
  *                horizontal (resp. vertical) AutoSegment of an AutoContact can be
  *                forced.
  *
  *                \image html  AutoSegmentCollapse-6.png "collapse by AutoContact"
  *                \image latex AutoSegmentCollapse-6.pdf "collapse by AutoContact" width=0.4\textwidth
  *
  * \subsection    collapsedExample An example of collapse/alignment
  *
  *                \image html  AutoSegmentCollapse-1.png "collapse - Step 1"
  *                \image latex AutoSegmentCollapse-1.pdf "collapse - Step 1" width=0.4\textwidth
  *
  *                \image html  AutoSegmentCollapse-2.png "collapse - Step 2"
  *                \image latex AutoSegmentCollapse-2.pdf "collapse - Step 2" width=0.4\textwidth
  *
  *                \image html  AutoSegmentCollapse-3.png "collapse - Step 3"
  *                \image latex AutoSegmentCollapse-3.pdf "collapse - Step 3" width=0.4\textwidth
  *
  *                \image html  AutoSegmentCollapse-4.png "collapse - Step 4"
  *                \image latex AutoSegmentCollapse-4.pdf "collapse - Step 4" width=0.4\textwidth
  */


 //! \addtogroup   collapseCanonical
 //! \{

 /*! \enum         AutoSegment::PerpandicularState
  *                set of flags used to build the state of two AutoSegment.
  *  \see          getPerpandicularState().
  */

 /*! \var          AutoSegment::PerpandicularAny
  *                The \e current AutoSegment is perpandicular to the \e master.
  *                May it be or not through collapsed perpandiculars.
  */

 /*! \var          AutoSegment::PerpandicularIndirect
  *                The \e current AutoSegment is perpandicular to the \e master
  *                through at least one collapsed perpandicular.
  */

 /*! \var          AutoSegment::ParallelOrExpanded
  *                The \e current AutoSegment is not part of the aligned set,
  *                it's either parallel but not aligned (no constraint on the
  *                AutoContact) or perpandicular and not collapsed.
  */

 /*! \var          AutoSegment::ParallelAndLayerChange
  *                The \e current AutoSegment is parallel to the master but not on
  *                the same layer as the \e source (the \e master by transitivity).
  */

 /*! \function     unsigned int AutoSegment::getPerpandicularState ( AutoContact* contact, AutoSegment* source, AutoSegment* current, bool isHorizontalMaster, const Layer* masterLayer=NULL )
  *  \param        contact             The AutoContact shared by source \& current.
  *  \param        source              The AutoSegment from where we came.
  *  \param        current             The AutoSegment we are exploring.
  *  \param        isHorizontalMaster  The direction of the reference AutoSegment.
  *  \param        masterLayer         The \Layer of the reference AutoSegment.
  *  \return       A composite value telling the position of current relative to
  *                source and reference.
  *
  *                Locators of \Collections like AutoSegment::getCollapseds() or
  *                AutoSegment::getCollapsedPerpandiculars() are built on this
  *                function. Any \Collection manipulating aligned sets must uses
  *                this function which is the keystone of the aligned set walk-through.
  *
  *                The return value is a combination of binary flags from the
  *                AutoSegment::PerpandicularState enumeration. The function
  *                compute the following boolean values :
  *                <ul>
  *                  <li>\e sourcePerpandicular : \True if the \e source is perpandicular
  *                      to the \e master AutoSegment.
  *                  <li>\e currentPerpandicular : \True if the \e current is perpandicular
  *                      to the \e master AutoSegment.
  *                  <li>\e contactAlignate : \True if the alignment constraint on the
  *                      AutoContact (if any) applies to \e source \& \e current. For instance
  *                      it will be \True if both source and current are horizontal
  *                      \b and AutoContact::isHAlignate() is \True.
  *                </ul>
  *                Then the return value is computed as follow :
  *                <ol>
  *                  <li>If \e current is parallel to \e master \b but not on the same
  *                      layer.
  *
  *                      sets the AutoSegment::AutoSegment::ParallelAndLayerChange flag.
  *                  <li>If \e current is perpandicular to \e master \b and not
  *                      collapsed, it is perpandicular to the aligned set of the
  *                      \e master.
  *
  *                      sets the AutoSegment::AutoSegment::PerpandicularAny flag.
  *                  <li>\e source is perpandicular to \e master. There is an implicit
  *                      context : the only way a perpandicular segment gets took into
  *                      account, is to be collapsed. Then if the \e current AutoSegment
  *                      is also perpandicular \b and \b not collapsed, it means
  *                      that it's a perpandicular to the aligned set of the \e master,
  *                      The difference with the previous case, is that it's through at
  *                      least one collapsed perpandicular.
  *
  *                      sets the AutoSegment::AutoSegment::PerpandicularIndirect flag.
  *                  <li>\e source is parallel to \e master. Then we check for
  *                      disconnection in the aligned set. Disconnection arises
  *                      if the \e contactAlignate flag is \false (either no
  *                      alignment constraint on the AutoContact or different
  *                      directions), \b and the \e current segment is not a
  *                      collapsed perpandicular. 
  *
  *                      sets the AutoSegment::AutoSegment::ParallelOrExpanded flag.
  *                </ol>
  *                The \b zero return value means that the \e current AutoSegment
  *                belong to the same aligned set as the \e master \b or is a
  *                perpandicular collapsed AutoSegment.
  *
  *                The figures below demonstrate all thoses case :
  *
  *                \image html  PerpandicularState-1.png "Simple Perpandicular (case 2)"
  *                \image latex PerpandicularState-1.pdf "Simple Perpandicular (case 2)" width=0.8\textwidth
  *
  *                \image html  PerpandicularState-2.png "Indirect Perpandicular (case 3)"
  *                \image latex PerpandicularState-2.pdf "Indirect Perpandicular (case 3)" width=0.8\textwidth
  *
  *                \image html  PerpandicularState-3.png "Parallel (case 4.1)"
  *                \image latex PerpandicularState-3.pdf "Parallel (case 4.1)" width=0.8\textwidth
  *
  *                \image html  PerpandicularState-4.png "Aligned through AutoContact (case 4.2)"
  *                \image latex PerpandicularState-4.pdf "Aligned through AutoContact (case 4.2)" width=0.8\textwidth
  */

 /*! \function     unsigned int AutoSegment::getPerpandicularState ( AutoContact* contact, AutoSegment* source, AutoSegment* current, AutoSegment* master )
  *  \param        contact  The AutoContact shared by source \& current.
  *  \param        source   The AutoSegment from where we came.
  *  \param        current  The AutoSegment we are exploring.
  *  \param        master   The reference AutoSegment.
  *  \return       A composite value telling the position of current relative to
  *                source and reference.
  */

 /*! \function     bool  AutoSegment::arePerpandiculars ( AutoSegment* a, AutoSegment* b );
  *  \param        a  First AutoSegment.
  *  \param        b  Second AutoSegment.
  *  \return       true if a \& b have perpandicular directions.
  */

 /*! \function     bool  AutoSegment::areAligneds ( AutoSegment* a, AutoSegment* b );
  *  \param        a  First AutoSegment.
  *  \param        b  Second AutoSegment.
  *  \return       true if a \& b have same directions.
  */

 /*! \function     bool  AutoSegment::arePerpandiculars ( bool isHorizontalA, AutoSegment* b );
  *  \param        isHorizontalA  is the A AutoSegment horizontal.
  *  \param        b              Second AutoSegment.
  *  \return       true if a \& have perpandicular directions.
  */

 }
