Chapter 8 Graphics Functions

8章 グラフィック関数

• 領域のクリアとコピー
• 点、線、長方形、扇形の描画
• 領域の塗りつぶし
• フォントの操作
• テキストの描画
• クライアントとサーバ間でのイメージの転送

同じドロウアブルとGCが関数呼び出しに使われる場合、 Xlibは XDrawPoint ,XDrawLine ,XDrawRectangle ,XFillArc ,XFillRectangle へのback-to-back呼び出しをバッチ処理する。 これはサーバへのリクエスト総数を減らすことを意味することに注意すること

Clearing Areas

Xlibはある領域、あるいは全ウィンドウ領域をクリアするのに使う関数を提供する。 ピクスマップは定義された背景色を持たないので、この節で示される関数で示される 関数を使ってピクスマップを塗りつぶすことはできない。 代わりに、ピクスマップ上に類似の操作を行うには、 XFillRectangle を使う。 これはピクスマップを既知の値にセットする。

与えられたウィンドウの長方形領域をクリアするには、 XClearArea を使う。

XClearArea(display, w, x, y, width, height, exposures)
Display *display;
Window w;
int x, y;
unsigned int width, height;
Bool exposures;

display

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

w

ウィンドウを指定。

x

y

x, y 座標を指定。これはウィンドウの原点に対する相対座標であり、長方形の左上隅を指定する。

width

height

幅と高さを指定。これは長方形のディメンジョンである。

exposures

Exposeイベントを生成するかどうか示す真偽値を指定。

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

与えられたウィンドウの全領域をクリアするには、 XClearWindow を使う。

XClearWindow(display, w)
Display *display;
Window w;

display

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

w

ウィンドウを指定。

XClearWindowはエラー BadMatch, BadWindow を起こすことがある。

Copying Areas

Xlibは領域やビットプレーンをコピーするのに使う関数を提供する。

同じルートと深さを持つドロウアブルの間で領域をコピーするには、 XCopyArea を使う。

XCopyArea(display, src, dest, gc, src_x, src_y, width, height, dest_x, dest_y)
Display *display;
Drawable src, dest;
GC gc;
int src_x, src_y;
unsigned int width, height;
int dest_x, dest_y;

display

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

src

dest

コピー元とコピー先の長方形を指定。

gc

GC を指定。

src_x

src_y

コピー先の長方形の左上隅の x, y 座標を指定。 これはコピー先の 長方形の原点に対する相対座標で指定する。

width

height

高さと幅を指定。これはコピー元とコピー先両方の長方形のディメンジョンである。

dest_x

dest_y

コピー先の長方形の左上隅の x, y 座標を指定。これはコピー先の長方形の原点に対する相対座標で指定する。

コピー元の長方形領域が他のウィンドウに隠されていて、その部分がバッキン グストアに 保持されていない場合や、 コピー元のドロウアブルの境界の外側の部分が指定された場合には、 領域間でのコピーは行われない。 その代わりに、その部分に対応するコピー先領域で、可視状態であったりバッキング ストアに保存されているもの全ては以下に示すようになる。 コピー先の領域が None でない背景色を持つウィンドウである場合、 コピー先の対応する領域は背景色で塗りつぶされる(プレーンマスク は全て1で、 GXcopy function が使われる)。 塗りつぶしや、コピー先領域がウィンドウかピックスマップであるかどうかに は関係なく、 graphics-exposures が True の時には、対応するコピー先領域に対する GraphicsExposeイベントが生成される。 graphics-exposures は True であるが、 GraphicsExposeイベントが全く生成されない場合には、 NoExpose イベントが生成される。 新規作成した GC においては、graphics-exposures のデフォルトの値は Trueである点に注意せよ。

この関数は以下の GC コンポーネントを使用する。 function, plane-mask, subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin, and clip-mask.

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

与えられたドロウアブルの単一のビットプレーンをコピーするには、 XCopyPlane を使う。

XCopyPlane(display, src, dest, gc, src_x, src_y, width, height, dest_x, dest_y, plane)
Display *display;
Drawable src, dest;
GC gc;
int src_x, src_y;
unsigned int width, height;
int dest_x, dest_y;
unsigned long plane;

display

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

src

dest

コピー元とコピー先の長方形を指定。

gc

GC を指定。

src_x

src_y

コピー元の長方形の左上隅の x, y 座標を指定。 これはコピー元の長方形の 原点に対する相対座標で指定する。

width

height

高さと幅を指定。これはコピー元とコピー先両方の長方形のディメンジョンである。

dest_x

dest_y

コピー先の長方形の左上隅の x, y 座標を指定。これはコピー先の長方形の原点に対する相対座標で指定する。

plane

ビットプレーンを指定。 1つのビットだけを1にセットしなければならない。

実際には、 XCopyPlaneはコピー先領域と同じ深さで、コピー元領域で指定したサイズの ピックスマップを作る。 そして、GC内の前景色/背景色のピクセル(コピー元のビットプレーンで1の部分は前景色、 0の部分は背景色)を用いて、 CopyAreaプロトコルリクエストと同等のリクエストが実行される。 ウィンドウの露出については全く同じである。 これは、指定したコピー元領域のビットプレーンを fille-style が FillOpaqueStippledのスティプルを使って、コピー先の長方形領域を塗りつぶし たと考えることもできる。

この関数は以下の GC コンポーネントを使用する: function, plane-mask, foreground, background, subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin, , clip-mask.

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

Drawing Points, Lines, Rectangles, and Arcs

Xlibは以下のものを描画するのに使う関数を提供する。

• 一個、複数の点
• 一個、複数の線
• 一個、複数の長方形
• 一個、複数の円弧

以下の節で示す関数の中にはこれらの構造体を使うものもある。

typedef struct {
	short x1, y1, x2, y2;
} XSegment;

typedef struct {
	short x, y;
} XPoint;

typedef struct {
	short x, y;
	unsigned short width, height;
} XRectangle;

typedef struct {
	short x, y;
	unsigned short width, height;
	short angle1, angle2;             /* 弧度(degree) * 64 */ 
} XArc;

全ての x, y メンバは符号付き整数である。 width, height メンバは16ビットの符号無し整数である。 プロトコルではこれらの値は16ビットのフィールドしか持たないので、 16ビットの範囲を越える座標やサイズを生成しないよう注意しなければならない。

Drawing Single and Multiple Points

To draw a single point in a given drawable, use XDrawPoint .

XDrawPoint(display, d, gc, x, y)
Display *display;
Drawable d;
GC gc;
int x, y;

