1<?xml version="1.0" encoding="utf-8"?>
2<!--
3Copyright (C) 2004 Josh Triplett
4Copyright (C) 2007 Jeremy Kolb
5All Rights Reserved.
6
7Permission is hereby granted, free of charge, to any person obtaining a copy
8of this software and associated documentation files (the "Software"), to deal
9in the Software without restriction, including without limitation the rights
10to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11copies of the Software, and to permit persons to whom the Software is
12furnished to do so, subject to the following conditions:
13
14The above copyright notice and this permission notice shall be included in all
15copies or substantial portions of the Software.
16
17THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
21ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
22WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23
24Except as contained in this notice, the names of the authors or their
25institutions shall not be used in advertising or otherwise to promote the
26sale, use or other dealings in this Software without prior written
27authorization from the authors.
28-->
29<!-- This file describes version 1.1 of DAMAGE. -->
30<xcb header="damage" extension-xname="DAMAGE" extension-name="Damage"
31    major-version="1" minor-version="1">
32  <import>xproto</import>
33  <import>xfixes</import>
34
35  <xidtype name="DAMAGE" />
36
37  <enum name="ReportLevel">
38    <item name="RawRectangles">   <value>0</value> </item>
39    <item name="DeltaRectangles"> <value>1</value> </item>
40    <item name="BoundingBox">     <value>2</value> </item>
41    <item name="NonEmpty">        <value>3</value> </item>
42  </enum>
43
44  <error name="BadDamage" number="0" />
45
46  <request name="QueryVersion" opcode="0">
47    <field type="CARD32" name="client_major_version" />
48    <field type="CARD32" name="client_minor_version" />
49    <reply>
50      <pad bytes="1" />
51      <field type="CARD32" name="major_version" />
52      <field type="CARD32" name="minor_version" />
53      <pad bytes="16" />
54      <doc>
55	<brief>The negotiated version of the DAMAGE extension</brief>
56	<description>
57This indicates the version of the DAMAGE extension chosen by the server.
58It will always be less than or equal to the version offered by the client.
59	</description>
60	<field name="major_version">The major version chosen by the server.</field>
61	<field name="minor_version">The minor version chosen by the server.</field>
62      </doc>
63    </reply>
64    <doc>
65      <brief>Negotiate the version of the DAMAGE extension</brief>
66      <description>
67This negotiates the version of the DAMAGE extension.  It must precede any other
68request using the DAMAGE extension.  Failure to do so will cause a BadRequest
69error for those requests.
70      </description>
71      <field name="client_major_version">The major version supported by the client.</field>
72      <field name="client_minor_version">The minor version supported by the client.</field>
73    </doc>
74  </request>
75
76  <request name="Create" opcode="1">
77    <field type="DAMAGE"   name="damage" />
78    <field type="DRAWABLE" name="drawable" />
79    <field type="CARD8"    name="level" enum="ReportLevel" />
80    <pad bytes="3" />
81    <doc>
82      <brief>Creates a Damage object to monitor changes to a drawable.</brief>
83      <description><![CDATA[
84This creates a Damage object to monitor changes to a drawable, and specifies
85the level of detail to be reported for changes.
86
87We call changes made to pixel contents of windows and pixmaps 'damage'
88throughout this extension.
89
90Damage accumulates as drawing occurs in the drawable.  Each drawing operation
91'damages' one or more rectangular areas within the drawable.  The rectangles
92are guaranteed to include the set of pixels modified by each operation, but
93may include significantly more than just those pixels.  The desire is for
94the damage to strike a balance between the number of rectangles reported and
95the extraneous area included.  A reasonable goal is for each primitive
96object drawn (line, string, rectangle) to be represented as a single
97rectangle and for the damage area of the operation to be the union of these
98rectangles.
99
100The DAMAGE extension allows applications to either receive the raw
101rectangles as a stream of events, or to have them partially processed within
102the X server to reduce the amount of data transmitted as well as reduce the
103processing latency once the repaint operation has started.
104
105The Damage object holds any accumulated damage region and reflects the
106relationship between the drawable selected for damage notification and the
107drawable for which damage is tracked.
108      ]]></description>
109      <field name="damage"><![CDATA[
110The ID with which you will refer to the new Damage object, created by
111`xcb_generate_id`.
112      ]]></field>
113      <field name="drawable">The ID of the drawable to be monitored.</field>
114      <field name="level">The level of detail to be provided in Damage events.</field>
115    </doc>
116  </request>
117
118  <request name="Destroy" opcode="2">
119    <field type="DAMAGE" name="damage" />
120    <doc>
121      <brief>Destroys a previously created Damage object.</brief>
122      <description>
123This destroys a Damage object and requests the X server stop reporting
124the changes it was tracking.
125      </description>
126      <field name="damage"><![CDATA[
127The ID you provided to `xcb_create_damage`.
128      ]]></field>
129    </doc>
130  </request>
131
132  <request name="Subtract" opcode="3">
133    <field type="DAMAGE" name="damage" />
134    <field type="REGION" name="repair" altenum="Region" />
135    <field type="REGION" name="parts" altenum="Region" />
136    <doc>
137      <brief>Remove regions from a previously created Damage object.</brief>
138      <description>
139This updates the regions of damage recorded in a a Damage object.
140See https://www.x.org/releases/current/doc/damageproto/damageproto.txt
141for details.
142      </description>
143      <field name="damage">The ID you provided to `xcb_create_damage`.</field>
144    </doc>
145  </request>
146
147  <request name="Add" opcode="4">
148    <field type="DRAWABLE" name="drawable" />
149    <field type="REGION" name="region" />
150    <doc>
151      <brief>Add a region to a previously created Damage object.</brief>
152      <description>
153This updates the regions of damage recorded in a a Damage object.
154See https://www.x.org/releases/current/doc/damageproto/damageproto.txt
155for details.
156      </description>
157      <field name="damage">The ID you provided to `xcb_create_damage`.</field>
158    </doc>
159  </request>
160
161  <event name="Notify" number="0">
162    <field type="CARD8"     name="level" enum="ReportLevel" />
163    <field type="DRAWABLE"  name="drawable" />
164    <field type="DAMAGE"    name="damage" />
165    <field type="TIMESTAMP" name="timestamp" />
166    <field type="RECTANGLE" name="area" />
167    <field type="RECTANGLE" name="geometry" />
168    <doc>
169      <brief>the contents of the monitored drawable have changed</brief>
170      <field name="level"><![CDATA[
171The level of the damage being reported.
172If the 0x80 bit is set, indicates there are subsequent Damage events
173being delivered immediately as part of a larger Damage region.
174      ]]></field>
175      <field name="drawable"><![CDATA[
176The drawable for which damage is being reported.
177      ]]></field>
178      <field name="damage"><![CDATA[
179The Damage object being used to track the damage.
180      ]]></field>
181      <field name="timestamp"><![CDATA[
182Time when the event was generated (in milliseconds).
183      ]]></field>
184      <field name="area"><![CDATA[
185Damaged area of the drawable.
186      ]]></field>
187      <field name="geometry"><![CDATA[
188Total area of the drawable.
189      ]]></field>
190      <see type="request" name="Create" />
191    </doc>
192  </event>
193</xcb>
194