<sect1>
<title>Using X</title>

<para>
This chapter provides some hints and tips for using DOSEMU in X.
</para>

<sect2>
<title>Basic information</title>

<para>
If you start <command>dosemu</command> in X it brings up its own window,
in which you can
also execute graphical programs such as games. To force text-only execution
of DOSEMU in an xterm or other terminal (konsole, gnome-terminal, and so on),
you need to run <command>dosemu -t</command>.
</para>

<para>
Use <command>dosemu -w</command> to start DOSEMU in fullscreen mode.
When running DOSEMU,
you can flip between fullscreen and windowed mode by pressing
&lt;Ctrl&gt;&lt;Alt&gt;&lt;F&gt;.
The graphics window is resizeable.
</para>

<para>
Some DOS applications want precise mouse control that is only possible
if the mouse cursor is trapped in the DOSEMU window. To enable this you
need to grab the mouse by pressing &lt;Ctrl&gt;&lt;Alt&gt;&lt;Home&gt;.
Similarly, you can grab the keyboard by pressing
&lt;Ctrl&gt;&lt;Alt&gt;&lt;K&gt;, or
&lt;Ctrl&gt;&lt;Alt&gt;&lt;Shift&gt;&lt;K&gt; if your
window manager already grabs &lt;Ctrl&gt;&lt;Alt&gt;&lt;K&gt;.
After you grab the keyboard
all key combinations (including &lt;Alt&gt;&lt;Tab&gt; and so on)
are passed to DOSEMU.
In fullscreen mode the mouse and keyboard are both automatically grabbed.
</para>

<para>
Use &lt;Ctrl&gt;&lt;Alt&gt;&lt;Pause&gt; to pause and unpause
the DOSEMU session, which is useful if you want it to sit silently
in the background when it is eating too much CPU time.
Press &lt;Ctrl&gt;&lt;Alt&gt;&lt;PgDn&gt; or click the close button
of the window to exit DOSEMU.
</para>

<para>
DOSEMU uses bitmapped internal fonts by default, so it can accurately
simulate a real VGA card text mode. It is also possible to use X fonts.
The advantages of these is that they may be easier on the eyes, and
are faster, in particular if you use DOSEMU remotely. Any native DOS font
setting utilities do not work, however. To set an X font use the
provided xmode.com utility, using
<screen>
xmode -font vga
</screen>
at the DOS prompt or
<screen>
$_X_font = "vga"
</screen>
in dosemu.conf. The provided fonts are vga, vga8x19, vga11x19, vga10x24,
vga12x30, vga-cp866, and vga10x20-cp866.
</para>

<para>
If the mouse is not grabbed, then you can copy and paste text if the DOSEMU
window is in text mode. This uses the standard X mechanism: select by
dragging the left mouse button, and paste by pressing the middle mouse
button.
</para>
</sect2>

<sect2>
<title> More detailed information, hints and tips</title>

<para>
What you might take care of:
</para>

<para>

<itemizedlist>
<listitem>

<para>
If backspace and delete do not work, you can try
 'xmodmap -e "keycode 22 = 0xff08"' to get use of your backspace key, and
</para>
</listitem>
<listitem>

<para>
 'xmodmap -e "keycode 107 = 0xffff"' to get use of your delete key.
</para>
</listitem>
<listitem>

<para>
 Make sure DOSEMU has X support compiled in. The configure script
 complains loudly if it does not find X development libraries.
</para>
</listitem>

<listitem>
<para>
 There are some X-related configuration options for dosemu.conf.
See the file itself for details.
</para>
</listitem>
<listitem>

<para>
 Keyboard support of course depends on your X keyboard mappings (xmodmap).
If certain keys don't work (like Pause, Backspace,...), it *might* be 
because you haven't defined them in your xmodmap, or defined to something
other than DOSEMU expects.
</para>
</listitem>
<listitem>
<para>
 using the provided icon (dosemu.xpm):
</para>

<para>

<itemizedlist>
<listitem>

<para>
 you need the xpm (pixmaps) package. If you're not sure, look for
