XCreateGC(3X11)

名前
XCreateGC, XCopyGC, XChangeGC, XGetGCValues, XFreeGC, XGContextFromGC, XGCValues - グラフィックスコンテクストの生成・解放関数と、グラフィックスコンテクスト構造体

書式
GC XCreateGC(display, d, valuemask, values)
      Display *display;
      Drawable d;
      unsigned long valuemask;
      XGCValues *values;

XCopyGC(display, src, valuemask, dest)
      Display *display;
      GC src, dest;
      unsigned long valuemask;

XChangeGC(display, gc, valuemask, values)
      Display *display;
      GC gc;
      unsigned long valuemask;
      XGCValues *values;

Status XGetGCValues(display, gc, valuemask, values_return)
      Display *display;
      GC gc;
      unsigned long valuemask;
      XGCValues *values_return;

XFreeGC(display, gc)
      Display *display;
      GC gc;

GContext XGContextFromGC(gc)
      GC gc;

引き数

d   ドロウアブルを指定。

dest
    対象となるGCを指定。

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

gc  GC を指定。

src 元のGC のコンポーネントを指定。

valuemask
    GC のコンポーネントのうち、設定・コピー・変更されるもの、あるいは値が 返されるものを指定。 この引き数は、GC コンポーネントの有効なマスクビットのゼロ個以上に対して、 ビットごとの論理和をとったものである。

values
    引き数 valuemask で指定したコンポーネントの値を指定。

values_return
    指定した 構造体内の GC 値が返される。

説明
関数 はグラフィックスコンテクストを生成し、GC を返す。 生成された GC は指定したドロウアブルと同じルートウィンドウ、深さを持つ 任意の描画対象のドロウアブルと共に用いることができる。 他のドロウアブルと共に使った場合には、エラー となる。

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

関数 はコピー元のGCの指定したコンポーネントをコピー先のGCにコピーする。 コピー元とコピー先のGCは、ルートウィンドウと深さが同じでなければならな い。そうでなければ、エラー となる。 valuemask は の場合と同じく、どのコンポーネントをコピーするかを指定する。

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

関数 は、指定したGCの valuemask で指定したコンポーネントを変更する。 引き数 values にはセットする値が含まれる。 この関数の値と制限は の場合と同じである。 clip-mask の変更は、そのコンテクストに対する以前の をオーバライドする。 dash-offset や dash-list の変更は、そのコンテクストに対する以前の をオーバライドする。 コンポーネントが確認、変更される順序は、サーバに依存する。 エラーが発生した場合、コンポーネントの一部はすでに変更されているかもし れない。

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

関数 は、指定したGCの指定した valuemask で指定されるコンポーネントを返す。 valuemask が正しい GC マスクビットのセット を含んでおり、エラーも起きなかった場合には、 は引き数 values_return に要求されたコンポーネントをセットし、ゼロでない ステータスを返す。 そうでない場合、この関数はゼロのステータスを返す。 clip-mask と dash-list(valuemask ではそれぞれ と ビット)を要求することはできない点に注意せよ。 また、クライアントがコンポーネントを明示的にセットしなかった場合には、 に対して不正なリソースIDが返される(3つの最上位ビットのうちの1つ以上が1 にセットされる)点にも注意すること。

関数 は指定した GC を破棄し、対応するメモリを解放する。

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

構造体
構造体の内容を示す。

