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_PATH_SOURCE_INFO modeInfoIdx 멤버에서 참조하는 표시 원본 및 대상 모드 정보(DISPLAYCONFIG_MODE_INFO)와 pathArray의 경로 정보 요소 DISPLAYCONFIG_PATH_TARGET_INFO 배열입니다. 이 매개 변수는 NULL일 수 있습니다.
[in] flags
이 함수의 동작을 나타내는 플래그 값의 비트 OR입니다. 이 매개 변수는 다음 값 중 하나이거나 다음 값의 조합일 수 있습니다. 0이 잘못되었습니다. 유효한 플래그 조합에 대한 설명은 아래를 참조하세요.
다음 목록에는 Flags 매개 변수에 대한 유효한 값 조합이 포함되어 있습니다.
- SDC_APPLY 또는 SDC_VALIDATE 모두 설정해야 하지만 둘 다 설정해야 하는 것은 아닙니다.
- SDC_USE_SUPPLIED_DISPLAY_CONFIG 또는 SDC_TOPOLOGY_XXX 조합을 설정해야 합니다. SDC_USE_SUPPLIED_DISPLAY_CONFIG SDC_TOPOLOGY_XXX 플래그로 설정할 수 없습니다.
- SDC_NO_OPTIMIZATION SDC_APPLY 사용하여 설정할 수 있습니다.
- SDC_ALLOW_CHANGES 다른 유효한 조합으로 허용됩니다.
- SDC_SAVE_TO_DATABASE SDC_USE_SUPPLIED_DISPLAY_CONFIG 사용하여 설정할 수 있습니다.
- SDC_PATH_PERSIST_IF_REQUIRED SDC_USE_SUPPLIED_DISPLAY_CONFIG 또는 SDC_TOPOLOGY_SUPPLIED 사용할 수 없습니다.
- SDC_FORCE_MODE_ENUMERATION SDC_APPLY 및 SDC_USE_SUPPLIED_DISPLAY_CONFIG 지정된 경우에만 유효합니다.
- SDC_TOPOLOGY_SUPPLIED 지정된 경우에만 SDC_ALLOW_PATH_ORDER_CHANGES 허용됩니다.
- SDC_TOPOLOGY_SUPPLIED 다른 SDC_TOPOLOGY_XXX 플래그와 함께 사용할 수 없습니다. 유효성 검사 문제로 인해 호출자가 이 규칙을 위반하는 경우 SetDisplayConfig 는 실패하지 않습니다. 그러나 SetDisplayConfig 는 SDC_TOPOLOGY_SUPPLIED 플래그를 무시합니다.
반환 값
함수는 다음 반환 코드 중 하나를 반환합니다.
| 반환 코드 | 설명 |
|---|---|
|
함수가 성공했습니다. |
|
지정된 매개 변수와 플래그의 조합이 잘못되었습니다. |
|
시스템에서 WDDM(Windows 디스플레이 드라이버 모델)에 따라 작성된 그래픽 드라이버를 실행하고 있지 않습니다. 함수는 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이어야 하며 연결된 크기는 0이어야 합니다. 예를 들어 SDC_TOPOLOGY_CLONE 및 SDC_TOPOLOGY_EXTEND 설정된 경우 이 함수는 가장 최근의 클론을 사용하거나 표시 경로 구성을 확장합니다. 단일 토폴로지 형식이 요청되면 해당 형식의 마지막 구성이 사용됩니다. 해당 토폴로지를 이전에 설정한 적이 없는 경우 SetDisplayConfig 는 최상의 토폴로지 논리를 사용하여 최상의 토폴로지를 찾은 다음 최상의 모드 논리를 사용하여 사용할 최상의 원본 및 대상 모드를 찾습니다. 토폴로지 플래그의 조합이 설정되었고 데이터베이스 항목이 없는 경우 다음 우선 순위가 사용됩니다. 랩톱의 경우: 복제, 확장, 내부 및 외부; 데스크톱의 경우 우선 순위는 확장한 다음 복제하는 것입니다.
호출자는 SDC_TOPOLOGY_SUPPLIED 플래그를 지정하여 SetDisplayConfig 가 가져온 경로 정보(토폴로지) 및 요청만 설정한 다음 지속성 데이터베이스에서 원본 및 대상 모드 정보를 사용함을 나타낼 수 있습니다. 호출자가 제공하는 활성 경로에 지속성 데이터베이스에 항목이 없으면 SetDisplayConfig 가 실패합니다. 이 경우 호출자가 동일한 경로 데이터를 사용하여 SetDisplayConfig 를 다시 호출하지만 SDC_USE_SUPPLIED_DISPLAY_CONFIG 플래그가 설정된 경우 SetDisplayConfig 는 최상의 모드 논리를 사용하여 원본 및 대상 모드 정보를 만듭니다. 호출자가 SDC_TOPOLOGY_SUPPLIED 지정하면 호출자는 numModeInfoArrayElements 매개 변수를 0으로 설정하고 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 포함) |
| 라이브러리 | User32.lib |
| DLL | User32.dll |
| API 세트 | ext-ms-win-ntuser-sysparams-ext-l1-1-1(Windows 10 버전 10.0.14393에 도입됨) |
참고 항목
DISPLAYCONFIG_PATH_SOURCE_INFO