1 Information about the icon theme cache format used by GTK+
2 for more information, see the mailing list threads at
4 http://mail.gnome.org/archives/gtk-devel-list/2004-April/msg00065.html
5 http://lists.freedesktop.org/archives/xdg/2004-October/005140.html
8 Back in May, Owen Taylor proposed [1] caching scheme for icon theme
9 information, to reduce the amount of stating and disk seeking at
10 application startup, and to reduce the memory overhead if each app
11 allocates all the icon theme data separately.
13 The proposal is to keep the information about the icons in the
14 directory tree below each icon theme directory in an mmap()able
15 cache file (There is basically one cache file per index.theme file).
17 The cache doesn't try to hold all information from the index.theme files
18 that you would need to do lookups; it turns out that with the icon theme
19 specification, this isn't even sensible - you can install a
21 $HOME/.local/share/icons/Bluecurve/index.theme
25 /usr/share/icons/Bluecurve/index.theme
27 and chances how lookup happens for icons in /usr/share/icons/Bluecurve.
29 We would like to propose the cache file format as an appendix to the
30 icon theme specification. One thing which still needs to be investigated
31 is caching of the actual image data; the file format is has an
32 IMAGE_DATA_OFFSET member to allow adding that compatibly. An
33 implementation of the caching scheme for GTK+ can be found at [2]. The
34 cache generator which is included in the patch depends only on glib, and
35 it may be a good idea to move it to freedesktop.org as well.
38 Regards, Matthias Clasen
41 The cache file format:
44 2 CARD16 MAJOR_VERSION 1
45 2 CARD16 MINOR_VERSION 0
47 4 CARD32 DIRECTORY_LIST_OFFSET
50 4 CARD32 N_DIRECTORIES
51 4*N_DIRECTORIES CARD32 DIRECTORY_OFFSET
55 4*N_BUCKETS CARD32 ICON_OFFSET
60 4 CARD32 IMAGE_LIST_OFFSET
64 8*N_IMAGES Image IMAGES
67 2 CARD16 DIRECTORY_INDEX
69 4 CARD32 IMAGE_DATA_OFFSET
78 4 CARD32 IMAGE_PIXEL_DATA_OFFSET
79 4 CARD32 IMAGE_META_DATA_OFFSET
81 4 CARD32 IMAGE_PIXEL_DATA_TYPE
82 4 CARD32 IMAGE_PIXEL_DATA_LENGTH
89 4 CARD32 EMBEDDED_RECT_OFFSET
90 4 CARD32 ATTACH_POINT_LIST_OFFSET
91 4 CARD32 DISPLAY_NAME_LIST_OFFSET
100 4 CARD32 N_ATTACH_POINTS
101 4*N_ATTACH_POINTS AttachPoint
108 4 CARD32 N_DISPLAY_NAMES
109 4*N_DISPLAY_NAMES DisplayName
112 4 CARD32 DISPLAY_LANG_OFFSET
113 4 CARD32 DISPLAY_NAME_OFFSET
118 * All offsets are from in bytes from the beginning of the file
120 * Strings are zero-terminated
122 * Directories are stored as relative paths.
124 * All numbers are in network (big-endian) order. This is
125 necessary because the data will be stored in arch-independent
126 directories like /usr/share/icons or even in user's
129 * The hash function is that used by g_str_hash()
132 icon_str_hash (gconstpointer key)
138 for (p += 1; *p != '\0'; p++)
139 h = (h << 5) - h + *p;
144 This should not be implemented by calling g_str_hash(). For
145 optimal results, N_BUCKETS should be typically be prime.
147 * The same file format is used for icon themes (e.g.,
148 /usr/share/icons/Bluecurve) and for unthemed icon directories
149 (e.g., /usr/share/pixmaps)
151 For an unthemed directory, N_DIRECTORIES==0 and each
152 image has a DIRECTORY_INDEX field of 0xFFFF.
154 * Up-to-dateness of a cache file is determined simply:
156 If the mod-time on the directory where the cache file
157 lives is newer than the mod-time of the cache file,
158 the cache file is out of date.
160 * Cache files have to be written atomically - write to a
161 temporary name, then move over the old file - so that
162 clients that have the old cache file open and mmap'ed
163 won't get corrupt data.