名称

XCreateGC, XCopyGC, XChangeGC, XGetGCValues, XFreeGC, XGContextFromGC, XGCValues − グラフィックコンテキストの作成または解放とグラフィックコンテキスト構造体

形式

GC XCreateGC(display, d, valuemask, values)
      Display ∗display;
      Drawable d;
      unsigned long valuemask;
      XGCValues ∗values; Status XGetGCValues(display, gc, valuemask, values_return)
      Display ∗display;
      GC gc;
      unsigned long valuemask;
      XGCValues ∗values_return; 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; XFreeGC(display, gc)
      Display ∗display;
      GC gc; GContext XGContextFromGC(gc)
      GC gc;

引数

ddrawable を指定します。

dest目的 GC を指定します。

displayX サーバへのコネクションを指定します。

gcGC を指定します。

src元の GC の構成要素を指定します。

valuemaskGC のどの構成要素を設定 を、コピー、変更または返すかを指定します。 この引数は、ひとつ以上の有効な GC 構成要素マスクビット単位の内包的 論理和です。

valuesどの値でも valuemask で指定されたとおりに指定します。

values_return
XGCValues 構造体で指定された GC を返します

解説

XCreateGC 関数は、グラフィックコンテキストを作成し、GC を返します。 GC は、指定された drawable と同じ root と depth をもつ 目的 drawable とともに使用できます。 他の drawable とともに使用すると、 BadMatch エラーが生じます。 XCreateGC の返しうるエラーは、 BadAlloc、 BadDrawable、 BadFont、 BadMatch、 BadPixmap および BadValue です。 XGetGCValues 関数は、GC で指定された valuemask によって指定された成分を返します。 クリップマスクと dash-list（それぞれ、valuemask の GCClipMask と GCDashList ビットで表現される）は、要求できません。 もし 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 で要求された成分をセットし、0 でないステータスを返します。 そうでなければ、ステータス 0 が返されます。 XCopyGC 関数は、元の GC から目的 GC へ指定された要素をコピーします。 元の、および目的の GC は、同じ root と depth をもたなければなりません。 さもなければ BadMatch エラーが生じます。 valuemask は、 XCreateGC と同様に、どの構成要素をコピーするかを指定します。 XCopyGC の返しうるエラーは、 BadAlloc、 BadGC および BadMatch です。 XChangeGC 関数は、指定された GC の valuemask で指定された構成要素を変更します。 values 引数は、設定する値を含んでいます。 値と制限は、 XCreateGC と同じです。 clip-mask を変更すると、コンテキストに対する前の XSetClipRectangles リクエストが無効になります。 dash-offset または dash-list を変更すると、 コンテキストに対する前の XSetDashes リクエストが無効になります。 構成要素を検証し、変更する順序は、サーバに依存します。 エラーが生じた場合、構成要素のサブセットが変更されたかもしれません。 XChangeGC の返しうるエラーは、 BadAlloc、 BadFont、 BadGC、 BadMatch、 BadPixmap および BadValue です。 XGetGCValues 関数は、指定された GC の valuemask で指定された構成要素を返します。 クリップマスクと dash-list（それぞれ、valuemaskの GCClipMask と GCDashList ビットによって表される） は、要求することはできません。 もし valuemask が、GC mask bits (GCFunction, GCPlaneMask, GCForeground, GCBackground, GCLineWidth, GCLineStyle, GCCapStyle, GCJoinStyle, GCFillStyle, GCFillRule, GCTile, GCStipple, GCTileStipXOrigin, GCTileStipYOrigin, GCFont, GCSubwindowMode, GCGraphicsExposures, GCClipXOrigin, GCCLipYOrigin, GCDashOffset, あるいは、 GCArcMode) の集合を含んでいて、かつエラーが生じなかった場合、 XGetGCValues は、values_return に要求された成分をセットし、0 でないステータスを返します。 そうでない場合、ステータス 0 を返します。 XFreeGC 関数は、指定された GC および関連するすべての記憶領域を破壊します。 XFreeGC の返しうるエラーは、 BadGC です。

構造体

XGCValues 構造体は、以下のような内容をしています。 /∗ GC attribute value mask bits ∗/

