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.