-------------------------------------------------------------------
                  MIL AND ACTIVEMIL DRIVER for METEOR
-------------------------------------------------------------------

===================================================================
GENERAL INFORMATION
===================================================================

WHICH WINDOWS DISPLAY RESOLUTION TO USE:
-------------------------------------------------------------------
- The METEOR can grab in three different data formats: 8 bits 
  monochrome, 15 bits color, and 32 bits color.
  
  Under Windows, as for DOS, it is always better to select a
  display resolution that matches the buffer being displayed. 
  For example, when grabbing 32-bit color, the 256 colors display 
  resolution will give bad results in both speed of the continuous 
  grab operation and also in the number of different colors 
  displayed. Whereas in true color (32-bit) display resolution, 
  the continuous grab operation will appear live and will show 
  all the colors of the grab operation.

  
      GRAB DATA FORMAT              ->  BEST DISPLAY RESOLUTION
      ----------------------------      -----------------------
      Monochrome 8  bits per pixel      256   colors  ( 8-bit)
      Color      15 bits per pixel      32768 colors  (15-bit)
      Color      32 bits per pixel      True  colors  (32-bit)
      
  Note: MIL and ActiveMIL allocate a 3-band buffer as a 32-bit per 
        pixel buffer. To allocate it as a 15-bit per pixel buffer:
           MIL: the following flags have to be added to the attributes of 
                the buffer at buffer allocation time.
                MbufAlloc...() : M_RGB15+M_PACKED.

           ActiveMIL : set the buffer's format to Buffer.Format = mRGB15Packed	
        
        
AUTOMATIC DETECTION OF OVERLAP:
-------------------------------------------------------------------
- During a continuous grab operation (MIL: MdigGrabContinuous,
  ActiveMIL: Digitizer.GrabContinuous), the METEOR grabs directly into the Vga
  memory when the selected display resolution matches the one of the buffer
  being displayed (see note above). However when the grab display window is
  being overlapped by another window (situation that can only happen
  under Windows), then the METEOR switches to a different mode  of continuous
  grab operation called 'Pseudo Live Grab'. In this  mode each frame is grabbed
  into memory then sent back to the display. Since that this whole transfer is
  handled by Direct Draw, then you might not even notice that a different
  mechanism is used to perform the task of continuous grab on the display.That
  is you could still obtain a full grab rate. However in that mode, CPU time
  is necessary to perform the display update time. Which could slow  any
  concurrent processing task. When the grab display window is no more
  overlapped by another window then the METEOR switches back to grabbing
  directly into the Vga.
  
  Note: If Direct Draw has been disabled then the 'Pseudo Live Grab'
        operation will be slower and there is no automatic detection of 
        overlap.

        MIL       : MsysAlloc() : M_NO_DDRAW
        ActiveMIL : System.InitializationFlag = ... | mNoDirectDraw
        
        Since that there is no automatic detection of overlap, it 
        means that the METEOR switches to 'Pseudo Live Grab' when the grab
        display window looses the focus. 


GRABBING PROBLEMS ON SOME PCs:
-------------------------------------------------------------------

- The grab operations make use of an interrupt line assigned 
  to the PCI bus. The grab operation will freeze, or will not
  behave properly, if there is a conflict with interrupt lines
  or if there is no interrupt line enabled on the PCI bus.
  Make sure that your BIOS configuration has assigned such a line
  to the PCI bus and that this line is not shared by another bus. 
  Note that for the PCI bus, the interrupt lines are sharable, 
  which is not the case for the ISA bus. So make sure that your 
  ISA bus is not using the same interrupt line as your PCI bus. 
  To disable the use of interrupts for grab operations, refer
  to the characteristics of MsysAlloc() in the MIL section or System Control
  in the ActveMIL section of the present decument.

- In some PCs the bridge between the PCI bus and the PC memory is not fast
  enough for the fast PCI transfers of the METEOR. If this is the case, 
  you may be unable to grab properly with the METEOR on that PC.

- In old PCI systems, the bridge between the PCI bus and the PC memory
  is too slow to be able to grab big images (typically 640X480
  in RGB 888 at 32 bits per pixel) in the PC memory. In that case,
  MIL will automatically use the RGB 555 (16 bits) format instead of 
  the RGBX 888 (32 bits) format and the 3 least significant bits of
  the RGB buffers will be set to 0 when reading the pixels. On systems
  with fast PCI bridge, like Intel Triton Chip Set, full 32 bit grabs can
  be done.


