Extend the TurboJPEG C API to support generating YUV images with arbitrary padding and to support image scaling when decompressing to YUV

git-svn-id: svn://svn.code.sf.net/p/libjpeg-turbo/code/trunk@962 632fc199-4ca6-4c93-a231-07263d6284db

1 files changed, 61 insertions, 25 deletions

diff --git a/turbojpeg.h b/turbojpeg.h
index 3fc6c39..c7a29a0 100644
--- a/turbojpeg.h
+++ b/turbojpeg.h
@@ -587,6 +587,8 @@ DLLEXPORT unsigned long DLLCALL tjBufSize(int width, int height,
  * the given parameters.
  *
  * @param width width of the image (in pixels)
+ * @param pad the width of each line in each plane of the image is padded to
+ *        the nearest multiple of this number of bytes (must be a power of 2.)
  * @param height height of the image (in pixels)
  * @param subsamp level of chrominance subsampling in the image (see
  *        @ref TJSAMP "Chrominance subsampling options".)
@@ -594,22 +596,22 @@ DLLEXPORT unsigned long DLLCALL tjBufSize(int width, int height,
  * @return the size of the buffer (in bytes) required to hold the image, or
  * -1 if the arguments are out of bounds.
  */
-DLLEXPORT unsigned long DLLCALL tjBufSizeYUV(int width, int height,
+DLLEXPORT unsigned long DLLCALL tjBufSizeYUV2(int width, int pad, int height,
   int subsamp);
 
 
 /**
  * Encode an RGB or grayscale image into a YUV planar image.  This function
  * uses the accelerated color conversion routines in TurboJPEG's underlying
- * codec to produce a planar YUV image that is suitable for X Video.
- * Specifically, if the chrominance components are subsampled along the
- * horizontal dimension, then the width of the luminance plane is padded to 2
- * in the output image (same goes for the height of the luminance plane, if the
- * chrominance components are subsampled along the vertical dimension.)  Also,
- * each line of each plane in the output image is padded to 4 bytes.  Although
- * this will work with any subsampling option, it is really only useful in
- * combination with TJ_420, which produces an image compatible with the I420
- * (AKA "YUV420P") format.
+ * codec but does not execute any of the other steps in the JPEG compression
+ * process.  The Y, U, and V image planes are stored sequentially into the
+ * destination buffer, and the size of each plane is determined by the width
+ * and height of the source image, as well as the specified padding and level
+ * of chrominance subsampling.  If the chrominance components are subsampled
+ * along the horizontal dimension, then the width of the luminance plane is
+ * padded to the nearest multiple of 2 in the output image (same goes for the
+ * height of the luminance plane, if the chrominance components are subsampled
+ * along the vertical dimension.)
  *
  * @param handle a handle to a TurboJPEG compressor or transformer instance
  * @param srcBuf pointer to an image buffer containing RGB or grayscale pixels
@@ -626,20 +628,26 @@ DLLEXPORT unsigned long DLLCALL tjBufSizeYUV(int width, int height,
  * @param pixelFormat pixel format of the source image (see @ref TJPF
  *        "Pixel formats".)
  * @param dstBuf pointer to an image buffer that will receive the YUV image.
- *        Use #tjBufSizeYUV() to determine the appropriate size for this buffer
- *        based on the image width, height, and level of chrominance
- *        subsampling.
+ *        Use #tjBufSizeYUV2() to determine the appropriate size for this
+ *        buffer based on the image width, height, padding, and level of
+ *        chrominance subsampling.
+ * @param pad the width of each line in each plane of the YUV image will be
+ *        padded to the nearest multiple of this number of bytes (must be a
+ *        power of 2.)  To generate images suitable for X Video, <tt>pad</tt>
+ *        should be set to 4.
  * @param subsamp the level of chrominance subsampling to be used when
  *        generating the YUV image (see @ref TJSAMP
- *        "Chrominance subsampling options".)
+ *        "Chrominance subsampling options".)  To generate images suitable for
+ *        X Video, <tt>subsamp</tt> should be set to @ref TJSAMP_420.  This
+ *        produces an image compatible with the I420 (AKA "YUV420P") format.
  * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP
  *        "flags".
  *
  * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr().)
 */
-DLLEXPORT int DLLCALL tjEncodeYUV2(tjhandle handle,
+DLLEXPORT int DLLCALL tjEncodeYUV3(tjhandle handle,
   unsigned char *srcBuf, int width, int pitch, int height, int pixelFormat,
-  unsigned char *dstBuf, int subsamp, int flags);
+  unsigned char *dstBuf, int pad, int subsamp, int flags);
 
 
 /**
@@ -736,26 +744,43 @@ DLLEXPORT int DLLCALL tjDecompress2(tjhandle handle,
 /**
  * Decompress a JPEG image to a YUV planar image.  This function performs JPEG
  * decompression but leaves out the color conversion step, so a planar YUV
- * image is generated instead of an RGB image.  The padding of the planes in
- * this image is the same as in the images generated by #tjEncodeYUV2().  Note
- * that, if the width or height of the image is not an even multiple of the MCU
- * block size (see #tjMCUWidth and #tjMCUHeight), then an intermediate buffer
- * copy will be performed within TurboJPEG.
+ * image is generated instead of an RGB image.  The structure of the planes in
+ * this image is the same as in the images generated by #tjEncodeYUV3().  Note
+ * that, if the width or height of the JPEG image is not an even multiple of
+ * the MCU block size (see #tjMCUWidth and #tjMCUHeight), then an intermediate
+ * buffer copy will be performed within TurboJPEG.
  *
  * @param handle a handle to a TurboJPEG decompressor or transformer instance
  * @param jpegBuf pointer to a buffer containing the JPEG image to decompress
  * @param jpegSize size of the JPEG image (in bytes)
  * @param dstBuf pointer to an image buffer that will receive the YUV image.
- *        Use #tjBufSizeYUV() to determine the appropriate size for this buffer
- *        based on the image width, height, and level of subsampling.
+ *        Use #tjBufSizeYUV2() to determine the appropriate size for this
+ *        buffer based on the image width, height, padding, and level of
+ *        subsampling.
+ * @param width desired width (in pixels) of the YUV image.  If this is
+ *        different than the width of the JPEG image being decompressed, then
+ *        TurboJPEG will use scaling in the JPEG decompressor to generate the
+ *        largest possible image that will fit within the desired width.  If
+ *        <tt>width</tt> is set to 0, then only the height will be considered
+ *        when determining the scaled image size.
+ * @param pad the width of each line in each plane of the YUV image will be
+ *        padded to the nearest multiple of this number of bytes (must be a
+ *        power of 2.)  To generate images suitable for X Video, <tt>pad</tt>
+ *        should be set to 4.
+ * @param height desired height (in pixels) of the YUV image.  If this is
+ *        different than the height of the JPEG image being decompressed, then
+ *        TurboJPEG will use scaling in the JPEG decompressor to generate the
+ *        largest possible image that will fit within the desired height.  If
+ *        <tt>height</tt> is set to 0, then only the width will be considered
+ *        when determining the scaled image size.
  * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP
  *        "flags".
  *
  * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr().)
  */
-DLLEXPORT int DLLCALL tjDecompressToYUV(tjhandle handle,
+DLLEXPORT int DLLCALL tjDecompressToYUV2(tjhandle handle,
   unsigned char *jpegBuf, unsigned long jpegSize, unsigned char *dstBuf,
-  int flags);
+  int width, int pad, int height, int flags);
 
 
 /**
@@ -892,6 +917,9 @@ DLLEXPORT unsigned long DLLCALL TJBUFSIZE(int width, int height);
 DLLEXPORT unsigned long DLLCALL TJBUFSIZEYUV(int width, int height,
   int jpegSubsamp);
 
+DLLEXPORT unsigned long DLLCALL tjBufSizeYUV(int width, int height,
+  int subsamp);
+
 DLLEXPORT int DLLCALL tjCompress(tjhandle handle, unsigned char *srcBuf,
   int width, int pitch, int height, int pixelSize, unsigned char *dstBuf,
   unsigned long *compressedSize, int jpegSubsamp, int jpegQual, int flags);
@@ -900,6 +928,10 @@ DLLEXPORT int DLLCALL tjEncodeYUV(tjhandle handle,
   unsigned char *srcBuf, int width, int pitch, int height, int pixelSize,
   unsigned char *dstBuf, int subsamp, int flags);
 
+DLLEXPORT int DLLCALL tjEncodeYUV2(tjhandle handle,
+  unsigned char *srcBuf, int width, int pitch, int height, int pixelFormat,
+  unsigned char *dstBuf, int subsamp, int flags);
+
 DLLEXPORT int DLLCALL tjDecompressHeader(tjhandle handle,
   unsigned char *jpegBuf, unsigned long jpegSize, int *width, int *height);
 
@@ -907,6 +939,10 @@ DLLEXPORT int DLLCALL tjDecompress(tjhandle handle,
   unsigned char *jpegBuf, unsigned long jpegSize, unsigned char *dstBuf,
   int width, int pitch, int height, int pixelSize, int flags);
 
+DLLEXPORT int DLLCALL tjDecompressToYUV(tjhandle handle,
+  unsigned char *jpegBuf, unsigned long jpegSize, unsigned char *dstBuf,
+  int flags);
+
 
 /**
  * @}