Removed DOS task fields from the NE_MODULE structure.
[wine] / documentation / x11drv
1 The X11 driver
2 --------------
3
4    Most Wine users run Wine under the windowing system known as X11.
5    During most of Wine's history, this was the only display driver
6    available, but in recent years, parts of Wine has been reorganized to
7    allow for other display drivers (although the only alternative
8    currently available is Patrik Stridvall's ncurses-based ttydrv, which
9    he claims works for displaying calc.exe). The display driver is chosen
10    with the "GraphicsDriver" option in the [wine] section of
11    wine.conf/.winerc, but I will only cover the x11drv in this document.
12    
13   x11drv modes of operation
14   
15    The x11drv consists of two conceptually distinct pieces, the graphics
16    driver (GDI part), and the windowing driver (USER part). Both of these
17    are linked into the libx11drv.so module, though (which you load with
18    the "GraphicsDriver" option). In Wine, running on X11, the graphics
19    driver must draw on drawables (window interiors) provided by the
20    windowing driver. This differs a bit from the Windows model, where the
21    windowing system creates and configures device contexts controlled by
22    the graphics driver, and applications are allowed to hook into this
23    relationship anywhere they like. Thus, to provide any reasonable
24    tradeoff between compatibility and usability, the x11drv has three
25    different modes of operation.
26    
27    Unmanaged/Normal
28           The default. Window-manager-independent (any running window
29           manager is ignored completely). Window decorations (title bars,
30           borders, etc) are drawn by Wine to look and feel like the real
31           Windows. This is compatible with applications that depend on
32           being able to compute the exact sizes of any such decorations,
33           or that want to draw their own.
34           
35    Managed
36           Specified by using the --managed command-line option or the
37           Managed wine.conf option (see below). Ordinary top-level frame
38           windows with thick borders, title bars, and system menus will
39           be managed by your window manager. This lets these applications
40           integrate better with the rest of your desktop, but may not
41           always work perfectly. (A rewrite of this mode of operation, to
42           make it more robust and less patchy, is highly desirable,
43           though, and is planned to be done before the Wine 1.0 release.)
44           
45    Desktop-in-a-Box
46           Specified by using the --desktop command-line option (with a
47           geometry, e.g. --desktop 800x600 for a such-sized desktop, or
48           even --desktop 800x600+0+0 to automatically position the
49           desktop at the upper-left corner of the display). This is the
50           mode most compatible with the Windows model. All application
51           windows will just be Wine-drawn windows inside the
52           Wine-provided desktop window (which will itself be managed by
53           your window manager), and Windows applications can roam freely
54           within this virtual workspace and think they own it all,
55           without disturbing your other X apps.
56           
57   The [x11drv] section
58   
59    AllocSystemColors
60           Applies only if you have a palette-based display, i.e. if your
61           X server is set to a depth of 8bpp, and if you haven't
62           requested a private color map. It specifies the maximum number
63           of shared colormap cells (palette entries) Wine should occupy.
64           The higher this value, the less colors will be available to
65           other applications.
66           
67    PrivateColorMap
68           Applies only if you have a palette-based display, i.e. if your
69           X server is set to a depth of 8bpp. It specifies that you don't
70           want to use the shared color map, but a private color map,
71           where all 256 colors are available. The disadvantage is that
72           Wine's private color map is only seen while the mouse pointer
73           is inside a Wine window, so psychedelic flashing and funky
74           colors will become routine if you use the mouse a lot.
75           
76    PerfectGraphics
77           This option only determines whether fast X11 routines or exact
78           Wine routines will be used for certain ROP codes in blit
79           operations. Most users won't notice any difference.
80           
81    ScreenDepth
82           Applies only to multi-depth displays. It specifies which of the
83           available depths Wine should use (and tell Windows apps about).
84           
85    Display
86           This specifies which X11 display to use, and if specified, will
87           override both the DISPLAY environment variable and the
88           --display command-line option.
89           
90    Managed
91           Wine can let frame windows be managed by your window manager.
92           This option specifies whether you want that by default.
93           
94    UseDGA
95           This specifies whether you want DirectDraw to use XFree86's
96           Direct Graphics Architecture (DGA), which is able to take over
97           the entire display and run the game full-screen at maximum
98           speed. (With DGA1 (XFree86 3.x), you still have to configure
99           the X server to the game's requested bpp first, but with DGA2
100           (XFree86 4.x), runtime depth-switching may be possible,
101           depending on your driver's capabilities.) But be aware that if
102           Wine crashes while in DGA mode, it may not be possible to
103           regain control over your computer without rebooting. DGA
104           normally requires either root privileges or read/write access
105           to /dev/mem.
106           
107    UseXShm
108           If you don't want DirectX to use DGA, you can at least use X
109           Shared Memory extensions (XShm). It is much slower than DGA,
110           since the app doesn't have direct access to the physical frame
111           buffer, but using shared memory to draw the frame is at least
112           faster than sending the data through the standard X11 socket,
113           even though Wine's XShm support is still known to crash
114           sometimes.
115           
116    DXGrab
117           If you don't use DGA, you may want an alternative means to
118           convince the mouse cursor to stay within the game window. This
119           option does that. Of course, as with DGA, if Wine crashes,
120           you're in trouble (although not as badly as in the DGA case,
121           since you can still use the keyboard to get out of X).
122           
123    DesktopDoubleBuffered
124           Applies only if you use the --desktop command-line option to
125           run in a desktop window. Specifies whether to create the
126           desktop window with a double-buffered visual, something most
127           OpenGL games need to run correctly.
128           
129                                                               - Ove Kåven