DocsExtensionsV1

Display

Display methods return device metadata as JSON and pixels as a kind-1 frame. The JSON result for a snapshot is only the envelope descriptor. The pixels follow on the binary channel, role framebuffer, same JSON-RPC id.

listDisplaySources

{ "vmId": "f1e6a94c-6ee2-4c9b-8a44-9be7b2ca6cf1" }

Result is DisplaySourceSnapshot[]. Identity is a tagged enum (kind):

[
  {
    "identity": { "kind": "engine", "id": 0 },
    "sourceName": "scanout0",
    "frameSequence": 1,
    "width": 1920,
    "height": 1080,
    "rowBytes": 7680,
    "pixelFormat": "BGRA8888",
    "cursorSequence": null,
    "cursorImageSequence": null
  },
  {
    "identity": {
      "kind": "deviceOutput",
      "deviceId": "mxgpu0",
      "outputId": 0
    },
    "sourceName": "mx-gpu",
    "frameSequence": 90,
    "width": 1920,
    "height": 1080,
    "rowBytes": 7680,
    "pixelFormat": "BGRA8888",
    "cursorSequence": 3,
    "cursorImageSequence": 3
  }
]

An arm64e DCP pipe uses sourceName "Apple DCP/IOMFB". A machine with no display sources returns [].

snapshotFramebuffer

{
  "vmId": "f1e6a94c-6ee2-4c9b-8a44-9be7b2ca6cf1",
  "preferDeviceFramebuffer": true,
  "afterSequence": 89,
  "afterCursorImageSequence": 3,
  "holdsFrame": false
}

preferDeviceFramebuffer defaults to true. holdsFrame defaults to false. afterMemoryFrameToken is optional.

JSON result, then a kind-1 frame of byteLength bytes:

{
  "encoding": "mxfb0001",
  "byteLength": 52,
  "selection": {
    "name": "device-frame",
    "provenanceIsInferred": false
  }
}

That pair is what the host unit test encodes for a 1x1 BGRA frame. selection.name is one of:

name	Inferred?
`no-session`	no
`device-frame`	no
`device-unchanged`	no
`device-frame-holding-no-picture`	no
`memory-framebuffer-sole-surface`	no
`memory-framebuffer-holds-pixels`	yes
`boot-console-has-been-written`	yes
`display-framebuffer-untested`	yes
`display-framebuffer-guest-stated`	no
`boot-console-guest-stated`	no
`no-firmware-memory-map`	no
`nothing-presented`	no

Inferred means the host chose a guest-memory surface by testing pixels, not by reading a present-source the guest stated.

snapshotDisplaySource

{
  "vmId": "f1e6a94c-6ee2-4c9b-8a44-9be7b2ca6cf1",
  "identity": { "kind": "engine", "id": 0 },
  "afterSequence": 1,
  "afterCursorImageSequence": 0
}

Same MXFB0001 JSON result, without selection (the caller already named the source).

MXFB0001 envelope

The binary attachment bytes are the envelope framebuffer_wire already uses for the UI:

MXFB0001          8 bytes magic
u32le             header length
header JSON       that many bytes
payload           pixel runs the header addresses

A present 2x1 BGRA frame from the host test fixture (sequence: 7, base_address: "0x0000000000010000", row_bytes: 8) has this header:

{
  "present": true,
  "selection": {
    "name": "device-frame",
    "provenanceIsInferred": false
  },
  "frame": {
    "sequence": 7,
    "baseAddress": "0x0000000000010000",
    "width": 2,
    "height": 1,
    "rowBytes": 8,
    "pixelFormat": "BGRA8888",
    "bytes": { "offset": 0, "length": 8 },
    "damage": [],
    "cursor": null
  }
}

present: false with frame: null is a source that produced nothing for this request. That is distinct from a frame whose payload length is 0.

memoryFrameToken appears on frame only when the host supplied one. Pass it back as afterMemoryFrameToken on the next snapshotFramebuffer if you are polling the firmware framebuffer.