xcursorgen

Create an X cursor file using a configuration file

$ xcursorgen [path/to/config.cursor] [path/to/output_file]

$ xcursorgen --prefix [path/to/image_directory]/ [path/to/config.cursor] [path/to/output_file]

$ xcursorgen [path/to/config.cursor]

xcursorgen [-V] [-p] [-f] [-o outputfile] configfile

-V
    Displays the xcursorgen version number and exits.

-p
    Pads the generated cursor image to the nearest power of 2 dimension. Useful for older X servers or drivers with specific texture requirements.

-f
    Forces the output cursor to be in 32-bit ARGB (Alpha, Red, Green, Blue) format, even if the source images lack an alpha channel.

-o
    Specifies the path for the output cursor file. If omitted, the generated cursor data is written to standard output (stdout).

configfile
    The path to the input configuration file. This file describes the cursor frames, their sizes, hotspots, and animation delays.

xcursorgen is a utility within the X.Org project designed to convert one or more Portable Network Graphics (PNG) images into a binary X cursor file. These files, typically named Xcursor, are utilized by the X Window System to display custom mouse pointers. It supports the creation of both static and animated cursors. For animated cursors, multiple PNG images representing frames can be specified along with their display durations. A crucial aspect is the definition of a "hotspot" (xhot, yhot), which determines the precise active pixel within the cursor image. This tool is fundamental for developers and theme designers looking to customize the visual appearance of the mouse pointer in X-based desktop environments.

Proper transparency in cursors requires input PNG images with an alpha channel.
The format of the configfile is strict and must adhere to the expected structure for successful cursor generation.
Older X servers or display drivers might impose limitations on cursor dimensions or color depth, potentially affecting compatibility.

The configfile is a plain text file, where each line defines a single frame of a cursor. The typical format for each line is:
size filename xhot yhot [delay]
size: The nominal dimension (width and height) for the cursor frame, e.g., 24, 32, 48.
filename: The path to the PNG image file for this frame.
xhot: The X-coordinate of the 'hotspot' relative to the top-left corner of the image. This is the exact pixel that represents the mouse pointer's logical position.
yhot: The Y-coordinate of the 'hotspot'.
delay: (Optional) For animated cursors, this specifies the display duration of the frame in milliseconds. If omitted, the frame is considered static or the last frame of a non-looping animation.

A simple static cursor:
32 cursor.png 16 16

An animated cursor (assuming frame1.png, frame2.png, etc., exist):
32 frame1.png 16 16 100
32 frame2.png 16 16 100
32 frame3.png 16 16 100

xcursorgen is an integral part of the X.Org project's libXcursor library. Its development emerged to standardize and streamline the process of creating custom cursors for the X Window System. It provides a more robust and flexible alternative to earlier, less capable methods for cursor definition, aligning with the ongoing efforts to enhance the graphical capabilities and user experience of X.

xsetroot(1), xrdb(1), xcursortool(1), update-alternatives(8) (often used for default cursor theme management on Debian-based systems)