layout

The layout command creates and modifies MultiView layouts: the grids of surfaces and windows that MultiView configurations are built on.

Command Type	DisplayNet
Minimum Version	3.x.x

Prefer the editors in DisplayNet Manager

DisplayNet Manager's MultiView layout editor and configuration editor are the recommended way to create and edit layouts.

Usage

layout list
layout descriptions
layout <layoutname> create size <width> <height>
layout <layoutname> window <index> position <x> <y> size <width> <height> offset <x> <y> target <surface>
layout <layoutname> describe
layout <layoutname> save
layout <layoutname> rename <newname>
layout <layoutname> delete

Name first

The layout name comes before the subcommand: layout NewLayout create size 3840 2160. Using layout create NewLayout will silently fail.

On a TCI session, load the MultiView module before using layout, or the command is refused as Invalid command:

require multiview 1.1.0

Subcommands

Subcommand	Description
list	Returns a basic list of all layouts
descriptions	Returns a detailed list of all layouts, including each one's surfaces and windows
create	Creates a new layout with the given canvas size
describe	Returns the detailed description of a single layout
save	Stores the layout indefinitely, not just for the current session
rename	Renames a layout. The new name must not already be in use
delete	Deletes the layout. Refused while a MultiView configuration still uses the layout; the error names the configurations

If no subcommand is given after the layout name, the layout is modified with the arguments that follow. This is how windows are defined:

layout NewLayout window 0 position 0 0 size 1280 720 offset 0 0 target 1

Window arguments

Argument	Value	Description
window	<index>	The window to create or modify
position	<x> <y>	Placement of the window on the layout canvas
size	<width> <height>	Size of the window (also used with create for the canvas)
offset	<x> <y>	Offset of the window content
target	<surface>	The surface number the window displays. Sources are assigned to surfaces with mtv assign

Examples

Create and save a 2x2 quad layout at 1080p
layout My2x2 create size 1920 1080
layout My2x2 window 0 position 0 0 size 960 540 offset 0 0 target 1
layout My2x2 window 1 position 960 0 size 960 540 offset 0 0 target 2
layout My2x2 window 2 position 0 540 size 960 540 offset 0 0 target 3
layout My2x2 window 3 position 960 540 size 960 540 offset 0 0 target 4
layout My2x2 save

Rearrange an existing layout
layout NewLayout window 0 position 0 0 size 1280 720 offset 0 0 target 1
layout NewLayout window 1 position 1280 0 size 640 720 offset 0 0 target 2

Return value

layout list

layout list
{
  "status": "SUCCESS",
  "request_id": null,
  "result": {
    "layout": [
      { "name": "compatibility_4k_2x2" },
      { "name": "ControlRoom" },
      { "name": "New_Layout" }
    ]
  },
  "error": null
}

layout describe

describe returns one layout as a layout_description object, with the same members as an entry of layout descriptions.

layout New_Layout describe (surfaces truncated)
{
  "status": "SUCCESS",
  "request_id": null,
  "result": {
    "layout_description": {
      "name": "New_Layout",
      "width": 3840,
      "height": 2160,
      "read_only": false,
      "surfaces": [
        {
          "index": 0,
          "horizontal_position": 0,
          "vertical_position": 0,
          "width": 4096,
          "height": 2160
        },
        {
          "index": 1,
          "horizontal_position": 4160,
          "vertical_position": 0,
          "width": 2048,
          "height": 1080
        }
      ],
      "windows": []
    }
  },
  "error": null
}

layout descriptions

layout descriptions
{
  "status": "SUCCESS",
  "request_id": null,
  "result": {
    "layout_list": [
      {
        "LayoutId": "My2x2",
        "name": "My2x2",
        "width": 1920,
        "height": 1080,
        "read_only": false,
        "surfaces": [
          {
            "Id": "00f742b6-ac03-4e20-a8d9-39ad4a7e8642",
            "id": "00f742b6-ac03-4e20-a8d9-39ad4a7e8642",
            "index": 1,
            "horizontal_position": 4160,
            "vertical_position": 0,
            "width": 2048,
            "height": 1080
          },
          {
            "Id": "0457434a-ad43-4179-9457-752996765e45",
            "id": "0457434a-ad43-4179-9457-752996765e45",
            "index": 2,
            "horizontal_position": 6240,
            "vertical_position": 0,
            "width": 2048,
            "height": 1080
          }
        ],
        "windows": [
          {
            "Id": "10ef2fef-1833-4ab0-96d3-f7d3361dda0b",
            "id": "10ef2fef-1833-4ab0-96d3-f7d3361dda0b",
            "index": 0,
            "horizontal_position": 0,
            "vertical_position": 0,
            "width": 960,
            "height": 540,
            "horizontal_offset": 0,
            "vertical_offset": 0,
            "content": "VIDEO",
            "target_surface": 1
          },
          {
            "Id": "0c7b274e-b231-41a2-9091-486ecf87b463",
            "id": "0c7b274e-b231-41a2-9091-486ecf87b463",
            "index": 1,
            "horizontal_position": 960,
            "vertical_position": 0,
            "width": 960,
            "height": 540,
            "horizontal_offset": 0,
            "vertical_offset": 0,
            "content": "VIDEO",
            "target_surface": 2
          }
        ]
      }
    ]
  },
  "error": null
}

Other subcommands

layout NewLayout create size 1920 1080
{
  "status": "SUCCESS",
  "request_id": null,
  "result": null,
  "error": null
}

Notifications

In async mode, a DN_NOTIFICATION is sent whenever a layout is saved, deleted, or renamed:

Result object	Contains
layout_update	The changed layout descriptions
layout_delete	The deleted layout names
layout_rename	Objects with oldname and newname

Update

layout My2x2 save (surfaces truncated)
{
  "status": "DN_NOTIFICATION",
  "request_id": null,
  "result": {
    "layout_update": [
      {
        "LayoutId": "New_Layout",
        "name": "New_Layout",
        "width": 3840,
        "height": 2160,
        "read_only": false,
        "surfaces": [],
        "windows": [
          {
            "id": "6d1700b0-b59f-452d-9c0d-e017e1c0a10b",
            "index": 0,
            "horizontal_position": 180,
            "vertical_position": 180,
            "width": 1920,
            "height": 1080,
            "horizontal_offset": 0,
            "vertical_offset": 0,
            "content": "VIDEO",
            "target_surface": 1
          }
        ]
      }
    ]
  },
  "error": null
}

Rename

layout New_Layout rename MyLayout
{
  "status": "DN_NOTIFICATION",
  "request_id": null,
  "result": {
    "layout_rename": [
      {
        "oldname": "New_Layout",
        "newname": "MyLayout"
      }
    ]
  },
  "error": null
}

Delete

layout New_Layout delete
{
  "status": "DN_NOTIFICATION",
  "request_id": null,
  "result": {
    "layout_delete": [
      "New_Layout"
    ]
  },
  "error": null
}

REST API

Endpoint type	DisplayNet API command
Address	POST /api/displaynet/<operation>, or name the operation in the body of a POST /api/displaynet. See Sending commands.
Role	User

Subcommand	Operation	Parameters
—	layout	name action [args]*
create_dashboard	layout_create_dashboard	name [args]*
describe	layout_describe	name
descriptions	layout_descriptions	—
list	layout_list	—
save	layout_save	name [args]*

A parameter in brackets is optional. A parameter marked * takes the remainder of the command line as one string. Pass the text exactly as you would type it on the TCI interface.

See also

• mtv: build configurations on a layout and route them
• getinitdata: layout / layout_descriptions datasets