Xinerama API (Proposal)(日本語訳)

翻訳にあたって、オープンソースグループ・ジャパンの MIT ライセンスの訳を参考にした。

著者：

Jay Cotton、Sun Microsystems, Inc.
John McKernan、Sun Microsystems, Inc.
Rob Lembree、Digital Equipment Corporation
Yanjun Zhang、Sun Microsystems, Inc.
Paul Anderson、Hewlett Packard Inc.
Mark Vojkovich、The XFree86 Project, Inc.
Heather Lanigan、Hewlett Packard

本文書は、X ウィンドウ・システムで使用する TOG(The Open Group) X ライセンスに基いて配布される。同ライセンスの内容は以下の通り。

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

(以下に定める条件に従い、本ソフトウェアおよび関連文書のファイル（以下「ソフトウェア」）の複製を取得するすべての人に対し、ソフトウェアを無制限に扱うことを無償で許可する。これには、ソフトウェアの複製を使用、複写、変更、結合、掲載、頒布、サブライセンス、および/または販売する権利、およびソフトウェアを提供する相手に同じことを許可する権利も無制限に含まれる。)

(上記の著作権表示および本許諾表示を、ソフトウェアのすべての複製または重要な部分に記載するものとする。)

(ソフトウェアは「現状のまま」で、明示であるか暗黙であるかを問わず、何らの保証もなく提供される。ここでいう保証には、商品性、特定の目的への適合性、および権利非侵害についての保証も含まれるが、それに限定されるものではない。著者または著作権者は、契約行為、不法行為、またはそれ以外であろうと、ソフトウェアに起因または関連し、あるいはソフトウェアの使用またはその他の扱いによって生じる一切の請求、損害、その他の義務について何らの責任も負わないものとする。)

1. 概要

Xinerama 拡張機能は、複数のモニターを持つシステムが１つの大きなスクリーンとして機能するようにするための手段を提供するものである。ウィンドウは、複数のスクリーンに跨ることもできるし、１つのスクリーンから別のスクリーンへ移動することもできる。

Xinerama が動作するには、均質なグラフィクス環境が必要である(訳註：a homogeneous graphics environment。対義語は heterogeneous 〜)。均質な環境とは、ヴィジュアル、深さ、及びスクリーン・サイズの共通集合(全グラフィクス・カードに対して共通)が存在する環境のことである。各グラフィクス・カードには、全カードで共通して使えるヴィジュアルが少なくとも１つ存在していなければならない。こうしたヴィジュアルは、８ビットの pseudo color であったり、２４ビットの true color 等であったりする。８ビットと２４ビットのヴィジュアルの寄せ集めでもかまわないが、全てのカードが少なくとも１つの共通ヴィジュアル ID に対応している必要がある。Xinerama 拡張は、ヴィジュアル ID の最小共通集合(the intersection of lowest common set)を見つけ出して使用することになる。異なるスクリーン・サイズで Xinerama を動作させるのは望ましいことではなく、スクリーン・サイズの変更はウィンドウ・マネージャを混乱させる可能性がある。

Xinerama の目的に沿うように、(１つの)スクリーンを「単一の作業平面(work surface)として論理的に接合されたフレームバッファの一群」と定義する。

2. Xinerama の関数

関数 XineramaQueryExtension を使用することで、X サーバに対して Xinerama 拡張機能が利用可能か否かを問い合わせることができる。この拡張が利用可能であれば、戻り値として TRUE が返り、event_base と error_base にはそれぞれ、この拡張で使用されるイベント番号の先頭の番号と、この拡張で使用されるエラー番号の先頭の番号が設定される。この拡張が利用可能でなければ、戻り値として FALSE が返り、event_base と error_base の値は未定義となる。

