Skip to main content

​
Overview

IddCx (Indirect Display Driver Class eXtension) uses an event-driven callback model to communicate with the driver. This page documents all callback functions implemented in the Virtual Display Driver and their lifecycle.

​
Callback Lifecycle

The IddCx framework invokes callbacks in a specific sequence:

​
Driver Initialization Callbacks

​
DriverEntry

Type: DRIVER_INITIALIZE Signature: 
extern "C" NTSTATUS DriverEntry(
    _In_ PDRIVER_OBJECT  DriverObject,
    _In_ PUNICODE_STRING RegistryPath
);
Purpose: Main entry point for the driver. Initializes WDF and registers device callbacks. Source Location: Driver.cpp:2402 Responsibilities:
  • Initialize WDF driver configuration
  • Register VirtualDisplayDriverDeviceAdd callback
  • Create WDF driver object
  • Load configuration settings

​
VirtualDisplayDriverDeviceAdd

Type: EVT_WDF_DRIVER_DEVICE_ADD Signature: 
NTSTATUS VirtualDisplayDriverDeviceAdd(
    WDFDRIVER Driver,
    PWDFDEVICE_INIT pDeviceInit
);
Purpose: Called when a new display adapter device is detected. Source Location: Driver.cpp:2808 Responsibilities:
  • Configure PnP power callbacks
  • Initialize IddCx configuration structure
  • Register IddCx event callbacks
  • Create device context
  • Initialize IddCx device
Callback Registration: 
IDD_CX_CLIENT_CONFIG IddConfig;
IDD_CX_CLIENT_CONFIG_INIT(&IddConfig);

IddConfig.EvtIddCxAdapterInitFinished = VirtualDisplayDriverAdapterInitFinished;
IddConfig.EvtIddCxMonitorGetDefaultDescriptionModes = VirtualDisplayDriverMonitorGetDefaultModes;
IddConfig.EvtIddCxMonitorAssignSwapChain = VirtualDisplayDriverMonitorAssignSwapChain;
IddConfig.EvtIddCxMonitorUnassignSwapChain = VirtualDisplayDriverMonitorUnassignSwapChain;

// Version-specific callbacks (IddCx 1.8+)
if (IDD_IS_FIELD_AVAILABLE(IDD_CX_CLIENT_CONFIG, EvtIddCxMonitorSetGammaRamp)) {
    IddConfig.EvtIddCxAdapterQueryTargetInfo = VirtualDisplayDriverEvtIddCxAdapterQueryTargetInfo;
    IddConfig.EvtIddCxMonitorSetDefaultHdrMetaData = VirtualDisplayDriverEvtIddCxMonitorSetDefaultHdrMetadata;
    IddConfig.EvtIddCxParseMonitorDescription2 = VirtualDisplayDriverEvtIddCxParseMonitorDescription2;
    IddConfig.EvtIddCxMonitorQueryTargetModes2 = VirtualDisplayDriverEvtIddCxMonitorQueryTargetModes2;
    IddConfig.EvtIddCxAdapterCommitModes2 = VirtualDisplayDriverEvtIddCxAdapterCommitModes2;
    IddConfig.EvtIddCxMonitorSetGammaRamp = VirtualDisplayDriverEvtIddCxMonitorSetGammaRamp;
}

​
VirtualDisplayDriverDeviceD0Entry

Type: EVT_WDF_DEVICE_D0_ENTRY Signature: 
NTSTATUS VirtualDisplayDriverDeviceD0Entry(
    WDFDEVICE Device,
    WDF_POWER_DEVICE_STATE PreviousState
);
Purpose: Called when device enters D0 (fully powered) state. Source Location: Driver.cpp:2946 Responsibilities:
  • Initialize adapter context
  • Trigger monitor creation
  • Begin adapter initialization

​
Adapter Callbacks

​
VirtualDisplayDriverAdapterInitFinished

Type: EVT_IDD_CX_ADAPTER_INIT_FINISHED Signature: 
NTSTATUS VirtualDisplayDriverAdapterInitFinished(
    IDDCX_ADAPTER AdapterObject,
    const IDARG_IN_ADAPTER_INIT_FINISHED* pInArgs
);
Purpose: Called after IddCx completes adapter initialization. Source Location: Driver.cpp:3945 Parameters:
  • AdapterObject: Handle to the adapter
  • pInArgs: Initialization status information
Usage: 
NTSTATUS VirtualDisplayDriverAdapterInitFinished(
    IDDCX_ADAPTER AdapterObject,
    const IDARG_IN_ADAPTER_INIT_FINISHED* pInArgs
) {
    UNREFERENCED_PARAMETER(AdapterObject);
    UNREFERENCED_PARAMETER(pInArgs);
    return STATUS_SUCCESS;
}

​
VirtualDisplayDriverAdapterCommitModes / VirtualDisplayDriverAdapterCommitModes2

Type: EVT_IDD_CX_ADAPTER_COMMIT_MODES / EVT_IDD_CX_ADAPTER_COMMIT_MODES2 Signature: 
// IddCx 1.0-1.8
NTSTATUS VirtualDisplayDriverAdapterCommitModes(
    IDDCX_ADAPTER AdapterObject,
    const IDARG_IN_COMMITMODES* pInArgs
);

// IddCx 1.9+
NTSTATUS VirtualDisplayDriverEvtIddCxAdapterCommitModes2(
    IDDCX_ADAPTER AdapterObject,
    const IDARG_IN_COMMITMODES2* pInArgs
);
Purpose: Called when the OS commits a mode change. Source Location: Driver.cpp:3969, Driver.cpp:4486 Responsibilities:
  • Validate mode parameters
  • Apply display mode changes
  • Return success/failure status

​
VirtualDisplayDriverEvtIddCxAdapterQueryTargetInfo

Type: EVT_IDD_CX_ADAPTER_QUERY_TARGET_INFO (IddCx 1.8+) Signature: 
NTSTATUS VirtualDisplayDriverEvtIddCxAdapterQueryTargetInfo(
    IDDCX_ADAPTER AdapterObject,
    IDARG_IN_QUERYTARGET_INFO* pInArgs,
    IDARG_OUT_QUERYTARGET_INFO* pOutArgs
);
Purpose: Queries information about display target capabilities. Source Location: Driver.cpp:4203 Returns: Target connector type and other display target properties.

​
Monitor Callbacks

​
VirtualDisplayDriverParseMonitorDescription / VirtualDisplayDriverEvtIddCxParseMonitorDescription2

Type: EVT_IDD_CX_PARSE_MONITOR_DESCRIPTION / EVT_IDD_CX_PARSE_MONITOR_DESCRIPTION2 Signature: 
// IddCx 1.0-1.8
NTSTATUS VirtualDisplayDriverParseMonitorDescription(
    const IDARG_IN_PARSEMONITORDESCRIPTION* pInArgs,
    IDARG_OUT_PARSEMONITORDESCRIPTION* pOutArgs
);

// IddCx 1.9+
NTSTATUS VirtualDisplayDriverEvtIddCxParseMonitorDescription2(
    const IDARG_IN_PARSEMONITORDESCRIPTION2* pInArgs,
    IDARG_OUT_PARSEMONITORDESCRIPTION2* pOutArgs
);
Purpose: Parses monitor EDID and provides monitor information to the OS. Source Location: Driver.cpp:3985, Driver.cpp:4337 Responsibilities:
  • Parse EDID data from pInArgs->MonitorDescription.pData
  • Fill in monitor connector type
  • Provide monitor size information

​
VirtualDisplayDriverMonitorGetDefaultModes

Type: EVT_IDD_CX_MONITOR_GET_DEFAULT_DESCRIPTION_MODES Signature: 
NTSTATUS VirtualDisplayDriverMonitorGetDefaultModes(
    IDDCX_MONITOR MonitorObject,
    const IDARG_IN_GETDEFAULTDESCRIPTIONMODES* pInArgs,
    IDARG_OUT_GETDEFAULTDESCRIPTIONMODES* pOutArgs
);
Purpose: Provides default display modes based on monitor description. Source Location: Driver.cpp:4031 Responsibilities:
  • Return list of default display modes
  • Convert internal mode format to DISPLAYCONFIG_VIDEO_SIGNAL_INFO
  • Report number of modes available
Example Implementation: 
NTSTATUS VirtualDisplayDriverMonitorGetDefaultModes(
    IDDCX_MONITOR MonitorObject,
    const IDARG_IN_GETDEFAULTDESCRIPTIONMODES* pInArgs,
    IDARG_OUT_GETDEFAULTDESCRIPTIONMODES* pOutArgs
) {
    UNREFERENCED_PARAMETER(MonitorObject);
    UNREFERENCED_PARAMETER(pInArgs);
    
    pOutArgs->DefaultMonitorModeBufferOutputCount = 
        static_cast<UINT>(s_KnownMonitorModes2.size());
    
    if (pInArgs->DefaultMonitorModeBufferInputCount >= s_KnownMonitorModes2.size()) {
        copy(s_KnownMonitorModes2.begin(),
             s_KnownMonitorModes2.end(),
             pOutArgs->pDefaultMonitorModes);
    }
    
    return STATUS_SUCCESS;
}

​
VirtualDisplayDriverMonitorQueryModes / VirtualDisplayDriverEvtIddCxMonitorQueryTargetModes2

Type: EVT_IDD_CX_MONITOR_QUERY_TARGET_MODES / EVT_IDD_CX_MONITOR_QUERY_TARGET_MODES2 Signature: 
// IddCx 1.0-1.8
NTSTATUS VirtualDisplayDriverMonitorQueryModes(
    IDDCX_MONITOR MonitorObject,
    const IDARG_IN_QUERYTARGETMODES* pInArgs,
    IDARG_OUT_QUERYTARGETMODES* pOutArgs
);

// IddCx 1.9+
NTSTATUS VirtualDisplayDriverEvtIddCxMonitorQueryTargetModes2(
    IDDCX_MONITOR MonitorObject,
    const IDARG_IN_QUERYTARGETMODES2* pInArgs,
    IDARG_OUT_QUERYTARGETMODES2* pOutArgs
);
Purpose: Called by OS to query all supported target modes for a monitor. Source Location: Driver.cpp:4128, Driver.cpp:4425 Responsibilities:
  • Fill target mode array with supported display modes
  • Report total number of modes
  • Handle buffer size queries

​
SwapChain Callbacks

​
VirtualDisplayDriverMonitorAssignSwapChain

Type: EVT_IDD_CX_MONITOR_ASSIGN_SWAPCHAIN Signature: 
NTSTATUS VirtualDisplayDriverMonitorAssignSwapChain(
    IDDCX_MONITOR MonitorObject,
    const IDARG_IN_SETSWAPCHAIN* pInArgs
);
Purpose: Called when OS assigns a swap chain to the monitor for frame rendering. Source Location: Driver.cpp:4176 Responsibilities:
  • Create SwapChainProcessor to handle frame processing
  • Store swap chain handle in device context
  • Start frame processing thread
Example: 
NTSTATUS VirtualDisplayDriverMonitorAssignSwapChain(
    IDDCX_MONITOR MonitorObject,
    const IDARG_IN_SETSWAPCHAIN* pInArgs
) {
    auto* pContext = WdfObjectGet_IndirectDeviceContextWrapper(MonitorObject);
    pContext->pContext->AssignSwapChain(
        MonitorObject,
        pInArgs->hSwapChain,
        pInArgs->RenderAdapterLuid,
        pInArgs->hNextSurfaceAvailable
    );
    return STATUS_SUCCESS;
}

​
VirtualDisplayDriverMonitorUnassignSwapChain

Type: EVT_IDD_CX_MONITOR_UNASSIGN_SWAPCHAIN Signature: 
NTSTATUS VirtualDisplayDriverMonitorUnassignSwapChain(
    IDDCX_MONITOR MonitorObject
);
Purpose: Called when OS removes the swap chain assignment. Source Location: Driver.cpp:4191 Responsibilities:
  • Stop frame processing
  • Clean up SwapChainProcessor
  • Release resources

​
HDR and Color Callbacks (IddCx 1.8+)

​
VirtualDisplayDriverEvtIddCxMonitorSetDefaultHdrMetadata

Type: EVT_IDD_CX_MONITOR_SET_DEFAULT_HDR_METADATA Signature: 
NTSTATUS VirtualDisplayDriverEvtIddCxMonitorSetDefaultHdrMetadata(
    IDDCX_MONITOR MonitorObject,
    const IDARG_IN_MONITOR_SET_DEFAULT_HDR_METADATA* pInArgs
);
Purpose: Receives HDR metadata from the OS for the display. Source Location: Driver.cpp:4242 Responsibilities:
  • Store HDR metadata (SMPTE ST.2086)
  • Configure HDR display parameters
  • Validate metadata values

​
VirtualDisplayDriverEvtIddCxMonitorSetGammaRamp

Type: EVT_IDD_CX_MONITOR_SET_GAMMA_RAMP Signature: 
NTSTATUS VirtualDisplayDriverEvtIddCxMonitorSetGammaRamp(
    IDDCX_MONITOR MonitorObject,
    const IDARG_IN_SET_GAMMARAMP* pInArgs
);
Purpose: Receives gamma ramp data from OS for color correction. Source Location: Driver.cpp:4498 Responsibilities:
  • Apply gamma correction
  • Store gamma ramp for processing
  • Support SDR/HDR tone mapping

​
Callback Return Values

All callbacks return NTSTATUS values:
  • STATUS_SUCCESS: Operation completed successfully
  • STATUS_BUFFER_TOO_SMALL: Provided buffer is insufficient
  • STATUS_INVALID_PARAMETER: Invalid input parameters
  • STATUS_UNSUCCESSFUL: General failure

​
Threading Model

  • Most callbacks are invoked in arbitrary thread context
  • Must be thread-safe
  • Should not block for extended periods
  • Use synchronization primitives for shared data access

​
Error Handling

Callbacks should:
  1. Validate all input parameters
  2. Check buffer sizes before copying data
  3. Return appropriate NTSTATUS codes
  4. Log errors for diagnostics
  5. Gracefully handle unexpected states

​
References

  • Source File: ~/workspace/source/Virtual Display Driver (HDR)/MttVDD/Driver.cpp
  • Header File: ~/workspace/source/Virtual Display Driver (HDR)/MttVDD/Driver.h
  • IddCx Documentation: Microsoft IddCx Reference

Build docs developers (and LLMs) love

Get started for freeTalk to us