From f610d61fcc38b36a8a29879e5c053015164242f8 Mon Sep 17 00:00:00 2001 From: DRC Date: Fri, 26 Apr 2013 10:33:29 +0000 Subject: 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+ssh://svn.code.sf.net/p/libjpeg-turbo/code/trunk@962 632fc199-4ca6-4c93-a231-07263d6284db --- turbojpeg.h | 86 +++++++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 61 insertions(+), 25 deletions(-) (limited to 'turbojpeg.h') diff --git a/turbojpeg.h b/turbojpeg.h index 3fc6c39d..c7a29a03 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, pad + * 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, subsamp 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 + * width 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, pad + * 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 + * height 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); + /** * @} -- cgit v1.2.3