update docs for rad2float etc.

ChangeLog

@@ -13,6 +13,7 @@
 - added IM_CODING_RAD, support where it makes sense (extract, flip, rotate,
   etc.)
 - IM_PROGRESS env var
+- docs for rad2float and IM_CODING_RAD
 
 3/3/09 started 7.17.2
 - im_magick2vips.c: allow funky bit depths, like 14 (thanks Mikkel)

TODO

@@ -1,4 +1,8 @@
-- rad2floatt/float2rad/radiance read/write all need docs
+- radiance read/write needs docs
+
+  maybe have an im_format(3) page with all the built-in formats?
+
+  hard until we document vips_object :(
 
 - same for matio?
 

doc/src/fileformat.tex

@@ -94,6 +94,7 @@ Bytes  & Represent 					 & VIPS name \\
 \hline
 \ct{IM\_CODING\_NONE}  & \ct{NOCODING} & 0 & VIPS computation format \\
 \ct{IM\_CODING\_LABQ}  & \ct{LABQ} & 2 & LABQ storage format \\
+\ct{IM\_CODING\_RAD}  & \ct{RAD} & 6 & Radiance storage format \\
 \hline
 \end{tabular}
 \end{center}
@@ -146,7 +147,7 @@ automatically byte-swap for you if necessary, but this can be slow.
 \subsection{Storage formats}
 
 All storage formats have other values for the \ct{Coding} field. This
-release supports only \ct{IM\_CODING\_LABQ} format. 
+release supports \ct{IM\_CODING\_LABQ} and \ct{IM\_CODING\_RAD}.
 
 \ct{IM\_CODING\_LABQ} stores $L^{*}$, $a^{*}$ and $b^{*}$ for each pixel,
 with 10 bits for $L^{*}$ and 11 bits for each of $a^{*}$ and $b^{*}$. These
@@ -155,6 +156,18 @@ value in the first 3 bytes, and the left-over bits packed into the final
 byte as 2:3:3.
 
 This format is a little awkward to process. Some VIPS functions can work
-directly on \ct{IM\_CODING\_LABQ} images (\ct{im\_extract()}, for example),
+directly on \ct{IM\_CODING\_LABQ} images (\ct{im\_extract\_area()}, for
-but most will require you to unpack the image to one of the computation
+example), but most will require you to unpack the image to one of the
-formats (for example with \ct{im\_LabQ2Lab()}) first.
+computation formats (for example with \ct{im\_LabQ2Lab()}) first.
+
+\ct{IM\_CODING\_RAD} stores $RGB$ or $XYZ$ float images as 8 bytes of mantissa
+and then 8 bytes of exponent, shared between the three channels. This coding
+style is used by the Radiance family of programs (and the HDR format) commonly
+used for HDR imaging. This style of image is generated when you load an HDR
+image.
+
+This format is a little awkward to process. Some VIPS functions can work
+directly on \ct{IM\_CODING\_RAD} images (\ct{im\_extract\_area()}, for
+example), but most will require you to unpack the image to one of the
+computation formats with \ct{im\_rad2float()} first.
+

man/im_float2rad.3

@@ -0,0 +1 @@
+.so man3/im_rad2float.3 

man/im_rad2float.3

@@ -0,0 +1,38 @@
+.TH IM_RAD2FLOAT 3 "25 March 2009"
+.SH NAME
+im_rad2float, im_float2rad \- convert RAD coded images to float and back
+.SH SYNOPSIS
+#include <vips/vips.h>
+
+int im_rad2float( IMAGE *in, IMAGE *out )
+
+int im_float2rad( IMAGE *in, IMAGE *out )
+
+.SH DESCRIPTION
+These functions convert 
+.B IM_CODING_RAD 
+images to 3-band float and back.
+
+.B im_rad2float(3)
+unpacks a 4-band uchar image in
+.B IM_CODING_RAD
+format to 3-band float. RAD images are used by the 
+.B radiance(1)
+family of programs for HDR imaging. 
+
+Some VIPS operations will work directly on the packed RAD images (such as 
+.B im_extract_area(3)
+) but many will require the image to be unpacked to 3-band float for
+processing.
+
+.B im_float2rad(3)
+packs a 3-band float image back to 4-band uchar in
+.B IM_CODING_RAD
+format.
+
+.SH RETURN VALUE
+The functions return 0 on success and -1 on error.
+.SH SEE ALSO
+im_LabQ2Lab(3), im_format(3).
+.SH AUTHOR
+J. Cupitt \- 23 March 2009