XCB: XCB Damage API

XCB 1.17.0

Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
XCB Damage API

Damage XCB Protocol Implementation. More...

## Data Structures
struct | xcb_damage_damage_iterator_t
| xcb_damage_damage_iterator_t More...
struct | xcb_damage_bad_damage_error_t
| xcb_damage_bad_damage_error_t More...
struct | xcb_damage_query_version_cookie_t
| xcb_damage_query_version_cookie_t More...
struct | xcb_damage_query_version_request_t
| xcb_damage_query_version_request_t More...
struct | xcb_damage_query_version_reply_t
| xcb_damage_query_version_reply_t More...
struct | xcb_damage_create_request_t
| xcb_damage_create_request_t More...
struct | xcb_damage_destroy_request_t
| xcb_damage_destroy_request_t More...
struct | xcb_damage_subtract_request_t
| xcb_damage_subtract_request_t More...
struct | xcb_damage_add_request_t
| xcb_damage_add_request_t More...
struct | xcb_damage_notify_event_t
| xcb_damage_notify_event_t More...

## Macros
#define | XCB_DAMAGE_MAJOR_VERSION 1
#define | XCB_DAMAGE_MINOR_VERSION 1
#define | XCB_DAMAGE_BAD_DAMAGE 0
#define | XCB_DAMAGE_QUERY_VERSION 0
#define | XCB_DAMAGE_CREATE 1
#define | XCB_DAMAGE_DESTROY 2
#define | XCB_DAMAGE_SUBTRACT 3
#define | XCB_DAMAGE_ADD 4
#define | XCB_DAMAGE_NOTIFY 0

## Typedefs
typedef uint32_t | xcb_damage_damage_t
typedef struct xcb_damage_damage_iterator_t | xcb_damage_damage_iterator_t
| xcb_damage_damage_iterator_t
typedef enum xcb_damage_report_level_t | xcb_damage_report_level_t
typedef struct xcb_damage_bad_damage_error_t | xcb_damage_bad_damage_error_t
| xcb_damage_bad_damage_error_t
typedef struct xcb_damage_query_version_cookie_t | xcb_damage_query_version_cookie_t
| xcb_damage_query_version_cookie_t
typedef struct xcb_damage_query_version_request_t | xcb_damage_query_version_request_t
| xcb_damage_query_version_request_t
typedef struct xcb_damage_query_version_reply_t | xcb_damage_query_version_reply_t
| xcb_damage_query_version_reply_t
typedef struct xcb_damage_create_request_t | xcb_damage_create_request_t
| xcb_damage_create_request_t
typedef struct xcb_damage_destroy_request_t | xcb_damage_destroy_request_t
| xcb_damage_destroy_request_t
typedef struct xcb_damage_subtract_request_t | xcb_damage_subtract_request_t
| xcb_damage_subtract_request_t
typedef struct xcb_damage_add_request_t | xcb_damage_add_request_t
| xcb_damage_add_request_t
typedef struct xcb_damage_notify_event_t | xcb_damage_notify_event_t
| xcb_damage_notify_event_t

## Enumerations
enum | xcb_damage_report_level_t { XCB_DAMAGE_REPORT_LEVEL_RAW_RECTANGLES = 0 , XCB_DAMAGE_REPORT_LEVEL_DELTA_RECTANGLES = 1 , XCB_DAMAGE_REPORT_LEVEL_BOUNDING_BOX = 2 , XCB_DAMAGE_REPORT_LEVEL_NON_EMPTY = 3 }

## Functions
void | xcb_damage_damage_next (xcb_damage_damage_iterator_t *i)
xcb_generic_iterator_t | xcb_damage_damage_end (xcb_damage_damage_iterator_t i)
xcb_damage_query_version_cookie_t | xcb_damage_query_version (xcb_connection_t *c, uint32_t client_major_version, uint32_t client_minor_version)
| Negotiate the version of the DAMAGE extension.
xcb_damage_query_version_cookie_t | xcb_damage_query_version_unchecked (xcb_connection_t *c, uint32_t client_major_version, uint32_t client_minor_version)
| Negotiate the version of the DAMAGE extension.
xcb_damage_query_version_reply_t * | xcb_damage_query_version_reply (xcb_connection_t *c, xcb_damage_query_version_cookie_t cookie, xcb_generic_error_t **e)
xcb_void_cookie_t | xcb_damage_create_checked (xcb_connection_t *c, xcb_damage_damage_t damage, xcb_drawable_t drawable, uint8_t level)
| Creates a Damage object to monitor changes to a drawable.
xcb_void_cookie_t | xcb_damage_create (xcb_connection_t *c, xcb_damage_damage_t damage, xcb_drawable_t drawable, uint8_t level)
| Creates a Damage object to monitor changes to a drawable.
xcb_void_cookie_t | xcb_damage_destroy_checked (xcb_connection_t *c, xcb_damage_damage_t damage)
| Destroys a previously created Damage object.
xcb_void_cookie_t | xcb_damage_destroy (xcb_connection_t *c, xcb_damage_damage_t damage)
| Destroys a previously created Damage object.
xcb_void_cookie_t | xcb_damage_subtract_checked (xcb_connection_t *c, xcb_damage_damage_t damage, xcb_xfixes_region_t repair, xcb_xfixes_region_t parts)
| Remove regions from a previously created Damage object.
xcb_void_cookie_t | xcb_damage_subtract (xcb_connection_t *c, xcb_damage_damage_t damage, xcb_xfixes_region_t repair, xcb_xfixes_region_t parts)
| Remove regions from a previously created Damage object.
xcb_void_cookie_t | xcb_damage_add_checked (xcb_connection_t *c, xcb_drawable_t drawable, xcb_xfixes_region_t region)
| Add a region to a previously created Damage object.
xcb_void_cookie_t | xcb_damage_add (xcb_connection_t *c, xcb_drawable_t drawable, xcb_xfixes_region_t region)
| Add a region to a previously created Damage object.

