display-x man page on Mandriva

Man page or keyword search:  
man Server   17060 pages
apropos Keyword Search (all sections)
Output format
Mandriva logo
[printable version]

display-x(7)			      GGI			  display-x(7)

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* func‐
       tions) 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 dis‐
	      abled 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  direct‐
	      buffer  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 primi‐
	      tives.  It is best used when resources are severely  limited  on
	      the  client side, and with applications that do not perform fre‐
	      quent ggiPut*  operations.   Note,  with	this  option  evExpose
	      events are passed to the application (Otherwise, they are inter‐
	      nally 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 dis‐
	      abled.

       -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 cur‐
	      sor 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 win‐
	      dow is used unaltered.  If both options are supplied, the latter
	      takes precedence.

       -nomansync
	      Use  of  the  mansync helper library to periodically flush back‐
	      buffer contents to the X11 server is disabled.  This, of course,
	      will  result in incorrect behavior of applications that use syn‐
	      cronous 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 com‐
	      patible 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 com‐
       mand  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 ini‐
       tiating 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 dra‐
       wops hooks -- that is, the RAM buffer was essentially a	re-implementa‐
       tion  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-mem‐
       ory 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 pro‐
       cessed 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 func‐
       tion, 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 tar‐
       gets.

       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	 back‐
       ing store available in the server.

       Either  the RAM backbuffer or the X primitives can be disabled via tar‐
       get 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	 back‐
	      buffer  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 work‐
       around 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 emu‐
       late 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 perfor‐
       mance 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 par‐
       ent 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

libggi-2.2.x			  2005-04-11			  display-x(7)
[top]

List of man pages available for Mandriva

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net