// -*- C++ -*-
namespace Katabatic {
/*! \defgroup NetConstraints 5. Constraints Computations (internal)
*
* This module documents how constraints computation are performed.
* It is intented for developpers only.
*
* Constraints gives the absolute minimal and maximal position an
* \c AutoSegment axis can be set. They materialize the bounds over
* which we may have an electrical disconnection.
*
* Practically, due to the magic of \c AutoContact, disconnections
* can only occurs on \c AutoContact anchored on \c RoutingPad :
* if they go outside the \c RoutingPad area, we are in trouble.
* Those \c AutoContact can be spotted either by the fact they have
* an anchor or the AutoContact::isTerminal() flag is set.
*
*
* \section secConstraintsOrgan Organisation
*
* Due to algorithmic consideration, instead of storing constraint
* interval (one axis) in \c AutoSegment, we store constraint \c Box
* (both axis) in \c AutoContact. They are easier to propagate during the
* computation stage and should takes less memory as \c AutoContact
* are often shared by more than two \c AutoSegment.
*
* To spare memory, each coordinate of the constraint \c Box is expressed
* as a strictly positive offset in \e lambdas from the lower left corner
* of the \c FCell owning the \c AutoContact. Offsets are 8 bits <code>unsigned int</code>,
* thus a \c Box takes one word (32 bits). This leads to two restrictions :
* <ul>
* <li>A \c FCell side cannot be greater than 256 \e lambdas.
* <li>The constraint \c Box minimal precision is the \e lambda.
* </ul>
* In all cases I can foresee, none of them should be a problem.
*
* Constraint interval on \c AutoSegment can be deduced from any of
* the source or target \c AutoContact. For an horizontal \c AutoSegment
* we take the constraint \c Box vertical interval and for a vertical,
* the horizontal interval.
*
*
* \section secNativeConstraints Native Constraints
*
* Before the contraints computation starts, we needs to initialize
* each \c AutoContact \c Box to a reasonable default : the
* <em>Native Constraint Box</em>. Wich is :
* <ul>
* <li>For an anchored/passive \c AutoContact : the bounding box
* of the underlying terminal.
* <li>For any other \c AutoContact : the bounding box of the
* \c FCell owner.
* </ul>
*
*
* \section secConstraintsPropagation Constraints Propagation
*
* The only source of constraints being the anchored \c AutoContact
* we do a full propagation from each of them. Propagation is done
* through \c AutoSegment as follow :
* <ul>
* <li>Horizontal \c AutoSegment propagate the vertical (\b DY)
* constraint part.
* <li>Vertical \c AutoSegment propagate the horizontal (\b DX)
* constraint part.
* </ul>
* Obviously, any constraint diseapear after we have gone through
* exactly one horizontal and one vertical, thus the propagation is
* somewhat limited.
*
* Case of collapsed \c AutoSegment : those are to be kept at
* zero-length, thus they act as a bypass between two \c AutoContact.
* Their source and target can be considered as <em>stacked</em>
* and propagate both vertical and horizontal constraint (that is :
* the whole constraint \c Box).
*
*
* \section secCollapseUncollapse Collapsing & Uncollapsing
*
* Only local \c AutoSegment can be collapsed, as a global
* \c AutoSegment crosses the boundary of at least one \c FCell
* it can't have a null length.
*
* When collapsing a new \c AutoSegment, we can do an incremental
* constraint computation as it will result in a further increase
* of constraint (if any).
*
* When uncollapsing an \c AutoSegment we may have to slacken the
* constraint, but we do not know to which extend. So to make it
* simple we fully recompute constraints from scratch.
*
* Note that collapsing/uncollapsing are exceptionnal operations,
* so we can afford losing a little time there.
*
*
* \section secCollapseExample progressive Collapsing Example
*
* In this set of example we show how constraints propagate along the
* \c AutoSegment, depending on the collapsed ones. We starts we no
* collapse and ends with all \e local \c AutoSegment collapseds.
*
* \image html NetConstraints-1.png "Fully expanded"
* \image latex NetConstraints-1.pdf "Fully expanded" width=0.4\textwidth
* \image html NetConstraints-2.png "After One Vertical collapse"
* \image latex NetConstraints-2.pdf "After One Vertical collapse" width=0.4\textwidth
* \image html NetConstraints-3.png "After Horizontal collapse"
* \image latex NetConstraints-3.pdf "After Horizontal collapse" width=0.4\textwidth
* \image html NetConstraints-4.png "Fully collapsed"
* \image latex NetConstraints-4.pdf "Fully collapsed" width=0.4\textwidth
*/
//! \addtogroup NetConstraints
//! \{
/*! \function void KatabaticEngine::_computeNetConstraints ( Net* net );
* \param net The net for which to compute constraints.
*
* compute constraints on a net.
*/
//! \}
}