IddCxAdapterDisplayConfigUpdate2 function (iddcx.h)
A remote driver can call IddCxAdapterDisplayConfigUpdate2 to allow a client to tell the server how to update the monitor configuration.
Syntax
HRESULT IddCxAdapterDisplayConfigUpdate2(
IDDCX_ADAPTER AdapterObject,
const IDARG_IN_ADAPTERDISPLAYCONFIGUPDATE2 *pInArgs
);
Parameters
AdapterObject
[in] The IDDCX_ADAPTER object of the remote adapter that the display configuration is specified for.
pInArgs
[in] Pointer to an IDARG_IN_ADAPTERDISPLAYCONFIGUPDATE2 structure containing input arguments to the function.
Return value
IddCxAdapterDisplayConfigUpdate2 returns STATUS_SUCCESS upon success; otherwise, it returns an appropriate error code.
Remarks
A remote indirect display driver can call IddCxAdapterDisplayConfigUpdate2 to set the mode, colorimetry and other values that the OS should use for a specific monitor. Only remote drivers are able to call this function.
For more information about HDR support, see IddCx version 1.10 updates.
The IDDCX_DISPLAYCONFIGPATH2 structure is defined in such a way that not all information has to be provided in every call. For example, some paths may not supply colorimetry data if the color mode is not HDR or WCG, or IddCxAdapterDisplayConfigUpdate2 could be called to only update the SDR white level if no layout changes are required.
Controlling modes (setting the IDDCX_DISPLAYCONFIGPATH2_FLAGS_MODE_VALID flag for a path) has some additional rules and clarifications:
- If any path has IDDCX_DISPLAYCONFIGPATH2_FLAGS_MODE_VALID set then all paths provided must have it set
- When IDDCX_DISPLAYCONFIGPATH2_FLAGS_MODE_VALID is provided on all paths then any currently active paths not in the path list will become inactive
- If only non-IDDCX_DISPLAYCONFIGPATH2_FLAGS_MODE_VALID flags are set then only the paths to be updated need to be present
- Depending on the color mode specified, additional data may be required for a path. The following table indicates what additional flags must be set:
| Color mode | IDDCX_DISPLAYCONFIGPATH2_FLAGS_MONITOR_COLORIMETRY_VALID | IDDCX_DISPLAYCONFIGPATH2_FLAGS_MONITOR_SDRWHITELEVEL_VALID |
|---|---|---|
| SDR | No | No |
| SDRWCG | Yes | No |
| HDR | Yes | Yes |
First versus subsequent calls to IddCxAdapterDisplayConfigUpdate2
The first time a path is included in a IddCxAdapterDisplayConfigUpdate2 call has different requirements than subsequent times. The following table outlines the requirements.
| Path field | Required in initial call for path | Can be updated after initial call | How would Windows client get the info |
|---|---|---|---|
| Mode | Yes | Yes | QueryDisplayConfig will provide client display configuration and WM_DISPLAYCHANGE is sent when display config changes; AdvancedColorInfo.CurrentAdvancedColorKind will give a color mode |
| Scale factor | Yes | Yes | Drivers can use the method used for IddCxAdapterDisplayConfigUpdate |
| Physical size | Yes if no EDID passed | No | Not needed if EDID passed |
| Colorimetry | Yes for non SDR color mode | Yes | Most fields from corresponding AdvancedColorInfo fields |
| SDR white level | Yes for HDR color mode, default is 80 nits | Yes | AdvancedColorInfo.SdrWhiteLevelInNits, see DirectX with Advanced Color on HDR/SDR displays for more information |
Behavior differences when running on Windows 11, version 22H2 September Update
Due to underlying OS functionality, the support for drivers requesting HDR and WCG color modes when running on Windows 11, version 22H2 September Update differs slightly from when running on the Windows platform release coming in 2024. A driver can use the IddCxGetVersion function to determine which OS they are running on. The following table describes which color modes a driver can request depending on the monitor descriptor previously provided to the OS:
| Edid type | 22H2 September Update possible color modes | Platform release in 2024 possible color modes |
|---|---|---|
| None | SDR, HDR | SDR, SDRWCG, HDR |
| SDR | SDR, SDRWCG | SDR, SDRWCG |
| HDR | SDR, HDR | SDR, SDRWCG, HDR |
Examples
Some examples of which paths to include in subsequent IddCxAdapterDisplayConfigUpdate2 calls follow. At the start of each scenario, a remote session has the following paths configured:
| Monitor | Resolution | Desktop position | Color mode |
|---|---|---|---|
| 1 | 1920x1080 @ 30Hz | 0,0 | SDR |
| 2 | 1024x768 @ 30Hz | 1024,0 | SDRWCG |
| 3 | 3840x2160 @ 30Hz | 0,1848 | HDR |
Scenario 1 - Change the desktop position of Monitor 3 to be left of Monitor 1
| Monitor | Flags | Details |
|---|---|---|
| 1 | IDDCX_DISPLAYCONFIGPATH2_FLAGS_MODE_VALID | No change to current mode data |
| 2 | IDDCX_DISPLAYCONFIGPATH2_FLAGS_MODE_VALID | No change to current mode data |
| 3 | IDDCX_DISPLAYCONFIGPATH2_FLAGS_MODE_VALID | Change the desktop position to -3840,0 |
Scenario 2 – Change monitor 2 from SDRWCG to SDR
| Monitor | Flags | Details |
|---|---|---|
| 1 | IDDCX_DISPLAYCONFIGPATH2_FLAGS_MODE_VALID | No change to current mode data |
| 2 | IDDCX_DISPLAYCONFIGPATH2_FLAGS_MODE_VALID | Set new color mode |
| 3 | IDDCX_DISPLAYCONFIGPATH2_FLAGS_MODE_VALID | No change to current mode data |
Scenario 3 – Change monitor 1 from SDR to HDR
| Monitor | Flags | Details |
|---|---|---|
| 1 | IDDCX_DISPLAYCONFIGPATH2_FLAGS_MODE_VALID, IDDCX_DISPLAYCONFIGPATH2_FLAGS_MONITOR_COLORIMETRY_VALID, IDDCX_DISPLAYCONFIGPATH2_FLAGS_MONITOR_SDRWHITELEVEL_VALID | Set new color mode, colorimetry and SDR white level |
| 2 | IDDCX_DISPLAYCONFIGPATH2_FLAGS_MODE_VALID | No change to current mode data |
| 3 | IDDCX_DISPLAYCONFIGPATH2_FLAGS_MODE_VALID | No change to current mode data |
Scenario 4 – Change scale factor of Monitor 2
| Monitor | Flags | Details |
|---|---|---|
| 2 | IDDCX_DISPLAYCONFIGPATH2_FLAGS_MONITOR_SCALE_FACTOR_VALID | Set new scale factor |
Scenario 5 – Change scale factor of Monitor 2 and the desktop position of Monitor 3 to be left of Monitor 1
| Monitor | Flags | Details |
|---|---|---|
| 1 | IDDCX_DISPLAYCONFIGPATH2_FLAGS_MODE_VALID | No change to current mode data |
| 2 | IDDCX_DISPLAYCONFIGPATH2_FLAGS_MODE_VALID, IDDCX_DISPLAYCONFIGPATH2_FLAGS_MONITOR_SCALE_FACTOR_VALID | No change to current mode data, set new scale factor |
| 3 | IDDCX_DISPLAYCONFIGPATH2_FLAGS_MODE_VALID | Change the desktop position to -3840,0 |
Scenario 6 – Remove Monitor 2 from the current configuration
| Monitor | Flags | Details |
|---|---|---|
| 1 | IDDCX_DISPLAYCONFIGPATH2_FLAGS_MODE_VALID | No change to current mode data |
| 3 | IDDCX_DISPLAYCONFIGPATH2_FLAGS_MODE_VALID | No change to current mode data |
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 11, version 22H2 September Update (IddCx version 1.10) |
| Header | iddcx.h |