This file provides cygwin specific (http://www.cygwin.com) information
on configuration and installation of POGL.

=================================================================
                         INSTALLATION
=================================================================

CYGWIN / GLX
-----------------------------------------------------------------

To install POGL on cygwin+XP you need to use the Cygwin setup
program to install a current version of Cygwin including Perl,
w32api, X11, FreeGLUT, and all the developer tools.

The cygwin POGL port was tested to work on a full cygwin install.

The standard perl module install process works:

  Download and extract the distribution directory and then,
  in an xterm shell:

    perl Makefile.PL # same as perl Makefile.PL interface=GLX
    make
    make test
    make install

  This will build and install POGL in the standard locations
  using FreeGLUT via GLX, the X11 interface to OpenGL.  For cygwin
  X11, the OpenGL library is Mesa (software rendering) and the GLX
  inteface is only emulated.

  If you do not configure in an xterm shell, the glversion
  utility will fail to report GPU capabilities, and may reduce
  the features and performance of your installation.  The
  test app will fail, as well.


CYGWIN / W32API
-----------------------------------------------------------------

  It is also possible to configure POGL to use the native
  MS OpenGL renderer which is usually hardware accellerated.

    perl Makefile.PL interface=W32API
    make
    make test
    make install     # don't install if make test fails

  Note: this builds successfully for some, not for others.
  We appreciate feedback on whether or not this works for you...
  Please use "verbose" on Makefile.PL and send us your console
  output to pogl@graphcomp.com

  The W32API interface does not require an xterm shell for
  building/testing/using. It also produces a binary installation
  that can be run on any win32/cygwin system.  As with the
  X11/Mesa default, POGL will use the FreeGLUT library and
  will install the win32 version if needed.

  If you do not have accelerated OpenGL supported for your
  display (either the hardware does not support acceleration
  for the current mode or the vendor drivers are not
  installed) then the system will fall back to the default
  Microsoft GDI renderer (slow and may not support the newer
  OpenGL versions).



=================================================================
                            PROBLEMS
=================================================================

1. There is a known issue on cygwin where DLLs have to have
   their base addresses fixed so that runtime conflicts do not
   occur.  The problems occur for the external modules and their
   interfaces using DLLs.
   
   The only symptom is usually a mysterious failure to run.
   
   The current POGL testers on Cygwin have not reported
   this problem but it is possible.  *IF* you have this
   problem, the fix is to use the rebaseall command to
   adjust the base addresses for the cygwin DLLs as follows:
   
   
     0. Generate a list of additional DLLs to check
        (the perl5 install directories and/or the blib/
	directory of the OpenGL source directory if the
	problem occured during make test:
   
        find /usr/lib/perl5 /usr/local /OpenGL/blib \
             -iname '*.dll' > /bin/fixit.list
   
     1. Exit all cygwin processes, windows, shells, X server,...
   
     2. Start up a windows CMD shell window (Start->Run cmd)
   
     3. cd to the cygwin /bin directory (e.g. c:\cygwin\bin)
   
     4. Run ash in that directory (ash)
   
     5. Run rebaseall (./rebaseall -T fixit.list)
   
          Note that we created the fixit.list file in the
	  c:\cygwin\bin folder to begin with.  If you put
	  it elsewhere, you'll need to use the appropriate
	  pathnames.
   
   After the rebaseall command has completed, you should be
   able to start up X windows and rerun the failed test
   (make test) from the source directory as above.


2. If you use the X11/Mesa option, there is a known bug
   where resizing the window with the OpenGL context in
   it causes a crash of the cygwin X11 server.



=================================================================
                              NOTES
=================================================================

OpenGL is a graphics rendering library.  Any window system
specific code is platform dependent.  Most platforms have
a single vendor window system and provide the requisite
interface library to OpenGL for things like creating windows,
setting/getting display properties, etc:

  X11: GLX

  MS Windows + FreeGLUT: W32API

  AppleOS: AGL

  FreeGLUT/GLUT: FreeGLUT

Cygwin provides both GLX (to interface to X11/Mesa
software renderer) and W32API (via FreeGLUT to interface to
the native MS Windows OpenGL).  Use the INTERFACE= option
to perl Makefile.PL to select the desired interface
(GLX or W32API) to build POGL.

* The flag and option names are case insensitive.

* The interface is *not* dynamically selectable.  You use the
  one you initially configured.

* For W32API, the interface is configured for the capabilities
  of the current display format (size, color depth).  If you
  change display settings, the interface may no longer be
  valid.  If so, you'll need to reinitialize your GL context.
  
  - For flexibility, use the default X11/Mesa interface.

  - For win32 binary distributions, hardware performance, and
    full use supported OpenGL extensions use W32API.  This may
    become the default for cygwin in the next POGL.
    
  - NOTE: There is an accelerated X server in cygwin (XWin_GL)
    that offers more hardware performance for the GLX + Mesa
    OpenGL.  This has not been tested.  It likely that the native
    win32 performance is better and more robust.



=================================================================
                   COMPILING OPENGL ON CYGWIN
=================================================================

This is how to compile OpenGL code in Cygwin using either the GLX
interface or the WGL interface (via w32api).  For my systems, the
directories containing OpenGL, GLU, and FreeGLUT libraries are:

  /usr/X11R6/lib : for X11/Mesa and freeGLUT
  /lib/w32api    : for native windows OpenGL
  /lib/mingw     : guess they could be MinGW specific (not used)

This is the way to compile a programs using the native win32
OpenGL where the include files gl.h, glext.h, glu.h, glut.h are
found in the /usr/include/w32api/GL directory (If you have w32api
installed this dir may be in the default includes path):

  gcc -o glut2 glut2.c -L/usr/lib/w32api/ -lglut32 -lglu32 -lopengl32

This is what you need to compile with the standard X11 OpenGL
using the GLX interface (Mesa implementation on cygwin).  Note
the specific inclusion of the X11 include path so that the GLX
OpenGL headers are used (and not the win32 ones) : 

  gcc -o glut2 -I/usr/X11R6/include glut2.c -L/usr/X11R6/lib -lglut -lGL -lGLU

The best way to unambiguously link is to specify the full file
pathnames rather than the -lxxx names but the above should work
for most cases.
