1XCreateColormap(3)              XLIB FUNCTIONS              XCreateColormap(3)
2
3
4

NAME

6       XCreateColormap,  XCopyColormapAndFree, XFreeColormap, XColor - create,
7       copy, or destroy colormaps and color structure
8

SYNTAX

10       Colormap XCreateColormap(Display *display, Window  w,  Visual  *visual,
11              int alloc);
12
13       Colormap XCopyColormapAndFree(Display *display, Colormap colormap);
14
15       int XFreeColormap(Display *display, Colormap colormap);
16

ARGUMENTS

18       alloc     Specifies the colormap entries to be allocated.  You can pass
19                 AllocNone or AllocAll.
20
21       colormap  Specifies the colormap that you want to create, copy, set, or
22                 destroy.
23
24       display   Specifies the connection to the X server.
25
26       visual    Specifies a visual type supported on the screen.  If the vis‐
27                 ual type is not one supported by the screen, a BadMatch error
28                 results.
29
30       w         Specifies  the  window  on  whose screen you want to create a
31                 colormap.
32

DESCRIPTION

34       The XCreateColormap function creates a colormap of the specified visual
35       type  for  the screen on which the specified window resides and returns
36       the colormap ID associated with it.  Note that the specified window  is
37       only used to determine the screen.
38
39       The initial values of the colormap entries are undefined for the visual
40       classes GrayScale, PseudoColor, and DirectColor.  For StaticGray, Stat‐
41       icColor, and TrueColor, the entries have defined values, but those val‐
42       ues are specific to the visual and are not defined  by  X.   For  Stat‐
43       icGray,  StaticColor, and TrueColor, alloc must be AllocNone, or a Bad‐
44       Match error results.  For the other visual classes, if alloc is  Alloc‐
45       None,  the colormap initially has no allocated entries, and clients can
46       allocate them.  For information about the  visual  types,  see  section
47       3.1.
48
49       If  alloc  is AllocAll, the entire colormap is allocated writable.  The
50       initial values of all allocated entries are undefined.   For  GrayScale
51       and  PseudoColor, the effect is as if an XAllocColorCells call returned
52       all pixel values from zero to N - 1, where N is  the  colormap  entries
53       value in the specified visual.  For DirectColor, the effect is as if an
54       XAllocColorPlanes call returned a pixel value  of  zero  and  red_mask,
55       green_mask, and blue_mask values containing the same bits as the corre‐
56       sponding masks in the specified visual.  However, in all cases, none of
57       these entries can be freed by using XFreeColors.
58
59       XCreateColormap  can generate BadAlloc, BadMatch, BadValue, and BadWin‐
60       dow errors.
61
62       The XCopyColormapAndFree function creates a colormap of the same visual
63       type  and for the same screen as the specified colormap and returns the
64       new colormap ID.  It also moves all of the client's existing allocation
65       from the specified colormap to the new colormap with their color values
66       intact and their read-only or writable characteristics intact and frees
67       those entries in the specified colormap.  Color values in other entries
68       in the new colormap are undefined.  If the specified colormap was  cre‐
69       ated by the client with alloc set to AllocAll, the new colormap is also
70       created with AllocAll, all color values for all entries are copied from
71       the  specified colormap, and then all entries in the specified colormap
72       are freed.  If the specified colormap was not  created  by  the  client
73       with  AllocAll,  the  allocations  to be moved are all those pixels and
74       planes that have been allocated by the client using  XAllocColor,  XAl‐
75       locNamedColor, XAllocColorCells, or XAllocColorPlanes and that have not
76       been freed since they were allocated.
77
78       XCopyColormapAndFree can generate BadAlloc and BadColor errors.
79
80       The XFreeColormap function deletes the association between the colormap
81       resource  ID and the colormap and frees the colormap storage.  However,
82       this function has no effect on the default colormap for a  screen.   If
83       the  specified  colormap  is an installed map for a screen, it is unin‐
84       stalled (see XUninstallColormap).  If the specified colormap is defined
85       as  the colormap for a window (by XCreateWindow, XSetWindowColormap, or
86       XChangeWindowAttributes), XFreeColormap changes the colormap associated
87       with  the  window to None and generates a ColormapNotify event.  X does
88       not define the colors displayed for a window with a colormap of None.
89
90       XFreeColormap can generate a BadColor error.
91

STRUCTURES

93       The XColor structure contains:
94
95       typedef struct {
96               unsigned long pixel;    /* pixel value */
97               unsigned short red, green, blue;        /* rgb values */
98               char flags;     /* DoRed, DoGreen, DoBlue */
99               char pad;
100       } XColor;
101
102       The red, green, and blue values are always in the range 0 to 65535  in‐
103       clusive, independent of the number of bits actually used in the display
104       hardware.  The server scales these values down to the range used by the
105       hardware.  Black is represented by (0,0,0), and white is represented by
106       (65535,65535,65535).  In some  functions,  the  flags  member  controls
107       which of the red, green, and blue members is used and can be the inclu‐
108       sive OR of zero or more of DoRed, DoGreen, and DoBlue.
109

DIAGNOSTICS

111       BadAlloc  The server failed  to  allocate  the  requested  resource  or
112                 server memory.
113
114       BadColor  A  value for a Colormap argument does not name a defined Col‐
115                 ormap.
116
117       BadMatch  An InputOnly window is used as a Drawable.
118
119       BadMatch  Some argument or pair of arguments has the correct  type  and
120                 range  but  fails  to match in some other way required by the
121                 request.
122
123       BadValue  Some numeric value falls outside the range of values accepted
124                 by  the request.  Unless a specific range is specified for an
125                 argument, the full range defined by the  argument's  type  is
126                 accepted.   Any argument defined as a set of alternatives can
127                 generate this error.
128
129       BadWindow A value for a Window argument does not name a defined Window.
130

SEE ALSO

132       XAllocColor(3), XChangeWindowAttributes(3),  XCreateWindow(3),  XQuery‐
133       Color(3), XStoreColors(3)
134       Xlib - C Language X Interface
135
136
137
138X Version 11                     libX11 1.8.1               XCreateColormap(3)
Impressum