Chapter 7 Graphics Context Functions

7章: グラフィックコンテキスト関数

多くのリソースがXでグラフィック操作を行うときに使われる。 グラフィック操作を行う大部分の情報(例えば、前景色、背景色、 線のスタイル等)はグラフィックコンテキスト(GC)と呼ばれる リソースに格納されている。 大部分のグラフィック操作(8章を参照)は GCを引き数に取る。 理論的にX プロトコルはアプリケーション間のGCの共有を許容するが、 アプリケーションが操作を行うときにGCを自分で所有して使うのが望ましい。 ライブラリがGCの状態をキャッシュするかもしれないので、GCを共有化することは よくはじかれる。

グラフィックの操作はウィンドウ、ピクスマップのいずれかに対して行われるので、 これらはまとめてドローアブルと呼ばれる。 それぞれのドローアブルは単一のスクリーン上に存在する。 GCは指定したスクリーンと描画可能な深さに対して作られ、 スクリーンと深さが一致しているドローアブルのみ使用できる。

この章は以下の方法について述べられる。

Manipulating Graphics Context/State

グラフィック操作の大部分の属性がGCに格納される。 これらは線の幅、線のスタイル、プレーンマスク、前景、背景、タイル、点描、 クリッピング、領域、終端のスタイル、接合のスタイル等を含む。 グラフィック操作(例えば、線を描く)は実際の描画操作を決定するために これらの値を使う。 Xヘの拡張はGCに追加的なコンポーネントを追加する。 GCのコンテンツはXlibにプライベートである。

XlibはGCの全ての要素に対してライトバックキャッシュを実装している。 これらのGCの要素はXlibがGCへの変更の透過的な融合を実装するできるように リソースIDではない。 例えば、 XSetLineAttributesへの呼び出しに続くGCの XSetForegroundへの呼び出しにより、 サーバに単一の変更GCプロトコル要求のみが生じる。 GCはクライアントアプリケーション間で共有することを望みもしないし、推奨も しない。だからこれらのライトキャッシュバックはまったく問題なく与えられる。 アプリケーションは外部の同期機構なしにGCを共有することは出来ない。 それゆえ、 アプリケーション間でGCを共有することはよくはじかれる。

GCの属性をセットするには、 XCreateGC .への呼び出し時に、 適切な XGCValues構造体とのメンバーとそれに相当するビットマスク値との間で論理和を取ることによりセットする。 ビットマスクの値に対するシンボルと XGCValues構造体は以下の通りである。

/* GC属性のビットマスク値 */

#define\ GCFunction
(1L<<0)
#define\ GCPlaneMask
(1L<<1)
#define\ GCForeground
(1L<<2)
#define\ GCBackground
(1L<<3)
#define\ GCLineWidth
(1L<<4)
#define\ GCLineStyle
(1L<<5)
#define\ GCCapStyle
(1L<<6)
#define\ GCJoinStyle
(1L<<7)
#define\ GCFillStyle
(1L<<8)
#define\ GCFillRule
(1L<<9)
#define\ GCTile
(1L<<10)
#define\ GCStipple
(1L<<11)
#define\ GCTileStipXOrigin
(1L<<12)
#define\ GCTileStipYOrigin
(1L<<13)
#define\ GCFont
(1L<<14)
#define\ GCSubwindowMode
(1L<<15)
#define\ GCGraphicsExposures
(1L<<16)
#define\ GCClipXOrigin
(1L<<17)
#define\ GCClipYOrigin
(1L<<18)
#define\ GCClipMask
(1L<<19)
#define\ GCDashOffset
(1L<<20)
#define\ GCDashList
(1L<<21)
#define\ GCArcMode
(1L<<22) 
/* Values */
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;	/* クリッピングの原点 */ /* origin for clipping */
	int clip_y_origin;
	Pixmap clip_mask;	/* クリッピングに使うビットマップ。長方形のクリッピングには他の関数を使う。*/ 
	int dash_offset;	/* パターン線/点線の情報 */ 
	char dashes;
} XGCValues;