関数 XineramaQueryVersion は、X サーバが実装している Xinerama 拡張の版番号を返すものである。版番号は、引数 major_version 及び引数 major_version に返る。この仕様においては、上位の版番号(major version)は「1」、下位の版番号(minor version)は「2」である。上位の版番号は、プロトコルに互換性のない変更が生じた場合に増加し、下位の版番号は、上方互換性のある小さな変更が生じた場合に増加する。

何も問題が起きなければ、戻り値の Status として Success が返る。

(訳註：Xinerama の仕様書のプロトコルでは、クライアントから自身の使用したいバージョンを通知し、サーバから実際に使用するバージョンが返ってくることになっている。実装上は、クライアント側の希望は Xinerama のソースコードの中で PANORAMIX_MAJOR_VERSION、PANORAMIX_MINOR_VERSION という固定値を使って指定しているので、API には戻り値を受け取る引数しかない。X11R7.7/proto/xineramaproto-1.2.1/panoramiXproto.h では、PANORAMIX_MINOR_VERSION の値は「1」であり、「2」ではない。X11R7.7/xerver/xorg-server-1.12.2/include/protocol-versions.h では、SERVER_PANORAMIX_MINOR_VERSION の値は「1」であり、「2」ではない。X11R7.7/driver 等でも「1」だったり「0」だったりして、「2」であるところは無い。令和6年11月。)

関数 XineramaActive は、ブール値(原文は「Boolean operator」)を返す。これによって、win で指定されたスクリーンにおいて Xinerama が有効か否かを判断することができる。有効であれば TRUE が返り、無効であれば FALSE が返る。無効なウィンドウを指定した場合、エラー BadWindow が発生する。

Display *display;
Window win;
XRectangle **framebuffer_rects;
int *number_framebuffers;

関数 XineramaGetData は、下記の２つのポインタを使用し、そこに各 Xinerama スクリーンにある個別のフレームバッファの情報を返す。

エラーが起きなければ、戻り値の Status として Success が返る。無効なウィンドウが指定された場合、エラー BadWindow が発生する。メモリの割り当てに失敗した場合、エラー BadAlloc が発生する。

関数 XineramaGetCenterHint は、x と y の座標を返す。この座標は、「中央」(center)に表示されることを望むウィンドウがどこに配置されるべきかを表す(どこを中央と見做して配置されるべきかを表す)。

Xinerama の中央ヒント(center hint)は、ルート・ウィンドウのプロパティでもある。このプロパティのアトムは XINERAMA_CENTER_HINT である。このプロパティの形式(format)は２つの１６ビット整数から成るものであり、X 座標が先でその後に Y 座標が続く。

全てが上手く行った場合、戻り値の Status として Success が返る。指定されたウィンドウが無効なものであった場合、エラー BadWindow が発生する。

XineramaSetCenterHint では、指定された x と y に基いて XINERAMA_CENTER_HINT アトム(で表されるプロパティ)を設定することができる。

指定されたウィンドウが無効なものであった場合、エラー BadWindow が発生する。

display	X サーバとの接続を指定する。
major_version	この拡張の上位の版番号が返る。
minor_version	この拡張の下位の版番号が返る。

framebuffer_rects	矩形の配列である。１つ１つの矩形はそれぞれのフレームバッファに対応している。配列中の矩形は、X サーバのコマンド・ラインにおいて(各フレームバッファが)指定された順序で並んでいる。
num_framebuffers	win のウィンドウによって指定されたスクリーンに対して Xinerama が管理しているフレームバッファの数である。

display	X サーバとの接続を指定する。
root_window	ルート・ウィンドウを指定する。
x	ここに x 座標の値が返る。
y	ここに y 座標の値が返る。

display	X サーバとの接続を指定する。
root_window	ルート・ウィンドウを指定する。
x	x の値
y	y の値

display	X サーバとの接続を指定。
event_base	この拡張に与えられた「先頭イベント番号」(base event)が返る。
error_base	この拡張に与えられた「先頭エラー番号」(base error)が返る。

display	X サーバとの接続を指定する。
win	ウィンドウを指定する。