높은 DPI

고해상도 디스플레이(망막 디스플레이라고도 함)는 물리적 크기(mm)에 비해 해상도(픽셀)가 높은 디스플레이로, 픽셀 밀도 또는 인치당 도트 수(DPI)가 높습니다. 해상도 증가는 더 많은 콘텐츠(더 많은 창, 더 큰 창 크기)가 아니라 화면에 더 자세한 콘텐츠(더 부드러운 텍스트, 더 자세한 아이콘)를 제공하는 데 사용됩니다.

Qt는 모든 플랫폼에서 높은 DPI 디스플레이를 지원하며, 플랫폼의 차이를 추상화하는 통합 API를 제공합니다. Qt Widgets 및 Qt Quick 과 같은 상위 레벨 API를 사용할 때 Qt는 디스플레이 해상도를 자동으로 고려하며, 애플리케이션은 이미지 및 아이콘과 같은 고해상도 에셋만 제공하기만 하면 됩니다. 플랫폼의 사용자 환경 설정 변경 사항은 자동으로 반영됩니다.

저수준 그래픽 드로잉(예: OpenGL 코드)은 높은 DPI를 인식해야 하지만 크로스 플랫폼 Qt API를 사용하여 플랫폼의 디스플레이 해상도에 대해 알아낼 수 있습니다.

개념 모델

Qt는 애플리케이션 좌표계가 디스플레이 장치의 해상도와 독립적인 모델을 사용합니다. 애플리케이션은 기기에 독립적인 픽셀로 작동하며, 이 픽셀은 기기 픽셀 비율이라고 하는 배율을 통해 디스플레이의 물리적 픽셀에 매핑됩니다. 배율은 1.0 또는 2.0 과 같이 부동 소수점 숫자로 표시되거나 1x 및 2x 과 같이 비공식적으로 표시됩니다.

예를 들어 QWindow 또는 QWidget 을 만들고 크기를 200x200으로 설정하면 일반 밀도 디스플레이(디바이스 픽셀 비율 1.0)에서는 200x200 디스플레이 픽셀을 커버하지만 고밀도 디스플레이(디바이스 픽셀 비율 2.0)에서는 400x400 픽셀을 커버합니다.

이 모델은 위젯 및 아이템 지오메트리, 이벤트 지오메트리, 데스크톱, 창 및 화면 지오메트리, 애니메이션 속도를 포함하여 상위 수준 Qt GUI, 위젯 및 퀵 API의 대부분의 유닛에 적용됩니다.

드로잉

Qt는 QPainter 와 같은 드로잉 API를 사용하거나 Qt Quick 에서 그래픽 프리미티브나 텍스트를 렌더링할 때 자동으로 높은 DPI 디스플레이의 증가된 밀도를 활용합니다.

결과적으로 애플리케이션은 애플리케이션이 실행될 디스플레이 밀도를 고려할 필요 없이 하나의 통합된 좌표계에서 작동할 수 있습니다.

그러나 OpenGL과 같은 하위 수준의 드로잉 API를 사용하는 경우 애플리케이션은 디스플레이의 디바이스 픽셀 비율을 고려해야 합니다. 이는 QWindow::devicePixelRatio()(디스플레이 간에 이동할 때 창의 디바이스 픽셀 비율 추적)와 같이 창별로 사용하거나 QScreen::devicePixelRatio()와 같이 디스플레이별로 사용할 수 있습니다.

QImage 및 QPixmap 같은 이미지 버퍼는 원시 픽셀을 나타내므로 앞서 설명한 디바이스 독립 좌표계에서 작동하지 않습니다. 디바이스 픽셀 비율이 2.0인 400x400 크기의 QImage 는 고밀도(2배) 디스플레이에서는 200x200 QWindow 에 적합하며, 일반 밀도(1배) 디스플레이를 대상으로 하는 경우 그리는 동안 자동으로 200x200으로 축소됩니다. 자세한 내용은 Drawing High Resolution Versions of Pixmaps and Images 을 참조하세요.