display

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

d

ドロウアブル(drawable)を指定。

gc

GC を指定。

x

y

点を描画する x,y 座標を指定。

与えられたドロウアブルに複数の点を描画するには、 XDrawPoints を使う。

XDrawPoints(display, d, gc, points, npoints, mode)
Display *display;
Drawable d;
GC gc;
XPoint *points;
int npoints;
int mode;

display

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

d

ドロウアブル(drawable)を指定。

gc

GC を指定。

points

点の配列を指定。

npoints

配列内の点の数を指定。

mode

座標モードを指定。 CoordModeOriginまたは CoordModePrevious を指定する。

どちらの関数も以下の GC コンポーネントを使用する。 function, plane-mask, foreground, subwindow-mode, clip-x-origin, clip-y-origin, clip-mask.

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

Drawing Single and Multiple Lines

与えられたドロウアブルで2つの点の間に1個の線を描画するには、 XDrawLine を使う。

XDrawLine(display, d, gc, x1, y1, x2, y2)
Display *display;
Drawable d;
GC gc;
int x1, y1, x2, y2;

display

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

d

ドロウアブル(drawable)を指定。

gc

GC を指定。

x1

y1

x2

y2

線で結ばれる点 (x1, y1) と (x2, y2) を指定。

与えられたドロウアブルに複数の線を描画するには、 XDrawLines を使う。

XDrawLines(display, d, gc, points, npoints, mode)
Display *display;
Drawable d;
GC gc;
XPoint *points;
int npoints;
int mode;

display

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

d

ドロウアブル(drawable)を指定。

gc

GC を指定。

points

点の配列を指定。

npoints

配列中の点の数を指定。

mode

座標モードを指定。 CoordModeOriginか CoordModePrevious のいずれかを指定する。

与えられたドロウアブルに複数の、接続されていない線を描画するには、 XDrawSegments を使う。

XDrawSegments(display, d, gc, segments, nsegments)
Display *display;
Drawable d;
GC gc;
XSegment *segments;
int nsegments;

display

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

d

ドロウアブル(drawable)を指定。

gc

GC を指定。

segments

線分の配列を指定。

nsegments

配列中の線分の数を指定。

関数 XDrawLinesは、指定した GC のコンポーネントを使い、 XPoint構造体の配列が示す点の組 (point[i], point[i+1]) を結ぶ npoints-1 個の 線を描く。 この関数は配列に入っている順に線を描画する。 中間の点全てにおいて線分は正しく接続され、最初の点と最後の点が一致して いれば最初と最後の点も正しく接続される。 与えられた任意の線について、 XDrawLinesは1つのピクセルを2度以上描画しない。 細い(line-width がゼロの)線が交差している場合、 交差している点は複数回 描画される。 幅を持つ線が交差している場合は、交差しているピクセルは1度だけ描画される。 つまり、あたかも全体の PolyLine プロトコルリクエストが単一の、塗りつぶしに対するものであるかのように処理される。 CoordModeOriginの場合は全ての座標値は原点からの相対座標となり、 CoordModePreviousの場合には、最初の点より後の座標は全て前の点からの相対座標となる。

関数 XDrawSegments は複数の、接続されていない線を描画する。 各線分に対して、 XDrawSegments は点 (x1, y1) と (x2, y2) を結ぶ線を描く。 この関数は XSegment構造体の配列に入っている順に線を描画する。一致する端点の接続は行わない。 ある線について、 XDrawSegmentsは1つのピクセルを1度しか描画しない。 線が交差している場合は、交差しているピクセルは複数回描画される。

これら3つの関数が使う GC コンポーネントは以下である。 function, plane-mask, line-width, line-style, cap-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, clip-mask. 関数 XDrawLinesは、GC の join-style コンポーネントも使用する。 これら3つの関数は、以下の GC モード依存のコンポーネントも使用する。 foreground, background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, dash-list.

XDrawLine ,XDrawLines ,XDrawSegmentsはエラー BadDrawable ,BadGC ,BadMatch を起こすことがある。 XDrawLinesはさらに BadValue も起こすことがある。

Drawing Single and Multiple Rectangles

与えられたドロウアブルに一個の長方形のアウトラインを描画するには、 XDrawRectangle を使う。

XDrawRectangle(display, d, gc, x, y, width, height)
Display *display;
Drawable d;
GC gc;
int x, y;
unsigned int width, height;

display

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

d

ドロウアブル(drawable)を指定。

gc

GC を指定。

x

y

長方形の左上隅の位置を決める x,y 座標を指定。

width

height

長方形のディメンジョンを決める幅と高さを指定。

与えられたドロウアブルに複数の長方形の アウトラインを描画するには、 XDrawRectangles を使う。

XDrawRectangles(display, d, gc, rectangles, nrectangles)
Display *display;
Drawable d;
GC gc;
XRectangle rectangles[];
int nrectangles;

display

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

d

ドロウアブル(drawable)を指定。

gc

GC を指定。

rectangles

長方形の配列を指定。

nrectangles

配列内の長方形の数を指定。

これらの関数は、指定した1つあるいは複数の長方形に対して、 1つのピクセル を1度しか描画しない。 XDrawRectanglesは、配列中の順序通りに長方形を描画する。 長方形が交わっている場合、 重なっている部分のピクセルは複数回描画される。

いずれの関数も以下の GC コンポーネントを使用する。 function, plane-mask, line-width, line-style, cap-style, join-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, clip-mask. 関数はこれらのGCモード依存のコンポーネントを使用する。 foreground, background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, dash-list.

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

Drawing Single and Multiple Arcs

与えられたドロウアブルに1個の円弧を描画するには、 XDrawArc を使う。

XDrawArc(display, d, gc, x, y, width, height, angle1, angle2)
Display *display;
Drawable d;
GC gc;
int x, y;
unsigned int width, height;
int angle1, angle2;

display

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

d

ドロウアブル(drawable)を指定。

gc

GC を指定。

x

y

x, y 座標を指定。これはドロウアブルの原点からの相対座標であり、 円弧を囲む長方形の左上隅 の座標である。

width

height

幅と高さを指定。これは弧の長軸と短軸である。

angle1

弧の中心と3時の位置を結んだ線を基準として弧の開始角を指定。 単位は弧度(degree)*64である。

angle2

弧の開始角からの角度で弧の軌跡と領域を指定。 単位は弧度*64である。

与えられたドロウアブルに複数の円弧を描画するには、 XDrawArcs を使う。

