\documentclass[11pt]{article}

% GILDAS specific definitions
\include{gildas-def}


\title{IRAM Memo 2011-1\\[3\bigskipamount]
  Preparing GILDAS for large datasets\\
  I - GREG 2011}%
\author{S. Bardeau$^{1}$, E. Reynier$^{1}$, J. Pety$^{1,2}$\\[0.5cm]
  1. IRAM (Grenoble) \\
  2. Observatoire de Paris}%
\date{26-jun-2013 \\
      version 1.4}
\makeindex{}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{document}

\maketitle

\begin{rawhtml}
  Note: this is the on-line version of the Introduction to the Python port
  of GILDAS.
  A <A HREF="../../pdf/gildas-python.pdf"> PDF version</A>
  is also available.
\end{rawhtml}

\begin{rawhtml}
  Related information is available in:
  <UL>
  <LI> <A HREF="../greg-html/greg.html"> GREG:</A> Grenoble Graphics
  <LI> <A HREF="../sic-html/sic.html"> SIC:</A> Simple Interpretor of Commands
  </UL>
\end{rawhtml}

\begin{abstract}
The size of the datasets produced by the IRAM instruments experience a
tremendeous increase (because of multi-beam receivers, wide bandwidth
receivers, spectrometers with thousands of channels, and/or new
observing mode like the interferometric on-the-fly). Visualizing these
datasets in a fluent way is a challenge, which requires the best use
of the available hardware and operating systems (multi-cores
processors and multi-window environments). This prompted a large
rewriting of the part of the GILDAS kernel (known as GTV) in charge of
the interface between the plotting facilities and the system. The main
guidelines of this rewriting were 1) the backward compatibility when
possible, 2) the use of modern standards as the multi-threading or the
GTK+ toolkit, 3) the factorization of the source code for different OS
(Linux, Mac OSX and MS Windows), 4) the implementation of new
facilities like a PNG output or an interactive lens. This document
thoroughly describes the improvements for the end-users and the programmers.\\

  Keywords: multithreading, multiwindowing, the GIMP ToolKit (GTK+),
Portable Network Graphics (PNG)

  Related documents: \emph{GreG documentation}, \emph{Programming in GILDAS}
\end{abstract}

\newpage
\tableofcontents

% --- Why? -------------------------------------------------------------
\newpage
\section{Why a new implementation of the GTV library?}

The {\tt GreG} program lies on the so-called {\tt GTV} library, a low
level segment library. This library was written two decades ago, and
not updated for several years. This was resulting in old-fashion
graphical aesthetics for nowadays users, with some annoying
constraints from other ages, e.g. windows which where not refreshed as
often as the user would like.\\

For the maintainers point of view, the lack of experts of the source
code was a big problem to fix bugs or improve any feature, especially
with an old-fashion source code. Finally the status was usual rule in
such a case: \emph{``If you don't touch it you don't break it''}.\\

It was decided in 2007 to act before reaching the non-return point. In
particular it was time to cut the dependency with the old widget
library {\tt Motif} (and its various implementations giving more or
less satisfying results). The choice was made to use GTK instead, a
well-known widget library for Linux users (but also supported on MS
Windows and Mac OSX), and actively developed by the community. This
was a first part of the work.\\

 Another key piece is that GTV could only do one action at a time. By
\emph{action} one have to understand: storing a new plot coming from a
user command, or drawing in one window, or plotting an hardcopy,
etc. In particular this explains why the windows could not all be
refreshed when desired. From the developers point of view, it was due
to the fact that a large amount of the drawings were performed with
global variables (some of them were internal to the library, but some
others were the user property!). Thanks to modern Fortran features
(namely derived types and pointers), the majority of the variables are
not global anymore, but are passed to the drawing routines through a
small number of structures describing the plot and its destination.\\

 Finally, thanks to the above point, it was possible to implement GTV
as a multi-threaded library: the user can work on its data while all
its X windows are automatically refreshed or updated.\\

 In this new context, the field is open for new and modern graphical
tools. For example, a \emph{lens} is already available: a popup window
can be opened to zoom and browse a plotting window with the
cursor. And more tools are already considered for the future.

% --- Cool things ------------------------------------------------

\section{The new cool things for the enthousiastic users}

Will your life change with the new GTV? Well, not exactly, but
consider these points:
\begin{itemize}
\item the GTV is now {\bf multithreaded}: this means basically that
      the drawings and the flow of commands (including the data
      processing) are done in two different \emph{threads}. With the
      efficient rewriting of the code and your multi-core machine, you
      will experience much more fluid graphics: the drawing events
      won't be slowed or postponed by the data processing, and
      vice-versa.
\item {\bf GTK+} is now used as the widget library. No more
      old-fashion windows, forms, or file browsing popups, they will
      look like what you are used to.
\item {\bf multi-windowing} is more user friendly: you can have
      several plots in several windows, all are refreshed in real
      time. No more {\tt ZOOM REFRESH}: windows are always
      up-to-date. You can also define the windows size and position
      with much more flexibility. The first window is not anymore
      forced to open in the top right corner of your screen: now YOU
      decide if your windows should open or not at a specific
      position.
\item {\bf zooming} is now easier and more interactive: a lens is now
      available at any time when center-clicking in any plotting
      window, and zooming/unzooming is done with the mouse wheel.
\item tired of PostScript captures, rotations, and even color
      conversions? Now you can convert (hardcopy) your plot natively
      to the {\bf PNG image format}. In particular, the background
      transparency is supported for an enhanced cosmetic of your
      presentations.
\end{itemize}

There also other things which will ease your life:
\begin{itemize}
\item {\bf Encapsulated PostScripts} of landscape-oriented plots are
      not rotated anymore to portrait orientation. It is assumed that
      you will include it in another document (Latex source,
      presentation, etc): you will not have do derotate it back to
      landscape orientation.
\item the {\bf Look-Up-Table dynamics} has been increased from 128 to
      65536 levels. You will not see anymore staircasing effects on
      smoothly-varying images.
\item the so-called {\bf \emph{static} Look-Up Table mode} works now:
      you can use one Look-Up Table per image in a single window.
