OS/2 Presentation Manager Game Development Guide

By Antonino Iannella



Introduction
This document is intended to be a guide for OS/2 users (or wannabes) to see more high-quality native OS/2 games. It is not designed to teach people how to write games, only as a reference guide for more information. A lot of this guide also relates to writing general OS/2 applications.



Copyright
This guide's author is Antonino Iannella. It is released into the public domain, and may be used by anyone. It is freely distributable using any medium or site. It may not be sold. The author has no authority over the way that it is distributed. It may not be distributed on the Microsoft Network (MSN) or used by Microsoft in any way. A breach of this policy will result in legal action.

The author shall not be made responsible for any errors, or damage caused by this guide's contents, so don't hit your grandmother with it!

This is what people who break this law will look like! :-) (Courtesy of Salvador Dali).



Revision History

 * Version 1.0 - An Email message to a colleague gave me the idea to make a reference guide.
 * Version 1.1 - An introduction was added.
 * Version 2.0 - A large amount of information was added, so it was decided to format the guide in OS/2 INF format, then distribute it.
 * Version 2.+ - Well? Please send any contribution you may have to the author!

Things to Learn
This section has some suggestions regarding the OS/2 Warp Presentation Manager programming.



Get Warped!
What are you waiting for? Go on, try it! OS/2 Warp is one of the most advanced and powerful operating systems in the world. Some of the many features are:
 * Robust, and reliable,
 * Object orientation,
 * Complete 32-bit architecture,
 * Real pre-emptive multitasking,
 * Easier to program than other platforms, and
 * Excellent multimedia support.



Now take advantage of the wide range of native applications. You can even run most DOS and Windows applications. Whatever you do, get Galactic Civilisations. This game by Stardock Systems is a must!

Choose a standard programming language
Find a commonly-used language to program in. It is important to know one! My personal preference is C. A lot of OS/2 applications, and games, are written in C (or C++). Lots of source code examples are, too.



If object-oriented programming is your scene, go for C++. The Warp Entertainment Toolkit is aimed at C++ developers. REXX is also a popular language. It is interpreted, rather than compiled. A REXX program will run slower than an equivalent C or C++ program. However, REXX programs are easy to write, and quite powerful. Multimedia with OS/2 REXX is easy, too. Refer to the MCIREXX.INF in your MMOS2 directory, if available.

OS/2 Warp Presentation Manager programming
Learn to program the OS/2 Presentation Manager in C (or your language of choice). Knowing basic PM programming will let you design a user interface for your game. The PM API functions may look overwhelming to the uninitiated. It is hard work to learn (and understand!) how to do the simplest tasks, however PM programming allows you to write powerful applications with minimal code.

GPI programming
The Graphics Programming Interface (GPI) is the method to draw primitive graphics in a PM window. It also handles bitmaps, metafiles, animation and other things. It is very functional, and sometimes complicated. I don't know much about it.



Other PM technologies
OS/2 Warp has many extra technologies which greatly enhance games. They are:
 * DIVE - Direct Interface to Video Extensions. It allows for really fast graphics or real-time video, and can play AVI or FLI format files effectively.
 * MMPM - Multimedia Presentation Manager. Allows easy-to-use multimedia features, such as playing WAV or MID-format files.
 * SOM - System Object Model. This lets the system and its applications have the concept of 'objects'. A directory is an object. An icon is an object. Your chess game opponent on a future, high-technology WAN which might extend into an unfathomable dimension, full of highly-developed alien life - but who are on the Internet - is also treated as an object.



Other technologies include DART, enDIVE, 3D animation, Real-Time MIDI, DirectDMA and networking features.

Miscellaneous suggestions
For more information on creating OS/2 Warp games, including an overview of the Warp Entertainment Toolkit, see http://www.austin.ibm.com/os2games.



Join the IBM Solution Developer's Programme in your country. It may also be referred to as the Developer Assistance Programme (DAP). Also, join the Worldwide DAP (Email wwdap@vnet.ibm.com). This gives you access to development software, including the Developer's Connection CD-ROM.

Join Club OpenDoc, see http://www.software.ibm.com/clubopendoc/index.html (or Email Club_OpenDoc@aussmtp.austin.ibm.com).



Do not be afraid to buy a book on the topic you are after!