===================================================================
MIL INFORMATION
===================================================================

PARTICULARITIES USING MIL AND THE METEOR:
-------------------------------------------------------------------

  Please refer to the MIL driver for METEOR appendix in the MIL command 
  reference manual to get detailed information about any particularities
  involving MIL and the METEOR. 

  The following notes do not appear in the appendix:

  MsysAlloc():   
  
       The METEOR performs grab operation into the host system memory via
       the PCI bus. In order to be able to grab in the host system memory
       via the PCI bus, buffers must be allocated in a physically linear 
       memory array. 

       Note, that in general, the installation program will 
       automatically set everything for you. Use the application
       mildrv.exe to set the necessary values in the registry database.
  
       To disable the use of interrupts for grab operations, a 
       special init flag must be passed to the MsysAlloc() at 
       system allocation time. The init flag is the 
       following: M_NO_INTERRUPT.
       
       When supported by the operating system (ie Win95 and NT4), the 
       MIL driver will make use of Direct Draw (DDraw). DirectDraw is a 
       DirectX SDK component that allows direct manipulation of display 
       memory, hardware blitters, hardware overlays, and page flipping. 
       DirectDraw provides this functionality while maintaining compatibility 
       with existing Microsoft Windows applications and device drivers. 
       However, some limitations are associated with its use. This is why a 
       special initialization flag exists to prevent MIL driver from using 
       DDraw. The init flag is the following: M_NO_DDRAW. Conversely, to force 
       MIL to use DDraw if it has decided not to make use of it, the following
       init flag must be specified: M_DDRAW.
       
       Under Microsoft Windows, if problems related to the tracking of a 
       window are experienced, that is if live grab operation is taking place at 
       a bad position in the desktop or if the content of the display window is 
       erratic, then specify the following init flag to disable the use of 
       DDraw: M_NO_DDRAW.
       
       This flag will disable both the enhanced window tracking and the fast
       display update of buffers. However it is also possible to disable 
       only one or the other option.
        by the use of a display control
       MdispControl() : M_WINDOW_USE_SYSTEMHOOK_TRACKING 

       MsysControl() :  M_DIB_ONLY 

       Note that in order to be effective, these control parameters must be 
       used prior to any MdispSelect() and MbufAlloc...() operation.

  MsysControl():   
  
       Under Microsoft Windows, to enable/disable the use of DDraw buffers 
       (fast display update):
       M_DIB_ONLY (M_ENABLE, M_DISABLE)
       Default=M_DISABLE.
  
       
DOS DPMI SERVER:

- Under DOS (Watcom), the following DPMI servers are not compatible 
  with the current MIL driver for METEOR: 386MAX and EMM386.
  

WHEN DEBUGGING USING DIRECTDRAW
-------------------------------

       When the MIL driver makes use of DirectDraw (DDraw), 
       you might experience some problems while debugging an application with 
       a display active. The system will hang and will not let you continue 
       debugging. To work around this problem, a remote debugger may be used 
       to separate the debugger environment from the application user interface. 
       Another method would be to use the M_NO_DDRAW init flag parameter at the 
       MsysAlloc() call. This will not let the allocated system to use DirectDraw.
       Another approach would be to use MdispControl() to specify the use of 
       a timeout to avoid a desktop lock. The control type to use is 
       M_DESTOP_LOCK_TIMEOUT and the control value to specify is the maximum time 
       in ms that the desktop may be locked. This time is usually related to the 
       camera frame time used in the application (two times the frame time). See
       MdispControl() below for more information.

       MdispControl():   
       
            Under Microsoft Windows, to enable/disable the use of enhanced window 
            tracking:
            M_WINDOW_USE_SYSTEMHOOK_TRACKING (M_ENABLE, M_DISABLE) 
            Default=M_ENABLE.
            
            Under Microsoft Windows, to enable/disable the use of desktop 
            lock timeout:
            M_DESKTOP_LOCK_TIMEOUT (M_INFINITE, M_DEFAULT, any other value)
            Default=M_INFINITE.
            
            Value M_INFINITE: The timeout is not activated; therefore the desktop 
            may hang while debugging the application.
            Value M_DEFAULT: The timeout is activated using a timeout value 
            equal to twice the frame time of a standard RS-170 camera.
            Value long > 0: The timeout is activated and the timeout value is
            the time specified in ms.
      
            