XDrawArcs(display, d, gc, arcs, narcs)
Display *display;
Drawable d;
GC gc;
XArc *arcs;
int narcs;

display

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

d

ドロウアブル(drawable)を指定。

gc

GC を指定。

arcs

弧の配列を指定。

narcs

配列中の弧の数を指定。

%[ ~x, ~y, ~width , ~height, ~angle1, ~angle2 ]% で指定される弧の場合、 長軸と短軸の原点は % [ x +^ {width over 2} , ~y +^ {height over 2} ]% である。また、円や楕円の無限に細い軌跡は横軸とは % [ x, ~y +^ {height over 2} ]% と % [ x +^ width , ~y +^ { height over 2 }] % で交わり、縦軸とは % [ x +^ { width over 2 } , ~y ]% と % [ x +^ { width over 2 }, ~y +^ height ]% で交わる。 これらの座標は小数であり、離散的な座標には丸められない。 跡は数学的に厳密に定義すべきである。 幅 lw を持つ線の場合、 塗りつぶしの輪郭線は、円/楕円の軌跡からの距離が lw/2(これは小数になり得る) に等しい点からなる2つの無限に細い軌跡によって与えられる。 弧の端点については、その円/楕円の接線に対する cap_style や join_style と同じものが用いられる。

% [ ~x, ~y, ~width, ~height, ~angle1, ~angle2 ]% で指定される弧の場合、 この角度は実際には歪んでいる楕円の座標系で定義しなければならない (円の 場合には、角度と座標系は一致している)。 これらの角度とスクリーンの通常の座標系で表現される角度 (分度器で測るよ うな角度)の関係は次式で表される。

% roman "skewed-angle" ~ = ~ atan left ( tan ( roman "normal-angle" )
 * width over height right ) +^ adjust%

skewed-angle と normal-angle は範囲が % [ 0 , ~2 pi ]% のラジアン(64 で割った弧度ではない)で表される。 この角度のアークタンジェントは範囲 % [ - pi over 2 , ~pi over 2 ] % を返す。また、adjust は以下の値を取 る。

%0%		通常の角度が % [ 0 , ~pi over 2  ]% の範囲にある場合
%pi%		通常の角度が % [ pi over 2 , ~{3 pi} over 2  ]% の範囲にある場合
%2 pi%		通常の角度が % [ {3 pi} over 2 , ~2 pi  ]% の範囲にある場合

与えられた弧について、 XDrawArcと XDrawArcsは、1つのピクセルを1度しか描画しない。 正しく接続している2つの弧の幅がゼロより大きく、弧が交わっている場合には、 XDrawArcと XDrawArcsは、1つのピクセルを1度しか描画しない。 そうでない場合、交わっている弧のピクセルは複数回描画される。 ある端点から時計周りに指定した弧と他方の端点から反時計周りに同じ角度を 指定した弧は、接続に違いが出る以外は同じピクセルを描画する。

ある弧の終点と次の弧の最初の点が一致した場合、2つの弧は正しく接続される。 最初の弧の最初の点と最後の弧の最後の点が一致する場合、 2つの弧は正しく 接続される。 1つの軸にゼロを指定すれば、水平な線か垂直な線を描くことができる。 角度は単に座標系に基づいて計算され、アスペクト比は無視される。

どちらの関数も以下の GC コンポーネントを使用する。 function, plane-mask, line-width, line-style, cap-style, join-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, clip-mask. 関数はこれらのGCモードの依存コンポーネントも使用する。 foreground, background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, dash-list.

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

Filling Areas

Xlibは以下のものを塗りつぶすのに使う関数を提供する。

• １個、もしくは複数の長方形
• １個の多角形
• １個、もしくは複数の円弧

Filling Single and Multiple Rectangles

与えられたドロウアブルに１つの長方形領域を塗りつぶすには、 XFillRectangle を使う。

XFillRectangle(display, d, gc, x, y, width, height)
Display *display;
Drawable d;
GC gc;
int x, y;
unsigned int width, height;

display

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

d

ドロウアブルを指定。

gc

GC を指定。

x

y

x,y 座標を指定。これはドロウアブルの原点からの相対座標で長方形の左隅の位置を指定する。

width

height

幅と高さを指定。これは塗りつぶされる長方形のディメンジョンである。

与えられたドロウアブルに複数の長方形領域を塗りつぶすには、 XFillRectangles を使う。

XFillRectangles(display, d, gc, rectangles, nrectangles)
Display *display;
Drawable d;
GC gc;
XRectangle *rectangles;
int nrectangles;

display

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

d

ドロウアブルを指定。

gc

GC を指定。

rectangles

長方形の配列を指定。

nrectangles

配列中の長方形の数を指定。

[x,y] [x+width,y] [x+width,y+height] [x,y+height]

それぞれの関数は指定された x, y 座標、幅と高さ、 ディメンジョン、GC を使用する。

XFillRectanglesは配列内で列挙されている順に長方形を塗りつぶす。 与えられたいかなる長方形に対しても、 XFillRectangleおよび XFillRectanglesは1つのピクセルを1回しか描画しない。 長方形が重なっている場合、重なっている部分は複数回描画される。

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

XFillRectangleおよび XFillRectanglesBadDrawable ,BadGC ,BadMatch を起こすことがある。

Filling a Single Polygon

与えられたドロウアブルに多角形領域を塗りつぶすには、 XFillPolygon を使う。

XFillPolygon(display, d, gc, points, npoints, shape, mode)
Display *display;
Drawable d;
GC gc;
XPoint *points;
int npoints;
int shape;
int mode;

display

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

d

ドロウアブルを指定。

gc

GC を指定。

points

点の配列を指定。

npoints

配列中の点の数を指定。

shape

サーバが効率の向上を図れるよう形状を指定。 Complex , Convex , Nonconvex のいずれかを渡すことができる。

mode

座標モードを指定。 CoordModeOriginあるいは CoordModePrevious を渡すことができる。

指定した shape によっては、以下のことが起こる。

• もし shape が Complex ならば、 パスは自己干渉するかもしれない。 パス上での隣接する点の一致は自己干渉としては扱わない。
• shape が Convex (凸包)の場合には、多角形の内側の任意の点の組について、 これらを繋ぐ線分 はパスと干渉しない。 凸包になることをクライアントが知っている場合、 Convex を指定することで効率を高めることができる。 凸包でないパスに対して Convex を指定した場合、 表示結果は未定義である。
• shape が Nonconvex の場合、 パスは自己干渉しないが、かならずしも凸包ではない。 これをクライアントが知っている場合、 Complexでなく Nonconvexを指定することで描画効率を上げることができる。 パスが自己干渉している場合に Nonconvex を指定した場合の表示結果は未定義である。