Get all the issues of EDM/2 magazine that you can! There are many excellent articles about PM programming. The 'Gearing Up For Games' series gives an introduction to Warp gaming technologies, like DIVE.

You will probably be spending a lot of time in front of a computer. Be patient, and have regular breaks.

Don't be afraid to try things. Have fun while you are trying it.

Read the newsgroup rec.sys.programmer FAQ. It provides many useful references to books, companies, sites and techniques useful for game development. Most of the information relates to DOS programming, so it may not be useful for PM programming, except for techniques like artificial intelligence or virtual reality.

Games and animation may be resource-intensive; you may experience device driver problems.

Learn threads and semaphores. It is possible to write a simple text-based program where one can create, destroy, and pass messages between threads. Get a sound understanding of multithreading. Semaphores are useful to synchronise events.

Don't program in Ada.

People who 8514 video adapters cannot use (or view) DIVE instances. DIVE is not really necessary if you do not need to update large graphics regularly; GPI functions are sufficient in these cases.



Books Recommendations
Books may be ordered through the IBM SDP (DAP), or at your local bookshop. All the books listed are in English, unless stated otherwise.

Learning to Program the OS/2 2.0 Presentation Manager by Example - Stephen Knight

This book is a reasonable beginner's book, for PM C. It explains basic concept very well. It deals with basic PM window creation, simple GPI programming, help files, some GPI animation (which I couldn't understand), amongst other things. It uses one big example, which is a slide puzzle game. At times it may be hard to follow the large chunks of sample code.

The Art of OS/2 Warp Programming - Catherine Panov, Larry Salomon, Arthur Panov

This may be a better PM C beginner's book than the former. It deals with more concepts relating to PM programming, even multitasking. See http://www.iqpac.com/tao/index.shtml



Programming the OS/2 Warp GPI - Stephen Knight, Jeffrey Ryan

This book explains GPI programming in C. It is for beginning to intermediate programmer, and appears to explain difficult GPI concepts. It also uses one big example to illustrate all concepts. See http://www.wiley.com/compbooks/i5.html



Programming Multimedia in OS/2

This book is written for OS/2 2.1, so it does not explain all the features which were introduced with OS/2 Warp. it might be worth a miss, until it gets revised!

System-Programmierung OS/2 - Frank Eckgold (in German)

Quite a good reference but many typographical errors and mistakes in the early edition. It has some useful examples.

The Ultimate OS/2 Programmer's Manual - John Mueller

It is a good reference, but that's it. It has no sample programs. It is not a stand-alone buy, but an additional book where you will quickly find what you are looking for.

OS/2 Programmierung - T. Legenkamp, J. Bredno (in German)

It is a good introductory book with some samples, but no use at all as a reference. It has some information not available in the other books.

OS/2 Multimedia Programmierung - T. Legenkamp (in German)

The only reference to MMOS/2. It has the most important information on MMOS/2 but that's it. It is easier to use than the online help from VisualAge C++!

Other Resources
This section lists useful resources which any OS/2 developer should consider.

Compilers
Get one. I prefer EMX/GNU C. It has a C, C++, and an Objective C compiler. It's free. It does the job. Some commercial compilers are:
 * IBM VisualAge C++ - Nice compiler. Loads of features, good user interface. American students get it very cheaply.
 * Watcom C/C++ - Arguably better than VisualAge. Can cross-compile for multiple operating systems.
 * Borland C++ - Uses their infamous IDE interface. If you are considering this compiler, consider GNU C.
 * VisPro C/C++ - It is from Canada. Any opinion would be appreciated.

For REXX development there is: This is what people who are frustrated with their compiler look like! :-)
 * DrDialog - Cute, useable, and free
 * The commercial compilers Watcom VX-REXX, and VisPro REXX are good for graphical development of PM applications using REXX.

Software
Subscribe to the Developer's Connection CDROMs through the IBM SDP. It is your life blood. It is about US$200 for 4 sets of CD-ROMs, which are distributed quarterly. If you can't afford it, ask for the Promotional DevCon. They give you one (but ONLY one) set out of good will, for free! With the money you have now saved, buy a CD-ROM drive so you can use them :-).

Get the Hobbes OS/2 CD-ROM (Email info@cdrom.com). It is about US$30. You get the entire OS/2 hobbes.nmsu.edu site on two CD-ROMs, which comes in handy. If you develop software that they put on the CD-ROM, they will even send you one as a gift, because they are nice.

