Other Alias
XAllocColor, XAllocNamedColor, XAllocColorCells, XFreeColors書式
Status XAllocColor(display, colormap, screen_in_out)Display *display;
Colormap colormap;
XColor *screen_in_out;
Status XAllocNamedColor(display, colormap,
color_name, screen_def_return, exact_def_return)
Display *display;
Colormap colormap;
char *color_name;
XColor *screen_def_return, *exact_def_return;
Status XAllocColorCells(display, colormap, contig,
plane_masks_return, nplanes,
pixels_return, npixels)
Display *display;
Colormap colormap;
Bool contig;
unsigned long plane_masks_return[];
unsigned int nplanes;
unsigned long pixels_return[];
unsigned int npixels;
Status XAllocColorPlanes(display, colormap, contig, pixels_return, ncolors, nreds, ngreens,
nblues, rmask_return, gmask_return, bmask_return)
Display *display;
Colormap colormap;
Bool contig;
unsigned long pixels_return[];
int ncolors;
int nreds, ngreens, nblues;
unsigned long *rmask_return, *gmask_return, *bmask_return;
XFreeColors(display, colormap, pixels, npixels, planes)
Display *display;
Colormap colormap;
unsigned long pixels[];
int npixels;
unsigned long planes;
引き数
- color_name
- 色定義の構造体を得たい色の名前を示す文字列(例えば red)を指定する。
- colormap
- カラーマップを指定する。
- contig
- プレーンが連続でなければならないかどうかを示す真偽値を指定する。
- display
- X サーバへの接続を指定する。
- exact_def_return
- 正確な RGB 値を指定する。
- ncolors
- 配列 pixels_return に返されるピクセル値の数を指定する。
- npixels
- ピクセルの数を指定する。
- nplanes
- プレーンマスクの配列に返されるプレーンマスクの数を指定する。
- nreds
-
- ngreens
-
- nblues
-
R, G, B のプレーンの数を指定する。 この値は負であってはならない。 - pixels
- ピクセル値の配列を指定する。
- pixels_return
- ピクセル値の配列が返される。
- plane_mask_return
- プレーンマスクの配列が返される。
- planes
- 解放するプレーンを指定する。
- rmask_return
-
- gmask_return
-
- bmask_return
- R, G, B プレーンに対するプレーンマスクが返される。
- screen_def_return
- ハードウェアで提供される最も近い RGB 値が返される。
- screen_in_out
- カラーマップで実際に使用される値を指定する。 あるいは、カラーマップで実際に使用される値が返される。
説明
関数 XAllocColor はハードウェアにサポートされている中から最も近い RGB 値に対応する 読み取り専用のカラーマップエントリーを割り当てる。 XAllocColor は、ハードウェアがサポートしている、指定した RGB 要素に最も近い色のピ クセル値と、実際に使用される RGB 値を返す。 対応するカラーマップセルは読み取り専用である。 また、 XAllocColor は成功時には 0 でない値を返し、失敗時には 0 を返す。 同じ実効 RGB 値を求めた複数のクライアントには、同一の読み取り専用の エントリーが割り当てられるので、クライアント間でエントリーを共有するこ とができる。 最後のクライアントが共有しているセルを解放した時、このセルは実際に解放 される。 XAllocColor は XColor 構造体の flags メンバは使用しないし、値の変更もしない。XAllocColor はエラー BadColor を起こすことがある。
関数 XAllocNamedColor は指定したカラーマップに対応するスクリーンのおいて、名前が付けられてい る色を問い合わせる。 この関数はデータベースでの正確な定義とスクリーンがサポートしている最も 近い色との両方を返す。 割り当てられたカラーセルは読み取り専用である。 ピクセル値は screen_def_return に返される。 色の名前のエンコーディングがホストポータブル文字エンコーディングでない 場合、結果は実装依存である。 大文字と小文字のいずれを使っても結果は同じである。 screen_def_return と exact_def_return が同じ構造体を指している場合、 pixel フィールドは正しく設定されるが、色の値は未定義である。 XAllocNamedColor はセルが割り当てられていた場合には 0 でない値を返し、そうでなければ 0 を返す。
XAllocNamedColor はエラー BadColor を起こすことがある。
delim %% 関数 XAllocColorCells は読み書き可能なカラーセルを割り当てる。 色の数は正の値でなければならず、プレーンの数は 0 以上でなければならな い。そうでない場合は BadValue エラーとなる。 ncolors と nplanes が要求された場合、ncolors 個のピクセルと nplane 個 のプレーンマスクが返される。 あるマスクが、他のマスクやピクセルと、1 に設定されたビットを共有する ことはない。 各ピクセルと0個以上のマスクとの論理和を取ることによって、 ncolors * %2 sup nplanes% 個の別々のピクセルを作ることができる。 これらの全ては、リクエストによって書き換えることができるように割り当て られる。 GrayScale や PseudoColor に対しては、各マスクはちょうど1ビットを持ち、これらは全て 1 に設定され る。 DirectColor に対しては、各マスクはちょうど3ビットを持ち、これらはすべて 1 に設定さ れる。 contig が True であり、全てのマスクの論理和が取られている場合には、1 に設定されてい る連続しているビットの集まり1つが GrayScale や PseudoColor に対して作られ、1 に設定されている3組の連続したビットの集まり(各pixel サブフィールド内に1つ)が DirectColor に対して作られる。 割り当てられたエントリーの RGB 値は未定義である。 XAllocColorCells は成功時には 0 でない値を返し、失敗時には 0 を返す。
XAllocColorCells はエラー BadColor, BadValue を起こすことがある。
delim %% 指定する ncolors は正の値で無ければならず、nreds, ngreens, nblues は 0 以上でなければならない。そうでない場合には、エラー BadValue となる。 ncolors 個の色、nreds 個の赤、ngreeens 個の緑、nblues 個の青が要求され た場合、ncolors 個のピクセルが返される。また、マスク内では ngreens 個、 nreds 個、nblues 個のビットがそれぞれ 1 に設定される。 contig が True ならば、各マスクは 1 に設定された連続なビットの集合となる。 あるマスクが、他のマスクやピクセルと、1 に設定されたビットを共有する ことはない。 DirectColor に対しては、各マスクは対応するピクセルサブフィールド内に置かれる。 マスクのサブセットと各ピクセル値の論理和を取ることによって、 ncolors * %2 sup (nreds+ngreens+nblues)% 個の個別のピクセル値を作るこ とができる。 これらの全てはリクエストによって割り当てられる。 しかし、カラーマップ内には ncolors * %2 sup nreds% 個の独立の red エントリーと ncolors * %2 sup ngreens% 個の独立の green エントリーと ncolors * %2 sup blues% 個の独立の blue エントリーしかない。 これは PseudoColor であっても同じである。 ピクセル値のカラーマップエントリーが( XStoreColors, XStoreColor, XStoreNamedColor の使用により)変更された時、ピクセルはマスクに従って分解され、対応する 独立したエントリーが更新される。 XAllocColorPlanes は成功時には 0 でない値を返し、失敗時には 0 を返す。
XAllocColorPlanes はエラー BadColor, BadValue を返すことがある。
関数 XFreeColors は、セルの解放を行う。解放されるセルは、その値が pixels 配列に存在して いるピクセルで表されているものである。 引き数 planes は、いずれのピクセルとも 1 に設定されたビットを共有しては ならない。 全てのピクセルの集合は、この引き数 planes のサブセットとピクセルの論理和 を取ることで作ることができる。 このリクエストは( XAllocColor, XAllocNamedColor, XAllocColorCells, XAllocColorPlanes を使用して) クライアントによって割り当てられたこれらのピクセルを全て解放する。 XAllocColorPlanes で得た個別のピクセルを解放しても、実際には関係するピクセルも全て解放さ れるまで、それらのピクセルは再利用できないことに注意せよ。 同様に、読み取り専用のエントリーは全てのクライアントから解放されるまで は実際に解放されない。また、クライアントが同じ読み取り専用のエントリー を複数回割り当てた場合は、エントリーが解放されるまでに何度も解放を 行わなければならない。
1つ以上のピクセルがエラーとなっていても、指定したピクセルで クライアントによってカラーマップ内に割り当てられたものは全て解放される。 指定したピクセルがカラーマップへの有効なインデックスでなかった場合には、 エラー BadValue となる。 指定したピクセルが、そのクライアントによって割り当てられていない(つ まり、割り当てられていないか、別のクライアントによってのみ割り当てられ ている)場合や、カラーマップの全てのエントリーが書き込み可能で作ら れている( XCreateColormap に AllocAll を渡している)場合には、 BadAccess エラーとなる。 複数のピクセルがエラーの場合、エラーが通知されるピクセルはどれかわから ない。
XFreeColors はエラー BadAccess, BadColor, BadValue を起こすことがある。
返り値
- BadAccess
- 割り当てられていないエントリーをクライアントが解放しようとした。
- BadAccess
- クライアントが読み取り専用のカラーマップエントリーに値を代入しようとし た。
- BadColor
- 引き数 Colormap の値が、定義されている Colormap を指していない。
- BadValue
- 指定された数値の中にリクエストの許容範囲を越えているものがある。引き数に対 して特定の範囲が指定されていない限り、引き数の型で定義されている全ての範 囲が許される。選択肢として定義されている引き数はこのエラーを起こすことが ある。