/* GC 属性値のマスクビット */
#define |  | (1L<<0)
#define |  | (1L<<1)
#define |  | (1L<<2)
#define |  | (1L<<3)
#define |  | (1L<<4)
#define |  | (1L<<5)
#define |  | (1L<<6)
#define |  | (1L<<7)
#define |  | (1L<<8)
#define |  | (1L<<9)
#define |  | (1L<<10)
#define |  | (1L<<11)
#define |  | (1L<<12)
#define |  | (1L<<13)
#define |  | (1L<<14)
#define |  | (1L<<15)
#define |  | (1L<<16)
#define |  | (1L<<17)
#define |  | (1L<<18)
#define |  | (1L<<19)
#define |  | (1L<<20)
#define |  | (1L<<21)
#define |  | (1L<<22)
/* 値 */ typedef struct {
    int function;    /* 論理的操作 */
     unsigned long plane_mask;    /* プレーンマスク */
     unsigned long foreground;    /* 前景色のピクセル */
     unsigned long background;    /* 背景色のピクセル */
     int line_width;    /* 線の幅 (ピクセル単位) */
    int line_style;    /* LineSolid, LineOnOffDash, LineDoubleDash */
    int cap_style;    /* CapNotLast, CapButt, CapRound, CapProjecting */
    int join_style;    /* JoinMiter, JoinRound, JoinBevel */
    int fill_style;    /* FillSolid, FillTiled, FillStippled FillOpaqueStippled*/
    int fill_rule;    /* EvenOddRule, WindingRule */
    int arc_mode;    /* ArcChord, ArcPieSlice */
     Pixmap tile;    /* タイリング操作のタイルピックスマップ */
     Pixmap stipple;    /* スティプル操作に使う1プレーンのピックスマップ */
    int ts_x_origin;    /* タイリング、スティプル操作でのオフセット */
    int ts_y_origin;
     Font font;    /* テキスト操作に使うデフォルトのテキストフォント */
    int subwindow_mode;    /* ClipByChildren, IncludeInferiors */
     Bool graphics_exposures;    /* 真偽値。露出イベントを生成するかどうか指定 */
     int clip_x_origin;    /* クリッピングの原点 */
    int clip_y_origin;
    Pixmap clip_mask;    /* クリッピングに使うビットマップ。長方形のクリッピングには他の関数を使う。 */
     int dash_offset;    /* パターン線/点線の情報 */
    char dashes; } XGCValues;

GC の function 属性はドロウアブル(操作対象)の一部を他のドロウアブル(操 作元)のビットを使って更新するときに用いられる。 GC の function コンポーネントは、新しい操作対象のビットが、操作元のビッ トと古い操作対象のビットからどのように算出されるかを定義する。 はカラーディスプレイで動作するので一般的には最も便利であるが、特別なア プリケーションでは他の function を使うこともある。 特に、カラーディスプレイの特定のプレーンを使うアプリケーションではそう である。 16 の GC 操作関数が で定義されている。
関数 名前 値 操作
 | 0x0 | 0
 | 0x1 | src AND dst
 | 0x2 | src AND NOT dst
 | 0x3 | src
 | 0x4 | (NOT src) AND dst
 | 0x5 | dst
 | 0x6 | src XOR dst
 | 0x7 | src OR dst
 | 0x8 | (NOT src) AND (NOT dst)
 | 0x9 | (NOT src) XOR dst
 | 0xa | NOT dst
 | 0xb | src OR (NOT dst)
 | 0xc | NOT src
 | 0xd | (NOT src) OR dst
 | 0xe | (NOT src) OR (NOT dst)
 | 0xf | 1

グラフィックス操作の多くは、GC のピクセル値やプレーンに依存する。 プレーン属性は long 型で、プレーンごとに1ビットが割り当てられており、 描画対象のどのプレーンが変更されるか指定する。 モノクロのディスプレイは1つのプレーンしか持たず、プレーンマスクの最下 位ビットしか意味を持たない。 ディスプレイのハードウェアのプレーンが増えるに従って、プレーンマスクの より上位のビットが使われる。

グラフィックス操作では操作元と操作対象のピクセルが与えられると、ピクセ ルの対応する各ビットがビットごとに演算されて、結果が得られる。 つまり、各プレーンにおいてブーリアン操作が実行される。 plane_mask は操作をプレーンの一部分に制限する。 マクロ定数 を使うことで、スクリーンの全てのプレーンを同時に参照することができる。 結果は以下のように計算される。

((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask))

foreground, background, plane_mask の値に対しては、範囲のチェックは行 われない。 これらの値は単に適切なビット数に切り詰められる。 line-width の単位はピクセル数で、1以上(wide line)か特殊な意味を持つ値 0(thin line)のどちらかである。