\item the {\bf GTV variables} have been merged under a few SIC
      structures: this avoids diluting your own variables into a large
      number of program variables.
\item some {\bf command and options} have been renamed for clarity,
      and to get rid of obsolete nomenclature. Among other things, you
      will not have anymore to figure out which one of the nine {\tt
      CLEAR} flavors you need. For a smooth transition, GTV will
      recognize the old syntax commands and let you know what they
      should be replaced with. Some {\bf variables, SIC logicals, and
      symbols} have also changed for the same reasons: you will find a
      summary of all the changes in the tables~\ref{tbl:commands},
      \ref{tbl:variables}, \ref{tbl:logicals} and \ref{tbl:symbols}.
\item {\bf $N^2$ algorithms} in the source code are fixed. You think
      that {\tt GO SPECTRUM} or {\tt GO BIT} are taking ages on a big
      data cube, slowing down at a point you feel they will never
      finish? Try again now!
\item no more {\bf weird error messages} like \emph{``Not enough
      colors''} or \emph{``Too many images plotted''}: the internal
      limitations have been removed and you are now only limited by
      the physical memory of your computer.
\end{itemize}

And more will come in the future!

% --- Requirements ----------------------------------------------------------

\section{Requirements}

\subsection{Widget and graphic library}

The GIMP ToolKit (GTK+) is now used as the widget library, while the
GIMP Drawing Kit (GDK) is used as the graphic library. This choice
ensures portable code and similar rendering on the three major sytems
Gildas supports: Linux, Mac OSX, MS Windows. GTK+ and GDK are thus now
a requirement in order to compile the Gildas kernel. They are provided
together on the system repositories as a unique package. Its presence
on your system can be checked with the following command:
\begin{verbatim}
pkg-config --exists gtk+-2.0; echo $?
\end{verbatim}
If a 0 is returned (i.e. no error), then you will be able to compile
the new Gildas kernel. If another value is returned, you will need
first to install the package.

The GTK+/GDK package has been tested between versions 2.10 and
2.22. Beyond this range, you can encounter GTK warnings or
errors. Please report these to {\tt gildas@iram.fr}, with your GTK
version which you can find in the file {\tt gtk/gtkversion.h}
installed on your system.\\

In addition, the support for the old widget library {\tt Xforms} is
removed. Its support was still present but was not tested for
years. The support for the {\tt MOTIF} library (the default used with
the previous kernel) is obsolete and is considered for complete
removal soon.

\subsection{Fortran compilers}

At the time this documentation is written (14-dec-2010), here is the
status of the various Fortran compilers supported by Gildas:
\begin{itemize}
\item Intel Fortran Compiler (ifort): versions 9.0 and 11.1 have been
      tested. As far as we know it seems fine to compile the new
      kernel with ifort. There is no bug directly related to the new
      kernel, but remember there can be problems in old version of
      ifort (e.g. a memory leak with ifort 9.0).

\item g95: none of the stable versions of g95 (i.e. up to 0.92) is now
      able to run correctly the new Gildas kernel. The Fortran runtime
      libraries it provides do not seem to be thread-safe, i.e. there
      are conflictual access to its internal routines. With the
      implementation of the Fortran co-arrays, the current development
      version of g95 (0.93) should be thread-safe. The problem is that
      this version is not stable enough to compile the Gildas kernel,
      and developments seem frozen since August 2010.

\item the GNU Fortran Compiler (gfortran): recent versions of gfortran
      are able to compile and run correctly the new Gildas kernel. The
      lower limit 4.3.0 required for the gfortran version and
      introduced 2 years ago is kept unchanged. The annoying bug which
      enforce the user to type {\tt RETURN} after clicking in a widget
      is {\bf not} related to the new kernel. A patch for this bug has
      been submitted to the development versions of gfortran, and it
      will be part of the releases 4.4.6, 4.5.2 and 4.6.0.
\end{itemize}


% --- End-user documentation ------------------------------------------------

\section{Changes for end-users}

All the obsolete, changed or new concepts are exhaustively described
in this section and in the appendix~\ref{txt:changes}.

% --- Behavior ---

\subsection{Behavior}

\subsubsection{Removed}

 There is a number of \emph{devices} officially supported by GTV which
have been removed. In the GTV context, a \emph{device} is a
destination for the plot stored in the GTV tree (e.g. X-Windows or
PostScripts). The following ones have been removed, mostly because
they are just obsolete:
\begin{itemize}
\item {\tt HPGL}
\item {\tt REGIS}
\item {\tt TEKTRO}
\end{itemize}
This includes all the variants which were available in the Gildas {\tt
kernel/etc/} sources, but not compiled by default in the standard
Terminal Definition File.\\

The device {\tt SVG INTERACTIVE} is also disabled, at least as long as
its need is not clearly required. The device {\tt SVG [LOCAL]} is kept
for hardcopies.

\subsubsection{Changed}

\begin{itemize}

\item The EPS (Encapsulated PostScript) hardcopies are not
  automatically rotated anymore. The reason is that we assume now that
  EPS are intended to be included in another document rather than
  being printed. The new option {\tt /FITPAGE} for command {\tt
    HARDCOPY} enables automatic rotation and scaling (i.e. the
  historical behavior). You can also set the global variable {\tt
    GTV\%FITPAGE} to {\tt YES} for an identical result. The option
  {\tt /PRINT} (formerly {\tt /PLOT}) implicitely activates {\tt
    /FITPAGE}. Finally, the standard (non-encapsulated) PostScripts
  have not been changed. The table~\ref{tbl:postscript} summarizes the
  former and new rotation rules.

\item The default Look-Up Table (LUT) is now a continuous variation of
  colors, from black to white. It is similar to the LUT which can be
  loaded from the file {\tt rainbow3.lut}, probably the most popular
  LUT in GTV. It can be reloaded at any time with the command {\tt LUT
    DEFAULT}. The previous default LUT was also a continuous variation
  of colors (circular hue value), but from red to red, resulting in
  confusing low and high levels. It still can be loaded with the
  command {\tt LUT COLOR}.