GC 制御の fill-rule は、自己干渉する多角形の塗りつぶしの挙動を 制御する。

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

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

Filling Single and Multiple Arcs

与えられたドロウアブルに1個の円弧を塗りつぶすには、 XFillArc を使う。

XFillArc(display, d, gc, x, y, width, height, angle1, angle2)
Display *display;
Drawable d;
GC gc;
int x, y;
unsigned int width, height;
int angle1, angle2;

display

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

d

ドロウアブルを指定。

gc

GC を指定。

x

y

x,y 座標を指定。これはドロウアブルの相対座標であり、境界線である長方形の 左上隅の座標を指定する。

width

height

幅と高さを指定。これは円弧の長軸と短軸である。

angle1

円の中央から3時の方向に対して開始角を指定。単位は弧度(degree)*64である。

angle2

開始角に対して弧の軌跡と領域を指定。単位は弧度*64である。

与えられたドロウアブルに複数の円弧を塗りつぶすには、 XFillArcs を使う。

XFillArcs(display, d, gc, arcs, narcs)
Display *display;
Drawable d;
GC gc;
XArc *arcs;
int narcs;

display

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

d

ドロウアブルを指定。

gc

GC を指定。

arcs

円弧の配列を指定。

narcs

配列中の円弧の数を指定。

両方の関数とも以下の GC コンポーネントを使用する: function, plane-mask, fill-style, arc-mode, subwindow-mode, clip-x-origin, clip-y-origin, clip-mask. また、これらの関数は以下の GC モード依存コンポーネントを使用する: foreground, background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin.

XFillArcおよび XFillArcsはエラー BadDrawable ,BadGC ,BadMatch を起こすことがある。

Font Metrics

フォントは文字セットの図による表示である。これは小さな、良く似たサイズのパターンの組が 常に繰り返して使われるとき、効率を上げるために使われる。

この節では

• フォントの読みこみと解放
• フォント名の取得と解放
• 文字列サイズの計算
• 論理長の計算
• 文字列のサイズの問い合わせ

Xサーバはプログラムが新しいフォントを要求したときにフォントを読みこむ。 サーバはすばやく調べるためにフォントをキャッシュできる。 フォントはサーバ上の全てのスクリーンに対してグローバルである。 いくつかのレベルでフォントを扱うことが可能である。 大部分のアプリケーションは単にフォントを読み出したり フォントメトリックスを問い合わせるために XLoadQueryFontを使う。

フォントにおける文字はマスクとして扱われる。 画像テキストリクエストに対するものを除いて、 変更されるピクセルはビットが文字の中で１にセットされるものだけである。 これはスティプルやタイルを使ってテキストを描くことが理解できることを意味する (例えば、多くのメニュー、gray-out、使うことが出来ないエントリー)。

The XFontStruct構造体にはフォントの情報が全て含まれる。 この構造体は、フォント固有の情報や XCharStruct構造体(フォントに含まれる文字の情報)の配列への ポインタから構成されている。 XFontStruct ,XFontProp ,XCharStructの各構造体の内容を以下に示す。

typedef struct {
	short lbearing;	/* 原点からラスタ領域の左端までの距離 */ 
	short rbearing;	/* 原点からラスタ領域の右端までの距離 */ 
	short width;	/* 次の文字の原点へ進む量 */ 
	short ascent;	/* ベースラインからラスタ領域の上端までの距離 */ 
	short descent;	/* ベースラインからラスタ領域の下端までの距離 */ 
	unsigned short attributes;	;/* 文字毎のフラグ (予め定義されてはいない) */ 
} XCharStruct;

typedef struct {
	Atom	name;
	unsigned long card32;
} XFontProp;

typedef struct {	/* 通常の16ビット文字は2バイトである */ 
    unsigned char byte1;
    unsigned char byte2;
} XChar2b;

typedef struct {
	XExtData *ext_data;	/* データを持つ拡張のためのフック */ 
	Font fid;	/* このフォントのフォントID */ 
	unsigned direction;	/* フォントの描画方向に関するヒント */ 
	unsigned min_char_or_byte2;	/* 最初の文字 */ 
	unsigned max_char_or_byte2;	/* 最後の文字 */ 
	unsigned min_byte1;	/* 存在する最初の列 */ 
	unsigned max_byte1;	/* 存在する最後の列 */ 
	Bool all_chars_exist;	/* 全ての文字がゼロでない大きさを持つかどうかのフラグ */ 
	unsigned default_char;	/* 未定義文字の表示に使う文字 */ 
	int n_properties;	/* いくつプロパティがあるか */ 
	XFontProp *properties;	/* 追加プロパティの配列へのポインタ */ 
	XCharStruct min_bounds;	/* 存在する全ての文字中の最小値 */ 
	XCharStruct max_bounds;	/* 存在する全ての文字中の最大値 */ 
	XCharStruct *per_char;	/* first_char から last_char の情報 */ 
	int ascent;	/*スペーシングのためのベースラインの上の論理的な広さ */ 
	int descent;	/* スペーシングのためのベースラインより下の論理的な広さ*/ 
} XFontStruct;

X は 1バイト/文字の形式、2バイト/文字の行列形式と、 16ビット文字形式のテキスト操作をサポートしている。 あるフォントはこれらの形式のいずれでも使用できるが、 1バイト/文字のテキストのリクエストだけが単独のバイト(つまり、2バイトフォントの最初の列) を指定できる。 2バイトフォントは定義された文字の2次元行列として見るべきである。 byte1 はフォントの定義された列の範囲を指定し、byte2 は定義された行の範囲を定義する。 1バイト/文字のフォントは列が1つ定義されており、 構造体で定義された byte2 は文字の範囲を定義する。

文字のバウンディングボックスは文字の XCharStruct によって定義される。 フォントに含まれていない文字があるときにはデフォルト文字が使用される。 フォントの全ての文字のサイズが同じであるとき、 XFontStruct構造体の min_bounds と max_bounds の情報だけが使用される。

XFontStruct のメンバは以下の意味を持つ。

