| 1 | .\" $Xorg: Xnest.man,v 1.3 2000/08/17 19:53:28 cpqbld Exp $ |
| 2 | .\" Copyright (c) 1993, 1994 X Consortium |
| 3 | .\" |
| 4 | .\" Permission is hereby granted, free of charge, to any person obtaining |
| 5 | .\" a copy of this software and associated documentation files (the |
| 6 | .\" "Software"), to deal in the Software without restriction, including |
| 7 | .\" without limitation the rights to use, copy, modify, merge, publish, |
| 8 | .\" distribute, sublicense, and/or sell copies of the Software, and to |
| 9 | .\" permit persons to whom the Software is furnished to do so, subject to |
| 10 | .\" the following conditions: |
| 11 | .\" |
| 12 | .\" The above copyright notice and this permission notice shall be included |
| 13 | .\" in all copies or substantial portions of the Software. |
| 14 | .\" |
| 15 | .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS |
| 16 | .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF |
| 17 | .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. |
| 18 | .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR |
| 19 | .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, |
| 20 | .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR |
| 21 | .\" OTHER DEALINGS IN THE SOFTWARE. |
| 22 | .\" |
| 23 | .\" Except as contained in this notice, the name of the X Consortium shall |
| 24 | .\" not be used in advertising or otherwise to promote the sale, use or |
| 25 | .\" other dealings in this Software without prior written authorization |
| 26 | .\" from the X Consortium. |
| 27 | .\" |
| 28 | .\" $XFree86: xc/programs/Xserver/hw/xnest/Xnest.man,v 1.6 2001/01/27 18:21:00 dawes Exp $ |
| 29 | .\" |
| 30 | .TH Xnest __appmansuffix__ __xorgversion__ |
| 31 | .SH NAME |
| 32 | Xnest \- a nested X server |
| 33 | .SH SYNOPSIS |
| 34 | .B Xnest |
| 35 | [ |
| 36 | .I options |
| 37 | ] |
| 38 | .SH DESCRIPTION |
| 39 | .B Xnest |
| 40 | is both an X client and an X server. |
| 41 | .B Xnest |
| 42 | is a client of the real server which manages windows and graphics requests on |
| 43 | its behalf. |
| 44 | .B Xnest |
| 45 | is a server to its own clients. |
| 46 | .B Xnest |
| 47 | manages windows and graphics requests on their behalf. |
| 48 | To these clients, |
| 49 | .B Xnest |
| 50 | appears to be a conventional server. |
| 51 | .SH OPTIONS |
| 52 | .B Xnest |
| 53 | supports all standard options of the sample server implementation. |
| 54 | For more details, please see |
| 55 | .BR Xserver (__appmansuffix__). |
| 56 | The following additional arguments are supported as well. |
| 57 | .TP |
| 58 | .BI "\-display " string |
| 59 | This option specifies the display name of the real server that |
| 60 | .B Xnest |
| 61 | should try to connect to. |
| 62 | If it is not provided on the command line, |
| 63 | .B Xnest |
| 64 | will read the |
| 65 | .I DISPLAY |
| 66 | environment variable in order to find out this information. |
| 67 | .TP |
| 68 | .B \-sync |
| 69 | This option tells |
| 70 | .B Xnest |
| 71 | to synchronize its window and graphics operations with the real server. |
| 72 | This is a useful option for debugging, but it will slow down |
| 73 | .BR Xnest 's |
| 74 | performance considerably. |
| 75 | It should not be used unless absolutely necessary. |
| 76 | .TP |
| 77 | .B \-full |
| 78 | This option tells |
| 79 | .B Xnest |
| 80 | to utilize full regeneration of real server objects and reopen a new connection |
| 81 | to the real server each time the nested server regenerates. |
| 82 | The sample server implementation regenerates all objects in the server when the |
| 83 | last client of this server terminates. |
| 84 | When this happens, |
| 85 | .B Xnest |
| 86 | by default maintains the same top-level window and the same real server |
| 87 | connection in each new generation. |
| 88 | If the user selects full regeneration, even the top-level window and the |
| 89 | connection to the real server will be regenerated for each server generation. |
| 90 | .TP |
| 91 | .BI "\-class " string |
| 92 | This option specifies the default visual class of the nested server. |
| 93 | It is similar to the |
| 94 | .B \-cc |
| 95 | option from the set of standard options except that it will accept a string |
| 96 | rather than a number for the visual class specification. |
| 97 | The |
| 98 | .I string |
| 99 | must be one of the following six values: |
| 100 | .BR StaticGray , |
| 101 | .BR GrayScale , |
| 102 | .BR StaticColor , |
| 103 | .BR PseudoColor , |
| 104 | .BR TrueColor , |
| 105 | or |
| 106 | .BR DirectColor . |
| 107 | If both the |
| 108 | .B \-class |
| 109 | and |
| 110 | .B \-cc |
| 111 | options are specified, the last instance of either option takes precedence. |
| 112 | The class of the default visual of the nested server need not be the same as the |
| 113 | class of the default visual of the real server, but it must be supported by the |
| 114 | real server. |
| 115 | Use |
| 116 | .BR xdpyinfo (__appmansuffix__) |
| 117 | to obtain a list of supported visual classes on the real server before starting |
| 118 | .BR Xnest . |
| 119 | If the user chooses a static class, all the colors in the default color map will |
| 120 | be preallocated. |
| 121 | If the user chooses a dynamic class, colors in the default color map will be |
| 122 | available to individual clients for allocation. |
| 123 | .TP |
| 124 | .BI "\-depth " int |
| 125 | This option specifies the default visual depth of the nested server. |
| 126 | The depth of the default visual of the nested server need not be the same as the |
| 127 | depth of the default visual of the real server, but it must be supported by the |
| 128 | real server. |
| 129 | Use |
| 130 | .BR xdpyinfo (__appmansuffix__) |
| 131 | to obtain a list of supported visual depths on the real server before starting |
| 132 | .BR Xnest . |
| 133 | .TP |
| 134 | .B \-sss |
| 135 | This option tells |
| 136 | .B Xnest |
| 137 | to use the software screen saver. |
| 138 | By default, |
| 139 | .B Xnest |
| 140 | will use the screen saver that corresponds to the hardware screen saver in the |
| 141 | real server. |
| 142 | Of course, even this screen saver is software-generated since |
| 143 | .B Xnest |
| 144 | does not control any actual hardware. |
| 145 | However, it is treated as a hardware screen saver within the sample server code. |
| 146 | .TP |
| 147 | .B \-geometry \fIW\fBx\fIH\fB+\fIX\fB+\fIY\fP |
| 148 | This option specifies the geometry parameters for the top-level |
| 149 | .B Xnest |
| 150 | window. |
| 151 | See \(lqGEOMETRY SPECIFICATIONS\(rq in |
| 152 | .BR X (__miscmansuffix__) |
| 153 | for a discusson of this option's syntax. |
| 154 | This window corresponds to the root window of the nested server. |
| 155 | The width |
| 156 | .I W |
| 157 | and height |
| 158 | .I H |
| 159 | specified with this option will be the maximum width and height of each |
| 160 | top-level |
| 161 | .B Xnest |
| 162 | window. |
| 163 | .B Xnest |
| 164 | will allow the user to make any top-level window smaller, but it will not |
| 165 | actually change the size of the nested server root window. |
| 166 | .B Xnest |
| 167 | does not yet support the RANDR extension for resizing, rotation, and reflection |
| 168 | of the root window. |
| 169 | If this option is not specified, |
| 170 | .B Xnest |
| 171 | will choose |
| 172 | .I W |
| 173 | and |
| 174 | .I H |
| 175 | to be 3/4ths the dimensions of the root window of the real server. |
| 176 | .TP |
| 177 | .BI "\-bw " int |
| 178 | This option specifies the border width of the top-level |
| 179 | .B Xnest |
| 180 | window. |
| 181 | The integer parameter |
| 182 | .I int |
| 183 | must be positive. |
| 184 | The default border width is 1. |
| 185 | .TP |
| 186 | .BI "\-name " string |
| 187 | This option specifies the name of the top-level |
| 188 | .B Xnest |
| 189 | window as |
| 190 | .IR string . |
| 191 | The default value is the program name. |
| 192 | .TP |
| 193 | .BI "\-scrns " int |
| 194 | This option specifies the number of screens to create in the nested server. |
| 195 | For each screen, |
| 196 | .B Xnest |
| 197 | will create a separate top-level window. |
| 198 | Each screen is referenced by the number after the dot in the client display name |
| 199 | specification. |
| 200 | For example, |
| 201 | .B xterm \-display :1.1 |
| 202 | will open an |
| 203 | .BR xterm (__appmansuffix__) |
| 204 | client in the nested server with the display number |
| 205 | .B :1 |
| 206 | on the second screen. |
| 207 | The number of screens is limited by the hard-coded constant in the server sample |
| 208 | code, which is usually 3. |
| 209 | .TP |
| 210 | .B \-install |
| 211 | This option tells |
| 212 | .B Xnest |
| 213 | to do its own color map installation by bypassing the real window manager. |
| 214 | For it to work properly, the user will probably have to temporarily quit the |
| 215 | real window manager. |
| 216 | By default, |
| 217 | .B Xnest |
| 218 | will keep the nested client window whose color map should be installed in the |
| 219 | real server in the |
| 220 | .I WM_COLORMAP_WINDOWS |
| 221 | property of the top-level |
| 222 | .B Xnest |
| 223 | window. |
| 224 | If this color map is of the same visual type as the root window of the nested |
| 225 | server, |
| 226 | .B Xnest |
| 227 | will associate this color map with the top-level |
| 228 | .B Xnest |
| 229 | window as well. |
| 230 | Since this does not have to be the case, window managers should look primarily |
| 231 | at the |
| 232 | .I WM_COLORMAP_WINDOWS |
| 233 | property rather than the color map associated with the top-level |
| 234 | .B Xnest |
| 235 | window. |
| 236 | .\" Is the following still true? This sentence is several years old. |
| 237 | Unfortunately, window managers are not very good at doing that yet so this |
| 238 | option might come in handy. |
| 239 | .TP |
| 240 | .BI "\-parent " window_id |
| 241 | This option tells |
| 242 | .B Xnest |
| 243 | to use |
| 244 | .I window_id |
| 245 | as the root window instead of creating a window. |
| 246 | .\" XRX is dead, dead, dead. |
| 247 | .\" This option is used by the xrx xnestplugin. |
| 248 | .SH "EXTENDED DESCRIPTION" |
| 249 | Starting up |
| 250 | .B Xnest |
| 251 | is just as simple as starting up |
| 252 | .BR xclock (__appmansuffix__) |
| 253 | from a terminal emulator. |
| 254 | If a user wishes to run |
| 255 | .B Xnest |
| 256 | on the same |
| 257 | workstation as the real server, it is important that the nested server is given |
| 258 | its own listening socket address. |
| 259 | Therefore, if there is a server already running on the user's workstation, |
| 260 | .B Xnest |
| 261 | will have to be started up with a new display number. |
| 262 | Since there is usually no more than one server running on a workstation, |
| 263 | specifying |
| 264 | .RB \(oq "Xnest :1" \(cq |
| 265 | on the command line will be sufficient for most users. |
| 266 | For each server running on the workstation, the display number needs to be |
| 267 | incremented by one. |
| 268 | Thus, if you wish to start another |
| 269 | .BR Xnest , |
| 270 | you will need to type |
| 271 | .RB \(oq "Xnest :2" \(cq |
| 272 | on the command line. |
| 273 | .PP |
| 274 | To run clients in the nested server, each client needs to be given the same |
| 275 | display number as the nested server. |
| 276 | For example, |
| 277 | .RB \(oq "xterm \-display :1" \(cq |
| 278 | will start up an |
| 279 | .B xterm |
| 280 | process in the first nested server |
| 281 | and |
| 282 | .RB \(oq "xterm \-display :2" \(cq |
| 283 | will start an |
| 284 | .B xterm |
| 285 | in the second nested server from the example above. |
| 286 | Additional clients can be started from these |
| 287 | .BR xterm s |
| 288 | in each nested server. |
| 289 | .SS "Xnest as a client" |
| 290 | .B Xnest |
| 291 | behaves and looks to the real server and other real clients as another real |
| 292 | client. |
| 293 | It is a rather demanding client, however, since almost any window or graphics |
| 294 | request from a nested client will result in a window or graphics request from |
| 295 | .B Xnest |
| 296 | to the real server. |
| 297 | Therefore, it is desirable that |
| 298 | .B Xnest |
| 299 | and the real server are on a local network, or even better, on the same machine. |
| 300 | .B Xnest |
| 301 | assumes that the real server supports the SHAPE extension. |
| 302 | There is no way to turn off this assumption dynamically. |
| 303 | .B Xnest |
| 304 | can be compiled without the SHAPE extension built in, in which case the real |
| 305 | server need not support it. |
| 306 | Dynamic SHAPE extension selection support may be considered in further |
| 307 | development of |
| 308 | .BR Xnest . |
| 309 | .PP |
| 310 | Since |
| 311 | .B Xnest |
| 312 | need not use the same default visual as the the real server, the top-level |
| 313 | window of the |
| 314 | .B Xnest |
| 315 | client always has its own color map. |
| 316 | This implies that other windows' colors will not be displayed properly while the |
| 317 | keyboard or pointer focus is in the |
| 318 | .B Xnest |
| 319 | window, unless the real server has support for more than one installed color map |
| 320 | at any time. |
| 321 | The color map associated with the top window of the |
| 322 | .B Xnest |
| 323 | client need not be the appropriate color map that the nested server wants |
| 324 | installed in the real server. |
| 325 | In the case that a nested client attempts to install a color map of a different |
| 326 | visual from the default visual of the nested server, |
| 327 | .B Xnest |
| 328 | will put the top window of this nested client and all other top windows of the |
| 329 | nested clients that use the same color map into the |
| 330 | .I WM_COLORMAP_WINDOWS |
| 331 | property of the top-level |
| 332 | .B Xnest |
| 333 | window on the real server. |
| 334 | Thus, it is important that the real window manager that manages the |
| 335 | .B Xnest |
| 336 | top-level window looks at the |
| 337 | .I WM_COLORMAP_WINDOWS |
| 338 | property rather than the color map associated with the top-level |
| 339 | .B Xnest |
| 340 | window. |
| 341 | Since most window managers don't yet appear to implement this convention |
| 342 | properly, |
| 343 | .B Xnest |
| 344 | can optionally do direct installation of color maps into the real server |
| 345 | bypassing the real window manager. |
| 346 | If the user chooses this option, it is usually necessary to temporarily disable |
| 347 | the real window manager since it will interfere with the |
| 348 | .B Xnest |
| 349 | scheme of color map installation. |
| 350 | .PP |
| 351 | Keyboard and pointer control procedures of the nested server change the keyboard |
| 352 | and pointer control parameters of the real server. |
| 353 | Therefore, after |
| 354 | .B Xnest |
| 355 | is started up, it will change the keyboard and pointer controls of the real |
| 356 | server to its own internal defaults. |
| 357 | .SS "Xnest as a server" |
| 358 | .B Xnest |
| 359 | as a server looks exactly like a real server to its own clients. |
| 360 | For the clients, there is no way of telling if they are running on a real or a |
| 361 | nested server. |
| 362 | .PP |
| 363 | As already mentioned, |
| 364 | .B Xnest |
| 365 | is a very user-friendly server when it comes to customization. |
| 366 | .B Xnest |
| 367 | will pick up a number of command-line arguments that can configure its default |
| 368 | visual class and depth, number of screens, etc. |
| 369 | .PP |
| 370 | The only apparent intricacy from the users' perspective about using |
| 371 | .B Xnest |
| 372 | as a server is the selection of fonts. |
| 373 | .B Xnest |
| 374 | manages fonts by loading them locally and then passing the font name to the real |
| 375 | server and asking it to load that font remotely. |
| 376 | This approach avoids the overload of sending the glyph bits across the network |
| 377 | for every text operation, although it is really a bug. |
| 378 | The consequence of this approach is that the user will have to worry about two |
| 379 | different font paths \(em a local one for the nested server and a remote one for |
| 380 | the real server \(em since |
| 381 | .B Xnest |
| 382 | does not propagate its font path to the real server. |
| 383 | The reason for this is because real and nested servers need not run on the same |
| 384 | file system which makes the two font paths mutually incompatible. |
| 385 | Thus, if there is a font in the local font path of the nested server, there is |
| 386 | no guarantee that this font exists in the remote font path of the real server. |
| 387 | The |
| 388 | .BR xlsfonts (__appmansuffix__) |
| 389 | client, if run on the nested server, will list fonts in the local font path and, |
| 390 | if run on the real server, will list fonts in the remote font path. |
| 391 | Before a font can be successfully opened by the nested server, it has to exist |
| 392 | in local and remote font paths. |
| 393 | It is the users' responsibility to make sure that this is the case. |
| 394 | .SH "FUTURE DIRECTIONS" |
| 395 | Make dynamic the requirement for the SHAPE extension in the real server, rather |
| 396 | than having to recompile |
| 397 | .B Xnest |
| 398 | to turn this requirement on and off. |
| 399 | .PP |
| 400 | Perhaps there should be a command-line option to tell |
| 401 | .B Xnest |
| 402 | to inherit the keyboard and pointer control parameters from the real server |
| 403 | rather than imposing its own. |
| 404 | .PP |
| 405 | .B Xnest |
| 406 | should read a customization input file to provide even greater freedom and |
| 407 | simplicity in selecting the desired layout. |
| 408 | .PP |
| 409 | There is no support for backing store and save unders, but this should also be |
| 410 | considered. |
| 411 | .PP |
| 412 | .\" Is the following still true now that client-side font rendering is |
| 413 | .\" considered the way to go? |
| 414 | The proper implementation of fonts should be moved into the |
| 415 | .I os |
| 416 | layer. |
| 417 | .SH BUGS |
| 418 | Doesn't run well on servers supporting different visual depths. |
| 419 | .PP |
| 420 | Still crashes randomly. |
| 421 | .PP |
| 422 | Probably has some memory leaks. |
| 423 | .SH AUTHOR |
| 424 | Davor Matic, MIT X Consortium |
| 425 | .SH "SEE ALSO" |
| 426 | .BR Xserver (__appmansuffix__), |
| 427 | .BR xdpyinfo (__appmansuffix__), |
| 428 | .BR X (__miscmansuffix__) |