/∗ Values ∗/
 typedef struct {
        int function;/∗ logical operation ∗/
        unsigned long plane_mask;/∗ plane mask ∗/
        unsigned long foreground;/∗ foreground pixel ∗/
        unsigned long background;/∗ background pixel ∗/
        int line_width;/∗ line width (in pixels) ∗/
        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;/∗ tile pixmap for tiling operations ∗/
        Pixmap stipple;/∗ stipple 1 plane pixmap for stippling ∗/
        int ts_x_origin;/∗ offset for tile or stipple operations ∗/
        int ts_y_origin;
        Font font;/∗ default text font for text operations ∗/
        int subwindow_mode;/∗ ClipByChildren, IncludeInferiors ∗/
        Bool graphics_exposures;/∗ boolean, should exposures be generated ∗/
        int clip_x_origin;/∗ origin for clipping ∗/
        int clip_y_origin;
        Pixmap clip_mask;/∗ bitmap clipping; other calls for rects ∗/
        int dash_offset;/∗ patterned/dashed line information ∗/
        char dashes;
} XGCValues;

 
GC の関数の属性は、どこか他（のソース）から、目的 drawable のセクションの日付を更新するのに使われます。 GC の関数は、新しい目的ビットが、いかにソースビットと 古いデスチネーションビットから計算されるのかを定義します。 GXcopy は、典型的にもっとも便利です。なぜなら、それがカラーディスプレイで動くからです。 しかし、特別なアプリケーションは、別の関数、特に、カラーディスプレイの特別なプレーン に関連した関数を使うかも知れません。 16 の GC 関数が、 <X11/X.h>, に定義されています。 それは、以下のようなものです。

多くのグラフィック操作は、GC の pixel values とプレーンに依存しています。 プレーンの属性は、long 型で、プレーンごとに 1 ビット、目的プレーンが修正 されるように指定されます。 モノクロディスプレイは、1 プレーンしか持たず、あまり重要なビットにはなりません。 プレーンがディスプレイのハードウェアに加えられたら、プレーンマスクで より重要なビットを占めます。 グラフィック操作で、ソースと 目的 pixel が与えられたら、 結果は、ピクセルに関連のあるビットの bitwise を計算します。 いわゆる、Boolean 操作が、それぞれのビットプレーンに対して行なわれます。 プレーンマスクはプレーンの集合への操作を制限します。 マクロ定数、 AllPlanes は、同時にスクリーンのすべてのプレーンを参照するのに使われることができます。 結果は、以下のように計算されます。

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

範囲のチェックは、foreground, background あるいは、プレーンマスクの値には 行なわれません。 それらは単に、適当な数のビットに切り詰められます。 line-width は、ピクセルで測られ、1（wide line）以上にも、 特別な値 0（thin line）にもなりえます。 広いラインは、グラフィックリクエストによって述べられたパスを中心に描かれます。 join-style または cap-style によって指定されないかぎり、 端点 [x1, y1], [x2, y2] と幅 w を持った width line の bounding box は、 以下の実際の座標を頂点にもつ長方形になります。

[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 はラインの角度の sin であり、cs はラインの角度の cos です。 ピクセルは、ラインの 1 部であり、 （限りなく薄い端を持っているように見える）bounding box の完全に内側に あるかのように描かれます。 もし、ピクセルの中央が正確に bounding box の上にあれば、 その内部が、すぐ右側（x が増加する方向）にあった場合のみ、line の 1 部となります。 水平方向の端に中央のあるピクセルは特別な場合であり、その内部か境界が すぐ下側（y が増加する方向）にあり、その内部か境界がすぐ右側（x が増加する方向） にある場合のみ、line の 1 部となります。 細いライン（line-width が 0）は、指定されない、デバイスに依存するアルゴリズムを 使って描かれた 1 ピクセルの幅のラインです。 このアルゴリズムには 2 つの制限があります。

1.もしあるラインが、[x1,y1] から [x2,y2]へクリップされずに描かれ、 もう 1 つのラインが [x1+dx,y1+dy] から [x2+dx,y2+dy] へクリップされずに描かれたら、 点 [x+dx,y+dy] が、2 番目のラインを描くことによって接する場合のみ、 点 [x,y] が、最初のラインを描くことによって接します。

2.ラインを含む点の効果的な集合は、クリップすることによって影響を受けません。 つまり、その点がクリップする部分の内側にある場合のみクリップしたラインに接するし、 クリップされずに描かれたときは、そのラインに接するでしょう。 [x1,y1] から [x2,y2] に引かれた広いラインは、cap-style や join-style をカウントしない、[x2,y2] から [x1,y1] に引かれた広いラインとして、 いつもいくつかのピクセルを描きます。 この特性は、細いラインについても言えますが、これは必要とされていないことを 述べています。 0 の line-width は、ピクセルがかかれている 0 の line-width とは違うかも知れません。 これは、より正確に指定された広いラインより、たいていの場合速く実行する、 おおくのマニュファクチャのラインを描くハードウェアの使用を許可します。 一般に、細いラインを描くことは、width 1 の広いラインを描くよりも速いでしょう。 けれども、これらの異なったアルゴリズムによって、 細いラインは、広いラインとは混同しません。 もし、すべてのディスプレイに渡って、正確で一定の結果を得るのが望ましいならば、 クライアントは、いつも 0 の line-width より 1 の line-width を使うべきです。 line-style は、ラインのセクションが描かれたところで、以下のように定義されています。

cap-style は、以下にパスの終点が描かれるかを、以下のように定義します。

join-style は、いかに角が広いラインのために描かれているかを、以下のように 定義します。

一致する終点を持ったライン (x1=x2, y1=y2) に対して、 cap-style が両方の終点に適用されたとき、 記号論は、line-width と cap-style に依存します。

一致する終点 (x1=x2, y1=y2) を持つラインに対して、 join-style が 1 つ、あるいは両方の終点に適用されたとき、 結果は、まるでラインが全部のパスから取り除かれたようになります。 けれども、もし全体のパスが、自分につながっているシングルの点から 成り立っているか、それに変わっているならば、 結果は、cap-style が両方の終点に適用されたときと同じになります。 tile/stipple と clip の原点は、目的 drawable がグラフィックリクエストで指定された ものすべての原点に比例して翻訳されます。 タイルピクスマップは、GC あるいは BadMatch エラーの結果と同じ root と depth を持たなければいけません。 stipple ピクスマップは、depth ピクスマップを持たなければならないし、 GC あるいは BadMatch エラーの結果と同じ root を持たなければいけません。 fill-style が、 FillStippled であり FillOpaqueStippled でない stipple 操作に対して、stipple プレーンは、 シングルプレーンにタイルされ、clip-mask に足されるべきである 付加的なクリップマスクとして振る舞います。 あるサイズは、他のサイズより使うのが速いかもしれないけれども、 あるサイズのピクスマップは、tilling や stippling に使われることができます。 fill-style は、ライン、テキスト、fill リクエストのソースの内容を定義します。 すべてのテキストと fill リクエスト（例えば、 XDrawText, XDrawText16, XFillRectangle, XFillPolygon, XFillArc） に対して、また、line-style for line requests with line-style LineSolid （例えば、 XDrawLine, XDrawSegments, XDrawRectangle, XDrawArc） を持ったラインリクエストに対して、また、line-style LineOnOffDash あるいは LineDoubleDash を持ったラインリクエストに対する偶数の dash に対して、 次のことがあてはまります。

line-style LineDoubleDash でラインを描くとき、 奇数の dash は、次の方法の fill-style によってコントロールされます。

GC にピクスマップを格納することは、コピーが作られることに なるかもしれないし、ならないかもしれません。 もしピクスマップが、あとでグラフィックリクエストへの目的として使われたなら、 その変化は、GC に反映されるかもしれないし、されないかもしれません。 もしピクスマップが、目的として、そして tile あるいは stipple として、 同時にグラフィックリクエストに使われたなら、結果は定義されません。
 
最高のパフォーマンスに対して、 できる限りたくさん、同じ GC を （その成分を変えることなしに）描くべきです。 弧となる GC を使うことに関して GC 成分の変換のコストは、 ディスプレイのハードウェアとサーバのツールに依存します。 ある量の GC の情報は、ディスプレイのハードウェアに隠され、 そのようなハードウェアは、小さな数の GC を隠すことのみできるでしょう。 dash の値は、実際は XSetDashes でセットできる、もっと一般的なパターンの簡単な形をしています。 N の値を指定することは、 XSetDashes の 2 つの成分のリスト [N, N] を指定することに等しくなります。 The value must be nonzero, 値は、0 以外でなければなりません。でなければ、 BadValue エラーとなります。 clip-mask は、目的 drawable への書き込みを制限します。 もし clip-mask がピクスマップにセットされたら、 depth が 1 でなければならないし、GC と同じ root を持たなければなりません。でなければ、 BadMatch エラーとなります。 もし clip-mask が、 None にセットされたら、 ピクセルはいつも、clip の原点に注意せずに描かれます。 clip-mask は、 XSetClipRectangles あるいは XSetRegion 関数と呼ばれるものによってもまたセットされます。 clip-mask が 1 にセットされたビットを持つピクセルのみが、描かれます。 ピクセルは、clip-mask によって覆われたエリアの内側、あるいは、 clip-mask が 0 にセットされたビットを持つところでは描かれません。 clip-mask は、すべてのグラフィックのリクエストに影響します。 clip-mask は、ソースをクリップしません。 clip-mask の原点は、目的 drawable がグラフィックのリクエストで指定された 所の原点に関して解釈されます。 subwindow-mode を、 ClipByChildren あるいは、 IncludeInferiors にセットすることができます。 ClipByChildren に対して、ソースと目的ウィンドウの両方は、すべての目に見える InputOutput チルドレンによって付加的にクリップされます。 IncludeInferiors に対して、ソースと目的ウィンドウの両方とも、下位のものによってクリップされません。 この結果、ソースの中にサブウィンドウの中身を含み、 目的のサブウィンドウ境界線を通して描かれます。 異なった深さのインフィアリアにマップされた深さ 1 のウィンドウ上での IncludeInferiors の使用は、間違いではありません。しかし、記号論は、コアプロトコルに定義されていません。 fill-rule は、ピクセルが XFillPolygon リクエストで与えられるパスの内側に描かれることを定義し、 EvenOddRule あるいは WindingRule にセットされることができます。 EvenOddRule, に対して、 もし原点としてのその点をもつ無限の ray が、奇数回パスを横切るなら、 点は内側にあります。 WindingRule に対して、 もし原点としてのその点をもつ無限の ray が、パスに向かって 右回りと左回りのセグメントの数に等しくないだけ横切るならば、 点は内側にあります。 パスに向かって右回りのセグメントは、その点から見て左から右に ray を横切ります。 左回りのセグメントは、その点から見て右から左に ray を横切ります。 ラインに向けられたセグメントが、その ray に一致する場合は、おもしろくありません。 なぜなら、セグメントに一致しない異なった ray をすぐ選ぶことができるからです。 EvenOddRule と WindingRule, の両方で、点は限りなく小さく、パスは限りなく薄いラインです。 もし、ピクセルの中央の点が内側にあって、中央の点が境界線上になかったら、 ピクセルは内側にあります。 もし、中央の点が境界線上にあったら、 多角形の内側が、その右側（x が増加する方向）にあった場合のみ、 ピクセルは内側になります。 水平方向の端に中央を持つピクセルは、特別な場合です。 多角形の内側が下側（y の増加する方向）にあった場合のみ内側になります。 arc-mode は、 XFillArcs 関数で fill するのをコントロールします。 そして、 ArcPieSlice あるいは ArcChord にセットされることができます。 ArcPieSlice に対して、 arcs は、pie-slice fill されます。 ArcChord, に対して、 arcs は、chord fill されます。 graphics-exposure フラグは、 XCopyArea や XCopyPlane のリクエスト（と拡張によって定義されたほかの同じようなリクエスト） に対して、 GraphicsExpose イベントジェネレーションを操作します。

診断

BadAlloc サーバが、要求されたリソースまたはサーバメモリの割当てに失敗した。

BadDrawable
Drawable 引数の値が、定義された Window または Pixmap を指さない。

BadFont Font または GContext 引数の値が、定義された Font を指さない。

BadGC GContext 引数の値が、定義された GContext を指さない。

BadMatch InputOnly ウィンドウが Drawable として使用された。

BadMatch ある引数またはひと組の引数の型と範囲は正しいが、リクエストにより要求された その他のなにかが一致しない。

BadPixmap
Pixmap 引数の値が、定義された Pixmap を指さない。

BadValue ある数値が許容範囲を超えた。 引数の値の範囲が明示されない限り、引数の型によって決まる最大の範囲まで 指定可能です。 選択形式の引数も、このエラーを生じることがあります。

関連事項

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
 
 
 
 
 
 
 
 
 
 
 
 
 
 

NEWS-OSRelease 4.1C