\item The so-called ``LUT static'' mode has been fixed and works
  correctly now. ``LUT static'' mode can be used to define one LUT per
  GreG image. It also applies to pens 8 to 23 used by \eg\ {\tt RGMAP
    /GREY}. See {\tt HELP GTVL\textbackslash{}CHANGE LUT} for details.

\item Now the pen is a global atribute, e.g.:
  \begin{verbatim}
  GREG\PEN 0  ! Black
  CREATE DIRECTORY SUB
  CHANGE DIRECTORY SUB
  GREG\PEN 1  ! Red
  CHANGE DIRECTORY ..
  \end{verbatim}
With the above sequence of commands, the next segments created in the
first directory would have been black, since there was a memory of the
last pen in use when leaving the directory. Now, the pen used
\emph{everywhere} is the last pen defined \emph{anywhere}.
\end{itemize}

\begin{table}[htb]
\begin{center}
  \caption{How the PostScripts and Encapsulated PostScripts are
    rotated or not depending on the GTV version and the plotting
    page. \emph{Condition1}: Yes if the X range of the drawings is
    larger than its Y range (\emph{bounding box}), else No. This table
    reflects how the printers or the Latex inclusions behave. It does
    not reflect how some viewers can display the PostScript, in
    particular \emph{ghostview}.}
\vspace{1ex}
\begin{tabular}{l|cc|cc|cc|cc}
          & \multicolumn{2}{|c|}{Old} & \multicolumn{6}{c}{New} \\
\hline
Kind      & EPS & PS  & EPS & PS  & EPS        & PS   & EPS        & PS  \\
          &     &     &     &     & \multicolumn{2}{c|}{\tt HARD /FITPAGE} & \multicolumn{2}{c}{\tt GTV\%FITPAGE YES}\\
\hline
Landscape & Yes & Yes & No  & Yes & Condition1 & Yes  & Condition1 & Yes \\
Portrait  & No  & No  & No  & No  & Condition1 & No   & Condition1 & No
\end{tabular}
\label{tbl:postscript}
\end{center}
\end{table}


\subsubsection{New}

\begin{itemize}

\item An interactive ``lens'' tool: browsing and zooming in your
      figures is now enhanced thanks to a new tool: i) open the lens
      with a center-click on any plotting window, ii) zoom in or out
      with the mouse wheel, iii) enlarge or reduce the lens with
      CTRL+wheel, iv) close the lens with center-click again.

\item PNG hardcopies: in the context of modern use of figures
      (e.g. digital presentations, webpages, etc), Greg plots can now
      be transfered natively to PNG images. See {\tt HELP
      GTVL\textbackslash{}HARDCOPY} for details. In particular, these
      images support background transparency

\end{itemize}

% --- Commands et al. ---
\subsection{Commands, variables, SIC logicals and symbols}

There has been an important effort to clarify the names of the various
GTV \emph{objects}, to fix or improve their behavior, and to clean out
the obsolete ones. This can imply here and there an action from the
user to make its procedures compatible with the new GTV. The new GTV
knows about the old commands: it will detect these and suggest to the
user what they should be replaced with. It can run in 2 modes,
tolerant or strict, which can be toggled with the SIC variable {\tt
GTV\%STRICT2011}. All the changes regarding these objects are
exhaustively described in the appendix~\ref{txt:changes}. The
tables~\ref{tbl:commands}, \ref{tbl:variables}, \ref{tbl:logicals} and
\ref{tbl:symbols} summarize these changes.

\begin{table}
\small
\begin{center}
\caption{Old {\tt GTV} and {\tt GREG} commands which are removed or
modified, their purpose, and their equivalent with the new GTV
syntax. Refer to section~\ref{txt:commands} for a detailed
description.}
\vspace{1ex}
\begin{tabular}{lp{5cm}l}
Old command                   & Behavior                                       & Equivalent \\
\hline
{\tt CLEAR}                   & perform a {\tt CLEAR PLOT}                     & see {\tt CLEAR PLOT}               \\
{\tt CLEAR ALPHA}             & bring the plotting window in front             & not yet defined                    \\
{\tt CLEAR GRAPHIC}           & bring the terminal in front                    & none                               \\
{\tt CLEAR PLOT}              & perform a {\tt CLEAR WHOLE}, or                & {\tt DESTROY ALL}, or              \\
                              & perform a {\tt CLEAR TREE}                     & {\tt CHANGE DIRECTORY} + {\tt CLEAR DIRECTORY} \\
{\tt CLEAR TREE}              & destroy the current tree                       & {\tt CHANGE DIRECTORY} + {\tt CLEAR DIRECTORY} \\
{\tt CLEAR WHOLE}             & destroy all the trees                          & {\tt DESTROY ALL}                  \\
{\tt CLEAR WINDOW [Num]}      & close the active/numbered window               & {\tt DESTROY WINDOW [Dir [Num]]}   \\
{\tt CHANGE CLEAR TREE|WHOLE} & set the behavior of {\tt CLEAR PLOT}           & none                               \\
{\tt CHANGE DRAW ON|OFF}      & toggle the drawing state to active or sleeping & none                               \\
{\tt CHANGE ZOOM NEW|CURRENT} & toggle the default behavior of ZOOM            & none                               \\
{\tt CREATE DIRECTORY /PIXEL} & set the window size of a new top directory     & {\tt CREATE DIRECTORY /GEOMETRY}   \\
{\tt CREATE DIRECTORY /SIZE}  & set the plot page of a new top directory       & {\tt CREATE DIRECTORY /PLOT\_PAGE} \\
{\tt DISPLAY CLEAR}           & show the {\tt CLEAR PLOT} behavior             & none                               \\
{\tt HARDCOPY /PLOT}          & send the hardcopy to the printer               & {\tt HARDCOPY /PRINT}              \\
{\tt ZOOM REFRESH}            & force the redraw of the active window          & {\tt REFRESH [Dir [Num]]}          \\
{\tt ZOOM /REGION}            & define the zoom area with the cursor           & none                               \\
{\tt ZOOM /CURRENT}           & zoom is performed in the current window        & none                               \\
{\tt ZOOM /NEW}               & zoom is performed in a new window              & {\tt ZOOM} without argument        \\
\hline
{\tt GREG1\textbackslash{}SET DRAW ON|OFF} & toggle the drawing state to active or sleeping & none \\
{\tt GREG1\textbackslash{}SHOW DRAW}       & display the drawing state                      & none \\
\end{tabular}
\label{tbl:commands}
\end{center}
\end{table}

