Previous

Next

Using the MetaWINDOW Graphics Library

With a few run-time restrictions, the graphics library MetaWINDOW by MetaGraphics - which was originally designed for DOS and DOS extenders - can be used with RTTarget-32. However, to use MetaWINDOW, it is important to understand how the support for it has been implemented. For professional GUIs, On Time RTOS-32 component RTPEG-32 is recommended instead of MetaWINDOW.

MetaWINDOW performs BIOS calls to communicate with the graphics adapter, in particular to change the graphics mode. However, RTTarget-32 is a pure protected mode environment which does not support such BIOS calls. The PC BIOS consists of 8086 real mode code which cannot be executed in protected mode.

To overcome this problem, RTTarget-32 can set a desired graphics mode during the boot process before switching to protected mode. This is achieved with the GMode directive (see section RTLoc: Locating a Program, GMode Command). At run-time, RTTarget-32's function RTGetGMode can be used to enquire which mode has been set.

This mechanism is used to place the display hardware in graphics mode. To prevent the MetaWINDOW library from performing int 10h calls, a dummy int 10h handler is installed which will trap all such calls. The handler simulates success, but actually does nothing except to pass some diagnostics information to the host debugger (if desired).

Prerequisites

To successfully run MetaWINDOW programs under RTTarget-32, the following conditions must be satisfied:

• The target computer must have a BIOS and a graphics display adapter.
• The first 4k of physical address space must not be used, because MetaWINDOW needs to access the BIOS data area located here. Reserving this memory area is best achieved with the following directive:

  Region  BIOSMem  0  4k  RAM  NoAccess
  

• For modes not using a linear frame buffer, the graphics video memory required for the mode must be declared.

  Example:

  Region  ColorGraphic  A0000h  64k  Device  SysRead
  

  The access right assigned in the Region command should be SysRead or higher. If the video RAM is actually used at run-time, function RTMetaWInit will assign ReadWrite access rights to this region.
• The RTTarget-32 configuration file used to build the program containing the boot code (either the Debug Monitor or the graphics application itself) must contain directive:

  VideoRAM = None
  

  to suppress text mode style screen I/O. All text mode screen output will be sent to the host debugger (if present). (Note: you can re-enable text mode I/O at run-time by supplying your own OutCharHandler, see the section Function RTDisplayChar in the RTTarget-32 Reference Manual).

• The same configuration file must contain a GMode directive with at least one BIOS graphics mode to be set. Example for VGA 640x480, 16 colors:

  GMode  12h
  

• All required MetaWINDOW driver DLLs must be included in the program image with the DLL command.

  Example:

  DLL  \MetaWindow\metwnd05.dll
  

  The driver DLLs can also be loaded as DLMs as done by the example programs.

• All required font files must be mapped with Locate File commands.

  Example:

  Locate  File  \MetaWindow\fonts\system00.fnt  HighMem
  

• The program's source code should #include header file RTMETAW.H supplied with RTTarget-32 and function RTMetaWInit must be called before any MetaWINDOW function is called (see below).
• The program must be linked with the RTTarget-32 library Rtt32.lib, Rtmetaw.lib and a suitable MetaWINDOW library (e.g., one for DPMI-32).
• Selector 7Bh (or 78h at CPL 0) is reserved for MetaWINDOW and must not be used by the application.
• If the graphics program also uses RTKernel-32, you must use the CPU386 driver and not CPU386F which is the default. This is very important! MetaWINDOW frequently changes segment registers. If CPU386F is used, random and evasive to debug program crashes will occur.

Initialization

Function RTMetaWInit must be called to initialize MetaWINDOW.

Example:

int main(void) 
{ 
   int   i; 
   printf("Current BIOS video mode: %04X\n", RTGetGMode()); 
   i = RTMetaWInit(RT_METAW_INIT_GRAPHICS); 
   RTIdleHandler = RTGetMetaWEvents;  // update event queue 
   if (i != 0) 
   { 
      printf( "MetaWINDOW InitGraphics error - %d\n",i ); 
      exit(1); 
   } 
   SetDisplay( GrafPg0 );     /* switch display to graphics mode   */ 
   ...

Limitations

Several features of MetaWINDOW are not available under RTTarget-32, mainly because no BIOS calls are possible at run-time. In particular, these are the limitations:

• Mode switches are not possible at run time. The hardware is placed in a particular mode at boot time which cannot be changed later.
• Only display page 0 (GrafPg0) can be used and switching pages is not supported.
• MetaWINDOW functions QueryGraphics and FindBestGraphics are not supported.
• MetaWINDOW functions QueryMouse and FindBestMouse are not supported.
• The MetaWINDOW mouse drivers MsDriver and Joystick are not supported. However, the RTTarget-32 mouse driver can be used.

Advanced Topics

Multithread Applications

Using the 387 Emulator