fix up orientation docs

document the new orientation system

various tiff/jpeg doc fixups too

libvips/conversion/autorot.c

@@ -203,12 +203,16 @@ vips_autorot_init( VipsAutorot *autorot )
  *
  * * @angle: output #VipsAngle the image was rotated by
  *
- * Look at the exif tags and rotate the image to make it upright. The
- * orientation tag is removed from @out to prevent accidental double rotation. 
+ * Look at the image metadata and rotate the image to make it upright. The
+ * #VIPS_META_ORIENTATION tag is removed from @out to prevent accidental 
+ * double rotation. 
  *
  * Read @angle to find the amount the image was rotated by. 
  *
- * See also: vips_rot().
+ * vips only supports the four simple rotations, it does not support the
+ * various mirror modes. 
+ *
+ * See also: vips_autorot_get_angle(), vips_autorot_remove_angle(), vips_rot().
  *
  * Returns: 0 on success, -1 on error
  */

libvips/foreign/jpegload.c

@@ -369,13 +369,16 @@ vips_foreign_load_jpeg_buffer_init( VipsForeignLoadJpegBuffer *buffer )
  * This can be useful for detecting truncated files, for example. Normally 
  * reading these produces a warning, but no fatal error.  
  *
- * Setting @autorotate to %TRUE will make the loader interpret the EXIF
- * Orientation field and automatically rotate the image appropriately during
- * load. After rotation, the Orientation tag will be removed to prevent
- * accidental double-rotation.  
+ * Setting @autorotate to %TRUE will make the loader interpret the 
+ * orientation tag and automatically rotate the image appropriately during
+ * load. 
  *
- * Using @autorotate can be much slower than doing the rotate later
- * in processing. See vips_autorot().
+ * If @autorotate is %FALSE, the metadata field #VIPS_META_ORIENTATION is set 
+ * to the value of the orientation tag. Applications may read and interpret 
+ * this field
+ * as they wish later in processing. See vips_autorot(). Save
+ * operations will use #VIPS_META_ORIENTATION, if present, to set the
+ * orientation of output images. 
  *
  * Example:
  *
@@ -388,12 +391,11 @@ vips_foreign_load_jpeg_buffer_init( VipsForeignLoadJpegBuffer *buffer )
  *
  * Any embedded ICC profiles are ignored: you always just get the RGB from 
  * the file. Instead, the embedded profile will be attached to the image as 
- * @VIPS_META_ICC_NAME ("icc-profile-data"). You need to use something like 
+ * #VIPS_META_ICC_NAME. You need to use something like 
  * vips_icc_import() to get CIE values from the file. 
  *
- * EXIF metadata is attached as @VIPS_META_EXIF_NAME ("exif-data"), IPCT as
- * @VIPS_META_IPCT_NAME ("ipct-data"), and XMP as VIPS_META_XMP_NAME
- * ("xmp-data").
+ * EXIF metadata is attached as #VIPS_META_EXIF_NAME, IPCT as
+ * #VIPS_META_IPCT_NAME, and XMP as #VIPS_META_XMP_NAME.
  *
  * The int metadata item "jpeg-multiscan" is set to the result of 
  * jpeg_has_multiple_scans(). Interlaced jpeg images need a large amount of
@@ -403,10 +405,7 @@ vips_foreign_load_jpeg_buffer_init( VipsForeignLoadJpegBuffer *buffer )
  * The EXIF thumbnail, if present, is attached to the image as 
  * "jpeg-thumbnail-data". See vips_image_get_blob().
  *
- * This function only reads the image header and does not decompress any pixel
- * data. Decompression only occurs when pixels are accessed.
- *
- * See also: vips_jpegload_buffer(), vips_image_new_from_file().
+ * See also: vips_jpegload_buffer(), vips_image_new_from_file(), vips_autorot().
  *
  * Returns: 0 on success, -1 on error.
  */
@@ -434,6 +433,8 @@ vips_jpegload( const char *filename, VipsImage **out, ... )
  *
  * * @shrink: %gint, shrink by this much on load
  * * @fail: %gboolean, fail on warnings
+ * * @autorotate: %gboolean, use exif Orientation tag to rotate the image 
+ *   during load
  *
  * Read a JPEG-formatted memory block into a VIPS image. Exactly as
  * vips_jpegload(), but read from a memory buffer. 

libvips/foreign/jpegsave.c