% --- Variables ---

\begin{table}
\small
\begin{center}
\caption{{\tt GTV} and {\tt GREG} variables which are removed,
modified, or added. Their read-write status is indicated in the third
column. Refer to section~\ref{txt:variables} for a detailed
description.}
\vspace{1ex}
\begin{tabular}{llcp{5cm}}
Old name                & New name                         & Read-Write & Usage \\
\hline
{\tt GTV\%SLEEP}        & none                             & RO & the active/sleeping drawing state                 \\
{\tt GTV\%IMAGES[4,15]} & none                             & RO & internal values associated to the first 15 images \\
{\tt GTV\%IDENT}        & none                             & RW & the number of the device currently in use         \\
{\tt LUT}               & none                             & RO & the hue values of the current LUT in use          \\
{\tt REXTR}             & none                             & RO & the extrema of the last segment created           \\
{\tt REXTR\_D}          & none                             & RO & the extrema of the current working directory      \\
none                    & {\tt GTV\%PWD}                   & RO & the current working directory                     \\
none                    & {\tt GTV\%FITPAGE}               & RW & activate option {\tt /FITPAGE} for {\tt HARDCOPY} \\
\hline
{\tt GTV\%LUT\_STATIC}  & {\tt LUT\%STATIC}                & RO & the dynamic/static LUT state                           \\
{\tt LUT\_SIZE}         & {\tt LUT\%SIZE}                  & RO & the number of levels of the current LUT                \\
{\tt LUT\_MODE}         & {\tt LUT\%MODE}                  & RW & the HSV or RGB mode for the user-defined LUT           \\
{\tt HUE}               & {\tt LUT\%HUE}                   & RW & the hue values of the current LUT (input/output)       \\
{\tt SATURATION}        & {\tt LUT\%SATURATION}            & RW & same for the saturation values                         \\
{\tt VALUE}             & {\tt LUT\%VALUE}                 & RW & same for the intensity values                          \\
{\tt RED}               & {\tt LUT\%RED}                   & RW & same for the red intensity values                      \\
{\tt GREEN}             & {\tt LUT\%GREEN}                 & RW & same for the green intensity values                    \\
{\tt BLUE}              & {\tt LUT\%BLUE}                  & RW & same for the blue intensity values                     \\
{\tt B\_HUE}            & {\tt LUT\%BLANKING\%HUE}         & RW & the hue value of the blanking color (input/output)     \\
{\tt B\_SATURATION}     & {\tt LUT\%BLANKING\%SATURATION}  & RW & same for the saturation value                          \\
{\tt B\_VALUE}          & {\tt LUT\%BLANKING\%VALUE}       & RW & same for the intensity value                           \\
{\tt B\_RED}            & {\tt LUT\%BLANKING\%RED}         & RW & same for the red intensity value                       \\
{\tt B\_GREEN}          & {\tt LUT\%BLANKING\%GREEN}       & RW & same for the green intensity value                     \\
{\tt B\_BLUE}           & {\tt LUT\%BLANKING\%BLUE}        & RW & same for the blue intensity value                      \\
{\tt P\_HUE}            & {\tt LUT\%PEN\%HUE}              & RW & the hue values of the user-defined pens (input/output) \\
{\tt P\_SATURATION}     & {\tt LUT\%PEN\%SATURATION}       & RW & same for the saturation values                         \\
{\tt P\_VALUE}          & {\tt LUT\%PEN\%VALUE}            & RW & same for the intensity values                          \\
{\tt P\_RED}            & {\tt LUT\%PEN\%RED}              & RW & same for the red intensity values                      \\
{\tt P\_GREEN}          & {\tt LUT\%PEN\%GREEN}            & RW & same for the green intensity values                    \\
{\tt P\_BLUE}           & {\tt LUT\%PEN\%BLUE}             & RW & same for the blue intensity values                     \\
\hline
{\tt LCUT}              & {\tt CURIMA\%SCALE[1]}           & RO & low cut for last image {\tt PLOT}'ted       \\
{\tt HCUT}              & {\tt CURIMA\%SCALE[2]}           & RO & high cut for last image {\tt PLOT}'ted      \\
{\tt SCALING}           & {\tt CURIMA\%SCALING}            & RO & scaling mode for last image {\tt PLOT}'ted  \\
{\tt EQUAL\_NLEV}       & {\tt CURIMA\%EQUAL\%NLEV}        & RO & number of levels in {\tt EQUAL} mode        \\
{\tt EQUAL\_LEV}        & {\tt CURIMA\%EQUAL\%LEV}         & RO & levels in {\tt EQUAL} mode                  \\
{\tt EQUAL\_HIST}       & {\tt CURIMA\%EQUAL\%HIST}        & RO & values per level in {\tt EQUAL} mode
\end{tabular}
\label{tbl:variables}
\end{center}
\end{table}

% --- Logicals ---

