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

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

   Name: Quaternion Julia Set Ray-tracing Sample

   This sample was inspired by Keenan Crane's work to implement
   Julia Set ray-tracers on GPUs using Nvidia's Cg language. 
   Procedurally generated surfaces serve as an ideal OpenCL 
   workload because their dynamic resolution independent nature,
   high computational intensity, and low memory foot print.

   The Julia sample illustrates how to port a vectorized workload
   to OpenCL.  It allows for double buffering of compute and
   display for maximum performance.  The kernel computes four 
   pixels at a time in SOA (structure of arrays) form then writes 
   them directly to the framebuffer provided by the host program.
   The Julia sample serves as a great framework for writing a high 
   performance compute or rendering application in OpenCL.

   The original ray-tracing algorithm for the Julia set can be
   found in the paper titled "Ray Tracing Deterministic 3-D
   Fractals". Keenan Crane's Cg code base was used as the starting
   point for this sample.

   Three different versions of the Julia Set sample are built for
   for both 32-bit addressing and 64-bit addressing. They are:

   julia         Julia Set sample that computes frames without
                 display. Useful for measuring OpenCL device 
                 computational performance.

   julia_gl      Julia Set sample that displays frames using 
                 the "GL Viewer". The GL Viewer (common/gl_viewer.c)
                 depends on OpenGL and the OpenGL Utility Toolkit 
                 (called GLUT). The display device can be either
                 HW accelerated or software enabled, and either local
                 or remote depending on the system enviroment and X11
                 DISPLAY environment variable setting.

                 If the rasterization is performed by MesaGL on 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), then a byte swap correction is required by
                 exporting the "GL_VIEWER_BYTE_SWAP" environment 
                 variable.

   julia_remote  Julia Set sample that displays frames using 
                 the "Remote Viewer" client. The remote viewer is a 
                 separate application that displays image data
                 computed by the server application (julia_remote).
                 Communications between the client and server is
                 over TCP sockets. More details on the remote 
                 viewer are found in the Remote Viewer's readme
                 (remote_viewer/readme.remote_viewer.txt).

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

   The Julia Set samples that provide viewer support (julia_gl 
   and julia_remote) require the installation of the OpenGL and
   freeglut (freeglut and freeglut-devel). If glut is not installed,
   then the julia_gl and julia_remote programs are not built.

================================================================================
HOW TO BUILD  
================================================================================

   Change to the OpenCL-samples-0.3-0 directory

       cd OpenCL-samples-0.3.0

   To build for 32-bit addressability, change to the ppc directory and type 
   "make":

       cd julia/ppc
       make

   To build for 64-bit addressability, change to the ppc64 directory and type 
   "make":

       cd julia/ppc64
       make

================================================================================
HOW TO RUN    
================================================================================

   To run on the accelerator (Cell SPU):
       ./julia --accel

   To run on the CPU:
       ./julia --cpu

   To run with the GL Viewer using the default OpenCL device with verbose output:
       ./julia_gl -V

   To run with the Remote Viewer with a image size of 1024 x 768:
       ./julia_remote -w 1024 -h 768

   The julia sample will terminate after generating the specified "iteration" 
   frames.

   The viewer enabled samples, julia_gl and julia_remote, will run indefinitely
   and can be user terminated by pressing the "ESC" key with input focus is in 
   the display window. 

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

   Usage: ./julia [options]

          ./julia_gl [options]

          ./julia_remote [options]

   Examples:
      ./julia --accel -V       # Run on accelerator device with verbose output.
      ./julia --cpu            # Run on CPU device.

   Device Types Options:
      -a, --accel              Use Accelerator for compute.
      -c, --cpu                Use CPU for compute.
      -g, --gpu                Use GPU for compute.

      If a device type is unspecified, then the platform's CL_DEVICE_TYPE_DEFAULT
      is used.

   Run Options:
      -i, --iterations N       Number of iterations frames. julia only.
      -l, --lwgsize N          Local work group size. Must be an integral factor
                               of width/4. 0 or unspecified then OpenCL will choose
                               the best size.
      -w, --width N            The width, in pixels, of the ray traced image.
      -h, --height N           The height, in pixels, of the ray traced image.

   Output Options:
      -H, --help               Display usage help.
      -V, --verbose            Emit verbose informational output.

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