## Variables
xcb_extension_t | xcb_damage_id

## Detailed Description

Damage XCB Protocol Implementation.

## Macro Definition Documentation

## ◆ XCB_DAMAGE_ADD

#define XCB_DAMAGE_ADD 4

Opcode for xcb_damage_add.

Referenced by xcb_damage_add(), and xcb_damage_add_checked().

## ◆ XCB_DAMAGE_BAD_DAMAGE

#define XCB_DAMAGE_BAD_DAMAGE 0

Opcode for xcb_damage_bad_damage.

## ◆ XCB_DAMAGE_CREATE

#define XCB_DAMAGE_CREATE 1

Opcode for xcb_damage_create.

Referenced by xcb_damage_create(), and xcb_damage_create_checked().

## ◆ XCB_DAMAGE_DESTROY

#define XCB_DAMAGE_DESTROY 2

Opcode for xcb_damage_destroy.

Referenced by xcb_damage_destroy(), and xcb_damage_destroy_checked().

## ◆ XCB_DAMAGE_NOTIFY

#define XCB_DAMAGE_NOTIFY 0

Opcode for xcb_damage_notify.

## ◆ XCB_DAMAGE_QUERY_VERSION

#define XCB_DAMAGE_QUERY_VERSION 0

Opcode for xcb_damage_query_version.

Referenced by xcb_damage_query_version(), and xcb_damage_query_version_unchecked().

## ◆ XCB_DAMAGE_SUBTRACT

#define XCB_DAMAGE_SUBTRACT 3

Opcode for xcb_damage_subtract.

Referenced by xcb_damage_subtract(), and xcb_damage_subtract_checked().

## Function Documentation

## ◆ xcb_damage_add()

xcb_void_cookie_t xcb_damage_add | ( | xcb_connection_t * | c,
|  | xcb_drawable_t | drawable,
|  | xcb_xfixes_region_t | region )

Add a region to a previously created Damage object.

Parameters

  c | The connection

Returns
  A cookie

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.

References XCB_DAMAGE_ADD.

## ◆ xcb_damage_add_checked()

xcb_void_cookie_t xcb_damage_add_checked | ( | xcb_connection_t * | c,
|  | xcb_drawable_t | drawable,
|  | xcb_xfixes_region_t | region )

Add a region to a previously created Damage object.

Parameters

  c | The connection

Returns
  A cookie

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.

This form can be used only if the request will not cause a reply to be generated. Any returned error will be saved for handling by xcb_request_check().

References XCB_DAMAGE_ADD.

## ◆ xcb_damage_create()

xcb_void_cookie_t xcb_damage_create | ( | xcb_connection_t * | c,
|  | xcb_damage_damage_t | damage,
|  | xcb_drawable_t | drawable,
|  | uint8_t | level )

Creates a Damage object to monitor changes to a drawable.

Parameters

  c | The connection
  damage | The ID with which you will refer to the new Damage object, created by xcb_generate_id.
  drawable | The ID of the drawable to be monitored.
  level | A bitmask of xcb_damage_report_level_t values.
  level | The level of detail to be provided in Damage events.

Returns
  A cookie

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.

References XCB_DAMAGE_CREATE.

## ◆ xcb_damage_create_checked()

xcb_void_cookie_t xcb_damage_create_checked | ( | xcb_connection_t * | c,
|  | xcb_damage_damage_t | damage,
|  | xcb_drawable_t | drawable,
|  | uint8_t | level )

Creates a Damage object to monitor changes to a drawable.

Parameters

  c | The connection
  damage | The ID with which you will refer to the new Damage object, created by xcb_generate_id.
  drawable | The ID of the drawable to be monitored.
  level | A bitmask of xcb_damage_report_level_t values.
  level | The level of detail to be provided in Damage events.

Returns
  A cookie

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.

