名称

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プレーンが連続していなければならないか否かを示すブール値を指定します。

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

exact_def_return
正確な RGB 値を返します。

ncolors配列 pixels_return に返されるピクセル値の数を指定します。

npixelsピクセル数を指定します。

nplanesプレーン配列 plane_masks_return に返されるプレーンマスク数を指定します。

nreds

ngreens

nblues
red(赤)、green(緑) および blue(青) のプレーン数を指定します。 値は、負数以外でなければなりません。

pixelsピクセル値の配列を指定します。

pixels_returnピクセル値の配列を返します。

plane_mask_return
プレーンマスクの配列を返します。

planes解放したいプレーンを指定します。

rmask_return

gmask_return

bmask_return
red(赤)、green(緑) および blue(青) のプレーンに対する ビットマスクを返します。

screen_def_return
ハードウェアがもっている最も近い RGB 値を返します。

screen_in_out
カラーマップで実際に使用された値を指定、あるいは返します。

解説

XAllocColor 関数は、ハードウェアがサポートする最も近い RGB 値に対応する リードオンリのカラーマップエントリを割り当てます。 XAllocColor は、ハードウェアがサポートする指定された RGB 要素に最も近い カラーのピクセル値を返し、 また実際に使用されている RGB 値を返します。 対応するカラーマップセルは、リードオンリです。 さらに XAllocColor は、成功であれば 0 でない値、また、失敗であれば 0 を 返します。 複数のクライアントが同じ有効な RGB 値をリクエストすると、同じ リードオンリーのエントリが割り当てられます。 このようにエントリの共有が許可されています。 最後のクライアントが共有セルの割り当てを解除すると、このセルは 解放されます。 XAllocColor は、 XColor 構造体のフラグを使用しませんし、あるいはこれらのフラグに 影響を与えません。 XAllocColor の返しうるエラーは、 BadColor です。 XAllocNamedColor 関数は、指定されたカラーマップに対応するスクリーンに関して 指定された名前のカラーを捜します。 そして、正確なデータベース定義およびスクリーンがサポートする もっとも近いカラーを返します。 割り当てられているカラーセルは、リードオンリです。 ピクセル値は screen_def_return に返されます。 カラー名が ホストポータブル文字コード (Host Portable Character Encoding) に ない場合、結果はインプリメンテーションにより異なります。 大文字、小文字は両方使用できます。 XLookupColor は、セルが割り当てられた場合、ゼロ以外の値を返します。 それ以外の場合は、ゼロを返します。 XAllocNamedColor の返しうるエラーは、 BadColor です。 XAllocColorCells 関数は、読書き可能なカラーセルを割り当てます。 カラー数は正で、プレーン数は負数以外でなければなりません。 さもなければ BadValue エラーが生じます。 ncolors および nplanes にセットされた値によって、 ncolors 個のピクセルおよび nplane 個のプレーンマスクが返されます。 マスクの 1 がセットされているビットは、他のマスク あるいはどのピクセルでも 1 に設定されていません。 したがって、各ピクセルと、0 個あるいは複数個のマスクとの 論理和をとることで、 ncolors ∗2nplanes 種類のピクセルを生成することができます。 これらすべてはリクエストにより割り当てられ書込み可能です。 GrayScale または PseudoColor に対するマスクは、1 つのビットだけが 1 に設定されます。 DirectColor に対するマスクは、3 つのビットが 1 に設定されます。 contig が True で、すべてのマスクの論理和をとる場合、 GrayScale または PseudoColor に対して 1 に設定された 1 組の連続したビットが形成され、 DirectColor に対して 1 に設定された 3 組の連続したビット (各ピクセルサブフィールド内で 1 つ）が形成されます。 割り当てられたエントリの RGB は定義されません。 XAllocColorCells は、成功であれば 0 でない値を、失敗であれば 0 を返します。 XAllocColorCells の返しうるエラーは、 BadColor および BadValue です。 XAllocColorPlanes 関数は、読書き可能なカラーリソースを割り当てます。 指定される ncolors は、正でなければなりません。 nreds、ngreens および nblues は、負数以外でなければなりません。 さもなければ BadValue エラーが生じます。 ncolors 個の colors 、nreds 個の reds 、ngreens 個の greens および nblues 個の blues が要求された場合、ncolors 個の pixels が返され、 また、マスクのそれぞれには nreds 、ngreens および nblues 個の ビットが 1 に設定されます。 contig が True であれば、各マスクの、ひと組の連続したビットが、1 に設定されます。 マスクの 1 が設定されているビットは他のマスク、あるいは どのピクセルでも 1 には設定されていません。 DirectColor の場合、 各マスクは 対応するピクセルのサブフィールド内にあります。 マスクのサブセットと各ピクセルとの論理和をとることで、 ncolors ∗2(nreds+ngreens+nblues) 種類のピクセル値を 生成することができます。 これらすべては、リクエストにより割り当てられます。 ただし、カラーマップでは ncolors ∗2nreds 個の独立したレッド用エントリ、 ncolors ∗2ngreens 個の独立したグリーン用エントリ、 ncolors ∗2nblues 個の独立したブルー用エントリ があります。 これは PseudoColor の場合にもあてはまります。 ピクセル値のカラーマップエントリが変更された場合（ XStoreColors、 XStoreColor または XStoreNamedColor を使用して）、ピクセルはマスクに従い分解され、対応する 独立したエントリが更新されます。 XAllocColorPlanes は、成功すれば 0 でない値を、失敗であれば 0 を返します。 XAllocColorPlanes の返しうるエラーは、 BadColor および BadValue です。 XFreeColors 関数は、値が配列 pixels にあるピクセルによって表されるセルを解放します。 planes 引数は、1 の設定されているビットがピクセルでも同様に 1 に 設定されてはいけません。 planes 引数の任意のサブセットとピクセルとの論理和をとることによって すべてのピクセルが生成できます。 このリクエストにより、クライアント（ XAllocColor、 XAllocNamedColor、 XAllocColorCells および XAllocColorPlanes を使用して） が割り当てたピクセルすべてを解放します。 なお、 XAllocColorPlanes から得た各ピクセルを解放しても、実際には関連するピクセルすべてが 解放されるまで再使用することができないことに注意してください。 同様に、リードオンリーのエントリは実際にはすべてのクライアントによって 開放されないかぎり、開放されません。 もし、あるクライアントが同じリードオンリーのエントリを何度も アロケートしているならば、そのエントリが実際に開放される前に そのクライアントは何度もそのエントリを開放しなくてはなりません。 たとえひとつ以上のピクセルにエラーがある場合でさえ、 クライアントが割り当てたピクセルがすべてカラーマップ上にあるなら 解放されます。 指定されたピクセルがカラーマップに対して有効なインデックスでなければ、 BadValue エラーが生じます。 指定されたピクセルがそのクライアントによって割り当てられたものでなければ （すなわち、実際に割り当てられていない場合、あるいは 他のクライアントにより割り当てられた場合)、 あるいは ( AllocAll を XCreateColormap に渡して) カラーマップのエントリを書き込み可として作成した場合は、 BadAccess エラーが生じます。 2 つ以上のピクセルにエラーがあれば、どのピクセルについて 報告されたかは不定です。 XFreeColors の返しうるエラーは BadAccess、 BadColor および BadValue です。

診断

BadAccess クライアントが、割り当てられていないカラーマップエントリを 解放しようとした。

BadAccess クライアントが、リードオンリのカラーマップエントリにストアしようとした。

BadColor Colormap 引数の値が、定義済みのカラーマップを指定していない。

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

関連事項

XCreateColormap(3X11), XQueryColor(3X11), XStoreColors(3X11)
Xlib − C Language X Interface

NEWS-OSRelease 4.2.1R