songsenand
/
cgal
mirror of https://github.com/CGAL/cgal
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

- Use 80 columns.

This commit is contained in:
Sylvain Pion 2003-02-06 16:00:04 +00:00
parent 4f970f521e
commit 96c42cf8da
1 changed files with 65 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
Packages/Kernel_23/doc_tex/kernel/kernel_tools.tex
View File

@ -2,10 +2,11 @@
\section{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.
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
@ -15,61 +16,70 @@ all people developing CGAL-style code that uses the CGAL kernel.
\subsection{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.
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).
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 cartesian kernel (\ccc{CGAL::Cartesian}) or the homogeneous kernel (\ccc{CGAL::Homogeneous}),
that can be used with the packages of the basic library.
The CGAL distribution comes with a number of models (or geometry kernels), for
instance the 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 neccesarily, 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.
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
neccesarily, 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 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
{\em CGAL\_CONCEPT\_ARCHETYPE\_ALLOW\_COMPARISONS}.
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 {\em
CGAL\_CONCEPT\_ARCHETYPE\_ALLOW\_COMPARISONS}.
The geometrical types of the concept archetype encapsulate no data members, so runtime checks with the archetype
are not very useful (\ccc{CGAL::Kernel_archetype} is only meant for compilation checks with a minimal model in the testsuites
of CGAL packages).
The geometrical types of the concept archetype encapsulate no data members, so
runtime checks with the archetype are not very useful
(\ccc{CGAL::Kernel_archetype} is only meant for compilation checks with a
minimal model in the testsuites of CGAL packages).
The header file for the concept archetype is {\em 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.
The package supports the two- and three-dimensional part of the CGAL kernel
concept. The d-dimensional part is not supported.
\subsection{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 {\em CGAL\_CA\_LIMITED\_INTERFACE} (before the inclusion
of {\em 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 {\em CGAL\_CA\_NAME\_OF\_KERNEL\_TYPE}, where {\em 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 {\em Point\_3} and {\em Plane\_3} and the
3d orientation functor type definition {\em Orientation\_3}:
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 {\em CGAL\_CA\_LIMITED\_INTERFACE} (before the
inclusion of {\em 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 {\em CGAL\_CA\_NAME\_OF\_KERNEL\_TYPE}, where {\em
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 {\em Point\_3} and {\em Plane\_3} and the 3d orientation functor type
definition {\em Orientation\_3}:
\ccHtmlLinksOff
@ -85,14 +95,15 @@ The interface has to offer type definitions for {\em Point\_3} and {\em Plane\_3
\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.
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.
\subsection{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.
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
@ -118,7 +129,8 @@ int main()
K traits;
CGAL::convex_hull_2(input.begin(), input.end(), std::back_inserter(output), traits);
CGAL::convex_hull_2(input.begin(), input.end(),
std::back_inserter(output), traits);
return 0;
}
\end{ccExampleCode}