Pileus Git - ~andy/gtk/blob - docs/iconcache.txt

   1 Information about the icon theme cache format used by GTK+
   2 for more information, see the mailing list threads at
   3
   4 http://mail.gnome.org/archives/gtk-devel-list/2004-April/msg00065.html
   5 http://lists.freedesktop.org/archives/xdg/2004-October/005140.html
   6
   7
   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.
  12
  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).
  16
  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
  20
  21  $HOME/.local/share/icons/Bluecurve/index.theme
  22
  23 That overrides
  24
  25  /usr/share/icons/Bluecurve/index.theme
  26
  27 and chances how lookup happens for icons in /usr/share/icons/Bluecurve.
  28
  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.
  36
  37
  38 Regards, Matthias Clasen
  39
  40
  41 The cache file format:
  42
  43 Header:
  44 2                       CARD16          MAJOR_VERSION   1
  45 2                       CARD16          MINOR_VERSION   0
  46 4                       CARD32          HASH_OFFSET
  47 4                       CARD32          DIRECTORY_LIST_OFFSET
  48
  49 DirectoryList:
  50 4                       CARD32          N_DIRECTORIES
  51 4*N_DIRECTORIES         CARD32          DIRECTORY_OFFSET
  52
  53 Hash:
  54 4                       CARD32          N_BUCKETS
  55 4*N_BUCKETS             CARD32          ICON_OFFSET
  56
  57 Icon:
  58 4                       CARD32          CHAIN_OFFSET
  59 4                       CARD32          NAME_OFFSET
  60 4                       CARD32          IMAGE_LIST_OFFSET
  61
  62 ImageList:
  63 4                       CARD32          N_IMAGES
  64 8*N_IMAGES              Image           IMAGES
  65
  66 Image:
  67 2                       CARD16          DIRECTORY_INDEX
  68 2                       ICON_FLAGS      FLAGS
  69 4                       CARD32          IMAGE_DATA_OFFSET
  70
  71 ICON_FLAGS
  72 HAS_SUFFIX_PNG  1
  73 HAS_SUFFIX_XPM  2
  74 HAS_SUFFIX_SVG  4
  75 HAS_ICON_FILE   8
  76
  77 ImageData:
  78 4                       CARD32          IMAGE_PIXEL_DATA_OFFSET
  79 4                       CARD32          IMAGE_META_DATA_OFFSET
  80
  81 4                       CARD32          IMAGE_PIXEL_DATA_TYPE
  82 4                       CARD32          IMAGE_PIXEL_DATA_LENGTH
  83 N/A                     N/A             PIXEL_DATA
  84
  85 IMAGE_PIXEL_DATA_TYPE
  86 0 GdkPixdata format
  87
  88 MetaData:
  89 4                       CARD32          EMBEDDED_RECT_OFFSET
  90 4                       CARD32          ATTACH_POINT_LIST_OFFSET
  91 4                       CARD32          DISPLAY_NAME_LIST_OFFSET
  92
  93 EmbeddedRect:
  94 2                       CARD16          X0
  95 2                       CARD16          Y0
  96 2                       CARD16          X1
  97 2                       CARD16          Y1
  98
  99 AttachPointList:
 100 4                       CARD32          N_ATTACH_POINTS
 101 4*N_ATTACH_POINTS       AttachPoint
 102
 103 AttachPoint:
 104 2                       CARD16          X
 105 2                       CARD16          Y
 106
 107 DisplayNameList:
 108 4                       CARD32          N_DISPLAY_NAMES
 109 4*N_DISPLAY_NAMES       DisplayName
 110
 111 DisplayName:
 112 4                       CARD32          DISPLAY_LANG_OFFSET
 113 4                       CARD32          DISPLAY_NAME_OFFSET
 114
 115
 116 Notes:
 117
 118 * All offsets are from in bytes from the beginning of the file
 119
 120 * Strings are zero-terminated
 121
 122 * Directories are stored as relative paths.
 123
 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
 127   home directories.
 128
 129 * The hash function is that used by g_str_hash()
 130
 131   unsigned int
 132   icon_str_hash (gconstpointer key)
 133   {
 134     const char *p = key;
 135     unsigned int h = *p;
 136
 137     if (h)
 138       for (p += 1; *p != '\0'; p++)
 139         h = (h << 5) - h + *p;
 140
 141     return h;
 142   }
 143
 144  This should not be implemented by calling g_str_hash(). For
 145  optimal results, N_BUCKETS should be typically be prime.
 146
 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)
 150
 151   For an unthemed directory, N_DIRECTORIES==0 and each
 152   image has a DIRECTORY_INDEX field of 0xFFFF.
 153
 154 * Up-to-dateness of a cache file is determined simply:
 155
 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.
 159
 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.