이미지 자산

고DPI 디스플레이의 증가된 픽셀 밀도를 활용하려면 애플리케이션에 고DPI 버전의 정적 이미지 자산도 포함되어야 합니다. 이는 고밀도 에셋에 특별한 명명 규칙(예: logo@2x.png)을 사용하고 일반 밀도 이미지와 고밀도 이미지를 모두 QIcon 에 로드하면 됩니다. Qt는 런타임에 대상 디스플레이에 가장 적합한 표현을 자동으로 선택합니다. 자세한 내용은 High DPI Icons 을 참조하십시오.

디바이스 독립적 화면 지오메트리

Qt 애플리케이션은 일반적으로 디바이스 독립 픽셀로 작동합니다. 여기에는 애플리케이션에 보고되는 창과 화면 지오메트리가 포함됩니다.

즉, QScreen::geometry()는 화면의 실제 픽셀 수나 운영 체제에서 보고한 픽셀 크기를 반환하지 않을 수 있습니다. 이는 가상 데스크톱 지오메트리에 영향을 미칩니다:

최신 데스크톱 운영 체제는 일반적으로 연결된 모든 화면에 대해 하나의 공유 좌표계를 생성하고 사용자가 일반적으로 구성 대화 상자를 통해 물리적 화면 설정에 맞게 화면 위치를 지정할 수 있도록 합니다. 이 위치 지정이 Qt의 디바이스 독립 픽셀에 해당하는 좌표계에서 수행되는 경우(예: macOS), QScreen 지오메트리는 기본 화면 레이아웃과 일치합니다. 위치 지정이 화면의 물리적 픽셀로 수행되는 경우(예: Windows), Qt의 화면 지오메트리 처리는 어떤 화면에서도 사용되지 않는 가상 데스크탑 지오메트리에 "간격"을 발생시킬 수 있습니다.

구체적으로, Qt는 화면 크기를 조절하지만(양수 배율의 경우 "작은" 화면이 됩니다) 화면 위치는 변경하지 않습니다. 이렇게 하면 화면 섬 유형의 가상 데스크탑 지오메트리가 생성됩니다.

애플리케이션 코드는 한 화면 바로 옆과 바깥쪽의 위치를 인접한 화면의 유효한 위치로 가정해서는 안 됩니다. 대신 QGuiApplication::screens()를 사용하여 화면 목록을 가져와서 이 목록을 사용하여 사용 가능한 화면 지오메트리를 추론하세요.

구성

최종 사용자는 디스플레이 하드웨어에 맞게 또는 시청 거리와 개인 선호도를 고려하여 DPI 또는 배율 설정을 조정하고 싶을 수 있습니다. 이러한 조정은 플랫폼의 기본 디스플레이 설정을 사용하여 수행해야 모든 애플리케이션이 동일한 DPI 또는 배율 값에 동의할 수 있습니다. Qt는 최종 사용자가 Qt의 높은 DPI 지원의 동작을 구성할 수 있는 기능을 제공하지 않습니다.

운영 체제는 배율을 계수(1.5), 백분율(150%) 또는 인치당 도트 수(144 DPI)로 표시할 수 있습니다. Qt는 이를 애플리케이션에서 보이는 디바이스 픽셀 비율로 변환합니다. 후자의 경우 Qt는 "기본" DPI(예: X11의 경우 96)를 가정하고 그에 따라 결과 디바이스 픽셀 비율을 계산합니다.

최상의 결과를 얻으려면 정수 배율(예: 1.0 또는 2.0)이 선호됩니다. "배율을 25% 단위로 '반올림'해도 좋은 결과를 얻을 수 있습니다. 배율 또는 DPI를 정확한 물리적 디스플레이 DPI로 설정하면 부분 배율로 인해 시각적 결과가 좋지 않을 수 있습니다. 이 시나리오에서 애플리케이션에 시각적 아티팩트가 발생하는 경우 QGuiApplication::setHighDpiScaleFactorRoundingPolicy()를 사용하여 표시되는 배율을 제한할 수 있습니다.

