hw/xnest/man/Xnest.man

   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__)