1X11::Protocol::Ext::DAMUAsGeEr(3C)ontributed Perl DocumeXn1t1a:t:iPornotocol::Ext::DAMAGE(3)
2
3
4

NAME

6       X11::Protocol::Ext::DAMAGE - drawing notifications
7

SYNOPSIS

9        use X11::Protocol;
10        my $X = X11::Protocol->new;
11        $X->init_extension('DAMAGE')
12          or print "DAMAGE extension not available";
13
14        my $damage = $X->new_rsrc;
15        $X->DamageCreate ($damage, $drawable, 'NonEmpty');
16
17        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

DESCRIPTION

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
31       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
36       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
41       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
46       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
51       See examples/damage-duplicate.pl for one way to use damage to duplicate
52       a window in real-time.
53

REQUESTS

55       The following requests are made available with an "init_extension()",
56       as per "EXTENSIONS" in X11::Protocol.
57
58           my $is_available = $X->init_extension('DAMAGE');
59
60   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
68           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
73       "$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
78               # listening to every change on the whole screen
79               my $damage = $X->new_rsrc;
80               $X->DamageCreate ($damage, $X->root, 'RawRectangles');
81
82           $level is an enum string controlling how often "DamageNotify"
83           events are emitted (see "EVENTS" below).
84
85               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
90       "$X->DamageDestroy ($damage)"
91           Destroy $damage.
92
93       "$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
97           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
101           $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
107           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
113           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
119   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
124           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

EVENTS

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
135           name             "DamageNotify"
136           synthetic        true if from a SendEvent
137           code             integer opcode
138           sequence_number  integer
139
140       and event-specific fields
141
142           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
150       "drawable" and "level" are as from the "DamageCreate()" which made the
151       "damage" object.
152
153       "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
157       "area" is a rectangle within "drawable", as a 4-element arrayref,
158
159           [ $x, $y, $width, $height ]
160
161       What it covers depends on the reporting level requested,
162
163       ·   "RawRectangles" -- a rectangle around an arc, line, etc, drawing
164           operation which changed "drawable".
165
166       ·   "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
171       ·   "BoundingBox" -- a bounding box around the damage region
172           accumulated, bigger than previously reported.
173
174       ·   "NonEmpty" -- umm, something, maybe the entire drawable.
175
176       "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
180           [ $root_x, $root_y, $width, $height ]
181

ENUM TYPES

183       The reporting level above is type "DamageReportLevel".  So for example
184       (after a successful "$X->init_extension('DAMAGE')"),
185
186           $number = $X->num('DamageReportLevel', 'RawRectangles');
187
188           $string = $X->interp('DamageReportLevel', 3);
189
190       See "SYMBOLIC CONSTANTS" in X11::Protocol.
191

ERRORS

193       Error type "Damage" is a bad $damage resource XID in a request.
194

BUGS

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

SEE ALSO

203       X11::Protocol, X11::Protocol::Ext::XFIXES
204
205       /usr/share/doc/x11proto-damage-dev/damageproto.txt.gz,
206       <http://cgit.freedesktop.org/xorg/proto/damageproto/tree/damageproto.txt>
207

HOME PAGE

209       <http://user42.tuxfamily.org/x11-protocol-other/index.html>
210

LICENSE

212       Copyright 2011, 2012, 2013, 2014, 2017 Kevin Ryde
213
214       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
219       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
224       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/>.
226
227
228
229perl v5.28.1                      2017-01-20     X11::Protocol::Ext::DAMAGE(3)
Impressum