                           GLVis visualization tool

                     _/_/_/  _/      _/      _/  _/
                  _/        _/      _/      _/        _/_/_/
                 _/  _/_/  _/      _/      _/  _/  _/_/
                _/    _/  _/        _/  _/    _/      _/_/
                 _/_/_/  _/_/_/_/    _/      _/  _/_/_/

                              http://glvis.org

GLVis is an X11 application and can be built on Linux/Unix systems including
Mac OS X using the X11/XQuarz app.

Besides a C++ compiler, GLVis depends on the following external packages:

- the MFEM library (use the latest release) plus any libraries that MFEM was
  built to depend on
  http://mfem.org

- the X11, GL and GLU libraries
  http://www.x.org, http://www.opengl.org, http://www.mesa3d.org

- the XQuarz app (on Mac OS X)
  http://www.xquartz.org/

- the libpng or libtiff library; used for taking screenshots (optional)
  http://www.libpng.org, http://www.libtiff.org

- the FreeType 2 and Fontconfig libraries; used for font rendering (optional)
  http://www.freetype.org, http://www.fontconfig.org

The build system is based on GNU make, as described below.


Building with GNU make
======================
GLVis comes with a standard makefile, which can be adjusted to specify the paths
to the external libraries, the compiler flags, etc.

Some of the available 'make' targets are:

make       -> Builds the glvis binary, using the MFEM compiler and options
make opt   -> Builds an optimized version
make debug -> Builds a debug version
make clean -> Cleans the build
make style -> Format the code with Artistic Style.
make help  -> Prints a short help message

Information about the current build configuration can be viewed using

   make status
   make info

An optional installation of the glvis executable can be performed with

   make install [PREFIX=<dir>]

Some building considerations:

- On most Linux distributions, the required dependencies (except MFEM) can be
  installed via a package manager. Usually it is sufficient to install the
  packages: libGLU-dev, libpng-dev, and fontconfig-dev with their dependencies
  (actual packages names may vary).

- To adjust the anti-aliasing settings for your hardware:

  1) Modify the value of the GLVIS_MULTISAMPLE variable (multisample mode) in
     the makefile. Supported values can be obtained from the 'glxinfo' command
     ('ms' columns) or a from a tool like 'nvidia-settings'.

  2) Modify the value of the GLVIS_MS_LINEWIDTH variable (anti-aliased line
     width) in the makefile. Note that the same value can produce different
     results depending on the OpenGL implementation.

  3) The above options and some other built-in defaults can be overwritten with
     command line options, see glvis -h for short help.

- If your X11 server does not support GLX 1.3, you can build GLVis to only use
  GLX 1.0 calls, by specifying the GLVIS_GLX10 define. Note that the X11.app in
  OS X complains about GLX 1.3 support, but in practice works fine with GLVis.

- GLVis can be built without libpng/libtiff/FreeType 2/Fontconfig by setting
  the makefile variables USE_LIBPNG/USE_LIBTIFF/USE_FREETYPE to NO.

- On Mac OS X, it is better to start manually the XQuarz app, before starting
  GLVis, in order to avoid the wait for establishing the first X11 connection.

- Support for secure sockets using the GnuTLS library through MFEM can be
  enabled by configuring and compiling MFEM with the option MFEM_USE_GNUTLS=YES,
  see MFEM's INSTALL for more details. In addition, in order for this to work,
  one needs to generate GLVis server/client key pairs (in ~/.config/glvis),
  similar to ssh keys. The script 'glvis-keygen.sh' can be used to do that:

     bash glvis-keygen.sh ["Your Name"] ["Your Email"]
