cgal/Geomview/doc_tex/Geomview_ref/Geomview_stream.tex

% +------------------------------------------------------------------------+
% | Reference manual page: Geomview.tex
% +------------------------------------------------------------------------+
% | 10.04.2002   Author
% | Package: Package
% | 
\RCSdef{\RCSGeomviewRev}{$Id$}
\RCSdefDate{\RCSGeomviewDate}{$Date$}
% |
%%RefPage: end of header, begin of main body
% +------------------------------------------------------------------------+


\begin{ccRefClass}{Geomview_stream}  %% add template arg's if necessary

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

\ccDefinition
 An object of the class \ccRefName\ is a stream in which geometric
objects can be inserted and where geometric objects can be extracted
from. The constructor starts Geomview either on the local either on
a remote machine. 

\ccInclude{CGAL/IO/Geomview_stream.h}




\ccCreation
\ccCreationVariable{gs}  %% choose variable name

\ccConstructor{Geomview_stream(const Bbox_3 &bbox 
	                                 = Bbox_3(0,0,0, 1,1,1),
				    const char *machine = NULL,
                                    const char *login = NULL);}
{Introduces a Geomview stream \ccVar\ with a camera that sees the
bounding box.  The command \ccc{geomview} must be in the user's \ccc{PATH}.
If \ccc{machine} and \ccc{login} are not \ccc{NULL},
Geomview is started on the remote machine using \ccc{rsh}.}

\ccOperations
\ccHeading{Output Operators for CGAL Kernel Classes}

\def\ccTagRmEigenClassName{\ccFalse}
%\def\ccTagOperatorLayout{\ccFalse}

At the moment not all classes of the \cgal\ kernel have output
operators. 2D objects are embedded in the \ccc{xy}-plane.

\ccFunction{template <class R>
            Geomview_stream&
            operator<<(Geomview_stream& G, const Point_2<R>& p);}
{Inserts the point \ccc{p} into the stream \ccVar.}

\newpage
\ccFunction{template <class R>
            Geomview_stream&
            operator<<(Geomview_stream& G, const Point_3<R>& p);}
{Inserts the point \ccc{p} into the stream \ccVar.}


\ccFunction{template <class R>
            Geomview_stream&
            operator<<(Geomview_stream& G, const Segment_2<R>& s);}
{Inserts the segment \ccc{s} into the stream \ccVar.}

\ccFunction{template <class R>
            Geomview_stream&
            operator<<(Geomview_stream& G, const Segment_3<R>& s);}
{Inserts the segment \ccc{s} into the stream \ccVar.}


\ccFunction{template <class R>
            Geomview_stream&
            operator<<(Geomview_stream& G, const Ray_2<R>& r);}
{Inserts the ray \ccc{r} into the stream \ccVar.}

\ccFunction{template <class R>
            Geomview_stream&
            operator<<(Geomview_stream& G, const Ray_3<R>& r);}
{Inserts the ray \ccc{r} into the stream \ccVar.}


\ccFunction{template <class R>
            Geomview_stream&
            operator<<(Geomview_stream& G, const Line_2<R>& l);}
{Inserts the line \ccc{l} into the stream \ccVar.}

\ccFunction{template <class R>
            Geomview_stream&
            operator<<(Geomview_stream& G, const Line_3<R>& l);}
{Inserts the line \ccc{l} into the stream \ccVar.}


\ccFunction{template <class R>
            Geomview_stream&
            operator<<(Geomview_stream& G, const Triangle_2<R>& t);}
{Inserts the triangle \ccc{t} into the stream \ccVar.}


\ccFunction{template <class R>
            Geomview_stream&
            operator<<(Geomview_stream& G, const Triangle_3<R>& t);}
{Inserts the triangle \ccc{t} into the stream \ccVar.}


\ccFunction{template <class R>
            Geomview_stream&
            operator<<(Geomview_stream& G, const Tetrahedron_3<R>& t);}
{Inserts the tetrahedron \ccc{t} into the stream \ccVar.}

\ccFunction{template <class R>
            Geomview_stream&
            operator<<(Geomview_stream& G, const Sphere_3<R>& s);}
{Inserts the sphere \ccc{s} into the stream \ccVar.}


\ccFunction{Geomview_stream&
          operator<<(Geomview_stream& G, const Bbox_2& b);}
{Inserts the bounding box \ccc{b} into the stream \ccVar.}