\begin{table}
\begin{center}
\caption{{\tt SIC} logicals in {\tt GTV} which are modified or
added. Refer to section~\ref{txt:logicals} for a detailed
description.}
\vspace{1ex}
\begin{tabular}{llp{8cm}}
Old name         & Equivalent name        & Usage                                        \\
\hline
{\tt LUT\_DIR:}  & {\tt LUT\#DIR:}        & where the LUT files should be searched in    \\
none             & {\tt WINDOW\_GEOMETRY} & the default geometry of new windows          \\
none             & {\tt WINDOW\_POSITION} & the position on screen of the first window
\end{tabular}
\label{tbl:logicals}
\end{center}
\end{table}

% --- Symbols ---

\begin{table}[htb]
\begin{center}
\caption{Old GTV symbols which are removed, and the command which can
be used to define them in user's {\tt \$HOME/.gag.dico}. Refer to
section~\ref{txt:symbols} for a detailed description.}
\vspace{1ex}
\begin{tabular}{ll}
Old symbol  &  Equivalent \\
\hline
{\tt CD}    & {\tt SYMBOL CD    "GTVL\textbackslash{}CHANGE DIRECTORY"}  \\
{\tt PWD}   & {\tt SYMBOL PWD   "GTVL\textbackslash{}DISPLAY DIRECTORY"} \\
{\tt MKDIR} & {\tt SYMBOL MKDIR "GTVL\textbackslash{}CREATE DIRECTORY"}  \\
\end{tabular}
\label{tbl:symbols}
\end{center}
\end{table}

% --- Programmers ------------------------------------------------------
\clearpage
\section{Changes for programmers}

\subsection{The new GTV overview}

In the previous version of the GTV, the metacode describing the plots
was stored in several chunks of memory. The current chunk was
contiguously filled with all the incoming data: directory descriptors,
segments descriptors, segment data, or image descriptors. When the
current chunk was (nearly) full, it was copied to a newly allocated
chunk, and reset for new use. This had 3 major limitations:
\begin{itemize}
\item it was a permanent worry to make sure that the incoming data
      will fit in the remaining place of the current chunk,
\item the tree size and the numbers of images in the tree were limited
      by hard coded parameters in the source code,
\item the various links in the tree between the directories, the
      segments, and their data, were remembering the chunk number and
      the position in the chunk. Deleting an object and freeing its
      associated memory was just a nightmare: links could not be
      updated easily.
\end{itemize}

\begin{figure}[htb]
  \includegraphics[width=\textwidth]{greg-2011-gtvtree}
  \caption{The tree and linked lists structure of the metacode storing
           the plots in the GTV, with a basic example of top
           directories, subdirectories, and segments. The relationship
           presented here between the various elements is not
           exhaustive.}
\label{tree:png}
\end{figure}

Given these limitations, the choice was made to fully rewrite the way
the metacode data is stored in memory. Appropriate Fortran derived
types were defined: they describe the various links an object can have
with others in the tree. Figure~\ref{tree:png} shows an example of the
various kind of data which can be encountered in the metacode.\\

All the links are made with allocatable pointers, which are allocated
in real time, on-demand. The tree is thus now growing dynamically in
memory. Deleting an object is just as easy as deallocating a pointer
to it, after having taken care that the surrounding elements in the
tree are correctly updated. Furthermore, deallocation can be delayed
(i.e. put in the event stack) after all the events which need it are
done, without altering the normal life of the tree (as ruled by the
commands executed).

% --- Entry points ---
\subsection{Entry points}

\subsubsection{Removed}
\label{prog:entry:removed}

The so-called ``immediate pen'' support and associated entry points
are removed:
\begin{itemize}
\item {\tt gti\_where}
\item {\tt gti\_pen}
\item {\tt gti\_out}
\item {\tt gti\_draw}
\item {\tt gti\_reloc}
\end{itemize}
The ``immediate pen'' was used to plot lines directly on the default
window, without storing them in the metacode. This was an unsatisfying
mechanism since: i) these drawings (probably useful) were lost as soon
as the window was redrawn, ii) the window manager could ask for a
window redraw at any time.\\

The {\tt Sleep} and {\tt Wake\_Up} modes for {\tt gtview} are
removed. They were intended to delay the drawing of new segments being
added to the metacode. This behavior has been removed because i) the
drawing is performed in another thread i.e. it does not slow down the
main thread execution, ii) the drawing routines were speed up to avoid
re-reading the whole tree in order to search for undrawn segments,
iii) user always wants to see the segments being added as soon as
possible. As a consequence the following entry points are removed:
\begin{itemize}
\item {\tt gtstat} (it was returning the sleeping status of the {\tt
      GTV})
\item {\tt gtview('Sleep')} and {\tt gtview('Wake\_Up')} (they were
      setting the sleeping status of the {\tt GTV}).
\end{itemize}

The following obsolete entry points are removed:
\begin{itemize}
\item {\tt gtpaus}
\item {\tt gtg\_charsiz}
\item {\tt gtg\_open}
\end{itemize}

\subsubsection{New}

Any segment opened with {\tt gr\_segm} must now be closed with the
following new entry point after all the data it contains has been sent
to the metacode:
\begin{itemize}
\item {\tt gr\_segm\_close(error)}
\end{itemize}
The following conditions applies:
\begin{itemize}
\item at close time ({\tt gr\_segm\_close}), a segment is implicitely
      drawn by {\tt GTV},
\item attempting to send segment data to the metacode while there is
      no segment currently opened is an error,
\item attempting to open ({\tt gr\_segm}) a new segment while the
      previous one is not closed ({\tt gr\_segm\_close}) is an error,
\item attempting to close ({\tt gr\_segm\_close}) twice a segment is
      an error.
\end{itemize}
Given the first point above, the necessity for an {\tt Append} mode
for {\tt gtview} is severely reduced. Basically, what you will
probably have to do is to replace all the statements {\tt
gtview('Append')} by {\tt gr\_segm\_close(error)}. The only purpose to
call {\tt gtview('Append')} is now when you are filling a unique
segment, and want the user to see in real-time this segment being
filled (e.g. a curve showing the convergence of a computation, or an
interactive drawing with the cursor, ...).\\

Instead of calling {\tt gr\_exec('CLEAR SEGMENT FOO')}, programmers
can invoke the public subroutine {\tt
gt\_clear\_segment(name,present,error)} where {\tt name} is the
segment(s) name to be destroyed (e.g. if {\tt name} is {\tt FOO} it
will destroy all the segments named {\tt FOO:*}), {\tt present} is a
logical indicating if an error should be raised if no segment with
such a name is found, and {\tt error} is an {\tt inout} logical error
flag (i.e. it keeps its entering value if no error occurs).

% --- Appendices ----------------------------------------------------------
\clearpage
\newpage
\appendix{}

\section{Exhaustive description of the changes in GTV}
\label{txt:changes}

% --- Commands ---
\subsection{Commands}
\label{txt:commands}

A choice has been made to clarify the various commands. In particular,
there were some keywords which were refering to some obsolete devices
(e.g. {\tt CLEAR ALPHA} and {\tt CLEAR GRAPHIC}).\\

There was a also a confusion with the behavior command {\tt
CLEAR}. The rule is now: {\tt CLEAR FOO} erases the content of the
object designated by {\tt FOO}, while the new command {\tt DESTROY}
kills this object.

\subsubsection{Removed}

\begin{itemize}
\item {\tt CHANGE CLEAR TREE|WHOLE, DISPLAY CLEAR}
  \begin{itemize}
  \item commands were controling and displaying the behavior of {\tt
        CLEAR PLOT}
  \item reason: associated {\tt CLEAR TREE} and {\tt CLEAR WHOLE} are removed.
  \end{itemize}

\item {\tt CHANGE ZOOM NEW|CURRENT}
  \begin{itemize}
  \item command was controling the default behavior of {\tt ZOOM},
        i.e. if the zoom should be performed in the main or in a new
        window.
  \item {\tt CHANGE ZOOM} is removed since the zoom is now always
        performed in a new window.
  \end{itemize}

\item {\tt CHANGE DRAW ON|OFF}, and {\tt GREG1\textbackslash{}SET DRAW ON|OFF}
  \begin{itemize}
  \item commands were both disabling ({\tt OFF}) the real-time drawing
        of the new segments being added to the metacode, and drawing
        them ({\tt ON}) later on.
  \item reason: associed mode is removed in the Fortran API (see
        comments on {\tt gtview} at section~\ref{prog:entry:removed}.
  \end{itemize}

\item {\tt CLEAR GRAPHIC}
  \begin{itemize}
  \item command was supposed to bring to front (or focus) the terminal
        ({\tt CLEAR GRAPHIC} means \emph{hide the graphic window}).
  \item reason: not supported on any known modern window managers +
        too many keywords accepted by {\tt CLEAR} + keywords have no
        meaning for those who did not know the old devices like
        Tektro.
  \end{itemize}

\item {\tt CLEAR PLOT}
  \begin{itemize}
  \item reason: there was a confusion between plot clearing and
        windows destruction.
  \item in the simplest case, you have one window, and you are working
        in the top directory (probably {\tt <GREG}): just type {\tt
        CLEAR} to erase the content of the current directory and clear
        the window.
  \item if you have several windows: i) if you want to \emph{clear}
        one window, type {\tt CLEAR TopDir} where {\tt TopDir} is the
        directory associated to the window you want to clear, ii) but
        if you want to \emph{kill} one directory and its associated
        window, type {\tt DESTROY TopDir}
  \item finally if you want to reset all your plots i.e. get back the
        startup status, type {\tt DESTROY ALL}.
  \end{itemize}

\item {\tt CLEAR TREE}
  \begin{itemize}
  \item reason: too many keywords associated to the command {\tt CLEAR}, can
        be replaced in the new GTV context
  \item use {\tt CLEAR DIRECTORY TopDir} instead, or {\tt CHANGE
        DIRECTORY} (with no argument, it goes to the top directory) +
        {\tt CLEAR DIRECTORY} (with no argument, it erases the content
        of the current directory).
  \end{itemize}

\item {\tt CLEAR WHOLE}
  \begin{itemize}
  \item reason: too many keywords associated to the command {\tt CLEAR},
        command unused
  \item use {\tt CLEAR} without argument instead
  \end{itemize}

\item {\tt CLEAR WINDOW [Num]}
  \begin{itemize}
  \item reason: name is ambiguous, too many keywords associated to the
    {\tt CLEAR} command
  \item use {\tt DESTROY WINDOW [Dir [Num]]} instead. No way to
    destroy (from the command line) the current window only. For the
    old {\tt CLEAR WINDOW ZOOM}, use {\tt ZOOM OFF} or {\tt DESTROY
      WINDOW ZOOM} instead.
  \end{itemize}

\item {\tt CREATE DIRECTORY|WINDOW /PIXEL}
  \begin{itemize}
  \item option {\tt /PIXEL Nx Ny} is removed. It was overiding the
        default size of the new window opened by the command.
  \item reason: new option {\tt /GEOMETRY} does the same and more (see
        detailed description hereafter)
  \item use {\tt CREATE DIRECTORY|WINDOW /GEOMETRY Nx Ny} for an
        identical result.
  \end{itemize}

\item {\tt CREATE DIRECTORY /SIZE}
  \begin{itemize}
  \item option {\tt /SIZE} is renamed {\tt /PLOT\_PAGE} for symmetry
        with command {\tt GREG\textbackslash{}SET PLOT\_PAGE}) which does
        the same afterwards. These commands define the physical size
        of the plotting area of a top directory.
  \end{itemize}

\item {\tt HARDCOPY /PLOT}
  \begin{itemize}
  \item option {\tt /PLOT} for command {\tt HARDCOPY} is renamed {\tt
        /PRINT}.
  \item reason: nowadays we use printers, not plotters.
  \end{itemize}

\item {\tt GREG1\textbackslash{}SHOW DRAW}
  \begin{itemize}
  \item command was displaying the current real-time or delayed
        drawing status.
  \item reason: associated command {\tt GREG1\textbackslash{}SET DRAW
        ON|OFF} is removed.
  \end{itemize}

\item {\tt ZOOM REFRESH}
  \begin{itemize}
  \item command is renamed {\tt REFRESH}
  \item reason: we may want to redraw any kind of window, not only
    zooms.
  \end{itemize}

\item {\tt ZOOM /NEW|/CURRENT}
  \begin{itemize}
  \item options were indicating if the zoom had to be performed in the
        main or in a new window
  \item these options are removed since it not possible anymore to
        zoom in the main window (i.e. {\tt /NEW} is implicit now)
  \end{itemize}

\item {\tt ZOOM /REGION}
  \begin{itemize}
  \item reason: not available on MS Windows, unused, duplicate of the new
        lens.
  \end{itemize}

\item {\tt ZOOM buttons}
  \begin{itemize}
  \item "A" (Clear alphanumeric screen) is removed
  \item reason: same as {\tt CLEAR ALPHA}
  \end{itemize}

\end{itemize}

\subsubsection{Changed}

\begin{itemize}

