From: DRC Date: Fri, 26 Apr 2013 08:41:25 +0000 (+0000) Subject: Further doc tweaks X-Git-Tag: 1.3.0~10 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=01fdcc391a0a669525bc6670d56b7881ac048003;p=libjpeg-turbo Further doc tweaks git-svn-id: svn+ssh://svn.code.sf.net/p/libjpeg-turbo/code/branches/1.3.x@959 632fc199-4ca6-4c93-a231-07263d6284db --- diff --git a/doc/html/annotated.html b/doc/html/annotated.html index 03097a9..6ad64d9 100644 --- a/doc/html/annotated.html +++ b/doc/html/annotated.html @@ -81,7 +81,7 @@ var searchBox = new SearchBox("searchBox", "search",false,'Search'); -
Generated on Fri Apr 26 2013 00:23:46 for TurboJPEG by  +
Generated on Fri Apr 26 2013 03:39:31 for TurboJPEG by  doxygen 1.7.4
diff --git a/doc/html/classes.html b/doc/html/classes.html index 4068ded..12ff745 100644 --- a/doc/html/classes.html +++ b/doc/html/classes.html @@ -80,7 +80,7 @@ var searchBox = new SearchBox("searchBox", "search",false,'Search'); -
Generated on Fri Apr 26 2013 00:23:46 for TurboJPEG by  +
Generated on Fri Apr 26 2013 03:39:31 for TurboJPEG by  doxygen 1.7.4
diff --git a/doc/html/functions.html b/doc/html/functions.html index f7c0549..4857569 100644 --- a/doc/html/functions.html +++ b/doc/html/functions.html @@ -113,7 +113,7 @@ var searchBox = new SearchBox("searchBox", "search",false,'Search'); -
Generated on Fri Apr 26 2013 00:23:46 for TurboJPEG by  +
Generated on Fri Apr 26 2013 03:39:31 for TurboJPEG by  doxygen 1.7.4
diff --git a/doc/html/functions_vars.html b/doc/html/functions_vars.html index 782aea0..bdc9169 100644 --- a/doc/html/functions_vars.html +++ b/doc/html/functions_vars.html @@ -113,7 +113,7 @@ var searchBox = new SearchBox("searchBox", "search",false,'Search'); -
Generated on Fri Apr 26 2013 00:23:46 for TurboJPEG by  +
Generated on Fri Apr 26 2013 03:39:31 for TurboJPEG by  doxygen 1.7.4
diff --git a/doc/html/group___turbo_j_p_e_g.html b/doc/html/group___turbo_j_p_e_g.html index 86ac670..3335c08 100644 --- a/doc/html/group___turbo_j_p_e_g.html +++ b/doc/html/group___turbo_j_p_e_g.html @@ -90,7 +90,7 @@ Defines #define TJFLAG_FORCESSE3  Turn off CPU auto-detection and force TurboJPEG to use SSE3 code (if the underlying codec supports it.)
#define TJFLAG_FASTUPSAMPLE - When decompressing, use the fastest chrominance upsampling algorithm available in the underlying codec.
+ When decompressing an image that was compressed using chrominance subsampling, use the fastest chrominance upsampling algorithm available in the underlying codec.
#define TJFLAG_NOREALLOC  Disable buffer (re)allocation.
#define TJFLAG_FASTDCT @@ -98,7 +98,7 @@ Defines #define TJFLAG_ACCURATEDCT  Use the most accurate DCT/IDCT algorithm available in the underlying codec.
#define TJ_NUMXOP - Number of transform operations.
+ The number of transform operations.
#define TJXOPT_PERFECT  This option will cause tjTransform() to return an error if the transform is not perfect.
#define TJXOPT_TRIM @@ -255,7 +255,7 @@ Variables
-

Number of transform operations.

+

The number of transform operations.

@@ -317,7 +317,7 @@ Variables
-

When decompressing, use the fastest chrominance upsampling algorithm available in the underlying codec.

+

When decompressing an image that was compressed using chrominance subsampling, use the fastest chrominance upsampling algorithm available in the underlying codec.

The default is to use smooth upsampling, which creates a smooth transition between neighboring chrominance components in order to reduce upsampling artifacts in the decompressed image.

@@ -631,7 +631,7 @@ Variables

Chrominance subsampling options.

-

