New Font Spec
Tag Howard
tag at jthoward.dev
Tue Jul 9 02:44:10 UTC 2024
I've been following some of the discussions around new cursor theme
specs and wanted
to throw an idea out there to get some feedback on it.
The following is a modified section of the XCursor man page to
illustrate my thoughts
CURSOR FILES
Xcursor defines a new format for cursors on disk. Each file holds one
or more cursor images. Each cursor image is tagged with a nominal size
so that the best size can be selected automatically. Multiple cursors
of the same nominal size can be loaded together; applications are
expected to use them as an animated sequence.
+ Originally XCursor only specified uncompressed images and comments as
+ chunks. In addition to uncompressed images, icon files may now reference
+ external files such as vector images to provide scalable and/or higher
+ quality images than can be contained in a traditional image chunk. When
+ multiple file sections of the same subtype are loaded, they are
+ considered an animated sequence.
+ If Vector chunks are included and the client supports them, raster and
+ classic image chunks should be ignored and the vector chunks used instead.
+ If the client does not support vector chunks or none are provided then
+ XCursor will read the raster and image chunks together. Animation frames
+ for a given size must all be of the same chunk type. For example an icon
+ may consist of three Image chunks of the same size and three Raster chunks
+ of a different size, but it may not consist of an Image section and a
+ Raster which have the same size.
Cursor files are stored as a header containing a table of contents
followed by a sequence of chunks. The table of contents indicates the
type, subtype and position in the file of each chunk. The file header
looks like:
magic: CARD32 "Xcur" (0x58, 0x63, 0x75, 0x72)
header: CARD32 bytes in this header
version: CARD32 file version number
ntoc: CARD32 number of toc entries
toc: LISTofTOC table of contents
Each table of contents entry looks like:
type: CARD32 entry type
subtype: CARD32 type-specific label - size for images
position: CARD32 absolute byte position of table in file
Each chunk in the file has set of common header fields followed by
additional type-specific fields:
header: CARD32 bytes in chunk header (including type-specific fields)
type: CARD32 must match type in TOC for this chunk
subtype: CARD32 must match subtype in TOC for this chunk
version: CARD32 version number for this chunk type
~ There are currently three chunk types defined for cursor files; comments,
~ classic images, rasters, and vectors. Comments look like:
header: 20 Comment headers are 20 bytes
type: 0xfffe0001 Comment type is 0xfffe0001
subtype: { 1 (COPYRIGHT), 2 (LICENSE), 3 (OTHER) }
version: 1
length: CARD32 byte length of UTF-8 string
string: LISTofCARD8 UTF-8 string
Images look like:
header: 36 Image headers are 36 bytes
type: 0xfffd0002 Image type is 0xfffd0002
subtype: CARD32 Image subtype is the nominal size
version: 1
width: CARD32 Must be less than or equal to 0x7fff
height: CARD32 Must be less than or equal to 0x7fff
xhot: CARD32 Must be less than or equal to width
yhot: CARD32 Must be less than or equal to height
delay: CARD32 Delay between animation frames in milliseconds
pixels: LISTofCARD32 Packed ARGB format pixels
+ Rasters look like:
+
+ header: 40 Comment headers are 32 bytes
+ type: 0xfffe0003 File type is 0xfffe0003
+ subtype: { 1 (PNG) }
+ version: 1
+ size CARD32 Nominal size
+ width: CARD32 Must be less than or equal to 0x7fff, must be 0 for SVGs
+ height: CARD32 Must be less than or equal to 0x7fff, must be 0 for SVGs
+ xhot: CARD32 Must be less than or equal to width
+ yhot: CARD32 Must be less than or equal to height
+ delay: CARD32 Delay between animation frames in milliseconds
+ length: CARD32 byte length of UTF-8 path
+ path: LISTofCARD8 Slash separated UTF-8 encoded relative path
+ within the "content" directory
+
+ Vectors look like:
+
+ header: 32 Comment headers are 32 bytes
+ type: 0xfffe0003 File type is 0xfffe0003
+ subtype: { 1 (SVG) }
+ version: 1
+ xhot: CARD32 Must be less than or equal to width
+ yhot: CARD32 Must be less than or equal to height
+ delay: CARD32 Delay between animation frames in milliseconds
+ length: CARD32 byte length of UTF-8 path
+ path: LISTofCARD8 Slash separated UTF-8 encoded relative path
+ within the "content" directory
THEMES
Xcursor (mostly) follows the freedesktop.org spec for theming icons.
The default search path it uses is
~/.local/share/icons, ~/.icons, /usr/share/icons,
/usr/share/pixmaps
Within each of these directories, it searches for a directory using the
theme name:
o Within the theme directory, it looks for cursor files in the
"cursors" subdirectory.
Xcursor looks for a specific file, which must be one of the cursor
shape names, e.g., as used in XcursorLibraryLoadImage or
XcursorLibraryShape.
+ o Within the theme directory, it looks for paths referenced by a "File"
+ chunk in the "content" subdirectory. Such paths must not resolve to
+ any file not within the "content" directory
+
+ Such SVG files must not contain animation directives and must be
+ self contained (i.e. they may not reference other images).
o If it finds no matching cursor file in the "cursors" subdirectory,
Xcursor next looks for an "index.theme" file in each theme
directory to look for inherited themes. Those are lines in this
format:
Inherits = theme-name
Xcursor uses the first inherited theme-name, ignoring others which
may exist in a given "index.theme" file. If it finds an inherited
theme, Xcursor searches along the path to use that as well.
Xcursor ignores other keys in the "index.theme" file, including
"Name" (i.e., the name which a graphical application may use as the
presentation name).
More than one theme-name may be listed on the Inherits= line. The
freedesktop.org spec states that list items are separated by
commas. Xcursor also accepts semicolon, but translates both to
colon when searching the path. Xcursor expects only one Inherits=
line; the freedesktop.org spec is unclear whether multiple keys are
allowed.
If no theme is set, or if no cursor is found for the specified theme
anywhere along the path, Xcursor checks the "default" theme.
When Xcursor finds a cursor file, it stops searching. It always uses
the first cursor file found while searching along the path.
This is broadly an effort to match the capabilities of Hyprcursors
within the
confines of existing XCursor infrastructure. From what I have read of the
XCursor codebase, older programs would still be able understand a cursor
which
includes these extra chunks. However, any updated themes or applications
would
have access to PNG and SVG cursors without needing to overhaul their cursor
handling. For backwards compatibility themes would need to keep classic
image
chunks in the cursor files, but could cut back on how many they ship and
would
no longer be quite as constrained by file size.
Any thoughts? My background is in application side more than desktop
infrastructure so
it's possible I'm missing some major blocker here, but I'd love to hear
any feedback
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.freedesktop.org/archives/xdg/attachments/20240708/fff183dd/attachment.htm>
More information about the xdg
mailing list