%% Copyright (c) 2004  SciSoft.  All rights reserved.
%%
%% This file is part of CGAL (www.cgal.org); you may redistribute it under
%% the terms of the Q Public License version 1.0.
%% See the file LICENSE.QPL distributed with CGAL.
%%
%% Licensees holding a valid commercial license may use this file in
%% accordance with the commercial license agreement provided with the software.
%%
%% This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
%% WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
%%
%% 
%%
%% Author(s)     : Fernando Cacciola <fernando_cacciola@hotmail.com>

\begin{ccRefConcept}{ConnectedPlanarDirectedGeometricGraph}

%% \ccHtmlCrossLink{}     %% add further rules for cross referencing links
%% \ccHtmlIndexC[concept]{} %% add further index entries

\ccDefinition

The concept \ccRefName\ describes the requirements and constrians of a \ccc{Boost Graph} commonly found in geometric data structures.

\ccHeading{Requirements}

\begin{description}
\item[Connected] 
Any vertex is connected to any other vertex via some path (a sequence of adjacent vertices).
The graph must be at least {\em 2-connected}. That is, it cannot have any {\em terminal} vertex (incident upon just 1 edge).

\item[Planar]
The graph \textit{can} be drawn without crossing edges \textit{and} the straight line segments implicitely connecting the vertices do not intersect except at the vertices.

\item[Directed]
All edges are {\em ordered} pair of vertices.

\item[Geometric]
The vertices embeed geometric points (in any geometric dimension) and its edges are {\em implicitely assumed} to be straight line segments (even if a concrete model embeeds a different type of curve).

\end{description}

Additionally, the vertices and edges of this graph are required to have a distinguishible \ccc{null} state such that any default constructed vertex or edge is formally \ccc{null}.
  
\ccRefines
\ccc{BidirectionalGraph}
\ccc{AdjacencyGraph}
\ccc{EdgeAndVertexListGraph}

\ccTypes
  \ccNestedType{Point}{The Point type of the vertex}{}

\ccOperations

Following the BGL interface, the following graph operations are defined as free rather than member functions.

  \ccFunction
  {template<class Graph>
  typename boost::graph_traits<Graph const>::edge_descriptor 
  opposite_edge(typename boost::graph_traits<Graph const>::edge_descriptor e, Graph const& g );
  }
  {Given the edge \ccc{e: s->t}, returns the edge with opposite direction: \ccc{t->s}.
  If the resulting edge does not belong to \ccc{g} the result is a \ccc{null} (default constructed) edge.\\
  (non-const version ommited)
  }
  
  \ccFunction
  {template<class Graph>
  typename boost::graph_traits<Graph const>::edge_descriptor 
  next_edge_ccw(typename boost::graph_traits<Graph const>::edge_descriptor e, Graph const& g );
  }
  {Given the edge \ccc{e} with source vertex \ccc{s}, returns the first edge with the same source vertex which
  is found in a Counter-clockwise rotation around \ccc{s}.
  Since a \ccRefName\ is required to be {\em 2-connected}, the result is always different from \ccc{e}.
  }
  
  \ccFunction
  {template<class Graph>
  typename boost::graph_traits<Graph const>::edge_descriptor 
  next_edge_cw(typename boost::graph_traits<Graph const>::edge_descriptor e, Graph const& g );
  }
  {Given the edge \ccc{e} with source vertex \ccc{s}, returns the first edge with the same source vertex which
  is found in a Clockwise rotation around \ccc{s}.
  Since a \ccRefName\ is required to be at least {\em 2-connected}, the result is always
  different from \ccc{e}.
  }
  
  \ccFunction
  {template<class Graph>
  typename boost::graph_traits<Graph const>::edge_descriptor 
  next_edge(typename boost::graph_traits<Graph const>::edge_descriptor e, Graph const& g );
  }
  {Returns the {\em successor} of \ccc{e}. It is alwat
  That is, given the edge \ccc{a->b} returns \ccc{b->c} such that \ccc{c != a}.\\
  (non-const version ommited)
  }
  
  \ccFunction
  {template<class Graph>
  typename boost::graph_traits<Graph const>::edge_descriptor 
  prev_edge(typename boost::graph_traits<Graph const>::edge_descriptor e, Graph const& g );
  }
  {Returns the {\em predecessor} of \ccc{e}.
  That is, given the edge \ccc{b->c} returns \ccc{a->b} such that \ccc{c != a}\\
  (non-const version ommited)
  }
  
  \ccFunction
  {template<class Graph>
  typename CGAL::Geometric_graph_traits<Graph>::Point const& 
  get_point(typename boost::graph_traits<Graph const>::vertex_descriptor v, Graph const& g );
  }
  {Returns the point of the vertex \ccc{v} belonging to the graph \ccc{g}}
  
  \ccFunction
  {template<class Graph>
  void set_point(typename boost::graph_traits<Graph>::vertex_descriptor v
                ,Graph& g
                ,typename CGAL::Geometric_graph_traits<Graph>::Point p
                );
  }
  {Sets \ccc{p} as the point of the vertex \ccc{v} belonging to the graph \ccc{g}.}

\ccHasModels
\ccRefIdfierPage{boost::graph_traits< CGAL::Polyhedron_3<Traits> const > }\\
\ccRefIdfierPage{boost::graph_traits< CGAL::Polyhedron_3<Traits> > }\\
\ccRefIdfierPage{CGAL::Geometric_graph_traits< CGAL::Polyhedron_3<Traits> > }\\

\end{ccRefConcept}

% +------------------------------------------------------------------------+
%%RefPage: end of main body, begin of footer
% EOF
% +------------------------------------------------------------------------+