man/XAllocColor.man

   1 '\" e
   2 .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
   3 .\"
   4 .\" Permission is hereby granted, free of charge, to any person obtaining
   5 .\" a copy of this software and associated documentation files (the
   6 .\" "Software"), to deal in the Software without restriction, including
   7 .\" without limitation the rights to use, copy, modify, merge, publish,
   8 .\" distribute, sublicense, and/or sell copies of the Software, and to
   9 .\" permit persons to whom the Software is furnished to do so, subject to
  10 .\" the following conditions:
  11 .\"
  12 .\" The above copyright notice and this permission notice shall be included
  13 .\" in all copies or substantial portions of the Software.
  14 .\"
  15 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  16 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  17 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  18 .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
  19 .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
  20 .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  21 .\" OTHER DEALINGS IN THE SOFTWARE.
  22 .\"
  23 .\" Except as contained in this notice, the name of the X Consortium shall
  24 .\" not be used in advertising or otherwise to promote the sale, use or
  25 .\" other dealings in this Software without prior written authorization
  26 .\" from the X Consortium.
  27 .\"
  28 .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
  29 .\" Digital Equipment Corporation
  30 .\"
  31 .\" Portions Copyright \(co 1990, 1991 by
  32 .\" Tektronix, Inc.
  33 .\"
  34 .\" Permission to use, copy, modify and distribute this documentation for
  35 .\" any purpose and without fee is hereby granted, provided that the above
  36 .\" copyright notice appears in all copies and that both that copyright notice
  37 .\" and this permission notice appear in all copies, and that the names of
  38 .\" Digital and Tektronix not be used in in advertising or publicity pertaining
  39 .\" to this documentation without specific, written prior permission.
  40 .\" Digital and Tektronix makes no representations about the suitability
  41 .\" of this documentation for any purpose.
  42 .\" It is provided ``as is'' without express or implied warranty.
  43 .\"
  44 .\"
  45 .ds xT X Toolkit Intrinsics \- C Language Interface
  46 .ds xW Athena X Widgets \- C Language X Toolkit Interface
  47 .ds xL Xlib \- C Language X Interface
  48 .ds xC Inter-Client Communication Conventions Manual
  49 .na
  50 .de Ds
  51 .nf
  52 .\\$1D \\$2 \\$1
  53 .ft 1
  54 .\".ps \\n(PS
  55 .\".if \\n(VS>=40 .vs \\n(VSu
  56 .\".if \\n(VS<=39 .vs \\n(VSp
  57 ..
  58 .de De
  59 .ce 0
  60 .if \\n(BD .DF
  61 .nr BD 0
  62 .in \\n(OIu
  63 .if \\n(TM .ls 2
  64 .sp \\n(DDu
  65 .fi
  66 ..
  67 .de FD
  68 .LP
  69 .KS
  70 .TA .5i 3i
  71 .ta .5i 3i
  72 .nf
  73 ..
  74 .de FN
  75 .fi
  76 .KE
  77 .LP
  78 ..
  79 .de IN          \" send an index entry to the stderr
  80 ..
  81 .de C{
  82 .KS
  83 .nf
  84 .D
  85 .\"
  86 .\"     choose appropriate monospace font
  87 .\"     the imagen conditional, 480,
  88 .\"     may be changed to L if LB is too
  89 .\"     heavy for your eyes...
  90 .\"
  91 .ie "\\*(.T"480" .ft L
  92 .el .ie "\\*(.T"300" .ft L
  93 .el .ie "\\*(.T"202" .ft PO
  94 .el .ie "\\*(.T"aps" .ft CW
  95 .el .ft R
  96 .ps \\n(PS
  97 .ie \\n(VS>40 .vs \\n(VSu
  98 .el .vs \\n(VSp
  99 ..
 100 .de C}
 101 .DE
 102 .R
 103 ..
 104 .de Pn
 105 .ie t \\$1\fB\^\\$2\^\fR\\$3
 106 .el \\$1\fI\^\\$2\^\fP\\$3
 107 ..
 108 .de ZN
 109 .ie t \fB\^\\$1\^\fR\\$2
 110 .el \fI\^\\$1\^\fP\\$2
 111 ..
 112 .de hN
 113 .ie t <\fB\\$1\fR>\\$2
 114 .el <\fI\\$1\fP>\\$2
 115 ..
 116 .de NT
 117 .ne 7
 118 .ds NO Note
 119 .if \\n(.$>$1 .if !'\\$2'C' .ds NO \\$2
 120 .if \\n(.$ .if !'\\$1'C' .ds NO \\$1
 121 .ie n .sp
 122 .el .sp 10p
 123 .TB
 124 .ce
 125 \\*(NO
 126 .ie n .sp
 127 .el .sp 5p
 128 .if '\\$1'C' .ce 99
 129 .if '\\$2'C' .ce 99
 130 .in +5n
 131 .ll -5n
 132 .R
 133 ..
 134 .               \" Note End -- doug kraft 3/85
 135 .de NE
 136 .ce 0
 137 .in -5n
 138 .ll +5n
 139 .ie n .sp
 140 .el .sp 10p
 141 ..
 142 .ny0
 143 '\" e
 144 .TH XAllocColor __libmansuffix__ __xorgversion__ "XLIB FUNCTIONS"
 145 .SH NAME
 146 XAllocColor, XAllocNamedColor, XAllocColorCells, XAllocColorPlanes, XFreeColors \- allocate and free colors
 147 .SH SYNTAX
 148 .HP
 149 Status XAllocColor\^(\^Display *\fIdisplay\fP, Colormap \fIcolormap\fP\^,
 150 XColor *\fIscreen_in_out\fP\^);
 151 .HP
 152 Status XAllocNamedColor\^(\^Display *\fIdisplay\fP, Colormap \fIcolormap\fP\^,
 153 char *\fIcolor_name\fP\^, XColor *\fIscreen_def_return\fP\^, XColor
 154 *\fIexact_def_return\fP\^);
 155 .HP
 156 Status XAllocColorCells\^(\^Display *\fIdisplay\fP, Colormap \fIcolormap\fP\^,
 157 Bool \fIcontig\fP\^, unsigned long \fIplane_masks_return\fP[\^]\^, unsigned int
 158 \fInplanes\fP\^, unsigned long \fIpixels_return\fP[\^]\^, unsigned int
 159 \fInpixels\fP\^);
 160 .HP
 161 Status XAllocColorPlanes\^(\^Display *\fIdisplay\fP, Colormap
 162 \fIcolormap\fP\^, Bool \fIcontig\fP\^, unsigned long
 163 \fIpixels_return\fP[\^]\^, int \fIncolors\fP\^, int \fInreds\fP\^, int
 164 \fIngreens\fP\^, int \fInblues\fP\^, unsigned long *\fIrmask_return\fP\^,
 165 unsigned long *\fIgmask_return\fP\^, unsigned long *\fIbmask_return\fP\^);
 166 .HP
 167 int XFreeColors\^(\^Display *\fIdisplay\fP, Colormap \fIcolormap\fP\^, unsigned
 168 long \fIpixels\fP\^[\^], int \fInpixels\fP\^, unsigned long \fIplanes\fP\^);
 169 .IP \fIcolor_name\fP 1i
 170 Specifies the color name string (for example, red) whose color
 171 definition structure you want returned.
 172 .IP \fIcolormap\fP 1i
 173 Specifies the colormap.
 174 .IP \fIcontig\fP 1i
 175 Specifies a Boolean value that indicates whether the planes must be contiguous.
 176 .IP \fIdisplay\fP 1i
 177 Specifies the connection to the X server.
 178 .IP \fIexact_def_return\fP 1i
 179 Returns the exact RGB values.
 180 .IP \fIncolors\fP 1i
 181 Specifies the number of pixel values that are to be returned in the
 182 pixels_return array.
 183 .IP \fInpixels\fP 1i
 184 Specifies the number of pixels.
 185 .IP \fInplanes\fP 1i
 186 Specifies the number of plane masks that are to be returned in the plane masks
 187 array.
 188 .IP \fInreds\fP 1i
 189 .br
 190 .ns
 191 .IP \fIngreens\fP 1i
 192 .br
 193 .ns
 194 .IP \fInblues\fP 1i
 195 .br
 196 .ns
 197 Specify the number of red, green, and blue planes.
 198 The value you pass must be nonnegative.
 199 .IP \fIpixels\fP 1i
 200 Specifies an array of pixel values.
 201 .IP \fIpixels_return\fP 1i
 202 Returns an array of pixel values.
 203 .IP \fIplane_mask_return\fP 1i
 204 Returns an array of plane masks.
 205 .\" *** JIM: NEED MORE INFO FOR THIS. ***
 206 .IP \fIplanes\fP 1i
 207 Specifies the planes you want to free.
 208 .IP \fIrmask_return\fP 1i
 209 .br
 210 .ns
 211 .IP \fIgmask_return\fP 1i
 212 .br
 213 .ns
 214 .IP \fIbmask_return\fP 1i
 215 Return bit masks for the red, green, and blue planes.
 216 .IP \fIscreen_def_return\fP 1i
 217 Returns the closest RGB values provided by the hardware.
 218 .IP \fIscreen_in_out\fP 1i
 219 Specifies and returns the values actually used in the colormap.
 220 .SH DESCRIPTION
 221 The
 222 .ZN XAllocColor
 223 function allocates a read-only colormap entry corresponding to the closest
 224 RGB value supported by the hardware.
 225 .ZN XAllocColor
 226 returns the pixel value of the color closest to the specified
 227 RGB elements supported by the hardware
 228 and returns the RGB value actually used.
 229 The corresponding colormap cell is read-only.
 230 In addition,
 231 .ZN XAllocColor
 232 returns nonzero if it succeeded or zero if it failed.
 233 .IN "Color map"
 234 .IN "Color" "allocation"
 235 .IN "Allocation" "colormap"
 236 .IN "read-only colormap cells"
 237 Multiple clients that request the same effective RGB value can be assigned
 238 the same read-only entry, thus allowing entries to be shared.
 239 When the last client deallocates a shared cell, it is deallocated.
 240 .ZN XAllocColor
 241 does not use or affect the flags in the
 242 .ZN XColor
 243 structure.
 244 .LP
 245 .ZN XAllocColor
 246 can generate a
 247 .ZN BadColor
 248 error.
 249 .LP
 250 The
 251 .ZN XAllocNamedColor
 252 function looks up the named color with respect to the screen that is
 253 associated with the specified colormap.
 254 It returns both the exact database definition and
 255 the closest color supported by the screen.
 256 The allocated color cell is read-only.
 257 The pixel value is returned in screen_def_return.
 258 If the color name is not in the Host Portable Character Encoding,
 259 the result is implementation-dependent.
 260 Use of uppercase or lowercase does not matter.
 261 If screen_def_return and exact_def_return
 262 point to the same structure, the pixel field will be set correctly,
 263 but the color values are undefined.
 264 .ZN XAllocNamedColor
 265 returns nonzero if a cell is allocated;
 266 otherwise, it returns zero.
 267 .LP
 268 .ZN XAllocNamedColor
 269 can generate a
 270 .ZN BadColor
 271 error.
 272 .LP
 273 .EQ
 274 delim %%
 275 .EN
 276 The
 277 .ZN XAllocColorCells
 278 function allocates read/write color cells.
 279 The number of colors must be positive and the number of planes nonnegative,
 280 or a
 281 .ZN BadValue
 282 error results.
 283 If ncolors and nplanes are requested,
 284 then ncolors pixels
 285 and nplane plane masks are returned.
 286 No mask will have any bits set to 1 in common with
 287 any other mask or with any of the pixels.
 288 By ORing together each pixel with zero or more masks,
 289 ncolors * %2 sup nplanes% distinct pixels can be produced.
 290 All of these are
 291 allocated writable by the request.
 292 For
 293 .ZN GrayScale
 294 or
 295 .ZN PseudoColor ,
 296 each mask has exactly one bit set to 1.
 297 For
 298 .ZN DirectColor ,
 299 each has exactly three bits set to 1.
 300 If contig is
 301 .ZN True
 302 and if all masks are ORed
 303 together, a single contiguous set of bits set to 1 will be formed for
 304 .ZN GrayScale
 305 or
 306 .ZN PseudoColor
 307 and three contiguous sets of bits set to 1 (one within each
 308 pixel subfield) for
 309 .ZN DirectColor .
 310 The RGB values of the allocated
 311 entries are undefined.
 312 .ZN XAllocColorCells
 313 returns nonzero if it succeeded or zero if it failed.
 314 .LP
 315 .ZN XAllocColorCells
 316 can generate
 317 .ZN BadColor
 318 and
 319 .ZN BadValue
 320 errors.
 321 .LP
 322 .EQ
 323 delim %%
 324 .EN
 325 The specified ncolors must be positive;
 326 and nreds, ngreens, and nblues must be nonnegative,
 327 or a
 328 .ZN BadValue
 329 error results.
 330 If ncolors colors, nreds reds, ngreens greens, and nblues blues are requested,
 331 ncolors pixels are returned; and the masks have nreds, ngreens, and
 332 nblues bits set to 1, respectively.
 333 If contig is
 334 .ZN True ,
 335 each mask will have
 336 a contiguous set of bits set to 1.
 337 No mask will have any bits set to 1 in common with
 338 any other mask or with any of the pixels.
 339 For
 340 .ZN DirectColor ,
 341 each mask
 342 will lie within the corresponding pixel subfield.
 343 By ORing together
 344 subsets of masks with each pixel value,
 345 ncolors * %2 sup (nreds+ngreens+nblues)% distinct pixel values can be produced.
 346 All of these are allocated by the request.
 347 However, in the
 348 colormap, there are only ncolors * %2 sup nreds% independent red entries,
 349 ncolors * %2 sup ngreens% independent green entries,
 350 and ncolors * %2 sup nblues% independent blue entries.
 351 This is true even for
 352 .ZN PseudoColor .
 353 When the colormap entry of a pixel
 354 value is changed (using
 355 .ZN XStoreColors ,
 356 .ZN XStoreColor ,
 357 or
 358 .ZN XStoreNamedColor ),
 359 the pixel is decomposed according to the masks,
 360 and the corresponding independent entries are updated.
 361 .ZN XAllocColorPlanes
 362 returns nonzero if it succeeded or zero if it failed.
 363 .LP
 364 .ZN XAllocColorPlanes
 365 can generate
 366 .ZN BadColor
 367 and
 368 .ZN BadValue
 369 errors.
 370 .LP
 371 The
 372 .ZN XFreeColors
 373 function frees the cells represented by pixels whose values are in the
 374 pixels array.
 375 The planes argument should not have any bits set to 1 in common with any of the
 376 pixels.
 377 The set of all pixels is produced by ORing together subsets of
 378 the planes argument with the pixels.
 379 The request frees all of these pixels that
 380 were allocated by the client (using
 381 .IN XAllocColor
 382 .IN XAllocNamedColor
 383 .IN XAllocColorCells
 384 .IN XAllocColorPlanes
 385 .ZN XAllocColor ,
 386 .ZN XAllocNamedColor ,
 387 .ZN XAllocColorCells ,
 388 and
 389 .ZN XAllocColorPlanes ).
 390 Note that freeing an
 391 individual pixel obtained from
 392 .ZN XAllocColorPlanes
 393 may not actually allow
 394 it to be reused until all of its related pixels are also freed.
 395 Similarly,
 396 a read-only entry is not actually freed until it has been freed by all clients,
 397 and if a client allocates the same read-only entry multiple times,
 398 it must free the entry that many times before the entry is actually freed.
 399 .LP
 400 All specified pixels that are allocated by the client in the colormap are
 401 freed, even if one or more pixels produce an error.
 402 If a specified pixel is not a valid index into the colormap, a
 403 .ZN BadValue
 404 error results.
 405 If a specified pixel is not allocated by the
 406 client (that is, is unallocated or is only allocated by another client)
 407 or if the colormap was created with all entries writable (by passing
 408 .ZN AllocAll
 409 to
 410 .ZN XCreateColormap ),
 411 a
 412 .ZN BadAccess
 413 error results.
 414 If more than one pixel is in error,
 415 the one that gets reported is arbitrary.
 416 .LP
 417 .ZN XFreeColors
 418 can generate
 419 .ZN BadAccess ,
 420 .ZN BadColor ,
 421 and
 422 .ZN BadValue
 423 errors.
 424 .SH DIAGNOSTICS
 425 .TP 1i
 426 .ZN BadAccess
 427 A client attempted
 428 to free a color map entry that it did not already allocate.
 429 .TP 1i
 430 .ZN BadAccess
 431 A client attempted
 432 to store into a read-only color map entry.
 433 .TP 1i
 434 .ZN BadColor
 435 A value for a Colormap argument does not name a defined Colormap.
 436 .TP 1i
 437 .ZN BadValue
 438 Some numeric value falls outside the range of values accepted by the request.
 439 Unless a specific range is specified for an argument, the full range defined
 440 by the argument's type is accepted.  Any argument defined as a set of
 441 alternatives can generate this error.
 442 .SH "SEE ALSO"
 443 XCreateColormap(__libmansuffix__),
 444 XQueryColor(__libmansuffix__),
 445 XStoreColors(__libmansuffix__)
 446 .br
 447 \fI\*(xL\fP