When an image is converted from the RGB to the YCbCr colorspace as part of the JPEG compression process, some of the Cb and Cr (chrominance) components can be discarded or averaged together to produce a smaller image with little perceptible loss of image clarity (the human eye is more sensitive to small changes in brightness than small changes in color.) This is called "chrominance subsampling".

+

When an image is converted from the RGB to the YUV colorspace as part of the JPEG compression process, some of the U and V (chrominance) components can be discarded or averaged together to produce a smaller image with little perceptible loss of image clarity (the human eye is more sensitive to small changes in brightness than small changes in color.) This is called "chrominance subsampling".

Enumerator:

The maximum size of the buffer (in bytes) required to hold a JPEG image with the given parameters.

-

The number of bytes returned by this function is larger than the size of the uncompressed source image. The reason for this is that the JPEG format uses 16-bit coefficients, and it is thus possible for a very high-quality JPEG image with very high frequency content to expand rather than compress when converted to the JPEG format. Such images represent a very rare corner case, but since there is no way to predict the size of a JPEG image prior to compression, the corner case has to be handled.

+

The number of bytes returned by this function is larger than the size of the uncompressed source image. The reason for this is that the JPEG format uses 16-bit coefficients, and it is thus possible for a very high-quality JPEG image with very high-frequency content to expand rather than compress when converted to the JPEG format. Such images represent a very rare corner case, but since there is no way to predict the size of a JPEG image prior to compression, the corner case has to be handled.

Parameters:
TJSAMP_444 

4:4:4 chrominance subsampling (no chrominance subsampling).

@@ -768,7 +768,7 @@ Variables
@@ -1003,10 +1003,10 @@ If you choose option 1, *jpegSize should be set to the size of your - - + + - +
widthwidth of the image (in pixels)
handlea handle to a TurboJPEG decompressor or transformer instance
jpegBufpointer to a buffer containing the JPEG image to decompress
jpegSizesize of the JPEG image (in bytes)
dstBufpointer to an image buffer that will receive the decompressed image. This buffer should normally be pitch * scaledHeight bytes in size, where scaledHeight can be determined by calling TJSCALED() with the JPEG image height and one of the scaling factors returned by tjGetScalingFactors(). The dstBuf pointer may also be used to decompress into a specific region of a larger buffer.
widthdesired width (in pixels) of the destination 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.
dstBufpointer to an image buffer that will receive the decompressed image. This buffer should normally be pitch * scaledHeight bytes in size, where scaledHeight can be determined by calling TJSCALED() with the JPEG image height and one of the scaling factors returned by tjGetScalingFactors(). The dstBuf pointer may also be used to decompress into a specific region of a larger buffer.
widthdesired width (in pixels) of the destination 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.
pitchbytes per line of the destination image. Normally, this is scaledWidth * tjPixelSize[pixelFormat] if the decompressed image is unpadded, else TJPAD(scaledWidth * tjPixelSize[pixelFormat]) if each line of the decompressed image is padded to the nearest 32-bit boundary, as is the case for Windows bitmaps. (NOTE: scaledWidth can be determined by calling TJSCALED() with the JPEG image width and one of the scaling factors returned by tjGetScalingFactors().) You can also be clever and use the pitch parameter to skip lines, etc. Setting this parameter to 0 is the equivalent of setting it to scaledWidth * tjPixelSize[pixelFormat].
heightdesired height (in pixels) of the destination 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.
heightdesired height (in pixels) of the destination 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.
pixelFormatpixel format of the destination image (see Pixel formats.)
flagsthe bitwise OR of one or more of the flags.
@@ -1125,13 +1125,13 @@ If you choose option 1, *jpegSize should be set to the size of your

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 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.

+

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.

Parameters:
- +
handlea handle to a TurboJPEG decompressor or transformer instance
jpegBufpointer to a buffer containing the JPEG image to decompress
jpegSizesize of the JPEG image (in bytes)
dstBufpointer 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.
dstBufpointer 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.
flagsthe bitwise OR of one or more of the flags.
@@ -1448,7 +1448,7 @@ If you choose option 1, *jpegSize should be set to the size of your

Losslessly transform a JPEG image into another JPEG image.

-

Lossless transforms work by moving the raw coefficients from one JPEG image structure to another without altering the values of the coefficients. While this is typically faster than decompressing the image, transforming it, and re-compressing it, lossless transforms are not free. Each lossless transform requires reading and Huffman decoding all of the coefficients in the source image, regardless of the size of the destination image. Thus, this function provides a means of generating multiple transformed images from the same source or of applying multiple transformations simultaneously, in order to eliminate the need to read the source coefficients multiple times.