\ccFunction{Geomview_stream&
          operator<<(Geomview_stream& G, const Bbox_3& b);}
{Inserts the bounding box \ccc{b} into the stream \ccVar.}

\ccMethod{template < class InputIterator >
    void draw_triangles(InputIterator begin, InputIterator end);}
{[\ccc{begin};\ccc{end}) is an iterator range with value type
\ccc{Triangle_3<R>}.  This method uses the OFF format to draw several triangles
at once, which is much faster than drawing them one by one.}


\ccHeading{Input Operators for CGAL Kernel Classes}

At the moment input is only provided for points. The user has to select
a point on the {\it pick plane} with the right mouse button. The pick plane
can be moved anywhere with the left mouse button, before a point is entered.

\ccFunction{template <class R>
            Geomview_stream&
            operator>>(Geomview_stream& G, Point_3<R>& p);}
{Extracts the point \ccc{p} from the stream \ccVar. The point is
 echoed by default, and it depends on the stream echo mode status.}



\ccHeading{Output Operators for CGAL Basic Library Classes}

\ccInclude{CGAL/IO/Polyhedron_geomview_ostream.h}

\ccFunction{template <class Traits, class HDS>
Geomview_stream&
operator<<(Geomview_stream &G, const Polyhedron_3<Traits,HDS> &P);}
{Inserts the polyhedron \ccc{P} into the stream \ccVar.}

\ccInclude{CGAL/IO/Triangulation_geomview_ostream_2.h}

\ccFunction{template <class GT, class TDS>
Geomview_stream&
operator<<(Geomview_stream &G, const Triangulation_2<GT,TDS> &T);}
{Inserts the 2D triangulation \ccc{T} into the stream \ccVar.
 The actual output depends on whether the stream is in wired mode or not.
 Also note that in the case of terrains (when \ccc{GT::Point_2} is
 \ccc{Point_3<R>}), then the 3D terrain is displayed.}

\ccInclude{CGAL/IO/Triangulation_geomview_ostream_3.h}

\ccFunction{template <class GT, class TDS>
Geomview_stream&
operator<<(Geomview_stream &G, const Triangulation_3<GT,TDS> &T);}
{Inserts the 3D triangulation \ccc{T} into the stream \ccVar.
 The actual output depends on whether the stream is in wired mode or not.}

\ccHeading{Colors}

Geomview distinguishes between edge and face colors. The edge color
is at the same time the color of vertices. 

\ccMethod{Geomview_stream& operator<<(const Color& c);}
{Makes \ccc{c} the color of vertices, edges and faces in subsequent IO 
 operations.}

\ccMethod{Color set_bg_color(const Color& c);}
{Changes the background color. Returns the old value.}

\ccMethod{Color set_vertex_color(const Color& c);}
{Changes the vertex color. Returns the old value.}

\ccMethod{Color set_edge_color(const Color& c);}
{Changes the edge color. Returns the old value.}


\ccMethod{Color set_face_color(const Color& c);}
{Changes the face color. Returns the old value.}


\ccHeading{Miscellaneous}

\ccMethod{void clear();}
{Deletes all objects.}

\ccMethod{void pickplane();}
{Creates a pickplane (useful after a clear).}

\ccMethod{void look_recenter();}
{Positions the camera in a way that all objects can be seen.}

\ccMethod{int get_line_width() const;}
{Returns the line width.}

\ccMethod{int set_line_width(int w);}
{Sets the line width to \ccc{w}. Returns the previous value.}

\ccMethod{double get_vertex_radius() const;}
{Returns the radius of vertices.}

\ccMethod{double set_vertex_radius(double r) const;}
{Sets the radius of vertices to \ccc{d}. Returns the previous value.}

\ccMethod{string get_new_id(string s);}
{Used to obtain unique identifier names passed to Geomview.  On successive
calls with the same \ccc{s} value, it will return a string which is \ccc{s}
appended with the numbers 0, then 1, then 2...  Note that all counters are
reset when \ccc{clear}() is called.}

\ccMethod{bool set_wired(bool b);} 
{Sets wired mode.  In wired mode, some structures output only there edges,
 not there surfaces.
 Returns the previous value. By default, wired mode is off.}

\ccMethod{bool get_wired();}
{Returns \ccc{true} iff wired mode is on.}


