
  1. About HXGUI
  
  HX GUI is an extension to the HX runtime and consists of some binaries
  which extend the HX Win32 emulation significantly:
  
  þ Winsocket support (WSOCK32.DLL, WS2_32.DLL)
  þ Windows Multimedia support (WINMM.DLL)
  þ DirectInput support (DINPUT.DLL)
  þ DirectSound support (DSOUND.DLL)
  þ OpenGL (software) support by using OPENGL32.DLL from Win98/95
  
  This allows to run more Win32 applications, for example applications
  based on the Win32 port of SDL. The HX runtime is required as well,
  and the version numbers of HXRT and HXGUI must be identical.


  2. HXGUI Installation

  þ unzip HXGUI.ZIP in the same directory where HXRT has been unzipped.
  
  þ the Winsocket emulation is based on WatTCP/Watt-32. This software
    uses a configuration file WATTCP.CFG which is located in HX\Bin
    and most likely will require some adjustments.

  þ change in HXGUI v2.12: if a patched OPENGL32.DLL was created with
    previous versions of HXGUI, this should be undone now and the 
    unmodified version of OPENGL32.DLL be used. 
    

  3. OpenGL Installation
  
  HXGUI supports using the Windows 9x versions of OPENGL32.DLL and 
  GLU32.DLL. This will allow to run OpenGL applications, natively or through
  SDL. Just copy the dlls from the windows system directory to the HX BIN
  directory. If no copy of Windows 9x is available - or the dlls cannot be
  found in the system directory - one can search for a redistributable version
  for Windows 95, named OPENGL95.EXE. In case nothing can be found just 
  download these binaries from http://www.japheth.de/Download/opengl95.zip.
  Please be aware that this early version for Windows 95 is slower than the
  one supplied with Windows 98. Regretably the WinXP versions of the dlls
  cannot be used currently.

  
  4. Preparing to run applications using HXGUI features

  þ many GUI applications want to access files with long names (LFN).
    For this to work one must install LFN support for DOS. A driver known
    to work pretty good - although not perfect - is DOSLFN. Read
    HX\DOC\LFN.TXT where to get this driver.

  þ To enable the mouse load a DOS mouse driver. CTMOUSE is a good choice
    and it is free.
    
  þ Since version 1.40 there is support for wave sound in HXGUI. A SB Pro
    or SB 16 compatible sound card will be accepted. To enable sound the
    BLASTER environment variable has to be set. This should have been done
    by some sound card utility, else one may enter:

      set BLASTER=A220 I5 D1              ;for a SB Pro compatible card
      set BLASTER=A220 I5 D1 H5 T6        ;for a SB 16 compatible card

    The correct values may vary, however (i.e. I7 instead of I5).
    Sound formats supported are 8-bit or 16-bit wave sounds in mono or stereo.
  
  þ Since version 1.43 there is support for midi sound (MPU-401) in HXGUI.
    It requires at least a SB 16 compatible sound card. To enable midi sound,
    an entry for the midi port must be found in the BLASTER environment 
    variable:
    
      set BLASTER=A220 I5 D1 H5 P330 T6   ;to enable MPU-401 at port 330

    The correct values may vary, however (i.e. P300 instead of P330).
      
  þ Since version 1.99 there is support for internet access through HX's
    WinSocket emulation. This emulation requires a so-called packet driver
    to be installed. For many NICs there are free packet drivers available.


  5. Preparing to run SDL applications

  þ the Win32 version of SDL (SDL.DLL) is needed. The binary of version
    1.2.12 may be found at

      http://www.libsdl.org/release/SDL-1.2.12-win32.zip

    or, even better, search the current version (with/without source) at

      http://www.libsdl.org

  þ SDL.DLL most likely will need the MS Visual C runtime dll MSVCRT.DLL.
    It must be ensured that this dll can be found somewhere in a directory
    included in the PATH environment variable.
    

  6. Known Problems / Restrictions / Hints

  þ HX displays a window without any system area. There is no "close window"
    icon on the screen, but the APPS (optionally Ctrl+Break) key will cause
    a menu to popup where one should be able to close the application window.
  
  þ HX's GUI extension will only run if a VESA BIOS is available which 
    supports LFB access (version 2.0+).

  þ GUI apps will run slower on DOS than on Windows. Most likely this is
    because there is no graphics acceleration available on DOS. For newer
    cpus one may gain some speed on DOS by applying tool VESAMTRR.EXE. View
    Unsupp\VESAMTRR.TXT for details.
  
  þ OpenGL applications most likely will not run in 8bpp video modes.
    Usually they require at least HiColor. For windowed applications set
    entry "bpp=" in HXGUIHLP.INI to 15, 16, 24 or 32 - whatever is
    appropriate.
  
  þ Some VESA BIOSes implement buggy code for saving and restoring the  
    video state. In such cases view HXGUIHLP.INI for switches which may
    disable this feature.
    
  þ HX will automatically switch to graphics mode for Win32 GUI applications.
    However, for binaries linked as Win32 console applications there will be
    no such mode switch. The screen will remain in text mode, unless the
    application sets a graphics mode on its own. This is a problem if a 
    window is to be rendered, it will be invisible. To allow those windows
    to be seen, the application has to be launched by entering:
    
      DPMILD32 -g application_name
  
  þ To run a Win32 GUI application in a Windows DOS box under control of
    HX one has to set environment variable DPMILDR=8192 and then launch the
    app by entering:

      DPMILD32 application_name

    On WinXP or WinNT, however, GUI apps won't run in a DOS box because no 
    VESA LFB is available there.

  þ The packet driver used for the WinSocket emulation can be loaded in   
    plain DOS only. For Windows DOS boxes there exist solutions which
    emulate a packet driver in this environment. These may work, but
    haven't been tested yet. For hints on problems with the packet driver
    see Doc\WSOCK32.TXT.
  
  þ For sound issues please be aware:
    - only SoundBlaster compatible cards/emulations are accepted
    - the BLASTER environment variable has to be set. Try TEST\GETSB.EXE.
    - if an expanded memory manager (EMM386) is loaded, it may have some
      influence on sound quality.
    - the sound card should not share its IRQ with any other card.
    - some (all?) SBLive/SBPCI SB16 DOS emulation drivers have a bug which
      may require to set environment variable HDPMI=512 (see HDPMI.TXT for
      details).
    - the standard sound emulation in a Windows XP DOS box is limited to
      a SB 2. This is not sufficient for HX, but one may get a SB 16
      emulation by installing external products, for example:
      
      + VDMSound: this is free software. Regretably the SB16 emulation
        quality sometimes is a bit low.
      + SoundFX 2000: SB16 emulation is good, but it is shareware only and
        the unregistered version has severe annoyances.
  
  þ Not all versions of SDL.DLL work with HXGUI, for example version
    1.2.4 may not work. Also, SDL might have problems with sound and video
    in certain configurations. In "windib" mode (SET SDL_VIDEODRIVER=windib)
    not all keys may "work" if the keyboards is non-US. OTOH, the "directx"
    mode (SET SDL_VIDEODRIVER=directx) seems to have "color" problems with
    8 bpp palettized video modes if the applications doesn't run fullscreen.
  
  þ In case of problems try to run the test applications in directory TEST.
    They may give some hints about what is wrong. View HX\TEST\README2.TXT
    for details.


  7. Files Overview

  þ HXGUIHLP.DLL: a Win32 PE binary which will be loaded by DPMILD32.EXE
    if a Win32 GUI application is to be launched. Does some initialisation
    like switching the screen to graphics mode and so on.

  þ HXGUIHLP.INI: initialisation file which tells HXGUIHLP.DLL what to do.
  
  þ Some Win32 emulation dlls. Currently these are:
  
    Name            Comment
    ---------------------------------------------------------------------
    COMCTL32.DLL    (almost) dummy
    COMDLG32.DLL    dummy
    DCIMAN32.DLL    required by the Windows 9x versions of OPENGL32.DLL
    DINPUT.DLL      DirectInput emulation
    DSOUND.DLL      DirectSound emulation
    IPHLPAPI.DLL    dummy
    MPR.DLL         dummy
    MSACM32.DLL     dummy
    SHELL32.DLL     (almost) dummy
    SHLWAPI.DLL     (almost) dummy
    WINMM.DLL       wave/midi sound output / timers
    WINSPOOL.DRV    dummy
    WSOCK32.DLL     WinSocket emulation (uses WatTCP/Watt-32)
    WS2_32.DLL      WinSocket 2 emulation, routes most calls to WSOCK32.DLL
    
    These dlls have identical names as the ones supplied with windows, so
    DO NOT copy them into the windows system directory and make sure that 
    the windows versions of these dlls are "invisible" for HX when running
    in native DOS.

  þ SB16.DLL: for SB Pro and SB 16 access.
  
  þ TEST\*: some test programs.

  þ UNSUPP\PATCHOGL.EXE: tool to patch windows 9x versions of OPENGL32.DLL
    so they are safe to use with HX. View UNSUPP\PATCHOGL.TXT for details.

  þ UNSUPP\VESAMTRR.EXE: tool to setup a MTRR for VESA LFB to type WC, which
    may increase video memory write performance. To be used in plain DOS only.

  þ UNSUPP\WSOCK32.DLL: a version of WSOCK32 which contains just dummy 
    exports. May be useful if internet access is not required or no
    working packet driver is available, but WSOCK32 is referenced by a binary.


  8. History
  
  05/27/2011, V2.17: HXGUIHLP V2.5, SHELL32 V1.8, WSOCK32 V1.8, WS2_32 V1.9,
                     WINSPOOL V1.2.
                     SHLWAPI.DLL added.
  11/16/2009, V2.16: SHELL32 V1.7, WSOCK32 V1.7, WS2_32 V1.8.
                     Sample WSTEST updated.
                     WINSPOOL.DRV V1.1 added.
  01/20/2009, V2.15: SHELL32 V1.6.
                     JWasm used to translate assembly modules.
  03/02/2008, V2.14: -
  01/11/2008, V2.13: WINMM V2.12
  07/15/2007, V2.12: HXGUIHLP V2.3, DSOUND V1.3, WINMM V2.11, SB16 V1.1,
                     SHELL32 V1.5.
                     PATCHOGL.EXE removed because it is obsolete.
                     MPR.DLL added.
  03/15/2007, V2.11: HXGUIHLP V2.2, WS2_32 V1.7, DCIMAN32 V1.1, DSOUND V1.2,
                     WINMM V2.10, SB16 V1.0.
                     HXGUIHLP now automatically loaded when a window is to
                     be displayed and screen is still in text mode.
                     OpenGL will now work with 15/16 bpp.
                     SB specific code moved from WINMM.DLL to SB16.DLL.
  12/14/2006, V2.10: WINMM V2.9. 
  10/15/2006, V2.9:  HXGUIHLP V2.1, WINMM V2.8, WSOCK32 V1.6, WS2_32 V1.6, 
                     SHELL32 V1.4.
  09/14/2006, V2.8:  SHELL32 V1.3.
                     Bochs PC emulator supported.
  08/15/2006, V2.7:  HXGUIHLP V2.0, WINMM V2.7, SHELL32 V1.2.
                     Qemu 0.8.2 supported. APPS key now default key to show
                     the hxguihlp menu, may be changed by editing hxguihlp.ini.
                     Win32 emulation dlls COMCTL32.DLL and COMDLG32.DLL added.
  07/15/2006, V2.6:  HXGUIHLP V1.9, WINMM V2.6, SHELL32 V1.1.
                     SDL V1.2.11 runtime dll supported.
  06/14/2006, V2.5:  WINMM V2.5.
                     TEST\SDLAUDIO.EXE added.
                     SDL V1.2.10 runtime dll supported.
  05/15/2006, V2.4:  WSOCK32 V1.5, WS2_32 V1.5
                     SETVMODE.EXE deleted (no longer required).
  05/02/2006, V2.3:  -
  04/21/2006, V2.2:  DINPUT V1.4.
  04/04/2006, V2.1:  DINPUT V1.3.
  03/18/2006, V2.0:  HXGUIHLP V1.8, WINMM V2.4. WSOCK32 V1.4
                     WinSocket emulation implemented in WSOCK32.DLL.
                     SHELL32.DLL emulation dll added.
                     WS2_32.DLL routes all calls to WSOCK32.DLL.
                     Some test apps moved to HXRT. GUI subdirectory renamed
                     to TEST. Test app WSTEST added. Unsupp\DKRNL32.DLL
                     deleted.
  02/06/2006, V1.43: HXGUIHLP V1.7, WINMM V2.3, DSOUND V1.1.
                     SB MPU-401 support added (SB16+ only).
                     test app for triple buffering added.
  01/22/2006, V1.42: HXGUIHLP V1.6, WINMM V2.2, DINPUT V1.2, DSOUND V1.0.
                     DirectSound support added.
  01/02/2006, V1.41: HXGUIHLP V1.5, WINMM V2.1.
                     Now a SoundBlaster Pro compatible device is accepted
                     as well.
  12/20/2005, V1.40: WINMM V2.0.
                     Renamed HXSDL to HXGUI.
                     Unsupp\DKRNL32.DLL added. 
                     Unsupp\VESAMTRR.EXE added. 
                     Support for SoundBlaster 16 compatible wave sound added.
  12/07/2005, V1.39: HXGUIHLP V1.4, WINMM V1.2.
                     DCIMAN32.DLL, WSOCK32.DLL and PATCHOGL.EXE added.
                     Support for OpenGL added.
  11/24/2005, V1.38: HXGUIHLP V1.3, WINMM V1.1.
                     SETVMODE.EXE, GETVMODE.EXE, FLIPTST.EXE added.
  11/18/2005, V1.37: HXGUIHLP V1.2.
  11/07/2005, V1.36: HXGUIHLP V1.1. DINPUT V1.1. ENUMMODE.EXE added.
                     DITEST.EXE displays keyboard+mouse events.
  10/24/2005, V1.35: HX SDL first version. 
                     HXGUIHLP V1.0, DINPUT V1.0, WINMM V1.0. 

  For details about version changes see the documentation files
  in subdirectory DOC.


  9. License

  HXGUI is part of HX DOS extender. This extender is freeware and may be
  used for any purpose. The binaries found in HXGUI can be freely distributed
  with any application. Copyright Japheth 2005-2010. 
  
  The WSOCK32.DLL binary is written with the help of WatTCP/Watt-32. If you
  want to distribute WSOCK32.DLL, please read the copyright regarding WatTCP
  in Doc\WSOCK32.TXT.

  Japheth   ( http://www.japheth.de )

