XPutImage(3X11)

名前
XPutImage, XGetImage, XGetSubImage - イメージ転送

書式
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
    イメージのフォーマットを指定。 あるいは を指定する。

gc  GC を指定。

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

plane_mask
    プレーンマスクを指定。

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

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

width

height
    サブイメージの幅と高さを指定。 これは長方形のディメンジョンを定義する。

x

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

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

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

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

はエラー を起こすことがある。

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

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

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

はエラー を起こすことがある。

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

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

はエラー を起こすことがある。

返り値

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

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

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

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

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

関連項目
Xlib - C Language X Interface