\begin{ccAdvanced}

\ccHeading{Advanced and Developers Features}

The following functions are helpful if you develop your own insert
and extract functions. The following functions allow to pass a string
from Geomview and to read data sent back by Geomview.

\ccMethod{Geomview_stream& operator<<(string s);}
{Inserts string \ccc{s} into the stream.}


\ccMethod{Geomview_stream& operator>>(char* s);}
{Extracts a string \ccc{s} from the stream.
\ccPrecond You have to allocate enough memory.}

\ccMethod{Geomview_stream& operator<<(int i);}
{Inserts \ccc{i} into the stream. Puts whitespace around if the
stream is in ascii mode.}

\ccMethod{Geomview_stream& operator<<(unsigned int i);}
{Inserts \ccc{i} into the stream. Puts whitespace around if the
stream is in ascii mode.}

\ccMethod{Geomview_stream& operator<<(long i);}
{Inserts \ccc{i} into the stream. Puts whitespace around if the
stream is in ascii mode. Currently implemented by converting to int, so it
can be truncated on 64 bit platforms.}

\ccMethod{Geomview_stream& operator<<(unsigned long i);}
{Inserts \ccc{i} into the stream. Puts whitespace around if the
stream is in ascii mode. Currently implemented by converting to unsigned int,
so it can be truncated on 64 bit platforms.}

\ccMethod{Geomview_stream& operator<<(double d);}
{Inserts double \ccc{d} into the stream. Puts whitespace around if the
stream is in ascii mode.}

\ccMethod{bool set_trace(bool b);} 
{Sets tracing on. The data that are sent to \ccc{Geomview} are also
 sent to \ccc{cerr}.  Returns the previous value. By default tracing is
 off.}

\ccMethod{bool get_trace();}
{Returns \ccc{true} iff tracing is on.}

\ccMethod{bool set_raw(bool b);} 
{Sets raw mode.  In raw mode, kernel points are output without headers and
 footers, just the coordinates (in binary or ascii mode).  This allows the
 implementation of the stream functions for other objects to re-use the
 code for points internally, by temporary saving the raw mode to true, and
 restoring it after.
   Returns the previous value. By default, raw mode is off.}

\ccMethod{bool get_raw();}
{Returns \ccc{true} iff raw mode is on.}

\ccMethod{bool set_echo(bool b);} 
{Sets echo mode.  In echo mode, when you select a point in Geomview, the point
 is actually sent back to Geomview.
 Returns the previous value. By default, echo mode is on.}

\ccMethod{bool get_echo();}
{Returns \ccc{true} iff echo mode is on.}

\ccMethod{bool set_binary_mode(bool b = true);}
{Sets whether we are in binary mode.}

\ccMethod{bool set_ascii_mode(bool b = true);}
{Sets whether we are in ascii mode.}

\ccMethod{bool get_binary_mode();}
{Returns \ccc{true} iff \ccVar\ is in binary mode.}

\ccMethod{bool get_ascii_mode();}
{Returns \ccc{true} iff \ccVar\ is in ascii mode.}

\end{ccAdvanced}

\ccImplementation

The constructor forks a process and establishes two pipes between the
processes. The forked process is then overlaid with Geomview. The
file descriptors \ccc{stdin} and \ccc{stdout} of Geomview are hooked
on the two pipes.

All insert operators construct expressions in \ccc{gcl}, the Geomview
command language, which is a subset of {\sc Lisp}. These expressions
are sent to Geomview via the pipe. The extract operators notify \ccc{interest}
for a certain kind of events. When such an event happens Geomview
sends a description of the event in \ccc{gcl} and the extract operator has
to parse this expression.

In order to implement further insert and extract operators you should
take a look at the implementation and at the Geomview manual.


%\ccSeeAlso

%\ccc{Some_other_class},
%\ccc{some_other_function}.

%\ccExample

%A short example program.
%Instead of a short program fragment, a full running program can be
%included using the 
%\verb|\ccIncludeExampleCode{Package/Geomview_prog.cpp}| 
%macro. The program example would be part of the source code distribution and
%also part of the automatic test suite.

%\begin{ccExampleCode}
%void your_example_code() {
%}
%\end{ccExampleCode}

%%% \ccIncludeExampleCode{Package/Geomview_prog.cpp}

\end{ccRefClass}

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