wide line はグラフィックスリクエストが示す軌跡の中心に描画される。 join-style か cap-style で別途に指定されなければ、端点が [x1, y1], [x2, y2] であり幅 w を持つ wide line のバウンディングボックスは以下の 実座標を持つ長方形となる。

[x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)], [x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)]

ここで sn は線の角度のサインであり、cs は線の角度のコサインである。 ピクセルは線の一部であり、従ってピクセルの中心が完全にバウンディングボッ クス(これは無限に細い辺を持つと考える)の内部にあれば、このピクセルは描 画される。 ピクセルの中心がちょうどバウンディングボックスの辺の上にある場合は、バ ウンディングボックスの内部がピクセル中心のすぐ右(x の増加方向)にある時 に限り、ピクセルが線の一部となる。 ピクセルの中心が水平な辺上にある場合は特別で、バウンディングボックス内 部か境界が中心のすぐ下(y の増加方向)にあり、バウンディングボックス内部 か境界が中心のすぐ右(x の増加方向)にある時に限り、ピクセルが線の一部と なる。

line line(line-width がゼロ)は1ピクセル幅の線である。描画アルゴリズム は定義されておらず、デバイスに依存する。 このアルゴリズムに対しては2つの制約しかない。

1.  線がクリップされずに [x1,y1] から [x2,y2] へ描画され、他の線がクリップ されずに [x1+dx,y1+dy] から [x2+dx,y2+dy] へ描画された場合、点 [x+dx, y+dy] が2番目の線の描画によって塗られた場合に限り、点 [x, y] が最初の 線の描画により塗られる。

2.  線を構成する有効な点は、クリッピングによる影響を受けない。 点がクリップされた線によって塗られるのは以下の二つの条件が満たされてい る場合だけとなる: (1)その点がクリッピング領域の内部にある。 (2)線がクリップされずに描かれた場合に、その点は塗られる。

cap-style や join-style を考慮に入れなければ、[x1,y1] から [x2,y2] に 描かれる wide line と [x2,y2] から [x1,y1] に描かれる wide line は常に 同じピクセルを描画する。 これは thin line でも成り立つことが望ましいが、必須ではない。 line-width が 0 の線と line-width が 1 の線の場合では、異なるピクセル が描画されてもよい。 これにより、ハードウェアで提供される線の描画機能が利用でき、正確に仕様 が決められている wide line よりずっと速く実行することができる。

一般的には、thin line の描画は幅が1の wide line よりも描画がずっと速い。 しかし、異なる描画アルゴリズムを使うため、thin line と wide line を混 在させると見栄えが良くないことがある。 ディスプレイ全体で正確かつ均一な結果が求められる場合には、クライアント は line-width を 0 ではなく 1 とすべきである。

line-style は線のどの部分が描画されるかを定義する。
 | 線の全ての軌跡が描画される。
 | 線の全ての軌跡が描画されるが、偶数番目のダッシュ(短い線分)と奇数番目の ダッシュでは異なる色で塗られる。また、偶数番目と奇数番目のダッシュの継 ぎ目は スタイルで描画される。
 | 偶数番目のダッシュだけが描画され、線の内部での各ダッシュの端点では cap-style が適用される。スタイルは を除いて、 として扱われる。

cap-style は軌跡の端点がどのように描画されるか定義する。
 | これは とほぼ同じであるが、line-width がゼロの場合には最後の端点が描画されな い点が異なる。
 | 線は端点の部分で、端点を越えない四角形(線の勾配に垂直)になる。
 | 線の端点は、直径が line-width に等しくて端点が中心である半円となる。 (line-width がゼロならば と等価である。)
 | 線は端で四角形になるが、軌跡は端点を越えても line-width の半分の長さ分続く。 (line-width がゼロならば と等価である。)

join-style は wide line の角がどのように描画されるのかを定義する。
 | 2つの線の外側の辺が角で交わるまで伸ばす。 しかし、交わる角度が11度以下ならば、join-style が代わりに使われる。
 | 角は直径が line-width であり、中心が交点である扇形となる。
 | 角における線分の端点のスタイルは であり、さらに、三角形をなす切り目の部分を塗りつぶしたものである。

