高DPI

高DPIディスプレイ（Retinaディスプレイとも呼ばれる）は、物理的なサイズ（mm）に対して解像度（ピクセル数）が高く、その結果、ピクセル密度が高く、1インチあたりのドット数（DPI）が高くなるディスプレイです。 解像度の向上は、画面上のコンテンツ量（ウィンドウ数の増加やウィンドウサイズの拡大）を増やすためではなく、画面上のコンテンツをより詳細に表示するため（テキストの滑らかさ、アイコンの精細さ）に利用されます。

Qt は、すべてのプラットフォームで高 DPI ディスプレイをサポートしており、プラットフォーム間の違いを抽象化した統一された API を提供しています。Qt では、次のような高レベルな 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 、Widgets、およびQuick APIのほとんどの単位に適用されます。

描画

Qt は、QPainter などの描画 API を使用する場合や、Qt Quick でグラフィックプリミティブやテキストをレンダリングする場合、高 DPI ディスプレイの密度の向上を自動的に活用します。

その結果、アプリケーションは、実行されるディスプレイの密度を考慮する必要なく、単一の統一された座標系で動作することができます。

ただし、OpenGL などの低レベルの描画 API を使用する場合、アプリケーションはディスプレイのデバイス ピクセル比を考慮する必要があります。これは、ウィンドウごとにQWindow::devicePixelRatio() として（ディスプレイ間でウィンドウが移動した際のデバイス ピクセル比を追跡）、またはディスプレイごとにQScreen::devicePixelRatio() として利用できます。

QImage やQPixmap などの画像バッファは生のピクセルを表すため、前述のデバイス非依存座標系では動作しません。サイズが400x400のQImage は、 デバイスピクセル比が2.0の場合、高密度（2x）ディスプレイ上では200x200のQWindow に収まりますが、標準密度（1x）ディスプレイを対象とする場合は、描画時に自動的に200x200に縮小されます。詳細については、Drawing High Resolution Versions of Pixmaps and Images を参照してください。

画像アセット

高DPIディスプレイのピクセル密度の向上を活用するには、アプリケーションに静的画像アセットの高DPIバージョンを含める必要があります。 これは、高密度アセットに特別な命名規則（例：logo@2x.png ）を使用し、通常密度の画像と高密度の画像の両方をQIcon に読み込むことで実現されます。Qt は実行時に、ターゲットディスプレイに最適な表示形式を自動的に選択します。詳細については、High DPI Icons を参照してください。

デバイス非依存の画面ジオメトリ

Qt アプリケーションは、一般的にデバイス非依存ピクセル単位で動作します。これには、アプリケーションに報告されるウィンドウおよび画面のジオメトリも含まれます。

つまり、QScreen::geometry() が返す値は、画面の物理ピクセル数や、オペレーティングシステムから報告されるピクセルサイズとは一致しない場合があります。これは仮想デスクトップのジオメトリにも影響を及ぼします:

最新のデスクトップOSでは通常、接続されたすべての画面に対して1つの共有座標系を作成し、ユーザーが（通常は設定ダイアログを介して）物理的な画面配置に合わせて画面を配置できるようにしています。この配置がQtのデバイス独立ピクセルに相当する座標系（macOSなど）で行われる場合、QScreen で取得されるジオメトリはネイティブな画面レイアウトと一致します。 Qt Positioningが画面の物理ピクセル単位で行われる場合（Windowsなど）、Qtによる画面ジオメトリの処理により、どの画面でも使用されていない仮想デスクトップのジオメトリに隙間が生じる可能性があります。

具体的には、Qtは画面サイズをスケーリングしますが（正のスケーリング係数では画面が「小さくなる」結果となります）、画面の位置は変更しません。これにより、「画面の島」のような仮想デスクトップのジオメトリが生成されます。

アプリケーションコードでは、ある画面に隣接し、かつその画面の外側にある位置が、隣接する画面上の有効な位置であると仮定してはなりません。代わりに、QGuiApplication::screens() を使用して画面リストを取得し、そのリストに基づいて利用可能な画面ジオメトリを判断してください。

設定

ディスプレイハードウェアに合わせて、あるいは視聴距離や個人の好みに合わせて、DPIやスケール設定を調整したい場合があります。これらの調整は、すべてのアプリケーションが同じDPIまたはスケール係数の値で一致するように、プラットフォームのネイティブなディスプレイ設定を使用して行う必要があります。 Qt は、Qt の高 DPI サポートの動作を設定するためのエンドユーザー向け機能を提供していません。

オペレーティングシステムは、スケール係数を倍率（1.5）、パーセンテージ（150%）、または 1 インチあたりのドット数（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 設定は他のプラットフォームよりも複雑になる可能性があります。

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はデフォルトで「Per-Monitor DPI Aware V2」に設定されています。単一のグローバルDPIを前提としたコードを組み込む場合は、別の対応レベルを設定することをお勧めします。これを行うには、qt.conf に以下を追加してください：

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

テスト

高DPI対応の開発やデバッグを行う際、特定のハードウェアに依存することは現実的でない場合がよくあります。Qtでは、さまざまなスケーリング係数をシミュレートするための環境変数と、Qtが現在のディスプレイ設定をどのように解釈しているかを確認するためのテストアプリケーションが提供されています。

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()によって報告されるウィンドウのデバイスピクセル比を表示します。さらに、QPlatformScreen::logicalDpi()およびQPlatformScreen::devicePixelRatio()によって報告される、ウィンドウが表示されている画面のネイティブDPIとデバイスピクセル比も表示します。

画面やDPIが変更されると、表示される値は自動的に更新され、ダイアログのサイズは変わらないはずです。そうでない場合は、Qtのバグである可能性があります。

DprGadget は Qt の手動テストスイートの一部であり、qtbase/tests/manual/highdpi/dprgadget で確認できます。

環境変数リファレンス

このセクションでは、Qt が認識する高 DPI 関連の環境変数を一覧表示します。アルファベット順に以下に示します：

座標系のリファレンス

Qt の API 全体で、以下の座標系が使用されています。ほとんどのアプリケーションコードはデバイス非依存ピクセルで動作しますが、その他の座標系は主に低レベルのグラフィックスやプラットフォーム統合に関連しています: