オーバーレイカラー情報の検索

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)

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 を戻します。