DXGKDDI_VIDPN_ASSIGNTARGETMODESET callback function (d3dkmddi.h)

Article
05/26/2023

The pfnAssignTargetModeSet function assigns a target mode set to a particular target in a specified VidPN.

Syntax

DXGKDDI_VIDPN_ASSIGNTARGETMODESET DxgkddiVidpnAssigntargetmodeset;

NTSTATUS DxgkddiVidpnAssigntargetmodeset(
  [in] IN_D3DKMDT_HVIDPN hVidPn,
  [in] IN_CONST_D3DDDI_VIDEO_PRESENT_TARGET_ID VidPnTargetId,
  [in] IN_CONST_D3DKMDT_HVIDPNTARGETMODESET hVidPnTargetModeSet
)
{...}

Parameters

[in] hVidPn

A handle to a VidPN object. The VidPN manager previously provided this handle to the display miniport driver by calling DxgkDdiEnumVidPnCofuncModality or DxgkDdiRecommendFunctionalVidPn.

[in] VidPnTargetId

An integer that identifies one of the video present targets associated with the VidPN object.

[in] hVidPnTargetModeSet

A handle to the target mode set object that is to be assigned to the target identified by VidPnTargetId. The display miniport driver previously obtained this handle by calling pfnCreateNewTargetModeSet.

Return value

The pfnAssignTargetModeSet function returns one of the following values:

Return code	Description
STATUS_SUCCESS	The function succeeded.
STATUS_GRAPHICS_INVALID_VIDPN	The handle supplied in hVidPn was invalid.
STATUS_GRAPHICS_INVALID_VIDEO_PRESENT_TARGET	The identifier supplied in VidPnTargetId was invalid.
STATUS_GRAPHICS_INVALID_VIDPN_TARGETMODESET	The handle supplied in hVidPnTargetModeSet was invalid.
STATUS_GRAPHICS_PINNED_MODE_MUST_REMAIN_IN_SET	The target mode set you are attempting to assign does not contain the mode that was already pinned on the target.

Remarks

VidPN target identifiers are assigned by the display miniport driver. DxgkDdiQueryChildRelations, implemented by the display miniport driver, returns an array of DXGK_CHILD_DESCRIPTOR structures, each of which contains an identifier.

If you obtain a handle by calling pfnCreateNewTargetModeSet and then pass that handle to pfnAssignTargetModeSet, you do not need to release the handle by calling pfnReleaseTargetModeSet.

If you obtain a handle by calling pfnCreateNewTargetModeSet and then you decide not to assign the new target mode set to a target, you must release the newly obtained handle by calling pfnReleaseTargetModeSet.

Note The pfnAssignTargetModeSet function releases or does not release the target mode set object that is identified by the hVidPnTargetModeSet parameter depending on the reason that caused pfnAssignTargetModeSet to fail.

pfnAssignTargetModeSet does not release the target mode set object if pfnAssignTargetModeSet fails with an invalid input parameter (that is, fails with the STATUS_GRAPHICS_INVALID_VIDPN, STATUS_GRAPHICS_INVALID_VIDEO_PRESENT_TARGET, or STATUS_GRAPHICS_INVALID_VIDPN_TARGETMODESET error code) because the parameters that were specified were not sufficient for the operating system to determine which mode set object to release. Such invalid parameter situations indicate a gross coding error in the driver. You can fix this error by specifying the correct VidPN handle, target identifier, or VidPN target mode set handle.

pfnAssignTargetModeSet will release the target mode set object after successfully validating all of the input parameters if pfnAssignTargetModeSet fails because of one of the following reasons:

The target mode set is empty.
The target mode set does not contain a mode that is pinned in the previous mode set, if any.
The target mode set was not created for the target that is identified by VidPnTargetId.

The D3DDDI_VIDEO_PRESENT_TARGET_ID data type is defined in D3dukmdt.h.

The D3DKMDT_HVIDPN and D3DKMDT_HVIDPNTARGETMODESET data types are defined in D3dkmdt.h.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Target Platform	Desktop
Header	d3dkmddi.h (include D3dkmddi.h)
IRQL	PASSIVE_LEVEL