@@ -437,19 +437,9 @@ vips_foreign_save_jpeg_mime_init( VipsForeignSaveJpegMime *mime )
  * "don't attach a profile".
  *
  * If no profile is specified and the VIPS header 
- * contains an ICC profile named VIPS_META_ICC_NAME ("icc-profile-data"), the
+ * contains an ICC profile named #VIPS_META_ICC_NAME, the
  * profile from the VIPS header will be attached.
  *
- * The image is automatically converted to RGB, Monochrome or CMYK before 
- * saving. 
- *
- * EXIF data is constructed from @VIPS_META_EXIF_NAME ("exif-data"), then
- * modified with any other related tags on the image before being written to
- * the file. 
- *
- * IPCT as @VIPS_META_IPCT_NAME ("ipct-data") and XMP as VIPS_META_XMP_NAME
- * ("xmp-data") are coded and attached. 
- *
  * If @optimize_coding is set, the Huffman tables are optimised. This is
  * sllightly slower and produces slightly smaller files. 
  *
@@ -504,6 +494,17 @@ vips_foreign_save_jpeg_mime_init( VipsForeignSaveJpegMime *mime )
  * Tables 5-7 are based on older research papers, but generally achieve worse
  * compression ratios and/or quality than 2 or 4.
  *
+ * The image is automatically converted to RGB, Monochrome or CMYK before 
+ * saving. 
+ *
+ * EXIF data is constructed from #VIPS_META_EXIF_NAME, then
+ * modified with any other related tags on the image before being written to
+ * the file. #VIPS_META_RESOLUTION_UNIT is used to set the EXIF resolution
+ * unit. #VIPS_META_ORIENTATION is used to set the EXIF orientation tag. 
+ *
+ * IPCT as #VIPS_META_IPCT_NAME and XMP as #VIPS_META_XMP_NAME
+ * are coded and attached. 
+ *
  * See also: vips_jpegsave_buffer(), vips_image_write_to_file().
  *
  * Returns: 0 on success, -1 on error.

libvips/foreign/tiffload.c

@@ -302,7 +302,7 @@ vips_foreign_load_tiff_buffer_init( VipsForeignLoadTiffBuffer *buffer )
  * Optional arguments:
  *
  * * @page: int, load this page
- * * @autorotate: %gboolean, use Orientation tag to rotate the image 
+ * * @autorotate: %gboolean, use orientation tag to rotate the image 
  *   during load
  *
  * Read a TIFF file into a VIPS image. It is a full baseline TIFF 6 reader, 
@@ -313,17 +313,24 @@ vips_foreign_load_tiff_buffer_init( VipsForeignLoadTiffBuffer *buffer )
  * 0) is read.
  *
  * Setting @autorotate to %TRUE will make the loader interpret the 
- * Orientation field and automatically rotate the image appropriately during
- * load. After rotation, the Orientation tag will be removed to prevent
- * accidental double-rotation.  
+ * orientation tag and automatically rotate the image appropriately during
+ * load. 
  *
- * Using @autorotate can be much slower than doing the rotate later
- * in processing. See vips_autorot().
+ * If @autorotate is %FALSE, the metadata field #VIPS_META_ORIENTATION is set 
+ * to the value of the orientation tag. Applications may read and interpret 
+ * this field
+ * as they wish later in processing. See vips_autorot(). Save
+ * operations will use #VIPS_META_ORIENTATION, if present, to set the
+ * orientation of output images. 
  *
- * Any ICC profile is read and attached to the VIPS image. Any XMP metadata is
- * read and attached to the image. 
+ * Any ICC profile is read and attached to the VIPS image as
+ * #VIPS_META_ICC_NAME. Any XMP metadata is read and attached to the image
+ * as #VIPS_META_XMP_NAME. Any IPCT is attached as #VIPS_META_IPCT_NAME. The
+ * image description is
+ * attached as #VIPS_META_IMAGEDESCRIPTION. Data in the photoshop tag is 
+ * attached as #VIPS_META_PHOTOSHOP_NAME.
  *
- * See also: vips_image_new_from_file().
+ * See also: vips_image_new_from_file(), vips_autorot().
  *
  * Returns: 0 on success, -1 on error.
  */
@@ -350,6 +357,8 @@ vips_tiffload( const char *filename, VipsImage **out, ... )
  * Optional arguments:
  *
  * * @page: %gint, load this page
