Document the "orientation" option.

2007-07-02  Matthias Clasen <mclasen@redhat.com>

        * gdk-pixbuf.c (gdk_pixbuf_get_option): Document the
        "orientation" option.

        * gdk-pixbuf.symbols:
        * gdk-pixbuf-core.h:
        * gdk-pixbuf-util.c (gdk_pixbuf_apply_embedded_orientation):
        New function to handle Exif orientation information in
        tiff and jpeg images.  (#439567, Michael Chudobiak)


svn path=/trunk/; revision=18340

docs/reference/gdk-pixbuf/gdk-pixbuf-sections.txt

@@ -108,6 +108,7 @@ gdk_pixdata_to_csource
 gdk_pixbuf_add_alpha
 gdk_pixbuf_copy_area
 gdk_pixbuf_saturate_and_pixelate
+gdk_pixbuf_apply_embedded_orientation
 gdk_pixbuf_fill
 </SECTION>
 

gdk-pixbuf/ChangeLog

@@ -1,3 +1,14 @@
+2007-07-02  Matthias Clasen <mclasen@redhat.com>
+
+	* gdk-pixbuf.c (gdk_pixbuf_get_option): Document the
+	"orientation" option.
+
+	* gdk-pixbuf.symbols:
+	* gdk-pixbuf-core.h:
+	* gdk-pixbuf-util.c (gdk_pixbuf_apply_embedded_orientation):
+	New function to handle Exif orientation information in 
+	tiff and jpeg images.  (#439567, Michael Chudobiak)
+
 2007-06-19  Matthias Clasen <mclasen@redhat.com>
 
 	* === Released 2.11.4 ===

gdk-pixbuf/gdk-pixbuf-core.h

@@ -231,6 +231,8 @@ void gdk_pixbuf_saturate_and_pixelate (const GdkPixbuf *src,
                                        gfloat           saturation,
                                        gboolean         pixelate);
 
+/* Transform an image to agree with its embedded orientation option / tag */
+GdkPixbuf *gdk_pixbuf_apply_embedded_orientation (GdkPixbuf *src);
 
 G_CONST_RETURN gchar * gdk_pixbuf_get_option (GdkPixbuf   *pixbuf,
                                               const gchar *key);

gdk-pixbuf/gdk-pixbuf-util.c

@@ -245,6 +245,88 @@ gdk_pixbuf_saturate_and_pixelate(const GdkPixbuf *src,
         }
 }
 
+
+/**
+ * gdk_pixbuf_apply_embedded_orientation:
+ * @src: A #GdkPixbuf.
+ *
+ * Takes an existing pixbuf and checks for the presence of an
+ * associated "orientation" option, which may be provided by the 
+ * jpeg loader (which reads the exif orientation tag) or the 
+ * tiff loader (which reads the tiff orientation tag, and
+ * compensates it for the partial transforms performed by 
+ * libtiff). If an orientation option/tag is present, the
+ * appropriate transform will be performed so that the pixbuf
+ * is oriented correctly.
+ *
+ * Return value: A newly-created pixbuf, or a reference to the
+ * input pixbuf (with an increased reference count).
+ *
+ * Since 2.12
+ **/
+GdkPixbuf *
+gdk_pixbuf_apply_embedded_orientation (GdkPixbuf *src)
+{
+  	const gchar *orientation_string;
+	int          transform = 0;
+	GdkPixbuf   *temp;
+	GdkPixbuf   *dest;
+
+	g_return_val_if_fail (src != NULL, NULL);
+
+	/* Read the orientation option associated with the pixbuf */
+	orientation_string = gdk_pixbuf_get_option (src, "orientation");	
+
+	if (orientation_string) {
+		/* If an orientation option was found, convert the 
+		   orientation string into an integer. */
+		transform = (int) g_ascii_strtoll (orientation_string, NULL, 10);
+	}
+
+	/* Apply the actual transforms, which involve rotations and flips. 
+	   The meaning of orientation values 1-8 and the required transforms
+	   are defined by the TIFF and EXIF (for JPEGs) standards. */
+        switch (transform) {
+        case 1:
+                dest = src;
+                g_object_ref (dest);
+                break;
+        case 2:
+                dest = gdk_pixbuf_flip (src, TRUE);
+                break;
+        case 3:
+                dest = gdk_pixbuf_rotate_simple (src, GDK_PIXBUF_ROTATE_UPSIDEDOWN);
+                break;
+        case 4:
+                dest = gdk_pixbuf_flip (src, FALSE);
+                break;
+        case 5:
+                temp = gdk_pixbuf_rotate_simple (src, GDK_PIXBUF_ROTATE_CLOCKWISE);
+                dest = gdk_pixbuf_flip (temp, TRUE);
+                g_object_unref (temp);
+                break;
+        case 6:
+                dest = gdk_pixbuf_rotate_simple (src, GDK_PIXBUF_ROTATE_CLOCKWISE);
+                break;
+        case 7:
+                temp = gdk_pixbuf_rotate_simple (src, GDK_PIXBUF_ROTATE_CLOCKWISE);
+                dest = gdk_pixbuf_flip (temp, FALSE);
+                g_object_unref (temp);
+                break;
+        case 8:
+                dest = gdk_pixbuf_rotate_simple (src, GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE);
+                break;
+        default:
+		/* if no orientation tag was present */
+                dest = src;
+                g_object_ref (dest);
+                break;
+        }
+
+        return dest;
+}
+
+
 #define __GDK_PIXBUF_UTIL_C__
 #include "gdk-pixbuf-aliasdef.c"
 

gdk-pixbuf/gdk-pixbuf.c

@@ -593,7 +593,15 @@ gdk_pixbuf_fill (GdkPixbuf *pixbuf,
  * @key: a nul-terminated string.
  * 
  * Looks up @key in the list of options that may have been attached to the
- * @pixbuf when it was loaded. 
+ * @pixbuf when it was loaded, or that may have been attached by another
+ * function using gdk_pixbuf_set_option().
+ *
+ * For instance, the ANI loader provides "Title" and "Artist" options. 
+ * The ICO, XBM, and XPM loaders provide "x_hot" and "y_hot" hot-spot 
+ * options for cursor definitions. The PNG loader provides the tEXt ancillary
+ * chunk key/value pairs as options. Since 2.12, the TIFF and JPEG loaders
+ * return an "orientation" option string that corresponds to the embedded 
+ * TIFF/Exif orientation tag (if present).
  * 
  * Return value: the value associated with @key. This is a nul-terminated 
  * string that should not be freed or %NULL if @key was not found.

gdk-pixbuf/gdk-pixbuf.symbols

@@ -82,6 +82,7 @@ gdk_pixbuf_new_from_inline
 gdk_pixbuf_add_alpha
 gdk_pixbuf_copy_area
 gdk_pixbuf_saturate_and_pixelate
+gdk_pixbuf_apply_embedded_orientation
 #endif
 #endif