This form can be used only if the request will not cause a reply to be generated. Any returned error will be saved for handling by xcb_request_check().

References XCB_DAMAGE_CREATE.

## ◆ xcb_damage_damage_end()

xcb_generic_iterator_t xcb_damage_damage_end | ( | xcb_damage_damage_iterator_t | i | ) |

Return the iterator pointing to the last element

Parameters

  i | An xcb_damage_damage_iterator_t

Returns
  The iterator pointing to the last element

Set the current element in the iterator to the last element. The member rem is set to 0. The member data points to the last element.

References xcb_generic_iterator_t::data, xcb_generic_iterator_t::index, and xcb_generic_iterator_t::rem.

## ◆ xcb_damage_damage_next()

void xcb_damage_damage_next | ( | xcb_damage_damage_iterator_t * | i | ) |

Get the next element of the iterator

Parameters

  i | Pointer to a xcb_damage_damage_iterator_t

Get the next element in the iterator. The member rem is decreased by one. The member data points to the next element. The member index is increased by sizeof(xcb_damage_damage_t)

## ◆ xcb_damage_destroy()

xcb_void_cookie_t xcb_damage_destroy | ( | xcb_connection_t * | c,
|  | xcb_damage_damage_t | damage )

Destroys a previously created Damage object.

Parameters

  c | The connection
  damage | The ID you provided to xcb_create_damage.

Returns
  A cookie

This destroys a Damage object and requests the X server stop reporting the changes it was tracking.

References XCB_DAMAGE_DESTROY.

## ◆ xcb_damage_destroy_checked()

xcb_void_cookie_t xcb_damage_destroy_checked | ( | xcb_connection_t * | c,
|  | xcb_damage_damage_t | damage )

Destroys a previously created Damage object.

Parameters

  c | The connection
  damage | The ID you provided to xcb_create_damage.

Returns
  A cookie

This destroys a Damage object and requests the X server stop reporting the changes it was tracking.

This form can be used only if the request will not cause a reply to be generated. Any returned error will be saved for handling by xcb_request_check().

References XCB_DAMAGE_DESTROY.

## ◆ xcb_damage_query_version()

xcb_damage_query_version_cookie_t xcb_damage_query_version | ( | xcb_connection_t * | c,
|  | uint32_t | client_major_version,
|  | uint32_t | client_minor_version )

Negotiate the version of the DAMAGE extension.

Parameters

  c | The connection
  client_major_version | The major version supported by the client.
  client_minor_version | The minor version supported by the client.

Returns
  A cookie

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.

References XCB_DAMAGE_QUERY_VERSION.

## ◆ xcb_damage_query_version_reply()

xcb_damage_query_version_reply_t * xcb_damage_query_version_reply | ( | xcb_connection_t * | c,
|  | xcb_damage_query_version_cookie_t | cookie,
|  | xcb_generic_error_t ** | e )

Return the reply

Parameters

  c | The connection
  cookie | The cookie
  e | The xcb_generic_error_t supplied

Returns the reply of the request asked by

The parameter `e` supplied to this function must be NULL if xcb_damage_query_version_unchecked(). is used. Otherwise, it stores the error if any.

The returned value must be freed by the caller using free().

## ◆ xcb_damage_query_version_unchecked()

xcb_damage_query_version_cookie_t xcb_damage_query_version_unchecked | ( | xcb_connection_t * | c,
|  | uint32_t | client_major_version,
|  | uint32_t | client_minor_version )

Negotiate the version of the DAMAGE extension.

Parameters

  c | The connection
  client_major_version | The major version supported by the client.
  client_minor_version | The minor version supported by the client.

Returns
  A cookie

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.

This form can be used only if the request will cause a reply to be generated. Any returned error will be placed in the event queue.

References XCB_DAMAGE_QUERY_VERSION.

## ◆ xcb_damage_subtract()

xcb_void_cookie_t xcb_damage_subtract | ( | xcb_connection_t * | c,
|  | xcb_damage_damage_t | damage,
|  | xcb_xfixes_region_t | repair,
|  | xcb_xfixes_region_t | parts )

Remove regions from a previously created Damage object.

Parameters

  c | The connection
  damage | The ID you provided to xcb_create_damage.

Returns
  A cookie

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.

References XCB_DAMAGE_SUBTRACT.

## ◆ xcb_damage_subtract_checked()

xcb_void_cookie_t xcb_damage_subtract_checked | ( | xcb_connection_t * | c,
|  | xcb_damage_damage_t | damage,
|  | xcb_xfixes_region_t | repair,
|  | xcb_xfixes_region_t | parts )

Remove regions from a previously created Damage object.

Parameters

  c | The connection
  damage | The ID you provided to xcb_create_damage.

Returns
  A cookie

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.

This form can be used only if the request will not cause a reply to be generated. Any returned error will be saved for handling by xcb_request_check().

References XCB_DAMAGE_SUBTRACT.