Provided by: libggi-target-x_2.2.2-5ubuntu2_amd64 bug

NAME

       display-x - Displays to an X11 server

SYNOPSIS

       display-x: [ [-inwin=<winid>|root] | [-screen=<screenidx>] ]
                  [-fullscreen] [-keepcursor] [-noaccel] [-nobuffer]
                  [-nocursor] [-nodbe] [-nodga] [-noevi] [-noinput]
                  [-nomansync] [-noshm] [-novidmode] [-physz=<sizex>,<sizey>[dpi]]
                  [<display>]

DESCRIPTION

       display-x  displays  a  GGI  application  via  an  X11 server.  The server may be local or
       remote, and options are provided to tune performance  to  various  scenerios.   In  normal
       operation,  a  new X11 window is opened, solid fill primitives and copybox are accelerated
       by the server, and a backbuffer is  kept  client-side  for  content  fills  (e.g.  ggiPut*
       functions)  and to restore data when an application has been exposed after being concealed
       by another window.

       Ctrl-Alt-m toggles mouse grabbing in the new window.  It will try to  emulate  a  relative
       mouse  device,  i.e.  one  that can be moved arbitrarily far in any direction without ever
       leaving the window.  This is useful for game controls, where loosing  focus  is  generally
       undesireable.  Note that grabbing must be turned off in order to leave the window.

OPTIONS

       display
              The  X  display  to  connect  to,  otherwise  defaults  to the display specified in
              DISPLAY.

       -fullscreen
              Turns on the fullscreen mode. Default mode is the  windowed  mode.   In  fullscreen
              mode,  the  dga  helper is tried first if not disabled by -nodga or failed for some
              reason. Then the vidmode helper is tried. When this fails, then  the  target  falls
              back to the windowed mode. Note, the -inwin option has no effect with fullscreen.

       -noaccel
              All  rendering  is  performed  in  the client-side backbuffer, and then sent to the
              server; no  server-side  accelerated  graphics  operations  are  used.   This  will
              signifigantly  slow  down  certain graphics applications, but for applications that
              use  directbuffer  and  asyncronous  mode  extensively  the  effect  will  not   be
              noticeable.   The  only  real  reason  to use this option, however, is to eliminate
              artifacts caused by incorrectly implemented X11 hardware drivers.

       -nobuffer
              No client-side backbuffer is kept.  This may result in lost data  when  the  LibGGI
              application  is  obscured  by  other  windows.   This data loss can be minimized by
              enabling backing store in the X11 server.  Using this option will cause  operations
              which  must read back framebuffer data to be much slower, but on the other hand can
              result in a slight speed gain for certain graphics primitives.   It  is  best  used
              when  resources are severely limited on the client side, and with applications that
              do not perform frequent ggiPut* operations.  Note, with this option evExpose events
              are passed to the application (Otherwise, they are internally grabbed to update the
              backbuffer).

       -nodbe Use of the X11 DBE extension to provide buffered frame support is disabled.
              Note: Currently DBE extension support has not been completed.

       -nodga Use of the XFree86-DGA extension to provide direct framebuffer access is  disabled.
              Some  implementations  of  the XFree86-DGA extension may cause system lockups.  Use
              this option to prevent such occurrances.

       -noevi Use of the X11 Extended Visual Information extension to identify visuals which  are
              exclusively used for overlay/underlay is disabled.

       -noinput
              X events sent to the window are not captured and merged with any other LibGII input
              sources.  This allows  one  to  take  input  from  raw  devices  without  receiving
              duplicate events should X also be configured to use the device.

       -nocursor, -keepcursor
              Normal  behavior of display-x is to create a small dot mouse cursor pixmap which is
              visible when the mouse is positioned over the window containing the  visual.   This
              goes  away  when  using mouse grabbing as described above, but otherwise can get in
              the way of mouse cursors implemented by the application.  With the  former  option,
              the  X  mouse cursor will be invisible when it is over the visual, with the latter,
              the cursor from the root window is used unaltered.  If both options  are  supplied,
              the latter takes precedence.

       -nomansync
              Use  of the mansync helper library to periodically flush backbuffer contents to the
              X11 server is disabled.  This, of course, will  result  in  incorrect  behavior  of
              applications that use syncronous mode.

       -noshm Use  of  the  MIT-SHM  extension to speed data transfer between clients and servers
              which are running on the same machine is disabled.  Normally it is not necessary to
              use  this  option,  as use of the MIT-SHM extension is disabled automatically if it
              appears to be nonfunctional.

       -inwin=<winid>|root
              Run in already-existing window with id winid.  This can be used to embed  a  LibGGI
              application  into  an  X11  application.   The  value  should  be  an X11 window ID
              expressed as a "0x" prefixed hexadecimal number.  The special  string  "root"  will
              cause  the  application  to  run  in the root window of the selected screen (or the
              default screen if no explicit selection has been made.)   Note  that  in  the  root
              window, you may need to explicitly select a LibGII input source using the GGI_INPUT
              environment variable as the window manager will absorb all events sent to the  root
              window.   Some  features  (currently frames and virtual areas) may not work in root
              windows.  On the other hand, when using the root window other features like  direct
              framebuffer access and video hardware mode selection may be available which are not
              available when the application is running in a normal window.

       -novidmode
              Use of the X11 Vidmode extension to change video timing  in  full-screen  modes  is
              disabled.   Some implementations of the Vidmode extension may cause system lockups.
              Use this option to prevent such occurrances.

       -physz=<sizex>,<sizey>[dpi]
              This option will override the physical screen size reported by the X server,  which
              affects  applications  which wish to remain resolution independent.  sizex,:p:sizey
              are the x,y size of the entire screen (not just the X window containing the visual)
              in  millimeters,  unless  the  optional  dpi string is affixed, in which case, they
              represent resolution in dots-per-inch. Yes, there are two equals signs  there,  for
              reasons of compatibility with other targets.

       -screen=<screenidx>
              The  screen  to  run  on.   Normally the biggest/deepest screen compatible with the
              requested mode will be chosen; with  this  option  only  the  screen  specified  by
              screenidx will be considered.