+

Lossless transforms work by moving the raw coefficients from one JPEG image structure to another without altering the values of the coefficients. While this is typically faster than decompressing the image, transforming it, and re-compressing it, lossless transforms are not free. Each lossless transform requires reading and performing Huffman decoding on all of the coefficients in the source image, regardless of the size of the destination image. Thus, this function provides a means of generating multiple transformed images from the same source or applying multiple transformations simultaneously, in order to eliminate the need to read the source coefficients multiple times.

Parameters:
@@ -1458,11 +1458,11 @@ If you choose option 1, *jpegSize should be set to the size of your - +
handlea handle to a TurboJPEG transformer instance
dstBufspointer to an array of n image buffers. dstBufs[i] will receive a JPEG image that has been transformed using the parameters in transforms[i]. TurboJPEG has the ability to reallocate the JPEG buffer to accommodate the size of the JPEG image. Thus, you can choose to:
  1. pre-allocate the JPEG buffer with an arbitrary size using tjAlloc() and let TurboJPEG grow the buffer as needed,
  2. set dstBufs[i] to NULL to tell TurboJPEG to allocate the buffer for you, or
    3. -
  3. pre-allocate the buffer to a "worst case" size determined by calling tjBufSize() with the cropped width and height. This should ensure that the buffer never has to be re-allocated (setting TJFLAG_NOREALLOC guarantees this.)
    4. +
  4. pre-allocate the buffer to a "worst case" size determined by calling tjBufSize() with the transformed or cropped width and height. This should ensure that the buffer never has to be re-allocated (setting TJFLAG_NOREALLOC guarantees this.)