플랫폼 세부 정보

다음 표에서는 다양한 플랫폼에서 높은 DPI를 구성하는 방법을 설명합니다.

X11 구성하기

Qt에 필요한 구성 입력은 화면별 논리적 DPI입니다. 현재 X11은 전역 논리적 DPI 또는 화면별 물리적 DPI를 제공합니다. 이 중 어느 것도 Qt에 정확히 필요한 것이 아니기 때문에 X11의 DPI 구성은 다른 플랫폼보다 복잡할 수 있습니다.

우분투나 쿠버투와 같은 데스크톱 환경에서는 논리적 DPI 부족에 대한 해결 방법을 구현하고 있으며, 쉽게 구성할 수 있는 높은 DPI 지원을 제공합니다. 대신 X11 DPI 설정을 수동으로 구성하려는 경우, 이 섹션에서는 Qt가 읽는 X11 설정에 대해 설명합니다.

일부 X11 구성 워크플로에서는 DPI 계산이 특정 DPI 값을 산출하도록 하기 위해 보고된 화면의 물리적 크기를 재정의하는 것이 포함됩니다. Qt는 이 워크플로우를 지원하지만, 아래 설명된 대로 옵트인해야 합니다.

정확한 구성 우선 순위는 다음과 같으며, Qt는 사용 가능한 첫 번째 옵션을 사용합니다. 동작은 사용 중인 Qt 버전에 따라 다릅니다. Qt 5 동작은 AA_EnableHighDpiScaling이 설정되어 있다고 가정합니다(이 플래그는 Qt 6에서는 필요하지 않음).

QT_USE_PHYSICAL_DPI 오버라이드

QT_USE_PHYSICAL_DPI=1로 설정하면 Qt가 무조건 RandR 물리 DPI를 사용하도록 하며, 특히 xcb_randr_screen_change_notify_event_t 구조체의 mwidth 및 mheight 필드가 사용됩니다. DPI 값은 정수로 반올림됩니다.

윈도우 설정하기

Qt는 Windows 디스플레이 배율 설정을 자동으로 사용하므로 특별한 설정이 필요하지 않습니다. 예를 들어 디스플레이가 175% 배율로 구성된 경우 Qt 앱은 해당 화면에서 1.75의 디바이스 픽셀 비율을 표시합니다.

Windows는 애플리케이션이 높은 DPI 기능을 선택하기 위해 설정하는 몇 가지 DPI인식 수준을 정의합니다. Qt 6는 기본적으로 모니터별 DPI 인식 V2입니다. 단일 글로벌 DPI를 가정하는 코드를 통합하는 경우 다른 인식 수준을 설정할 수 있습니다. 이는 qt.conf에 항목을 추가하여 수행할 수 있습니다:

[Platforms]
WindowsArguments = dpiawareness=0,1,2

테스트

qt_scale_factor

애플리케이션의 전역 배율을 제공하려면 QT_SCALE_FACTOR 환경 변수를 설정합니다.

QT_SCALE_FACTOR=2 ./myapp

이렇게 하면 모든 애플리케이션 지오메트리(디바이스 픽셀 비율 포함)에 지정된 배율이 적용되므로 사용 가능한 하드웨어와 무관하게 높은 DPI 지원을 테스트할 수 있습니다. 설정된 배율은 Qt에서 그대로 사용되며 rounding policy 의 영향을 받지 않습니다.

QWindow::devicePixelRatio()에서 반환되는 유효 디바이스 픽셀 비율은 설정된 배율과 기본 디바이스 픽셀 비율의 곱이 됩니다. 예를 들어, 2x Wayland 디스플레이에서 QT_SCALE_FACTOR=2를 설정하면 애플리케이션에 4의 장치 픽셀 비율이 표시됩니다.

DprGadget

DprGadget 테스트 애플리케이션을 사용하여 기본 구성과 Qt가 이에 반응하는 방식을 검사할 수 있습니다:

