cgal/Packages/PS_Stream/doc/ref.tex

\chapter{CGAL 3D Viewer}

\section{Introduction}
\ccc{Viewer\_3} is a CGAL class that implements a three dimensional viewer for 
geometric objects. It is based on OpenGL for the graphic part and FLTK 
(Fast Light Tools Kit)
for the window, the widgets and the events handling. \\
As it uses OpenGL graphic capabilities, the viewer can display
3-dimensional objects with full graphic quality (including lights,
material properties, textures, special effects as blending
or fog...). Obviously, the cost in time computation is proportional
to the quality of the rendering.\\
The FLTK library provides all the necessary tools to add
interacivity to the interface : buttons, menu bars, sliders,
browsers, windows and subwindows, mouse events handling...\\
The class \ccc{Viewer\_3} is build as a multithreading application. The avantage is 
that the main function can be interrupted easily with a stop signal,
giving control to the viewer thread. A simple click on the viewer
``Exit thread'' button suspends the viewer thread and wakes up the main
one. As some platform doesn't support multithreading application, a
flag \ccc{USE\_THREAD} has to be set in the makefile to allow
multithreading functionnalities.\\
Graphical geometric objects inherit from a virtual class 
\ccc{Drawable\_object}. All of them have the same interface. They are stored by the
viewer in a two level scene graph that can be accessed interactively
with the viewer window or by functions in the main program. \\
In order to use the \ccc{Viewer\_3}, you will need to install the FLTK
library (http://www.fltk.org/about.html) and the OpenGL (or Mesa)
library (http://www.opengl.org/, http://mesa3d.sourceforge.net/).

\section{Global view}

The package contains two major classes : \ccc{Viewer\_3} and 
\ccc{GL\_win}. Two more classes implement the scene graph : \ccc{Scene\_graph} and \ccc{Scene\_group}. Several classes are provided to
define drawable objects which inherit from a single virtual class :
\ccc{Drawable\_object}. 
\\
More information about these classes can be found in the user manual.

\begin{ccClass}{Viewer_3}
\section{The Viever Class \protect \ccClassTemplateName}

This is the main class that implements the viewer by itself. It
contains several widgets (and associated callback functions) to
interact whith it and a \ccc{GL\_win} to display OpenGL graphic
commands. The \ccc{GL\_win} has a fixed size but its scale (the
dimension of the effective viewing volume) can be defined as a
parameter in the \ccc{Viewer\_3} constructor. The origine of the
system of coordinates is approximativelly (depend on the perspective
choosen) put in the middle of the viewing cube.

\ccInclude{CGAL/Viewer_3.h}

\ccTypes
\ccThree{typedef void (*User_ctr_win User_ctr_win and so on }{}{A
function pointer and so on and so on and so on}
\ccThreeToTwo
 
\ccTypedef{typedef void (*User_ctr_win)(GL_win *,Viewer_3 *) User_ctr_win;}{A
function pointer used as type for the member function
\ccc{set\_custom\_panel(User\_ctr\_win)}.}




\subsection{Functionalities}

\ccCreation
\ccCreationVariable{w}
\ccThree{Viewer_3();}{t = tr bidulebidulebidulebidule}{}
\ccThreeToTwo
\ccConstructor{Viewer_3();}{Defines and displays a new viewer with a
viasualization window scaled on a 500~$\times$~500~$\times$~500 units cube. }

\ccConstructor{Viewer_3(int scale);}{Defines and displays a new viewer scaled on a scale~$\times$~scale~$\times$~scale units cube.}

\ccHeading{Adding things}

\ccMethod{void add_group();}{Adds a new empty group at the end of the
scene graph.}

\ccMethod{void add_drawable(Drawable_object* obj, int g=1);}{Adds the
drawable object obj into the group g.}

\ccAccessFunctions

\ccMethod{pthread_t get_window_thread();}{Returns window's thread.}

\ccMethod{Size get_size();}{Returns the default drawable object \ccc{Size}.}

\ccMethod{Style get_style();}{Returns the default drawable object
\ccc{Style}.}

\ccMethod{Precision get_precision();}{Returns the default drawable
object \ccc{Precision}.}

\ccMethod{Color get_color(int i);}{Returns the default viewer first \ccc{Color} if i=1, the second \ccc{Color} elsewhere.}

\ccMethod{GL_win* get_window();}{Returns a pointer on the \ccc{GL\_win} member.}

\ccMethod{int get_group();}{The total number of groups in the scene graph.}

\ccHeading{Setting}

\ccMethod{void reset();}{Sets to identity all transformation
matrices.}

\ccMethod{void reset_groups();}{for all groups, sets all local
transformations matrices to identity.}

\ccMethod{void set_size(Size s);}{Sets the default drawable object \ccc{Size}
to s.}
\ccMethod{void set_style(Style s);}{Sets the default drawable object \ccc{Style}
to s.}

\ccMethod{void set_precision(Precision p);}{Sets the default drawable object
\ccc{Precision} to p.}

\ccMethod{void set_color(Color c, int i);}{Sets the default viewer
first \ccc{Color} to c if i=1, the second elsewhere.}
\ccMethod{void set_custom_panel(User_ctr_win fct);}{Sets the viewer 
user panel to be defined by the function \ccc{fct}.}

\ccMethod{void set_mouse_push_handler(GL_win::Mouse_click hand_fct);}{Sets the
mouse push handler for the user mode menu to be \ccc{hand\_fct} function.}

\ccMethod{void set_mouse_release_handler(GL_win::Mouse_click hand_fct);}{Sets the
mouse release handler for the user mode menu to be\ccc{ hand\_fct} function.}

\ccMethod{void set_mouse_grab_handler(GL_win::Mouse_grab hand_fct);}{Sets the
mouse grab handler for the user mode menu to be \ccc{hand\_fct} function.}

\ccHeading{Insertion, Removal}

\ccMethod{void add_drawable(Drawable_object* obj , int gr=1);}{Adds
drawable \ccc{obj} to the scene graph in group \ccc{gr}.}

\ccMethod{void remove_drawable(int gr, int i);}{Removes in group \ccc{gr}, the
drawable indiced by \ccc{i}.}

\ccMethod{void delete_drawable(int gr, int i);}{Deletes in group\ccc{gr}, the
drawable indiced by \ccc{i}. The drawable is definitely deleted.}

\ccMethod{void delete_selection();}{Deletes selection made in the
viewer graph browser.}

\ccMethod{void delete_group(int g);}{Deletes the group of drawables
indiced by g;}

\ccHeading{Miscellaneous}

\ccMethod{void display();}{Displays the content of the scene graph on
the screen. Necessary to call each time a modification is done on the
scene.}

\ccMethod{void init_window_thread();}{Inits viewer thread. This function
has to be called only if mode multi-threads is choosen.}

\ccMethod{void main_loop();}{Launches the viewer main loop. If
multi-threading is used, then the function \ccc{init\_window\_thread()} will 
automatically calls the \ccc{main\_loop()}. If not, \ccc{main\_loop()} has to be
explicitaly calls at the end of the main program.}

\end{ccClass}

\begin{ccClass}{GL_win}

\section{The GL window class \protect \ccClassTemplateName }


The class \ccc{GL\_win} implements the visualisation window where OpenGL
primitives are displayed. It also contains matrices for tranformation, 
mouse events catched into the \ccc{GL\_win} and associated
callbacks. \ccc{GL\_win} object is the main data member of the class \ccc{Viewer\_3}. For elementary
usage of the viewer, users do not have to interfer with the \ccc{GL\_win}
object and use \ccc{GL\_win} member functions. For developping more advanced 
application (such as defining a custom actions), it could be necessary 
to access some of the \ccc{GL\_win} function and parameters.

\ccInclude{CGAL/GL_win.h}

\ccTypes
\ccThree{typedef void (*Mouse_grab)(int, int, int, int, int, int, int,
GL_win *) Mouse_grab;}{}{A function pointer and so on and so on and so on}
\ccThreeToTwo

\ccTypedef{typedef void (*Mouse_click)(int, int, int, GL_win *)
Mouse_click;}{Used to defined a function to set a custom mouse click event.}
\ccGlue
\ccTypedef{typedef void (*Mouse_grab)(int, int, int, int, int, int,
int, GL_win *) Mouse_grab;}{Used to defined a function to set a custom mouse grab event.}

\ccCreation
\ccCreationVariable{win}
\ccThree{GL_win();}{t = tr bidulebidulebidulebidule}{}
\ccThreeToTwo
\ccConstructor{GL_win(int x,int y,int w,int h,int s,const char*
l=0);}{Defines a windows in the wiever having \ccc{x,y,w,h} coordinates (see
FLTK coordinates style for widgets : \ccc{x,y} : top-left corner,
\ccc{w} : width and \ccc{h}: height of the widget). \ccc{s} is used for the scale of the
viewing volume (see \ccc{Viewer_3} description and constructor). A
scale of \ccc{s} will displays objects
with coordinates included in $ [- \frac{s}{2} , + \frac{s}{2} ]
\times [- \frac{s}{2} , + \frac{s}{2} ] \times [- \frac{s}{2} , +
\frac{s}{2} ] $ viewing cube.}



\subsection{Functionalities}
\ccHeading{Setting}

\ccMethod{void set_angle(float ag);}{Sets camera view angle in
perspective projection.}

\ccMethod{void set_deep(float dp);}{Sets deepth field of view;}

\ccMethod{void set_projection(bool b);} {Sets the projection mode. If true, 
mode is in perspective else, in orthogonal.}

\ccMethod{void set_mouse_push_handler(Mouse_click fct);}{Sets mouse events 
callbacks (see \ccc{Viewer\_3} class);}

\ccMethod{void set_mouse_release_handler(Mouse_click fct);}{Sets mouse events 
callbacks (see \ccc{Viewer\_3} class);}

\ccMethod{void set_mouse_grab_handler(Mouse_click fct);}{Sets mouse events 
callbacks (see \ccc{Viewer\_3} class);}

\ccMethod{void set_mode(int i);}{Sets the visualization mode :
``View'', ``insert point'', ``Slice'', ``User mode''.}

\ccMethod{void set_light_diff(float,float,float);}{Sets light RGB
parameters.}

\ccMethod{void set_light_variation(float);}{Sets light intensity.}

\ccMethod{void set_light_shy(float);}{Sets material shininess;}

\ccMethod{void set_X_light_pos(float);}{Sets light position in
x-coordinate;}


\ccMethod{void set_Y_light_pos(float);}{Sets light position in
y-coordinate;}

\ccMethod{void set_Z_light_pos(float);}{Sets light position in
z-coordinate;}

\ccMethod{void set_clip_planes(int);}{Sets the clip planes for the
slice mode : 0 means x-y plane, 1, x-z, 2, y-z;}

\ccMethod{void set_clip_width(float w,int s);} {Sets the width to \ccc{w} for
slice \ccc{s} (0,1,2);}

\ccMethod{void set_clip_move(float t,int s);}{Sets the translation for
slice \ccc{s} (0,1,2) in respect to the original position of the slice;}

\ccMethod{void set_bgcolor(Color c);}{Assignes background color to \ccc{c};}

\ccMethod{void set_light();}{Reset the lightning. Needs to be called
when light parameters are modified.}

\ccMethod{void set_light(bool);}{Sets the light to be on/off (true/false);}

\ccHeading{Access functions}

\ccMethod{vector<double> get_real_point(int i,std::vector<double>
p);}{Apply to point p (represented by a vector) all the oposite
matrices transformation (the  global matrix of the whole scene and the
local matrix to groupe \ccc{i}) and return the new vector.}

\ccMethod{vector<double> get_point();}{Returns the coordinates
(expressed in the viewer coordinates system not in the user one. To
have the coordinates in the user coordinates system, apply
\ccc{get_real_point} on it) of the point generated by the ``insert point'' mode.}

\ccMethod{Drawable_object* get_drawable(int gr, int ind);}{Returns a
pointer to the drawable object indiced by \ccc{ind}, in group \ccc{gr}.}

\ccMethod{double* get_transform();}{Returns the global transformation
matrix;}

\ccMethod{Scene_graph* get_scene_graph();}{Return the scene graph reference.}

\ccHeading{Adding, removing}

\ccMethod{void delete_group(int gr);}{Deletes group\ccc{ gr}.}

\ccMethod{void add_new_group();}{Adds a new empty group at the end of
the scene graph.}

\ccMethod{void add_point_to_object(int gr,int obj,std::vector<double>
pt);}{Adds point \ccc{pt} (represented by a vector) to object \ccc{obj} in group
\ccc{gr}. The object has to be an drawable object based on point that
implement its \ccc{add\_point} function (see \ccc{Drawable\_objects}).}

\ccMethod{void add_drawable(Drawable_object* obj, int i);}{Adds drawable
\ccc{obj} in group \ccc{gr}.}

\ccMethod{void remove_drawable(int gr, int obj);}{Removes drawable  \ccc{obj} 
in group \ccc{gr}.}


\ccHeading{Miscellaneous}

\ccMethod{void reshape();}{Defines the projection matrix and enable
some Open GL functionalities.}

\ccMethod{void reset();}{Resets the all the transformations matrices
(global and for each group).}

\ccMethod{void redraw();}{Draws the scene and swaps the buffers.}

\ccMethod{void make_visible(int gr);}{Sets the group \ccc{gr} to be
displayable in the viewer.}

\ccMethod{void change_visibility(int gr , int obj, bool b);}{Changes the
visibility status for object \ccc{obj} in group \ccc{gr}.}

\ccMethod{void group_visible(bool b, int gr);}{Changes the
visibility status in group \ccc{gr}.}

\ccMethod{void change_group(int val);}{Sets \ccc{val} to be the number of
groups present in the scene graph.}

\ccMethod{void clean_graph();}{Removes empty groups eventually present 
in scene graph.}

\ccMethod{void switch_light();}{Switches the light : on/off.}


\end{ccClass}

\begin{ccClass}{Drawable_object}

\section{The Drawable Object Class and its inherited ones : \protect \ccClassTemplateName}

The class \ccc{Drawable\_object} is a virtual class that implement the
generic representation for a drawable object. All drawable objects
contained in the scene graph derive from this virtual class. The
principal functions it defines are not implemented in the virtual
\ccc{Drawable\_object} class but in its derived classes, as each drawable
has its proper way to draw itself, compute its gravity center and so
on. 

\ccInclude{CGAL/Drawable_object.h}

For streams support and users comfort, some types (\cgal\ types) are
defined :

\ccTypes
\ccThree{typedef unsigned char Precision}{}{The Rendering quality for 
a drawable object.}
\ccThreeToTwo

\ccEnum{enum Style {FILL=1, WIRE, RAW, FOS1, FOS2, FOS3, FOS4, FOS5};}{FILL, WIRE and RAW are standard styles for drawables, and FOS are
special styles for facets objects.}

\ccTypedef{typedef int Size;}{The size of a drawable object.}
\ccGlue
\ccTypedef{typedef unsigned char Precision;}{The Rendering quality for 
a drawable object.}

A drawable object has several data members : two colors, style,
precision and center of mass. It also has an OpenGL display list flag, 
\ccc{lind},  for the object that said if OpenGL display list (to speed up GL
computation) is already computed or not; \ccc{lind} is 0 if the object has
never been drawn (no call to draw function) and 1 when the first call to
draw is made. If the object is change (color, add of point, etc), \ccc{lind}
must be reset to 0 to force the draw function to rebuild the display
list. (see OpenGL programming manual for more information on display
lists).




\ccCreation
\ccCreationVariable{obj}
\ccThree{Drawable_object();}{t = tr bidulebidulebidulebidule}{}
\ccThreeToTwo
\ccConstructor{Drawable_object();}{Empty constructor;}

\subsection{Functionalities}


\ccMethod{virtual void draw();}{Virtual drawing method.}

\ccMethod{void set_center();}{Generic function to compute the gravity
center of the object.}

\ccMethod{double get_center(int i);}{Returns the i-coordinate of the
gravity center (i=0,1,2).}

\ccMethod{void set_style(Style s);}{Sets the objects drawing style to
be s.}
\ccMethod{void set_colors(Color c1, Color c2);}{Sets the color to \ccc{c1} and
the second color to \ccc{c2}.}

\ccMethod{void set_color1(Color c1);}{Sets the first color to \ccc{c1}.}

\ccMethod{void set_color2(Color c1);}{Sets the second color to \ccc{c1}.}

\ccMethod{virtual void add_point(double x, double y, double
z);}{Virtual function to add a point to an object.}
\end{ccClass}

\subsection{Predifined drawable objects}

The file \ccc{draw\_CGAL\_Object.h} implements several drawable objects 
in two and three dimensions. All these classes are derived (public) from the
virtual interface \ccc{Drawable\_object} and are templated by a geometric
object. All these drawables are using \cgal\ standard acces functions
for accessing coordinates of objects. All coordinates number types
(for the template objects) must support the \cgal\ standard
\ccc{to_double} function. Note that all drawables make a copy of the
\cgal\ object they represent. 

\ccInclude{CGAL/draw\_CGAL\_Object.h}

\subsubsection{Two dimensional objects.}

\ccCreation
\ccCreationVariable{obj}
\ccThree{Drawable_object();}{t = tr bidulebidulebidulebidule}{}
\ccThreeToTwo


\begin{ccClassTemplate}{Drawable_point_2<Point2>}

\ccConstructor{Drawable_point_2(const Point2& p, Color c, Style
		   sty=RAW, Size s = 5 , Precision
		   prec=5);}{Object constructor.The \ccc{Point2} must provide 
 \ccc{x()} and  \ccc{y()} access functions.}


\ccConstructor{Drawable_point_2(const double& x1,const double& y1,
		    Color c, Style sty=RAW, Size s = 5 , Precision
		    prec=5);}{Object constructor. A \ccc{Point_2}
template parameter type on double coordinates must be provided.}
\end{ccClassTemplate}

\begin{ccClassTemplate}{Drawable_segment_2<Segment2>}
\ccConstructor{Drawable_segment_2(const Segment2& sg, Color c, Style
sty= RAW, Size s=2, Precision prec=0);}{The \ccc{Segment2} type must provide
 \ccc{target().x()} and  \ccc{source().y()} access functions.}
\end{ccClassTemplate}


\begin{ccClassTemplate}{Drawable_line_2<Line2>}
\ccConstructor{Drawable_line_2(const Line2& ln, Color c, Style
sty= RAW, Size s=2, Precision prec=15);}{The \ccc{Line2} type must provide
 \ccc{point(int i).x()} acces \ccc{point(int i).y()} access functions.}
\end{ccClassTemplate}

\begin{ccClassTemplate}{Drawable_ray_2<Ray2>}
\ccConstructor{Drawable_ray_2(const Ray2& ry, Color c, Style
sty= RAW, Size s=2, Precision prec=15);}{The \ccc{Ray2} type must provide
 \ccc{point(int i).x/y()} function and source().x/y() function.}
\end{ccClassTemplate}

\begin{ccClassTemplate}{Drawable_triangle_2<Triangle2>}
\ccConstructor{Drawable_triangle_2(const Triangle2& 
tri, Color c1, Color c2=BLACK, Style sty=FILL, Size s=2, Precision prec=0);}{The
\ccc{Triangle2} must provide \ccc{tr[i].x/y()} (i=0,1,2) access functions.}
\end{ccClassTemplate}

\begin{ccClassTemplate}{Drawable_circle_2<Circle2>}
\ccConstructor{Drawable_circle_2(const Circle2& 
crl, Color c, Style sty= RAW, Size s=5, Precision prec=5);}{The
\ccc{Circle2} type must have  \ccc{center().x/y()}  and
\ccc{squared\_radius()} functions.}
\end{ccClassTemplate}


\begin{ccClassTemplate}{Drawable_triangulation_2<Triangulation2>}
\ccConstructor{Drawable_triangulation_2(triangulation_2* tri, Color c1,
Color c2, Style sty=WIRE, Size s=5, Precision prec=15);}{ The
\ccc{Triangulation2} must provide a \cgal\ like interface
(\ccc{Edge_iterator, Vertex_iterator, Vertex_handle, Face_handle} and
functions associated to them).}
\end{ccClassTemplate}

\subsubsection{Three dimensional objects.}

\begin{ccClassTemplate}{Drawable_point_3<Point3>}
\ccConstructor{Drawable_point_3(const Point3 &p, Color c, Style
sty=FILL, Size s=5, Precision prec=15);}{The type \ccc{Point3} must provide
 \ccc{x()},  \ccc{y()},  \ccc{z()} access functions.}
\end{ccClassTemplate}


\begin{ccClassTemplate}{Drawable_point_3<Point3>}
\ccConstructor{Drawable_point_3(const double& x, const double& y,const
double& z, Color c, Style
sty=FILL, Size s=5, Precision prec=15);}{Constructor with three double 
for coordinates. A \ccc{Point_3} template type parameter on double
cordinates must be provided.}
\end{ccClassTemplate}

\begin{ccClassTemplate}{Drawable_points_set_3<InputIterator, Point3>}
\ccConstructor{Drawable_points_set_3(InputIterator first,
InputIterator last, Color c, Style
sty=FILL, Size s=5, Precision prec=15);}{\ccc{first} and \ccc{last}
are iterators on a container containing \ccc{point3} objects.}
\end{ccClassTemplate}

\begin{ccClassTemplate}{Drawable_segment_3<segment3>}
\ccConstructor{Drawable_segment_3(const segment3& sg, Color c, Style
sty=RAW, Size s=5, Precision prec=15);}{The type \ccc{segment3} must
provide \ccc{source()} and \ccc{target()} access functions.}
\end{ccClassTemplate}

\begin{ccClassTemplate}{Drawable_line_3<line3>}
\ccConstructor{Drawable_line_3(const line3& ln, Color c, Style
sty=RAW, Size s=2, Precision prec=15);}{The type \ccc{line3} must
provide \ccc{point(int)} function.}
\end{ccClassTemplate}

\begin{ccClassTemplate}{Drawable_ray_3<line3>}
\ccConstructor{Drawable_ray_3(const ray3& ry, Color c, Style
sty=RAW, Size s=2, Precision prec=15);}{The type \ccc{ray3} must
provide \ccc{point(int)} and source() functions.}
\end{ccClassTemplate}

\begin{ccClassTemplate}{Drawable_triangle_3<triangle3>}
\ccConstructor{Drawable_triangle_3(const triangle3& tri, Color c, Style
sty=WIRE, Size s=2, Precision prec=0);}{The type\ccc{triangle3} must
provide \ccc{tr[i]} for accessing vertices and \ccc{x()},  \ccc{y()},
\ccc{z()} access functions for coordinates of each vertex.}
\end{ccClassTemplate}

\begin{ccClassTemplate}{Drawable_tetrahedron_3<tetrahedron3>}
\ccConstructor{Drawable_tetrahedron_3(const tetrahedron3& tri, Color c, Style
sty=FILL, Size s=2, Precision prec=0);}{The type \ccc{tetrahedron3} must
provide  \ccc{tr[i]} for accessing vertices and  \ccc{x()},
\ccc{y()},  \ccc{z()} access functions for coordinates of each vertex.}
\end{ccClassTemplate}

\subsubsection{Three dimensional facet objects.}

The file \ccc{facet\_object.h} implements a special kind of drawable object : 
a generic implementation for 3-dimensional object that can be
represented with facets (triangulations, polyhedral surfaces,...). A
special menu is defined in the viewer window to interact with these
kind of objects, essentially, by offering several predefined way to
display them. 

\ccInclude{CGAL/facet\_object.h}

This file exports several \cgal\ types that are used into the
\ccc{Drawable\_facets\_object\_3} class and have to be used by user to
build the interface between its own geometric objects and a
\ccc{Drawable\_facets\_object\_3}. 

\ccTypes
\ccThree{typedef Gt::Triangleblblblnl}{}{the triangulatiooooooooooooooooooooooo}
\ccThreeToTwo

\ccTypedef{typedef  std::vector<double> vertex ;}{The vertex type.}
\ccGlue
\ccTypedef{typedef  std::vector<vertex> edge ;}{The edge type.}
\ccGlue
\ccTypedef{typedef  std::list<vertex> facet;}{The facet type.}
\ccGlue
\ccTypedef{typedef  std::list<vertex> list_vertices;}{A list of
vertices.}
\ccGlue
\ccTypedef{typedef  std::list<edge>   list_edges;}{A list of edges.}
\ccGlue
\ccTypedef{typedef  std::list<facet>   list_facets;}{Alist of facets.}

The user must provide its own interface between its object and a
\ccc{Drawable\_facets\_object\_3} in the form of three functions :

\ccThree{typedef Gt::Triangle}{}{the triangulatiooooooooooooooooooooooo}
\ccThreeToTwo
\ccFunction{template <class facet_object> list_vertices
get_vertices(const facet_object &fo);} {Returns the list of vertices
of the object \ccc{fo}.}

\ccFunction{template <class facet_object> list_edges get_edges(const
facet_object &fo);} {Returns the list of edges of the object \ccc{fo}.}

\ccFunction{template <class facet_object> list_facets get_facets(const
facet_object &fo);}{Returns the list of facets of the object\ccc{fo}.}

(Warning : this interface may change in futur)

Facet objects of class \ccc{Drawable\_facets\_object\_3} are like regular
drawable objects (inherits from \ccc{Drawable\_object}). They are templated by
the geometric objects and the template class must be the same as the
one given to the three interface function described bellow. The style
can be of five type : \ccc{FOS1}, \ccc{FOS2}, \ccc{FOS3}, \ccc{FOS4} and \ccc{FOS5}. \ccc{FO1} is a raw
wire frame style, \ccc{FO2} adds raw vertices to the previous one, \ccc{FO3} is
wire frame style with only visible edges shown, \ccc{FO4} shows facets and
\ccc{FO5} is a nice wire frame style build with cylinders for edges and
spheres for vertices. 

\begin{ccClassTemplate}{Drawable_facets_object_3<facets_object_3>}
\ccConstructor{Drawable_facets_object_3(const facets_object_3 &obj
,char* name="Facet Object",Color c, Color c2=BLACK, Style sty=FOS1,
Sizes=2, Precision prec=10);}{Builds a new Drawable\_facets\_object\_3.}
\end{ccClassTemplate}


\begin{ccClass}{Scene_graph}
\subsection{The Scene graph Class, \protect \ccClassTemplateName}

The scene graph of the viewer is implemented in the file
\ccc{scene\_graph.h}. It looks like a list of scene groups and acts as a
container for these groups of drawable objects. It contains also the
transformation matrices (rotation, translation) for the scene and the
center of the scene as data members.

\ccInclude{CGAL/scene\_graph.h}

\ccTypes
\ccThree{typedef Gt::Triangle}{}{the triangulatiooooooooooooooooooooooooo00000}
\ccThreeToTwo

\ccTypedef{typedef Scene_graph::iterator;}{Iterator over all groups of 
the scene graph.}




\ccCreation
\ccCreationVariable{sg}
\ccThree{Scene_graph()graph;}{t = tr bidulebidulebidulebidule}{}
\ccThreeToTwo
\ccConstructor{Scene_graph();}{Builds a new scene graph with one empty 
group. Transformation matrices are set to identity.}


\subsection{Functionalities}
\ccHeading{Setting}

\ccMethod{void set_identity();}{Sets the two transformation matrices
to identity;}

\ccMethod{void set_scene_center();}{Computes the center of mass of
the scene.}

\ccMethod{void make_visible(int gr);}{Sets all objects of group gr to
be visible (selected in the scene browser).}


\ccMethod{void change_visibility(int gr, int obj, bool b);}{Sets the
visibility status of objetct \ccc{obj} in group \ccc{gr} to be \ccc{b};}

\ccMethod{void group_visible(bool b, int gr);}{Sets the visibility status of
group \ccc{gr} to be \ccc{b};}

\ccMethod{void set_rotation();}{Sets the rotation matrix to the current 
matrix defined in the top of the OpenGL modelview matrix stack.}

\ccMethod{void set_translation(double x, double y);}{Sets the
x/y-coordinates for the global translation matrix.}


\ccHeading{Adding and remove}



\ccMethod{void add_new_group(Drawable_object* obj);}{Adds a new group
to scene graph containing object \ccc{obj}.}

\ccMethod{void add_new_group();}{Adds a new empty group.}

\ccMethod{void delete_group(int gr);}{Deletes group \ccc{gr};}

\ccMethod{void add_drawable(Drawable_object* obj, int gr=1);}{Adds
drawable object \ccc{obj} in group \ccc{gr}.}

\ccMethod{int remove_drawable(int gr, int obj);}{Removes drawable \ccc{obj}
from group \ccc{gr}. Do nothing if no object indiced by \ccc{obj} in
\ccc{gr} or no group \ccc{gr} exist.}

\ccMethod{void add_point_to_object(int gr, int obj, float x, float y,
float z);}{Adds as point having x/y/z/-coordinates to object \ccc{obj} in
group \ccc{gr}. Object must have \ccc{add\_point()} method defined.}

\ccHeading{Accessing}

\ccMethod{Drawable_object* get_drawable(int gr, int obj);}{Returns a
pointer on the drawable \ccc{obj} in group \ccc{gr}.}
  

\ccMethod{double get_center(int i);}{Returns x/y/z coordinates (0,1,2) 
of scene center of mass.}

\ccMethod{int get_size();}{Returns the size of the scene graph (ie,
the number of groups it contains).}

\ccMethod{double* get_rotation();}{Returns the scene rotation matrix;}

\ccMethod{double* get_translation();}{Returns the scene translation
matrix;}

\ccMethod{double* get_group_translation(int gr);}{Returns the matrix of 
translation of group gr.}


\ccMethod{double* get_group_rotation(int g);}{Returns the matrix of 
rotation of group \ccc{gr}.}

\ccMethod{bool group_visible(int g);}{Returuns if a group is visible or 
not (name to be changed!).}


\ccHeading{Iterators}

\ccMethod{iterator begin();}{Iterator over all groups.}

\ccMethod{iterator end();}{past-the-end iterator.}

\ccHeading{Miscellaneous}

\ccMethod{void change_group(int orig, int obj, int dest);}{Moves
object \ccc{obj} from group \ccc{orig} to group\ccc{dest}.}

\ccMethod{void clean_graph();}{Browses the scene graph and remove
empty groups.}


\end{ccClass}
\begin{ccClass}{Scene_group}
\subsection{The scene group, \protect \ccClassTemplateName}

Scene groups are the elementary drawable objects containers. It is
implemented in the file \ccc{scene\_group.h}. An object of class
\ccc{Scene\_group} contains a vector of drawable object, informations about the
visibility of the group and its objects, its center of mass and two
local transformation matrices for rotation and translation. It exports 
its own iterator type to browse through the objects of the group.

\ccInclude{CGAL/scene\_group.h}

\ccTypes
\ccThree{typedef Gt::Triangleblblblnl}{}{the triangulatiooooooooooooooooooooooo}
\ccThreeToTwo

\ccTypedef{typedef Scene_group::iterator;}{Iterator over all groups of 
the scene graph.}




\ccCreation
\ccCreationVariable{gr}
\ccThree{Scene_graph()group;}{t = tr bidulebidulebidulebidule}{}
\ccThreeToTwo
\ccConstructor{Scene_group();}{Builds a new scene
group. Transformation matrices are set to identity.}


\ccConstructor{Scene_group(std::vector<Drawable_object*> l);}{Builds a
new scene group containing drawable objects included in \ccc{l}.}

\ccConstructor{Scene_group(Drawable_object* obj);}{Builds a
new scene group containing the object \ccc{obj}.}

\subsection{Functionalities}

\ccHeading{Setting}

\ccMethod{void set_scene_center();}{Sets the center of mass for the
group.}

\ccMethod{void set_rotation(float y, float x, double* Mw);}{Modifies the
rotation matrix around x/y axis for the group. The matrix \ccc{Mw} is the
global transformation matrix (rotation and translation) for the
scene.}

\ccMethod{void set_translation(float x, float y, double* Mw);}{Idem as 
previously for translation.}

\ccMethod{void change_visibility(int obj,bool b);}{Sets the visibility 
of the object \ccc{obj} to be\ccc{b}.}

\ccMethod{void all_visible();}{Sets all objects in the group to be
visible.}

\ccMethod{void group_visible(bool b);}{Sets the visibility status of
the group to be\ccc{b}.}


\ccHeading{Accessing}

\ccMethod{double get_center(int i);}{Returns the x/y/z-coordinates of
the center of mass for the group.}

 \ccMethod{int get_size();}{Returns the size of the group (i.e., the
number of drawable object it contains).}

\ccMethod{Drawable_object* get_drawable(int obj);}{Returns the
reference of the drawable \ccc{obj}.}

\ccMethod{double* get_group_rotation();}{Returns the rotation matrix
for the group.}

\ccMethod{double* get_group_translation();}{Returns the translation matrix
for the group.}

\ccMethod{bool group_visible();}{Return the visibility status for the
group.}

\ccHeading{Adding and remove}

\ccMethod{void add_to_group(Drawable_object* obj);}{Adds the drawable
\ccc{obj} to the group.}

\ccMethod{int remove_drawable(int i);}{Remove the drawable of indice \ccc{i} 
from the group.}

\ccMethod{void add_point_to_object(int i, float x, float y, float
z);}{Adds \ccc{point(x,y,z)} to object \ccc{i}. Object \ccc{i} must
have an \ccc{add\_point()} method defined. If not, nothing is done.}


\ccHeading{Iterators}

\ccMethod{iterator begin();}{Iterator over all groups.}

\ccMethod{iterator end();}{past-the-end iterator.}

\ccHeading{Miscellaneous}

\ccMethod{void draw_group();}{Draws group without regarding of
visibility status. This function has to be called inside a more
general display function that define all the viewer parameters}

\ccMethod{void draw_visible();}{Draws group. Only visible objects are
drawn.}

\ccMethod{void draw_invisible();}{Draws group. Only invisible objects are
drawn.}



\end{ccClass}


\subsection{Stream support}

\cgal\ objects could directly be sended to the viewer via standard
streams. In this case, drawable objects are automatically builded with 
default parameters. Streams are provided for \cgal\ objects (see the
listing bellow), for \ccc{Color}, \ccc{Size} and \ccc{Precision}. For
user defined drawable objects, the implementor must provide a
\ccc{convert_type} for its drawable type that build a drawable object
and send it to the viewer. This function will be automaticaly called
by the stream operator. 

\ccInclude{CGAL/Viewer_stream.h}

\subsubsection{Input streams}

\ccThree{Viewer_3& operator}{operator<<(Viewer_3& W, Style s);}{}
\ccThreeToTwo
\ccFunction{Viewer_3& operator<<(Viewer_3& W, Object o);}
{Sends the object \ccc{o} to the viewer.}

\subsubsection{Convert functions}

The stream operator for a \cgal\ object is defined generically for any 
object type. It calls a function named \ccc{convert_type(Object o,
Viewer_3 &W)} that returns a reference to a drawable object build with
default parameters stored in the viewer. Each \cgal\ object should
implements such \ccc{convert_type} function in order to use the viewer 
stream. 

The interface for such function is as follows :

\begin{cprog} 
template <class R>
Drawable_Object<Object<R> >*
convert_type(Object<R> p, Viewer_3 &W)
{
  Drawable_Object<Object<R> >* d_obj = new
    Drawable_Object<Object<R> >(p,W.get_color(),W.get_style(),W.get_size(),W.get_precision());
  return(d_obj);
}
\end{cprog}

The file \ccc{Viewer_stream.h} provides \ccc{convert_type} functions
for the kernel objects : 

\ccc{Point_3<R>},  \ccc{Segment_3<R>}, \ccc{Triangle_3<R>},
\ccc{Tetrahedron_3<R>}, \ccc{Line_3<R>}, \ccc{Ray_3<R>},
\ccc{Point_2<R>}, \ccc{Segment_2<R>}, \ccc{Line_2<R>}, \ccc{Ray_2<R>},
\ccc{Triangle_2<R>}, \ccc{Circle_2<R>}.

A function that takes a \ccc{std::vector<R>} with three elements and
returns a \ccc{Drawable_point_3} is also provided.

\subsubsection{Manipulators for assigning \ccc{Viewer_3} parameters}

The stream support offer stream facilities to set some Viewer
parameters like default colors, size, precision, etc. It use a manipulator class \ccc{O_manip} that implements
generic stream function :

\ccFunction{Viewer_3& operator<< (Viewer_3& W, const O_manip<Obj>&
m);}{}

In order to use it, a manipulator must be build. The
\ccc{Viewer_stream.h} defines several manipulator constructor for
standards parameters.

\ccFunction{O_manip<Precision> set_precision(Precision i);}{Defines a
manipulator to set the viewer default precision parameter.}
\ccGlue
 \ccFunction{O_manip<Color> set_color1(Color c);}{Defines a
manipulator to set the viewer default first color parameter.}
\ccGlue
 \ccFunction{O_manip<Color> set_color2(Color c);}{Defines a
manipulator to set the viewer default second color parameter.}
\ccGlue
\ccFunction{O_manip<Size> set_size(Size i);}{Defines a
manipulator to set the viewer default size parameter.}
\ccGlue
\ccFunction{O_manip<Style> set_style(Style i);}{Defines a
manipulator to set the viewer default style parameter.}



\subsection{Threads}

In order to run independently from the main program, the viewer, when
it is defined, launches its proper thread. In this way, user can stop
the main process and control the viewer and then get back to the main
program as often as he want. 
The threads package used is the pthread one. It run actually with
Solaris but some problems are known in linux if the library X has not 
been compile with multithreading options. The Viewer\_3 can be use with 
or without multithreading option by simply add a flag when build
object files : simply add -DUSE\_THREAD in your makefile or in the make 
command line. Also, if multithreading is use, the libpthread.so library
have to be added when linking and option -D\_REENTRANT (see example
makefiles).
The pthread package exports several functions working on threads and
we recommand that people that want to build their own mutithreading
structure have a look to the documentation of pthread functions. This
package provides a simple class for the viewer thread in the file
Threads.h. It provides one function called stop() that stops the main
thread giving control to the viewer thread.