===================================================================
ACTIVEMIL INFORMATION
===================================================================

PARTICULARITIES USING ACTIVEMIL AND THE METEOR:
-------------------------------------------------------------------

  Please refer to the ActiveMIL board specific sections in the ActiveMIL 
  command reference manual to get detailed information about any 
  particularities involving ActiveMIL and the METEOR. 

  The following notes do not appear in the appendix:

  System Control:
  
       The METEOR performs grab operation into the host system memory via
       the PCI bus. In order to be able to grab in the host system memory
       via the PCI bus, buffers must be allocated in a physically linear 
       memory array. 

       Note that, in general, the installation program will 
       automatically set everything for you. Use the application
       mildrv.exe to set the necessary values in the registry database.
  
       To disable the use of interrupts for grab operations, a 
       special init flag can be used : 
       System.InitializationFlag = mNoInterrupts.
       
       When supported by the operating system (ie Win95 and NT4), the 
       ActiveMIL driver will make use of Direct Draw (DDraw). DirectDraw is a 
       DirectX SDK component that allows direct manipulation of display 
       memory, hardware blitters, hardware overlays, and page flipping. 
       DirectDraw provides this functionality while maintaining compatibility 
       with existing Microsoft Windows applications and device drivers. 
       However, some limitations are associated with its use. This is why a 
       special initialization flag exists to prevent ActiveMIL driver 
       from using DDraw : System.InitializationFlag = mNoDirectDraw
       Conversely, to force ActiveMIL to use DDraw if it has decided not to make
       use of it, the following init flag must be specified: 
       System.InitializationFlag = mDirectDraw.
       
       If problems related to the tracking of a window are experienced,
       that is if live grab operation is taking place at a bad position in
       the desktop or if the content of the display window is erratic,
       then specify the following init flag to disable the use of DDraw:
       System.InitializationFlag = mNoDirectDraw.
       
       This flag will disable both the enhanced window tracking and the fast
       display update of buffers. However it is also possible to disable 
       only one or the other :
          To disable enhanced window tracking, use 
          Display.Control(mWindowUseSystemHookTracking, mDisable) 
          before associating the Display control to a buffer.

          To disable fast display update of buffers, either:
             1) set your buffer with a DIB format attribute at design time
             2) use System.Control(mDIBOnly, mEnable) before allocation of 
                your non-AutomaticAllocation buffers.

  
WHEN DEBUGGING USING DIRECTDRAW
-------------------------------

       When the ActiveMIL driver makes use of DirectDraw (DDraw),
       you might experience some problems while debugging an application with 
       a display active. The system will hang and will not let you continue 
       debugging. To work around this problem, a remote debugger may be used 
       to separate the debugger environment from the application user interface. 
       Another method would be to use System.InitializationFlag = mNoDirectDraw.
       This will not let the allocated system use DirectDraw.
       Another approach would be to use Dislay.Control() to specify the use of 
       a timeout to avoid a desktop lock. The control type to use is 
       mDesktopLockTimeOut and the control value to specify is the maximum time 
       in ms that the desktop may be locked. This time is usually related to the 
       camera frame time used in the application (two times the frame time). See
       System.Control() below for more information.

       System control "Control" method:
       
            To enable/disable the use of enhanced window  tracking:
            System.Control(mWindowUseSystemHookTracking, mEnable) or
            System.Control(mWindowUseSystemHookTracking, mDisable)
            Default = mEnable
            
            To enable/disable the use of desktop lock timeout:
            System.Control(mDesktopLockTimeout, VAL...) 

               with VAL being one of the following:
            
               mInfinite : The timeout is not activated; therefore the desktop 
                           may hang while debugging the application.
               mDefault  : The timeout is activated using a timeout value 
                           equal to twice the frame time of a standard 
                           RS-170 camera.
               long > 0  : The timeout is activated and the timeout value is
                           the time specified in msec.
               
               Default = mInfinite.