DprGadget은 QWindow::devicePixelRatio()에서 보고된 대로 창의 디바이스 픽셀 비율을 표시합니다. 또한 위도우가 있는 화면의 기본 DPI와 디바이스 픽셀 비율을 QPlatformScreen::logicalDpi() 및 QPlatformScreen::devicePixelRatio()로 보고된 대로 표시합니다.

표시된 값은 화면과 DPI가 변경되면 자동으로 업데이트되어야 하며 대화 상자는 동일한 크기를 유지해야 합니다. 그렇지 않다면 Qt 버그일 수 있습니다.

DprGradget은 Qt의 수동 테스트 스위트의 일부이며 qtbase/tests/manual/highdpi/dprgadget 에서 찾을 수 있습니다.

환경 변수 참조

이 섹션에서는 Qt에서 인식하는 높은 DPI 관련 환경 변수를 나열합니다. 알파벳 순서로 나열합니다:

• 0으로 설정하면 고DPI 스케일링을 비활성화하여 Qt 5 기본 동작으로 되돌아갑니다. 이 변수는 Wayland나 macOS와 같은 플랫폼에는 영향을 미치지 않으며, 기본 고DPI 지원을 비활성화하지 않습니다. 이 변수는 테스트 목적으로만 사용되며 영구적으로 설정하지 않는 것이 좋습니다.
• QT_FONT_DPI 전역 DPI를 설정합니다. 이전 버전과의 호환성을 위해 제공되는 레거시 환경 변수입니다.
• QT_SCALE_FACTOR 글로벌 스케일 인자를 설정합니다. 디버깅 및 테스트 목적으로 사용됩니다.
• 화면 DPI에서 계산된 스케일 팩터에 적용되는 스케일 팩터 rounding policy 를 설정합니다. 지원되는 값은 다음과 같습니다.
  • 반올림(Qt 5 기본값)
  • 패스스루(Qt 6 기본값)
• QT_SCREEN_SCALE_FACTORS 화면 배율 목록을 설정합니다. 목록은 세미콜론으로 구분된 화면 배율 계수 목록("1;1.5;2") 또는 세미콜론으로 구분된 화면=계수 항목 목록("screenA=1;screenB=1.5;screenC=2") 중 한 가지 형식일 수 있습니다. 이 환경 변수를 설정하면 Qt가 시스템 DPI 값을 사용할 수 없으므로 권장하지 않습니다.
• QT_USE_PHYSICAL_DPI Qt가 논리적 DPI 대신 물리적 DPI를 사용하도록 합니다. 논리적 DPI를 사용하는 것이 일반적으로 가장 좋은 옵션이지만, 논리적 DPI를 사용할 수 없고 물리적 DPI가 올바른 것으로 알려진 경우 이 환경 변수를 설정할 수 있습니다.

좌표계 참조

• 장치 독립 픽셀 Qt의 기본 좌표계입니다. 창, 위젯, 빠른 항목, 이벤트 및 화면 지오메트리는 모두 기기 독립 픽셀로 되어 있습니다. 일반적으로 기기 독립 픽셀은 기기 유형과 화면 밀도에 관계없이 일정한 시각적 크기를 갖습니다. 이는 일반화이지만 정확한 크기는 디바이스 구성에 따라 달라집니다.
• 디바이스 픽셀 이 좌표계는 래스터화 및 저수준 그래픽 작업(예: OpenGL API 사용 시)에 사용됩니다. 디바이스 픽셀 좌표계는 디스플레이의 물리적 좌표계와 동일한 경우가 많지만 이것이 보장되는 것은 아닙니다. 예를 들어 macOS와 우분투 모두 디스플레이 설정에 따라 추가 배율을 적용할 수 있습니다.
• 네이티브 픽셀 Win32 또는 Cocoa(macOS)와 같은 네이티브 API에서 사용하는 좌표계입니다. 플랫폼 및 화면 구성에 따라 네이티브 픽셀은 디바이스 독립 픽셀 또는 디바이스 픽셀과 동일할 수 있습니다.