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