デフォルトのGC値は次の通りである。

Component Default
function GXcopy
plane_mask All ones
foreground 0
background 1
line_width 0
line_style LineSolid
cap_style CapButt
join_style JoinMiter
fill_style FillSolid
fill_rule EvenOddRule
arc_mode ArcPieSlice
tile Pixmap of unspecified size filled with foreground pixel
(that is, client specified pixel if any, else 0)
(subsequent changes to foreground do not affect this pixmap)
stipple Pixmap of unspecified size filled with ones
ts_x_origin 0
ts_y_origin 0
font <implementation dependent>
subwindow_mode ClipByChildren
graphics_exposures True
clip_x_origin 0
clip_y_origin 0
clip_mask None
dash_offset 0
dashes 4 (that is, the list [4, 4])

前景色と背景色があるウィンドウに都合がいいようになるような値の組は存在しないこと に注意すること。

GC の function 属性はドロウアブル(操作対象)の一部を他のドロウアブル(操作元)のビット を使って更新するときに用いられる。 GC の function コンポーネントは、新しい操作対象のビットが、操作元のビットと 古い操作対象のビットからどのように算出されるかを定義する。 GXcopyはカラーディスプレイで動作するので一般的には最も便利であるが、 特別なアプリケーションでは他の function を使うこともある。 16 の GC 操作関数が <X11/X.h ,>で定義されている。

関数 名前 値 操作
GXclear 0x0 0
GXand 0x1 src AND dst
GXandReverse 0x2 src AND NOT dst
GXcopy 0x3 src
GXandInverted 0x4 (NOT src) AND dst
GXnoop 0x5 dst
GXxor 0x6 src XOR dst
GXor 0x7 src OR dst
GXnor 0x8 (NOT src) AND (NOT dst)
GXequiv 0x9 (NOT src) XOR dst
GXinvert 0xa NOT dst
GXorReverse 0xb src OR (NOT dst)
GXcopyInverted 0xc NOT src
GXorInverted 0xd (NOT src) OR dst
GXnand 0xe (NOT src) OR (NOT dst)
GXset 0xf 1

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

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