a file like /usr/X11R6/lib/libXpm.so.*
</para>
</listitem>
<listitem>

<para>
 you also need a window manager which supports pixmaps. Fvwm is fine,
but I can't tell you about others. Twm probaby won't do.
</para>
</listitem>
<listitem>

<para>
 copy dosemu.xpm to where you usually keep your pixmap (not bitmap!) 
files (perhaps /usr/share/pixmaps)
</para>
</listitem>
<listitem>
<para>
tell your window manager to use it. For fvwm, add the following
line to your fvwmrc file:
</para>

<para>

<screen>
     
     Icon "xdosemu"   dosemu.xpm
</screen>

</para>

<para>
This assumes you have defined a PixmapPath. Otherwise, specify the
entire pathname.
</para>
</listitem>
<listitem>

<para>
 note that if you set a different icon name than "xdosemu" in your
dosemu.conf, you will also have to change the fvwmrc entry.
</para>
</listitem>
<listitem>

<para>
 restart the window manager. There's usually an option in the
root menu to do so.
</para>
</listitem>

</itemizedlist>

</para>

<para>
Now you should see the icon whenever you iconify xdosemu.
</para>

<para>
Note that the xdosemu program itself does not include the icon - that's
why you have to tell the window manager. I chose to do it this way
to avoid xdosemu <emphasis>requiring</emphasis> the Xpm library.
</para>
</listitem>
<listitem>

<para>
 If anything else does not work as expected, don't panic :-)
Remember the thing is still under construction.
However, if you think it's a real bug, please tell me.
</para>
</listitem>

</itemizedlist>

</para>

</sect2>
<sect2>
<title>The VGA Emulator</title>

<para>
In X, a VGA card is emulated. The same happens if you use the SDL library
using <command>dosemu -S</command>. This emulation (vgaemu) enables
X to run graphics modes.
</para>

<para>
Some features:
<itemizedlist>
<listitem>

<para>
 Video memory. 1 Mb is allocated. It is mapped with mmap() in the VGA 
memory region of DOSEMU (0xa00000-0xbfffff) to support bank switching.
This is very i386-Linux specific, don't be surprised if it doesn't work
under NetBSD or another Linux flavour (Alpha/Sparc/MIPS/etc).
</para>
</listitem>
<listitem>

<para>
 The DAC (Digital to Analog Converter). The DAC is completely emulated,
except for the pelmask. This is not difficult to implement, but it is
terribly slow because a change in the pelmask requires a complete redraw
of the screen. Fortunately, the pelmask changes aren't used often so
nobody will notice ;-)
</para>
</listitem>
<listitem>

<para>
 The attribute controller is emulated.
</para>
</listitem>
<listitem>

<para>
 The emulator emulates a basic Trident TVGA8900C graphics card.
 All standard VGA modes are emulated, most VGA hardware features (mode-X,
 320x240 and so on), some Trident extensions, and on
 top of that many high-resolution VESA 2.0 modes, that were not present
 in the original Trident card.
 Some (very few) programs, such as Fast Tracker, play intimately with the
 VGA hardware and may not work. As vgaemu improves these problems should
 disappear.
</para>
</listitem>

<listitem>
<para>
 Nearly full VESA 2.0 support.
</para>
</listitem>
<listitem>

<para>
 A VESA compatible video BIOS is mapped at 0xc00000. It is small because
 it only contains some glue code and the BIOS fonts (8x8, 8x14, 8x16).
</para>
</listitem>

<listitem>
<para>
 support for hi- and true-color modes (using Trident SVGA mode numbers
and bank switching)
</para>
</listitem>
<listitem>

<para>
 Support for mode-X type graphics modes (non-chain4 modes as used by e.g. DOOM)
</para>
</listitem>
<listitem>

<para>
 gamma correction for graphics modes
</para>
</listitem>
<listitem>

<para>
 video memory size is configurable via dosemu.conf
</para>
</listitem>
<listitem>

<para>
 initial graphics window size is configurable
</para>
</listitem>

<listitem>
<para>
The current hi- (16bpp) and true (24/32bpp) color support does
not allow resizing of the graphics window and gamma correction
is ignored.
</para>
</listitem>
</itemizedlist>

