salmanoff/docs/api-xcb-provider-xorg.md

# DAP Spec: stim-buff-api `xcb`, provider `xorg`

## Overview

The `xcb` stim-buff-api with the `xorg` provider allows Salmanoff to interact with Xorg
server windows. This can be used to capture visual data from specific windows 
or entire screens managed by the Xorg server.

## DAP Spec Format

The general format of a DAP spec for the `xcb` stim-buff-api with the `xorg` provider 
is:
```
sensor-type|dev-identifier|stim-iface-api|xcb(stim-buff-api-params)|xorg(provider-params)|deviceSelector
```

* `sensor-type` is always either '`+idev`' (interoceptor), '`+edev`' 
  (extrospector), or '`+adev`' (actuator).
* `dev-identifier` is a user-defined name for this specific device instance.
* `stim-iface-api` is the name of the StimIface library that should be used to 
  process the data from the stim buffer.
* `stim-buff-api` is `xcb` in this case, and the `stim-buff-api-params` in parentheses may be 
  omitted, in which case the parentheses will be empty, but the parentheses 
  must always be written out.
* `provider` is `xorg` in this case, and the `provider-params` in parentheses 
  may be omitted, in which case the parentheses will be empty, but the 
  parentheses must always be written out.
* `deviceSelector` is the idiosyncratic label/name used by the `provider` to 
  identify the specific window or screen you want to access via that 
  `provider`.

## `stim-buff-api-params` and `provider-params`

### `stim-buff-api-params`

The `stim-buff-api-params` for the `xcb` stim-buff-api can include the following:

* `dev-id` or `devid`: Specifies that the `deviceSelector` is a numeric window 
  ID. The ID can be specified in decimal or hexadecimal format.
* `dev-string`, `dev-str`, `devstr`, or `devstring`: Specifies that the 
  `deviceSelector` is an exact window name.
* `dev-substring`, `dev-substr`, `devsubstr`, or `devsubstring`: Specifies 
  that the `deviceSelector` is a substring match (default).

Example:
```
xcb(dev-id)|123456
xcb(dev-id)|0x1e240
xcb(dev-string)|exact-window-name
xcb(dev-substring)|window-name
```

### `provider-params`

The `provider-params` for the `xorg` provider can include the following:

* `display`: The display number (e.g., `0` for `:0`).
* `screen`: The screen number within the display (e.g., `0` for the first 
  screen).

Example:
```
xorg(display=0|screen=0)
```

## `deviceSelector`

The `deviceSelector` can be one of the following:

* A numeric window ID.
* A window name (exact match or substring match).

### Matching Types

* By default, the `deviceSelector` is treated as a substring match.
* To specify an exact match, use the `dev-string` parameter.
* To specify a numeric window ID, use the `dev-id` parameter.

Example:
```
xcb(dev-substring)|window-name
xcb(dev-string)|exact-window-name
xcb(dev-id)|123456
```

## Escaping Whitespace

In `deviceSelector` and other string tokens, whitespace can be included by 
prefixing it with a backslash (`\`). The backslash will be discarded during 
parsing.

Example:
```
xcb(dev-string)|My\ Exact\ Window\ Name
```

## Examples

### To attach a specific window by name (substring match):
```
+edev|my-window|visual-stimiface|xcb(dev-substring)|xorg(display=0|screen=0)|my-window
```
This will attach to a window whose name contains "my-window" as a substring.

### To attach a specific window by exact name:
```
+edev|my-window|visual-stimiface|xcb(dev-string)|xorg(display=0|screen=0)|My\ Exact\ Window\ Name
```
This will attach to a window whose name exactly matches "My Exact Window Name".

### To attach a specific window by numeric ID:
```
+edev|my-window|visual-stimiface|xcb(dev-id)|xorg(display=0|screen=0)|123456
```
This will attach to a window with the numeric ID `123456`.

### To attach the entire screen:
```
+edev|my-screen|visual-stimiface|xcb()|xorg(display=0|screen=0)|all
```
This will attach to the entire screen `0` of display `0`.