書式

XPutImage(display, d, gc, image, src_x, src_y, dest_x, dest_y, width, height)

        Display *display;

        Drawable d;

        GC gc;

        XImage *image;

        int src_x, src_y;

        int dest_x, dest_y;

        unsigned int width, height;

XImage *XGetImage(display, d, x, y, width, height, plane_mask, format)

        Display *display;

        Drawable d;

        int x, y;

        unsigned int width, height;

        unsigned long plane_mask;

        int format;

XImage *XGetSubImage(display, d, x, y, width, height, plane_mask, format, dest_image, dest_x,

                     dest_y)

      Display *display;

      Drawable d;

      int x, y;

      unsigned int width, height;

      unsigned long plane_mask;

      int format;

      XImage *dest_image;

      int dest_x, dest_y;

引き数

d

ドロウアブルを指定する。

dest_image

転送先のイメージを指定する。

dest_x

dest_y

x, y 座標を指定する。 これはドロウアブルの原点に対する相対座標で表されるサブイメージの座標か、 転送先の長方形の原点に対する相対座標で、その左上隅の座標を指定し、 サブイメージが転送先イメージのどこに配置されるかを決める。

display

X サーバへの接続を指定する。

format

イメージのフォーマットを指定する。 XYPixmap あるいは ZPixmap を指定する。

gc

GC を指定する。

image

長方形にコピーするイメージを指定する。

plane_mask

プレーンマスクを指定する。

src_x

XImage 構造体で定義されているイメージの左端からの X 方向へのオフセットを指定する。

src_y

XImage 構造体で定義されているイメージの上端からの Y 方向へのオフセットを指定する。

width

height

サブイメージの幅と高さを指定する。 これは長方形の大きさを定義する。

x

y

x, y 座標を指定する。 これはドロウアブルの原点に対する相対座標で、長方形の左上隅を定義する。

説明

関数 XPutImage は指定したドロウアブルの長方形領域にイメージをコピーする。 引き数 src_x, src_y, with, height によって定義されたイメージ領域は、 ドロウアブルの指定した部分に描画される。 XYBitmap フォーマットを用いた場合、イメージの深さは 1 でなければならない。 そうでなければ、エラー BadMatch となる。 GC の前景色ピクセルは、イメージ内でビットが1の部分に対応する転送元を定 義し、GC の背景色ピクセルは、ビットが0の部分に対応する転送元を定義する。 XYPixmap と ZPixmap の場合は、イメージの深さはドロウアブルの深さと一致していなくてはならな い。そうでない場合は、エラー BadMatch となる。

イメージの特性(例えば、byte_order や bitmap_unit)がサーバが要求する特 性と異なる場合、 XPutImage は適切な変換を自動的に行う。

この関数は以下の GC コンポーネントを使用する: function, plane-mask, subwindow-mode, clip-x-origin, clip-y-origin, clip-mask. また、この関数は以下の GC モード依存コンポーネントを使用する: foreground, background.

XPutImage はエラー BadDrawable, BadGC, BadMatch, BadValue を起こすことがある。

関数 XGetImage は、 XImage 構造体へのポインタを返す。 この構造体は、ドロウアブルの指定した長方形領域の内容を、指定したフォー マットで与える。 引き数 format が XYPixmap ならば、イメージは引き数 plane_mask で渡したビットプレーンだけを含む。 引き数 plane_mask でディスプレイのプレーンのサブセットだけを指定した場合 は、返されるイメージの深さは要求したプレーンの数になる。 引き数 format が ZPixmap ならば、 XGetImage は引き数 plane_mask で指定されていない全てのプレーンのビットに 0 を返す。 この関数は plane_mask の値の範囲チェックは行わず、無関係なビットは無視 する。

XGetImage は XImage 構造体の depth メンバにイメージの深さを返す。 イメージの深さはドロウアブルが生成されたときに指定される。 ただし、これには例外があり、 XYPixmap フォーマットのプレーンのサブセットを取得する時は、深さは plane_mask 中 で 1 がセットされているビットの数によって与えられる。

ドロウアブルがピックスマップの時、与えられた長方形領域は完全にピックス マップ内に含まれていなければならない。そうでない場合は、エラー BadMatch となる。 ドロウアブルがウィンドウの場合は、ウィンドウは表示可能でなければならず、 下位ウィンドウや重なりあっているウィンドウがない場合、ウィンドウの指定 した長方形領域はスクリーン上で完全に可視状態で、全体がウィンドウの外枠 に含まれていなければならない。そうでない場合は、エラー BadMatch となる。 ウィンドウの境界はこのリクエストで指定し、取得することが可能である点に 注意せよ。 ウィンドウがバッキングストアを持っている場合、下位ウィンドウでないウィ ンドウに隠されているウィンドウの領域に対しては、バッキングストアの内容 が返される。 ウィンドウがバッキングストアを持っていない場合、このように隠されている 領域について返される内容は未定義である。 指定したウィンドウとは深さが異なる下位ウィンドウの可視領域について返さ れる内容は未定義である。 ポインタカーソルのイメージは返される内容には含まれない。 問題が起こった場合、 XGetImage はNULLを返す。

XGetImage はエラー BadDrawable, BadMatch, BadValue を起こすことがある。

関数 XGetSubImage は指定したサブイメージを使い、 XGetImage と同様の方法で dest_image の内容を更新する。 引き数 format が XYPixmap ならば、イメージは引き数 plane_mask で渡したビットプレーンだけを含む。 引き数 format が ZPixmap ならば、 XGetSubImage は引き数 plane_mask で指定されていない全てのプレーンのビットに 0 を返す。 この関数は plane_mask の値の範囲チェックは行わず、無関係なビットは無視 する。 XGetSubImage は便宜上 dest_image で指定されたものと同じ XImage へのポインタを返す。

転送先の XImage 構造体の深さはドロウアブルの深さと同じでなければならない。 指定したサブイメージが転送先イメージの指定位置に当てはまらない場合、右 と下の辺がクリップされる。 ドロウアブルがピックスマップの時、与えられた長方形領域は完全にピックス マップ内に含まれていなければならない。そうでない場合は、エラー BadMatch となる。 ドロウアブルがウィンドウの場合は、ウィンドウは表示可能でなければならず、 下位ウィンドウや重なりあっているウィンドウがない場合、ウィンドウの指定 した長方形領域はスクリーン上で完全に可視状態で、全体がウィンドウの外枠 に含まれていなければならない。そうでない場合は、エラー BadMatch となる。 ウィンドウがバッキングストアを持っている場合、下位ウィンドウでないウィ ンドウに隠されているウィンドウの領域に対しては、バッキングストアの内容 が返される。 ウィンドウがバッキングストアを持っていない場合、このように隠されている 領域について返される内容は未定義である。 指定したウィンドウとは深さが異なる下位ウィンドウの可視領域について返さ れる内容は未定義である。 問題が起こった場合、 XGetSubImage はNULLを返す。

XGetSubImage はエラー BadDrawable, BadGC, BadMatch, BadValue を起こすことがある。

返り値

BadDrawable

引き数 Drawable の値が、定義されている Window や Pixmap を指していない。

BadGC

引き数 GContext の値が、定義されている GContext を指していない。

BadMatch

InputOnly のウィンドウが Drawable として指定された。

BadMatch

引き数や引き数の組は正しい型と範囲を持っているが、リクエストが要求する他の 条件に適合できなかった。

BadValue

数値のうちにリクエストの許容範囲を越えるものがある。引き数に対して特定の 範囲が指定されていない限り、引き数の型の全ての範囲が許される。選択肢とし て定義された引き数は、このエラーを起こすことがある。