XAllocColor(3X11)

名前
XAllocColor, XAllocNamedColor, XAllocColorCells, XAllocColorPlanes, 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
    カラーマップで実際に使用される値を指定。 あるいは、カラーマップで実際に使用される値が返される。

説明
関数 はハードウェアにサポートされている中から最も近い RGB 値に対応するリー ドオンリーのカラーマップエントリーをアロケートする。 は、ハードウェアがサポートしている、指定した RGB 要素に最も近い色のピ クセル値と、実際に使用される RGB 値を返す。 対応するカラーマップセルはリードオンリーである。 また、 は成功時にはゼロでない値を返し、失敗時にはゼロを返す。 同じ実効 RGB 値を求めた複数のクライアントには、同一のリードオンリーの エントリーが割り当てられるので、クライアント間でエントリーを共有するこ とができる。 最後のクライアントが共有しているセルを解放した時、このセルは実際に解放 される。 は 構造体の flags メンバは使用しないし、値の変更もしない。

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

関数 は指定したカラーマップに対応するスクリーンのおいて、名前が付けられてい る色を問い合わせる。 この関数はデータベースでの正確な定義とスクリーンがサポートしている最も 近い色との両方を返す。 アロケートされるカラーセルはリードオンリーである。 ピクセル値は screen_def_return に返される。 色の名前のエンコーディングがホストポータブル文字エンコーディングでない 場合、結果は実装依存である。 大文字と小文字のいずれを使っても結果は同じである。 screen_def_return と exact_def_return が同じ構造体を指している場合、 pixel フィールドは正しく設定されるが、色の値は未定義である。 はセルがアロケートされた場合にゼロでない値を返し、そうでなければゼロを返す。

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

関数 は読み書き可能なカラーセルをアロケートする。 色の数は正の値でなければならず、プレーンの数はゼロ以上でなければならな い。そうでない場合は エラーとなる。 ncolors と nplanes が要求された場合、ncolors 個のピクセルと nplane 個 のプレーンマスクが返される。 あるマスクが、他のマスクやピクセルと、1にセットされたビットを共有する ことはない。 各ピクセルと0個以上のマスクとの論理和を取ることによって、 ncolors * %2 sup nplanes% 個の別々のピクセルを作ることができる。 これらの全ては、リクエストによって書き換えることができるようにアロケー トされる。 や に対しては、各マスクはちょうど1ビットを持ち、これらは全て1にセットされ る。 に対しては、各マスクはちょうど3ビットを持ち、これらはすべて1にセットさ れる。 contig が であり、全てのマスクの論理和が取られている場合には、1にセットされてい る連続しているビットの集まり1つが や に対して作られ、1にセットされている3組の連続したビットの集まり(各pixel サブフィールド内に1つ)が に対して作られる。 アロケートされたエントリーの RGB 値は未定義である。 は成功時にはゼロでない値を返し、失敗時にはゼロを返す。

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

指定する ncolors は正の値で無ければならず、nreds, ngreens, nblues はゼ ロ以上でなければならない。そうでない場合には、エラー となる。 ncolors 個の色、nreds 個の赤、ngreeens 個の緑、nblues 個の青が要求され た場合、ncolors 個のピクセルが返される。また、マスク内では ngreens 個、 nreds 個、nblues 個のビットがそれぞれ1にセットされる。 contig が ならば、各マスクは1にセットされた連続なビットの集合となる。 あるマスクが、他のマスクやピクセルと、1にセットされたビットを共有する ことはない。 に対しては、各マスクは対応するピクセルサブフィールド内に置かれる。 マスクのサブセットと各ピクセル値の論理和を取ることによって、 ncolors * %2 sup (nreds+ngreens+nblues)% 個の個別のピクセル値を作るこ とができる。 これらの全てはリクエストによってアロケートされる。 しかし、カラーマップ内には ncolors * %2 sup nreds% 個の独立の red エントリーと ncolors * %2 sup ngreens% 個の独立の green エントリーと ncolors * %2 sup blues% 個の独立の blue エントリーしかない。 これは であっても同じである。 ピクセル値のカラーマップエントリーが( の使用により)変更された時、ピクセルはマスクに従って分解され、対応する 独立したエントリーが更新される。 は成功時にはゼロでない値を返し、失敗時にはゼロを返す。

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

関数 は、セルの解放を行う。解放されるセルは、その値が pixels 配列に存在して いるピクセルで表されているものである。 引き数 planes は、いずれのピクセルとも1にセットされたビットを共有しては ならない。 全てのピクセルの集合は、この引き数 planes のサブセットとピクセルの論理和 を取ることで作ることができる。 このリクエストは( を使用して) クライアントによってアロケートされたこれらのピクセルを全て解 放する。 で得た個別のピクセルを解放しても、実際には関係するピクセルも全て解放さ れるまで、それらのピクセルは再利用できないことに注意せよ。 同様に、リードオンリーのエントリーは全てのクライアントから解放されるまで は実際に解放されない。また、クライアントが同じリードオンリーのエントリー を複数回アロケートした場合は、エントリーが解放されるまでに何度も解放を 行わなければならない。

1つ以上のピクセルがエラーとなっていても、指定したピクセルでクライアントによってカラーマップ内にアロケートされたものは全て解放される。 指定したピクセルがカラーマップへの有効なインデックスでなかった場合には、 エラー となる。 指定したピクセルが、そのクライアントによってアロケートされていない(つ まり、アロケートされていないか、別のクライアントによってのみアロケート されている)場合や、カラーマップの全てのエントリーが書き込み可能で作ら れている( に を渡している)場合には、 エラーとなる。 複数のピクセルがエラーの場合、エラーが通知されるピクセルはどれかわから ない。

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

返り値

クライアントがアロケートしていないエントリーを解放しようとした。

クライアントがリードオンリーのカラーマップエントリーに値を入れようとし
    た。

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

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

関連項目
XCreateColormap(3X11), XQueryColor(3X11), XStoreColors(3X11)
Xlib - C Language X Interface