xref: /xsrc/external/mit/xcb-proto/dist/src/damage.xml

<?xml version="1.0" encoding="utf-8"?>
<!--
Copyright (C) 2004 Josh Triplett
Copyright (C) 2007 Jeremy Kolb
All Rights Reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Except as contained in this notice, the names of the authors or their
institutions shall not be used in advertising or otherwise to promote the
sale, use or other dealings in this Software without prior written
authorization from the authors.
-->
<!-- This file describes version 1.1 of DAMAGE. -->
<xcb header="damage" extension-xname="DAMAGE" extension-name="Damage"
    major-version="1" minor-version="1">
  <import>xproto</import>
  <import>xfixes</import>

  <xidtype name="DAMAGE" />

  <enum name="ReportLevel">
    <item name="RawRectangles">   <value>0</value> </item>
    <item name="DeltaRectangles"> <value>1</value> </item>
    <item name="BoundingBox">     <value>2</value> </item>
    <item name="NonEmpty">        <value>3</value> </item>
  </enum>

  <error name="BadDamage" number="0" />

  <request name="QueryVersion" opcode="0">
    <field type="CARD32" name="client_major_version" />
    <field type="CARD32" name="client_minor_version" />
    <reply>
      <pad bytes="1" />
      <field type="CARD32" name="major_version" />
      <field type="CARD32" name="minor_version" />
      <pad bytes="16" />
      <doc>
	<brief>The negotiated version of the DAMAGE extension</brief>
	<description>
This indicates the version of the DAMAGE extension chosen by the server.
It will always be less than or equal to the version offered by the client.
	</description>
	<field name="major_version">The major version chosen by the server.</field>
	<field name="minor_version">The minor version chosen by the server.</field>
      </doc>
    </reply>
    <doc>
      <brief>Negotiate the version of the DAMAGE extension</brief>
      <description>
This negotiates the version of the DAMAGE extension.  It must precede any other
request using the DAMAGE extension.  Failure to do so will cause a BadRequest
error for those requests.
      </description>
      <field name="client_major_version">The major version supported by the client.</field>
      <field name="client_minor_version">The minor version supported by the client.</field>
    </doc>
  </request>

  <request name="Create" opcode="1">
    <field type="DAMAGE"   name="damage" />
    <field type="DRAWABLE" name="drawable" />
    <field type="CARD8"    name="level" enum="ReportLevel" />
    <pad bytes="3" />
    <doc>
      <brief>Creates a Damage object to monitor changes to a drawable.</brief>
      <description><![CDATA[
This creates a Damage object to monitor changes to a drawable, and specifies
the level of detail to be reported for changes.

We call changes made to pixel contents of windows and pixmaps 'damage'
throughout this extension.

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.

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.
      ]]></description>
      <field name="damage"><![CDATA[
The ID with which you will refer to the new Damage object, created by
`xcb_generate_id`.
      ]]></field>
      <field name="drawable">The ID of the drawable to be monitored.</field>
      <field name="level">The level of detail to be provided in Damage events.</field>
    </doc>
  </request>

  <request name="Destroy" opcode="2">
    <field type="DAMAGE" name="damage" />
    <doc>
      <brief>Destroys a previously created Damage object.</brief>
      <description>
This destroys a Damage object and requests the X server stop reporting
the changes it was tracking.
      </description>
      <field name="damage"><![CDATA[
The ID you provided to `xcb_create_damage`.
      ]]></field>
    </doc>
  </request>

  <request name="Subtract" opcode="3">
    <field type="DAMAGE" name="damage" />
    <field type="REGION" name="repair" altenum="Region" />
    <field type="REGION" name="parts" altenum="Region" />
    <doc>
      <brief>Remove regions from a previously created Damage object.</brief>
      <description>
This updates the regions of damage recorded in a a Damage object.
See https://www.x.org/releases/current/doc/damageproto/damageproto.txt
for details.
      </description>
      <field name="damage">The ID you provided to `xcb_create_damage`.</field>
    </doc>
  </request>

  <request name="Add" opcode="4">
    <field type="DRAWABLE" name="drawable" />
    <field type="REGION" name="region" />
    <doc>
      <brief>Add a region to a previously created Damage object.</brief>
      <description>
This updates the regions of damage recorded in a a Damage object.
See https://www.x.org/releases/current/doc/damageproto/damageproto.txt
for details.
      </description>
      <field name="damage">The ID you provided to `xcb_create_damage`.</field>
    </doc>
  </request>

  <event name="Notify" number="0">
    <field type="CARD8"     name="level" enum="ReportLevel" />
    <field type="DRAWABLE"  name="drawable" />
    <field type="DAMAGE"    name="damage" />
    <field type="TIMESTAMP" name="timestamp" />
    <field type="RECTANGLE" name="area" />
    <field type="RECTANGLE" name="geometry" />
    <doc>
      <brief>the contents of the monitored drawable have changed</brief>
      <field name="level"><![CDATA[
The level of the damage being reported.
If the 0x80 bit is set, indicates there are subsequent Damage events
being delivered immediately as part of a larger Damage region.
      ]]></field>
      <field name="drawable"><![CDATA[
The drawable for which damage is being reported.
      ]]></field>
      <field name="damage"><![CDATA[
The Damage object being used to track the damage.
      ]]></field>
      <field name="timestamp"><![CDATA[
Time when the event was generated (in milliseconds).
      ]]></field>
      <field name="area"><![CDATA[
Damaged area of the drawable.
      ]]></field>
      <field name="geometry"><![CDATA[
Total area of the drawable.
      ]]></field>
      <see type="request" name="Create" />
    </doc>
  </event>
</xcb>