************************************************************************** * * * 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.