Qt Wayland Compositor

Qt Wayland Compositor は、Waylandプロトコルに基づくカスタムディスプレイサーバーの開発向けに、便利で強力なQMLおよびC++ APIを提供するモジュールです。ディスプレイサーバー（しばしばコンポジターと呼ばれる）は、Waylandプロトコルをサポートするクライアントアプリケーションからのコンテンツを表示します。

Waylandの設計思想は、コアプロトコルをシンプルかつ最小限に保つことです。これにより、開発者はこのコアプロトコルを、ユースケースに応じた拡張機能で拡張することができます。Qt Wayland Compositor は、デフォルトで多くの一般的な拡張機能をサポートしているほか、新しいカスタム拡張機能を作成するためのAPIも備えています。

通常、Qt Wayland Compositor で記述されたコンポジターは、より大規模なアプリケーションマネージャープロセス内のサブシステムとなります。Qt Wayland Compositor は、クライアントと通信し、そのコンテンツを画面に表示するためのAPIを提供します。 Qt Qml API には、Qt の他の部分と容易に統合できる高レベルな API が含まれており、Qt Quick を通じて便利なアニメーション、エフェクト、UI を実現できます。より低レベルのアクセスが必要な場合には、C++ API も利用可能です。

アプリケーションマネージャーでは通常、アプリケーションのライフサイクル、仮想キーボード入力、セキュリティ、プロセス間通信（IPC）などの追加機能を実装します。Qtは、他のモジュールでアプリケーションマネージャーの残りの部分を開発するために使用できるAPIを提供しています。実際、Qtは Qt Application Manager、Qt Wayland Compositor を基盤とした高レベルなQML APIを備え、カスタムコンポジターを実装できる完全なアプリケーションマネージャーも提供しています。

Waylandの詳細については、「WaylandとQt」を参照してください。

の機能Qt Wayland Compositor

Qt Wayland Compositor には、コンポジターを作成するために必要な機能が含まれています：

• クライアントコンテンツの表示および操作を行うためのQML API。Qt Quick のすべての機能と完全に統合されています。
• 低レベルでのアクセスおよび制御を行うための C++ API。
• XDG Shell や IVI Application などの一般的な拡張機能のサポート。
• カスタム拡張機能のサポートを容易に拡張するためのAPI。

環境変数とコマンドライン引数

以下は、Qt Wayland Compositor が認識する環境変数およびコマンドライン引数の不完全なリストです：

• 環境変数：
  • QT_WAYLAND_HARDWARE_INTEGRATIONコンポジターが提供すべきクライアントバッファ（ハードウェア）統合を定義します。セミコロン区切りのリストを指定できます（例: "linux-dmabuf-unstable-v1;wayland-egl"）。
  • QT_WAYLAND_CLIENT_BUFFER_INTEGRATIONコンポジターに対する QT_WAYLAND_HARDWARE_INTEGRATION（優先されます）と同じですが、クライアント側でも評価されます。クライアントが受け入れる統合は 1 つだけです。
  • QT_IVI_SURFACE_IDIVI-コンポジター環境において、クライアントのサーフェスに対する IVI サーフェス ID を指定します。
• コマンドライン引数:
  • --wayland-socket-name <name> クライアントとの通信に使用されるデフォルトのソケット名を上書きします。

Wayland コンポジターの実行

利用できないプラットフォーム固有の機能に依存していない限り、コンポジターは X11 ベースのデスクトップシステム上で容易にテストできます。これは開発中に、デバッグを簡素化したり、新機能を試す際の迅速な対応を可能にしたりする点で役立ちます。

Qt Wayland は、クライアントとサーバー間でグラフィックスバッファを共有するためのいくつかのバックエンドをサポートしています。主なものは以下の通りです:

• wayland-egl: これはデフォルトのバックエンドであり、可能な限りこれを優先すべきです。これを機能させるには、システムの OpenGL ドライバによるサポートが必要です。

QT_WAYLAND_HARDWARE_INTEGRATION 環境変数を設定することで、他のバックエンドを選択することも可能です。

また、システムですでに Wayland コンポジターが実行されている場合は、XDG_RUNTIME_DIR を別の場所を指すように設定する必要がある可能性がある点にも留意してください。その場合、コンポジターの起動時に警告が表示されます。XDG_RUNTIME_DIR は、まだ使用されていない、アクセス可能な任意の場所を指定できます。

たとえば、linux-dmabuf-v1 バックエンドを使用してfancy-compositorのサンプルを実行したい場合は、次のコマンドラインを使用できます:

% XDG_RUNTIME_DIR=~/my_temporary_runtime QT_XCB_GL_INTEGRATION=xcb_egl QT_WAYLAND_HARDWARE_INTEGRATION=linux-dmabuf-v1 ./fancy-compositor

その後、クライアント側でも同じ `XDG_RUNTIME_DIR ` を設定し、コマンドライン引数として `"-platform wayland"` を指定することで、コンポジター上でクライアントを実行できます。また、環境変数 `QT_QPA_PLATFORM ` を使用することで、クライアント側で Wayland QPA プラグインを選択することも可能です。

トラブルシューティング

複雑なコンポジターを開発している際、さらなる調査が必要な問題に遭遇することがあります。

環境変数 `WAYLAND_DEBUG ` を「1」に設定すると、Wayland ライブラリ自体のログ出力が有効になります。これは、たとえば Wayland プロトコルのカスタム拡張機能をデバッグする際に非常に役立ちます。これにより、クライアントとサーバー間でどのイベントやリクエストがやり取りされているか、およびそれらのタイムスタンプが正確に表示されます。

さらに、Qtにはqt.waylandcompositor.* およびqt.qpa.wayland.* というログカテゴリがあり、これらを設定することで追加のログ出力が可能になります。後者はWayland QPAプラグインからのログ出力を有効にするため、クライアント側で設定する必要があります。

例

Qt Wayland Compositor のサンプルを参照して、これらのAPIを使用してカスタムコンポジターを実装する方法を学んでください。

APIリファレンス

Qt Wayland Compositor はC++またはQMLから使用できます:

• Qt Wayland Compositor QML Types
• Qt Wayland Compositor C++ Classes

さらに、このモジュールは CMake 関数qt_generate_wayland_protocol_server_sources() を提供しています。

モジュールの進化

「Qt 6 への移植 -Qt Wayland Compositor」には、Qt 6 シリーズ向けに実施された、モジュールの API および機能に関する重要な変更点が記載されています。

ライセンスおよび帰属表示

Qt Wayland Compositor および Qt Wayland 統合プラグインは、The Qt Company から商用ライセンスの下で提供されています。

さらに、Qt Wayland Compositor はGNU General Public License バージョン 3 の下で提供されており、Qt Wayland 統合プラグインはGNU Lesser General Public License バージョン 3またはGNU General Public License バージョン 2 の下で提供されています。

詳細については、「Qt ライセンス」を参照してください。

Qt Wayland Compositor および Qt Wayland 統合プラグインは、以下の寛容なライセンスに基づくプロトコル定義を使用しています。