diff options
author | Philip Withnall <philip.withnall@collabora.co.uk> | 2013-11-07 12:01:58 +0000 |
---|---|---|
committer | Philip Withnall <philip.withnall@collabora.co.uk> | 2013-12-16 08:49:47 +0000 |
commit | f5561d740c26656da7796fdfd3163ce7ce00da31 (patch) | |
tree | 2ff9d8dd48f528b31bb401565b5f1f235c1bed86 /libgnome-desktop | |
parent | b0414e293b30b8f9138fb82ece70b16e1188234a (diff) | |
download | gnome-desktop-f5561d740c26656da7796fdfd3163ce7ce00da31.tar.gz |
thumbnailer: Add documentation on thumbnailers and .thumbnailer files
https://bugzilla.gnome.org/show_bug.cgi?id=711604
Diffstat (limited to 'libgnome-desktop')
-rw-r--r-- | libgnome-desktop/gnome-desktop-thumbnail.c | 102 |
1 files changed, 102 insertions, 0 deletions
diff --git a/libgnome-desktop/gnome-desktop-thumbnail.c b/libgnome-desktop/gnome-desktop-thumbnail.c index f3cc60e7..c9baeaca 100644 --- a/libgnome-desktop/gnome-desktop-thumbnail.c +++ b/libgnome-desktop/gnome-desktop-thumbnail.c @@ -24,6 +24,108 @@ * Author: Alexander Larsson <alexl@redhat.com> */ +/** + * SECTION:gnome-desktop-thumbnail + * @short_description: Generates and looks up thumbnails of files and + * directories + * @stability: Unstable + * @include: libgnome-desktop/gnome-desktop-thumbnail.h + * + * #GnomeDesktopThumbnailFactory allows generation and loading of thumbnails for + * local and remote files and directories. It uses a collection of programs + * called <firstterm>thumbnailers</firstterm>, each one generating thumbnails + * for a specific set of content-types of files. For example, + * <application>totem-video-thumbnailer</application> generates thumbnails for + * video files using GStreamer; <application>evince-thumbnailer</application> + * generates thumbnails for PDFs and other document files. If no specific + * thumbnailer exists for a file, or if the thumbnailer fails, gdk-pixbuf is + * used as a fallback. + * + * To generate a thumbnail, an appropriate thumbnailer program is selected then + * executed, passing it the URI of the file to thumbnail, plus a path to write + * the thumbnail image to. If thumbnailing succeeds, the thumbnailer should have + * written the image to disk before terminating; but if thumbnailing fails, no + * image should be written, and the thumbnailer should return a non-zero exit + * status. #GnomeDesktopThumbnailFactory will then fall back to using gdk-pixbuf + * to generate a thumbnail, if possible. + * + * Thumbnailers are chosen by examining a series of + * <filename>.thumbnailer</filename> files in + * <filename><replaceable>$PREFIX</replaceable>/share/thumbnailers</filename>. + * Each is in a simple key-file format: + * <informalexample><programlisting> + * [Thumbnailer Entry] + * TryExec=evince-thumbnailer + * Exec=evince-thumbnailer -s %s %u %o + * MimeType=application/pdf;application/x-bzpdf;application/x-gzpdf; + * </programlisting></informalexample> + * + * The <filename>.thumbnailer</filename> format supports three keys: + * <variablelist> + * <varlistentry><term><code>TryExec</code></term><listitem><para> + * Optional. The name of the the thumbnailer program in the current + * <envar>$PATH</envar>. This allows the calling code to quickly check whether + * the thumbnailer exists before trying to execute it. + * </para></listitem></varlistentry> + * <varlistentry><term><code>Exec</code></term><listitem><para> + * Required. The command to execute the thumbnailer. It supports a few different + * parameters which are replaced before calling the thumbnailer: + * <replaceable>%u</replaceable> is the URI of the file being thumbnailed; + * <replaceable>%i</replaceable> is its path; <replaceable>%o</replaceable> + * is the path of the image file to be written to; + * <replaceable>%s</replaceable> is the maximum desired size of the thumbnail + * image (the maximum width or height, in pixels); and + * <replaceable>%%</replaceable> is a literal percent character. + * </para></listitem></varlistentry> + * <varlistentry><term><code>MimeType</code></term><listitem><para> + * Required. A semicolon-separated list of MIME types which the thumbnailer + * supports generating thumbnails for. + * </para></listitem></varlistentry> + * </variablelist> + * + * So in the example <filename>.thumbnailer</filename> file above, the command + * passes the requested thumbnail size, then the input file’s URI, then the + * path for the output image file to + * <application>evince-thumbnailer</application>. + * + * The code to examine and call a thumbnailer is contained in + * #GnomeDesktopThumbnailFactory, which handles looking up the right thumbnailer + * script, building and executing the command for it, and loading the resulting + * thumbnail image into a #GdkPixbuf. + * + * Thumbnail caching is also supported by #GnomeDesktopThumbnailFactory. When + * calling a thumbnailer, the path passed for the output image file is in + * <filename><envar>$XDG_CACHE_HOME</envar>/thumbnails/ + * <replaceable>$SIZE</replaceable>/</filename>. The cached image file is given + * a (probably) unique filename, generated by hashing the original file’s URI, + * so the thumbnail can be looked up in future. #GnomeDesktopThumbnailFactory + * supports two sizes of thumbnails: %GNOME_DESKTOP_THUMBNAIL_SIZE_NORMAL and + * %GNOME_DESKTOP_THUMBNAIL_SIZE_LARGE. Normal thumbnails are up to 128×128 + * pixels, whereas large thumbnails are up to 256×256 pixels. Thumbnails which + * are larger than this are scaled down before being cached, and non-square + * thumbnails are scaled so their largest dimension is at most 128 or 256 + * pixels. + * + * #GnomeDesktopThumbnailFactory also handles failed thumbnails. If a + * thumbnailer can’t generate a thumbnail for a file (e.g. because the file is + * corrupt or because the right video codecs aren’t available), it returns a + * non-zero exit status. The thumbnail factory then writes an entry to + * <filename><envar>$XDG_CACHE_HOME</envar>/thumbnails/fail/ + * gnome-thumbnail-factory/</filename> which is named after the hash of the + * input file URI (just like a successful cached thumbnail). For future queries + * for thumbnails for that file, #GnomeDesktopThumbnailFactory can immediately + * return an error after looking up the fail entry. + * + * If a file changes content, #GnomeDesktopThumbnailFactory will generate a new + * thumbnail because each cached image has associated metadata (stored as PNG + * tEXt keys) storing the full URI of the thumbnailed file (to check for hash + * collisions) and its last modification time at the point of thumbnailing. If + * the stored modification time doesn’t match the file’s current one, a new + * thumbnail is generated. + * + * Since: 2.2 + */ + #include <config.h> #include <sys/types.h> #include <sys/stat.h> |