• direction メンバは FontLeftToRight か FontRightToLeft の値を持つ。 これは、 XCharStruct 要素の大部分が、正 (FontLeftToRight ) あるいは負 (FontRightToLeft )の文字幅を持っていることを示す単なるヒントに過ぎない。 コアプロトコルでは縦書きテキストのサポートは定義されていない。
• min_byte1 と max_byte1 メンバがいずれもゼロであれば、 min_char_or_byte2 は per_char 配列の最初の要素に対応する 線形文字インデックスを指定し、 max_char_or_byte2 は 最後の要素の線形文字インデックスを指定する。 .IP min_byte1 か max_byte1 がゼロでなければ、min_char_or_byte2 と max_char_or_byte2 は256未満であり、per_char 配列要素 N(0から数える) に対応する2バイト文字インデックス値は以下のようになる。 .IP .nf byte1 = N/D + min_byte1
  byte2 = N\\D + min_char_or_byte2 .IP .fi ここで： .IP .nf D = max_char_or_byte2 - min_char_or_byte2 + 1 / = integer division \\ = integer modulus .fi
• per_char ポインタが NULL であれば、最初と最後の文字インデックスの 間のグリフは全て同じ情報を持つ。 これは min_bounds と max_bounds で与えられる。
• all_chars_exist が True の場合、 per_char 配列内の全ての文字はゼロでないバウンディングボックスを持つ。
• default_char メンバは、未定義の文字や存在しない文字を 表示するときに用いられる文字を指定する。 default_char は(2バイト文字ではなく)16ビット文字である。 2バイト行列形式を使うフォントの場合、default_char は byte1 を 最上位バイト、byte2 を最下位バイトとする。 default_char 自身が未定義あるいは存在しない文字を指定した場合には、 未定義あるいは存在しない文字の表示は行われない。
• min_bounds と max_bounds メンバは、この配列の全ての 要素それぞれ(存在しない文字は除く)の XCharStruct 要素の最大値、最小値を持つ。 フォントのバウンディングボックス(全ての文字を同じ原点に置いて重ね合わせ、 得られた形状を囲む最少の長方形)の左上の座標は次のようになる:

  	[x + min_bounds.lbearing, y - max_bounds.ascent]
  

  .IP 幅は以下のようになる:

  	max_bounds.rbearing - min_bounds.lbearing
  

  .IP 高さは以下のようになる:

  	max_bounds.ascent + max_bounds.descent
  

• ascent メンバは、ベースライン上部のフォントの論理的な広さで、 行間を決定するために用いられる。 特定の文字はこれを越えることがある。
• descent メンバは、ベースライン下部のフォントの論理的な広さで、 行間を決定するために用いられる(0のこともある)。 特定の文字はこれを越えることがある。
• ベースラインが Y座標 y にあるとき、フォントの論理的な広さは Y 座標 (y - font.ascent) と (y + font.descent - 1) の内側である。 通常はテキストの行間の最少の送り量は ascent + descent で与えられる。

原点が[x, y]にある文字について、 XCharStruct コンポーネントを用いて記述される、文字のバウンディングボックス (つまり文字の形を囲む最小の長方形)は、次のようになる。:

[x + lbearing, y - ascent]

幅は次のようになる:

rbearing - lbearing

高さは次のようになる:

ascent + descent

隣の文字の原点は次のように定義される:

[x + width, y]

lbearing メンバは原点から文字が実際に描画される部分の左端までの大きさを定義する。 rbearing メンバは原点から文字が実際に描画される部分の右端までの大きさを定義する。 ascent メンバは原点から文字が実際に描画される部分の上端までの大きさを定義する。 descent メンバは原点から文字が実際に描画される部分の下端までの大きさを定義する。 width メンバは文字の論理的な幅を定義する。

ベースライン(文字原点のｙの位置)は論理的に下がらない文字のちょうど下のスキャンライン であるとみなされる。 descentが0の場合、 yより小さなY座標を持つピクセルだけ描かれ、 原点は論理的に出っ張っていない文字の左端に一致してるものとみなされる。 lbearingが0の場合、xより小さなX座標を持つピクセルは まったく描画されない。 XCharStructメトリックメンバーは全て負も取りうる。 the next character will be placed to the left of the current origin. widthが負の場合、 次の文字は現在の原点の左に置かれる。

Xプロトコルは XCharStruct構造体の任意のメンバーの解釈を定義していない。 存在しない文字は XCharStructの全てのメンバーが0にセットされたもので表示される。

フォントは全てのプロパティを持っているわけではない。 プロパティの値(例えば、longもしくはunsigned long)の解釈はプロパティの 先天的な知識から導かれる。 フォントプロパティの基本的な組はXコンソーシアム標準の X論理フォント表示規約に指定されるものである。

Loading and Freeing Fonts

Xlibはフォントを読み出したり、フォントの情報を取得したり、フォントをアンロードしたり、 フォントの情報を解放したりするのに使う関数を提供する。 2,3のフォント関数は GContext resource ID or a font ID interchangeably. リソースID、もしくはフォントIDを交互に使う。

与えられたフォントを読みこむには、 XLoadFont を使う。

Font XLoadFont(display, name)
Display *display;
char *name;

display

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

name

フォントの名前を指定。 これはNULLで終る文字列である。

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

利用可能なフォントについての情報を得るには、 XQueryFont を使う。

XFontStruct *XQueryFont(display, font_ID)
Display *display;
XID font_ID;

display

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

font_ID

フォント ID か GContextを指定。

一つの操作で XLoadFontと XQueryFontを行うには、 XLoadQueryFont を使う。

XFontStruct *XLoadQueryFont(display, name)
Display *display;
char *name;

display

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

name

フォントの名前を指定。 これはNULLで終る文字列である。

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

フォントをアンロードしたり、 XQueryFontや XLoadQueryFont に割り当てられたフォント構造体により使われるストレージ を解放するには、 XFreeFont を使う。

XFreeFont(display, font_struct)
Display *display;
XFontStruct *font_struct;

display

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

font_struct

フォントに対応する構造体を指定。

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

与えられたフォントプロパティを得るには、 XGetFontProperty を使う。

Bool XGetFontProperty(font_struct, atom, value_return)
XFontStruct *font_struct;
Atom atom;
unsigned long *value_return;

font_struct

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

atom

求めるプロパティ名に対するアトムを指定。

value_return

フォントプロパティの値が返される。

XLoadFont によりロードされたフォントをアンロードするには、 XUnloadFont を使う。

XUnloadFont(display, font)
Display *display;
Font font;

display

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

font

フォントを指定。

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

Obtaining and Freeing Font Names and Information

