Skip to main content
The ironrdp-displaycontrol crate implements the Display Control Virtual Channel Extension as specified in MS-RDPEDISP. This dynamic virtual channel (DVC) enables clients to request display resolution and monitor layout changes during an active RDP session.

Overview

The Display Control channel operates over the dynamic virtual channel (DVC) infrastructure and allows clients to dynamically adjust the remote desktop resolution without reconnecting. This is essential for responsive window resizing and multi-monitor configurations.

Channel Name

See: ironrdp-displaycontrol/src/lib.rs:4

Client API

DisplayControlClient

The client processor for display control operations.
See: ironrdp-displaycontrol/src/client.rs:11 Constructor:
The callback is invoked when the server sends its capabilities. The channel is not operational until capabilities are received. Key Methods:
  • ready() -> bool - Returns true if capabilities have been received
  • encode_single_primary_monitor() - Creates a monitor layout PDU for a single monitor

Core Types

DisplayControlPdu

Top-level PDU enum for display control messages:
See: ironrdp-displaycontrol/src/pdu/mod.rs:28

DisplayControlCapabilities

Server capabilities for display control:
See: ironrdp-displaycontrol/src/pdu/mod.rs:131 Constraints:
  • max_num_monitors must be less than or equal to 1024
  • max_monitor_area_factor_a must be less than or equal to 16384
  • max_monitor_area_factor_b must be less than or equal to 16384
  • max_monitor_area = max_monitor_area_factor_a * max_monitor_area_factor_b * max_num_monitors

DisplayControlMonitorLayout

Monitor layout configuration sent from client to server:
See: ironrdp-displaycontrol/src/pdu/mod.rs:213

MonitorLayoutEntry

Individual monitor configuration:
See: ironrdp-displaycontrol/src/pdu/mod.rs:354 Display Size Constraints:
  • Width: 200 to 8192 pixels (must be even)
  • Height: 200 to 8192 pixels
  • Physical dimensions: 10 to 10,000 mm
  • Desktop scale factor: 100% to 500%

Usage Example

Basic Setup

Requesting Resolution Change

Multi-Monitor Configuration

Monitor Orientation

See: ironrdp-displaycontrol/src/pdu/mod.rs:656

Device Scale Factors

See: ironrdp-displaycontrol/src/pdu/mod.rs:686

Protocol Flow

Initialization

  1. DVC channel is established using the channel name "Microsoft::Windows::RDS::DisplayControl"
  2. Server sends DisplayControlCapabilities PDU
  3. Client callback is invoked with server capabilities
  4. Client can now send DisplayControlMonitorLayout PDUs

Resolution Change Request

  1. Client detects window resize or monitor configuration change
  2. Client adjusts dimensions to valid ranges using adjust_display_size()
  3. Client creates DisplayControlMonitorLayout with new configuration
  4. Client sends PDU to server via DVC
  5. Server applies new resolution and responds with graphics updates

Validation Helpers

adjust_display_size

Adjusts width and height to be within valid ranges:
See: ironrdp-displaycontrol/src/pdu/mod.rs:438

Important Notes

Always use adjust_display_size() before creating monitor layout entries to ensure dimensions are within valid ranges. Invalid dimensions will cause encoding errors.
The primary monitor position must always be (0, 0). Attempting to position the primary monitor elsewhere will result in an error.
Exactly one monitor must be marked as primary. Layouts with zero or multiple primary monitors will be rejected.
  • ironrdp-dvc: Dynamic virtual channel infrastructure and traits
  • ironrdp-svc: Static virtual channel base types
  • ironrdp-pdu: Protocol data unit encoding/decoding

References