\item {\tt CHANGE WINDOW WinNum}
  \begin{itemize}
  \item change the active window to the given window number. The
        active window is the one in which the interactive cursor will
        appear when it is invoked.
  \item window numbering starts now from 1 (Fortran like) instead of 0
        (C like). So in most of the cases the main window of the
        current directory has now number 1, and the zoom window (if
        any) has number 2.
  \end{itemize}

\item {\tt CLEAR}
  \begin{itemize}
  \item was performing a {\tt CLEAR PLOT}
  \item now performs a {\tt CLEAR ALL} (see after).
  \end{itemize}

\item {\tt CLEAR ALPHA}
  \begin{itemize}
  \item commands is renamed (new name to be defined). It is supposed
        to bring to front (or focus) the graphic window ({\tt CLEAR
        ALPHA} means \emph{hide the alphanumeric terminal}).
  \item reason: too many keywords accepted by {\tt CLEAR} + keywords
        have no meaning for those who did not know the old devices
        like Tektro.
  \item remark: this feature is poorly supported on Linux window
        managers (too many applications must have excessively used
        this, so that the window managers are very restrictive now).
  \end{itemize}

\item {\tt CLEAR DIRECTORY [DirName]}
  \begin{itemize}
  \item the old behavior was to make the directory and its content
        invisible for later destruction by {\tt COMPRESS}.
  \item command behaves differently: {\tt CLEAR DIRECTORY DirName}
        empties the directory named {\tt DirName}. As a consequence,
        this clears the windows seeing this directory. Without
        argument the content of the current working directory is
        removed. Segments are now really deleted.
  \item reason: need a command which clears the content of a window i.e.
        of a top directory (usually). Need also to minimize the number of
        keywords accepted by {\tt CLEAR} for clarity.
  \item the old behavior (destruction of the directory) is ensured by the
        new command {\tt DESTROY DIRECTORY DirName}.
  \end{itemize}

\item {\tt CLEAR SEGMENT}
  \begin{itemize}
  \item without argument, command was deleting the last segment
        created \emph{in the metacode}.
  \item without argument, command behaves slightly differently: it
        deletes the last created segment \emph{in the current working
        directory}, which can be different from the old behavior.
  \item reason: the metacode is now growing dynamically and the
        segments have lost their ``temporality''. Actually the new
        behavior seems better than the previous one.
  \item no way to mimic exactly the old behavior
  \item NB: {\tt CLEAR SEGMENT Name} behaves as before, except it
        really deletes the segment now (in the past it could have only
        made the segment invisble for later deletion by {\tt
        COMPRESS}).
  \end{itemize}

\item {\tt METACODE IMPORT|EXPORT}
  \begin{itemize}
  \item Backward compatibility is broken.
  \end{itemize}

\end{itemize}

\subsubsection{New}

\begin{itemize}

\item {\tt CHANGE POSITION}
  \begin{itemize}
  \item support for {\tt Offx[Unitx] Offy[Unity]} is added. See {\tt
        CREATE WINDOW /POSITION} above for the syntax.
  \end{itemize}

\item {\tt CLEAR ALL}
  \begin{itemize}
  \item clear the content of all the top directories, which clears the
        content of their windows. Top windows are not destroyed.
  \end{itemize}

\item {\tt CREATE WINDOW [/GEOMETRY] [/POSITION]}
  \begin{itemize}
  \item new options {\tt /GEOMETRY} and {\tt /POSITION} are added:
        \begin{verbatim}
       CREATE WINDOW [/GEOMETRY Sx[u] Sy[u]]
                     [/POSITION Offx[u] Offy[u]]
        \end{verbatim}
        where {\tt Sx} and {\tt Sy} are the window size, {\tt Offx}
        and {\tt Offy} the offset on the screen. ``u'' (unit) can be
        ``p'' for pixels, ``\%'' for percent of the screen, or ``r''
        for the aspect ratio in unit of the other dimension. Default
        unit is pixel.
  \item if {\tt /GEOMETRY} is omitted, the values are read from the
        logical {\tt WINDOW\_GEOMETRY} defined in user's
        $\sim${\tt/.gag.dico} with the same syntax as above. If the
        logical {\tt WINDOW\_GEOMETRY} is not defined, internal
        defaults are used for the window size.
  \item if {\tt /POSITION} is omitted, the choice of the window
        position is let to the window manager. ``r'' unit is a
        non-sense and is forbidden for this option.
  \end{itemize}

\item {\tt CREATE DIRECTORY [/GEOMETRY] [/POSITION]}
  \begin{itemize}
  \item new options {\tt /GEOMETRY} and {\tt /POSITION} are added:
        they apply to the creation of the window of a new
        top-directory. See {\tt CREATE WINDOW} above for the syntax.
  \end{itemize}

\item {\tt DESTROY DIRECTORY DirName}
  \begin{itemize}
  \item destroys the input directory and its windows
        attached. Destroying {\tt <GREG} is allowed (as long as user
        has moved before to another directory).
  \end{itemize}

\item {\tt DESTROY WINDOW [DirName [WinNum]]}
  \begin{itemize}
  \item destroys all the windows attached to the directory {\tt
        DirName}, i.e. should be all the windows named {\tt DirName
        Number}. Destroys all the windows of the current working
        directory by default. If a window number is given, only this
        window is destroyed.
  \end{itemize}

\item {\tt DESTROY ALL}
  \begin{itemize}
  \item destroys all the top directories and their windows
  \item since the user can not be in the root directory ({\tt <}) and
        can not create segments in it, he would have to create right
        after a new top directory. A first top directory is thus
        created implicitely.
  \item As a consequence of these two points, the command resets the
        tree and windows to the startup status.
  \end{itemize}

\item {\tt HARDCOPY /DIRECTORY DirName}
  \begin{itemize}
  \item this new option allows to plot the given GTV
        directory. Default remains the current working directory.
  \end{itemize}

\item {\tt HARDCOPY /FITPAGE}
  \begin{itemize}
  \item this new option allows to adjust at best the plot on the
        hardcopy physical size. This is suited for EPS harcopies which
        are not automatically rotated and scaled anymore.
  \item this option is exclusive with the historical option {\tt
        /EXACT} (which disables the automatic scaling).
  \end{itemize}

\item {\tt LUT Name /REVERT}
  \begin{itemize}
  \item the look-up-table {\tt Name} is loaded and reverted on the
        fly.
  \end{itemize}

\item {\tt REFRESH [DirName [WinNum|ZOOM]]}
  \begin{itemize}
  \item redraw all (default) or some of the windows (identified by
    their directory and number/name).
  \item Note that all windows are always up-to-date (drawn in
    real-time thanks to multi-threading). The need of this command is
    thus very limited. It makes sense only when using segments at
    different depths (e.g. images) which may be redrawn in an order
    different from the first drawing (first drawing is done in
    chronological order in order to remain efficient).
  \end{itemize}

\item {\tt GREG1\textbackslash{}PEN [Ipen] /DASH 8}
  \begin{itemize}
  \item an 8th dashing style is added. It contains regular dashes,
        shorter than the 2nd style dashes, and larger than the 3rd
        (dot) style. Execute {\tt @ gag\_demo:demo5.greg} for an
        overview of all the pen attributes.
  \end{itemize}

\end{itemize}

% --- Variables ---
\subsection{Variables}
\label{txt:variables}

\subsubsection{Removed}
The following {\tt GTV} variables are removed:
\begin{itemize}
\item {\tt GTV\%SLEEP}: the real-time or delayed drawing status, but
      this functionality is removed.
\item {\tt GTV\%IMAGES[2,15]}: size and memory address of the images
      stored in the metacode, for debugging purpose.
\item {\tt GTV\%IDENT}: the number in Terminal Definition File of the
      device currently in use.
\item the {\tt LUT} array is removed: it was describing the hue values
      of the current Look-Up Table in use. But since the hue is not
      enough to describe a LUT (saturation and value are also needed),
      the two triplets ({\tt LUT\%RED}, {\tt LUT\%GREEN}, {\tt
      LUT\%BLUE}) or ({\tt LUT\%HUE}, {\tt LUT\%SATURATION}, {\tt
      LUT\%VALUE}) should now be used to get and set the Look-Up Table
      values.
\item {\tt REXTR}: the extrema (in plot\_page units) of the last
      segment created in the metacode.
\item {\tt REXTR\_D}: the extrema (in plot\_page units) of the current
      working directory.
\end{itemize}

\subsubsection{Changed}

The look-up table related variables are merged in a new structure
named {\tt LUT\%}. See table~\ref{tbl:variables} for details. This
structure has three major groups of variables related to the images
look-up table (under {\tt LUT\%}), to the blanking color (under {\tt
LUT\%BLANKING\%}) and to the pen look-up table (under {\tt
LUT\%PEN\%}).\\

The variables describing the current {\tt RG} image plotted by the
command {\tt GREG2\textbackslash{}PLOT} are merged under the structure
{\tt CURIMA\%}. The equalization mode, if in use, is described under
the substructure {\tt CURIMA\%EQUAL\%}. See table~\ref{tbl:variables}
for details.

\subsubsection{New}

\begin{itemize}
\item {\tt GTV\%PWD}: this new variable contains the current working
  GTV directory as a character string. It is aimed to help writing
  plotting procedures which can work in the directory they are started
  in without altering the other plots (trees) already created by the
  user.

\item {\tt GTV\%FITPAGE}: if YES, implies an implicit {\tt /FITPAGE}
  option for the command {\tt HARDCOPY}. In particular, this enables
  the historical behavior regarding Encapsulated PostScripts (if
  landscape, they will be rotated to match the portrait print
  page). Default is NO.

\item {\tt GTV\%STRICT2011}: this new variable will be available
  \emph{temporarily} to rule how the interpreter should behave when
  encountering an old GTV command. If its values is ``yes'', an error
  is raised. If ``no'', it is only a warning. In both cases an
  explanatory message is displayed. Default value is ``yes''. This
  variable is present to help the users and programmers to speed up
  the transition, but without breaking abruptly their procedures and
  programs.
\end{itemize}

% --- Logicals ---
\subsection{SIC logicals}
\label{txt:logicals}

\subsubsection{Removed}

\begin{itemize}
\item {\tt LUT\_DIR:}
  \begin{itemize}
  \item logical is removed. It was controlling the directory where the
        LUT files have to be searched in.
  \item reason: new logical {\tt LUT\#DIR:} is better.
  \end{itemize}
\end{itemize}

\subsubsection{New}

\begin{itemize}

\item {\tt GAG\_LUT:}, {\tt LUT\#DIR:}
  \begin{itemize}
  \item new logical {\tt GAG\_LUT:} is the path to the internal LUT
        files. User should not change it.
  \item new logical {\tt LUT\#DIR:} is \emph{a collection} of paths
        where the LUT files should be searched in. User can customize
        it as its will. Default value is {\tt ./;GAG\_LUT:;}.
  \end{itemize}

\item {\tt WINDOW\_GEOMETRY}, {\tt WINDOW\_POSITION}
  \begin{itemize}
  \item if defined, these new logicals control respectively the size
        of any new window, and the position on the screen of the first
        window when the device is opened.
  \item user can define (one of) them in its $\sim${\tt/.gag.dico}
        for all its sessions, or later during a session.
  \item the option {\tt /GEOMETRY} of the command {\tt CREATE
        DIRECTORY|WINDOW} override the values in WINDOW\_GEOMETRY.
  \item see {\tt CREATE DIRECTORY|WINDOW} above for the syntax to be
        used.
  \end{itemize}

\end{itemize}

% --- Symbols ---
\subsection{Symbols}
\label{txt:symbols}

\subsubsection{Removed}

\begin{itemize}

\item {\tt CD}
  \begin{itemize}
  \item reason: should not be provided by GREG
  \item use {\tt CHANGE DIRECTORY} or define the same symbol instead
  \end{itemize}

\item {\tt PWD}
  \begin{itemize}
  \item reason: unused / should not be provided by GREG
  \item use {\tt DISPLAY DIRECTORY} or define the same symbol instead
  \end{itemize}

\item {\tt MKDIR}
  \begin{itemize}
  \item reason: should not be provided by GREG
  \item use {\tt CREATE DIRECTORY} or define the same symbol instead
  \end{itemize}

\end{itemize}

\end{document}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
