透明オーバーレイ API は、次の 3 つのピクセル転送ルーチンを提供します。
XSolarisOvlCopyPaintType - ソースドロアブルのペイント型属性に基づいて、宛先ドロアブルに不透明ポイントと透明ポイントを描画する。
XSolarisCopyAreaAndPaintType - ドロアブルの一方のペアから別のペアに領域とそのペイント型をコピーする。
XReadScreen - 指定された画面領域に表示されるカラーを戻す。
既存の Xlib ピクセル転送ルーチン XGetImage、XCopyArea、XCopyPlane も、オーバーレイウィンドウに使用できます。これらのルーチンの使用方法については、以下の節で説明します。
XSolarisOvlCopyPaintType ルーチンは、ソース矩形内の指定された矩形のペイント型情報を使用して、宛先矩形内の指定された矩形の塗りつぶし操作を制御します。ソース矩形と宛先矩形には、任意のタイプのドロアブルを指定できます。ソース矩形が透明オーバーレイの場合は、そのピクセルのペイント型属性がコピーソースとして使用され、カラー情報は無視されます。ソース矩形が他のタイプのドロアブルであれば、ルーチン内で指定されたビットプレーンはペイント型データであるかのように処理され、コピーに使用されます。この場合、ビットプレーンはビットセットを 1 つだけ持たなければなりません。
構文と引数を次に示します。
void XSolarisOvlCopyPaintType(Display *display, Drawable src, Drawable dst, GC gc, int src_x, int src_y, unsigned int width, unsigned int height, int dest_x, int dest_y, unsigned long action, unsigned long plane)
display |
X サーバーへの接続を指定する。 |
src |
ペイント型属性に関する情報を取り出すソースのドロアブル (Drawable) を指定する。 |
dst |
宛先のドロアブルを指定する。 |
gc |
GCを指定する。 |
src_x, src_y |
ソース矩形の左上隅の xy 座標をソースドロアブルの原点に対する相対座標で指定する。 |
width, height |
ソースおよび宛先の矩形の幅と高さを指定する。 |
dest_x, dest_y |
宛先矩形の左上隅の xy 座標を宛先ドロアブルの原点に対する相対座標で指定する。 |
action |
コピーするペイント型データを指定する。指定できる値は、XSolarisOvlCopyOpaque、XSolarisOvlCopyTransparent、または XSolarisOvlCopyAll のいずれか。 |
plane |
ソースが透明オーバーレイでないときにペイント型情報として使用する src ドロアブルのビットプレーンを指定する。 |
src と dst は同じスクリーンを持たなければなりません。そうしないと、BadMatch エラーが発生します。
表 6-4に、src と dst の組み合わせとその動作を示します。表の左側は src の組み合わせ、表の上側は dst の組み合わせを表します。A1〜A4 の各動作については、表に続いて説明します。
表 6-4 XSolarisOvlCopyPaintType のソース/宛先の組み合わせと動作
ソース/宛先 |
オーバーレイ |
ドロアブル |
---|---|---|
オーバーレイ |
A1 |
A2 |
ドロアブル |
A3 |
A4 |
A1 - ソースオーバーレイの不透明ピクセルに対応する宛先ピクセルは、GC の塗りつぶし属性で指定された不透明カラーで描画されます。ソースオーバーレイの透明ピクセルに対応する宛先ピクセルは、透明なペイントで描画されます。
A2 - ソースオーバーレイの不透明ピクセルに対応する宛先ピクセルは、GC の塗りつぶし属性に従って描画されます。ソースオーバーレイの透明ピクセルに対応する宛先ピクセルは、GC の同じ塗りつぶし属性に従って描画されますが、前景と背景のピクセルが交換されます。
A3 - 宛先オーバーレイのピクセルは、ソースドロアブルの plane のビット値に応じて (上記の A1 と同様に) 不透明ペイントまたは透明ペイントで描画されます。ソースの 1 というビット値は不透明ピクセルとして取り扱われ、0 というビット値は透明ピクセルとして取り扱われます。
A4 - 宛先ドロアブルのピクセルは、ソースドロアブルの plane のビット値に応じて (上記の A2 と同様に) 描画されます。ソースのビットプレーンの 1 というビット値は不透明ピクセルとして取り扱われ、0 というビット値は透明ピクセルとして取り扱われます。
action 引数は、不透明ペイント (XSolarisOvlCopyOpaque) 、透明ペイント (XSolarisOvlCopyTransparent) 、それら両方 (XSolarisOvlCopyAll) のいずれをコピー対象とするかを指定します。これによって、クライアントは不透明ペイントまたは透明ペイントを累積することができます。
ソース矩形の一部が、隠れたりソースドロアブルの境界外部にある場合、サーバーは XCopyArea と同じセマンティクスを使用して Expose イベントを生成します。
このルーチンで使用される GC 構成要素は、function、plane-mask、fill-style、subwindow-mode、graphics-exposures、clip-x-origin、clip-y-origin、clip-mask です。また、GC モードに依存する構成要素として、foreground、background、tile、stipple、tile-stipple-x-origin、tile-stipple-y-origin が使用される場合もあります。
このルーチンで発生する可能性のあるエラーは、BadDrawable、BadGC、BadMatch、BadValue です。
XSolarisCopyAreaAndPaintType ルーチンは、カラー情報のソースとなるドロアブルの指定された領域を、カラー情報の宛先イメージとなるドロアブルの指定された領域にコピーします。宛先イメージとなるドロアブルがオーバーレイでなければ、ペイント型情報のソースとなるドロアブル内で指定されたペイント型情報に従って、ペイント型情報の宛先イメージとなるドロアブルの指定された領域も塗りつぶします。
XSolarisOvlCopyAreaAndPaintType ルーチンを使用すれば、カラーまたはペイント型の情報が格納されているクライアントのメモリー空間内のイメージと、指定されたオーバーレイウィンドウの矩形とを結合することができます。その場合は、最初にイメージとペイント型のデータをサーバーに移動し、XPutImage を使用して、適切なデプスの 2 つのピクセルマップにデータをコピーします。次に、カラーとペイント型のドロアブルを指定した XSolarisOvlCopyAreaAndPaintType を呼び出して、情報をオーバーレイにコピーします。
このルーチンを使用すれば、特定のドロアブルからピクセル情報 (カラーとペイント型の情報) を取り出すこともできます。その場合は、最初に 2 つの分離可能な宛先ドロアブルを指定する XSolarisOvlCopyAreaAndPaintType を呼び出します。次に、各ドロアブルに対して XGetImage を呼び出し、サーバーからクライアントのメモリー空間にデータを転送します。
XSolarisCopyAreaAndPaintType の構文と引数を次に示します。
void XSolarisOvlCopyAreaAndPaintType(Display * display, Drawable colorsrc, Drawable painttypesrc, Drawable colordst, Drawable painttypedst, GC colorgc, GC painttypegc, int colorsrc_x, int colorsrc_y, int painttypesrc_x, int painttypesrc_y, unsigned int width, unsigned int height, int colordst_x, int colordst_y, int painttypedst_x, int painttypedst_y, unsigned long action, unsigned long plane)
display |
X サーバーへの接続を指定する。 |
colorsrc |
カラー情報のソースとなるドロアブル。colorsrc として、任意のデプスのドロアブルまたはオーバーレイウィンドウを指定できる。 |
painttypesrc |
ペイント型情報のソースとなるドロアブル。painttypesrc として、任意のドロアブルまたはオーバーレイウィンドウを指定できる。painttypesrc がオーバーレイウィンドウでない場合、plane で指定された painttypesrc のビットプレーンはペイント型データであるかのように処理され、コピーに使用される。この場合、plane は 1 つのビットセットを持たなければならない。 |
colordst |
カラー情報の宛先となるドロアブル。 |
painttypedst |
ペイント型情報の宛先となるドロアブル。colordst がオーバーレイである場合、このドロアブルは無視される。 |
colorgc |
カラー情報のコピーに使用する GC。 |
painttypegc |
painttypedst 内の領域の描画に使用する GC。colordst/painttypedst がオーバーレイである場合、この GC は無視される。 |
colorsrc_x colorsrc_y |
カラー情報のソース矩形の左上隅の XY 座標を、カラー情報のソースドロアブルの原点に対する相対座標で指定する。 |
painttypesrc_x painttypesrc_y |
ペイント型情報のソース矩形の左上隅の XY 座標を、ペイント型情報のソースドロアブルの原点に対する相対座標で指定する。 |
width, height |
ソースおよび宛先の矩形の幅と高さをピクセル単位で指定する。 |
colordst_x colordst_y |
カラー情報の宛先矩形の左上隅の XY 座標を、カラー情報の宛先ドロアブルの原点に対する相対座標で指定する。 |
painttypedst_x painttypedst_y |
ペイント型情報の宛先矩形の左上隅の XY 座標を、ペイント型情報の宛先ドロアブルの原点に対する相対座標で指定する。colordst/painttypedst がオーバーレイである場合は、colordst_x と colordst_y が使用される。 |
action |
どのペイント型データをコピーするかを指定する。指定できる値は、XSolarisOvlCopyOpaque、XSolarisOvlCopyTransparent、XSolarisOvlCopyAll のいずれか。 |
plane |
painttypesrc がオーバーレイでないときに、ペイント型情報として使用する painttypesrc のソースビットプレーンを指定する。 |
colordst として任意のドロアブルを指定できますが、colorsrc と同じデプスで同じルートを持たないと、BadMatch エラーが発生します。colordst がオーバーレイの場合は、painttypedst が無視され、それ以外の場合は painttypedst として任意のタイプのドロアブルを指定できます。
表 6-5 に、ソースと宛先の組み合わせとそれらの動作を示します。表の左側は colorsrc/paittypesrc の組み合わせ、表の上側は colordst/painttypedst の組み合わせを表します。A1〜A8 の各動作については、表に続いて説明します。表の中で「不可能」と記載された箇所は、colordst がオーバーレイの場合は painttypedst が無視されるために、その組み合わせが不可能であることを示します。
表 6-5 XSolarisOvlCopyAreaAndPaintType のソース/宛先の組み合わせと動作
|
オーバーレイ/オーバーレイ |
オーバーレイ/ドロアブル |
ドロアブル/オーバーレイ |
ドロアブル/ドロアブル |
---|---|---|---|---|
オーバーレイ/オーバーレイ |
A1 |
不可能 |
A5 |
A5 |
オーバーレイ/ドロアブル |
A2 |
不可能 |
A6 |
A6 |
ドロアブル/オーバーレイ |
A3 |
不可能 |
A7 |
A7 |
ドロアブル/ドロアブル |
A4 |
不可能 |
A8 |
A8 |
A1 - painttypesrc のペイント型情報が、colorsrc から colordst にカラー情報をコピーするためのマスクとして使用されます。painttypesrc 内の不透明ピクセルに対応する colorsrc のピクセルは colordst にコピーされ、透明ピクセルに対応する colordst のピクセルは透明になります。colorsrc の透明ピクセルが colordst にコピーされる場合、実際に転送されるカラーは未定義になります。
A2 - plane で指定される painttypesrc のビットプレーンからペイント型情報が抽出される点以外は、A1 と同じです。1 というビット値は不透明ピクセルを表し、0 というビット値は透明ピクセルを表します。
A3 - オーバーレイでないドロアブルを使用してカラー情報が取得される点以外は、A1 と同じです。透明ピクセルを原因とする未定義のカラーは生じません。
A4 - A2 と同様に、 plane で指定される painttypesrc のビットプレーンからペイント型情報が抽出される点以外は、A3 と同じです。
A5 - A1 と同様に、 painttypesrc のペイント型情報が、colorsrc から colordst にカラー情報をコピーするためのマスクとして使用されます。さらに、XSolarisOvlCopyPaintType の場合のように、このペイント型情報によって painttypedst ドロアブルに対する描画が制御されます。
A6 - A2 と同様に、plane で指定される painttypesrc のビットプレーンからペイント型情報が抽出される点以外は、A5 と同じです。
A7 - カラー情報のソースの透明ピクセルを原因とする未定義のカラーが生じない点以外は、A5 と同じです。
A8 - A2 と同様に、 plane で指定される painttypesrc のビットプレーンからペイント型情報が抽出される点以外は、A7 と同じです。
action 引数は、不透明ペイント (XSolarisOvlCopyOpaque) 、透明ペイント (XSolarisOvlCopyTransparent) 、それら両方 (XSolarisOvlCopyAll) のいずれをコピー対象とするかを指定します。これによって、クライアントは不透明ペイントまたは透明ペイントを累積することができます。
XSolarisOvlCopyPaintType と同様の方法で、NoExpose イベントと GraphicsExpose イベントが生成されます。
colordst 引数にオーバーレイを指定すると、painttypedst、painttypegc、painttypedst_x、painttypedst_y の各引数はすべて無視されます。painttypegc には NULL ポインタ、painttypedst には None 値を指定できます。オーバーレイは、painttypesrc で指定される領域内のピクセルで定義されるのとまったく同じペイント型を持ちます。カラー情報をコピーしても、宛先のペイント型は影響を受けません。
このルーチンで使用される colorgc の GC 構成要素は、function、plane-mask、subwindow-mode、graphics-exposure、clip-x-origin、clip-y-origin、clip-mask です。
colordst がオーバーレイでない場合は、painttypegc の GC 構成要素として、function、plane-mask、fill-style、subwindow-mode、clip-x-origin、clip-y-origin、clip-mask が使用されます。また、GC モードに依存する構成要素として、foreground、background、tile、stipple、tile-stipple-x-origin、tile-stipple-y-origin が使用される場合もあります。
このルーチンで発生する可能性のあるエラーは、BadDrawable、BadGC、BadMatch、BadValue です。
XReadScreen は、スクリーンの矩形に表示されるカラーを戻します。このルーチンは、指定されたウィンドウの画面に表示されるカラーをアクセスします。
一部の高度な表示デバイス上では、表示されるカラーがデータの複合体として、複数の異なるフレーム記憶域に格納されており、これらのフレーム記憶域が異なるデプスやビジュアル型を持つことができます。また、アンダーレイの一部分がオーバーレイの下に見えるようなオーバーレイ/アンダーレイのウィンドウペアもあります。デプスが異なる矩形については、 XGetImage によって戻されるデータが未定義になるため、XGetImage は、ユーザーが実際に画面上で見ている画像を返すには不十分です。さらに、ピクセル情報が異なるドロアブルに存在するため、XGetImage はオーバーレイ/アンダーレイのウィンドウペアに関するピクセル情報を合成することができません。XReadScreen がこのような問題を解決します。
XReadScreen は、ピクセル情報ではなくカラー情報 (画面上に実際に表示される可視カラー) を戻します。すなわち、指定された矩形の境界内部のすべてのウィンドウに関するカラー情報を戻します。XGetImage とは違って、指定されたウィンドウのデプスとは異なるデプスを持つ下層ウィンドウやオーバラップウィンドウであっても、その可視領域について戻される情報は未定義にはならず、これらのウィンドウで実際に表示されるカラーが戻されます。
戻されるカラーは、画面上で利用できるハードウェアカラー LUT の数に制限がないと想定した場合には、表示されるカラーとなります。したがって、このカラーは理論的な表示カラーを意味します。すべてのソフトウェアカラーマップを同時に表示するのに十分な数のハードウェアカラー LUT がないと、画面上でカラーマップフラッシングが発生しますが、この場合は、戻されるカラーと実際に表示されるカラーが一致しないことがあります。
このルーチンの構文と引数を次に示します。
XImage * XReadScreen (Display *display, Window w, int x, int y, unsigned int width, unsigned int height, Bool includeCursor)
display |
X サーバーへの接続を指定する。 |
w |
スクリーンのデータが読み取られるウィンドウを指定する。 |
x, y |
矩形の左上隅の XY 座標をウィンドウ w の原点に対する相対座標で指定する。 |
width, height |
矩形の幅と高さを指定する。 |
includeCursor |
戻されるカラーにカーソルイメージを含めるかどうかを指定する。 |
w がオーバーレイウィンドウである場合、指定された矩形内に不透明なペイントが存在するすべての領域については、オーバーレイのカラー情報が戻されます。オーバーレイ内に透明なペイントが存在する領域については、アンダーレイのカラー情報が戻されます。通常、このアンダーレイは透明ペイントを含むオーバーレイウィンドウにできるため、透明ペイントを含む (x, y) 座標に関するカラー情報は、(x, y) に不透明なペイントを持つ最初に出合った上層ウインドウを表します。
カラー情報は、XImage として戻されます。戻されるイメージの幅と高さは、引数で指定された値と同じになります。イメージの形式は ZPixmap です。イメージのデプスは 24、bits_per_pixel は 32 です。各カラーチャネル (赤、緑、青) に関するカラー情報の最上位 8 ビットは、XImage 内の red_mask、green_mask、blue_mask で定義されるビット位置に戻されます。XImage の属性値のうちサーバーに依存するものは、byte_order, bitmap_unit, bitmap_bit_order, bitmap_pad, bytes_per_line, red_mask, green_mask, blue_mask です。
includeCursor が True の場合は、戻されるカラーにカーソルイメージが含められ、それ以外の場合は、除外されます。
このルーチンでは、引数のウィンドウ (およびその他のウィンドウ) の境界も読み取られることに注意してください。
問題が発生すると、XReadScreen は NULL を戻します。
Xlib ピクセル転送ルーチン XGetImage、XCopyArea、XCopyPlane も、透明オーバーレイウィンドウに使用できます。
オーバーレイ以外のドロアブル上では、XGetImage ルーチンは X11 仕様で定義されたとおりに動作します。オーバーレイウィンドウについても同じことが言えますが、例外として、これらのウィンドウ上では透明なピクセルについて戻されるカラー情報は未定義になります。画面上の領域の表示カラーを検索するだけの場合は、XReadScreen を使用してください。
ソースと宛先のドロアブルが両方ともオーバーレイ以外の場合、これらのルーチンは X11 仕様で定義されたとおりに動作します。ただし、ソースまたは宛先となるドロアブルがオーバーレイウィンドウの場合は、次の点に注意してください。
ソースのドロアブルがオーバーレイで、宛先のドロアブルがオーバーレイ以外の場合は、カラー情報だけがコピーされ、ソースのペイント型情報は無視されます。透明なピクセルに関するカラー情報は未定義になります。
ソースのドロアブルがオーバーレイ以外で、宛先のドロアブルがオーバーレイである場合は、GC のペイント型で指定されたとおりにコピーが実行されます。すなわち、ペイント型が XSolarisOvlPaintOpaque の場合は、不透明なペイントを使用してカラー情報が宛先にコピーされます。ペイント型が XSolarisOvlPaintTransparent の場合は、カラー情報が無視され、宛先のピクセルは透明になります。
ソースと宛先のドロアブルが両方ともオーバーレイの場合は、ソースのペイント型が無視され、ソースがオーバーレイでない場合と同じ動作になります。カラーとペイント型の両方の情報をコピーしたい場合は、XSolarisOvlCopyAreaAndPaintType を使用してください。