<para>
As the typical graphics mode with 320x200x8 will be used often
with large scalings and modern graphics boards are pretty fast,
Steffen Winterfeldt added something to eat up your CPU time: you can turn on
the bilinear interpolation. It greatly improves the display
quality (but is rather slow as I haven't had time yet to implement
an optimized version - it's plain C for now).
If the bilinear filter is too slow, you might instead try the linear
filter which interpolates only horizontally.
</para>

<para>
Note that (bi)linear filtering is not available on all
VGA/X display combinations. The standard drawing routines
are used instead in such cases.
</para>

<para>
If a VGA mode is not supported on your current X display, the graphics
screen will just remain black. Note that this <emphasis remap="bf">does not</emphasis> mean
that DOSEMU has crashed.
</para>

<para>
The only unsupported VBE function is VGA state save/restore. But this
functionality is rarely used and its lack should not cause
too much problems.
</para>

<para>
VBE allows you to use the horizontal and vertical scrolling
function even in text modes. This feature is not implemented.
</para>

<para>
If you think it causes problems, the linear frame buffer (LFB)
can be turned of via dosemu.conf as well as the protected mode
interface. Note, however, that LFB modes are faster than
banked modes, even in DOSEMU.
</para>

<para>
The default VBE mode list defines a lot of medium resolution
modes suitable for games (like Duke3D). You can still
create your own modes via dosemu.conf. Note that you
cannot define the same mode twice; the second (and all
subsequent) definitions will be ignored.
</para>

<para>
Modes that are defined but cannot be supported due
to lack of video memory or because they cannot be
displayed on your X display, are marked as unsupported
in the VBE mode list (but are still in it).
</para>

<para>
The current interface between VGAEmu and X will try to update
all invalid video pages at a time. This may, particularly
in hi-res VBE/SVGA modes, considerably disturb DOSEMU's signal
handling. That cannot be helped for the moment, but will
be addressed soon (by running an extra update thread).
</para>

<para>
If you really think that this is the cause of your problem, you might
try to play with veut.max_max_len in env/video/render.c.
This variable limits the amount of video memory that is updated
during one timer interrupt. This way you can dramatically
reduce the load of screen updates, but at the same rate reduce your
display quality.
</para>

<para>
Gamma correction works in both 4 and 8 bit modes. It must be specified
as a float value, e.g. $_X_gamma=(1.0). Higher values
give brighter graphics, lower make them darker. Reasonable
values are within a range of 0.5 ... 2.0.
</para>

<para>
You can specify the video memory size that the VGA emulator
should use in dosemu.conf. The value will be rounded up
to the nearest 256 kbyte boundary. You should stick to typical
values like 1024, 2048 or 4096 as not to confuse DOS applications.
Note that whatever value you give, 4 bit modes are only
supported up to a size of 800x600.
</para>

<para>
You can influence the initial size of the graphics window in various
ways. Normally it will have the same size (in pixel) as the VGA graphics
mode, except for mode 0x13 (320x200, 256 colors), which will be scaled by
the value of <emphasis>mode13fact</emphasis> (defaults to 2).
Alternatively, you can directly specify a window size in dosemu.conf via
<emphasis>$_X_winsize</emphasis>. You can still resize the window later.
</para>

<para>
The config option <emphasis>$_X_fixed_aspect</emphasis> allows you to fix the aspect ratio
of the graphics window while resizing it. Alternatively, <emphasis>$_X_aspect_43</emphasis>
ties the aspect ratio to a value of 4:3. The idea behind this is that, whatever
the actual resolution of a graphics mode is in DOS, it is displayed on
a 4:3 monitor. This way you won't run into problems with modes such
as 640x200 (or even 320x200) which would look somewhat distorted otherwise.
</para>

<para>
For planar modes (for instance, most 16 colour modes, but also certain
256-colour modes: mode-X), vgaemu has to
switch to partial cpu emulation. This can be slow, but expect it to
improve over time.
</para>
</sect2>

</sect1>

