cgal/Kernel_23/doc_tex/Kernel_23/kernel_tools.tex

\section{Kernel Related Tools}

\subsection{Introduction}

The following manual sections describe various tools that might be useful for
various kinds of users of the \cgal\ kernel. The kernel concept archetype
describes a minimal model for the \cgal\ kernel that can be used for testing \cgal\
kernel compatibility of geometrical algorithm implementations. It can be useful
for all people developing \cgal-style code that uses the \cgal\ kernel.

%say later something about Kernel checker
%say later something about Filter stuff 
%what else (converters ?) 

\subsection{Kernel Concept Archetype}

\subsubsection{Introduction}

\cgal\ defines the concept of a geometry kernel. Such a kernel provides types,
construction objects and generalized predicates. Most implementations of CG
algorithms and data structures in the basic library of \cgal\ were done in a way
that classes or functions can be parametrized with a geometric traits class. 

In most cases this geometric traits class must be a model of the \cgal\ geometry
kernel concept (but there are some exceptions).

The \cgal\ distribution comes with a number of models (or geometry kernels), for
instance the \ccHtmlNoLinksFrom{Cartesian} kernel (\ccc{CGAL::Cartesian}) or the homogeneous kernel
(\ccc{CGAL::Homogeneous}), that can be used with the packages of the basic
library.

But does it mean that packages of the basic library are fully compatible with
the \cgal\ kernel concept if they can be used with these \cgal\ kernel models? Not
necessarily, because such a package might also use member functions or global
functions/operators, that are implemented for \cgal\ kernel types but not for
other classes or kernels.

That's why it is important to verify whether the documented requirements of a
package are really covered by the implementation. Manual verification is error
prone, so there should be something better available in a generic library for
this application.

That's why the \cgal\ kernel concept archetype \ccc{CGAL::Kernel_archetype} was
developed. It provides all functionality required by the \cgal\ kernel concept,
but nothing more, so it can be seen as a minimal implementation of a model for
the \cgal\ kernel concept.  It can be used for testing successful compilation of
packages of the basic library with a minimal model. Deprecated kernel
functionality is not supported. All geometrical types (like the 2d/3d point or
segment types) of \ccc{CGAL::Kernel_archetype} have copy constructors, default
constructors and an assignment operator, and nothing else.  Comparison
operators are by default not supported, but can be switched on by the flag \ccc{
CGAL_CONCEPT_ARCHETYPE_ALLOW_COMPARISONS}.

The geometrical types of the concept archetype encapsulate no data members, so
run-time checks with the archetype are not very useful
(\ccc{CGAL::Kernel_archetype} is only meant for compilation checks with a
minimal model in the test-suites of \cgal\ packages).

The header file for the concept archetype is \ccc{CGAL/Kernel_archetype.h}.

The package supports the two- and three-dimensional part of the \cgal\ kernel
concept. The d-dimensional part is not supported.

\subsubsection{Restricting the Interface}

Normally packages of the Basic Library or Extension packages use only a small
subset of the functionality offered by models of the \cgal\ kernel concept. In
these cases testing with a model that offers only this (used and) documented
subset makes sense. \ccc{CGAL::Kernel_archetype} normally offers the full
functionality (all types, functors and constructions of a \cgal\ kernel model),
but it is possible to restrict the interface.\\ If you want to do this, you
have to define the macro \ccc{CGAL_CA_LIMITED_INTERFACE} (before the
inclusion of \ccc{CGAL/Kernel_archetype.h}) for switching on the interface
limitation. Now you have to tell the kernel archetype what types have to be
provided by it. For every type you have to define a macro.  The name of the
macro is \ccc{CGAL_CA_NAME_OF_KERNEL_TYPE}, where \ccc{
NAME_OF_KERNEL_TYPE} is the name of the kernel type (written in capitals)
that has to be provided by the kernel archetype for a specific package.  Lets
have a look at a small example. The kernel archetype has to provide in some
test suite a limited interface.  The interface has to offer type definitions
for \ccc{Point_3} and \ccc{Plane_3} and the 3d \ccHtmlNoLinksFrom{orientation} functor type
definition \ccc{Orientation_3}:

\ccHtmlLinksOff

\begin{ccExampleCode}
// limit interface of the Kernel_archetype
#define CGAL_CA_LIMITED_INTERFACE
#define CGAL_CA_POINT_3
#define CGAL_CA_PLANE_3
#define CGAL_CA_ORIENTATION_3

#include <CGAL/Kernel_archetype.h>
\end{ccExampleCode}

\ccHtmlLinksOn

Now other kernel functionality is removed from the interface of
\ccc{CGAL::Kernel_archetype}, so access to these other kernel types will result
in a compile-time error.
Another option is to use an own archetype class that encapsulates only the 
needed type definitions and the corresponding member functions. 
See the following code snippet for a simple example.

\ccHtmlLinksOff

\begin{ccExampleCode}
#include <CGAL/Kernel_archetype.h>

// build an own archetype class ...

// get needed types from the kernel archetype ...
typedef CGAL::Kernel_archetype           KA;
typedef KA::Point_3                      KA_Point_3;
typedef KA::Plane_3                      KA_Plane_3;
typedef KA::Construct_opposite_plane_3   KA_Construct_opposite_plane_3;

// reuse the types from the kernel archetype in the own archetype class
struct My_archetype {
  typedef KA_Point_3                    Point_3;
  typedef KA_Plane_3                    Plane_3;
  typedef KA_Construct_opposite_plane_3 Construct_opposite_plane_3;
  
  Construct_opposite_plane_3
  construct_opposite_plane_3_object()
  { return Construct_opposite_plane_3(); }
};
\end{ccExampleCode}

\ccHtmlLinksOn

\subsubsection{Example Program}

The following example shows a program for checking the 2d convex hull algorithm
of CGAL with the archetype. You can see the usage of the
\ccc{CGAL::Kernel_archetype} that replaces a \cgal\ kernel that is normally used.

\ccHtmlLinksOff

{\bf test\_convex\_hull\_2.cpp :}

\begin{ccExampleCode}
#include <CGAL/basic.h>
#include <CGAL/convex_hull_2.h>
#include <CGAL/Kernel_archetype.h>
#include <list>

typedef CGAL::Kernel_archetype      K;
typedef K::Point_2                  Point_2;

int main()
{
  std::list<Point_2> input;
  
  Point_2 act;
  input.push_back(act);

  std::list<Point_2> output;

  K  traits;

  CGAL::convex_hull_2(input.begin(), input.end(),
                      std::back_inserter(output), traits);		        
  return 0;
}
\end{ccExampleCode}

\ccHtmlLinksOn