Add generic rootless layer documentation missed from last commit.
This commit is contained in:
Torrey Lyons
parent
784e4d1cc0
commit
29012adb37
|
|
@ -0,0 +1,403 @@
|
||||||
|
Generic Rootless Layer
|
||||||
|
Version 1.0
|
||||||
|
July 13, 2004
|
||||||
|
|
||||||
|
Torrey T. Lyons
|
||||||
|
torrey@xfree86.org
|
||||||
|
|
||||||
|
|
||||||
|
Introduction
|
||||||
|
|
||||||
|
The generic rootless layer allows an X server to be implemented
|
||||||
|
on top of another window server in a cooperative manner. This allows the
|
||||||
|
X11 windows and native windows of the underlying window server to
|
||||||
|
coexist on the same screen. The layer is called "rootless" because the root
|
||||||
|
window of the X server is generally not drawn. Instead, each top-level
|
||||||
|
child of the root window is represented as a separate on-screen window by
|
||||||
|
the underlying window server. The layer is referred to as "generic"
|
||||||
|
because it abstracts away the details of the underlying window system and
|
||||||
|
contains code that is useful for any rootless X server. The code for the
|
||||||
|
generic rootless layer is located in xc/programs/Xserver/miext/rootless. To
|
||||||
|
build a complete rootless X server requires a specific rootless
|
||||||
|
implementation, which provides functions that allow the generic rootless
|
||||||
|
layer to interact with the underlying window system.
|
||||||
|
|
||||||
|
|
||||||
|
Concepts
|
||||||
|
|
||||||
|
In the context of a rootless X server the term window is used to
|
||||||
|
mean many fundamentally different things. For X11 a window is a DDX
|
||||||
|
resource that describes a visible, or potentially visible, rectangle on the
|
||||||
|
screen. A top-level window is a direct child of the root window. To avoid
|
||||||
|
confusion, an on-screen native window of the underlying window system
|
||||||
|
is referred to as a "frame". The generic rootless layer associates each
|
||||||
|
mapped top-level X11 window with a frame. An X11 window may be said
|
||||||
|
to be "framed" if it or its top-level parent is represented by a frame.
|
||||||
|
|
||||||
|
The generic rootless layer models each frame as being backed at
|
||||||
|
all times by a backing buffer, which is periodically flushed to the screen.
|
||||||
|
If the underlying window system does not provide a backing buffer for
|
||||||
|
frames, this must be done by the rootless implementation. The generic
|
||||||
|
rootless layer model does not assume it always has access to the frames'
|
||||||
|
backing buffers. Any drawing to the buffer will be proceeded by a call to
|
||||||
|
the rootless implementation's StartDrawing() function and StopDrawing()
|
||||||
|
will be called when the drawing is concluded. The address of the frame's
|
||||||
|
backing buffer is returned by the StartDrawing() function and it can
|
||||||
|
change between successive calls.
|
||||||
|
|
||||||
|
Because each frame is assumed to have a backing buffer, the
|
||||||
|
generic rootless layer will stop Expose events being generated when the
|
||||||
|
regions of visibility of a frame change on screen. This is similar to backing
|
||||||
|
store, but backing buffers are different in that they always store a copy of
|
||||||
|
the entire window contents, not just the obscured portions. The price paid
|
||||||
|
in increased memory consumption is made up by the greatly decreased
|
||||||
|
complexity in not having to track and record regions as they are obscured.
|
||||||
|
|
||||||
|
|
||||||
|
Rootless Implementation
|
||||||
|
|
||||||
|
The specifics of the underlying window system are provided to the
|
||||||
|
generic rootless layer through rootless implementation functions, compile-
|
||||||
|
time options, and runtime parameters. The rootless implementation
|
||||||
|
functions are a list of functions that allow the generic rootless layer to
|
||||||
|
perform operations such as creating, destroying, moving, and resizing
|
||||||
|
frames. Some of the implementation functions are optional. A detailed
|
||||||
|
description of the rootless implementation functions is provided in
|
||||||
|
Appendix A.
|
||||||
|
|
||||||
|
By design, a rootless implementation should only have to include
|
||||||
|
the rootless.h header file. The rootlessCommon.h file contains definitions
|
||||||
|
internal to the generic rootless layer. (If you find you need to use
|
||||||
|
rootlessCommon.h in your implementation, let the generic rootless layer
|
||||||
|
maintainers know. This could be an area where the generic rootless layer
|
||||||
|
should be generalized.) A rootless implementation should also modify
|
||||||
|
rootlessConfig.h to specify compile time options for its platform.
|
||||||
|
|
||||||
|
The following compile-time options are defined in
|
||||||
|
rootlessConfig.h:
|
||||||
|
|
||||||
|
o ROOTLESS_ACCEL: If true, use the optional rootless acceleration
|
||||||
|
functions where possible to a accelerate X11 drawing primitives.
|
||||||
|
If false, all drawing will be done with fb.
|
||||||
|
|
||||||
|
o ROOTLESS_GLOBAL_COORDS: This option controls the way that frame
|
||||||
|
coordinates are passed to the rootless implementation. If false,
|
||||||
|
the coordinates are passed per screen relative to the origin of
|
||||||
|
the screen the frame is currently on. Some implementations may
|
||||||
|
prefer to work in a single global coordinate space that spans all
|
||||||
|
screens. If this option is true, the coordinates are passed after
|
||||||
|
adding the coordinates of the screen origin and an overall offset of
|
||||||
|
(rootlessGlobalOffsetX, rootlessGlobalOffsetY).
|
||||||
|
|
||||||
|
o ROOTLESS_PROTECT_ALPHA: By default for a color bit depth of 24 and
|
||||||
|
32 bits per pixel, fb will overwrite the "unused" 8 bits to optimize
|
||||||
|
drawing speed. If this is true, the alpha channel of frames is
|
||||||
|
protected and is not modified when drawing to them. The bits
|
||||||
|
containing the alpha channel are defined by the macro
|
||||||
|
RootlessAlphaMask(bpp), which should return a bit mask for
|
||||||
|
various bits per pixel.
|
||||||
|
|
||||||
|
o ROOTLESS_REDISPLAY_DELAY: Time in milliseconds between updates to
|
||||||
|
the underlying window server. Most operations will be buffered until
|
||||||
|
this time has expired.
|
||||||
|
|
||||||
|
o ROOTLESS_RESIZE_GRAVITY: If the underlying window system supports it,
|
||||||
|
some frame resizes can be optimized by relying on the frame contents
|
||||||
|
maintaining a particular gravity during the resize. In this way less
|
||||||
|
of the frame contents need to be preserved by the generic rootless
|
||||||
|
layer. If true, the generic rootless layer will pass gravity hints
|
||||||
|
during resizing and rely on the frame contents being preserved
|
||||||
|
accordingly.
|
||||||
|
|
||||||
|
o ROOTLESS_TRACK_DAMAGE: The generic rootless layer draws to the
|
||||||
|
frames' backing buffers and periodically flushes the modified
|
||||||
|
regions to the underlying window server. If this option is true,
|
||||||
|
the generic rootless layer will track these damaged regions.
|
||||||
|
Currently it uses the miRegion code and will not simplify damaged
|
||||||
|
regions even when updating a bounding region would be more
|
||||||
|
efficient. Some window systems provide a more efficient way to
|
||||||
|
track damaged regions. If this option is false, the rootless
|
||||||
|
implementation function DamageRects() is called whenever a
|
||||||
|
backing buffer is modified and the rootless implementation is
|
||||||
|
expected to track the damaged regions itself.
|
||||||
|
|
||||||
|
The following runtime options are defined in rootless.h:
|
||||||
|
|
||||||
|
o rootlessGlobalOffsetX, rootlessGlobalOffsetY: These are only
|
||||||
|
used if ROOTLESS_GLOBAL_COORDS is true. They specify the global
|
||||||
|
offset that is applied to all screens when converting from
|
||||||
|
screen-local to global coordinates.
|
||||||
|
|
||||||
|
o rootless_CopyBytes_threshold, rootless_FillBytes_threshold,
|
||||||
|
rootless_CompositePixels_threshold, rootless_CopyWindow_threshold:
|
||||||
|
The minimum number of bytes or pixels for which to use the rootless
|
||||||
|
implementation's respective acceleration function. The rootless
|
||||||
|
acceleration functions are all optional so these will only be used
|
||||||
|
if the respective acceleration function pointer is not NULL.
|
||||||
|
|
||||||
|
|
||||||
|
Accelerated Drawing
|
||||||
|
|
||||||
|
The rootless implementation typically does not have direct access
|
||||||
|
to the hardware. Its access to the graphics hardware is generally through
|
||||||
|
the API of the underlying window system. This underlying API may not
|
||||||
|
overlap well with the X11 drawing primitives. The generic rootless layer
|
||||||
|
falls back to using fb for all its 2-D drawing. Providing optional rootless
|
||||||
|
implementation acceleration functions can accelerate some graphics
|
||||||
|
primitives and some window functions. Typically calling through to the
|
||||||
|
underlying window systems API will not speed up these operations for
|
||||||
|
small enough areas. The rootless_*_threshold runtime options allow the
|
||||||
|
rootless implementation to provide hints for when the acceleration
|
||||||
|
functions should be used instead of fb.
|
||||||
|
|
||||||
|
|
||||||
|
Alpha Channel Protection
|
||||||
|
|
||||||
|
If the bits per pixel is greater then the color bit depth, the contents
|
||||||
|
of the extra bits are undefined by the X11 protocol. Some window systems
|
||||||
|
will use these extra bits as an alpha channel. The generic rootless layer can
|
||||||
|
be configured to protect these bits and make sure they are not modified by
|
||||||
|
other parts of the X server. To protect the alpha channel
|
||||||
|
ROOTLESS_PROTECT_ALPHA and RootlessAlphaMask(bpp) must be
|
||||||
|
set appropriately as described under the compile time options. This
|
||||||
|
ensures that the X11 graphics primitives do not overwrite the alpha
|
||||||
|
channel in an attempt to optimize drawing. In addition, the window
|
||||||
|
functions PaintWindow() and Composite() must be replaced by alpha
|
||||||
|
channel safe variants. These are provided in rootless/safeAlpha.
|
||||||
|
|
||||||
|
|
||||||
|
Credits
|
||||||
|
|
||||||
|
The generic rootless layer was originally conceived and developed
|
||||||
|
by Greg Parker as part of the XDarwin X server on Mac OS X. John
|
||||||
|
Harper made later optimizations to this code but removed its generic
|
||||||
|
independence of the underlying window system. Torrey T. Lyons
|
||||||
|
reintroduced the generic abstractions and made the rootless code suitable
|
||||||
|
for use by other X servers.
|
||||||
|
|
||||||
|
|
||||||
|
Appendix A: Rootless Implementation Functions
|
||||||
|
|
||||||
|
The rootless implementation functions are defined in rootless.h. It
|
||||||
|
is intended that rootless.h contains the complete interface that is needed by
|
||||||
|
rootless implementations. The definitions contained in rootlessCommon.h
|
||||||
|
are intended for internal use by the generic rootless layer and are more
|
||||||
|
likely to change.
|
||||||
|
|
||||||
|
Most of these functions take a RootlessFrameID as a parameter.
|
||||||
|
The RootlessFrameID is an opaque object that is returned by the
|
||||||
|
implementation's CreateFrame() function. The generic rootless layer does
|
||||||
|
not use this frame id other than to pass it back to the rootless
|
||||||
|
implementation to indicate the frame to operate on.
|
||||||
|
|
||||||
|
/*
|
||||||
|
* Create a new frame.
|
||||||
|
* The frame is created unmapped.
|
||||||
|
*
|
||||||
|
* pFrame RootlessWindowPtr for this frame should be completely
|
||||||
|
* initialized before calling except for pFrame->wid, which
|
||||||
|
* is set by this function.
|
||||||
|
* pScreen Screen on which to place the new frame
|
||||||
|
* newX, newY Position of the frame. These will be identical to pFrame-x,
|
||||||
|
* pFrame->y unless ROOTLESS_GLOBAL_COORDS is set.
|
||||||
|
* pNewShape Shape for the frame (in frame-local coordinates). NULL for
|
||||||
|
* unshaped frames.
|
||||||
|
*/
|
||||||
|
typedef Bool (*RootlessCreateFrameProc)
|
||||||
|
(RootlessWindowPtr pFrame, ScreenPtr pScreen, int newX, int newY,
|
||||||
|
RegionPtr pNewShape);
|
||||||
|
|
||||||
|
/*
|
||||||
|
* Destroy a frame.
|
||||||
|
* Drawing is stopped and all updates are flushed before this is called.
|
||||||
|
*
|
||||||
|
* wid Frame id
|
||||||
|
*/
|
||||||
|
typedef void (*RootlessDestroyFrameProc)
|
||||||
|
(RootlessFrameID wid);
|
||||||
|
|
||||||
|
/*
|
||||||
|
* Move a frame on screen.
|
||||||
|
* Drawing is stopped and all updates are flushed before this is called.
|
||||||
|
*
|
||||||
|
* wid Frame id
|
||||||
|
* pScreen Screen to move the new frame to
|
||||||
|
* newX, newY New position of the frame
|
||||||
|
*/
|
||||||
|
typedef void (*RootlessMoveFrameProc)
|
||||||
|
(RootlessFrameID wid, ScreenPtr pScreen, int newX, int newY);
|
||||||
|
|
||||||
|
/*
|
||||||
|
* Resize and move a frame.
|
||||||
|
* Drawing is stopped and all updates are flushed before this is called.
|
||||||
|
*
|
||||||
|
* wid Frame id
|
||||||
|
* pScreen Screen to move the new frame to
|
||||||
|
* newX, newY New position of the frame
|
||||||
|
* newW, newH New size of the frame
|
||||||
|
* gravity Gravity for window contents (rl_gravity_enum). This is always
|
||||||
|
* RL_GRAVITY_NONE unless ROOTLESS_RESIZE_GRAVITY is set.
|
||||||
|
*/
|
||||||
|
typedef void (*RootlessResizeFrameProc)
|
||||||
|
(RootlessFrameID wid, ScreenPtr pScreen,
|
||||||
|
int newX, int newY, unsigned int newW, unsigned int newH,
|
||||||
|
unsigned int gravity);
|
||||||
|
|
||||||
|
/*
|
||||||
|
* Change frame ordering (AKA stacking, layering).
|
||||||
|
* Drawing is stopped before this is called. Unmapped frames are mapped by
|
||||||
|
* setting their ordering.
|
||||||
|
*
|
||||||
|
* wid Frame id
|
||||||
|
* nextWid Frame id of frame that is now above this one or NULL if this
|
||||||
|
* frame is at the top.
|
||||||
|
*/
|
||||||
|
typedef void (*RootlessRestackFrameProc)
|
||||||
|
(RootlessFrameID wid, RootlessFrameID nextWid);
|
||||||
|
|
||||||
|
/*
|
||||||
|
* Change frame's shape.
|
||||||
|
* Drawing is stopped before this is called.
|
||||||
|
*
|
||||||
|
* wid Frame id
|
||||||
|
* pNewShape New shape for the frame (in frame-local coordinates)
|
||||||
|
* or NULL if now unshaped.
|
||||||
|
*/
|
||||||
|
typedef void (*RootlessReshapeFrameProc)
|
||||||
|
(RootlessFrameID wid, RegionPtr pNewShape);
|
||||||
|
|
||||||
|
/*
|
||||||
|
* Unmap a frame.
|
||||||
|
*
|
||||||
|
* wid Frame id
|
||||||
|
*/
|
||||||
|
typedef void (*RootlessUnmapFrameProc)
|
||||||
|
(RootlessFrameID wid);
|
||||||
|
|
||||||
|
/*
|
||||||
|
* Start drawing to a frame.
|
||||||
|
* Prepare a frame for direct access to its backing buffer.
|
||||||
|
*
|
||||||
|
* wid Frame id
|
||||||
|
* pixelData Address of the backing buffer (returned)
|
||||||
|
* bytesPerRow Width in bytes of the backing buffer (returned)
|
||||||
|
*/
|
||||||
|
typedef void (*RootlessStartDrawingProc)
|
||||||
|
(RootlessFrameID wid, char **pixelData, int *bytesPerRow);
|
||||||
|
|
||||||
|
/*
|
||||||
|
* Stop drawing to a frame.
|
||||||
|
* No drawing to the frame's backing buffer will occur until drawing
|
||||||
|
* is started again.
|
||||||
|
*
|
||||||
|
* wid Frame id
|
||||||
|
* flush Flush drawing updates for this frame to the screen. This
|
||||||
|
* will always be FALSE if ROOTLESS_TRACK_DAMAGE is set.
|
||||||
|
*/
|
||||||
|
typedef void (*RootlessStopDrawingProc)
|
||||||
|
(RootlessFrameID wid, Bool flush);
|
||||||
|
|
||||||
|
/*
|
||||||
|
* Flush drawing updates to the screen.
|
||||||
|
* Drawing is stopped before this is called.
|
||||||
|
*
|
||||||
|
* wid Frame id
|
||||||
|
* pDamage Region containing all the changed pixels in frame-local
|
||||||
|
* coordinates. This is clipped to the window's clip. This
|
||||||
|
* will be NULL if ROOTLESS_TRACK_DAMAGE is not set.
|
||||||
|
*/
|
||||||
|
typedef void (*RootlessUpdateRegionProc)
|
||||||
|
(RootlessFrameID wid, RegionPtr pDamage);
|
||||||
|
|
||||||
|
/*
|
||||||
|
* Mark damaged rectangles as requiring redisplay to screen.
|
||||||
|
* This will only be called if ROOTLESS_TRACK_DAMAGE is not set.
|
||||||
|
*
|
||||||
|
* wid Frame id
|
||||||
|
* nrects Number of damaged rectangles
|
||||||
|
* rects Array of damaged rectangles in frame-local coordinates
|
||||||
|
* shift_x, Vector to shift rectangles by
|
||||||
|
* shift_y
|
||||||
|
*/
|
||||||
|
typedef void (*RootlessDamageRectsProc)
|
||||||
|
(RootlessFrameID wid, int nrects, const BoxRec *rects,
|
||||||
|
int shift_x, int shift_y);
|
||||||
|
|
||||||
|
/*
|
||||||
|
* Switch the window associated with a frame. (Optional)
|
||||||
|
* When a framed window is reparented, the frame is resized and set to
|
||||||
|
* use the new top-level parent. If defined this function will be called
|
||||||
|
* afterwards for implementation specific bookkeeping.
|
||||||
|
*
|
||||||
|
* pFrame Frame whose window has switched
|
||||||
|
* oldWin Previous window wrapped by this frame
|
||||||
|
*/
|
||||||
|
typedef void (*RootlessSwitchWindowProc)
|
||||||
|
(RootlessWindowPtr pFrame, WindowPtr oldWin);
|
||||||
|
|
||||||
|
/*
|
||||||
|
* Copy bytes. (Optional)
|
||||||
|
* Source and destinate may overlap and the right thing should happen.
|
||||||
|
*
|
||||||
|
* width Bytes to copy per row
|
||||||
|
* height Number of rows
|
||||||
|
* src Source data
|
||||||
|
* srcRowBytes Width of source in bytes
|
||||||
|
* dst Destination data
|
||||||
|
* dstRowBytes Width of destination in bytes
|
||||||
|
*/
|
||||||
|
typedef void (*RootlessCopyBytesProc)
|
||||||
|
(unsigned int width, unsigned int height,
|
||||||
|
const void *src, unsigned int srcRowBytes,
|
||||||
|
void *dst, unsigned int dstRowBytes);
|
||||||
|
|
||||||
|
/*
|
||||||
|
* Fill memory with 32-bit pattern. (Optional)
|
||||||
|
*
|
||||||
|
* width Bytes to fill per row
|
||||||
|
* height Number of rows
|
||||||
|
* value 32-bit pattern to fill with
|
||||||
|
* dst Destination data
|
||||||
|
* dstRowBytes Width of destination in bytes
|
||||||
|
*/
|
||||||
|
typedef void (*RootlessFillBytesProc)
|
||||||
|
(unsigned int width, unsigned int height, unsigned int value,
|
||||||
|
void *dst, unsigned int dstRowBytes);
|
||||||
|
|
||||||
|
/*
|
||||||
|
* Composite pixels from source and mask to destination. (Optional)
|
||||||
|
*
|
||||||
|
* width, height Size of area to composite to in pizels
|
||||||
|
* function Composite function built with RL_COMPOSITE_FUNCTION
|
||||||
|
* src Source data
|
||||||
|
* srcRowBytes Width of source in bytes (Passing NULL means source
|
||||||
|
* is a single pixel.
|
||||||
|
* mask Mask data
|
||||||
|
* maskRowBytes Width of mask in bytes
|
||||||
|
* dst Destination data
|
||||||
|
* dstRowBytes Width of destination in bytes
|
||||||
|
*
|
||||||
|
* For src and dst, the first element of the array is the color data. If
|
||||||
|
* the second element is non-null it implies there is alpha data (which
|
||||||
|
* may be meshed or planar). Data without alpha is assumed to be opaque.
|
||||||
|
*
|
||||||
|
* An X11 error code is returned.
|
||||||
|
*/
|
||||||
|
typedef int (*RootlessCompositePixelsProc)
|
||||||
|
(unsigned int width, unsigned int height, unsigned int function,
|
||||||
|
void *src[2], unsigned int srcRowBytes[2],
|
||||||
|
void *mask, unsigned int maskRowBytes,
|
||||||
|
void *dst[2], unsigned int dstRowBytes[2]);
|
||||||
|
|
||||||
|
/*
|
||||||
|
* Copy area in frame to another part of frame. (Optional)
|
||||||
|
*
|
||||||
|
* wid Frame id
|
||||||
|
* dstNrects Number of rectangles to copy
|
||||||
|
* dstRects Array of rectangles to copy
|
||||||
|
* dx, dy Number of pixels away to copy area
|
||||||
|
*/
|
||||||
|
typedef void (*RootlessCopyWindowProc)
|
||||||
|
(RootlessFrameID wid, int dstNrects, const BoxRec *dstRects,
|
||||||
|
int dx, int dy);
|
||||||
|
|
||||||
Loading…
Reference in New Issue