If you choose option 1, dstSizes[i] should be set to the size of your pre-allocated buffer. In any case, unless you have set TJFLAG_NOREALLOC, you should always check dstBufs[i] upon return from this function, as it may have changed.
dstSizespointer to an array of n unsigned long variables that will receive the actual sizes (in bytes) of each transformed JPEG image. If dstBufs[i] points to a pre-allocated buffer, then dstSizes[i] should be set to the size of the buffer. Upon return, dstSizes[i] will contain the size of the JPEG image (in bytes.)
transformspointer to an array of n tjtransform structures, each of which specifies the transform parameters and/or cropping region for the corresponding transformed output image.
transformspointer to an array of n tjtransform structures, each of which specifies the transform parameters and/or cropping region for the corresponding transformed output image.
flagsthe bitwise OR of one or more of the flags.
@@ -1594,7 +1594,7 @@ If you choose option 1, dstSizes[i] should be set to the size of yo
-
Generated on Fri Apr 26 2013 00:23:46 for TurboJPEG by  +
Generated on Fri Apr 26 2013 03:39:31 for TurboJPEG by  doxygen 1.7.4
diff --git a/doc/html/index.html b/doc/html/index.html index c19231f..7c43e58 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -69,7 +69,7 @@ var searchBox = new SearchBox("searchBox", "search",false,'Search');
-
Generated on Fri Apr 26 2013 00:23:46 for TurboJPEG by  +
Generated on Fri Apr 26 2013 03:39:31 for TurboJPEG by  doxygen 1.7.4
diff --git a/doc/html/modules.html b/doc/html/modules.html index f4ba3b6..dbd8ece 100644 --- a/doc/html/modules.html +++ b/doc/html/modules.html @@ -72,7 +72,7 @@ var searchBox = new SearchBox("searchBox", "search",false,'Search');
-
Generated on Fri Apr 26 2013 00:23:46 for TurboJPEG by  +
Generated on Fri Apr 26 2013 03:39:31 for TurboJPEG by  doxygen 1.7.4
diff --git a/doc/html/structtjregion.html b/doc/html/structtjregion.html index 6063ef0..d5cf584 100644 --- a/doc/html/structtjregion.html +++ b/doc/html/structtjregion.html @@ -165,7 +165,7 @@ Data Fields -
Generated on Fri Apr 26 2013 00:23:46 for TurboJPEG by  +
Generated on Fri Apr 26 2013 03:39:31 for TurboJPEG by  doxygen 1.7.4
diff --git a/doc/html/structtjscalingfactor.html b/doc/html/structtjscalingfactor.html index 74f235e..5f1413b 100644 --- a/doc/html/structtjscalingfactor.html +++ b/doc/html/structtjscalingfactor.html @@ -127,7 +127,7 @@ Data Fields -
Generated on Fri Apr 26 2013 00:23:46 for TurboJPEG by  +
Generated on Fri Apr 26 2013 03:39:31 for TurboJPEG by  doxygen 1.7.4
diff --git a/doc/html/structtjtransform.html b/doc/html/structtjtransform.html index bf44999..3e9cd55 100644 --- a/doc/html/structtjtransform.html +++ b/doc/html/structtjtransform.html @@ -103,8 +103,8 @@ Data Fields coeffspointer to an array of transformed DCT coefficients. (NOTE: this pointer is not guaranteed to be valid once the callback returns, so applications wishing to hand off the DCT coefficients to another function or library should make a copy of them within the body of the callback.) arrayRegiontjregion structure containing the width and height of the array pointed to by coeffs as well as its offset relative to the component plane. TurboJPEG implementations may choose to split each component plane into multiple DCT coefficient arrays and call the callback function once for each array. planeRegiontjregion structure containing the width and height of the component plane to which coeffs belongs - componentIDID number of the component plane to which coeffs belongs (Y, Cb, and Cr have, respectively, ID's of 0, 1, and 2 in typical JPEG images.) - transformIDID number of the transformed image to which coeffs belongs. This is the same as the index of the transform in the transforms array that was passed to tjTransform(). + componentIDID number of the component plane to which coeffs belongs (Y, U, and V have, respectively, ID's of 0, 1, and 2 in typical JPEG images.) + transformIDID number of the transformed image to which coeffs belongs. This is the same as the index of the transform in the transforms array that was passed to tjTransform(). transforma pointer to a tjtransform structure that specifies the parameters and/or cropping region for this transform @@ -191,7 +191,7 @@ Data Fields -
Generated on Fri Apr 26 2013 00:23:46 for TurboJPEG by  +
Generated on Fri Apr 26 2013 03:39:31 for TurboJPEG by  doxygen 1.7.4
diff --git a/turbojpeg.h b/turbojpeg.h index a61cc1a..3fc6c39 100644 --- a/turbojpeg.h +++ b/turbojpeg.h @@ -53,8 +53,8 @@ /** * Chrominance subsampling options. - * When an image is converted from the RGB to the YCbCr colorspace as part of - * the JPEG compression process, some of the Cb and Cr (chrominance) components + * When an image is converted from the RGB to the YUV colorspace as part of + * the JPEG compression process, some of the U and V (chrominance) components * can be discarded or averaged together to produce a smaller image with little * perceptible loss of image clarity (the human eye is more sensitive to small * changes in brightness than small changes in color.) This is called @@ -246,10 +246,11 @@ static const int tjPixelSize[TJ_NUMPF] = {3, 3, 4, 4, 4, 4, 1, 4, 4, 4, 4}; */ #define TJFLAG_FORCESSE3 128 /** - * When decompressing, use the fastest chrominance upsampling algorithm - * available in the underlying codec. The default is to use smooth upsampling, - * which creates a smooth transition between neighboring chrominance components - * in order to reduce upsampling artifacts in the decompressed image. + * When decompressing an image that was compressed using chrominance + * subsampling, use the fastest chrominance upsampling algorithm available in + * the underlying codec. The default is to use smooth upsampling, which + * creates a smooth transition between neighboring chrominance components in + * order to reduce upsampling artifacts in the decompressed image. */ #define TJFLAG_FASTUPSAMPLE 256 /** @@ -281,7 +282,7 @@ static const int tjPixelSize[TJ_NUMPF] = {3, 3, 4, 4, 4, 4, 1, 4, 4, 4, 4}; /** - * Number of transform operations + * The number of transform operations */ #define TJ_NUMXOP 8 @@ -455,11 +456,11 @@ typedef struct tjtransform * @param planeRegion #tjregion structure containing the width and height of * the component plane to which coeffs belongs * @param componentID ID number of the component plane to which - * coeffs belongs (Y, Cb, and Cr have, respectively, ID's of + * coeffs belongs (Y, U, and V have, respectively, ID's of * 0, 1, and 2 in typical JPEG images.) * @param transformID ID number of the transformed image to which * coeffs belongs. This is the same as the index of the - * transform in the transforms array that was passed to + * transform in the transforms array that was passed to * #tjTransform(). * @param transform a pointer to a #tjtransform structure that specifies the * parameters and/or cropping region for this transform @@ -562,7 +563,7 @@ DLLEXPORT int DLLCALL tjCompress2(tjhandle handle, unsigned char *srcBuf, * the given parameters. The number of bytes returned by this function is * larger than the size of the uncompressed source image. The reason for this * is that the JPEG format uses 16-bit coefficients, and it is thus possible - * for a very high-quality JPEG image with very high frequency content to + * for a very high-quality JPEG image with very high-frequency content to * expand rather than compress when converted to the JPEG format. Such images * represent a very rare corner case, but since there is no way to predict the * size of a JPEG image prior to compression, the corner case has to be @@ -694,14 +695,15 @@ DLLEXPORT tjscalingfactor* DLLCALL tjGetScalingFactors(int *numscalingfactors); * image. This buffer should normally be pitch * scaledHeight * bytes in size, where scaledHeight can be determined by * calling #TJSCALED() with the JPEG image height and one of the scaling - * factors returned by #tjGetScalingFactors(). The dstBuf pointer may - * also be used to decompress into a specific region of a larger buffer. + * factors returned by #tjGetScalingFactors(). The dstBuf + * pointer may also be used to decompress into a specific region of a + * larger buffer. * @param width desired width (in pixels) of the destination 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. + * width is set to 0, then only the height will be considered + * when determining the scaled image size. * @param pitch bytes per line of the destination image. Normally, this is * scaledWidth * #tjPixelSize[pixelFormat] if the decompressed * image is unpadded, else #TJPAD(scaledWidth * @@ -717,8 +719,8 @@ DLLEXPORT tjscalingfactor* DLLCALL tjGetScalingFactors(int *numscalingfactors); * 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. + * If height is set to 0, then only the width will be + * considered when determining the scaled image size. * @param pixelFormat pixel format of the destination image (see @ref * TJPF "Pixel formats".) * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP @@ -735,7 +737,7 @@ 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 the images generated by #tjEncodeYUV2(). Note + * 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. @@ -744,7 +746,7 @@ DLLEXPORT int DLLCALL tjDecompress2(tjhandle handle, * @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 + * Use #tjBufSizeYUV() to determine the appropriate size for this buffer * based on the image width, height, and level of subsampling. * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP * "flags". @@ -771,12 +773,12 @@ DLLEXPORT tjhandle DLLCALL tjInitTransform(void); * to another without altering the values of the coefficients. While this is * typically faster than decompressing the image, transforming it, and * re-compressing it, lossless transforms are not free. Each lossless - * transform requires reading and Huffman decoding all of the coefficients in - * the source image, regardless of the size of the destination image. Thus, - * this function provides a means of generating multiple transformed images - * from the same source or of applying multiple transformations simultaneously, - * in order to eliminate the need to read the source coefficients multiple - * times. + * transform requires reading and performing Huffman decoding on all of the + * coefficients in the source image, regardless of the size of the destination + * image. Thus, this function provides a means of generating multiple + * transformed images from the same source or applying multiple + * transformations simultaneously, in order to eliminate the need to read the + * source coefficients multiple times. * * @param handle a handle to a TurboJPEG transformer instance * @param jpegBuf pointer to a buffer containing the JPEG image to transform @@ -792,9 +794,9 @@ DLLEXPORT tjhandle DLLCALL tjInitTransform(void); * -# set dstBufs[i] to NULL to tell TurboJPEG to allocate the * buffer for you, or * -# pre-allocate the buffer to a "worst case" size determined by - * calling #tjBufSize() with the cropped width and height. This should - * ensure that the buffer never has to be re-allocated (setting - * #TJFLAG_NOREALLOC guarantees this.) + * calling #tjBufSize() with the transformed or cropped width and + * height. This should ensure that the buffer never has to be + * re-allocated (setting #TJFLAG_NOREALLOC guarantees this.) * . * If you choose option 1, dstSizes[i] should be set to * the size of your pre-allocated buffer. In any case, unless you have @@ -806,7 +808,7 @@ DLLEXPORT tjhandle DLLCALL tjInitTransform(void); * dstSizes[i] should be set to the size of the buffer. Upon * return, dstSizes[i] will contain the size of the JPEG image * (in bytes.) - * @param transforms pointer to an array of n tjtransform structures, each of + * @param transforms pointer to an array of n #tjtransform structures, each of * which specifies the transform parameters and/or cropping region for * the corresponding transformed output image. * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP