Metagraphics

MetaWINDOW Developer's Guide - Chapter 8
 
Considerations For Porting MetaWINDOW
To Other Operating Environments

MetaWINDOW is written in entirely Intel x86/Pentium assembly language and is designed to be largely system independent.  Functions that do require system services are localized to the following documented routines.  These functions may need to be replaced (or simply stubbed out) when porting MetaWINDOW to other non-DOS operating environments such as real-time, embedded or stand-alone operating systems.

MetaWINDOW products provide direct support for popular DOS real-mode, 16-bit protected mode and 32-bit protected-mode environments.  A list of commercial real-time and embedded operating system vendors providing expanded support for is included in the online document:

        partners.htm  (http://www.metagraphics.com/partners.htm#RTOS)

Please contact the designated vendor representative for futher information in using MetaWINDOW with the associated commercial operating system products.

MetaWINDOW is designed to make use of limited operating system functions.  These functions are packaged into generic interfaces to simplify porting MetaWINDOW to other operating environments such as real-time, embedded or stand-alone operating systems.

8.1 Video Initialization
MetaWINDOW typically makes use of only two video BIOS interrupt services: 1) to initialize the video hardware to the specified graphics mode on program startup, and 2) to reset the graphics mode back to text mode on program termination.  Setting and resetting the graphics mode is typically performed using either video Int 10h BIOS services, or a Vesa driver Int call.  If video BIOS or Vesa driver services are not available, you will need to directly program the MetaWINDOW SetDisplay() function to directly initialize the video hardware.  Video initialization sequences for standard CGA, EGA, VGA and many SuperVGA modes are in outlined in the online Metagraphics document file:

      xegia.zip   (http://www.metagraphics.com/metawindow/examples/xegia.zip)

8.2 Vesa Video Bank Switching
Most SuperVGA modes require a "bank manager" to access video memory during drawing operations.  (A bank manager handles mapping a block of video memory into processor memory typically into a 64K address space starting at A000h.)

For many SuperVGA modes, MetaWINDOW provides bank managers which talk directly to the hardware for controlling video bank addressing.  For other graphic modes not directly supported, MetaWINDOW uses Vesa BIOS interrupt services to set video bank addresses.  An expanded list of MetaWINDOW supported chipsets, graphic cards and video modes is provided in the online document:

 
     adapters.htm  (http://www.metagraphics.com/metawindow/adapters.htm)

This document identifies which modes are supported directly, and which modes are supported with VESA drivers and bank managers.

For SuperVGA modes where MetaWINDOW does not provide direct bank manager support and for operating systems where VESA Int 10h services are not available, a custom video bank manager may need to be implemented.  Typically this is about one page of assembly language code.  The MetaWINDOW Source Code provides examples for bank managers for its supported devices.  Support for other graphic chipset is typically adapted from this code.  The MetaWINDOW Developer's Guide manual (included with the MetaWINDOW Source Code), Chapter 4 "Implementing Custom Bank Managers", provides additional information for writing custom bank managers.

If you are working with a 32-bit protected mode environment and a custom video interface design that fully maps video memory into linear processor address space, you can bypass the need for a bank manager, and simply call the MetaWINDOW InitBitmap() and InitRowTable() functions to define the address space for your video hardware memory.  See the MetaWINDOW System and Library Reference Manual for further information on the InitBitmap() and InitRowTable() functions.

Other then for video mode initialization and optional bank switching, all other MetaWINDOW drawing operations are performed directly to the video hardware without any other video interrupt services (eg. MetaWINDOW does not use vertical retrace interrupts).

8.3 Memory Allocation Functions
Certain MetaWINDOW functions make use of common dynamic memory allocation functions to conserve system resources.  These functions include:

  • Dynamically loaded MetaWINDOW device drivers.
  • Dynamically loaded MetaWINDOW font files.
  • Dynamically allocated memory buffers.
Dynamically Loaded Device Drivers
For DOS real-mode, 16-bit protected mode and 32-bit protected mode MetaWINDOW graphic video drivers are typically loaded dynamically based on the video mode set by the applicaion at runtime. You can avoid the need for dynamically loading device drivers, by setting switches within the MetaWINDOW Source Code and rebuilding the MetaWINDOW libraries. With the video drivers built direcly into a library your final executable will contain all needed drivers.
Dynamically Loaded Font Files
MetaWINDOW fonts are also typically loaded from files during execution. The online file fontinc.zip provides a utility for converting MetaWINDOW font files into .H header files that can be compiled and linked directly into your program. With the font linked directly into your program, you simply call the MetaWINDOW SetFont() function with a pointer to the address of the buffer containing the font. 
   fontinc.zip   (http://www.metagraphics.com/metawindow/fonts/fontinc.zip)
Dynamically Allocated Memory Buffers
Certain MetaWINDOW functions, such as for dynamically creating graphic "regions" and offscreen bitmaps, make use of the MetaWINDOW GrafAlloc() and GrafFree() memory allocation functions. In standard MetaWINDOW, GrafAlloc() and GrafFree() simply pass the calls along to the standard compiler allocation routines, such as malloc() and free() for C. If your system does not support malloc() and free(), you will need to provide replacement GrafAlloc() and GrafFree() routines to work with your operating environment. In certain cases a fixed buffer area managed by replacement GrafAlloc() and GrafFree() functions will suffice most uses.

8.4 MwMapPhysAdr() / mwFreeLogAdr()

MwMapPhysAdr()
For protected mode environments, MwMapPhysAdr() is used to map physical memory (frame buffer) into a logical address. While called for all environments, usually only needs to return mapped address for protected mode environments. For 32-bit protected mode, the address must be mapped into the program's common data segment (flat model only, dx should be ignored).

     On entry:
     dx:(e)ax  = physical address
     (e)bx     = size to map in 64K increments

     Returns:    dx:(e)ax = mapped logical address, (e)bx = 0 if ok

mwFreeLogAdr()
mwFreeLogAdr() is used to free any selector(s) that were previously allocated via mwMapPhysAdr().

     On entry:
     dx        = selector to deallocate
     bx        = number of consecutive selectors to deallocate

     Returns:    (e)ax = 0 if ok

8.5 mwSegInfo()
mwSegInfo() is called to return segment selector information. It returns:

For Real Mode and 16-bit Protected Mode:

  1. a selector based at 400h for accessing the BIOS low memory area.
  2. a selector increment value for accessing consecutive 64k areas.

for 32-bit Protected Mode:

  1. a selector based at 0 for accessing the BIOS low memory area,
  2. the selector for the system data segment.

BIOS low memory variables used by MetaWINDOW include:

  • Most MetaWINDOW device managers to alter the equipment word when switching video modes (offset 410h for 386, 10h for non 386).
  • The MetaWINDOW event system to obtain a time stamp (offset 46Ch for 386, 6Ch for non 386).
  • The MetaWINDOW event system's default keyboard handler to obtain keys from the BIOS keyboard buffer (offsets 417h, 418h,41Ah, 41Ch, 41Eh, 43Eh for 386, 17h, 18h, 1Ah, 1Ch, 1Eh, 3Eh for non 386)

If none of these services are used, a BIOS selector need not be returned.

mwSegInfo() returns:
     ax   = bios segment
     bx   = segment incremnet value (16-bit protected mode)
     bx   = data segment (32-bit protected mode)

8.6 mwGetVect() / mwSetVect() / mwRestoreVect()

mwGetVect()
mwGetVect() is used to retrieve current interrupt vector settings.

On Entry:
   al  = interrupt number to return

On Return:
   es:(e)bx = vector value

For systems that maintain two vectors (real and protected), the second real mode pointer is returned in cx:(e)ax.

Interrupt vector management is used for:

  • The MetaWINDOW event system default keyboard handler, interrupt number 09.
  • MetaWINDOW input device drivers for serial mouse interrupts numbers 0Ch and 0Dh.

If none of these services are used, mwGetVect() will not be called.

mwSetVect()
mwSetVect() is used to set (and return) interrupt vectors. For protected mode, this sets the interrupt vector to always gain control in protected mode.

On Entry:
   al       = interrupt number to modify
   ds:(e)dx = vector value to set

On Return:
   es:(e)bx = vector

For systems that maintain two vectors (real and protected), the second real mode pointer is returned in cx:(e)ax.

mwRestoreVect()
mwRestoreVect() is used to restore interrupt vectors.  Note that mwSetVect() (Section 8.5) is used to set an interrupt vector and gain control in protected mode.  mwRestoreVect() is used to restore an interrupt vector and release control. 

On Entry:
   al        = interrupt number to modify
   ds:(e)dx  = vector to set

For systems that maintain two vectors (real and protected), the second real mode pointer is passed in cx:(e)bx.

8.7 mwGetEnv()
mwGetEnv() returns a string buffer from an environment variable name to its associated string value.  The environment string defines a path to MetaWINDOW system resources for fonts and loadable display drivers.  (The environment string is NULL terminated.)

On Entry:
   ds:(e)si = pointer to buffer to load with environment string

On Return:
   (e)ax    = zero if environment string found, non-zero if environment variable is not set.

8.8 mwLockMem() / mwUnLockMem()

mwLockMem()
For 32-bit protected-mode, mwLockMem() is called to lock memory areas for use with virtual demand paged memory.

On Entry:
   es:ecx = virtual address to lock
   edx    = length in bytes

mwUnlockMem()
mwUnlockMem() is called to unlock memory areas previous locked by mwLockMem().

On Entry:
   es:ecx = virtual address to unlock
   edx    = length in bytes

8.9 mwCreateAlias() / mwFreeAlias()

mwCreateAlias()
For 16-bit protected mode, mwCreateAlias() is used to create an alias of the DS descriptor and set it executable.

On Entry:
   ds = selector to alias.

On Return:
   ax = aliased executable descriptor.

mwFreeAlias()
mwFreeAlias() is used to free the descriptor previously created by mwCreateAlias().

On Entry:
   ax = descriptor to free.

On Return:
   n/a

8.10 FileQuery() / FileLoad()

FileQuery()
FileQuery() is standard MetaWINDOW function that is also used internally to query the presence of font and driver files.  This function is documented int the MetaWINDOW System and Library Reference Manual.

FileLoad()
FileLoad() is standard MetaWINDOW function that is also used internally to load fonts and driver files. This function is documented int the MetaWINDOW System and Library Reference Manual.

8.11 Other Required Services
Video BIOS services (interrupt 10h) are used by most of the device managers in order to set the video adaptor into graphics mode and back to text mode. If Int 10h services are not available, a custom device manager should be supplied (see Chapter 5, Implementing Custom Device Managers).

The Microsoft Mouse Driver device driver makes use of interrrupt 33h. If Int 33h services are not available, this driver cannot be used. The serial mouse drivers may be used, or custom input device managers could be supplied (see Chapter 7, Implementing Custom Input Devices).

DOS interrupt 21h services are used by HardCopy(). If Int 21h services are not available, HardCopy() cannot be used.

8.12 Related Information
A description for MetaWINDOW handling of real-time OS re-enterant operations is provided in the MetaWINDOW Developer's Guide reference manual, Chapter 9 "MetaWINDOW Real-Time Re-Entrancy Considerations", also available in the online document:

       mwdvgd09.htm  (http://www.metagraphics.com/metawindow/mwdvgd09.htm)

The MetaWINDOW Developer's Guide reference manual provides expanded information on porting MetaWINDOW to custom operating environments and interfacing custom graphics hardware. This manual is included with the pruchase the MetaWINDOW Source Code product, or can be purchased separately from the Metagraphics sales office for US$39 (plus applicable tax and shipping).

Home | Products | Order | Register | Support | Company | Contact | Feedback

Copyright © 1999- - Metagraphics Software Corporation.