Provided by: libggi-target-x_2.2.1-5ubuntu1_i386 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.

       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