고해상도(High DPI)

레티나 디스플레이라고도 알려진 고DPI 디스플레이는 물리적 크기(mm)에 비해 해상도(픽셀)가 높아 픽셀 밀도가 높거나 인치당 도트 수(DPI)가 높은 디스플레이를 말합니다. 해상도가 높아지면 화면상의 콘텐츠 양(창 수 증가, 창 크기 확대)보다는 화면상의 콘텐츠를 더 세밀하게(텍스트가 더 매끄럽게, 아이콘이 더 세밀하게) 표시하는 데 사용됩니다.

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

저수준 그래픽 렌더링(예: OpenGL 코드)은 고해상도를 고려해야 하지만, 크로스 플랫폼 Qt API를 사용하여 플랫폼의 디스플레이 해상도를 파악할 수 있습니다.

개념적 모델

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

예를 들어, QWindow 또는 QWidget 를 생성하고 크기를 200x200으로 설정하면, 표준 밀도 디스플레이(기기 픽셀 비율 1.0)에서는 200x200 디스플레이 픽셀을 차지하지만, 반면 고밀도 디스플레이(장치 픽셀 비율 2.0)에서는 400x400 픽셀을 차지합니다.

이 모델은 위젯 및 항목 기하학, 이벤트 기하학, 데스크톱, 창 및 화면 기하학은 물론 애니메이션 속도를 포함하여, 상위 수준의 Qt GUI, 위젯 및 Quick API에 있는 대부분의 단위에 적용됩니다.

그리기

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

그 결과, 애플리케이션은 실행되는 디스플레이의 밀도를 고려할 필요 없이 단일 통합 좌표계에서 작동할 수 있습니다.

그러나 OpenGL과 같은 저수준 그리기 API를 사용하는 경우, 애플리케이션은 디스플레이의 장치 픽셀 비율을 고려해야 합니다. 이는 창별로 QWindow::devicePixelRatio() (디스플레이 간 이동 시 창의 장치 픽셀 비율을 추적) 또는 디스플레이별로 QScreen::devicePixelRatio()를 통해 사용할 수 있습니다.

QImage 및 QPixmap 와 같은 이미지 버퍼는 원시 픽셀을 나타내므로, 앞서 설명한 장치 독립적 좌표계에서는 작동하지 않습니다. 크기 400x400인 QImage 는 장치 픽셀 비율(device pixel ratio)이 2.0인 경우, 고밀도(2x) 디스플레이에서는 200x200 크기의 QWindow 에 맞추어 표시되며, 표준 밀도(1x) 디스플레이를 대상으로 할 경우 그리기 과정에서 자동으로 200x200 크기로 축소됩니다. 자세한 내용은 Drawing High Resolution Versions of Pixmaps and Images 을 참조하십시오.

이미지 자산

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

장치 독립적 화면 기하 구조

Qt 애플리케이션은 일반적으로 장치 독립 픽셀(DIP) 단위로 작동합니다. 여기에는 애플리케이션에 보고되는 창 및 화면 기하 구조도 포함됩니다.

즉, ` QScreen::geometry()`가 화면의 물리적 픽셀 수나 운영 체제에서 보고하는 픽셀 크기를 반환하지 않을 수도 있습니다. 이는 가상 데스크톱 기하 구조에 다음과 같은 영향을 미칩니다:

최신 데스크톱 운영 체제는 일반적으로 연결된 모든 화면에 대해 하나의 공유 좌표계를 생성하며, 사용자가 (대개 설정 대화 상자를 통해) 물리적 화면 구성에 맞춰 화면의 위치를 조정할 수 있도록 합니다. 이러한 위치 지정이 Qt의 장치 독립 픽셀과 동등한 좌표계(macOS의 경우처럼)에서 이루어진다면, QScreen 의 기하 구조는 기본 화면 레이아웃과 일치합니다. Qt Positioning이 화면의 물리적 픽셀을 기준으로 이루어지는 경우(Windows 등), Qt가 화면 기하 구조를 처리하는 방식 때문에 어떤 화면에서도 사용되지 않는 빈 공간이 가상 데스크톱 기하 구조에 생길 수 있습니다.

