libgimp, plug-ins: properly document the return values of GimpThumbnailProcedure.

The various information (width, height, image type and number of layers) are
those of the full image, not of the thumbnail. Make it clear in the docs of
GimpRunThumbnailFunc.

Additionally:

- file-xmc was returning the proper information but variables were wrongly
  named, which was confusing.
- Fix file-ico thumbnail proc which was returning the thumbnail width/height.
- In file-darktable, initialize width/height to 0 so that we just don't show any
  size when we don't get the information. It's better not to show anything than
  completely wrong information (the thumbnail target size).

libgimp/gimpthumbnailprocedure.h

@@ -40,6 +40,18 @@ G_BEGIN_DECLS
  * The thumbnail function is run during the lifetime of the GIMP session,
  * each time a plug-in thumbnail procedure is called.
  *
+ * [class@ThumbnailProcedure] are always run non-interactively.
+ *
+ * On success, the returned array must contain:
+ * 1. a [class@Image]: this is the only mandatory return value. It should
+ *    ideally be a simple image whose dimensions are closest to @size and meant
+ *    to be displayed as a small static image.
+ * 2. (optional) the full image's width (not the thumbnail's image's), or 0 if
+ *    unknown.
+ * 3. (optional) the full image's height, or 0 if unknown.
+ * 4. (optional) the [enum@ImageType] of the full image.
+ * 5. (optional) the number of layers in the full image.
+ *
  * Returns: (transfer full): the @procedure's return values.
  *
  * Since: 3.0

plug-ins/common/file-xmc.c

@@ -851,9 +851,9 @@ load_image (GFile   *file,
 static GimpImage *
 load_thumbnail (GFile   *file,
                 gint32   thumb_size,
-                gint32  *thumb_width,
+                gint32  *img_width,
-                gint32  *thumb_height,
+                gint32  *img_height,
-                gint32  *thumb_num_layers,
+                gint32  *num_layers,
                 GError **error)
 {
   /* Return only one frame for thumbnail.
@@ -879,13 +879,13 @@ load_thumbnail (GFile   *file,
   gint           height;
   gint           i;
 
-  g_return_val_if_fail (thumb_width, NULL);
+  g_return_val_if_fail (img_width, NULL);
-  g_return_val_if_fail (thumb_height, NULL);
+  g_return_val_if_fail (img_height, NULL);
-  g_return_val_if_fail (thumb_num_layers, NULL);
+  g_return_val_if_fail (num_layers, NULL);
 
-  *thumb_width      = 0;
+  *img_width  = 0;
-  *thumb_height     = 0;
+  *img_height = 0;
-  *thumb_num_layers = 0;
+  *num_layers = 0;
 
   fp = g_fopen (g_file_peek_path (file), "rb");
 
@@ -937,15 +937,15 @@ load_thumbnail (GFile   *file,
           /* this content is image */
 
           size = READ32 (fp, error)
-          positions[*thumb_num_layers] = READ32 (fp, error)
+          positions[*num_layers] = READ32 (fp, error)
           /* is this image is more preferred than selected before? */
           diff = MAX (thumb_size, size) - MIN (thumb_size, size);
           if (diff < min_diff)
             {/* the image size is closer than current selected image */
               min_diff = diff;
-              sel_num = *thumb_num_layers;
+              sel_num = *num_layers;
             }
-          ++*thumb_num_layers;
+          ++*num_layers;
         }
     }
 
@@ -961,8 +961,8 @@ load_thumbnail (GFile   *file,
   /* get width and height of entire image */
 
   /* Let's make XcursorImages */
-  xcIs = XcursorImagesCreate (*thumb_num_layers);
+  xcIs = XcursorImagesCreate (*num_layers);
-  xcIs->nimage = *thumb_num_layers;
+  xcIs->nimage = *num_layers;
   for (i = 0; i < xcIs->nimage; ++i)
     {
       /* make XcursorImage with no pixel buffer */
@@ -984,13 +984,13 @@ load_thumbnail (GFile   *file,
           thumb_size - min_diff, thumb_size + min_diff);
 
   /* get entire image dimensions */
-  find_hotspots_and_dimensions (xcIs, NULL, NULL, thumb_width, thumb_height);
+  find_hotspots_and_dimensions (xcIs, NULL, NULL, img_width, img_height);
 
   DM_XMC ("width=%i\theight=%i\tnum-layers=%i\n",
-          *thumb_width, *thumb_height, xcIs->nimage);
+          *img_width, *img_height, xcIs->nimage);
 
   /* dimension check */
-  if (*thumb_width > MAX_LOAD_DIMENSION)
+  if (*img_width > MAX_LOAD_DIMENSION)
     {
       g_set_error (error, 0, 0,
                    _("'%s' is too wide for an X cursor."),
@@ -999,7 +999,7 @@ load_thumbnail (GFile   *file,
       return NULL;
     }
 
-  if (*thumb_height > MAX_LOAD_DIMENSION)
+  if (*img_height > MAX_LOAD_DIMENSION)
     {
       g_set_error (error, 0, 0,
                    _("'%s' is too high for an X cursor."),

plug-ins/file-ico/ico-load.c

@@ -1001,6 +1001,8 @@ ico_load_thumbnail_image (GFile   *file,
   IcoLoadInfo   *info;
   IcoFileHeader  header;
   GimpImage     *image;
+  gint           max_width;
+  gint           max_height;
   gint           w     = 0;
   gint           h     = 0;
   gint           bpp   = 0;
@@ -1042,9 +1044,17 @@ ico_load_thumbnail_image (GFile   *file,
       return NULL;
     }
 
+  max_width  = 0;
+  max_height = 0;
+
   /* Do a quick scan of the icons in the file to find the best match */
   for (i = 0; i < icon_count; i++)
     {
+      if (info[i].width > max_width)
+        max_width = info[i].width;
+      if (info[i].height > max_height)
+        max_height = info[i].height;
+
       if ((info[i].width  > w && w < *width) ||
           (info[i].height > h && h < *height))
         {
@@ -1073,8 +1083,8 @@ ico_load_thumbnail_image (GFile   *file,
                   "Thumbnail", info + match);
   g_free (buf);
 
-  *width  = w;
+  *width  = max_width;
-  *height = h;
+  *height = max_height;
 
   D(("*** thumbnail successfully loaded.\n\n"));
 

plug-ins/file-raw/file-darktable.c

@@ -517,7 +517,7 @@ load_thumbnail_image (GFile   *file,
   gimp_progress_init_printf (_("Opening thumbnail for '%s'"),
                              gimp_file_get_utf8_name (file));
 
-  *width = *height = thumb_size;
+  *width = *height = 0;
 
   if (g_spawn_sync (NULL,
                     argv,