高DPI

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

Qt はすべてのプラットフォームで高 DPI ディスプレイをサポートしており、プラットフォームの違いを抽象化する統一 API を提供しています。Qt は、Qt Widgets やQt Quick といった、より高度な API を使用する際に、自動的にディスプレイの解像度を考慮し、アプリケーションは画像やアイコンのような高解像度のアセットを提供するだけで済みます。プラットフォームのユーザー設定の変更も自動的に反映されます。

低レベルのグラフィックス描画（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 のような画像バッファは生のピクセルを表し、その結果、前述のデバイス非依存座標系では動作しません。サイズ400x400、デバイスピクセル比2.0のQImage 、高密度(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 （）は、画面の物理的なピクセル数や、オペレーティング・システムから報告されたピクセル・サイズを返さない可能性があります。これは仮想デスクトップのジオメトリにも影響する：

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

具体的には、Qt は画面サイズを拡大縮小しますが（拡大縮小率が正の場合、画面は "小さく "なります）、画面位置は変更しません。これにより、islands-of-screens タイプの仮想デスクトップジオメトリが生成されます。

アプリケーション・コードでは、1つの画面のすぐ外側に隣接する位置が、隣接する画面の有効な位置であると仮定しないでください。その代わりに、QGuiApplication::screens （）を使用してスクリーン・リストを取得し、そのリストを使用して使用可能なスクリーン・ジオメトリを推論してください。

設定

エンドユーザーとして、ディスプレイのハードウェアに合わせて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 設定は他のプラットフォームよりも複雑になります。

UbuntuやKubntuのようなデスクトップ環境では、論理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 値は整数に丸められます。

Windows の設定

Qt は Windows のディスプレイスケール設定を自動的に使用します。例えば、ディスプレイのスケールが175%に設定されている場合、Qtアプリはその画面上で1.75のデバイスピクセル比を見ることになります。

Windows ではいくつかの DPIAwarenessレベルが定義されており、アプリケーションは高 DPI 機能にオプトインするためにこのレベルを設定します。Qt 6はデフォルトでPer-Monitor DPI Aware 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()によって報告されたウィンドウのデバイスピクセル比を表示します。さらに、DprGadgetはQPlatformScreen::logicalDpi()とQPlatformScreen::devicePixelRatio()によって報告された、ウィドウが表示されているスクリーンのネイティブDPIとデバイスピクセル比を表示します。

表示される値は、スクリーンとDPIの変更時に自動的に更新され、ダイアログは同じサイズを維持するはずです。そうでない場合は、Qtのバグかもしれません。

DprGradgetはQtのマニュアルテストスイートで、qtbase/tests/manual/highdpi/dprgadget 。

環境変数リファレンス

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

• QT_ENABLE_HIGHDPI_SCALING 0に設定すると、高DPIスケーリングが無効になります。これは Wayland や macOS のようなプラットフォームでは効果がないことに注意してください - ネイティブの高DPIサポートを無効にするものではありません。この変数はテストのみを目的としており、永続的に設定することはお勧めしません。
• QT_FONT_DPI グローバルDPIを設定します。これは後方互換性のために提供されているレガシー環境変数です。
• QT_SCALE_FACTOR グローバルなスケールファクターを設定します。デバッグとテスト用です。
• QT_SCALE_FACTOR_ROUNDING_POLICY 画面 DPI から計算されたスケールファクターに適用されるスケールファクターrounding policy を設定します。サポートされている値は次のとおりです。
  • Round (Qt 5 デフォルト)
  • PassThrough (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 が正しいことが分かっている場合に、この環境変数を設定することができます。

座標系リファレンス

• Device Independent Pixels Qt のメイン座標系です。ウィンドウ、ウィジェット、クイックアイテム、イベント、画面のジオメトリはすべてデバイス非依存ピクセルです。一般的に、デバイス非依存ピクセルは、デバイスの種類や画面の密度を問わず、視覚的なサイズは一定です。これは一般論ですが、正確なサイズはデバイスの構成によって異なります。
• デバ イ ス ピ ク セル こ の座標系は、 OpenGL API を使 う と き な ど、 ラ ス タ 化お よ び低レベルのグ ラ フ ィ ッ ク ス タ ス ク に用い ら れます。デバイスピクセル座標系は、多くの場合、ディスプレイの物理座標系と等価ですが、これは保証されていません。たとえば、macOSでもUbuntuでも、ディスプレイの設定によっては追加のスケーリングが適用されることがあります。
• ネイティブピクセル Win32やCocoa（macOS）などのネイティブAPIが使用する座標系です。プラットフォームや画面構成によっては、ネイティブピクセルはデバイス非依存またはデバイスピクセルと等価になる場合があります。