setDisplayConfig 函数 (winuser.h)
SetDisplayConfig 函数通过以独占方式在当前会话中启用指定路径来修改显示拓扑、源和目标模式。
语法
LONG SetDisplayConfig(
[in] UINT32 numPathArrayElements,
[in, optional] DISPLAYCONFIG_PATH_INFO *pathArray,
[in] UINT32 numModeInfoArrayElements,
[in, optional] DISPLAYCONFIG_MODE_INFO *modeInfoArray,
[in] UINT32 flags
);
参数
[in] numPathArrayElements
pathArray 中的元素数。
[in, optional] pathArray
要设置的所有显示路径的数组。 仅设置此数组中在 DISPLAYCONFIG_PATH_INFO 的标志成员中设置了 DISPLAYCONFIG_PATH_ACTIVE标志的路径。 此参数可以为 NULL。 活动路径在此数组中的显示顺序决定了路径优先级。 有关路径优先级顺序的详细信息，请参阅 路径优先级顺序。
[in] numModeInfoArrayElements
modeInfoArray 中的元素数。
[in, optional] modeInfoArray
显示源和目标模式信息的数组 (DISPLAYCONFIG_MODE_INFO 由 DISPLAYCONFIG_PATH_SOURCE_INFO 的 modeInfoIdx 成员引用的) ，以及 pathArray 中路径信息的DISPLAYCONFIG_PATH_TARGET_INFO元素。 此参数可以为 NULL。
[in] flags
标志值的按位 OR，指示此函数的行为。 此参数可以是下列值之一，也可以是以下值的组合：0 无效。 有关有效标志组合的说明，请参阅下文。
以下列表包含 Flags 参数的值的有效组合：
- 必须设置SDC_APPLY或SDC_VALIDATE，但不能同时设置两者。
- 必须设置SDC_USE_SUPPLIED_DISPLAY_CONFIG或SDC_TOPOLOGY_XXX的任意组合。 不能使用任何SDC_TOPOLOGY_XXX标志设置SDC_USE_SUPPLIED_DISPLAY_CONFIG。
- 只能使用 SDC_APPLY 设置SDC_NO_OPTIMIZATION。
- 允许使用任何其他有效组合SDC_ALLOW_CHANGES。
- 只能使用 SDC_USE_SUPPLIED_DISPLAY_CONFIG 设置SDC_SAVE_TO_DATABASE。
- SDC_PATH_PERSIST_IF_REQUIRED不能与SDC_USE_SUPPLIED_DISPLAY_CONFIG或SDC_TOPOLOGY_SUPPLIED一起使用。
- 仅当指定了SDC_APPLY和SDC_USE_SUPPLIED_DISPLAY_CONFIG时，SDC_FORCE_MODE_ENUMERATION才有效。
- 仅当指定了SDC_TOPOLOGY_SUPPLIED时，才允许SDC_ALLOW_PATH_ORDER_CHANGES。
- SDC_TOPOLOGY_SUPPLIED不能与任何其他SDC_TOPOLOGY_XXX标志一起使用。 由于验证问题，如果调用方违反此规则， SetDisplayConfig 不会失败。 但是， SetDisplayConfig 会忽略SDC_TOPOLOGY_SUPPLIED标志。
返回值
该函数返回以下返回代码之一。
| 返回代码 | 说明 |
|---|---|
|
函数成功。 |
|
指定的参数和标志的组合无效。 |
|
系统未运行根据 Windows 显示驱动程序模型 (WDDM) 编写的图形驱动程序。 仅在运行 WDDM 驱动程序的系统上支持 函数。 |
|
调用方无权访问控制台会话。 如果调用进程无权访问当前桌面或在远程会话上运行，则会发生此错误。 |
|
发生了未指定的错误。 |
|
函数找不到调用方未指定的源模式和目标模式的可行解决方案。 |
注解
SetDisplayConfig 函数采用具有任何指定源和目标模式信息的活动显示路径，并使用最佳模式逻辑生成任何缺失的源和目标模式信息。 然后，此函数设置完整的显示路径。
DISPLAYCONFIG_PATH_SOURCE_INFO和DISPLAYCONFIG_PATH_TARGET_INFO结构中的 ModeInfoIdx 成员用于指示是否为给定的活动路径提供源模式和目标模式。 如果为任一项DISPLAYCONFIG_PATH_MODE_IDX_INVALID索引值，则表示未指定模式信息。 它对于为给定路径指定的路径加源模式或路径加源和目标模式信息有效。 但是，在不使用源模式的情况下指定路径加目标模式是无效的。
每个源和目标标识符的源和目标模式只能在 modeInfoArray 数组中出现一次。 例如，源标识符 S1 的源模式只能在表中出现一次;如果多个路径引用同一个源，则必须使用相同的 ModeInfoIdx。
预期大多数调用方使用 QueryDisplayConfig 获取当前配置以及其他有效可能性，然后使用 SetDisplayConfig 测试和设置配置。
活动路径在 PathArray 数组中的显示顺序决定了路径优先级。
默认情况下， SetDisplayConfig 永远不会更改提供的任何路径、源模式或目标模式信息。 如果最佳模式逻辑在未更改指定的显示路径信息的情况下找不到解决方案， 则 SetDisplayConfig 将失败并ERROR_BAD_CONFIGURATION。 在这种情况下，调用方应指定SDC_ALLOW_CHANGES标志，以允许函数调整某些指定的源和模式详细信息，以允许显示路径更改成功。
如果指定的或计算的源和目标模式具有相同的尺寸， SetDisplayConfig 会自动将路径缩放设置为DISPLAYCONFIG_PPR_IDENTITY，然后再设置显示路径并将其保存在数据库中。 有关 SetDisplayConfig 如何处理缩放的信息，请参阅 缩放桌面映像。
当调用方指定SDC_USE_SUPPLIED_DISPLAY_CONFIG标志来设置克隆路径，并且路径数组中的任何源模式索引无效时， SetDisplayConfig 将确定该源中的所有源模式索引都无效。 SetDisplayConfig 使用最佳模式逻辑来确定源模式信息。
除了SDC_TOPOLOGY_SUPPLIED标志 (，有关SDC_TOPOLOGY_SUPPLIED的详细信息，请参阅以下段落) ，SDC_TOPOLOGY_XXX标志设置最后一个显示路径设置，包括该拓扑类型的源和目标模式信息。 有关有效SDC_TOPOLOGY_XXX标志组合的信息，请参阅 Flags 参数说明。 pathArray 和 modeInfoArray 参数必须为 NULL，并且其关联大小必须为零。 例如，如果设置了SDC_TOPOLOGY_CLONE和SDC_TOPOLOGY_EXTEND，则此函数使用最新的克隆或扩展显示路径配置。 如果请求单个拓扑类型，则使用该类型的最后一个配置。 如果以前从未设置过该拓扑， 则 SetDisplayConfig 使用最佳拓扑逻辑查找最佳拓扑，然后使用最佳模式逻辑查找要使用的最佳源和目标模式。 如果已设置拓扑标志的组合，并且其中没有数据库条目，则使用以下优先级。 对于笔记本电脑：克隆、扩展、内部和外部;对于桌面，优先级为先扩展，然后克隆。
调用方可以指定SDC_TOPOLOGY_SUPPLIED标志，以指示它仅设置 (拓扑) 和请求的路径信息， SetDisplayConfig 获取并使用持久性数据库中的源和目标模式信息。 如果调用方提供的活动路径在持久性数据库中没有条目， SetDisplayConfig 将失败。 在这种情况下，如果调用方再次使用相同的路径数据调用 SetDisplayConfig ，但设置了SDC_USE_SUPPLIED_DISPLAY_CONFIG标志， 则 SetDisplayConfig 将使用最佳模式逻辑来创建源和目标模式信息。 当调用方指定SDC_TOPOLOGY_SUPPLIED时，调用方必须将 numModeInfoArrayElements 参数设置为零， 将 modeInfoArray 参数设置为 NULL;但是，调用方必须为调用方所需的路径信息设置 pathArray 和 numPathArrayElements 参数。 调用方必须将此路径数据中的所有源和目标模式索引标记为无效 (DISPLAYCONFIG_PATH_MODE_IDX_INVALID) 。
下表提供了一些常见方案，其中 调用 SetDisplayConfig 以及调用方传递给 Flags 参数以实现这些方案的标志组合。
| 方案 | 标志组合 |
|---|---|
| 测试计算机上是否支持指定的显示配置 | SDC_VALIDATE |SDC_USE_SUPPLIED_DISPLAY_CONFIG |
| 设置指定的显示配置并保存到数据库 | SDC_APPLY |SDC_USE_SUPPLIED_DISPLAY_CONFIG |SDC_SAVE_TO_DATABASE |
| 设置临时显示配置 (即不会保存显示配置) | SDC_APPLY |SDC_USE_SUPPLIED_DISPLAY_CONFIG |
| 测试计算机上是否支持克隆 | SDC_VALIDATE |SDC_TOPOLOGY_CLONE |
| 设置克隆拓扑 | SDC_APPLY |SDC_TOPOLOGY_CLONE |
| 设置克隆拓扑并允许启用路径持久性（如果需要满足请求） | SDC_APPLY |SDC_TOPOLOGY_CLONE |SDC_PATH_PERSIST_IF_REQUIRED |
| 从临时模式返回到上次保存的显示配置 | SDC_APPLY|SDC_USE_DATABASE_CURRENT |
| 仅给定路径信息，使用数据库中的路径的源和目标信息设置显示配置，并忽略路径顺序 | SDC_APPLY |SDC_TOPOLOGY_SUPPLIED |SDC_ALLOW_PATH_ORDER_CHANGES |
DPI 虚拟化
此 API 不参与 DPI 虚拟化。 DEVMODE 结构中的所有大小都以物理像素为单位，与调用上下文无关。要求
| 最低受支持的客户端 | 在 Windows 7 及更高版本的 Windows 操作系统中可用。 |
| 目标平台 | 通用 |
| 标头 | winuser.h (包括 Windows.h) |
| Library | User32.lib |
| DLL | User32.dll |
| API 集 | ext-ms-win-ntuser-sysparams-ext-l1-1-1 (在 Windows 10 版本 10.0.14393 中引入) |
另请参阅
DISPLAYCONFIG_PATH_SOURCE_INFO