OS/2 Warp Developer's Toolkit - THE tool for OS/2 developers. It has got necessary software, documentation, and examples for Assembler, C, C++, SOM, and REXX. It's on the DevCon. Install it.

OS/2 Warp Entertainment Toolkit - This may be another package to get if you intend to write games, particularly in C++. It includes new technologies like 3D rendering, animation, and a joystick driver.

Hyperwise - Allows easy creation of OS/2 and Windows help files. It's really nice. It can even import and export in HTML format. Unfortunately, there is only a demonstration version of it on the DevCon. If anyone can suggest a nice, freely-available INF creation tool, please do so!

Object REXX - This gives REXX object-oriented abilities. It may be worth a look. It's on the DevCon.

DrDialog - My favourite REXX tool! It allows the graphical creation of simple PM applications using REXX. It's on the DevCon.

Prominare Designer - This allows excellent graphical creation of OS/2 applications. The demonstration version (PDD.ZIP) has a dialog creation tool (which is perfectly usable) and rivals that in the Warp Developer's Toolkit. See http://www.prominare.com/prominare. You may need the LOADDSKF.EXE utility to decompress the demonstration version archive.

Guidelines - Graphical PM application development tool which builds using your C++ compiler. Very nice. The base package may be free. See ftp://hobbes.nmsu.edu/os2/dev32/gui*.

Paint Shop Pro - (psp311.zip, available in Windows sites like SimTel, in the 'graphics' directory) is a good shareware graphics viewer/editor. It rivals Adobe Photoshop. You will undoubtedly use it for editing images for your next hot OS/2 game! Unfortunately, it's not native, so why not contact the creators and tell them that it would be better if it was?

POVRAY - This is useful for creating rendered graphics, like those in the film Toy Story. It is also free. The graphics in a native OS/2 game, Toyland, were created using this. If you don't want to learn its modelling language, get a shareware modeller like PovCad 3D. Unfortunately, it's a Windows application, so why not tell the author that 'native is better'?

Information references available via the Internet
This section lists some Internet (with World Wide Web sites) of interest to OS/2 users and developers.

OS/2 game development related
There are two main OS/2 repositories on the internet. They are ftp-os2.cdrom.com, and hobbes.nmsu.edu. There are mirrors around the world. OS/2 information and software may be found at these sites. Various source code samples are provided in the /dev16 and /dev32 directories.


 * IBM OS/2 Warp games home page This is the starting point for looking for OS/2 game-specific information. http://www.austin.ibm.com/os2games
 * OS/2 Game Development Council http://naftalab.bus.utexas.edu/os2games
 * The Ultimate OS/2 games page http://www.cc.gatech.edu/people/home/buie/os2games.html
 * Team OS/2 Online There are lots of excellent links to all kinds of information. Become a member here. http://www.teamos2.org
 * EDM/2 Magazine This electronic magazine is so good, it should be put on the World Heritage List. Get all the issues!

See newsgroups comp.sys.os2.programmer.*, comp.os2.os2.misc.games

For a general OS/2 programming FAQ, see http://www.connix.com/~kiernasj/os2_prog.faq.html. This may come in somewhat useful.

For a list of OS/2-related books, see ftp://hobbes.nmsu.edu/os2/info/os2books.txt.

Game development related
Here are some sites relating to game development techniques and resources.


 * Games domain A useful nice site relating to all aspects of gaming. http://www.gamesdomain.co.uk
 * POVRAY archive and a mirror ftp://ftp.povray.org (or ftp://uniwa.uwa.edu.au/pub/povray)

The rec.sys.programmer.games newsgroup. Get its FAQ as well. The author is gavin@senator.demon.co.uk.

Game developer magazine http://www.mfi.com/gdmag

The X2ftp site (x2ftp.oulu.fi), contains a lot of information on designing DOS games. Most of it is irrelevant to PM games. Try the Games Programming Encyclopaedia.

General OS/2 related
Here is a list of sites for all OS/2 users. There is a general OS/2 FAQ. Look for it on the Team OS/2 site.


 * DOS and Windows games settings list http://eyelab.msu.edu/os2games
 * Rainald in Toyland http://www.uni-koeln.de/~a0085/Toyland.html or http://www.wilmington.net/bmtmicro/catalog/toyland/Toyland.html
 * Stardock! http://oeonline.com/~stardock/index.html
 * OS/2 software solutions http://www.mfi.com/os2dev/cgi-bin/
 * OS/2 e-Zine! http://www.isisnet.com./haligonian/os2