利用可能なサイズなどのリストに対するフォントタイプを問い合わせるときに、 ワイルドカード指定と一致するようなフォント名とフォント情報を取得する。

利用可能なフォント名のリストを得るには、 XListFonts を使う。

char **XListFonts(display, pattern, maxnames, actual_count_return)
Display *display;
char *pattern;
int maxnames;
int *actual_count_return;

display

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

pattern

NULL で終わるパターン文字列を指定。 これはワイルドカード文字を含んでいてもよい。

maxnames

返される名前の最大数を指定。

actual_count_return

フォント名の実際の数が返される。

フォント名の配列を解放するには、 XFreeFontNames を使う。

XFreeFontNames(list)
char *list[];

list

解放する文字列の配列を指定。

利用可能なフォントについて名前と情報を得るには、 XListFontsWithInfo を使う。

char **XListFontsWithInfo(display, pattern, maxnames, count_return, info_return)
Display *display;
char *pattern;
int maxnames;
int *count_return;
XFontStruct **info_return;

display

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

pattern

NULL で終わるパターン文字列を指定。これはワイルドカード文字を含んでいてもよい。

maxnames

返される名前の最大数を指定。

count_return

マッチしたフォント名の実際の数が返される。

info_return

フォント情報が返される。

フォント名の配列だけを解放する場合には、クライアントは XFreeFontNames を呼び出すべきである。 フォント名の配列とフォント情報の配列の両方を解放する場合と、 フォント情報の配列のみを解放する場合には、 クライアントは XFreeFontInfo を呼び出すべきである。

フォント構造体とフォント名を解放するには、 XFreeFontInfo を使う。

XFreeFontInfo(names, free_info, actual_count)
char **names;
XFontStruct *free_info;
int actual_count;

names

フォント名のリストを指定。

free_info

フォント情報を指定。

actual_count

フォント名の実際の数を指定。

Computing Character String Sizes

Xlibは8ビット、２バイト文字列についての幅、論理的な広さ、サーバ情報を 計算するために使う関数を提供する。 幅は全ての文字の文字幅を加えることにより計算される。 フォントが8ビットでも2バイトでも結果は同じである。 これらの関数はピクセル単位での文字メトリックスの合計を返す。

8ビット文字列の幅を決めるには、 XTextWidth を使う。

int XTextWidth(font_struct, string, count)
XFontStruct *font_struct;
char *string;
int count;

font_struct

幅の計算に使用するフォントを指定。

string

文字列を指定。

count

指定した文字列中の文字数を指定。

2バイト文字列の幅を決めるには、 XTextWidth16 を使う。

int XTextWidth16(font_struct, string, count)
XFontStruct *font_struct;
XChar2b *string;
int count;

font_struct

幅の計算に使用するフォントを指定。

string

文字列を指定。

count

指定した文字列中の文字数を指定。

Computing Logical Extents

与えられたフォントの8ビット文字列のバウンディングボックスを計算するには、 XTextExtents を使う。

XTextExtents(font_struct, string, nchars, direction_return, font_ascent_return,
font_descent_return, overall_return)
XFontStruct *font_struct;
char *string;
int nchars;
int *direction_return;
int *font_ascent_return, *font_descent_return;
XCharStruct *overall_return;

font_struct

XFontStruct 構造体を指定。

string

文字列を指定。

nchars

文字列内の文字数を指定。

direction_return

方向ヒント(direction hint)の値が返される (FontLeftToRightまたは FontRightToLeft )。

font_ascent_return

フォントの ascent 値が返される。

font_descent_return

フォントの descent 値が返される。

overall_return

ここに指定した XCharStruct 構造体に全てのサイズ情報が返される。

与えられたフォントで2バイトの文字列のバウンディングボックスを計算するには、 XTextExtents16 を使う。

XTextExtents16(font_struct, string, nchars, direction_return, font_ascent_return,
font_descent_return, overall_return)
XFontStruct *font_struct;
XChar2b *string;
int nchars;
int *direction_return;
int *font_ascent_return, *font_descent_return;
XCharStruct *overall_return;

font_struct

XFontStruct 構造体を指定。

string

文字列を指定。

nchars

文字列内の文字数を指定。

direction_return

方向ヒント(direction hint)の値が返される (FontLeftToRightまたは FontRightToLeft )。

font_ascent_return

フォントの ascent 値が返される。

font_descent_return

フォントの descent 値が返される。

overall_return

ここに指定した XCharStruct 構造体に全てのサイズ情報が返される。

ascent メンバは、文字列中の各文字 ascent 寸法の最大値に設定される。 descent メンバは descent 寸法の最大値に設定される。 width メンバには、文字列中のそれぞれの文字の幅の寸法の総和が設定される。 文字列中の各文字に対して、W を文字列中でその文字より前にある文字幅の 寸法の総和とする。 L はその文字の左側bearing寸法に W を加えたものとする。 R はその文字の右側bearing寸法に W を加えたものとする。 lbearing メンバは、文字列中の全ての文字についての L の最小値に設定される。 同じく rbearing は R の最大値に設定される。

2バイトの行列形式のインデックス(2-byte matrix indexing)ではなく、 線形インデックス(linear indexing)で定義されたフォントについては、 各 XChar2b 構造体は byte1 が最上位バイトである16ビットの数と解釈される。 フォントにデフォルト文字が定義されていない場合、 文字列中の未定義文字の寸法は全てゼロとして扱われる。

Querying Character String Sizes

与えられたフォントでの8ビット文字列のバウディングボックスについてサーバに問い合わせるには XQueryTextExtents を使う。

XQueryTextExtents(display, font_ID, string, nchars, direction_return, font_ascent_return,
font_descent_return, overall_return)
Display *display;
XID font_ID;
char *string;
int nchars;
int *direction_return;
int *font_ascent_return, *font_descent_return;
XCharStruct *overall_return;

display

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

font_ID

フォントIDかフォントを含む GContextの ID を指定。

string

文字列を指定。

nchars

文字列内の文字数を指定。

direction_return

方向ヒント(direction hint)の値が返される (FontLeftToRightまたは FontRightToLeft )。

font_ascent_return

フォントの ascent 値が返される。

font_descent_return

フォントの descent 値が返される。

overall_return

ここに指定した XCharStruct 構造体に全てのサイズ情報が返される。

与えられたフォントでの2バイト文字列のバウンディングボックスについてサーバに 問い合わせるには、 XQueryTextExtents16 を使う。

