**************************************************************************
*                                                                        *
*         GLUT for Rhapsody Developer Release 2 / MacOS X Server         *
*                                                                        *
**************************************************************************


1.) Packages and there Contents:

 a) MacOSXGLUT-1.0-P-b.tar.gz - Binary distribution
    
    - GLUT.framework
    - GLE.framework
    - MUI.framework
    - A number of cool demo applications using GLUT, GLE, MUI.
    - GLUT man pages
    - GLE man pages
  
 b) MacOSXGLUT-1.0-PI-s.tar.gz - Source distribution
    
    - GLUT.framework
    - GLE.framework
    - MUI.framework
    - A number of cool demo applications using GLUT, GLE, MUI
    - All GLUT test programs
    - GLUT man pages
    - GLE man pages
  
 c) MacOSXGLUT_Demos-1.0-PI-s.tar.gz - Source of example programs

    - All example programs that come with the standard GLUT distribution.


 d) MacOSXGLUT_Data-1.0-PI-b.tar.gz - Textures

    - Texture files needed for some of the example programs.


2.) General Information:

    This is version 1.0 of the MacOS X Server GLUT implementation. It is
    based on GLUT version 3.7 beta from Mark J. Kilgard.
    See the Copyright section for distribution and copyright notices.
    Bug reports and/or questions specific to this port of GLUT should go
    to Planitzer Dietmar (dave.pl@ping.at). 
    
    There is currently no web site for MacOSXGLUT, but you can obtain
    general information about GLUT itself from:
    http://reality.sgi.com/mjk/glut3/glut3.html
    
    This port of GLUT has a number of special features which should help
    making your daily life working with GLUT applications easier:
    
     Copy to Clipboard.
      You can copy the contents of the current window, the one which is
      key, to the pasteboard every time, even while an animation is running.
      The data is written in TIFF format to the general pasteboard.
      You can even take a look at the data currently stored on the paste-
      board server if you select "Show Clipboard" from the Edit menu. All
      standard data types are supported: various text formats, EPS, TIFF
      and sound.
     
     Services
      The contents of the current window can be sent via services to other
      applications at any time. All applications which are able to accept
      EPS, TIFF or RTFD data are supported.
      This mechanismn is very handy - i.e. if you want to send your newest
      and greatest graphics to your colleagues, simply select
      "MailViewer->MailTo" from the Services menu, which will bring up the
      MailViewer application displaying a new letter containing the graphics.
    
     Saving Window Contents
      It is also possible to save the current windows contents to a file on
      your local disk (URL and thus remote support, will be added in
      version 1.1). The data will be safed in uncompressed TIFF format.
     
     Printing
      Printing as EPS is also supported.
     
     Faxing
      Although, the necessary code to enable direct faxing from within any
      GLUT application is there, faxing is broken in RDR2.
      The problem is the fax panel, which has a bug in the menu creation
      code. If you have MacOS X Server Beta - give it a try, maybe it works !
     

3.) Installing the Frameworks and Examples:


    Installing the necessary pieces is very easy, even if it doesn't come
    with an installer application.
    Simply follow these steps:
    
     a) Unpack the MacOSXGLUT binary package by typing the following into
        Terminal.app (You can use GUI utilities like OpenUp.app from
        www.stepwise.com, if you prefer the graphical way):
        
         gnutar -xvzf MacOSXGLUT-1.0-P-b.tar.gz
        
     b) Move the resulting three frameworks GLUT.framework, GLE.framework
        and MUI.framework to /Local/Library/Frameworks.
     
     c) cd into the GLUT-Examples folder and run the examples.
    
    If you experience problems, make sure that you have Conix's OpenGL
    installed in /System/Library/Frameworks, because the binary
    distribution is per default compiled to these framework.
    
    If you want to use MacOSXGLUT with Mesa3D you need to get the source
    distribution and unpack it with the following command in Terminal.app
    
     gnutar -xvzf MacOSXGLUT-1.0-PI-s.tar.gz
    
    You will end up with an aggregate project type containing all three
    framework subprojects and a number of example programs.
    To see how you can configure MacOSXGLUT to use Mesa instead of Conix,
    see the next section.


4.) Compiling the MacOSXGLUT Aggregate Project:


    MacOSXGLUT uses a flexible class cluster solution to interface with
    a concrete OpenGL implementation. This makes it possible to decouple
    the core GLUT code from the code that deals with the OpenGL subsystem.
    The class cluster consists of the public class GLUTVisual, which
    provides the public interface necessary to create, select between and
    destroy a GL context and the two private subclasses GLUTMesaVisual and
    GLUTConixVisual. This two subclasses implement the interface to either
    Mesa3D version 2.6 or Conix's alpha OpenGL for RDR2 from July 1998.
    
    Now, to build MacOSXGLUT for use with Mesa3D version 2.6 you need to do
    the following:
    
     a) Select the aggregate project (top-level project) and enter this line
        in the Compiler Flags field of the Build Attributes inspector:
        "-DMACOSX -DGFXLIB_MESA26".
      
     b) Add the GL.framework to the framework section of every sub-project.
    
    In order to use Conix's OpenGL implementation do the following:
    
     a) Select the aggregate project (top-level project) and enter this line
        in the Compiler Flags field of the Build Attributes inspector:
        "-DMACOSX -DGFXLIB_CONIX".
     
     b) Add the OpenGL.framework to the framework section of every sub-project.
     
     c) Add the dynamic library libGLU.dylib to the library section of every
        sub-project.
   
    Before you actually build the project with the make target "install",
    you should clean it.
    Make sure that you enter the compiler flags at the top-level, aggregate
    project, and that you add the necessary frameworks in each of the sub-
    projects.
      