+ * * @autorotate: %gboolean, use orientation tag to rotate the image 
+ *   during load
  *
  * Read a TIFF-formatted memory block into a VIPS image. Exactly as
  * vips_tiffload(), but read from a memory source. 

libvips/foreign/tiffsave.c

@@ -319,14 +319,15 @@ vips_foreign_save_tiff_init( VipsForeignSaveTiff *tiff )
  * * @xres: %gdouble horizontal resolution in pixels/mm
  * * @yres: %gdouble vertical resolution in pixels/mm
  * * @bigtiff: set %TRUE to write a BigTiff file
+ * * @properties: set %TRUE to write an IMAGEDESCRIPTION tag
  *
  * Write a VIPS image to a file as TIFF.
  *
  * Use @compression to set the tiff compression. Currently jpeg, packbits,
  * fax4, lzw, none and deflate are supported. The default is no compression.
  * JPEG compression is a good lossy compressor for photographs, packbits is 
  * good for 1-bit images, and deflate is the best lossless compression TIFF 
- * can do. LZW has patent problems and is no longer recommended.
+ * can do. 
  *
  * Use @Q to set the JPEG compression factor. Default 75.
  *
@@ -346,7 +347,7 @@ vips_foreign_save_tiff_init( VipsForeignSaveTiff *tiff )
  * "don't attach a profile".
  *
  * If no profile is specified and the VIPS header 
- * contains an ICC profile named VIPS_META_ICC_NAME ("icc-profile-data"), the
+ * contains an ICC profile named #VIPS_META_ICC_NAME, the
  * profile from the VIPS header will be attached.
  *
  * Set @tile to TRUE to write a tiled tiff.  By default tiff are written in
@@ -365,8 +366,8 @@ vips_foreign_save_tiff_init( VipsForeignSaveTiff *tiff )
  *
  * Use @resunit to override the default resolution unit.  
  * The default 
- * resolution unit is taken from the header field "resolution-unit"
- * (#VIPS_META_RESOLUTION_UNIT in C). If this field is not set, then 
+ * resolution unit is taken from the header field 
+ * #VIPS_META_RESOLUTION_UNIT. If this field is not set, then 
  * VIPS defaults to cm.
  *
  * Use @xres and @yres to override the default horizontal and vertical
@@ -377,8 +378,16 @@ vips_foreign_save_tiff_init( VipsForeignSaveTiff *tiff )
  * Bigtiff is a variant of the TIFF
  * format that allows more than 4GB in a file.
  *
- * If @in has a field called VIPS_META_XMP_NAME ("xmp-data") it is written to
- * the tiff image. 
+ * Set @properties to write all vips metadata to the IMAGEDESCRIPTION tag as
+ * xml. If @properties is not set, the value of #VIPS_META_IMAGEDESCRIPTION is
+ * used instead.
+ *
+ * The value of #VIPS_META_XMP_NAME is written to
+ * the XMP tag. #VIPS_META_ORIENTATION (if set) is used to set the value of 
+ * the orientation
+ * tag. #VIPS_META_IPCT (if set) is used to set the value of the IPCT tag.  
+ * #VIPS_META_PHOTOSHOP_NAME (if set) is used to set the value of the PHOTOSHOP
+ * tag.
  *
  * See also: vips_tiffload(), vips_image_write_to_file().
  *

libvips/include/vips/header.h

@@ -113,6 +113,23 @@ extern "C" {
  *
  * The orientation tag for this image. An int from 1 - 8 using the standard 
  * exif/tiff meanings. 
+ *
+ * * 1 - The 0th row represents the visual top of the image, and the 0th column
+ *   represents the visual left-hand side.
+ * * 2 - The 0th row represents the visual top of the image, and the 0th column
+ *   represents the visual right-hand side.
+ * * 3 - The 0th row represents the visual bottom of the image, and the 0th
+ *   column represents the visual right-hand side.
+ * * 4 - The 0th row represents the visual bottom of the image, and the 0th
+ *   column represents the visual left-hand side.
+ * * 5 - The 0th row represents the visual left-hand side of the image, and the
+ *   0th column represents the visual top.
+ * * 6 - The 0th row represents the visual right-hand side of the image, and the
+ *   0th column represents the visual top.
+ * * 7 - The 0th row represents the visual right-hand side of the image, and the
+ *   0th column represents the visual bottom.
+ * * 8 - The 0th row represents the visual left-hand side of the image, and the
+ *   0th column represents the visual bottom. 
  */
 #define VIPS_META_ORIENTATION "orientation"