XCreateColormap(3)

📦
version 1.8.14 · 8 versions
, in alpine 3.24, arch rolling, nixos 26.05, nixpkgs unstable

💅 XCreateColormap(3) — the libX11 era ✨

Okay bestie, sit down, grab a strawberry 🍓, because today we're talking colormaps — the Xlib functions XCreateColormap, XCopyColormapAndFree, XFreeColormap, and the XColor structure. That's create, copy, or destroy colormaps and the color struct itself. It's giving foundational. It's giving "your pixels literally cannot exist without me." 👑

🌸 SYNTAX 🌸

Colormap XCreateColormap(Display *display, Window w, Visual *visual, int alloc);

Colormap XCopyColormapAndFree(Display *display, Colormap colormap);

int XFreeColormap(Display *display, Colormap colormap);

Three little calls, one big vibe. Main character energy fr fr. 💖

🎀 ARGUMENTS 🎀

  • alloc — tells the server which colormap entries get allocated. Your options are AllocNone or AllocAll. That's it, that's the whole menu, no secret third thing. 🙈
  • colormap — the colormap you wanna create, copy, set, or destroy. Basically whichever one you're currently obsessing over.
  • display — the connection to the X server. Your link to the mothership, iykyk.
  • visual — a visual type that's supported on the screen. And listen: if that visual type is not one supported by the screen, you get a BadMatch error. Not a vibe. Read your visuals. 💀
  • w — the window on whose screen you want the colormap created. Tiny plot twist: the window is only used to figure out which screen you mean. It's a passenger princess, not the driver. 🚗✨

✨ DESCRIPTION ✨

So XCreateColormap creates a colormap of the specified visual type, for the screen that your specified window lives on, and hands you back the colormap ID. And again — bestie, hear me — the window is only there to determine the screen. That's it. That's its whole job. 🫶

Now the juicy part, the initial values of the entries:

  • For the visual classes GrayScale, PseudoColor, and DirectColor, the initial values of the colormap entries are undefined. Undefined! Meaning don't come crying to me about what's in there, nobody promised you anything. 😭
  • For StaticGray, StaticColor, and TrueColor, the entries do have defined values 🎉 — but those values are specific to the visual and are not defined by X. So defined, but not that defined. It's giving "trust me bro."
  • Also for StaticGray, StaticColor, and TrueColor: alloc must be AllocNone, or you get a BadMatch error. Periodt. No exceptions, no negotiating. 🚫
  • For the other visual classes, if alloc is AllocNone, the colormap starts out with zero allocated entries and clients can go ahead and allocate them. Fresh canvas energy. 🎨

Want the whole scoop on visual types? See section 3.1. Go read it, it's worth it, I promise. 📖

🌈 the AllocAll situation 🌈

If alloc is AllocAll, the entire colormap is allocated writable. Slay. But — the initial values of all allocated entries are undefined. Again. Yes. We know. 🙈

For GrayScale and PseudoColor, it's as if an XAllocColorCells call returned all pixel values from zero to N - 1, where N is the colormap entries value in the specified visual. Math but make it fashion. 💅

For DirectColor, it's as if an XAllocColorPlanes call returned a pixel value of zero and red_mask, green_mask, and blue_mask values containing the same bits as the corresponding masks in the specified visual. Mask match, cute. ✨

⚠️ But in all cases — every single one — none of these entries can be freed by using XFreeColors. You allocated the whole map, you live with the whole map. No takebacks. 💀

XCreateColormap can generate BadAlloc, BadMatch, BadValue, and BadWindow errors. Collect them all, I guess? 😭

🦋 XCopyColormapAndFree — the glow-up copy 🦋

This one creates a colormap of the same visual type, for the same screen as the specified colormap, and returns the new colormap ID. Same vibes, new ID. 💖

It also moves all of the client's existing allocation from the specified colormap over to the new colormap — with their color values intact and their read-only or writable characteristics intact — and then frees those entries in the specified colormap. Color values in the other entries of the new colormap are undefined. (You knew that was coming. 😌)

Two paths, bestie:

  1. If the specified colormap was created by the client with alloc set to AllocAll, the new colormap is also created with AllocAll, all color values for all entries get copied from the specified colormap, and then all entries in the specified colormap are freed. Clean slate, full handoff. 🫱
  2. If the specified colormap was not created by the client with AllocAll, then the allocations being moved are all those pixels and planes that have been allocated by the client using XAllocColor, XAllocNamedColor, XAllocColorCells, or XAllocColorPlanes — and that have not been freed since they were allocated. Track your allocations, bestie, keep receipts. 🧾

XCopyColormapAndFree can generate BadAlloc and BadColor errors. 👑

🧚 XFreeColormap — the goodbye 🧚

XFreeColormap deletes the association between the colormap resource ID and the colormap, and frees the colormap storage. Bye bestie, it was real. 🥲

🚨 But heads up: this function has no effect on the default colormap for a screen. That one's protected. Untouchable. Iconic.

The deets:

  • If the specified colormap is an installed map for a screen, it gets uninstalled. (See XUninstallColormap.)
  • If the specified colormap is defined as the colormap for a window — whether by XCreateWindow, XSetWindowColormap, or XChangeWindowAttributes — then XFreeColormap changes the colormap associated with that window to None and generates a ColormapNotify event.
  • And X does not define the colors displayed for a window with a colormap of None. That's a mystery even to me. 🔮

XFreeColormap can generate a BadColor error. 🌸

💜 STRUCTURES 💜

The XColor structure contains:

typedef struct {
        unsigned long pixel;    /* pixel value */
        unsigned short red, green, blue;        /* rgb values */
        char flags;     /* DoRed, DoGreen, DoBlue */
        char pad;
} XColor;

Look at her. Gorgeous. 🎀

Now the rules for red, green, and blue — these values are always in the range 0 to 65535 inclusive, independent of how many bits the display hardware actually uses. The server scales them down to whatever range the hardware wants. It's like me translating my group chat for the group project. 😭

  • Black is (0,0,0).
  • White is (65535,65535,65535).

And for some functions, the flags member controls which of red, green, and blue gets used — it can be the inclusive OR of zero or more of DoRed, DoGreen, and DoBlue. Pick your fighters. ⭐

🔥 DIAGNOSTICS 🔥

  • BadAlloc — the server failed to allocate the requested resource or server memory. It tried, it ran out, it's over. 😭
  • BadColor — a value for a Colormap argument does not name a defined Colormap. You referenced something that isn't real. Not me when I say I'll sleep early. 💀
  • BadMatch — an InputOnly window is used as a Drawable. Wrong tool, wrong job.
  • BadMatch — some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request. Right on paper, wrong in context. It's giving situationship. 🙈
  • BadValue — some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error. Boundaries, bestie. 💅
  • BadWindow — a value for a Window argument does not name a defined Window. Fake window, no cap. 🪟

🫶 SEE ALSO 🫶

Go read your friends, they miss you. 📚💖

Ok that's the whole page bestie, go forth and allocate responsibly 💅✨

Signing off: this is the X Version 11 release, libX11 1.8.14 💖 — catch you in the source, muah! 🎀🦋

📦 where this page comes from