XQueryTextExtents16(display, font_ID, string, nchars, direction_return, font_ascent_return,
font_descent_return, overall_return)
Display *display;
XID font_ID;
XChar2b *string;
int nchars;
int *direction_return;
int *font_ascent_return, *font_descent_return;
XCharStruct *overall_return;

display

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

font_ID

フォントIDかフォントを含む GContextの ID を指定。

string

文字列を指定。

nchars

文字列内の文字数を指定。

direction_return

方向ヒント(direction hint)の値が返される (FontLeftToRightまたは FontRightToLeft )。

font_ascent_return

フォントの ascent 値が返される。

font_descent_return

フォントの descent 値が返される。

overall_return

ここに指定した XCharStruct 構造体に全てのサイズ情報が返される。

ascent メンバは、文字列中の各文字 ascent 寸法の最大値に設定される。 descent メンバは descent 寸法の最大値に設定される。 width メンバには、文字列中の各文字の幅の寸法の総和が設定される。 文字列中の各文字に対して、W を文字列中でその文字より前にある文字幅寸法の総和とする。 L はその文字の左側bearing寸法に W を加えたものとする。 R はその文字の右側bearing寸法に W を加えたものとする。 lbearing メンバは、文字列中の全ての文字についての L の最小値に設定される。 同じく rbearing は R の最大値に設定される。

2バイトの行列形式のインデックスではなく、線形インデックスで定義されたフォントについては、 各 XChar2b 構造体は byte1 が最上位バイトである16ビットの数と解釈される。 フォントにデフォルト文字が定義されていない場合、 文字列中の未定義文字の寸法は全てゼロとして扱われる。

寸法が全てゼロである文字は無視される。 フォントにデフォルト文字が定義されていない場合、 文字列中の未定義文字も無視される。

XQueryTextExtentsおよび XQueryTextExtents16はエラー BadFontBadGC を起こすことがある。

Drawing Text

この節は以下のものを描画する方法について述べる。

• 複合テキスト
• テキスト文字
• イメージテキスト文字

基本的なテキスト関数は XDrawTextと XDrawText16であり、以下の構造体を使う。

typedef struct {
	char *chars;	/* 文字列へのポインタ */ 
	int nchars;	/* 文字数 */ 
	int delta;	/* 文字列間の変化量 */ 
	Font font;	/* 表示に使うフォント。None ならば変更無し */ 
} XTextItem;

typedef struct {
	XChar2b *chars;	/* 2バイト文字列へのポインタ */ 
	int nchars;	/* 文字数 */ 
	int delta;	/* 文字列間の変化量 */ 
	Font font;	/* 表示に使うフォント。None ならば変更無し */ 
} XTextItem16;

font メンバが None でない場合、 表示前にフォントは切替えられ、新たなフォントが GC に格納される。 テキスト描画中にエラーが発生した場合も、 それより前のテキストアイテムは表示される。 文字のベースラインはテキスト描画関数で指定した x, y 座標を起点に描画される。

例として、 XDrawImageString によって描画される背景色の長方形を考える。 背景の長方形の左上隅をピクセル座標 (x, y) としたい場合には、 テキスト関数へは (x, y + ascent) をベースライン原点の座標として渡す。 ここで、ascent はフォントの ascent 値であり、 XFontStruct構造体で与えられる。 背景の長方形の左下隅をピクセル座標 (x, y) にしたい場合には、 テキスト関数へは (x, y, - descent + 1) をベースライン原点の座標として渡す。 descent は XFontStruct構造体で与えられる、フォントの descent 値である。

Drawing Complex Text

与えられたドロウアブルに8ビットの文字を描画するには、 XDrawText を使う。

XDrawText(display, d, gc, x, y, items, nitems)
Display *display;
Drawable d;
GC gc;
int x, y;
XTextItem *items;
int nitems;

display

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

d

ドロウアブルを指定。

gc

GC を指定。

x

y

x, y 座標を指定。これは指定したドロウアブルの原点からの相対座標であり、 最初の文字の原点を定義する。

items

テキストアイテムの配列を指定。

nitems

配列内のテキストアイテム数を指定。

与えられたドロウアブルに2バイト文字を描画するには、 XDrawText16 を使う。

XDrawText16(display, d, gc, x, y, items, nitems)
Display *display;
Drawable d;
GC gc;
int x, y;
XTextItem16 *items;
int nitems;

display

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

d

ドロウアブルを指定。

gc

GC を指定。

x

y

x, y 座標を指定。これは指定したドロウアブルの原点からの相対座標であり、 最初の文字の原点を定義する。

items

テキストアイテムの配列を指定。

nitems

配列内のテキストアイテム数を指定。

各テキストアイテムは順番に処理される。 アイテム内に None以外の font メンバがある場合、そのフォントは GC に格納され、 これに続くテキストに対して使用される。 テキスト要素 delta は文字列が描画される前の x 軸に沿っての 位置の追加的な変位を指定する。 delta は常に文字の原点に追加され、フォントのいかなる特性にも依存しない。 各文字のイメージは、GC 内のフォントで定義されるので、 ドロウアブルの fill 操作への追加マスクとして扱われる。 ドロウアブルはフォントの文字が1にセットされているビットを持つ点でのみ変更される。 テキストアイテムが BadFontエラーを起こした場合も、その前のテキストアイテムはおそらく既に描画されている。

2バイトの行列形式のインデックスでなく線形インデックスで定義されたフォントに対しては、 各 XChar2b構造体は最上位バイトが byte1 である16ビットの数として解釈される。

どちらの関数も以下の GC コンポーネントを使用する。 function, plane-mask, fill-style, font, subwindow-mode, clip-x-origin, clip-y-origin, clip-mask. また、以下の GC モード依存コンポーネントも使用する。 foreground, background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin.

XDrawTextと XDrawText16はエラー BadDrawable ,BadFont ,BadGC ,BadMatch を起こすことがある。

Drawing Text Characters

与えられたドロウアブルに8ビット文字を描画するには、 XDrawString を使う。

XDrawString(display, d, gc, x, y, string, length)
Display *display;
Drawable d;
GC gc;
int x, y;
char *string;
int length;

display

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

d

ドロウアブルを指定。

gc

GC を指定。

x

y

x, y 座標を指定。これは指定したドロウアブルの原点からの相対座標であり、 最初の文字の原点を定義する。

string

文字列を指定。

length

引き数 stirng 内の文字数を指定。

与えられたドロウアブルに2バイト文字を描画するには、 XDrawString16 を使う。

XDrawString16(display, d, gc, x, y, string, length)
Display *display;
Drawable d;
GC gc;
int x, y;
XChar2b *string;
int length;

