display-x

Section: GGI (7)
Updated: 2005-04-11
Page Index

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