/*************************************************************************/
/*                                                                       */
/* 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: Perlin Noise Generator Sample
   
   Description:
   
   This sample is an OpenCL Perlin Noise generator, which computes
   noise textures that can be used to create more realistic images.
   It is based on Ken Perlin's Improved Noise implementation found
   at http://mrl.nyu.edu/~perlin/noise/.
   
   The sample demonstrates a data-parallel algorithm. It uses an
   NDRange kernel to compute each iteration of the noise algorithm
   on an in-order command queue. The resulting image data is read
   by mapping the output buffer to a host pointer.
   
   The kernel implementation outputs the result data by directly
   writing to the output buffer's location, which is pointed to by
   a global pointer argument, instead of using async copies.
   
   The work group size for the kernel can either be specified by the
   user via a command line parameter or the user can leave it to the
   OpenCL implementation to select the best work group size for the
   kernel. Some devices will not support all of the values for this 
   option.
   
   Three different versions of the Perlin Noise sample are built for
   for both 32-bit addressing and 64-bit addressing. They are:

   perlin        Perlin Noise sample that computes frames without
                 display. Useful for measuring OpenCL device 
                 computational performance.

   perlin_gl     Perlin Noise 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.

   perlin_remote Perlin Noise 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 (perlin_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
================================================================================

   IBM OpenCL Dev Kit version 0.3 or later is required to run this sample

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

   To build 32-bit binary, 
   cd to the ppc directory in the sample and type "make".

   To build 64-bit binary, 
   cd to the ppc64 directory in the sample and type "make".

================================================================================
HOW TO RUN   
================================================================================
   To run on the accelerator (Cell SPU):
      ./perlin --accel

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

   To display usage message:
      ./perlin --help

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

   To run with the Remote Viewer with a image size of 768 x 768:
       ./perlin_remote -s 768

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

   The viewer enabled samples, perlin_gl and perlin_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: perlin [options...]
          perlin_gl [options...]
	  perlin_remote [options...]

   Examples:
     perlin --accel -i 10     # Run 10 iterations on accelerator

   Device Type Options:  
     -a, --accel              use CBEA 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, --iter N             Number of iterations (default: 1000). perlin only
                              option.
     -l, --lwgsize N          Local work group size. Must be an integral multiple
                              of image width  / 4. 0 or unspecified then OpenCL
                              will choose the best size.
     -s, --size N             Image size (width and height). Must be a positive 
                              multiple of 16. Default is 1024.
     -v, --verify             Verify OpenCL device output compares equal to host
                              computed output. Defaul is non-verify.
     -V, --verbose            Emit verbose informational ouput. Default is 
                              non-verbose.

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