/********************************************************************************* /* * /* Cpw or "Cross-platform Windowing for OpenGL" is an adaptation of Mark * /* Kilgard's GLUT library version 3.7. This library is true free software, * /* use is granted with only minor restrictions. Please send any bug * /* fixes, additional ports, and feedback to the cpw mailinglist address below. * /* The GLUT 3.7 library was used as a framework in developing this code. * /* Because of this I would like to graciously thank Mark Kilgard for his * /* hard work on the GLUT library. * /* * /* Other developers have had an important role in the development of this * /* library. Please note the developer credits on the Cpw web site. If you * /* use this library, please mention these developers on your web site or * /* in your documentation. * /* * /* Cpw web site: (for now) http://www.mathies.com/cpw/ * /* Cpw mailing list: (for now) cpw@mathies.com * /* license: The "Lua License" (see below) * /* * /* This Cpw Version: Beta 1.0 * /* * /*********************************************************************************/ Differences between GLUT and Cpw: Well, first off, this is a complete re-write. In writing the library, I have sometimes cut and pasted some of Mark's code into the project to use as a template, but I did not integrate any of his code into this library. Cpw is smaller than GLUT, and faster too (imho.) Especially when you have alot of windows. The source is squeaky clean, well commented, and easy to read and debug. The library is more reliable than GLUT on Win32 (imho.) I have addressed every GLUT issue mentioned in the opengl.org FAQ: http://www.opengl.org/developers/faqs/technical.html The library is aimed at three primary platforms, Win32, OSX, and Linux. As such, anything specific to other platforms has not been ported. This is a "modernized" version of GLUT (imho). A number of GLUT features which do not apply to the three main platforms are not supported. Input devices which are not supported on the three primary platforms are not supported. (What the heck is a 'button box' anyway?) Cpw interfaces have been improved (imho.) Some of the interface functions have new parameters that must be passed in. Timers are a notable example, you can now create recurring timers so you don't have to repeatedly call cpwTimerCallback every time a timer times out. All of the api's now have a parameter 'pCpw cpw' passed in first which is the library's state context. This allows for multi-threaded programming within a single process. Porting GLUT code is very easy however, since the general feel of the GLUT api has been maintained. The library supports clean init and shutdown. All memory allocated by the it is freed on close and cpwMainLoop returns. It is designed for use in embedded systems and to be embedded in applications that don't necassarily call exit when they close. All api's propagate their errors back out to the calling process. There is no call to exit anywhere. __glutFatalError('blah') {exit(0);} doesn't exist in this library. The library does not support GLUT font calls, but does support a really easy to use interface to FreeType 2.0. It can render pixelmap fonts, textured fonts, and 3d fonts using user supplied True-Type font files or localhost font files if they exists. Cpw is a cross-platform library through-out. There are no X Windows wrappers for non x-window platforms. Cpw is design for all platforms, not just one. '#ifdef blah #endif' is not used anywhere. All localhost code is contained within a single platform specific adapter .h and .c. Everything else is cross-platform in design. All localhost specific calls use the naming convention 'cpw_localhost_xxxx()' so they can easily be distinguished from the rest of the code. Each module of the library also has it's own naming convention, and i've tried to keep inter-dependency between various modules to a minimum. A number of tweaks and hacks in GLUT have not crossed over. I can not be sure these "features" still apply, so I haven't implemented them. Here's a good example: "XXX Brad's Matrix Millenium II has problems.." in win32_glx.c. Has Matrox updated their drivers so this isn't needed anymore? Does anybody even use a Matrox II anymore? Who the hell is Brad? These funny little hacks are issues which will need to be worked out again if they are still relevant. IMHO this is fine, because unneeded hacks are not be supported, and as such, will not take up code space or compute time in this library. Commenting is presented in a professional manner. You won't find weird comments like "windows is dumb because blah.." in Cpw. Everything is commented in detail and comments are to the point. Window z-order control and window events are handled in a much more robust way; Cpw sends an id with window events which identifies the window the event applies too. You can swap buffers on a single window or all at once. Cpw supports a number of new window events too, including create and destroy for resource management. Cpw also supports window event filtering, and has an event stack you can manipulate. Cpw does not support sub windows. Is there a need for such functionality? Time will tell. I'm thinking a "borderless window" might suffice. Cpw does not support overlay planes. And most importantly, Cpw source code _is_ in the public domain. You are free to use it any way you see fit, including for commercial purposes. You are free to modify it, hack it, change it, and bend it (but don't break it) to suit your needs. Just please don't release a heavily modified version with the same name so people don't get confused. I would like this to be a community managed piece of code. I don't want to control it, or stipulate the direction the community wishes to take with it. I am happy to continue to manage the win32 source, and help arbitrate updates and changes overall. OpenGL 1.2: Cpw works with the OpenGL 1.1 specification. Microsoft has promised the release of OpenGL 1.2 for Win32. But since they have a looooooong history of breaking their promises to developers who don't support their proprietary api's, I wouldn't expect this any time soon. (Prove me wrong Bill please!) You can get 1.2 functionality using either Sci-Tech's GLDirect or Mesa3D, both of which have been tested and work with Cpw. Although you have to purchase Sci-Tech's GLDirect, on a number of video boards it can improve your gl performance by 2x or even 3x. They currently have a 30 day free trial download on their site. (http://www.scitechsoft.com/) To compile and use Cpw: 1) download the latest FreeType 2.0 library and compile it into a multi-threaded or single-threaded library. Put the lib file in the Cpw 'libs' sub dir. (For Win32 users, there are precompiled libs in the libs dir already. They are the multi-state version, and use the MS multi-threaded system DLL's.) 2) take a look at cpw_config.h. If Cpw has been ported to your platform, about the only thing you'll need to set is the location of your gl include files and the location of your FreeType 2.0 include directory. You may need to add an include search path to your freetype include directory as well. 3) compile the library. You must have CPW_INTERN defined when compiling the library itself. Define CPW_EXTERN otherwise. 4) write your application. Cpw's main include file is "cpw.h". Just include this in your code and link to the lib from step 3. Make sure your compiler knows where cpw.h is too. A number of samples are available. Use these for examples of how to use Cpw. To port Cpw to a new platform: 1) take a look at the cpw_hosttemplate.h file. These are the functions you have to port to your platform. Everything else in the library is cross-platform in design. If you run into something that isn't please let me know. 2) write your cpw_(your platform).h/.c file. 3) compile the library and in doing so create a project or make file. Put project build associated files in "projectfiles/yourplatform/". The platform specific .h and .c should be located here. Do not put platform specific code in the 'src' or 'include' cpw directories. 3) compile and run the Cpw conformance demos. Make sure everything works the way each demo is supposed too. If it doesn't, fix it so it does. 4) create a web page where people can download it and announce the release to the Cpw mailing list. I'll link to it off the cpw download section on the Cpw web site. To create a new Cpw add-on: 1) add-on's usually support two internal functions defined in your header file: an init function: cpw_addonname_init( pCpw cpw ) an exit function: cpw_addonname_exit( pCpw cpw ) add-ons which require state can add an add-on context (type of pVoid) to the cpw state structure. The docs for your add-on should explain what to add to cpw_state.c. Add init and exit functions to cpwInitContext and cpwFreeContext calls if your add-on needs them. 2) write your cpw extension api. add-on api's should adhere to a naming convention: cpwextMyApiCall( pCpw cpw, param, param, .. ); please do not use the "cpwApiCall" naming convention. If a certain add-on becomes very popular and the community agrees, we can add it to the core library spec. add-on files should be stored in the add-on cpw sub-folder under a directory named after your add-on. Files should be named accordingly: cpwext_xxx.h/.c cpwext_xxx_platform.h/.c. 3) test your api and maybe write a conformance demo for it so other folks can port and test it on their platforms. 3) create a web page where people can download it and announce the release to the Cpw mailing list. I'll link to it off the cpw add-ons section on the Cpw web site. Make sure and include instructions on how to add it to the cpw source base. For the most part 'api extension' add-ons should not require changes to any file in cpw except cpw_state.c and cpw_state.h. You are welcome to create 'patch add-ons' too, which replace core library files with code that implements the same functionality in a different or better way. These add-ons may well become part of the core distribution if the community likes your code. Cpw add-ons should: - free all resources they allocate - use cpwmalloc, cpwrealloc, and cpwfree - adhere to cpw typing conventions - conform to the ansi-c coding standard Cpw add-ons should not: - use non-constant static variables or code that is not multi-state. - use malloc, realloc and free. - conflict with existing add-on api function names.( unless they do the same thing and you figured you could write a better add-on. ) Win32 Adapter Notes: - There are compile switchs in the cpw_config.h file which flip between DirectInput and WinBase for various types of input device access. The default for joystick access is DirectInput, other are WinBase. If you have trouble getting the Cpw DirectInput Joystick code to compile flip to WinBase. - If you think Direct3D has better performance, try GLDirect from Sci-Tech. Your app will use the Direct3D interface 'under the hood' and it will _also_ run on any platform Cpw gets ported to. Pretty cool eh? Combined with OpenAL (see below), it's a win-win situation dude. OSX Adapter Notes: - It doesn't exist yet Linux Adapter Notes: - It doesn't exist yet Why did I originally write Cpw? - I work on a project called Yindo (www.yindo.com) which uses GLUT. Unfortunately GLUT was not designed for commercial use nor was it design for the way we use it in Yindo. I always knew a replacement would be necassary. Since I use a great deal of free software in Yindo, I decided to free source this GLUT replacement in an effort to give a little something back. - I hate the fact that people have told me "OpenGL isn't reliable on Windows." (Most notably Alex St. John of wildtangent.com. Jab Nudge) Screw that. OpenGL is the best 2D and 3D rendering API in existence and it can be reliable on Win32. Direct3D is a big ugly COM mess, it requires a huge software installation, and it isn't cross-platform. Open standards gave birth to everything great. (See RFC 793 for a good example) Proprietary standard hinder advance. imho. - I don't like the name 'GLUT'. - I love programming games. Misc. Thoughts: - This code is intented as a "developer tool" and not a shared library. If you don't mind dealing with upgrade issues I incorrage you to modify the library to suit your needs. In some cases this can improve your performance since you are welcome to comment out chunks of code you never use. - I think it would be cool if people created add-ons that made using popular GL extensions easy. But I haven't written one yet since my video card is crud! - A hash list patch add-on for the library's list. If you have alot of windows, a hash will probably beat the current linkedlist's performance. But for apps with only a few windows, the linkedlist is probably better. About the Copyright: I'm not sure i've handled this in the appropriate way. I think somebody has to keep a copyright to enforce the license, but I probably won't be the only guy who writes code for Cpw. Comments welcome. About the license: The Lua License is the license used by the Lua Virtual Machine (www.lua.org). It stipulates that Cpw is _true_ free software unlike the GPL. (jab nudge) Background music: Most of this code was developed while listening to "The Chill Spot - Intelligent Drum And Base" which can be found on www.live365.com. Who I am: Just another software developer. I live in the state of Florida, USA. See www.mathies.com for more details. I do not proclaim to be god's gift to programming. if you find something in this library that you feel can be implemented in a better way, please do and post your changes to the mailing list. Other cool librares you should check out: OpenAL (www.openal.org) cross-platform open-source 3D sound with a procedural interface like OpenGL's. Very reliable on Win32, and very easy to use. Hides all of that nasty COM D3DSound crap from the developer. Works whether you have D3D installed or not. (Even on NT!) Also runs on Linux and OSX, (and a few other platforms I think.) Very cool. (LGPL Licensing) FreeType Font Library (www.freetype.org) Kick butt cross-platform font rendering library. David Turner rules. (Free Licensing) Lua Virtual Machine (www.lua.org) A simplistic, yet powerful OO language and light-weight vm. Very well suited for game AI scripting. Fast and easy to learn. A number of game companies are already using it, you should be too. I'm planning on adding a game AI scripting add-on to Cpw which makes use of it. SDL: The Simple Direct-Media Layer (www.sdl.org?) A higher level api than Cpw, supports OpenGL rendering and alot of other nifty things game programmers don't like to write from scratch. (LGPL Licensing) HawkNL/NLU/Voice (www.hawksoft.com) Easy to use cross-platform alternative to Microsoft's DirectPlay and DirectPlay Voice api's. Don't like COM? Can't stand socket programming? Want to network your game? Check this out. (LGPL Licensing) /********************************************************************************* /* * /* A basic cpw program: * /* * /* #include * /* #include * /* * /* void draw( pCpw cpw, int winid ) * /* { * /* /* do some gl stuff to win */ * /* } * /* * /* int main(int argc, char* argv[]) * /* { * /* pCpw cpw; * /* * /* cpw = null; * /* cpwInitContext( &cpw ); * /* * /* cpwCreateWindow( cpw, "Cpw" ); * /* cpwDisplayCallback( cpw, draw ) * /* * /* cpwMainLoop( cpw ); * /* * /* cpwFreeContext( &cpw ); * /* return 0; * /* } * /* * /*********************************************************************************/ /********************************************************************************* /* * /* Cpw is Copyright 2001-2002 by * /* Jim Mathies, * /* All rights reserved. * /* * /* Permission is hereby granted, without written agreement and without license * /* or royalty fees, to use, copy, modify, and distribute this software and it's * /* documentation for any purpose, including commercial applications, subject to * /* the following conditions: * /* * /* - The above copyright notice and this permission notice shall appear in all * /* copies or substantial portions of the software's source code. * /* * /* - The origin of this software must not be misrepresented; you must not * /* claim that you wrote the original software. If you use this software in a * /* product, an acknowledgment in the product documentation would be greatly * /* appreciated (but it is not required). * /* * /* - Altered source versions must be plainly marked as such, and must not be * /* misrepresented as being the original software. * /* * /* The authors specifically disclaim any warranties, including, but not limited * /* to, the implied warranties of merchantability and fitness for a particular * /* purpose. The software provided hereunder is on an "as is" basis, and the * /* authors have no obligation to provide maintenance, support, updates, * /* enhancements, or modifications. In no event shall the authors * /* be held liable to any party for direct, indirect, special, incidental, or * /* consequential damages arising out of the use of this software and its * /* documentation. * /* * /*********************************************************************************/