CLIFF NOTES ON NEW X TARGET

       The  old  X target rendered all primitives in a RAM backbuffer, and then copied the entire
       backbuffer periodically using the mansync helper to the X screen.  This caused  a  lot  of
       wasted  bandwidth.   However,  since  the  bandwidth  was  being wasted anyway, LibGGIMISC
       splitline support was a simple hack that added nearly no complexity.

       The old Xlib target had no RAM backbuffer and rendered all primitives  using  Xlib  calls.
       This  caused very slow performance when a lot of individual pixels were being drawn one at
       a time, and slow performance on operations which got pixel  data  back  from  the  visual,
       since  it  had  to  be  fetched  back  over the wire.  Also, this precluded the use of the
       directbuffer on the xlib target.

       The new X target in its default mode maintains both a RAM backbuffer on the  client  side,
       and uses Xlib primitives to draw on the server side.  When a primitive, such as a drawbox,
       can use an Xlib function, the command is dispatched to the X server and the  data  in  the
       RAM  buffer  is updated using a software renderer.  For operations such as putbox, the RAM
       buffer is updated first, and the synced to the X server.  Unlike the old target,  the  new
       target  keeps  track  of  a "dirty region" and only syncs the area affected since the last
       time a syncronization occured.   This  dirty-region  tracking  only  keeps  track  of  one
       rectangular  dirty  area.   A  helper  library that keeps track of more than one rectangle
       could be implemented to improve performance of display-X and any other similarly  designed
       display  target.   To  be  most  flexible  such  a  target should take weighted parameters
       representing the cost of transferring data (per byte) from the backbuffer,  and  the  per-
       operation  cost  of  initiating  such a transfer, which would alter its strategy as to how
       many regions are maintained and how much they overlap.

       The old X target's RAM buffer was implemented using the X target's drawops hooks  --  that
       is,  the  RAM  buffer was essentially a re-implementation of display-memory with the extra
       facilities to sync to the  X  server  built  in.   The  new  target  capitalizes  on  some
       improvements made in display-memory, and instead it opens and loads a child display-memory
       visual which takes care of finding software  renderers  for  the  RAM  buffer.   The  main
       drawops  of  the  new  target  dispatch  the  the  X  server commands and call the child's
       corresponsing software drawops to ensure consistant state of  the  RAM  buffer  vs  the  X
       window.   This must be done such that any requests to get data from the RAM backbuffer are
       not processed until the RAM backbuffer is up to date, and any flushes from the  backbuffer
       are  not processed until the backbuffer is up to date.  There's a lot of locking intracacy
       to ensure this level of consistancy.

       The basic syncronization operation is accomplished by the flush  function,  which  is  the
       function loaded on the xpriv flush member hook.  The flush hook function is called:

       1   When the mansync helper decides it is time to refresh the screen.

       2   After a primitive, if the visual is in syncronous rendering mode.

       3   When an expose or graphicsexpose event is sent from the server.  This means the server
           has discarded data that was concealed by another window or by the edge of the  screen,
           and the data must be resent from the client.

       In  the  last  case the whole area that must be refreshed is sent again by the client.  In
       the first two cases only the dirty area is sent, except when the  application  is  holding
       the  directbuffer  writing  resource,  in which case the whole area must be synced because
       there is no way for  the  target  to  tell  what  the  user  has  modified.   Holding  the
       directbuffer  write  resource  open  when  the  display is in syncronous mode or when also
       sending primitives will result in bad perfomance.  There's no  reason  to  do  so  on  any
       target, so don't.

       Unfortunately some XFree86 drivers are buggy, and when you render an accelerated primitive
       which overlaps an area which is not visible to the user, the driver fails  to  update  the
       backing  store  (it  only draws the clipped primitive using accelarated functions and does
       not complete the job by calling the software renderer to update the backing store.)   Most
       people will not be affected by this bug, however.

       The new X target implements gammamap (DirectColor), unlike the old targets.

       The  new  X  target is best used with backing store turned on in the server.  When backing
       store is not turned on, primitives which are clipped to the visual area but still  in  the
       virtual  area  may  be  slower  then the old target, since data will be sent to the server
       hoping it will be stored in the backing store.  Likewise when a full-screen flush  occurrs
       the entire virtual area data is sent.  The target could be optimized not to send this data
       when it detects that there is no backing store available in the server.

       Either the RAM backbuffer or the X primitives can be disabled via  target  options,  which
       will  cause  emulation of the old X (-noaccel) and Xlib (-nobuffer) targets, with a couple
       of notable exceptions:
              The old X and Xlib targets opened a window and drew directly into it.  The old Xlib
              target did not implement support for ggiSetOrigin.  As noted above the old X target
              used a hack that didn't cost  much  when  compared  to  the  cost  of  syncing  the
              backbuffer  periodically.   The  new  target  implements ggiSetOrigin by creating a
              parent window, then creating a child window inside the  parent  window.   Thus  the
              child  window  can  be moved around inside the parent window, and the parent window
              will clip the displayed data to the right size.  This is much more  efficient  than
              the old way when the server is keeping a backing store (which it sometimes does "in
              secret" even when the backing store functionality in the server is turned off.)
       Unfortunately many window managers seem to be buggy, and do not install the colormap of  a
       child  window  when  a mouse enters it.  This causes palette and gammamap to be messed up.
       Since so many windowmanagers  fail  to  implement  the  behavior  described  in  the  Xlib
       manpages, a workaround needs to be added which will not use the child window (this part is
       easy enough since the -inwin=root option already implements a  child-less  rendering)  and
       either  disables  ggiSetOrigin  support,  or  uses  a  better version of the old display-x
       target's creative blitting to emulate setorigin support.

       LibGGIMISC's splitline support for the original X display was broken  by  the  new  child-
       window  stuff as well.  In order to implement splitline support, libggimisc must implement
       a new set of primitives for the new display X that uses two child windows to  produce  the
       splitline  effect.  This complicates a lot of the primitives, so the code is best isolated
       in LibGGIMISC so any bugs or performance issues in it do not affect vanilla  LibGGI  users
       who  have  no need for splitline.  It would probably be best if the special renderers were
       only loaded on the first call to  ggiSetSplitline,  so  that  when  LibGGIMISC  implements
       support  for  the  XSync  extension,  users  who  are  not  using  splitline  do not pay a
       performance penalty for using XSync.

       The child window may also be to blame for the fact that a window which is focused, but not
       moused  over,  stops receiving keyboard events.  Reworking the X input target to take it's
       keyboard  events  from  the  parent  window  instead  of  the  child  window  (mouse   and
       expose/graphicsexpose  events  must  still come from the child window) would be the needed
       fix.

       The new target tries to remove dl dependencies by creating a separate module file for  any
       X  extensions  used.  Because of some deficiencies in the X module system (there is no way
       to cleanly unload a module) some kludges have had to be made when a module is  loaded  but
       gleaned to be nonpresent, then unloaded.  This won't effect most people.

       However,  a  more  common  problem  will  be  seen  because  X does not give us any way to
       determine if the XSHM extension will work -- it tells us whether the server has XSHM,  but
       it  does  not tell us whether the client and server can share memory segments.  Thus, when
       running a remote client, it may be necessary to manually disable  XSHM  support  with  the
       -noshm target option.

       Anyway,  I hope this is helpful to any intrepid soul which decides to fondle this code :-)
       (Brian S. Julin)

FEATURES

       ·   DirectBuffer always available.

       ·   Accelerated

       ·   Multiple frames except for root window

       ·   Panning except for root window

       ·   Support Gammamap