191 lines
6.1 KiB
Plaintext
191 lines
6.1 KiB
Plaintext
The DAMAGE Extension
|
|
Protocol Version 0.0
|
|
Document Revision 1
|
|
2003-11-03
|
|
|
|
Keith Packard
|
|
keithp@keithp.com
|
|
|
|
1. Introduction
|
|
|
|
Monitoring the regions affected by rendering has wide-spread use, from
|
|
VNC-like systems scraping the screen to screen magnifying applications
|
|
designed to aid users with limited visual acuity. The DAMAGE extension is
|
|
designed to make such applications reasonably efficient in the face of
|
|
server-client latency.
|
|
|
|
2. Acknolwedgements
|
|
|
|
As usual, the author had significant input from many people, in particular:
|
|
|
|
+ Havoc Pennington who designed and implemented a Damage extension
|
|
last year which was then lost to the mists of time.
|
|
|
|
+ Bill Haneman whose work on accessibility in the Gnome environment
|
|
is legendary.
|
|
|
|
+ Jim Gettys who found a way to avoid streaming damage rectangles
|
|
to the client in many cases.
|
|
|
|
+ Owen Taylor who suggested that streaming damage rectangles may
|
|
be warranted in some cases after all.
|
|
|
|
3. Damage Model
|
|
|
|
We call changes made to pixel contents of windows and pixmaps 'damage'
|
|
throughout this extension. Another notion of 'damage' are drawable regions
|
|
which are in need of redisplay to repair the effects of window manipulation
|
|
or other data loss. This extension doesn't deal with this second notion at
|
|
all; suggestions on a better term which isn't easily conflated with existing
|
|
notions are eagerly solicited.
|
|
|
|
Damage accumulates as drawing occurs in the drawable. Each drawing operation
|
|
'damages' one or more rectangular areas within the drawable. The rectangles
|
|
are guaranteed to include the set of pixels modified by each operation, but
|
|
may include significantly more than just those pixels. The desire is for
|
|
the damage to strike a balance between the number of rectangles reported and
|
|
the extraneous area included. A reasonable goal is for each primitive
|
|
object drawn (line, string, rectangle) to be represented as a single
|
|
rectangle and for the damage area of the operation to be the union of these
|
|
rectangles.
|
|
|
|
The DAMAGE extension allows applications to either receive the raw
|
|
rectangles as a stream of events, or to have them partially processed within
|
|
the X server to reduce the amount of data transmitted as well as reduce the
|
|
processing latency once the repaint operation has started.
|
|
|
|
Damage to a window reflects both drawing within the window itself as well as
|
|
drawing within any inferior window that affects pixels seen by
|
|
IncludeInferiors rendering operations. To reduce the computational
|
|
complexity of this, the DAMAGE extension allows the server to monitor all
|
|
rendering operations within the physical target pixel storage that fall
|
|
within the bounds of the window. In a system with a single frame buffer
|
|
holding all windows, this means that damage will accumulate for all
|
|
rendering operations that lie within the visible part of the window.
|
|
|
|
The precise reason for this architecture will be made clear in the XSPLITTREE
|
|
extension which will provide multiple pixel storage areas for the screen
|
|
contents.
|
|
|
|
4. Data types
|
|
|
|
The "Damage" object holds any accumulated damage region and reflects the
|
|
relationship between the drawable selected for damage notification and the
|
|
drawable for which damage is tracked.
|
|
|
|
5. Errors
|
|
|
|
Damage
|
|
A value for a DAMAGE argument does not name a defined DAMAGE.
|
|
|
|
6. Types
|
|
|
|
DAMAGE 32-bit value (top three bits guaranteed to be zero)
|
|
|
|
DamageReportLevel { DamageReportRawRectangles,
|
|
DamageReportDeltaRectangles,
|
|
DamageReportBoundingBox,
|
|
DamageReportNonEmpty }
|
|
|
|
DamageReportRawRectangles
|
|
|
|
Delivers DamageNotify events each time the screen
|
|
is modified with rectangular bounds that circumscribe
|
|
the damaged area. No attempt to compress out overlapping
|
|
rectangles is made.
|
|
|
|
DamageReportDeltaRectangles
|
|
|
|
Delivers DamageNotify events each time damage occurs
|
|
which is not included in the damage region. The
|
|
reported rectangles include only the changes to that
|
|
area, not the raw damage data.
|
|
|
|
DamageReportBoundingBox
|
|
|
|
Delivers DamageNotify events each time the bounding
|
|
box enclosing the damage region increases in size.
|
|
The reported rectangle encloses the entire damage region,
|
|
not just the changes to that size.
|
|
|
|
DamageReportNonEmpty
|
|
|
|
Delivers a single DamageNotify event each time the
|
|
damage rectangle changes from empty to non-empty, and
|
|
also whenever the result of a DamageSubtract request
|
|
results in a non-empty region.
|
|
|
|
7. Events
|
|
|
|
DamageNotify
|
|
|
|
level: DamageReportLevel
|
|
drawable: Drawable
|
|
damage: DAMAGE
|
|
more: Bool
|
|
timestamp: Timestamp
|
|
area: Rectangle
|
|
drawable-geometry: Rectangle
|
|
|
|
'more' indicates whether there are subsequent damage events
|
|
being delivered immediately as part of a larger damage region
|
|
|
|
8. Extension Initialization
|
|
|
|
The client must negotiate the version of the extension before executing
|
|
extension requests. Otherwise, the server will return BadRequest for any
|
|
operations other than QueryVersion.
|
|
|
|
QueryVersion
|
|
|
|
client-major-version: CARD32
|
|
client-minor-version: CARD32
|
|
|
|
->
|
|
|
|
major-version: CARD32
|
|
minor-version: CARD32
|
|
|
|
The client sends the highest supported version to the server and
|
|
the server sends the highest version it supports, but no higher than
|
|
the requested version. Major versions changes can introduce
|
|
incompatibilities in existing functionality, minor version
|
|
changes introduce only backward compatible changes. It is
|
|
the clients responsibility to ensure that the server supports
|
|
a version which is compatible with its expectations. Servers
|
|
are encouraged to support multiple versions of the extension.
|
|
|
|
9. Enable Monitoring
|
|
|
|
DamageCreate
|
|
|
|
damage: DAMAGE
|
|
drawable: Drawable
|
|
level: DamageReportLevel
|
|
|
|
Creates a damage object to monitor changes to Drawable
|
|
|
|
DamageDestroy
|
|
damage: DAMAGE
|
|
|
|
Destroys damage.
|
|
|
|
DamageSubtract
|
|
|
|
damage: DAMAGE
|
|
repair: Region or None
|
|
parts: Region
|
|
|
|
Synchronously modifies the regions in the following manner:
|
|
|
|
If repair is None:
|
|
|
|
1) parts = damage
|
|
2) damage = <empty>
|
|
|
|
Otherwise:
|
|
|
|
1) parts = damage INTERSECT repair
|
|
2) damage = damage - parts
|
|
3) Generate DamageNotify for remaining damage areas
|