_#OS/2 Internet Relay Channel (IRC) group.

Miscellaneous sites
This section contains some of my favourite World-Wide Web sites. Visit them!

Also try to find the Official Anti-Microsoft home page.
 * Antonino's very own home page! Rejoice in its splendour! http://www.tripod.com/~antonino/index.html
 * University of South Australia http://www.unisa.edu.au
 * Joan Grove's home page - Want to know how Microsoft treats its employees? http://www.seasun.com/redrose
 * Windows 95 hate page http://alfred.uid.no/People/wolf/grana
 * Zero Micro Software home page http://www.micros0ft.com
 * The Unofficial Brady Bunch home page http://www.teleport.com/~btucker/bradys.shtml
 * The Calvin and Hobbes archive http://www.eng.hawaii.edu/Contribs/justin/Archive/Index.html
 * Bite me! This is Illtel http://wonderland.illtel.denver.co.us
 * The official DefFX home page http://www.geko.com.au/vrx/dfx/html/def-fx.html

About the Author
I have been looking for information on how to program OS/2 applications (and games) for some time. I wrote this guide because I found that there is no similar source of information for beginners. The road to success with PM programming is long and hard, but the end result is rewarding. My best advice is to buy books which suit you.

Please send comments, suggestions, or improvements to      ****    ****       *  ****  Operate at a higher level. *   *  *    *     *  *    *    *    *  *         *       *    Mr Antonino Iannella *   *   ****    *      *       Computer Systems Engineering *   *  *    *  *     *          9308390r@lux.levels.unisa.edu.au  ****    ****  *      ******      http://www.tripod.com/~antonino/index.html

General Application Error in Module MS:WIN-95. This version will now self-destruct!

Would you fix your house if the windows need replacing? So why not fix your computer by replacing its Windows?

Pretty cool, eh?

Acknowledgements
The following wonderful people helped with the compilation of this guide.
 * Joan Grove
 * Dan Libby
 * Dan Rhoads
 * Timur Tabi
 * Rainald Menge
 * Jeff Chang
 * Bedrich Smetana
 * Nicholas Pioch
 * Larry Salomon
 * Tom Stevic
 * Toby Flugel
 * Thomas
 * Gerardo Diaz
 * Mark Rosenberg
 * University of South Australia ITU
 * JoanGrove, redrose@halcyon.com
 * Dan Libby, dandaman@aloha.com
 * Dan Rhoads, drhoads@ibm.net
 * Timur Tabi, timur@vnet.ibm.com
 * Rainald Menge, menge@rrz.uni-koeln.de
 * Jeff Chang, gozigen@aol.com
 * Bedrich Smetana, Bedrich_Smetana@idg.com
 * Nicholas Pioch, WebMuseum, pioch@netscape.com
 * Larry Salomon, os2man@panix.com
 * Tom Stevic, stevic@ibm.net
 * Toby Flugel, toby@annex.com
 * Thomas, ThomasC2@aol.com
 * Mark Rosenberg, marks@rosenberg.sdi.agate.net
 * Gerardo Diaz, gerdiaz@ibm.net
 * University of South Australia ITU

Registered trademarks
This section lists some of the trademarks which belong to their owners.
 * OS/2, Hyperwise, and VisualAge C++ are trademarks of the IBM Corporation.
 * OpenDoc is an industry standard, probably belonging to companies like Motorola, Apple, DEC, IBM, but definitely not Microsoft.
 * Windows and the Microsoft Network are trademarks of the Microsoft Corporation. 'Windoze' isn't, however.
 * Paint Shop Pro is a trademark of JASC Products.
 * Photoshop is a trademark of Adobe Systems, Inc.
 * Prominare Designer is a trademark of Prominare.
 * Netscape is a trademark of the Mozilla Corporation.
 * Galactic Civilisations is a trademark of Stardock Systems.

The pictures are copyright of Joan Grove, IBM, Mozilla, the WebMuseum, IQPac Inc, Rainald Mange, Stardock Systems, Salvador Dali, Graham Griffiths, the University of South Australia, and anyone else on the Internet whom I have not acknowledged.

Toy Story is a Walt Disney production.