구체적으로, Qt는 화면 크기를 조정하지만(양수 배율의 경우 화면이 “더 작아짐”), 화면 위치는 변경하지 않습니다. 이로 인해 ‘화면 섬’ 형태의 가상 데스크톱 기하 구조가 생성됩니다.

애플리케이션 코드는 한 화면 바로 옆에 위치하지만 그 화면 바깥쪽에 있는 위치가 인접한 화면에서 유효한 위치라고 가정해서는 안 됩니다. 대신, ` QGuiApplication::screens()`를 사용하여 화면 목록을 가져온 다음, 해당 목록을 바탕으로 사용 가능한 화면 기하 구조를 파악해야 합니다.

구성

디스플레이 하드웨어에 맞추거나, 시청 거리 및 개인 취향을 고려하여 DPI 또는 배율 설정을 조정하고 싶을 수 있습니다. 이러한 조정은 플랫폼의 기본 디스플레이 설정을 사용하여 수행해야 하며, 이를 통해 모든 애플리케이션이 동일한 DPI 또는 배율 값을 사용하도록 해야 합니다. Qt는 Qt의 고해상도(high-DPI) 지원 동작을 구성할 수 있는 최종 사용자용 기능을 제공하지 않습니다.

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

최상의 결과를 얻으려면 정수 스케일 계수(예: 1.0 또는 2.0)를 사용하는 것이 좋습니다. 배율 계수를 25% 단위로 “반올림”하는 것도 좋은 결과를 얻을 수 있습니다. 배율 계수나 DPI를 물리적 디스플레이의 정확한 DPI 값으로 설정하면 소수점 단위의 스케일링이 발생하여 시각적으로 만족스럽지 않은 결과가 나올 수 있습니다. 이러한 상황에서 애플리케이션에 시각적 아티팩트가 발생하는 경우, ` QGuiApplication::setHighDpiScaleFactorRoundingPolicy()`를 사용하여 인식하는 배율 계수를 제한할 수 있습니다.

플랫폼 세부 정보

다음 표는 다양한 플랫폼에서 고해상도(High-DPI)를 구성하는 방법을 설명합니다:

X11 구성

Qt에 필요한 구성 정보는 화면별 논리 DPI입니다. 현재 X11은 전역 논리 DPI 또는 화면별 물리 DPI 중 하나만 제공합니다. 이 둘 모두 Qt가 정확히 필요로 하는 것이 아니므로, X11에서의 DPI 구성은 다른 플랫폼보다 더 복잡할 수 있습니다.

Ubuntu 및 Kubuntu와 같은 데스크톱 환경은 논리적 DPI의 부재를 해결하기 위한 우회 방법을 구현하여, 쉽게 구성할 수 있는 고해상도 DPI 지원을 제공합니다. 대신 X11 DPI 설정을 수동으로 구성하려는 경우, 이 섹션에서는 Qt가 어떤 X11 설정을 참조하는지 설명합니다.

일부 X11 구성 워크플로에서는 DPI 계산 결과가 특정 DPI 값을 산출하도록 화면의 보고된 물리적 크기를 재정의하기도 합니다. Qt는 이 워크플로를 지원하지만, 아래에서 설명하듯이 이를 사용하려면 수동으로 활성화해야 합니다.

정확한 구성 우선순위는 다음과 같으며, Qt는 사용 가능한 첫 번째 옵션을 사용합니다.

X11에서 물리적 DPI 사용

Qt가 논리적 DPI 대신 RandR 물리적 DPI를 무조건 사용하도록 하려면 QT_USE_PHYSICAL_DPI=1 를 설정하십시오. 그러면 Qt는 xcb_randr_screen_change_notify_event_t 구조체의 mwidth 및 mheight 필드를 읽고, 결과 DPI 값을 정수로 반올림합니다.

