1X11::Protocol::Ext::DAMUAsGeEr(3C)ontributed Perl DocumeXn1t1a:t:iPornotocol::Ext::DAMAGE(3)
2
6 X11::Protocol::Ext::DAMAGE - drawing notifications
7
9 use X11::Protocol;
10 my $X = X11::Protocol->new;
11 $X->init_extension('DAMAGE')
12 or print "DAMAGE extension not available";
13 my $damage = $X->new_rsrc;
15 $X->DamageCreate ($damage, $drawable, 'NonEmpty');
16 sub my_event_handler {
18 my %h = @_;
19 if ($h{'name'} eq 'DamageNotify') {
20 my $drawable = $h{'drawable'};
21 $X->DamageSubtract ($damage, 'None', $parts_region);
22 # do something for $parts_region changed in $drawable
23 }
24 }
25
27 The DAMAGE extension lets a client listen for changes to drawables
28 (windows, pixmaps, etc) due to drawing operations, including drawing
29 into sub-windows which appears in the parent.
30 This can be used for various kinds of efficient copying or replicating
32 of window contents, such as cloning to another screen, showing a
33 magnified view, etc. The root window can be monitored to get changes
34 on the whole screen.
35 Content changes due to drawing are conceived as "damage". A server-
37 side damage object accumulates areas as rectangles to make a server-
38 side "region" per the XFIXES 2.0 extension (see
39 X11::Protocol::Ext::XFIXES)
40 A DamageNotify event is sent from a damage object. A reporting level
42 controls the level of detail, ranging from just one event on becoming
43 non-empty, up to an event for every drawing operation affecting the
44 relevant drawable.
45 Fetching an accumulated damage region (or part of it) is reckoned as a
47 "repair". It doesn't change any drawables in any way, just fetches the
48 region from the damage object. This fetch is atomic, so nothing is
49 lost if the listening client is a bit lagged etc.
50 See examples/damage-duplicate.pl for one way to use damage to duplicate
52 a window in real-time.
53
55 The following requests are made available with an "init_extension()",
56 as per "EXTENSIONS" in X11::Protocol.
57 my $is_available = $X->init_extension('DAMAGE');
59 DAMAGE 1.0
61 "($server_major, $server_minor) = $X->DamageQueryVersion
62 ($client_major, $client_minor)"
63 Negotiate a protocol version with the server. $client_major and
64 $client_minor is what the client would like, the returned
65 $server_major and $server_minor is what the server will do, which
66 might be less than requested (but not more).
67 The current code supports up to 1.1. If asking for higher then be
69 careful that it's upwardly compatible. The module code negotiates
70 a version in "init_extension()" so an explicit
71 "DamageQueryVersion()" is normally not needed.
72 "$X->DamageCreate ($damage, $drawable, $level)"
74 Create a new damage object in $damage (a new XID) which monitors
75 changes to $drawable. If $drawable is a window then changes to its
76 subwindows are included too.
77 # listening to every change on the whole screen
79 my $damage = $X->new_rsrc;
80 $X->DamageCreate ($damage, $X->root, 'RawRectangles');
81 $level is an enum string controlling how often "DamageNotify"
83 events are emitted (see "EVENTS" below).
84 RawRectangles every change
86 DeltaRectangles when damage region expands
87 BoundingBox when damage bounding box expands
88 NonEmpty when damage first becomes non-empty
89 "$X->DamageDestroy ($damage)"
91 Destroy $damage.
92 "$X->DamageSubtract ($damage, $repair_region, $parts_region)"
94 Move the accumulated region in $damage to $parts_region (a region
95 XID), and clear it from $damage.
96 If $parts_region is "None" then $damage is cleared and the region
98 discarded. This can be used if for example the entire $drawable
99 will be copied or re-examined, so the exact parts are not needed.
100 $repair_region is what portion of $damage to consider. "None"
102 means move and clear everything in $damage. Otherwise
103 $repair_region is a region XID and the portion of the damage region
104 within $repair_region is moved and cleared. Anything outside is
105 left in $damage.
106 If anything is left in $damage then a new "DamageNotify" event is
108 immediately sent. This can be good for instance if you picked out
109 a $repair_region corresponding to what you thought was the window
110 size (perhaps from the "geometry" field of a "DamageNotify" event),
111 but it has grown in the interim.
112 Region objects here can be created with the XFIXES 2.0 extension
114 (see X11::Protocol::Ext::XFIXES). It should be available whenever
115 DAMAGE is available. If using "None" and "None" to clear and
116 discard then region objects are not required and there's no need
117 for an "init_extension('XFIXES')".
118 DAMAGE 1.1
120 "$X->DamageAdd ($drawable, $region)"
121 Report to any interested damage objects that changes have occurred
122 in $region (a region XID) of $drawable.
123 This is used by clients which modify a drawable in ways not seen by
125 the normal protocol drawing operations. For example an MIT-SHM
126 shared memory pixmap modified by writing to the memory (see
127 X11::Protocol::Ext::MIT_SHM), or the various "direct rendering" to
128 graphics hardware or GL etc.
129
131 "DamageNotify" events are sent to the client which created the damage
132 object. These events are always generated, there's nothing to select
133 or deselect them. The event has the usual fields
134 name "DamageNotify"
136 synthetic true if from a SendEvent
137 code integer opcode
138 sequence_number integer
139 and event-specific fields
141 damage XID, damage object
143 drawable XID, as from DamageCreate
144 level enum, as from DamageCreate
145 more boolean, if more DamageNotify on the way
146 time integer, server timestamp
147 area arrayref [$x,$y,$width,$height]
148 geometry arrayref [$rootx,$rooty,$width,$height]
149 "drawable" and "level" are as from the "DamageCreate()" which made the
151 "damage" object.
152 "more" is true if there's further "DamageNotify" events on the way for
154 this damage object. This can happen when the "level" means there's a
155 set of "area" rectangles to report.
156 "area" is a rectangle within "drawable", as a 4-element arrayref,
158 [ $x, $y, $width, $height ]
160 What it covers depends on the reporting level requested,
162 · "RawRectangles" -- a rectangle around an arc, line, etc, drawing
164 operation which changed "drawable".
165 · "DeltaRectangles" -- an additional rectangle extending the damage
167 region. Only new rectangles are reported, not any of the existing
168 damage region. Reporting a region addition may require multiple
169 "DamageNotify" events.
170 · "BoundingBox" -- a bounding box around the damage region
172 accumulated, bigger than previously reported.
173 · "NonEmpty" -- umm, something, maybe the entire drawable.
175 "geometry" is the current size and position of the drawable as a
177 4-element arrayref in root window coordinates. For a pixmap $root_x
178 and $root_y are 0.
179 [ $root_x, $root_y, $width, $height ]
181
183 The reporting level above is type "DamageReportLevel". So for example
184 (after a successful "$X->init_extension('DAMAGE')"),
185 $number = $X->num('DamageReportLevel', 'RawRectangles');
187 $string = $X->interp('DamageReportLevel', 3);
189 See "SYMBOLIC CONSTANTS" in X11::Protocol.
191
193 Error type "Damage" is a bad $damage resource XID in a request.
194
196 The server extension version number is queried in the
197 "init_extension()", but not yet made available as such. The version
198 determines whether "DamageAdd()" ought to work. Currently that request
199 is always setup, but presumably generates an Opcode error if the server
200 doesn't have it.
201
203 X11::Protocol, X11::Protocol::Ext::XFIXES
204 /usr/share/doc/x11proto-damage-dev/damageproto.txt.gz,
206 <http://cgit.freedesktop.org/xorg/proto/damageproto/tree/damageproto.txt>
207
209 <http://user42.tuxfamily.org/x11-protocol-other/index.html>
210
212 Copyright 2011, 2012, 2013, 2014, 2017 Kevin Ryde
213 X11-Protocol-Other is free software; you can redistribute it and/or
215 modify it under the terms of the GNU General Public License as
216 published by the Free Software Foundation; either version 3, or (at
217 your option) any later version.
218 X11-Protocol-Other is distributed in the hope that it will be useful,
220 but WITHOUT ANY WARRANTY; without even the implied warranty of
221 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
222 General Public License for more details.
223 You should have received a copy of the GNU General Public License along
225 with X11-Protocol-Other. If not, see <http://www.gnu.org/licenses/>.
226perl v5.28.0 2017-01-20 X11::Protocol::Ext::DAMAGE(3)