MGL_init

Initializes MGL graphics library.

Declaration

int MGLAPI MGL_init(
const char *mglpath,
const char *server)

Prototype In

mgraph.h

Parameters

mglpath | Path to standard MGL resource files
server | Name of server to connect to (NULL for local system)

Return Value

Number of display devices attached, or 0 on error.

Description

This function initializes MGL for use, and should always be the first function called in MGL applications. The mglpath parameter is used by the MGL to locate all MGL resource files in their standard locations. The value passed in here should point to the base directory where all the resources are located. This may be the current directory if all resources are relative to the current directory of the application (i.e. a value of “.” passed in the mglpath parameter).

After you have called MGL_init, the MGL will automatically detect the installed graphics hardware when any of MGL_availablePages, MGL_modeResolution, MGL_modeFlags or MGL_findMode are called. The priority ordering of which driver will be used depends on the capabilities of the underlying display hardware, and the drivers will be chosen in the following order (first one in table is selected in preference to ones below it):

Driver | Highest performance driver selected
Snap | SciTech SNAP Graphics driver
DirectDraw | SciTech SNAP Graphics DirectDraw driver
VBE2 | SciTech SNAP Graphics VBE/Core 2.0 driver
VBE1 | SciTech SNAP Graphics VBE/Core 1.2 driver
StandardVGA | SciTech SNAP Graphics VGA driver

For instance if you had DirectDraw installed on your system and MGL found a SciTech SNAP Graphics driver, those modes supported by the SciTech SNAP Graphics drivers will use the SciTech SNAP Graphics driver in preference to the DirectDraw driver. If however the DirectDraw driver has additional modes not supported by the SciTech SNAP Graphics driver, the DirectDraw drivers would be used for those modes. If however the user has DirectDraw installed and only has a VBE 2.0 driver available, the DirectDraw drivers will be used for all modes whenever possible.

To change this default behavior you can selectively disable those drivers that you do not wish to be used immediately after calling MGL_init. A typical sequence of code to register drivers and allows the program to disable SciTech SNAP Graphics might be as follows:

int mode;
MGLDC *dc;

if (MGL_init(".",NULL) == 0)
MGL_fatalError(MGL_errorMsg(MGL_result()));
MGL_disableDriver(MGL_SNAPNAME);
if ((mode = MGL_findMode(640,480,8)) == -1)
MGL_fatalError(MGL_errorMsg(MGL_result()));
dc = MGL_createDisplayDC(mode,1,MGL_DEFAULT_REFRESH);
...

When the MGL is searching for resource files (bitmaps, icons, fonts and cursors), it will first attempt to find the files just by using the filename itself. Hence if you wish to look for a specific bitmap or font file, you should pass the full pathname to the file that you want. If the filename is a simple relative filename (i.e. “myfont.fnt”), MGL will then search in the standard directories relative to the path specified in mglpath. The standard locations that MGL will look for the resource files are as follows:

Resource | Base pathname
Bitmaps | mglpath/bitmaps
Fonts | mglpath/fonts
Icons | mglpath/icons
Cursors | mglpath/cursors

As a final resort the MGL will also look for the files relative to the MGL_ROOT environment variable. The MGL_ROOT variable can be set to point to a standard base directory where all MGL resources will be stored on the end user's machine. For MGL developer machines, MGL_ROOT is usually set to point to the directory where the SciTech MGL files were installed (ie: c:\scitech by default for DOS, Windows and OS/2 installations, $HOME/scitech for Unix installations).

The server parameter is used to connect to a remote server to display the output of the of the MGL program on a remote machine. For remote connections, the server name should either be the DNS name or TCP/IP address of the machine to connect to. For local operation on the client machine, this parameter should simply be set to NULL.

Once you have initialised the MGL, you then need to find an appropriate display mode to use with MGL_findDisplayMode, and then create a device context for all output, using MGL_createDisplayDC (for fullscreen display device contexts). To support multiple display controllers, please see the documenation for MGL_selectDisplayDevice to initialise all installed display devices.

If anything goes wrong during the initialization process, MGL will return a result code via the MGL_result routine. You can then use this result code to determine the cause of the problem, and use the MGL_errorMsg routine to display an appropriate error message for the user.

Note: To get up and running quickly with your first MGL program, check out the MGL_quickInit() function which allows you to start the MGL with a single line of code! Or alternatively check our the Game Framework API if you are developing game type applications.

Note: Remote client/server operation is not supported at this time. This is something scheduled for a future release of the MGL.

See Also

MGL_quickInit, MGL_selectDisplayDevice, MGL_enableAllDrivers, MGL_disableDriver, MGL_availablePages, MGL_modeResolution, MGL_findMode, MGL_addCustomMode, MGL_createDisplayDC, MGL_exit, MGL_result

Copyright © 2002 SciTech Software, Inc. Visit our web site at http://www.scitechsoft.com