Damage Extension Application Program Interface



Contents:

 1. Introduction
 2. C functions


1. Introduction
    The Damage extension provides detailed reports on all changes to the indicated screen as a
   stream of region records. The registered client process can control the volume of data
   sent to it in order to enable tuned performance gains. Common users of DAMAGE extension 
   are screen magnifiers and remote desktop utilities.
   
 
 
2. C functions


2.1 Query Extension

   NAME
       XDamageQueryExtension - Get version information

   SYNTAX
       Status XDamageQueryExtension(Display *display,
					int *event_basep,
					int *error_basep);

   ARGUMENTS
       display			- Connection to the X server.
       event_basep		- storage for base of event codes
       error_basep		- storage for base of error codes

   DESCRIPTION
	The XDamageQueryExtension function returns the event and error
   version numbers supported by the server. 
   XDamageQueryExtension returns True if the damage extension is supported in
   the server, otherwise, it returns False.



2.2 Query Extension Version

   NAME
       XDamageQueryVersion - Get version information

   SYNTAX
       Status XDamageQueryVersion(Display *display,
					int *major_version_return,
					int *minor_version_return);

   ARGUMENTS
       display			- Connection to the X server.
       major_version_number	- storage for major version number.
       minor_version_number	- storage for minor version number.

   DESCRIPTION
	The XDamageQueryVersion function returns the major and minor protocol
   version numbers supported by the server. XDamageQueryVersion always returns
   "1". Programmers must use XDamageQuery Extension to verify that the
   extension is supported in the server.




2.3 Create X Damage Session

    NAME
	DamagePtr
	XDamageCreate -   Creates a Damage object to monitor changes to Drawable
    SYNTAX
	XDamageCreate (Display *display, Drawable drawable, int level)
    ARGUMENTS
	display			- Connection to the X server.
	drawable			-
	level			- Detail level of reporting (Enum, see protocol doc)

    RETURNS
	DamagePtr		- Ptr to opaque descriptor of Damage session

    DESCRIPTION

	Initialize data objects related to damage reporting so that monitoring
	can begin.




2.4 Destroy X Damage Session

    NAME
	XDamageDestroy -  Ends monitoring and frees storage
    SYNTAX
	XDamageDestroy (Display *display, DamagePtr damage)
    ARGUMENTS
	display			- Connection to the X server.
	damage			- Damage handle

    DESCRIPTION

	Tear down Damage monitoring session.


2.5 Subtract Damage Regions

    NAME
	XDamageSubtract -  Synchronously modifies regions
    SYNTAX
	XDamageSubtract (Display *display, Damage damage, 
		 XserverRegion repair, XserverRegion parts)
    ARGUMENTS
	display			- Connection to the X server.
	damage			- damage descriptor
	repair			- value REGION or None
	parts			- Region

    DESCRIPTION
	If repair is None:
		parts = damage
		damage = <empty>
	Otherwise:
		parts = damage INTERSECT repair
		damage = damage - parts
		Generate DamageNotify for remaining damage areas

	Allows damage client to clear out some or all of the damage
	region as it completes the indicated repairs.
	



2.6  Damage Notify Event

    NAME
	Event
    STRUCTURE
typedef struct {
    int type;                   /* event base */
    unsigned long serial;	/* event serial number */
    Bool send_event;
    Display *display;
    Drawable drawable;		XID
    Damage damage;		XID
    int level;			reporting level set by user
    Bool more;                  /* more events will be delivered immediately */
    Time timestamp;
    XRectangle area;		The damaged area
    XRectangle geometry;	upper left corner of the drawable
} XDamageNotifyEvent;


    DESCRIPTION
	Common event structure used by Damage extension to report
	screen activity.