xdg-shell
次回以降は、実際にウィンドウを作成していきますが、まずは Wayland のプロトコルについて説明しておきます。
Wayland では、基本的なウィンドウの実装として、wl_shell がデフォルトで定義されていますが、こちらは機能が少なく、あまり実用的ではないので、拡張プロトコルとして、より機能の多い「xdg-shell」が定義されています。
GNOME では、以前は wl_shell を実装していましたが、現在は削除されており、グローバルオブジェクト内に wl_shell が含まれていないので、使用できません。
そのため、wl_shell はスキップして、xdg-shell を解説することにします。
※このように、Wayland の基本的な機能でも、実質的に使用されていないような状況であれば、サーバー側で実装が行われていない場合があるので、注意が必要です。
Wayland では、基本的なウィンドウの実装として、wl_shell がデフォルトで定義されていますが、こちらは機能が少なく、あまり実用的ではないので、拡張プロトコルとして、より機能の多い「xdg-shell」が定義されています。
GNOME では、以前は wl_shell を実装していましたが、現在は削除されており、グローバルオブジェクト内に wl_shell が含まれていないので、使用できません。
そのため、wl_shell はスキップして、xdg-shell を解説することにします。
※このように、Wayland の基本的な機能でも、実質的に使用されていないような状況であれば、サーバー側で実装が行われていない場合があるので、注意が必要です。
プロトコル
Wayland には、基本的なプロトコルとして、wl_* と名のつくインターフェイスが定義されています。
しかし、これらのプロトコルは最低限の機能しかないので、機能を拡張するために、多くの拡張プロトコルが定義されています。
2025年1月時点では、これら多くの拡張プロトコルは、まだまだ開発段階であり、数もこれからも増えていくと思われます。
Wayland の基本的なプロトコルは、wayland-client-protocol.h で定義されているため、普通にインクルードすれば使用することができます。
しかし、拡張プロトコルの場合は、インクルードファイルそのものが用意されているわけではありません。
プロトコルを定義した xml ファイルが存在するので、それを元に、開発者が wayland-scanner ツールを使って、ヘッダファイルやソースファイルを生成し、コンパイルする必要があります。
しかし、これらのプロトコルは最低限の機能しかないので、機能を拡張するために、多くの拡張プロトコルが定義されています。
2025年1月時点では、これら多くの拡張プロトコルは、まだまだ開発段階であり、数もこれからも増えていくと思われます。
Wayland の基本的なプロトコルは、wayland-client-protocol.h で定義されているため、普通にインクルードすれば使用することができます。
しかし、拡張プロトコルの場合は、インクルードファイルそのものが用意されているわけではありません。
プロトコルを定義した xml ファイルが存在するので、それを元に、開発者が wayland-scanner ツールを使って、ヘッダファイルやソースファイルを生成し、コンパイルする必要があります。
xml ファイル
Wayland では、各プロトコルの情報は、xml ファイルで定義されています。
Wayland のソースファイルを見てみると、protocol/wayland.xml に、デフォルトのプロトコルの情報が記述されています。
それを元に wayland-scanner で生成したヘッダファイルが、「wayland-client-protocol.h」となっています。
wayland-protocols に、拡張プロトコルの各 xml ファイルがあります。
Wayland のソースファイルを見てみると、protocol/wayland.xml に、デフォルトのプロトコルの情報が記述されています。
それを元に wayland-scanner で生成したヘッダファイルが、「wayland-client-protocol.h」となっています。
wayland-protocols に、拡張プロトコルの各 xml ファイルがあります。
パッケージ
拡張プロトコルの xml ファイルは、Wayland の公式サイトからダウンロードすることもできますが、各ディストリビューションのパッケージにも存在しています。
Wayland プログラムのソースコードを配布する場合は、scanner で生成したヘッダファイルやソースファイルを同梱させるか、これらのパッケージを依存パッケージとして、ビルド時に scanner で生成させます。
| Debian/Ubuntu Arch Linux | wayland-protocols |
|---|---|
| Red Hat | wayland-protocols-devel |
Wayland プログラムのソースコードを配布する場合は、scanner で生成したヘッダファイルやソースファイルを同梱させるか、これらのパッケージを依存パッケージとして、ビルド時に scanner で生成させます。
開発段階
拡張プロトコルでは、「stable (安定版)」や「unstable (不安定版)」など、開発の段階によって、グループが存在します。
定義が成熟すると、最終的に stable へと移行します。
stable 版において、機能が拡張された場合は、インターフェイス名はそのままで、バージョンが上がるため、下位互換が確立されています。
ほかの unstable 版などの場合は、開発中という扱いのため、基本的に下位バージョンとの互換性がありません。
そのため、バージョンごとにインターフェイスの名前が変わり、使用する関数の名前も、各バージョンごとに異なります。
(zxdg_exporter_v1, zxdg_exporter_v2 など)
unstable など開発版のプロトコルも、サーバーによっては実装されていますが、クライアントがそれを使用する場合は、注意が必要です。
バージョンが変わったり stable に移行した場合、インターフェイス名や関数名が変わるので、それに合わせてコード全体を書き直すか、各バージョンの処理をそれぞれ実装するといった対応が必要になるため、クライアントとしては扱いにくいものになります。
開発版のプロトコルは、stable に移行すれば、いずれサーバー側も古い実装を削除するので、最終的に使用できなくなります。
できれば、stable になってから実装するのが一番良いでしょう。
定義が成熟すると、最終的に stable へと移行します。
stable 版において、機能が拡張された場合は、インターフェイス名はそのままで、バージョンが上がるため、下位互換が確立されています。
ほかの unstable 版などの場合は、開発中という扱いのため、基本的に下位バージョンとの互換性がありません。
そのため、バージョンごとにインターフェイスの名前が変わり、使用する関数の名前も、各バージョンごとに異なります。
(zxdg_exporter_v1, zxdg_exporter_v2 など)
unstable など開発版のプロトコルも、サーバーによっては実装されていますが、クライアントがそれを使用する場合は、注意が必要です。
バージョンが変わったり stable に移行した場合、インターフェイス名や関数名が変わるので、それに合わせてコード全体を書き直すか、各バージョンの処理をそれぞれ実装するといった対応が必要になるため、クライアントとしては扱いにくいものになります。
開発版のプロトコルは、stable に移行すれば、いずれサーバー側も古い実装を削除するので、最終的に使用できなくなります。
できれば、stable になってから実装するのが一番良いでしょう。
wayland-scanner
「wayland-scanner」ツールを使うと、プロトコルを定義した xml ファイルから、コンパイルに必要なヘッダファイルやソースファイルを生成できます。
このコマンドは、Wayland の開発パッケージ内に含まれています。
▼ type (出力の種類)
<使用例>
生成したヘッダファイルには、マクロや列挙型、インライン関数などが定義されています。
生成したソースファイルには、「<name>_interface」など、バインドする時に必要なグローバル変数などが定義されています。
このコマンドは、Wayland の開発パッケージ内に含まれています。
wayland-scanner の使い方
$ wayland-scanner [option] [type] <input_file> <output_file>
▼ type (出力の種類)
| client-header | クライアント用のヘッダファイルを生成します。 出力ファイル名は、「<name>-client-protocol.h」にするのが一般的です。 |
|---|---|
| server-header | サーバー用のヘッダファイルを作成します。 |
| enum-header | 列挙型 (enum) のみを定義した、ヘッダファイルを生成します。 出力ファイル名は、「<name>-enum.h」にするのが一般的です。 |
| private-code | クライアント・サーバーの両方で必要なソースコードを生成します。 ファイル名は「<name>-protocol.c」にするのが一般的です。 |
| public-code | 同じく、ソースコードを生成します。 とりあえずは、private-code の方を使えば良さそうです。 |
<使用例>
$ wayland-scanner client-header xdg-shell.xml xdg-shell-client-protocol.h
生成したヘッダファイルには、マクロや列挙型、インライン関数などが定義されています。
生成したソースファイルには、「<name>_interface」など、バインドする時に必要なグローバル変数などが定義されています。
xdg-shell のファイルを生成
以降は、ウィンドウの表示に xdg-shell を使用するので、xdg-shell の、クライアント用のインクルードファイルと、ソースファイルを生成しておいてください。
※インクルードファイルだけではコンパイルできません。
ソースファイルを生成せずにコンパイルしようとすると、「<name>_interface が定義されていない」というエラーが出ます。
wayland-protocols パッケージをインストールした場合は、「/usr/share/wayland-protocols」ディレクトリ下に、各プロトコルの xml ファイルがあります。
xdg-shell は stable (安定版) になっているので、stable/xdg-shell ディレクトリ内にあります。
古いバージョンは、unstable/xdg-shell にあります。
※インクルードファイルだけではコンパイルできません。
ソースファイルを生成せずにコンパイルしようとすると、「<name>_interface が定義されていない」というエラーが出ます。
wayland-protocols パッケージをインストールした場合は、「/usr/share/wayland-protocols」ディレクトリ下に、各プロトコルの xml ファイルがあります。
xdg-shell は stable (安定版) になっているので、stable/xdg-shell ディレクトリ内にあります。
古いバージョンは、unstable/xdg-shell にあります。
$ wayland-scanner client-header xdg-shell.xml xdg-shell-client-protocol.h $ wayland-scanner private-code xdg-shell.xml xdg-shell-protocol.c
Doxygen
scanner で生成したヘッダファイルには、Doxygen 用のコメントが記述されているため、Doxygen を使って、関数などのドキュメントを生成することができます。
※wayland-client-core.h, wayland-cursor.h の関数に関しては、ヘッダファイル内にドキュメントが記述されていません。
これらは、公式のドキュメントの方をご覧ください。
scanner で xml ファイルからヘッダファイルを生成するシェルスクリプトと、Doxygen の設定ファイルを用意したので、良ければ使ってみてください。
Download: wayland_doxy.tar.bz2
※wayland-client-core.h, wayland-cursor.h の関数に関しては、ヘッダファイル内にドキュメントが記述されていません。
これらは、公式のドキュメントの方をご覧ください。
scanner で xml ファイルからヘッダファイルを生成するシェルスクリプトと、Doxygen の設定ファイルを用意したので、良ければ使ってみてください。
Download: wayland_doxy.tar.bz2
## include ディレクトリにヘッダファイルを生成 ## 何でもいいので引数を指定すると、/usr/include/wayland-* のヘッダファイルも対象にする $ ./header.sh 1 ## include ディレクトリのファイルから HTML ドキュメント生成 $ doxygen doxy_wayland