((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 は線のどの部分が描画されるかを定義する。

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

cap-style は軌跡の端点がどのように描画されるか定義する。

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

join-style は wide line の角がどのように描画されるのかを定義する。

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

端点が一致する線(x1=x2, y1=y2)に対して、cap-style が両端で指定されると、 この意味は line-width と cap-style によって決まる。

CapNotLast thin 結果はデバイス依存であるが、望ましい結果は何も描かれないことである。
CapButt thin 結果はデバイス依存であるが、望ましい結果はピクセルが1つだけ描かれることである。
CapRound thin 結果は CapButt /thin の場合と同じである。
CapProjecting thin 結果は CapButt /thin.の場合と同じである。
CapButt wide 何も描かれない。
CapRound wide 閉じた形は端点が中心で、直径が line-width に等しい円である。
CapProjecting wide 閉じた形は座標軸に平行で、端点が中心で、辺の長さが line-width となる正方形である。

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

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

fill-style は線描画、テキスト描画、塗りつぶしのリクエストの操作元の内容を定義する。 全てのテキスト描画と塗りつぶしのリクエスト (例えば、 XDrawText , XDrawText16 ,XFillRectangle , XFillPolygon , XFillArc )と、line-style LineSolid 指定付きの線描画のリクエスト (例えば XDrawLine ,XDrawSegments , XDrawRectangle ,XDrawArc );) と、さらに line-style ( LineOnOffDash , LineDoubleDash )を指定する線描画リクエストの偶数番目のダッシュに対して、 以下の項目が適用される。

FillSolid 前景色
FillTiled タイル
FillOpaqueStippled スティプルと同じ幅と高さを持つタイル。しかし、任意の場所でバックグラウンドのスティプルはゼロであり、任意の場所でフォアグラウンドのスティプルは1である。
FillStippled スティプルでマスクされたフォアグラウンド

線が line-style LineDoubleDash ,付きで描画されるとき、奇数番目のダッシュは以下の方法で fill-style に制御される。

FillSolid 背景色
FillTiled 偶数番目のダッシュと同じ。
FillOpaqueStippled 偶数番目のダッシュと同じ。
FillStippled スティプルにマスクされた背景色

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

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

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

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

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

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

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

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

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

ドロウアブルの深さを持つスクリーン上に使用可能な新しいGCを 作成するには、 XCreateGC を使う。

GC XCreateGC(display, d, valuemask, values)
Display *display;
Drawable d;
unsigned long valuemask;
XGCValues *values;
display
X サーバへの接続を指定。
d
ドロウアブルを指定。
valuemask
GC のコンポーネントのうち、指定したvalues構造体中の情報を使って設定されるものを指定。 この引き数は、GC コンポーネントの有効なマスクビットのゼロ個以上に対して、 ビットごとの論理和をとったものである。
values
引き数 valuemask で指定したコンポーネントの値を指定。

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

XCreateGCはエラー BadAlloc ,BadDrawable ,BadFont ,BadMatch ,BadPixmap ,, BadValue を起こすことがある。

操作元のGCから操作先のGCにコンポーネントをコピーするには、 XCopyGC を使う。

XCopyGC(display, src, valuemask, dest)
Display *display;
GC src, dest;
unsigned long valuemask;
display
X サーバへの接続を指定。
src
元のGC のコンポーネントを指定。
valuemask
GC のコンポーネントのうち、対象先のGCにコピーされるものを指定。 この引き数は、GC コンポーネントの有効なマスクビットのゼロ個以上に対して、 ビットごとの論理和をとったものである。
dest
対象となるGCを指定。

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

XCopyGCはエラー BadAlloc , BadGC ,, BadMatchを起こすことがある。

与えられたGCのコンポーネントを変更するには、 XChangeGC を使う。

XChangeGC(display, gc, valuemask, values)
Display *display;
GC gc;
unsigned long valuemask;
XGCValues *values;
display
X サーバへの接続を指定。
gc
GCを指定。 指定したvalue構造体中の情報を使って変更
valuemask
GC のコンポーネントのうち、対象先のGCにコピーされるものを指定。 この引き数は、GC コンポーネントの有効なマスクビットのゼロ個以上に対して、 ビットごとの論理和をとったものである。
values
引き数 valuemask で指定したコンポーネントの値を指定。

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

XChangeGCはエラー BadAlloc ,BadFont ,BadGC ,BadMatch ,BadPixmap ,, BadValueを起こすことがある。

与えられたGCのコンポーネントを得るには、 XGetGCValues を使う。

Status XGetGCValues(display, gc, valuemask, values_return)
Display *display;
GC gc;
unsigned long valuemask;
XGCValues *values_return;
display
X サーバへの接続を指定。
gc
GCを指定。
valuemask
GC のコンポーネントのうち、引き数 values_return に値が返されるものを指定。 この引き数は、GC コンポーネントの有効なマスクビットのゼロ個以上に対して、 ビットごとの論理和をとったものである。
values_return
指定した XGCValues 構造体内の GC 値が返される。

関数 XGetGCValuesは、指定したGCの指定した valuemask で指定されるコンポーネントを返す。 valuemask が正しい GC マスクビットのセット ( (GCFunction ,GCPlaneMask ,GCForeground ,GCBackground ,GCLineWidth ,GCLineStyle ,GCCapStyle ,GCJoinStyle ,GCFillStyle ,GCFillRule ,GCTile ,GCStipple ,GCTileStipXOrigin ,GCTileStipYOrigin ,GCFont ,GCSubwindowMode ,GCGraphicsExposures ,GCClipXOrigin ,GCCLipYOrigin ,GCDashOffset ,, GCArcMode )を含んでおり、エラーも起きなかった場合には、 XGetGCValuesは引き数 values_return に要求されたコンポーネントをセットし、ゼロでないステータスを返す。 そうでない場合、この関数はゼロのステータスを返す。 clip-mask と dash-list(valuemask ではそれぞれ GCClipMaskと GCDashList)を要求することはできない点に注意せよ。 また、クライアントがコンポーネントを明示的にセットしなかった場合には、 GCFont ,GCTile ,, GCStippleに対して不正なリソースIDが返される(3つの最上位ビットのうちの1つ以上が 1 にセットされる)点にも注意すること。

与えられたGCを解放するには、 XFreeGC を使う。

XFreeGC(display, gc)
Display *display;
GC gc;
display
Xサーバへの接続を指定。
gc
GCを指定。

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

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

与えられたGCに対する GContext リソースIDを得るには、 XGContextFromGC を使う。

GContext XGContextFromGC(gc)
GC gc;
gc
取得するリソースIDに対する GCを指定。

グラフィック関数がGCと一緒に呼び出されるまで、 Xlibは普通サーバにGCコンポーネントの変更を送ることを延期する。 これは単一サーバリクエストにおけるコンポーネント変更のバッチングを許す。 しかし、ある環境下では、クライアントが明示的にサーバに 変更を強制的に送ることが必要である。 例えば、プロトコルエクステンションがGCを直接使用するような場合であり、 このときエクステンションインターフェイスはGCが何を使用するかを知ることは出来ない。 GCコンポーネントの変更を強制的に送るには、 XFlushGC を使う。

void XFlushGC(display, gc)
Display *display;
GC gc;
display
X サーバへの接続を指定。
gc
GCを指定。

Using Graphics Context Convenience Routines

この節は以下のものをどのように設定するかを述べる。

Setting the Foreground, Background, Function, or Plane Mask

与えられたGCに対する前景色、背景色、プレーンマスク、function コンポーネントを 設定するには、 XSetState を使う。

XSetState(display, gc, foreground, background, function, plane_mask)
Display *display;
GC gc;
unsigned long foreground, background;
int function;
unsigned long plane_mask;
display
X サーバへの接続を指定。
gc
GC を指定。
foreground
指定したGCにセットする前景色を指定。
background
指定した GC にセットする背景色を指定。
function
指定した GC にセットする function を指定。
plane_mask
プレーンマスクを指定。

XSetStateはエラー BadAlloc ,BadGC ,, BadValue を起こすことがある。

与えられたGCの前景色をセットするには、 XSetForeground を使う。

XSetForeground(display, gc, foreground)
Display *display;
GC gc;
unsigned long foreground;
display
X サーバへの接続を指定。
gc
GC を指定。
foreground
指定した GC にセットする前景色を指定。

XSetForegroundはエラー BadAlloc, BadGC を起こすことがある。

与えられたGCの背景色をセットするには、 XSetBackground を使う。

XSetBackground(display, gc, background)
Display *display;
GC gc;
unsigned long background;
display
X サーバへの接続を指定。
gc
GC を指定。
background
指定した GC にセットする背景色を指定。

XSetBackgroundはエラー BadAlloc, BadGC を起こすことがある。

与えられたGCのディスプレイfunctionをセットするには、 XSetFunction を使う。

XSetFunction(display, gc, function)
Display *display;
GC gc;
int function;
display
X サーバへの接続を指定。
gc
GC を指定。
function
指定した GC にセットする function を指定。

XSetFunctionはエラー BadAlloc ,BadGC ,, BadValue を起こすことがある。

与えられたGCのプレーンマスクをセットするには、 XSetPlaneMask を使う。

XSetPlaneMask(display, gc, plane_mask)
Display *display;
GC gc;
unsigned long plane_mask;
display
X サーバへの接続を指定。
gc
GC を指定。
plane_mask
プレーンマスクを指定。

XSetPlaneMaskはエラー BadAlloc, BadGC を起こすことがある。

Setting the Line Attributes and Dashes

与えられたGCのの線の描画コンポーネントをセットするには、 XSetLineAttributes を使う。

XSetLineAttributes(display, gc, line_width, line_style, cap_style, join_style)
Display *display;
GC gc;
unsigned int line_width;
int line_style;
int cap_style;
int join_style;
display
X サーバへの接続を指定。
gc
GC を指定。
line_width
指定した GC にセットする線の幅を指定。
line_style
指定した GC に指定する線のスタイルを指定。 LineSolid ,LineOnOffDash ,, LineDoubleDash のいずれかを指定する。
cap_style
指定した GC にセットする線のスタイルと端点のスタイルを指定。 CapNotLast ,CapButt ,CapRound ,, CapProjecting のいずれかを指定する。
join_style
指定した GC にセットする線の接続スタイルを指定。 JoinMiter ,JoinRound ,, JoinBevel のいずれかを指定する。

XSetLineAttributesはエラー BadAlloc ,BadGC ,, BadValue を起こすことがある。

与えられたGC の点線のスタイルの dash-offset 属性と dash-list 属性をセットするには、 XSetDashes を使う。

XSetDashes(display, gc, dash_offset, dash_list, n)
Display *display;
GC gc;
int dash_offset;
char dash_list[];
int n;
display
X サーバへの接続を指定。
gc
GC を指定。
dash_offset
指定した GC にセットする点線のスタイルのパターンの相を指定。
dash_list
指定した GC にセットする点線のスタイルに対するダッシュ (点線の構成要素である短い線)のリストを指定。
n
dash_list の要素数を指定。

関数 XSetDashesは指定した GC の点線のスタイルの dash-offset 属性と dash-list 属性をセットする。 指定した dash_list には最低1つの要素がなければならない。 無い場合にはエラー BadValueとなる。 dash_list の最初の要素から交互の要素(2番目、4番目等)は偶数番目の ダッシュであり、残りが奇数番目のダッシュである。 それぞれの要素はピクセル単位でダッシュの長さを指定する。 全ての要素はゼロであってはならず、 そうでない場合はエラー BadValueとなる。 奇数番目の長さのリストを指定することは、自分自身を繋げがる同じリストを指定して 偶数番目の長さのリストを作ることと等価である。

dash-offset はパターンの位相を定義する。 これは単独のグラフィックスリクエストで、dash-list 中のいくつの ピクセルでパターンを実際に始めるかを指定する。 点線は join-style と繋がるまで軌跡上を続く。しかし、線を接続する場合には各シーケンス 間で位相は dash-offset に再設定される。

ダッシュの長さの単位は、通常の座標系と同じである。 理想的にはダッシュの長さは線の勾配に沿って測るべきだが、実装に対して要求されているのは 水平な線と垂直な線の場合に理想的になっていることだけである。 理想的にできない場合のために、線の長軸に沿って長さを測る方法を示しておく。 x 軸となす各が-45度から+45度、135度から225度である線に対しては、 x 軸が長軸であると定義される。 これ以外の場合には、長軸は y 軸である。

XSetDashesはエラー BadAlloc ,BadGC ,, BadValue を起こすことがある。 Setting the Fill Style and Fill Rule

与えられたGCのfill-styleをセットするには、 XSetFillStyle を使う。

XSetFillStyle(display, gc, fill_style)
Display *display;
GC gc;
int fill_style;
display
X サーバへの接続を指定。
gc
GCを指定。
fill_style
指定した GC にセットする fill-style 値を指定。 FillSolid ,FillTiled ,FillStippled ,, FillOpaqueStippled のいずれかを指定。

XSetFillStyleはエラー BadAlloc ,BadGC ,, BadValue を起こすことがある。

与えれられたGCのfill-ruleをセットするには、 XSetFillRule を使う。

XSetFillRule(display, gc, fill_rule)
Display *display;
GC gc;
int fill_rule;
display
X サーバへの接続を指定。
gc
GC を指定。
fill_rule
指定した GC にセットする fill-rule 値を指定。 EvenOddRuleか WindingRule を指定する。

XSetFillRuleはエラー BadAlloc ,BadGC ,, BadValue を起こすことがある。

Setting the Fill Tile and Stipple

ディスプレイの中には指定されたサイズのパターンを持つ タイリングやスティプルのハードウェアサポートを持つものもある。 これらの特定のサイズに制限されたタイリングやスティプル操作は任意のサイズ のパターンの操作よりも早く動作する。 Xlibはタイルやスティプルの形とタイル、スティプルの原点をセットするのと同様に ディスプレイに関して最も良いサイズ、タイル、スティプルを決定する 関数を提供する。

タイル、スティプル、カーソルの最も良いサイズを得るには、 XQueryBestSize を使う。

Status XQueryBestSize(display, class, which_screen, width, height, width_return, height_return)
Display *display;
int class;
Drawable which_screen;
unsigned int width, height;
unsigned int *width_return, *height_return;
display
X サーバへの接続を指定。
class
問い合わせる対象のクラスを指定。 TileShape , CursorShape , , StippleShape のいずれかを指定する。
which_screen
スクリーン上の任意のドロウアブル(drawable)を指定。
width

height
幅と高さを指定。
width_return

height_return
オブジェクトの幅と高さが返される。これはディスプレイのハードウェア のサポートが最も有効となる値である。

関数 XQueryBestSizeは指定したサイズに対して、最善かまたはそれにできるだけ近いサイズを返す。 CursorShape に対しては、 このサイズは which_screen で指定したスクリーン上で全体を表示できる最大のサイズである。 TileShape に対しては、 これは最も速くタイリングできるサイズである。 StippleShape に対しては、 これは最も速くスティプルを適用できるサイズである。 CursorShape の場合は、 対象とするスクリーンをドロウアブルで指定する。 TileShape と StippleShape の場合は、 ドロウアブルを使ってスクリーンを指示する。 これで同時にウィンドウクラスと深さを指示することもできる。 TileShape, StippleShapeに対し、 InputOnlyのウィンドウをドロウアブルとして用いることはできない。 これを用いた場合には、エラー BadMatch となる。

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

最も良い塗りつぶしタイルの形を得るには、 XQueryBestTile を使う。

Status XQueryBestTile(display, which_screen, width, height, width_return, height_return)
Display *display;
Drawable which_screen;
unsigned int width, height;
unsigned int *width_return, *height_return;
display
X サーバへの接続を指定。
which_screen
スクリーン上の任意のドロウアブル(drawable)を指定。
width

height
幅と高さを指定。
width_return

height_return
オブジェクトの幅と高さが返される。 これはディスプレイのハードウェアのサポートが最も有効となる値である。

関数 XQueryBestTileは which_screen として指定したスクリーン上で最善かそれにできるだけ近いサイズ (つまり最も速くタイリングできるサイズ)を返す。 ドロウアブルを使ってスクリーンを指示する。これで同時にウィンドウクラスと深さを 示すこともできる。 InputOnly のウィンドウをドロウアブルとして指定した場合は、 エラー BadMatch となる。

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

最も良いスティプルの形を得るには、 XQueryBestStipple を使う。

Status XQueryBestStipple(display, which_screen, width, height, width_return, height_return)
Display *display;
Drawable which_screen;
unsigned int width, height;
unsigned int *width_return, *height_return;
display
X サーバへの接続を指定。
which_screen
スクリーン上の任意のドロウアブル(drawable)を指定。
width

height
幅と高さを指定。
width_return

height_return
オブジェクトの幅と高さが返される。これはディスプレイのハードウェアの サポートが最も有効となる値である。

関数 XQueryBestStippleは、 which_screen として指定したスクリーン上で最善のサイズか、それにできるだけ 近いサイズ、つまり最も速くスティプルできるサイズを返す。 ドロウアブルを使ってスクリーンを指示する。これで同時にウィンドウクラスと 深さを示すこともできる。 InputOnlyのウィンドウをドロウアブルとして指定した場合は、 エラー BadMatchとなる。

XQueryBestStippleはエラー BadDrawableか BadMatch を起こすことがある。

与えられたGCの塗りつぶしタイルをセットするには、 XSetTile を使う。

XSetTile(display, gc, tile)
Display *display;
GC gc;
Pixmap tile;
display
X サーバへの接続を指定。
gc
GC を指定。
tile
指定した GC にセットする塗りつぶしタイル(fill tile)を指定。

タイルと GC は同じ深さでなければならない。 そうでない場合、エラー BadMatchとなる。

XSetTileはエラー BadAlloc ,BadGC ,BadMatch ,, BadPixmap を起こすことがある。

与えられたGCのスティプルをセットするには、 XSetStipple を使う。

XSetStipple(display, gc, stipple)
Display *display;
GC gc;
Pixmap stipple;
display
X サーバへの接続を指定。
gc
GC を指定。
stipple
指定した GC にセットするスティプルを指定。

スティプルは深さが1でなければならない。 そうでなければエラー BadMatchとなる。

XSetStippleはエラー BadAlloc ,BadGC ,BadMatch ,, BadPixmap を起こすことがある。

与えられたGCのスティプルの原点をセットするには、 XSetTSOrigin を使う。

XSetTSOrigin(display, gc, ts_x_origin, ts_y_origin)
Display *display;
GC gc;
int ts_x_origin, ts_y_origin;
display
X サーバへの接続を指定。
gc
GC を指定。
ts_x_origin

ts_y_origin
タイルとスティプルの原点の座標を指定。

ラフィックのリクエストがタイル操作やスティプル操作を要求した場合、 親の原点は、グラフィックスのリクエストで指定されたどんな描画対象の ドロウアブルに対しても相対的に解釈される。

XSetTSOriginはエラー BadAlloc, BadGC を起こすことがある。

Setting the Current Font

与えられたGCの現在のフォントをセットするには、 XSetFont を使う。

XSetFont(display, gc, font)
Display *display;
GC gc;
Font font;
display
X サーバへの接続を指定。
gc
GC を指定。
font
フォントを指定。

XSetFontはエラー BadAlloc ,BadFont ,, BadGC を起こすことがある。

Setting the Clip Region

Xlibはクリップ原点、クリップマスクをセットする 、もしくは長方形のリストにクリップマスクをセットするのに 使う関数を提供する。

与えられたGCのクリップ原点をセットするには、 XSetClipOrigin を使う。

XSetClipOrigin(display, gc, clip_x_origin, clip_y_origin)
Display *display;
GC gc;
int clip_x_origin, clip_y_origin;
display
X サーバへの接続を指定。
gc
GC を指定。
clip_x_origin

clip_y_origin
クリップマスク原点の x, y 座標を指定。

クリップマスクの原点はグラフィックスリクエストで指定された描画対象の ドロウアブルに対する相対座標として解釈される。

XSetClipOriginはエラー BadAlloc, BadGC を起こすことがある。

指定されたピクスマップに与えられたGCのクリップマスクをセットするには、 XSetClipMask を使う。

XSetClipMask(display, gc, pixmap)
Display *display;
GC gc;
Pixmap pixmap;
display
X サーバへの接続を指定。
gc
GC を指定。
pixmap
ピックスマップか None を指定する。

クリップマスクに None がセットされている場合、 ピクセルは常に描画される(クリップの頂点には無関係である)。

XSetClipMaskはエラー BadAlloc ,BadGC ,BadMatch ,, BadPixmap を起こすことがある。

指定された長方形のリストに与えられたGCのクリップマスクをセットするには、 XSetClipRectangles を使う。

XSetClipRectangles(display, gc, clip_x_origin, clip_y_origin, rectangles, n, ordering)
Display *display;
GC gc;
int clip_x_origin, clip_y_origin;
XRectangle rectangles[];
int n;
int ordering;
display
X サーバへの接続を指定。
gc
GC を指定。
clip_x_origin

clip_y_origin
クリップマスク原点の x, y 座標を指定。
rectangles
クリップマスクを指定する長方形の配列を指定。
n
長方形の数を指定。
ordering
長方形の順序の関係を指定。 Unsorted ,YSorted ,YXSorted ,, YXBanded のいずれかを指定する。

関数 XSetClipRectanglesは指定した GC のクリップマスクを指定した長方形のリストに変更し、 クリップの原点をセットする。 出力はリスト中の長方形に含まれる部分にクリップされる。 クリップの原点はグラフィックスリクエストで指定される任意の描画対象 ドロウアブルの原点に対する相対座標として解釈される。 長方形の座標はクリップの原点に対する相対座標として解釈される。 長方形は干渉してはならない。そうでなければ、グラフィックスリクエストの結果は 未定義である。 長方形のリストは空でも良いが、この場合は実際には出力が 無効になる。 これは XCreateGC ,XChangeGC ,, XSetClipMask のクリップマスクでは、 Noneを指定することと反対の意味である。

ライアントが分かっていれば、長方形の順序関係は引き数 ordering で指定することができる。 これにより、サーバによる操作が速くなることがある。 間違った順序を指定した場合、X サーバはエラー BadMatch起こすこともあるが、サーバの実装としてエラーを起こすことが 必要なわけではない。 エラーが起きなかった場合、グラフィックス操作の結果は 未定義である。 Unsorted は長方形の順序が任意であることを示す。 YSorted は長方形の順序は、長方形の原点の Y 座標について昇順(同一Y座標も許す) であることを示す。 YXSorted は YSorted の順序に加え、原点のY座標が同じ長方形は全て原点のX座標について昇順 (同一X座標も許す)に並ぶ制約を追加したものである。 YXBanded は YXSorted に次の制約を加えたものである。 その制約とは、全ての可能なYスキャンラインに対して、そのスキャンラインを含む 長方形全ては同じY座標とY方向の大きさを持つことである。

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

Xlibは領域計算を行う基本的な関数の組を提供する。 これらの関数についての情報に関しては 16.5節を参照すること。 arcモード、subwindowモード、graphics-exposureの設定

Setting the Arc Mode, Subwindow Mode, and Graphics Exposure

To set the arc mode of a given GC, use 与えられたGCのarcモードをセットするには、 XSetArcMode を使う。

XSetArcMode(display, gc, arc_mode)
Display *display;
GC gc;
int arc_mode;
display
X サーバへの接続を指定。
gc
GC を指定。
arc_mode
arc モードを指定。 ArcChordか ArcPieSlice を指定する。

XSetArcModeはエラー BadAlloc ,BadGC ,, BadValue を起こすことがある。

与えられたGCのsubwindowモードをセットするには、 XSetSubwindowMode を使う。

XSetSubwindowMode(display, gc, subwindow_mode)
Display *display;
GC gc;
int subwindow_mode;
display
X サーバへの接続を指定。
gc
GC を指定。
subwindow_mode
サブウィンドウのモードを指定。 ClipByChildren, IncludeInferiors .のいずれかを指定。

XSetSubwindowModeはエラー BadAlloc ,BadGC ,, BadValue を起こすことがある。

与えられたGCのgraphics-exposures フラグをセットするには、 XSetGraphicsExposures を使う。

XSetGraphicsExposures(display, gc, graphics_exposures)
Display *display;
GC gc;
Bool graphics_exposures;
display
X サーバへの接続を指定。
gc
GC を指定。
graphics_exposures
この GC で XCopyAreaや XCopyPlaneを呼んだ時に GraphicsExposeと NoExposeのどちらを通知するか示す真偽値を指定。

XSetGraphicsExposuresはエラー BadAlloc ,BadGC ,BadValue を起こすことがある。
目次に戻る