이는 논리적 DPI를 사용할 수 없고 디스플레이의 물리적 DPI가 정확한 것으로 알려진 경우에 유용합니다. 환경 변수 참조도 참조하십시오.

Windows 구성

Qt는 Windows 디스플레이 확대/축소 설정을 자동으로 사용하므로 별도의 설정이 필요하지 않습니다. 예를 들어, 디스플레이가 175% 확대/축소 비율로 설정된 경우, Qt 애플리케이션은 해당 화면에서 장치 픽셀 비율을 1.75로 인식합니다.

Windows는 여러 가지 DPI 인식 수준을 정의하며, 애플리케이션은 이를 설정하여 고해상도(DPI) 기능을 사용할 수 있습니다. Qt 6은 기본적으로 ‘모니터별 DPI 인식 V2’ 모드를 사용합니다. 단일 전역 DPI를 가정하는 코드를 통합하는 경우, 다른 인식 수준을 설정해야 할 수 있습니다. 이를 위해 qt.conf 파일에 다음 내용을 추가하십시오:

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

테스트

고해상도(High-DPI) 지원을 개발하거나 디버깅할 때, 특정 하드웨어에 의존하는 것은 종종 비실용적입니다. Qt는 다양한 배율 계수를 시뮬레이션하는 환경 변수와, Qt가 현재 디스플레이 구성을 어떻게 해석하는지 확인하기 위한 테스트 애플리케이션을 제공합니다.

QT_SCALE_FACTOR

QT_SCALE_FACTOR 환경 변수를 설정하여 애플리케이션에 전역 스케일 계수를 지정하십시오.

예:

QT_SCALE_FACTOR=2 ./myapp

이렇게 하면 모든 애플리케이션 지오메트리(디바이스 픽셀 비율 포함)가 지정된 배율로 조정되므로, 사용 가능한 하드웨어와 무관하게 고해상도(High-DPI) 지원을 테스트할 수 있습니다.

설정된 스케일 팩터는 Qt에서 그대로 사용되며, rounding policy 의 영향을 받지 않습니다.

QWindow::devicePixelRatio() 함수가 반환하는 유효한 장치 픽셀 비율은 설정된 배율과 네이티브 장치 픽셀 비율의 곱입니다. 예를 들어, 2x Wayland 디스플레이에서 QT_SCALE_FACTOR=2 로 설정하면 애플리케이션은 장치 픽셀 비율을 4로 인식합니다.

DprGadget 테스트 애플리케이션

DprGadget 테스트 애플리케이션을 사용하여 기본 구성을 확인하고, Qt가 이에 어떻게 반응하는지 살펴볼 수 있습니다:

DprGadget은 QWindow::devicePixelRatio()에서 반환된 값을 바탕으로 창의 장치 픽셀 비율을 표시합니다. 또한 QPlatformScreen::logicalDpi()와 QPlatformScreen::devicePixelRatio()에서 반환된 값을 바탕으로, 창이 표시된 화면의 네이티브 DPI와 장치 픽셀 비율을 표시합니다.

화면이나 DPI가 변경되면 표시된 값이 자동으로 업데이트되어야 하며, 대화 상자의 크기는 동일하게 유지되어야 합니다. 그렇지 않은 경우 Qt 버그일 가능성이 있습니다.

DprGadget은 Qt Test의 수동 테스트 모음의 일부이며, qtbase/tests/manual/highdpi/dprgadget 에서 확인할 수 있습니다.

환경 변수 참조

이 섹션에서는 Qt에서 인식하는 고해상도(High-DPI) 관련 환경 변수를 나열합니다. 알파벳 순으로 정리했습니다:

좌표계 참조

다음 좌표계는 Qt의 API 전반에 걸쳐 사용됩니다. 대부분의 애플리케이션 코드는 장치 독립 픽셀(DIP)을 기준으로 작동하며, 다른 좌표계들은 주로 저수준 그래픽 및 플랫폼 통합과 관련이 있습니다: