/*************************************************************************/
/*                                                                       */
/* Licensed Materials - Property of IBM                                  */
/*                                                                       */
/*                                                                       */
/* (C) Copyright IBM Corp. 2010                                          */
/* All Rights Reserved                                                   */
/*                                                                       */
/* US Government Users Restricted Rights - Use, duplication or           */
/* disclosure restricted by GSA ADP Schedule Contract with IBM Corp.     */
/*                                                                       */
/*************************************************************************/

================================================================================
OVERVIEW
================================================================================

   Name: Remote Viewer Client Application

   The viewer client is used to display images rendered by remote server 
   applications like "julia_remote", "perlin_noise_remote", and 
   "fluid_remote". Communications between the client and server is 
   accomplished via TCP sockets. The server application sample continuosly
   streams images to the client while the client asynchronously sends 
   mouse and keyboard inputs to the application.

   Images can are raw, rgb, unsigned byte format.

                         REMOTE VIEWER FRAMEWORK
			 =======================

         .--------. 
         | sample |                                .-----------.
         | kernel |                                |  display  |
         '----+---'                                '-----+-----'
              |                                          |
              |                                          |
     .--------+-------.                          .-------+-------.
     |     OpenCL     |                          |   GL Viewer   |
     |----------------|                          |---------------|
     |                |                          |               |
     |     sample     |                          |    remote     |
     |  application   |                          |    viewer     |
     |                |                          |    client     |
     |----------------|                          |               |
     | Remote Viewer  |                          |               |
     |----------------|   init info, images      |---------------|
     |    Network     |------------------------->|    Network    |
     |   Utilities    |<-------------------------|   Utilities   |
     '----------------'   mouse, keyboard, acks  '---------------'
 
          SERVER                                      CLIENT
          
   The sample application is linked with the remote viewer server functions
   (commmon/remote_viewer.c) and generates images using its OpenCL sample
   kernels. Images are streamed to the remote viewer client 
   (remote_viewer/viewer.c) using the TCP socket network utilities 
   (common/network_utils.c). The viewer displays the images using the 
   GL viewer services (common/gl_viewer.c).

   The viewer client and server sample application can be launched in either
   order. In addition, the viewer client also supports remote sample 
   application launch.

   If the remote viewer client is run in a big endian processor, there 
   is a chance that MesaGL will inadvertantly byte swap the image data. 
   If you find that images are incorrectly colored (primarily red for the
   remote viewer samples), then a byte swap correction is required by
   exporting the "GL_VIEWER_BYTE_SWAP" environment variable in the shell
   the viewer client is run.


================================================================================
PREREQUISITES
================================================================================

   The remote viewer client requires the installation of the OpenGL and
   freeglut (freeglut and freeglut-devel).

================================================================================
HOW TO BUILD  
================================================================================
   
   On the system the remote viewer client is expected to be run, change to the 
   OpenCL-samples-0.3-0, remote viewer client directory and type "make":

       cd OpenCL-samples-0.3.0/remote_viewer
       make

================================================================================
HOW TO RUN    
================================================================================
   On the display client system, invoke the remote viewer client, specifying
   the server's hostname:

       ./viewer <hostname>

   In addition, the server's, remote viewer enabled application must be started. 

   The viewer client can also be used to launch the server's application. It does
   so using ssh and an optionally specified user. See below for an example.

================================================================================
COMMAND LINE SYNTAX
================================================================================

   Usage: viewer [-V] [-H] [-p <port_number>] [user@]<hostname> [<remote_application>]

   Launch the viewer for a remote application. The <hostname> specifies the 
   host the remote application is running on, or to be run on. The viewer 
   can also launch the remote OpenCL application by specifying the 
   "remote_application", including path and parameters. The remote application 
   is launched using ssh with the optionally specified "user".

   For example, the following invocation executes the viewer and remotely 
   launches the julia sample on an accelerator device.

      viewer host "julia_remote -a"

   Options:
      -H, --help               Display usage help
      -V, --verbose            Emit verbose informational output.
      -p, --port #             Connect to server via the specified port number. 
                               Default port if unspecified.

================================================================================
END OF TEXT
================================================================================