5.) Things specific to the MacOS X Server port:


 a) The following command line options are ignored and wouldn't make much
    sense on MacOS X Server anyway:
    
     -display, -direct, -indirect, -iconic, -sync
    
 b) The following command line options are specific to this GLUT implementation:
     
     -multimouse
     
      This option allows you to turn off the multibutton mouse emulation mode
      that is enabled per default. If you don't specify this option, you can
      use your onebutton mouse together with the Alt and Ctrl keys to emulate
      a three button mouse. The following modifier keys are used:
       
       no modifier key and click    -> left mouse button
       ALT modifier key and click   -> middle mouse button
       CTRL modifier key and click  -> rigth mouse down

 c) GLUT top-Level window positions are NOT considered as beeing relative to
    the window's content area as it is the case with standard AppKit windows,
    rather they are used to specify the top-left corner of the window's frame
    rectangle.
    This behavior may change in version 1.1.
     
 d) The video resizing API is not supported.
    If there is no special hardware to support it - it wouldn't be funny to
    use it anyway, believe me.
 
 e) Extended input devices like trackballs, tablets, joysticks and so on
    are not supported.
    There is no support for this kinds of devices in AppKit or DeviceKit at
    this time (RDR2). I hope that IOKit in MacOS X will have the necessary
    classes and concepts to integrate this types of devices in a clean and
    decent way. If that's the case you can be sure that I will add the
    necessary support for all input devices that GLUT can support in a new
    release.

 f) Colormaps and thus indirect OpenGL rendering is not supported.
    The current DPS implementation does not support per window colormaps.
    Considering that DPS will be replaced with a PDF based Enhanced
    QuickDraw in MacOS X and that indirect drawing modes are not as
    important today than they used to be, I simply decided to leave color-
    map support out for now.
    If there is better colormap support in a future MacOS X version, I will
    release a new MacOSXGLUT with support for colormaps.


6.) Known Problems:


 a) Menus.
    The menu sub-system is currently not fully implemented (and in reality a
    awful hack). I.e. It supports only up to three menus at the same time and
    it can't manage menus on a per window basis as they should be.
    This is a well known issue and will be resolved in version 1.1, which will
    have a very powerful and elegant menu sub-system, that will be fully
    complient with Apple's interface guidelines.
 
 b) Overlays are not working.
    There is currently no support for overlays in RDR 2. Maybe I'm going to
    provide software overlay planes in version 1.1, but don't count on this.
  
 c) Window Status callback.
    I spended a good portion of the time needed to port GLUT, trying to get
    the window status callback to work like it should, and at least the GLUT
    test program No. 22 works now like a charme. But I'm still not sure that
    it is without any problems.
    In either way, only windows belonging to the GLUT application are taken
    into account when the window status has to be recomputed.
    That means, if a window of your favorite text editor covers one of your
    GLUT application's windows and you move this text editor window to a
    different location, exposing at least parts of a GLUT window, no window
    status change will be reported to your GLUT program.
    I have no intention to change this behavior.

 d) Positioning of Top-Level Windows.
    Sometimes it's possible that top-level windows will be erroneously
    positioned.
    
 e) Iconic command line option.
    The iconic command line option does not work in this release. If you use
    this option a warning will be printed and the option ignored.
    As of now I'm not sure if I will implement the option in version 1.1,
    because AppKit doesn't currently provide a way to create a window in
    an iconified state.

 f) Damaged windows are sometimes not updated.
    This is extremly rare. The only program that I've found so far showing
    this behavior is Newave.
 
 g) Faxing does not work.
    The Fax panel in RDR2 is broken. This should work in MacOS X Server.

 h) Cursors.
    Only the text and arrow cursor are currently supported. Other cursors
    will be supported by a later release when the needed API is publically
    available.
 
 i) glutGameModeString() does not work.
    The game mode string is currently ignored. The result is that whenever
    you switch into game mode, the resolution and referesh rate that you
    have set in the monitor preference will be used instead. Version 1.1
    will probably have full support for game mode.

 j) Sub-Windows are not correctly displayed if Conix's OpenGL is used.
    The July alpha build of Conix's OpenGL allows only NSWindows as it's
    drawable but not an NSView instance. This is a known problem which you
    can consider as already solved. 


7.) Useful Links:

 
    The following links maybe helpful to find out more about GLUT, OpenGL
    in general and the currently available OpenGL implementations for
    RDR2:

 a) GLUT's homepage:
     
     http://reality.sgi.com/opengl/glut3/glut3.html
 
     It contains everything about GLUT, especially documentation and the
     original implementation for X-Windows and Win32.

 b) OpenGL developer homepage:
     
     http://www.opengl.org/Viewpoints/DevView.html
     
     This site has a myriad of links to all forms of documentation,
     example programs and OpenGL implementations.

 c) Mesa3D version 2.6 download for RDR2:
   
     ftp://ftp.next.peak.org/pub/rhapsody/Developer/Frameworks/
     
 d) Conix's OpenGL for RDR2 download site:
    
     http://www.conix3d.com/download_request.html


8.) Copyright:


The OpenGL Utility Toolkit distribution for Rhapsody Developer
Release 2 and MacOS X Server contains source code modified from the
original source code for GLUT version 3.7 Beta which was developed
by Mark J. Kilgard.  The original source code for GLUT is Copyright
1997 by Mark J. Kilgard.
GLUT for Rhapsody DR2 / MacOS X Server is Copyright 1998 by Planitzer
Dietmar and is not in the public domain, but it is freely distributable
without licensing fees.
It is provided without guarantee or warrantee expressed or implied.
It was ported with the permission of Mark J. Kilgard by Planitzer Dietmar.

THIS SOURCE CODE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OR MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

OpenGL (R) is a registered trademark of Silicon Graphics, Inc.