display

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

d

ドロウアブルを指定。

gc

GC を指定。

x

y

x, y 座標を指定。これは指定したドロウアブルの原点からの相対座標であり、 最初の文字の原点を定義する。

string

文字列を指定。

length

引き数 stirng 内の文字数を指定。

どちらの関数も以下のGCコンポーネントを使用する。 function, plane-mask, fill-style, font, subwindow-mode, clip-x-origin, clip-y-origin, clip-mask. また、以下の GC モード依存コンポーネントも使用する。 foreground, background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin.

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

Drawing Image Text Characters

アプリケーションの中には、特にターミナルエミュレータにおいて、それぞれの 文字の前景色と背景色ビットが描かれているところにイメージテキストを表示する 必要がある。 これは多くのディスプレイに邪魔なちらつきを抑える。

与えられたドロウアブルに8ビットのイメージテキスト文字を描画するには、 XDrawImageString を使う。

XDrawImageString(display, d, gc, x, y, string, length)
Display *display;
Drawable d;
GC gc;
int x, y;
char *string;
int length;

display

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

d

ドロウアブルを指定。

gc

GC を指定。

x

y

最初の文字の原点の x, y 座標を指定。これは指定したドロウアブルの原点に対する相対座標で指定する。

string

文字列を指定。

length

引き数 string 中の文字数を指定。

与えられたドロウアブルに2バイトのイメージテキスト文字を描画するには、 XDrawImageString16 を使う。

XDrawImageString16(display, d, gc, x, y, string, length)
Display *display;
Drawable d;
GC gc;
int x, y;
XChar2b *string;
int length;

display

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

d

ドロウアブルを指定。

gc

GC を指定。

x

y

最初の文字の原点の x, y 座標を指定。これは指定したドロウアブルの原点に対する相対座標で指定する。

string

文字列を指定。

length

引き数 string 中の文字数を指定。

関数の動作としては、まず描画対象の長方形領域を GC で定義されている背景色の ピクセルで塗りつぶし、次に前景色でテキストを描く。 塗りつぶされる長方形の左上の点の座標は次のようになる。

[x, y - font-ascent]

幅は

overall-width

となり、高さは

font-ascent + font-descent

となる。 この overall-width, font-ascent, and font-descent は GC と文字列に対して XQueryTextExtents が返す値である。 これらの関数は、GC で定義されている function と fill-style を無視する。 実際に使われる function は GXcopy であり、実際に使われる fill-style は FillSolid である。

2バイト行列形式のインデックスで定義され、 XDrawImageString で使われるフォントに対しては、各バイトは byte2 として扱われ、 byte1 はゼロとして扱われる。

いずれの関数も以下の GC コンポーネントを使用する。 plane-mask, foreground, background, font, subwindow-mode, clip-x-origin, clip-y-origin, clip-mask.

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

Transferring Images between Client and Server

Xlibはクライアントとサーバ間でイメージを転送するのに使う関数を提供する。 サーバは異なるデータ形式を要求するので、 Xlibは完全にメモリ内のデータを示し、そのデータ上の基本的な操作を提供する イメージオブジェクトを提供する。 直接データを参照するよりイメージオブジェクトを通じてデータを参照するべきである。 しかし、Xlibライブラリの実装の中に特別な関数でプロシージャベクタに 関数を置き換えることにより通常使われるデータ形式を効率的に 扱うものもある。 サポートされる操作はイメージを破棄する、ピクセルを得る、ピクセルを格納する、 イメージの一部を取り出す、イメージに定数を加えるなどを含む(16.8 節を参照すること)。

この節で述べられているイメージを扱う関数は全て XImage 構造体を使用する。 この構造体はクライアントのメモリに存在するものとしてイメージを扱う。

typedef struct _XImage {
	int width, height;		/* イメージのサイズ */ 
	int xoffset;		/* X方向のピクセルオフセットの数 */ 
	int format;		/* XYBitmap, XYPixmap, ZPixmap */
	char *data;		/* イメージデータへのポインタ */ 
	int byte_order;		/* データのバイト順 LSBFirst,MSBFirst */ 
	int bitmap_unit;		/* quant. of scanline 8, 16, 32 */
	int bitmap_bit_order;		/* LSBFirst, MSBFirst */
	int bitmap_pad;		/* 8, 16 32 XYかZPixmapかどちらか */ 
	int depth;		/* イメージの深さ */ 
	int bytes_per_line;		/* 次のスキャンラインへのアクセレータ */ 
	int bits_per_pixel;		/* ピクセル当たりのビット(ZPixmap) */ 
	unsigned long red_mask;		/* z配列中のビット */ 
	unsigned long green_mask;
	unsigned long blue_mask;
	XPointer obdata;	/* 捕まえるためのオブジェクトルーチンに対するフック */ 
	struct funcs {		/* イメージ操作ルーチン */ 
		struct _XImage *(*create_image)();
		int (*destroy_image)();
		unsigned long (*get_pixel)();
		int (*put_pixel)();
		struct _XImage *(*sub_image)();
		int (*add_pixel)();
	} f;
} XImage;

イメージ構造体のイメージ操作ルーチンを初期化するには、 XInitImage を使う。

Status XInitImage(image)
XImage *image;

ximage

イメージを指定。

クライアントがイメージを生成した場合には、これを他の Xlib 関数に渡す前 に必ずこの関数を呼ばなければならない。 Xlib が生成あるいは返したイメージ構造体の場合は、 このような初期化は必要ない。

この関数は構造体の初期化に成功すればゼロでないステータスを返す。 エラー が起きた場合や構造体の矛盾が見つかった場合には、 この関数はゼロを返す。 この場合にはイメージは変更されない。

ディスプレイ上のドロウアブルの長方形とイメージを結合するには、 XPutImage を使う。

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;

display

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

d

ドロウアブルを指定。

gc

GC を指定。

image

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

src_x

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

src_y

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

dest_x

dest_y

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

width

height

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

イメージの特性(例えば、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 *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;

display

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

d

ドロウアブルを指定。

x

y

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

width

height

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

plane_mask

プレーンマスクを指定。

format

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

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

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

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

既に存在しているイメージ構造体に位置しているディスプレイ上 の長方形の定数をコピーするには、 XGetSubImage .

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;

display

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

d

ドロウアブルを指定。

x

y

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

width

height

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

plane_mask

プレーンマスクを指定。

format

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

dest_image

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

dest_x

dest_y

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

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

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