SciTech Multi-platform Graphics Library Version 5.0 BETA 4 Getting Started Guide What is this document for? -------------------------- This text document is intended to help developers get up and running with the MGL 5.0 beta products, and to show the steps necessary to compile and link the libraries and sample programs from for your OS and compiler configuration. Installing the files -------------------- To install the files you will need a copy of the source archive, the base utilities archive for your OS and the font and bitmap resource archive. Uncompress all files in the archive into the directoy on your system where you want the files to live (normally c:\scitech or ~/scitech). The names of the archives you will need are the following for the BETA 4 release: mgl50b4-src.zip - Source archive in ZIP format mgl50b4-font.zip - Base font and bitmap archive in ZIP format mgl50b4-ttf1.zip - Free TrueType Font archive 1 in ZIP format mgl50b4-ttf2.zip - Free TrueType Font archive 2 in ZIP format mgl50b4-dos.zip - DOS hosted base utilities mgl50b4-win32.zip - Win32 hosted base utilities mgl50b4-os2.zip - OS/2 hosted base utilities mgl50b4-src.tar.gz - Source archive in gzip'ed tar format mgl50b4-font.tar.gz - Base font and bitmap archive in gzip'ed tar format mgl50b4-ttf1.tar.gz - Free TrueType Font archive 1 in gzip'ed tar format mgl50b4-ttf2.tar.gz - Free TrueType Font archive 2 in gzip'ed tar format mgl50b4-linux.tar.gz - Linux hosted base utilities mgl50b4-qnx.tar.gz - QNX hosted base utilities SciTech MGL 5.0 is designed to work with DJGPP 2.02 and GCC 2.8.1. If you don't have all the correct files or you are having problems, we recommend that you download and install DJGPP 2.02 using the Windows based install archive we have created. The name of the file is: djgpp202.exe - Windows hosted DJGPP 2.02 32-bit DOS compiler Makefile utilities configuration -------------------------------- Once you have installed the files, you need to configure the makefile utilities and tools to allow you to compile the libraries. If you are compiling under DOS a Windows DOS box, you will need to set the environment for your DOS box to at least 3072 bytes as we use a lot of environment variables. The first step to set up the compile environment is always to edit the set-vars script files specific to your platform (copy it to a different named file if you are working with source code checked out of Perforce as this file will be read only). This file contains two very important variables that you need to ensure are set correctly. These are: SCITECH - Points to the location where you installed the files SCITECH_LIB - Should be the same as the above The SCITECH_LIB variable is where files get copied to when you do a 'dmake install', and is usually the same as the SCITECH variable. However it can be different if you wish the libraries to be installed to a different path such as on a shared file server for release builds. You should also ensure that you set the MGL_ROOT environment variable, which points to the location of where you installed the MGL files. This is a runtime varaiable that is used by SciTech MGL to find all font, bitmap, icon and cursor resource files. To help you get started configuring your system we have created a bunch of startup script files for each of the different operating systems. These files are called in the SCITECH\start.* files with an extension specific to each OS. These files contain the necessary sequence of steps to call the appropriate batch files to set up the compile environment. To use this copy this file to a new filename and edit to call your version of the set-vars script file as necessary. DOS/Windows hosted tools (start.bat/startw98.pif) ------------------------------------------------- The first thing you need to do is edit the bin\set-vars.bat batch file to reference the location where you have installed the files, and the locations where all your compilers are installed. See the comments in set-vars.bat for more information. Once you have the startup file configured, you then need to run the following each time you start a command shell to enable the SciTech makefile utilities (a good idea to put into your startup batch files): call c:\scitech\bin\set-vars.bat call c:\scitech\bin\wc11-d32.bat The second batch file sets up the compiler configuration for your default compiler. The line above sets up for Watcom C++ 11.0 32-bit DOS compilation. Substitute this for any of the batch files in the bin directory for the compiler you are using. Note that the start.w98 program information file (PIF file) should work on all Windows 9x operating systems without requiring changes. However if it doesn't work properly for you, you may wish to edit the properties from the explorer window as necessary. This PIF file will *not* work on Windows NT/2000 systems! Win32 hosted tools (start.bat/start.nt) --------------------------------------- The Win32 hosted tools are identical to the 32-bit DOS hosted tools, however they are native Win32 tools and hence can support long filenames properly under Windows 9x and Windows NT/2000. The Win32 tools usually runs slower than the DOS hosted tools on Windows 9x, but significantly faster on Windows NT/2000. Unless you need long filenames, you may want to stick with the DOS hosted tools for Windows 9x environments. Note that you will need to modify the start.nt shortcut as necessary to use the correct paths for where your Windows NT/2000 installation is located as well as where you have installed the SciTech source tree. OS/2 hosted tools ------------------ The first thing you need to do is edit the bin-os2\set-vars.cmd script file to reference the location where you have installed the files, and the locations where all your compilers are installed. See the comments in set-vars.cmd for more information. Once you have the startup file configured, you then need to run the following each time you start a command shell to enable the SciTech makefile utilities (a good idea to put into your startup batch files): call c:\scitech\bin-os2\set-vars.cmd call c:\scitech\bin-os2\wc11-o32.cmd The second batch file sets up the compiler configuration for your default compiler. The line above sets up for Watcom C++ 11.0 32-bit OS/2 compilation. Substitute this for any of the batch files in the bin directory for the compiler you are using. NOTE: In order for any of the OS/2 sample programs to run, you must have the SDDHELP.SYS device driver loaded. Hence ensure you add this device driver to your CONFIG.SYS file and then reboot in order to start using the MGL programs. Linux hosted tools ------------------ The first thing you need to do is edit the bin\set-vars-linux.sh script file to reference the location where you have installed the files, and the locations where all your compilers are installed. See the comments in set-vars-linux.sh for more information. Note that the Linux version of the set-vars uses the MGL_ROOT environment variable to set the SCITECH and SCITECH_LIB variables. For the most part you can probably just set the MGL_ROOT variable and then execute the set-vars-linux.sh shell script from your default shell profile (ie: .bash_profile etc). Once you have the startup file configured, you then need to run the following each time you start a command shell to enable the SciTech makefile utilities (a good idea to put into your startup scripts): . ~/scitech/bin/set-vars-linux.sh . ~/scitech/bin/gcc-linux.sh The second script file sets up the compiler configuration for your default compiler. The line above sets up for GNU C/C++ for Linux (eventually other compilers will come to Linux, such a MetroWerks). NOTE: In the above script code, you need to *source* the script files to ensure the environment variables are exported to your regular shell. Hence make sure the leading '.' is included! NOTE: If you are developing on an older libc5 based system (as opposed to the newer glibc as used by Red Hat 5.x etc), you will also need to set the LIBC=1 environment variable. This will tell our script files that you running on an older system and need to use the libc5 compiled binaries, and to put your compiled libraries into the libc5 directories. NOTE: In order to build the MGL libraries, you should have the latest Linux 2.x kernel sources installed. The PM library depends upon a number of header files from the 2.x kernels (joystick.h and mtrr.h) in order to build. You can build for older kernels if you wish, but you will need to modify the PM library makefiles to do this. NOTE: In order to use the mouse and joystick under Linux, you will need to set up the MGL mouse and joystick environment variables. See the section below on Linux Rutime Setup for more information. QNX hosted tools ---------------- The first thing you need to do is edit the bin\set-vars-qnx.sh script file to reference the location where you have installed the files, and the locations where all your compilers are installed. See the comments in set-vars-qnx.sh for more information. Note that the QNX version of the set-vars uses the MGL_ROOT environment variable to set the SCITECH and SCITECH_LIB variables. For the most part you can probably just set the MGL_ROOT variable and then execute the set-vars-qnx.sh shell script from your default shell profile (ie: .bash_profile etc). Once you have the startup file configured, you then need to run the following each time you start a command shell to enable the SciTech makefile utilities (a good idea to put into your startup scripts): . ~/scitech/bin/set-vars-qnx.sh . ~/scitech/bin/qnx4.sh The second script file sets up the compiler configuration for your default compiler. The line above sets up for Watcom C++ 10.6 for QNX. NOTE: In the above script code, you need the *source* the script files to ensure the environment variables are exported to your regular shell. Hence make sure the leading '.' is included! NOTE: For QNX development you will need to set the USE_BIOS=1 environment variable to enable support for calling the BIOS. You will also need to copy the vbios.lib files from the drivers/qnx directory into your runtime library directories. The final release will allow you to build MGL programs without requiring the BIOS support, but for the moment the BIOS support is required to run under QNX, even though it is not used if you are running on SciTech Nucleus drivers. NOTE: SciTech MGL for QNX uses an updated version of the QNX Input driver and a special MglMouse driver for mouse support. You will need to copy these two programs from the scitech/drivers/qnx directory into your /bin directory. After you have done this, you will also need to ensure you have the line 'mousetrap start' in your local /etc/config/sysinit. startup script, and to reboot your system to run on the new drivers. Compiling the libraries ----------------------- Once you have all the startup scripts configured and executed, you are ready to begin compiling. Building all the MGL libraries in one fell swoop is very easy. Simple change into the src directory below where you have installed all the files and issue a dmake build. Ie: cd scitech/src dmake build Using 'dmake build' will force build all the libraries, and will build all the libraries with your selected compiler and using the currently configured options. If any errors are encountered during the build, it will stop and you can fix the errors and then restart the build from the offending library with a simple 'dmake' (ie: the default target builds for the selected compiler). You can also build each library from each directory if you wish as well. Compiling release and debug builds ---------------------------------- We have also created script files to build all libraries for your selected compiler in both 'Debug' and 'Release' modes. To build the debug libraries, go into the src directory and issue run the mkdebug script files. Ie: cd scitech/src mkdebug To build the release libraries, go into the src directory and issue run the mkrelease script files. Ie: cd scitech/src mkrelease NOTE: For DOS environments without long filenames, the command for release builds is 'mkreleas' without the traling 'e', because 'mkrelease' is longer than 8 characters. Both mkreleas.bat and mkrelease.bat files are included. All debug libraries end up under the lib/debug directory tree, and all release libraries end up under the lib/release directory tree. To link your own programs with the debug libraries, you set the environment variable CHECKED=1 (or set it on the dmake command line). This will tell the dmake makefile scripts to build in CHECKED mode (add extra runtime checks) as to get the libraries from the lib/debug directories. Otherwise the libraries are pulled from the lib/release directory. Compiling the sample programs ----------------------------- Once you have all the libraries built, you can try to compile some of the sample programs. To build the example programs, go into the scitech/examples/mgl/samples directory and run dmake to build all the example programs. Runtime stack size issues ------------------------- The MGL and related libraries use quite a large amount of local stack space at runtime, especially when using the 3D libraries. For this reason it is important that you compile and link your applications to use a large amount of local stack space on operating systems that do not support dynamically growable stacks. Hence for 32-bit DOS, OS/2 and Windows you should link your apps with at least a 100K stack. We recommend and use a 200K stack in all our sample programs. For operating systems such as Linux and Unix derivatives this should not be an issue. SciTech Nucleus Runtime Setup ----------------------------- SciTech MGL 5.0 relies exclusively on the SciTech Nucleus, Graphics Architecture device drivers for all display output. The SciTech Nucleus, Graphics Architecture device drivers are not free, but licensed from SciTech Software for use with the MGL. However we do include a freely re-distributable, unaccelerated Nucleus device driver that uses the VESA VBE BIOS as part of the MGL (for more information see below). We also plan to release a freely re-distributable DirectX based Nucleus device driver for use with the MGL on Win32 platforms also. For licensing information about SciTech Nucleus device drivers, please email us at info@scitechsoft.com. In order for your programs to be able to properly utilise the SciTech Nucleus device drivers, they must be dynamically loaded and initialised and a driver specific to the installed hardware device loaded into memory. The code necessary to load the Binary Portable DLL file (graphics.bpd), initialise it and provide access to the internal functions is included as part of the SciTech MGL graphics library. The SciTech Nucleus, Graphics Architecture device drivers are located in the following standard locations on the end users system when installed as part of the retail SciTech Display Doctor package: Operating System Default Directory Location ---------------------------------------------- MSDOS c:\windows\system\nucleus Windows 95/98 c:\windows\system\nucleus Windows NT c:\winnt\system32\nucleus OS/2 c:\os2\drivers\nucleus Linux /usr/lib/nucleus QNX 4.x /qnx4/nucleus/bin QNX Neutrino /nto/nucleus//bin Note that the locations for the Windows and OS/2 operating systems are in the standard device driver directories, and may not necessarily be located in the c:\windows or c:\os2 directories. If the driver cannot be found in the global device driver directory, the loader library will also look in the 'drivers' directory relative to the current directory. Hence to distribute the licensed SciTech Nucleus device drivers along with your application, the most common approach is to put the SciTech Nucleus device drivers and related configuration files into a drivers directory below the application directory. Ie: the directory layout for your application might be as follows: c:\myapp\myapp.exe c:\myapp\drivers\graphics.bpd c:\myapp\drivers\config\monitor.dbx Note however that the user (or developer) may also set the NUCLEUS_PATH environment variable on the runtime system and the loader library will check in this directory for the driver file(s). For instance when developing SciTech MGL applications, it usually makes sense to set the NUCLEUS_PATH environment variable to point to your \scitech\drivers directory over a network drive connection from your target system to your development system. Using the free SciTech Nucleus VBE/Core driver ---------------------------------------------- Note that the SciTech MGL comes with a free version of the SciTech Nucleus device drivers that runs on top of the VESA VBE/Core BIOS (and eventually DirectX for Win32). This device driver should run on just about any system, but runs best if the underlying OS provides access to real mode BIOS functions. If those functions are not available it will utilise a BIOS emulator to access the BIOS functions, which may have problems with hardware we have not specifically tested. The BIOS emulator should work with any embedded OS or regular OS, provided the application is not running under a GUI environment (ie: a fullscreen console is required). The SciTech Nucleus VBE driver is called 'graphics.vbe' and should be copied over the top of the drivers\graphics.bpd file in your Nucleus device driver directory. If you are running on Unix systems, you may want to make a symbolic link between the two instead of manually copying the file. CauseWay DOS Extender and SciTech MGL ------------------------------------- SciTech MGL 5.0 is designed to work Watcom C++ and both the DOS4G/W and CauseWay DOS extenders (and compatibles). However the latest versions of MGL require an updated version of CauseWay to allow support for Intel MTRR programming, that is not available for download from the official CauseWay web site. We have all the binaries and source files for the CauseWay DOS Extender (now public domain) available for download from our ftp site. You can get them from: ftp://ftp.scitechsoft.com/devel/causeway/cw352.zip ftp://ftp.scitechsoft.com/devel/causeway/cw352bin.zip The cw394bin.zip is all you need if you just want the binaries to compile and link programs. The cw349.zip contains all the binaries and sources for CauseWay. In order to compile and link your programs to use CauseWay, either set the USE_CAUSEWAY=1 environment variable, or pass this variable on the command line to the dmake program. Linux Runtime Setup ------------------- In order for the MGL event libraries to support the mouse in fullscreen console modes, we need to directly interface to the installed mouse driver. By default SciTech MGL will run without any mouse support if the mouse environment variables have not been set up. The MGL_MOUSEDRV environment varaiable should be set to one of the following values, to inform SciTech MGL what type of mouse you have: MGL_MOUSEDRV = GPM - Use the currently installed GPM driver Microsoft - Microsoft and compatible serial mouse PS2 - Microsoft and compatible PS/2 mouse MouseSystems - Mouse Systems mouse MMSeries - MMSeries mouse Logitech - Logitech mouse BusMouse - Microsoft bus mouse MouseMan - MouseMan mouse IntelliMouse - Microsoft Intellimouse IntelliMousePS2 - Microsoft PS/2 Intellimouse If you already have the standard Linux GPM driver installed, you can set it to use this driver by default. NOTE: If any developers are familiar with mouse programming, we need someone to modify the PM event library to auto-detect the installed mouse type. This will then eliminate the need for users to configure the mouse environment variables for MGL applications. ---- END OF README.TXT ----