Fwd: Caching icon theme information

[Lubos Lunak]

 For whoever is responsible for the icon handling in KDE, in case they're not 
on the xdg list.

----------  Forwarded Message  ----------

Subject: Caching icon theme information
Date: Wednesday 13 of October 2004 22:17
From: Matthias Clasen <mclasen at redhat.com>
To: xdg-list at freedesktop.org
Cc: otaylor at redhat.com

Back in May, Owen Taylor proposed [1] caching scheme for icon theme
information, to reduce the amount of stating and disk seeking at
application startup, and to reduce the memory overhead if each app
allocates all the icon theme data separately.

The proposal is to keep the information about the icons in the
directory tree below each icon theme directory in an mmap()able
cache file (There is basically one cache file per index.theme file).

The cache doesn't try to hold all information from the index.theme files
that you would need to do lookups; it turns out that with the icon theme
specification, this isn't even sensible - you can install a

 $HOME/.local/share/icons/Bluecurve/index.theme

That overrides

 /usr/share/icons/Bluecurve/index.theme

and chances how lookup happens for icons in /usr/share/icons/Bluecurve.

We would like to propose the cache file format as an appendix to the
icon theme specification. One thing which still needs to be investigated
is caching of the actual image data; the file format is has an
IMAGE_DATA_OFFSET member to allow adding that compatibly. An
implementation of the caching scheme for GTK+ can be found at [2]. The
cache generator which is included in the patch depends only on glib, and
it may be a good idea to move it to freedesktop.org as well.


Regards, Matthias Clasen


The cache file format:

Header:
2  CARD16  MAJOR_VERSION 1
2  CARD16  MINOR_VERSION 0
4  CARD32  HASH_OFFSET
4  CARD32  DIRECTORY_LIST_OFFSET

DirectoryList:
4   CARD32  N_DIRECTORIES
4*N_DIRECTORIES CARD32  DIRECTORY_OFFSET

Hash:
4  CARD32  N_BUCKETS
4*N_BUCKETS CARD32  ICON_OFFSET

Icon:
4  CARD32  CHAIN_OFFSET
4  CARD32  NAME_OFFSET
4  CARD32  IMAGE_LIST_OFFSET

ImageList:
4  CARD32  N_IMAGES
4*N_IMAGES Image  IMAGES
Image:
2  CARD16  DIRECTORY_INDEX
2  ICON_FLAGS FLAGS
4  CARD32  IMAGE_DATA_OFFSET

ICON_FLAGS
HAS_SUFFIX_PNG 1
HAS_SUFFIX_XPM 2
HAS_SUFFIX_SVG 4
HAS_ICON_FILE 8



Notes:

* All offsets are from in bytes from the beginning of the file

* Strings are zero-terminated

* All numbers are in network (big-endian) order. This is
  necessary because the data will be stored in arch-independent
  directories like /usr/share/icons or even in user's
  home directories.

* The hash function is that used by g_str_hash()

  unsigned int
  icon_str_hash (gconstpointer key)
  {
    const char *p = key;
    unsigned int h = *p;

    if (h)
      for (p += 1; *p != '\0'; p++)
        h = (h << 5) - h + *p;

    return h;
  }

 This should not be implemented by calling g_str_hash(). For
 optimal results, N_BUCKETS should be typically be prime.

* The same file format is used for icon themes (e.g.,
  /usr/share/icons/Bluecurve) and for unthemed icon directories
  (e.g., /usr/share/pixmaps)

  For an unthemed directory, N_DIRECTORIES==0 and each
  image has a DIRECTORY_INDEX field of 0xFFFF.

* Up-to-dateness of a cache file is determined simply:

    If the mod-time on the directory where the cache file
    lives is newer than the mod-time of the cache file,
    the cache file is out of date.

* Cache files have to be written atomically - write to a
  temporary name, then move over the old file - so that
  clients that have the old cache file open and mmap'ed
  won't get corrupt data.


[1]
http://mail.gnome.org/archives/gtk-devel-list/2004-April/msg00065.html
[2] http://bugzilla.gnome.org/show_bug.cgi?id=154034


_______________________________________________
xdg mailing list
xdg at freedesktop.org
http://freedesktop.org/mailman/listinfo/xdg

-------------------------------------------------------

-- 
Lubos Lunak
KDE developer
---------------------------------------------------------------------
SuSE CR, s.r.o.  e-mail: l.lunak at suse.cz , l.lunak at kde.org
Drahobejlova 27  tel: +420 2 9654 2373
190 00 Praha 9   fax: +420 2 9654 2374
Czech Republic   http://www.suse.cz/