端点が一致する線(x1=x2, y1=y2)に対して、cap-style が両端で指定され ると、この意味は line-width と cap-style によって決まる。
 | thin | 結果はデバイス依存であるが、望ましい結果は何も描かれないことである。
 | thin | 結果はデバイス依存であるが、望ましい結果はピクセルが1つだけ描かれることで ある。
 | thin | 結果は の場合と同じである。
 | thin | 結果は の場合と同じである。
 | wide | 何も描かれない。
 | wide | 閉じた形は端点が中心で、直径が line-width に等しい円である。
 | wide | 閉じた形は座標軸に平行で、端点が中心で、辺の長さが line-width となる正 方形である。

端点が一致する線(x1=x2, y1=y2)について、join-style が片方あるいは両方 の端点に適用された場合、線が軌跡全体から取り除かれたような効果が得られ る。 しかし、全体の軌跡が自分自身と接続した単独の点から構成される、あるいは そのような点に縮小されている場合、cap-style を両方の端点に適用したよう な効果が得られる。

tile/stippleコンポーネントは無限に広い2次元平面であり、その面上でタイ ル/スティプルが繰り返される。 その平面がグラフィックス操作のためにドロウアブルに重ねられる場合、タイ ル/スティプルの何らかのインスタンスの左上隅は、タイル/スティプルの原点 座標によって指定されたドロウアブル内の座標に配置される。 タイル/スティプルとクリップの原点は、グラフィックスリクエストで指定さ れた任意の描画対象ドロウアブルの原点に対する相対座標として扱われる。 ピックスマップ tile は GC と同じルートウィンドウと同じ深さを持っていな ければならない。そうでなければ、エラー となる。 ピックスマップ stipple は深さが1で GC と同じルートウィンドウを持たなけ ればならない。そうでなければ、エラー となる。 fill-style が であるが でないスティプル操作に対しては、スティプルパターンは1つの平面を埋める のに使われ、clip-mask と AND 演算される追加クリップマスクとして用いら れる。 サイズによっては他のサイズのものよりも処理が速いが、任意のサイズのピッ クスマップをタイルやスティプルとして使うことができる。

fill-style は線描画、テキスト描画、塗りつぶしのリクエストの操作元の内容を 定義する。 全てのテキスト描画と塗りつぶしのリクエスト (例えば、 )と、 全ての line-style 指定付きの線描画のリクエスト (例えば と、さらに line-style ( )を指定する線描画リクエストの偶数番目のダッシュに対して、以下の項目が 適用される。
 | 前景色
 | タイル
 | スティプルと同じ幅と高さを持つタイル。しかし、任意の場所でバックグラウ ンドのスティプルはゼロであり、任意の場所でフォアグラウンドのスティプル は1である。
 | スティプルでマスクされたフォアグラウンド

線が line-style 付きで描画されるとき、奇数番目のダッシュは以下の方法で fill-style に制御される。
 | 背景色
 | 偶数番目のダッシュと同じ。
 | 偶数番目のダッシュと同じ。
 | スティプルにマスクされた背景色

GC へのピックスマップの格納はコピーが行われる場合もあるし、そうでない 場合もある。 このピックスマップが後でグラフィックスリクエストの描画対象となる場合に は、その変更は GC に反映されることも反映されないこともある。 グラフィックスリクエストにおいて、ピックスマップが描画対象としても、タイルあ るいはスティプルとしても使われている場合、その結果は未定義である。

性能を最適化するためには、できるだけ同じGC(コンポーネントも変更しない) で描画を行うとよい。 GC コンポーネントを変更するコストの、異なる GC を用いる場合に対する比 率は、ディスプレイのハードウェアやサーバの実装によって決まる。 GC 情報の一部はおそらくディスプレイのハードウェアにキャッシュされるだ ろう。と同時に、キャッシュできる GC の数はそれほど多くはないだろう。

dashes 値は実際には でセットできる、より一般的なパターンを簡略化した形になっている。 値 N を指定することは、 に2つの要素を持つリスト[N, N] を指定することと同じである。 この値はゼロ以外の値でなくてはならない。ゼロである場合には、エラー となる。

clip-mask は描画対象のドロウアブルへの書き込みを制限する。 clip-mask にピックスマップがセットされた場合、このピックスマップは深さ が 1 であり、GC と同じルートウィンドウを持たなければならない。そうでな い場合にはエラー となる。 clip-mask に がセットされた場合、クリップの原点にかかわらずピクセルは必ず描画される。 clip-mask は関数 や を呼び出してもセットすることができる。 clip-mask のビットが1にセットされているピクセルだけが描画される。 clip-mask がカバーしている領域の外側や、clip-mask のビットが0にセット されている領域では、ピクセルは描画されない。 clip-mask は全てのグラフィックスリクエストに影響を与える。 clip-mask は描画元はクリップしない。 clip-mask の原点は、グラフィックスリクエストで指定された任意の描画対象 ドロウアブルに対する相対座標で与えられる。

subwindow-mode には か をセットすることができる。 の場合は、描画元のウィンドウも描画先のウィンドウも、表示可能な である子ウィンドウ全てによって追加的にクリップされる。 の場合は、描画元、描画先いずれのウィンドウに対しても下位ウィンドウによ るクリップはなされない。 つまりサブウィンドウの内容は描画元に含まれ、描画は描画先のサブウィンド ウ境界を通して行われることになる。 を、ある深さを持ち、異なる深さの下位ウィンドウをマップしているようなウィ ンドウで使っても不正ではないが、その意味はコアプロトコルでは定義されて いない。

fill-rule は どのピクセルが リクエストで与えられた軌跡の内側である(描画される)か定義する。この値は か のいずれかである。 の場合は、ある点から無限遠への直線が軌跡と奇数回交わる場合に、その点を 図形の内側とみなす。 の場合は、ある点から無限遠への直線を考えたとき、これが図形に属する時計 周り方向の線分に交わる回数と、反時計周り方向の線分に交わる回数とが異なっ ていれば、その点を図形の内側とみなす。 時計周り方向の図形の線分とは、点から見た場合に直線を左から右に横切る線 分のことである。 反時計周り方向の図形の線分とは、点から見た場合に直線を右から左に横切る 線分のことである。 方向付きの線分が直線と一致する場合は考えなくてもよい。この場合は、単に 線分と一致しない別の直線を選べばよいからである。

いずれの場合も、点の大きさは無限小で、図形の軌跡は無限に細い。 あるピクセルの中心点が図形の内側にあり、中心点が境界線上にない場合、そ のピクセルは図形の内側である。 ピクセルの中心点が境界線上にある場合、多角形の内部がこの点のすぐ右(x 座標が増加する方向)にある場合に限り、そのピクセルは図形の内側である。 中心が水平な辺の上にあるピクセルは特別なケースであり、多角形の内部がこ の点のすぐ下(y座標が増加する方向)にある場合に限り、そのピクセルは図形 の内側である。

arc-mode は の塗りつぶしを制御する。この値は いずれにセットされる。 の場合は、円弧はパイを切った形に塗りつぶされる。 の場合には、弧と弦に囲まれる領域が塗りつぶされる。

graphics-exposure フラグは リクエスト(および拡張で定義される同様のリクエスト)に対しての イベントの生成を制御する。

返り値

サーバが、要求されたリソースやサーバメモリのアロケートに失敗した。

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

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

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

のウィンドウが Drawable として用いられた。

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

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

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

関連項目
AllPlanes(3X11), XCopyArea(3X11), XCreateRegion(3X11), XDrawArc(3X11), XDrawLine(3X11), XDrawRectangle(3X11), XDrawText(3X11), XFillRectangle(3X11), XQueryBestSize(3X11), XSetArcMode(3X11), XSetClipOrigin(3X11), XSetFillStyle(3X11), XSetFont(3X11), XSetLineAttributes(3X11), XSetState(3X11), XSetTile(3X11)
Xlib - C Language X Interface