dimension using the given scaling factor. More...Technically, the JPEG format uses the YCbCr colorspace (which is technically not a colorspace but a color transform), but per the convention of the digital video community, the TurboJPEG API uses "YUV" to refer to an image format consisting of Y, Cb, and Cr image planes.
-Each plane is simply a 2D array of bytes, each byte representing the value of one of the components (Y, Cb, or Cr) at a particular location in the image. The width and height of each plane are determined by the image width, height, and level of chrominance subsampling. The luminance plane width is the image width padded to the nearest multiple of the horizontal subsampling factor (2 in the case of 4:2:0 and 4:2:2, 4 in the case of 4:1:1, 1 in the case of 4:4:4 or grayscale.) Similarly, the luminance plane height is the image height padded to the nearest multiple of the vertical subsampling factor (2 in the case of 4:2:0 or 4:4:0, 1 in the case of 4:4:4 or grayscale.) This is irrespective of any additional padding that may be specified as an argument to the various YUV functions. The chrominance plane width is equal to the luminance plane width divided by the horizontal subsampling factor, and the chrominance plane height is equal to the luminance plane height divided by the vertical subsampling factor.
-For example, if the source image is 35 x 35 pixels and 4:2:2 subsampling is used, then the luminance plane would be 36 x 35 bytes, and each of the chrominance planes would be 18 x 35 bytes. If you specify a line padding of 4 bytes on top of this, then the luminance plane would be 36 x 35 bytes, and each of the chrominance planes would be 20 x 35 bytes.
+Each plane is simply a 2D array of bytes, each byte representing the value of one of the components (Y, Cb, or Cr) at a particular location in the image. The width and height of each plane are determined by the image width, height, and level of chrominance subsampling. The luminance plane width is the image width padded to the nearest multiple of the horizontal subsampling factor (1 in the case of 4:4:4, grayscale, or 4:4:0; 2 in the case of 4:2:2 or 4:2:0; 4 in the case of 4:1:1.) Similarly, the luminance plane height is the image height padded to the nearest multiple of the vertical subsampling factor (1 in the case of 4:4:4, 4:2:2, grayscale, or 4:1:1; 2 in the case of 4:2:0 or 4:4:0.) This is irrespective of any additional padding that may be specified as an argument to the various YUV functions. The chrominance plane width is equal to the luminance plane width divided by the horizontal subsampling factor, and the chrominance plane height is equal to the luminance plane height divided by the vertical subsampling factor.
+For example, if the source image is 35 x 35 pixels and 4:2:2 subsampling is used, then the luminance plane would be 36 x 35 bytes, and each of the chrominance planes would be 18 x 35 bytes. If you specify a row alignment of 4 bytes on top of this, then the luminance plane would be 36 x 35 bytes, and each of the chrominance planes would be 20 x 35 bytes.
Use the most accurate DCT/IDCT algorithm available in the underlying codec.
-The default if this flag is not specified is implementation-specific. For example, the implementation of TurboJPEG for libjpeg[-turbo] uses the fast algorithm by default when compressing, because this has been shown to have only a very slight effect on accuracy, but it uses the accurate algorithm when decompressing, because this has been shown to have a larger effect.
+Use the most accurate DCT/IDCT algorithm available.
+The default if this flag is not specified is implementation-specific. For example, the implementation of the TurboJPEG API in libjpeg-turbo uses the fast algorithm by default when compressing, because this has been shown to have only a very slight effect on accuracy, but it uses the accurate algorithm when decompressing, because this has been shown to have a larger effect.
The uncompressed source/destination image is stored in bottom-up (Windows, OpenGL) order, not top-down (X11) order.
+Rows in the packed-pixel source/destination image are stored in bottom-up (Windows, OpenGL) order rather than in top-down (X11) order.
Use the fastest DCT/IDCT algorithm available in the underlying codec.
-The default if this flag is not specified is implementation-specific. For example, the implementation of TurboJPEG for libjpeg[-turbo] uses the fast algorithm by default when compressing, because this has been shown to have only a very slight effect on accuracy, but it uses the accurate algorithm when decompressing, because this has been shown to have a larger effect.
+Use the fastest DCT/IDCT algorithm available.
+The default if this flag is not specified is implementation-specific. For example, the implementation of the TurboJPEG API in libjpeg-turbo uses the fast algorithm by default when compressing, because this has been shown to have only a very slight effect on accuracy, but it uses the accurate algorithm when decompressing, because this has been shown to have a larger effect.
When decompressing an image that was compressed using chrominance subsampling, 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.
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.
Disable buffer (re)allocation.
-If passed to one of the JPEG compression or transform functions, this flag will cause those functions to generate an error if the JPEG image buffer is invalid or too small rather than attempting to allocate or reallocate that buffer. This reproduces the behavior of earlier versions of TurboJPEG.
+Disable JPEG buffer (re)allocation.
+If passed to one of the JPEG compression or transform functions, this flag will cause those functions to generate an error if the JPEG destination buffer is invalid or too small, rather than attempt to allocate or reallocate that buffer.
Immediately discontinue the current compression/decompression/transform operation if the underlying codec throws a warning (non-fatal error).
+Immediately discontinue the current compression/decompression/transform operation if a warning (non-fatal error) occurs.
The default behavior is to allow the operation to complete unless a fatal error is encountered.
Pad the given width to the nearest 32-bit boundary.
+Pad the given width to the nearest multiple of 4.
This option will enable arithmetic entropy coding in the output image generated by this particular transform.
-Arithmetic entropy coding will generally improve compression relative to Huffman entropy coding (the default), but it will reduce compression and decompression performance considerably. Can be combined with TJXOPT_PROGRESSIVE.
+This option will enable arithmetic entropy coding in the JPEG image generated by this particular transform.
+Arithmetic entropy coding will generally improve compression relative to Huffman entropy coding (the default), but it will reduce compression and decompression performance considerably. Can be combined with TJXOPT_PROGRESSIVE.
This option will prevent tjTransform() from copying any extra markers (including EXIF and ICC profile data) from the source image to the output image.
+This option will prevent tjTransform() from copying any extra markers (including EXIF and ICC profile data) from the source image to the destination image.
This option will discard the color data in the input image and produce a grayscale output image.
+This option will discard the color data in the source image and produce a grayscale destination image.
This option will prevent tjTransform() from outputting a JPEG image for this particular transform (this can be used in conjunction with a custom filter to capture the transformed DCT coefficients without transcoding them.)
+This option will prevent tjTransform() from outputting a JPEG image for this particular transform.
+(This can be used in conjunction with a custom filter to capture the transformed DCT coefficients without transcoding them.)
This option will enable progressive entropy coding in the output image generated by this particular transform.
-Progressive entropy coding will generally improve compression relative to baseline entropy coding (the default), but it will reduce compression and decompression performance considerably. Can be combined with TJXOPT_ARITHMETIC.
+This option will enable progressive entropy coding in the JPEG image generated by this particular transform.
+Progressive entropy coding will generally improve compression relative to baseline entropy coding (the default), but it will reduce compression and decompression performance considerably. Can be combined with TJXOPT_ARITHMETIC.
JPEG colorspaces.
Error codes.
| Enumerator | |
|---|---|
| TJERR_WARNING | The error was non-fatal and recoverable, but the image may still be corrupt. + |
| Enumerator | |
| TJERR_WARNING | The error was non-fatal and recoverable, but the destination image may still be corrupt. |
| TJERR_FATAL | The error was fatal and non-recoverable. |
| TJPF_CMYK | CMYK pixel format. -Unlike RGB, which is an additive color model used primarily for display, CMYK (Cyan/Magenta/Yellow/Key) is a subtractive color model used primarily for printing. In the CMYK color model, the value of each color component typically corresponds to an amount of cyan, magenta, yellow, or black ink that is applied to a white background. In order to convert between CMYK and RGB, it is necessary to use a color management system (CMS.) A CMS will attempt to map colors within the printer's gamut to perceptually similar colors in the display's gamut and vice versa, but the mapping is typically not 1:1 or reversible, nor can it be defined with a simple formula. Thus, such a conversion is out of scope for a codec library. However, the TurboJPEG API allows for compressing CMYK pixels into a YCCK JPEG image (see TJCS_YCCK) and decompressing YCCK JPEG images into CMYK pixels. +Unlike RGB, which is an additive color model used primarily for display, CMYK (Cyan/Magenta/Yellow/Key) is a subtractive color model used primarily for printing. In the CMYK color model, the value of each color component typically corresponds to an amount of cyan, magenta, yellow, or black ink that is applied to a white background. In order to convert between CMYK and RGB, it is necessary to use a color management system (CMS.) A CMS will attempt to map colors within the printer's gamut to perceptually similar colors in the display's gamut and vice versa, but the mapping is typically not 1:1 or reversible, nor can it be defined with a simple formula. Thus, such a conversion is out of scope for a codec library. However, the TurboJPEG API allows for compressing packed-pixel CMYK images into YCCK JPEG images (see TJCS_YCCK) and decompressing YCCK JPEG images into packed-pixel CMYK images. |
| TJPF_UNKNOWN | Unknown pixel format. -Currently this is only used by tjLoadImage(). +Currently this is only used by tjLoadImage(). |
Chrominance subsampling options.
-When pixels are converted from RGB to YCbCr (see TJCS_YCbCr) or from CMYK to YCCK (see TJCS_YCCK) 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 to small changes in color.) This is called "chrominance subsampling".
+When pixels are converted from RGB to YCbCr (see TJCS_YCbCr) or from CMYK to YCCK (see TJCS_YCCK) 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 to small changes in color.) This is called "chrominance subsampling".
Allocate an image buffer for use with TurboJPEG.
-You should always use this function to allocate the JPEG destination buffer(s) for the compression and transform functions unless you are disabling automatic buffer (re)allocation (by setting TJFLAG_NOREALLOC.)
+Allocate a byte buffer for use with TurboJPEG.
+You should always use this function to allocate the JPEG destination buffer(s) for the compression and transform functions unless you are disabling automatic buffer (re)allocation (by setting TJFLAG_NOREALLOC.)
| bytes | the number of bytes to allocate |
| width | width (in pixels) of the image |
| 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.) |
| align | row alignment (in bytes) of the image (must be a power of 2.) Setting this parameter to n specifies that each row in each plane of the image will be padded to the nearest multiple of n bytes (1 = unpadded.) |
| height | height (in pixels) of the image |
| subsamp | level of chrominance subsampling in the image (see Chrominance subsampling options.) |
Compress an RGB, grayscale, or CMYK image into a JPEG image.
+Compress a packed-pixel RGB, grayscale, or CMYK image into a JPEG image.
| handle | a handle to a TurboJPEG compressor or transformer instance | ||||
| srcBuf | pointer to an image buffer containing RGB, grayscale, or CMYK pixels to be compressed | ||||
| srcBuf | pointer to a buffer containing a packed-pixel RGB, grayscale, or CMYK source image to be compressed | ||||
| width | width (in pixels) of the source image | ||||
| pitch | bytes per line in the source image. Normally, this should be width * tjPixelSize[pixelFormat] if the image is unpadded, or TJPAD(width * tjPixelSize[pixelFormat]) if each line of the image is padded to the nearest 32-bit boundary, as is the case for Windows bitmaps. You can also be clever and use this parameter to skip lines, etc. Setting this parameter to 0 is the equivalent of setting it to width * tjPixelSize[pixelFormat]. | ||||
| pitch | bytes per row in the source image. Normally this should be width * tjPixelSize[pixelFormat], if the image is unpadded, or TJPAD(width * tjPixelSize[pixelFormat]) if each row of the image is padded to the nearest multiple of 4 bytes, as is the case for Windows bitmaps. You can also be clever and use this parameter to skip rows, etc. Setting this parameter to 0 is the equivalent of setting it to width * tjPixelSize[pixelFormat]. | ||||
| height | height (in pixels) of the source image | ||||
| pixelFormat | pixel format of the source image (see Pixel formats.) | ||||
| jpegBuf | address of a pointer to an image buffer that will receive the JPEG image. TurboJPEG has the ability to reallocate the JPEG buffer to accommodate the size of the JPEG image. Thus, you can choose to:
jpegBuf | address of a pointer to a byte buffer that will receive the JPEG image. TurboJPEG has the ability to reallocate the JPEG buffer to accommodate the size of the JPEG image. Thus, you can choose to: |
*jpegSize should be set to the size of your pre-allocated buffer. In any case, unless you have set TJFLAG_NOREALLOC, you should always check *jpegBuf upon return from this function, as it may have changed.jpegSize | pointer to an unsigned long variable that holds the size of the JPEG image buffer. If | *jpegBuf points to a pre-allocated buffer, then *jpegSize should be set to the size of the buffer. Upon return, *jpegSize will contain the size of the JPEG image (in bytes.) If *jpegBuf points to a JPEG image buffer that is being reused from a previous call to one of the JPEG compression functions, then *jpegSize is ignored.*jpegSize should be set to the size of your pre-allocated buffer. In any case, unless you have set TJFLAG_NOREALLOC, you should always check *jpegBuf upon return from this function, as it may have changed. |
| jpegSize | pointer to an unsigned long variable that holds the size of the JPEG buffer. If *jpegBuf points to a pre-allocated buffer, then *jpegSize should be set to the size of the buffer. Upon return, *jpegSize will contain the size of the JPEG image (in bytes.) If *jpegBuf points to a JPEG buffer that is being reused from a previous call to one of the JPEG compression functions, then *jpegSize is ignored. | ||||
| jpegSubsamp | the level of chrominance subsampling to be used when generating the JPEG image (see Chrominance subsampling options.) | ||||
| jpegQual | the image quality of the generated JPEG image (1 = worst, 100 = best.) When generating a lossless JPEG image (see TJFLAG_LOSSLESS), jpegQual is psv * 10 + Pt, where psv is the predictor selection value (1-7) and Pt is the point transform (0-7). A point transform value of 0 is necessary in order to create a fully lossless JPEG image. (A non-zero point transform value right-shifts the input samples by the specified number of bits, which is effectively a form of lossy color quantization.) | ||||
| flags | the bitwise OR of one or more of the flags | int | -pad, | +align, | |
| @@ -1338,22 +1339,22 @@ If you choose option 1, |
Compress a YUV planar image into a JPEG image.
+Compress a unified planar YUV image into a JPEG image.
| handle | a handle to a TurboJPEG compressor or transformer instance | ||||
| srcBuf | pointer to an image buffer containing a YUV planar image to be compressed. The size of this buffer should match the value returned by tjBufSizeYUV2() for the given image width, height, padding, and level of chrominance subsampling. The Y, U (Cb), and V (Cr) image planes should be stored sequentially in the source buffer (refer to YUV Image Format Notes.) | ||||
| width | width (in pixels) of the source image. If the width is not an even multiple of the MCU block width (see tjMCUWidth), then an intermediate buffer copy will be performed within TurboJPEG. | ||||
| pad | the line padding used in the source image. For instance, if each line in each plane of the YUV image is padded to the nearest multiple of 4 bytes, then pad should be set to 4. | ||||
| height | height (in pixels) of the source image. If the height is not an even multiple of the MCU block height (see tjMCUHeight), then an intermediate buffer copy will be performed within TurboJPEG. | ||||
| srcBuf | pointer to a buffer containing a unified planar YUV source image to be compressed. The size of this buffer should match the value returned by tjBufSizeYUV2() for the given image width, height, row alignment, and level of chrominance subsampling. The Y, U (Cb), and V (Cr) image planes should be stored sequentially in the buffer. (Refer to YUV Image Format Notes.) | ||||
| width | width (in pixels) of the source image. If the width is not an even multiple of the MCU block width (see tjMCUWidth), then an intermediate buffer copy will be performed. | ||||
| align | row alignment (in bytes) of the source image (must be a power of 2.) Setting this parameter to n indicates that each row in each plane of the source image is padded to the nearest multiple of n bytes (1 = unpadded.) | ||||
| height | height (in pixels) of the source image. If the height is not an even multiple of the MCU block height (see tjMCUHeight), then an intermediate buffer copy will be performed. | ||||
| subsamp | the level of chrominance subsampling used in the source image (see Chrominance subsampling options.) | ||||
| jpegBuf | address of a pointer to an image buffer that will receive the JPEG image. TurboJPEG has the ability to reallocate the JPEG buffer to accommodate the size of the JPEG image. Thus, you can choose to:
jpegBuf | address of a pointer to a byte buffer that will receive the JPEG image. TurboJPEG has the ability to reallocate the JPEG buffer to accommodate the size of the JPEG image. Thus, you can choose to: |
*jpegSize should be set to the size of your pre-allocated buffer. In any case, unless you have set TJFLAG_NOREALLOC, you should always check *jpegBuf upon return from this function, as it may have changed.jpegSize | pointer to an unsigned long variable that holds the size of the JPEG image buffer. If | *jpegBuf points to a pre-allocated buffer, then *jpegSize should be set to the size of the buffer. Upon return, *jpegSize will contain the size of the JPEG image (in bytes.) If *jpegBuf points to a JPEG image buffer that is being reused from a previous call to one of the JPEG compression functions, then *jpegSize is ignored.*jpegSize should be set to the size of your pre-allocated buffer. In any case, unless you have set TJFLAG_NOREALLOC, you should always check *jpegBuf upon return from this function, as it may have changed. |
| jpegSize | pointer to an unsigned long variable that holds the size of the JPEG buffer. If *jpegBuf points to a pre-allocated buffer, then *jpegSize should be set to the size of the buffer. Upon return, *jpegSize will contain the size of the JPEG image (in bytes.) If *jpegBuf points to a JPEG buffer that is being reused from a previous call to one of the JPEG compression functions, then *jpegSize is ignored. | ||||
| jpegQual | the image quality of the generated JPEG image (1 = worst, 100 = best) | ||||
| flags | the bitwise OR of one or more of the flags |
*jpegSize should be set to the size of your
| handle | a handle to a TurboJPEG compressor or transformer instance | ||||
| srcPlanes | an array of pointers to Y, U (Cb), and V (Cr) image planes (or just a Y plane, if compressing a grayscale image) that contain a YUV image to be compressed. These planes can be contiguous or non-contiguous in memory. The size of each plane should match the value returned by tjPlaneSizeYUV() for the given image width, height, strides, and level of chrominance subsampling. Refer to YUV Image Format Notes for more details. | ||||
| width | width (in pixels) of the source image. If the width is not an even multiple of the MCU block width (see tjMCUWidth), then an intermediate buffer copy will be performed within TurboJPEG. | ||||
| strides | an array of integers, each specifying the number of bytes per line in the corresponding plane of the YUV source image. Setting the stride for any plane to 0 is the same as setting it to the plane width (see YUV Image Format Notes.) If strides is NULL, then the strides for all planes will be set to their respective plane widths. You can adjust the strides in order to specify an arbitrary amount of line padding in each plane or to create a JPEG image from a subregion of a larger YUV planar image. | ||||
| height | height (in pixels) of the source image. If the height is not an even multiple of the MCU block height (see tjMCUHeight), then an intermediate buffer copy will be performed within TurboJPEG. | ||||
| srcPlanes | an array of pointers to Y, U (Cb), and V (Cr) image planes (or just a Y plane, if compressing a grayscale image) that contain a YUV source image to be compressed. These planes can be contiguous or non-contiguous in memory. The size of each plane should match the value returned by tjPlaneSizeYUV() for the given image width, height, strides, and level of chrominance subsampling. Refer to YUV Image Format Notes for more details. | ||||
| width | width (in pixels) of the source image. If the width is not an even multiple of the MCU block width (see tjMCUWidth), then an intermediate buffer copy will be performed. | ||||
| strides | an array of integers, each specifying the number of bytes per row in the corresponding plane of the YUV source image. Setting the stride for any plane to 0 is the same as setting it to the plane width (see YUV Image Format Notes.) If strides is NULL, then the strides for all planes will be set to their respective plane widths. You can adjust the strides in order to specify an arbitrary amount of row padding in each plane or to create a JPEG image from a subregion of a larger planar YUV image. | ||||
| height | height (in pixels) of the source image. If the height is not an even multiple of the MCU block height (see tjMCUHeight), then an intermediate buffer copy will be performed. | ||||
| subsamp | the level of chrominance subsampling used in the source image (see Chrominance subsampling options.) | ||||
| jpegBuf | address of a pointer to an image buffer that will receive the JPEG image. TurboJPEG has the ability to reallocate the JPEG buffer to accommodate the size of the JPEG image. Thus, you can choose to:
jpegBuf | address of a pointer to a byte buffer that will receive the JPEG image. TurboJPEG has the ability to reallocate the JPEG buffer to accommodate the size of the JPEG image. Thus, you can choose to: |
*jpegSize should be set to the size of your pre-allocated buffer. In any case, unless you have set TJFLAG_NOREALLOC, you should always check *jpegBuf upon return from this function, as it may have changed.jpegSize | pointer to an unsigned long variable that holds the size of the JPEG image buffer. If | *jpegBuf points to a pre-allocated buffer, then *jpegSize should be set to the size of the buffer. Upon return, *jpegSize will contain the size of the JPEG image (in bytes.) If *jpegBuf points to a JPEG image buffer that is being reused from a previous call to one of the JPEG compression functions, then *jpegSize is ignored.*jpegSize should be set to the size of your pre-allocated buffer. In any case, unless you have set TJFLAG_NOREALLOC, you should always check *jpegBuf upon return from this function, as it may have changed. |
| jpegSize | pointer to an unsigned long variable that holds the size of the JPEG buffer. If *jpegBuf points to a pre-allocated buffer, then *jpegSize should be set to the size of the buffer. Upon return, *jpegSize will contain the size of the JPEG image (in bytes.) If *jpegBuf points to a JPEG buffer that is being reused from a previous call to one of the JPEG compression functions, then *jpegSize is ignored. | ||||
| jpegQual | the image quality of the generated JPEG image (1 = worst, 100 = best) | ||||
| flags | the bitwise OR of one or more of the flags |
*jpegSize should be set to the size of your
*jpegSize should be set to the size of your
*jpegSize should be set to the size of your
Decode a YUV planar image into an RGB or grayscale image.
-This function uses the accelerated color conversion routines in the underlying codec but does not execute any of the other steps in the JPEG decompression process.
+Decode a unified planar YUV image into a packed-pixel RGB or grayscale image.
+This function performs color conversion (which is accelerated in the libjpeg-turbo implementation) but does not execute any of the other steps in the JPEG decompression process.
| handle | a handle to a TurboJPEG decompressor or transformer instance |
| srcBuf | pointer to an image buffer containing a YUV planar image to be decoded. The size of this buffer should match the value returned by tjBufSizeYUV2() for the given image width, height, padding, and level of chrominance subsampling. The Y, U (Cb), and V (Cr) image planes should be stored sequentially in the source buffer (refer to YUV Image Format Notes.) |
| pad | Use this parameter to specify that the width of each line in each plane of the YUV source image is padded to the nearest multiple of this number of bytes (must be a power of 2.) |
| srcBuf | pointer to a buffer containing a unified planar YUV source image to be decoded. The size of this buffer should match the value returned by tjBufSizeYUV2() for the given image width, height, row alignment, and level of chrominance subsampling. The Y, U (Cb), and V (Cr) image planes should be stored sequentially in the source buffer. (Refer to YUV Image Format Notes.) |
| align | row alignment (in bytes) of the YUV source image (must be a power of 2.) Setting this parameter to n indicates that each row in each plane of the YUV source image is padded to the nearest multiple of n bytes (1 = unpadded.) |
| subsamp | the level of chrominance subsampling used in the YUV source image (see Chrominance subsampling options.) |
| dstBuf | pointer to an image buffer that will receive the decoded image. This buffer should normally be pitch * height bytes in size, but the dstBuf pointer can also be used to decode into a specific region of a larger buffer. |
| dstBuf | pointer to a buffer that will receive the packed-pixel decoded image. This buffer should normally be pitch * height bytes in size, but the dstBuf pointer can also be used to decode into a specific region of a larger buffer. |
| width | width (in pixels) of the source and destination images |
| pitch | bytes per line in the destination image. Normally, this should be width * tjPixelSize[pixelFormat] if the destination image is unpadded, or TJPAD(width * tjPixelSize[pixelFormat]) if each line of the destination image should be padded to the nearest 32-bit boundary, as is the case for Windows bitmaps. 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 width * tjPixelSize[pixelFormat]. |
| pitch | bytes per row in the destination image. Normally this should be set to width * tjPixelSize[pixelFormat], if the destination image should be unpadded, or TJPAD(width * tjPixelSize[pixelFormat]) if each row of the destination image should be padded to the nearest multiple of 4 bytes, as is the case for Windows bitmaps. You can also be clever and use the pitch parameter to skip rows, etc. Setting this parameter to 0 is the equivalent of setting it to width * tjPixelSize[pixelFormat]. |
| height | height (in pixels) of the source and destination images |
| pixelFormat | pixel format of the destination image (see Pixel formats.) |
| flags | the bitwise OR of one or more of the flags |
Decode a set of Y, U (Cb), and V (Cr) image planes into an RGB or grayscale image.
-This function uses the accelerated color conversion routines in the underlying codec but does not execute any of the other steps in the JPEG decompression process.
+Decode a set of Y, U (Cb), and V (Cr) image planes into a packed-pixel RGB or grayscale image.
+This function performs color conversion (which is accelerated in the libjpeg-turbo implementation) but does not execute any of the other steps in the JPEG decompression process.
| handle | a handle to a TurboJPEG decompressor or transformer instance |
| srcPlanes | an array of pointers to Y, U (Cb), and V (Cr) image planes (or just a Y plane, if decoding a grayscale image) that contain a YUV image to be decoded. These planes can be contiguous or non-contiguous in memory. The size of each plane should match the value returned by tjPlaneSizeYUV() for the given image width, height, strides, and level of chrominance subsampling. Refer to YUV Image Format Notes for more details. |
| strides | an array of integers, each specifying the number of bytes per line in the corresponding plane of the YUV source image. Setting the stride for any plane to 0 is the same as setting it to the plane width (see YUV Image Format Notes.) If strides is NULL, then the strides for all planes will be set to their respective plane widths. You can adjust the strides in order to specify an arbitrary amount of line padding in each plane or to decode a subregion of a larger YUV planar image. |
| strides | an array of integers, each specifying the number of bytes per row in the corresponding plane of the YUV source image. Setting the stride for any plane to 0 is the same as setting it to the plane width (see YUV Image Format Notes.) If strides is NULL, then the strides for all planes will be set to their respective plane widths. You can adjust the strides in order to specify an arbitrary amount of row padding in each plane or to decode a subregion of a larger planar YUV image. |
| subsamp | the level of chrominance subsampling used in the YUV source image (see Chrominance subsampling options.) |
| dstBuf | pointer to an image buffer that will receive the decoded image. This buffer should normally be pitch * height bytes in size, but the dstBuf pointer can also be used to decode into a specific region of a larger buffer. |
| dstBuf | pointer to a buffer that will receive the packed-pixel decoded image. This buffer should normally be pitch * height bytes in size, but the dstBuf pointer can also be used to decode into a specific region of a larger buffer. |
| width | width (in pixels) of the source and destination images |
| pitch | bytes per line in the destination image. Normally, this should be width * tjPixelSize[pixelFormat] if the destination image is unpadded, or TJPAD(width * tjPixelSize[pixelFormat]) if each line of the destination image should be padded to the nearest 32-bit boundary, as is the case for Windows bitmaps. 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 width * tjPixelSize[pixelFormat]. |
| pitch | bytes per row in the destination image. Normally this should be set to width * tjPixelSize[pixelFormat], if the destination image should be unpadded, or TJPAD(width * tjPixelSize[pixelFormat]) if each row of the destination image should be padded to the nearest multiple of 4 bytes, as is the case for Windows bitmaps. You can also be clever and use the pitch parameter to skip rows, etc. Setting this parameter to 0 is the equivalent of setting it to width * tjPixelSize[pixelFormat]. |
| height | height (in pixels) of the source and destination images |
| pixelFormat | pixel format of the destination image (see Pixel formats.) |
| flags | the bitwise OR of one or more of the flags |
Decompress a JPEG image to an RGB, grayscale, or CMYK image.
+Decompress a JPEG image into a packed-pixel RGB, grayscale, or CMYK image.
| handle | a handle to a TurboJPEG decompressor or transformer instance |
| jpegBuf | pointer to a buffer containing the JPEG image to decompress |
| jpegBuf | pointer to a byte buffer containing the JPEG image to decompress |
| jpegSize | size of the JPEG image (in bytes) |
| dstBuf | pointer 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. |
| dstBuf | pointer to a buffer that will receive the packed-pixel 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. |
| 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. |
| pitch | bytes per line in 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]. |
| pitch | bytes per row in the destination image. Normally this should be set to scaledWidth * tjPixelSize[pixelFormat], if the destination image should be unpadded, or TJPAD(scaledWidth * tjPixelSize[pixelFormat]) if each row of the destination image should be padded to the nearest multiple of 4 bytes, 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 rows, etc. Setting this parameter to 0 is the equivalent of setting it to scaledWidth * tjPixelSize[pixelFormat]. |
| height | desired 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. |
| pixelFormat | pixel format of the destination image (see Pixel formats.) |
| flags | the bitwise OR of one or more of the flags |
| handle | a handle to a TurboJPEG decompressor or transformer instance |
| jpegBuf | pointer to a buffer containing a JPEG image or an "abbreviated table specification" (AKA "tables-only") datastream. Passing a tables-only datastream to this function primes the decompressor with quantization and Huffman tables that can be used when decompressing subsequent "abbreviated image" datastreams. This is useful, for instance, when decompressing video streams in which all frames share the same quantization and Huffman tables. |
| jpegBuf | pointer to a byte buffer containing a JPEG image or an "abbreviated table specification" (AKA "tables-only") datastream. Passing a tables-only datastream to this function primes the decompressor with quantization and Huffman tables that can be used when decompressing subsequent "abbreviated image" datastreams. This is useful, for instance, when decompressing video streams in which all frames share the same quantization and Huffman tables. |
| jpegSize | size of the JPEG image or tables-only datastream (in bytes) |
| width | pointer to an integer variable that will receive the width (in pixels) of the JPEG image. If jpegBuf points to a tables-only datastream, then width is ignored. |
| height | pointer to an integer variable that will receive the height (in pixels) of the JPEG image. If jpegBuf points to a tables-only datastream, then height is ignored. | int | -pad, | +align, |
| @@ -1881,17 +1882,17 @@ If you choose option 1, |
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.
+Decompress a JPEG image into a unified planar YUV image.
+This function performs JPEG decompression but leaves out the color conversion step, so a planar YUV image is generated instead of a packed-pixel image.
| handle | a handle to a TurboJPEG decompressor or transformer instance |
| jpegBuf | pointer to a buffer containing the JPEG image to decompress |
| jpegBuf | pointer to a byte buffer containing the JPEG image to decompress |
| jpegSize | size of the JPEG image (in bytes) |
| dstBuf | pointer to an image buffer that will receive the YUV image. Use tjBufSizeYUV2() to determine the appropriate size for this buffer based on the image width, height, padding, and level of subsampling. The Y, U (Cb), and V (Cr) image planes will be stored sequentially in the buffer (refer to YUV Image Format Notes.) |
| 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. If the scaled width is not an even multiple of the MCU block width (see tjMCUWidth), then an intermediate buffer copy will be performed within TurboJPEG. |
| 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. |
| 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. If the scaled height is not an even multiple of the MCU block height (see tjMCUHeight), then an intermediate buffer copy will be performed within TurboJPEG. |
| dstBuf | pointer to a buffer that will receive the unified planar YUV decompressed image. Use tjBufSizeYUV2() to determine the appropriate size for this buffer based on the scaled image width, scaled image height, row alignment, and level of chrominance subsampling. The Y, U (Cb), and V (Cr) image planes will be stored sequentially in the buffer. (Refer to YUV Image Format Notes.) |
| 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. If the scaled width is not an even multiple of the MCU block width (see tjMCUWidth), then an intermediate buffer copy will be performed. |
| align | row alignment (in bytes) of the YUV image (must be a power of 2.) Setting this parameter to n will cause each row in each plane of the YUV image to be padded to the nearest multiple of n bytes (1 = unpadded.) To generate images suitable for X Video, align should be set to 4. |
| 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. If the scaled height is not an even multiple of the MCU block height (see tjMCUHeight), then an intermediate buffer copy will be performed. |
| flags | the bitwise OR of one or more of the flags |
*jpegSize should be set to the size of your
Decompress a JPEG image into separate Y, U (Cb), and V (Cr) image planes.
-This function performs JPEG decompression but leaves out the color conversion step, so a planar YUV image is generated instead of an RGB image.
+This function performs JPEG decompression but leaves out the color conversion step, so a planar YUV image is generated instead of a packed-pixel image.
| handle | a handle to a TurboJPEG decompressor or transformer instance |
| jpegBuf | pointer to a buffer containing the JPEG image to decompress |
| jpegBuf | pointer to a byte buffer containing the JPEG image to decompress |
| jpegSize | size of the JPEG image (in bytes) |
| dstPlanes | an array of pointers to Y, U (Cb), and V (Cr) image planes (or just a Y plane, if decompressing a grayscale image) that will receive the YUV image. These planes can be contiguous or non-contiguous in memory. Use tjPlaneSizeYUV() to determine the appropriate size for each plane based on the scaled image width, scaled image height, strides, and level of chrominance subsampling. Refer to YUV Image Format Notes for more details. |
| 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. If the scaled width is not an even multiple of the MCU block width (see tjMCUWidth), then an intermediate buffer copy will be performed within TurboJPEG. |
| strides | an array of integers, each specifying the number of bytes per line in the corresponding plane of the output image. Setting the stride for any plane to 0 is the same as setting it to the scaled plane width (see YUV Image Format Notes.) If strides is NULL, then the strides for all planes will be set to their respective scaled plane widths. You can adjust the strides in order to add an arbitrary amount of line padding to each plane or to decompress the JPEG image into a subregion of a larger YUV planar image. |
| 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. If the scaled height is not an even multiple of the MCU block height (see tjMCUHeight), then an intermediate buffer copy will be performed within TurboJPEG. |
| dstPlanes | an array of pointers to Y, U (Cb), and V (Cr) image planes (or just a Y plane, if decompressing a grayscale image) that will receive the decompressed image. These planes can be contiguous or non-contiguous in memory. Use tjPlaneSizeYUV() to determine the appropriate size for each plane based on the scaled image width, scaled image height, strides, and level of chrominance subsampling. Refer to YUV Image Format Notes for more details. |
| 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. If the scaled width is not an even multiple of the MCU block width (see tjMCUWidth), then an intermediate buffer copy will be performed. |
| strides | an array of integers, each specifying the number of bytes per row in the corresponding plane of the YUV image. Setting the stride for any plane to 0 is the same as setting it to the scaled plane width (see YUV Image Format Notes.) If strides is NULL, then the strides for all planes will be set to their respective scaled plane widths. You can adjust the strides in order to add an arbitrary amount of row padding to each plane or to decompress the JPEG image into a subregion of a larger planar YUV image. |
| 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. If the scaled height is not an even multiple of the MCU block height (see tjMCUHeight), then an intermediate buffer copy will be performed. |
| flags | the bitwise OR of one or more of the flags |
*jpegSize should be set to the size of your
*jpegSize should be set to the size of your
*jpegSize should be set to the size of your
Encode an RGB or grayscale image into a YUV planar image.
-This function uses the accelerated color conversion routines in the underlying codec but does not execute any of the other steps in the JPEG compression process.
+Encode a packed-pixel RGB or grayscale image into a unified planar YUV image.
+This function performs color conversion (which is accelerated in the libjpeg-turbo implementation) but does not execute any of the other steps in the JPEG compression process.
| handle | a handle to a TurboJPEG compressor or transformer instance |
| srcBuf | pointer to an image buffer containing RGB or grayscale pixels to be encoded |
| srcBuf | pointer to a buffer containing a packed-pixel RGB or grayscale source image to be encoded |
| width | width (in pixels) of the source image |
| pitch | bytes per line in the source image. Normally, this should be width * tjPixelSize[pixelFormat] if the image is unpadded, or TJPAD(width * tjPixelSize[pixelFormat]) if each line of the image is padded to the nearest 32-bit boundary, as is the case for Windows bitmaps. You can also be clever and use this parameter to skip lines, etc. Setting this parameter to 0 is the equivalent of setting it to width * tjPixelSize[pixelFormat]. |
| pitch | bytes per row in the source image. Normally this should be width * tjPixelSize[pixelFormat], if the image is unpadded, or TJPAD(width * tjPixelSize[pixelFormat]) if each row of the image is padded to the nearest multiple of 4 bytes, as is the case for Windows bitmaps. You can also be clever and use this parameter to skip rows, etc. Setting this parameter to 0 is the equivalent of setting it to width * tjPixelSize[pixelFormat]. |
| height | height (in pixels) of the source image |
| pixelFormat | pixel format of the source image (see Pixel formats.) |
| dstBuf | pointer to an image buffer that will receive the YUV image. Use tjBufSizeYUV2() to determine the appropriate size for this buffer based on the image width, height, padding, and level of chrominance subsampling. The Y, U (Cb), and V (Cr) image planes will be stored sequentially in the buffer (refer to YUV Image Format Notes.) |
| 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. |
| dstBuf | pointer to a buffer that will receive the unified planar YUV image. Use tjBufSizeYUV2() to determine the appropriate size for this buffer based on the image width, height, row alignment, and level of chrominance subsampling. The Y, U (Cb), and V (Cr) image planes will be stored sequentially in the buffer. (Refer to YUV Image Format Notes.) |
| align | row alignment (in bytes) of the YUV image (must be a power of 2.) Setting this parameter to n will cause each row in each plane of the YUV image to be padded to the nearest multiple of n bytes (1 = unpadded.) To generate images suitable for X Video, align should be set to 4. |
| subsamp | the level of chrominance subsampling to be used when generating the YUV image (see Chrominance subsampling options.) To generate images suitable for X Video, subsamp should be set to TJSAMP_420. This produces an image compatible with the I420 (AKA "YUV420P") format. |
| flags | the bitwise OR of one or more of the flags |
*jpegSize should be set to the size of your
Encode an RGB or grayscale image into separate Y, U (Cb), and V (Cr) image planes.
-This function uses the accelerated color conversion routines in the underlying codec but does not execute any of the other steps in the JPEG compression process.
+Encode a packed-pixel RGB or grayscale image into separate Y, U (Cb), and V (Cr) image planes.
+This function performs color conversion (which is accelerated in the libjpeg-turbo implementation) but does not execute any of the other steps in the JPEG compression process.
| handle | a handle to a TurboJPEG compressor or transformer instance |
| srcBuf | pointer to an image buffer containing RGB or grayscale pixels to be encoded |
| srcBuf | pointer to a buffer containing a packed-pixel RGB or grayscale source image to be encoded |
| width | width (in pixels) of the source image |
| pitch | bytes per line in the source image. Normally, this should be width * tjPixelSize[pixelFormat] if the image is unpadded, or TJPAD(width * tjPixelSize[pixelFormat]) if each line of the image is padded to the nearest 32-bit boundary, as is the case for Windows bitmaps. You can also be clever and use this parameter to skip lines, etc. Setting this parameter to 0 is the equivalent of setting it to width * tjPixelSize[pixelFormat]. |
| pitch | bytes per row in the source image. Normally this should be width * tjPixelSize[pixelFormat], if the image is unpadded, or TJPAD(width * tjPixelSize[pixelFormat]) if each row of the image is padded to the nearest multiple of 4 bytes, as is the case for Windows bitmaps. You can also be clever and use this parameter to skip rows, etc. Setting this parameter to 0 is the equivalent of setting it to width * tjPixelSize[pixelFormat]. |
| height | height (in pixels) of the source image |
| pixelFormat | pixel format of the source image (see Pixel formats.) |
| dstPlanes | an array of pointers to Y, U (Cb), and V (Cr) image planes (or just a Y plane, if generating a grayscale image) that will receive the encoded image. These planes can be contiguous or non-contiguous in memory. Use tjPlaneSizeYUV() to determine the appropriate size for each plane based on the image width, height, strides, and level of chrominance subsampling. Refer to YUV Image Format Notes for more details. |
| strides | an array of integers, each specifying the number of bytes per line in the corresponding plane of the output image. Setting the stride for any plane to 0 is the same as setting it to the plane width (see YUV Image Format Notes.) If strides is NULL, then the strides for all planes will be set to their respective plane widths. You can adjust the strides in order to add an arbitrary amount of line padding to each plane or to encode an RGB or grayscale image into a subregion of a larger YUV planar image. |
| strides | an array of integers, each specifying the number of bytes per row in the corresponding plane of the YUV image. Setting the stride for any plane to 0 is the same as setting it to the plane width (see YUV Image Format Notes.) If strides is NULL, then the strides for all planes will be set to their respective plane widths. You can adjust the strides in order to add an arbitrary amount of row padding to each plane or to encode an RGB or grayscale image into a subregion of a larger planar YUV image. |
| subsamp | the level of chrominance subsampling to be used when generating the YUV image (see Chrominance subsampling options.) To generate images suitable for X Video, subsamp should be set to TJSAMP_420. This produces an image compatible with the I420 (AKA "YUV420P") format. |
| flags | the bitwise OR of one or more of the flags |
*jpegSize should be set to the size of your
Free an image buffer previously allocated by TurboJPEG.
-You should always use this function to free JPEG destination buffer(s) that were automatically (re)allocated by the compression and transform functions or that were manually allocated using tjAlloc().
+Free a byte buffer previously allocated by TurboJPEG.
+You should always use this function to free JPEG destination buffer(s) that were automatically (re)allocated by the compression and transform functions or that were manually allocated using tjAlloc().
| buffer | address of the buffer to free. If the address is NULL, then this function has no effect. |
*jpegSize should be set to the size of your
-
-*jpegSize should be set to the size of your
Returns a list of fractional scaling factors that the JPEG decompressor in this implementation of TurboJPEG supports.
+Returns a list of fractional scaling factors that the JPEG decompressor supports.
| numscalingfactors | pointer to an integer variable that will receive the number of elements in the list |
| numScalingFactors | pointer to an integer variable that will receive the number of elements in the list |
*jpegSize should be set to the size of your
Load an uncompressed image from disk into memory.
+Load a packed-pixel image from disk into memory.
| filename | name of a file containing an uncompressed image in Windows BMP or PBMPLUS (PPM/PGM) format | ||||||||||||
| width | pointer to an integer variable that will receive the width (in pixels) of the uncompressed image | ||||||||||||
| align | row alignment of the image buffer to be returned (must be a power of 2.) For instance, setting this parameter to 4 will cause all rows in the image buffer to be padded to the nearest 32-bit boundary, and setting this parameter to 1 will cause all rows in the image buffer to be unpadded. | ||||||||||||
| height | pointer to an integer variable that will receive the height (in pixels) of the uncompressed image | ||||||||||||
| pixelFormat | pointer to an integer variable that specifies or will receive the pixel format of the uncompressed image buffer. The behavior of tjLoadImage() will vary depending on the value of *pixelFormat passed to the function:
filename | name of a file containing a packed-pixel image in Windows BMP or PBMPLUS (PPM/PGM) format | width | pointer to an integer variable that will receive the width (in pixels) of the packed-pixel image | align | row alignment of the packed-pixel buffer to be returned (must be a power of 2.) Setting this parameter to n will cause all rows in the buffer to be padded to the nearest multiple of n bytes (1 = unpadded.) | height | pointer to an integer variable that will receive the height (in pixels) of the packed-pixel image | pixelFormat | pointer to an integer variable that specifies or will receive the pixel format of the packed-pixel buffer. The behavior of tjLoadImage() will vary depending on the value of | *pixelFormat passed to the function:
flags | the bitwise OR of one or more of the flags. | |
*jpegSize should be set to the size of your
| componentID | ID number of the image plane (0 = Y, 1 = U/Cb, 2 = V/Cr) |
| width | width (in pixels) of the YUV image. NOTE: this is the width of the whole image, not the plane width. |
| stride | bytes per line in the image plane. Setting this to 0 is the equivalent of setting it to the plane width. |
| stride | bytes per row in the image plane. Setting this to 0 is the equivalent of setting it to the plane width. |
| height | height (in pixels) of the YUV image. NOTE: this is the height of the whole image, not the plane height. |
| subsamp | level of chrominance subsampling in the image (see Chrominance subsampling options.) |
*jpegSize should be set to the size of your
Save an uncompressed image from memory to disk.
+Save a packed-pixel image from memory to disk.
| filename | name of a file to which to save the uncompressed image. The image will be stored in Windows BMP or PBMPLUS (PPM/PGM) format, depending on the file extension. |
| buffer | pointer to an image buffer containing RGB, grayscale, or CMYK pixels to be saved |
| width | width (in pixels) of the uncompressed image |
| pitch | bytes per line in the image buffer. Setting this parameter to 0 is the equivalent of setting it to width * tjPixelSize[pixelFormat]. |
| height | height (in pixels) of the uncompressed image |
| pixelFormat | pixel format of the image buffer (see Pixel formats.) If this parameter is set to TJPF_GRAY, then the image will be stored in PGM or 8-bit (indexed color) BMP format. Otherwise, the image will be stored in PPM or 24-bit BMP format. If this parameter is set to TJPF_CMYK, then the CMYK pixels will be converted to RGB using a quick & dirty algorithm that is suitable only for testing (proper conversion between CMYK and other formats requires a color management system.) |
| filename | name of a file to which to save the packed-pixel image. The image will be stored in Windows BMP or PBMPLUS (PPM/PGM) format, depending on the file extension. |
| buffer | pointer to a buffer containing a packed-pixel RGB, grayscale, or CMYK image to be saved |
| width | width (in pixels) of the packed-pixel image |
| pitch | bytes per row in the packed-pixel image. Setting this parameter to 0 is the equivalent of setting it to width * tjPixelSize[pixelFormat]. |
| height | height (in pixels) of the packed-pixel image |
| pixelFormat | pixel format of the packed-pixel image (see Pixel formats.) If this parameter is set to TJPF_GRAY, then the image will be stored in PGM or 8-bit-per-pixel (indexed color) BMP format. Otherwise, the image will be stored in PPM or 24-bit-per-pixel BMP format. If this parameter is set to TJPF_CMYK, then the CMYK pixels will be converted to RGB using a quick & dirty algorithm that is suitable only for testing purposes. (Proper conversion between CMYK and other formats requires a color management system.) |
| flags | the bitwise OR of one or more of the flags. |
*jpegSize should be set to the size of your
| handle | a handle to a TurboJPEG transformer instance | ||||||
| jpegBuf | pointer to a buffer containing the JPEG source image to transform | ||||||
| jpegBuf | pointer to a byte buffer containing the JPEG source image to transform | ||||||
| jpegSize | size of the JPEG source image (in bytes) | ||||||
| n | the number of transformed JPEG images to generate | ||||||
| dstBufs | pointer 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:
dstBufs | pointer to an array of n byte 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 destination buffer to accommodate the size of the transformed JPEG image. Thus, you can choose to:
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.dstSizes | pointer 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.)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. | 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. |
| dstSizes | pointer 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 transformed JPEG image (in bytes.) | ||||||
| transforms | pointer to an array of n tjtransform structures, each of which specifies the transform parameters and/or cropping region for the corresponding transformed JPEG image. | ||||||
| flags | the bitwise OR of one or more of the flags |
dstSizes[i] should be set to the size of yo
Alpha offset (in bytes) for a given pixel format.
-This specifies the number of bytes that the Alpha component is offset from the start of the pixel. For instance, if a pixel of format TJ_BGRA is stored in char pixel[], then the alpha component will be pixel[tjAlphaOffset[TJ_BGRA]]. This will be -1 if the pixel format does not have an alpha component.
This specifies the number of bytes that the alpha component is offset from the start of the pixel. For instance, if a pixel of format TJPF_BGRA is stored in unsigned char pixel[], then the alpha component will be pixel[tjAlphaOffset[TJPF_BGRA]]. This will be -1 if the pixel format does not have an alpha component.
dstSizes[i] should be set to the size of yo
Blue offset (in bytes) for a given pixel format.
-This specifies the number of bytes that the Blue component is offset from the start of the pixel. For instance, if a pixel of format TJ_BGRX is stored in char pixel[], then the blue component will be pixel[tjBlueOffset[TJ_BGRX]]. This will be -1 if the pixel format does not have a blue component.
This specifies the number of bytes that the blue component is offset from the start of the pixel. For instance, if a pixel of format TJPF_BGRX is stored in unsigned char pixel[], then the blue component will be pixel[tjBlueOffset[TJPF_BGRX]]. This will be -1 if the pixel format does not have a blue component.
dstSizes[i] should be set to the size of yo
Green offset (in bytes) for a given pixel format.
-This specifies the number of bytes that the green component is offset from the start of the pixel. For instance, if a pixel of format TJ_BGRX is stored in char pixel[], then the green component will be pixel[tjGreenOffset[TJ_BGRX]]. This will be -1 if the pixel format does not have a green component.
This specifies the number of bytes that the green component is offset from the start of the pixel. For instance, if a pixel of format TJPF_BGRX is stored in unsigned char pixel[], then the green component will be pixel[tjGreenOffset[TJPF_BGRX]]. This will be -1 if the pixel format does not have a green component.
dstSizes[i] should be set to the size of yo
Red offset (in bytes) for a given pixel format.
-This specifies the number of bytes that the red component is offset from the start of the pixel. For instance, if a pixel of format TJ_BGRX is stored in char pixel[], then the red component will be pixel[tjRedOffset[TJ_BGRX]]. This will be -1 if the pixel format does not have a red component.
This specifies the number of bytes that the red component is offset from the start of the pixel. For instance, if a pixel of format TJPF_BGRX is stored in unsigned char pixel[], then the red component will be pixel[tjRedOffset[TJPF_BGRX]]. This will be -1 if the pixel format does not have a red component.
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.coeffs belongscoeffs belongs (Y, Cb, and Cr have, respectively, ID's of 0, 1, and 2 in typical JPEG images.)coeffs belongs. (Y, Cb, and Cr have, respectively, ID's of 0, 1, and 2 in typical JPEG images.)coeffs belongs. This is the same as the index of the transform in the transforms array that was passed to tjTransform().The bitwise OR of one of more of the transform options.
+The bitwise OR of one of more of the transform options.
= If testing YUV encoding/decoding, this specifies the number of"); - System.out.println(" bytes to which each row of each plane in the intermediate YUV image is"); - System.out.println(" padded (default = 1)"); + System.out.println(" bytes by which each row of each plane in the intermediate YUV image is"); + System.out.println(" evenly divisible (default = 1)"); System.out.println("-scale M/N = Scale down the width/height of the decompressed JPEG image by a"); System.out.print(" factor of M/N (M/N = "); for (i = 0; i < nsf; i++) { @@ -926,7 +927,7 @@ final class TJBench { } else usage(); } else if (argv[i].equalsIgnoreCase("-yuv")) { - System.out.println("Testing YUV planar encoding/decoding\n"); + System.out.println("Testing planar YUV encoding/decoding\n"); doYUV = true; } else if (argv[i].equalsIgnoreCase("-yuvpad") && i < argv.length - 1) { @@ -936,7 +937,7 @@ final class TJBench { temp = Integer.parseInt(argv[++i]); } catch (NumberFormatException e) {} if (temp >= 1) - yuvPad = temp; + yuvAlign = temp; } else if (argv[i].equalsIgnoreCase("-subsamp") && i < argv.length - 1) { i++; diff --git a/java/TJUnitTest.java b/java/TJUnitTest.java index b24a29a2..2f34c2d5 100644 --- a/java/TJUnitTest.java +++ b/java/TJUnitTest.java @@ -1,5 +1,5 @@ /* - * Copyright (C)2011-2018, 2022 D. R. Commander. All Rights Reserved. + * Copyright (C)2011-2018, 2022-2023 D. R. Commander. All Rights Reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are met: @@ -50,7 +50,7 @@ final class TJUnitTest { System.out.println("Options:"); System.out.println("-yuv = test YUV encoding/decoding support"); System.out.println("-noyuvpad = do not pad each line of each Y, U, and V plane to the nearest"); - System.out.println(" 4-byte boundary"); + System.out.println(" multiple of 4 bytes"); System.out.println("-lossless = test lossless JPEG compression/decompression"); System.out.println("-bi = test BufferedImage support\n"); System.exit(1); @@ -95,7 +95,7 @@ final class TJUnitTest { private static boolean doYUV = false; private static boolean lossless = false; private static int psv = 1; - private static int pad = 4; + private static int yuvAlign = 4; private static boolean bi = false; private static int exitStatus = 0; @@ -535,7 +535,7 @@ final class TJUnitTest { int hsf = TJ.getMCUWidth(subsamp) / 8, vsf = TJ.getMCUHeight(subsamp) / 8; int pw = pad(w, hsf), ph = pad(h, vsf); int cw = pw / hsf, ch = ph / vsf; - int ypitch = pad(pw, pad), uvpitch = pad(cw, pad); + int ypitch = pad(pw, yuvAlign), uvpitch = pad(cw, yuvAlign); int retval = 1; int correctsize = ypitch * ph + (subsamp == TJ.SAMP_GRAY ? 0 : uvpitch * ch * 2); @@ -671,7 +671,7 @@ final class TJUnitTest { if (doYUV) { System.out.format("%s %s -> YUV %s ... ", pfStrLong, buStrLong, SUBNAME_LONG[subsamp]); - YUVImage yuvImage = tjc.encodeYUV(pad, flags); + YUVImage yuvImage = tjc.encodeYUV(yuvAlign, flags); if (checkBufYUV(yuvImage.getBuf(), yuvImage.getSize(), w, h, subsamp, new TJScalingFactor(1, 1)) == 1) System.out.print("Passed.\n"); @@ -738,8 +738,8 @@ final class TJUnitTest { if (!sf.isOne()) System.out.format("%d/%d ... ", sf.getNum(), sf.getDenom()); else System.out.print("... "); - YUVImage yuvImage = tjd.decompressToYUV(scaledWidth, pad, scaledHeight, - flags); + YUVImage yuvImage = tjd.decompressToYUV(scaledWidth, yuvAlign, + scaledHeight, flags); if (checkBufYUV(yuvImage.getBuf(), yuvImage.getSize(), scaledWidth, scaledHeight, subsamp, sf) == 1) System.out.print("Passed.\n"); @@ -878,7 +878,7 @@ final class TJUnitTest { System.out.format("%04d x %04d\b\b\b\b\b\b\b\b\b\b\b", w, h); srcBuf = new byte[w * h * 4]; if (doYUV) - dstImage = new YUVImage(w, pad, h, subsamp); + dstImage = new YUVImage(w, yuvAlign, h, subsamp); else dstBuf = new byte[TJ.bufSize(w, h, subsamp)]; for (i = 0; i < w * h * 4; i++) { @@ -894,7 +894,7 @@ final class TJUnitTest { srcBuf = new byte[h * w * 4]; if (doYUV) - dstImage = new YUVImage(h, pad, w, subsamp); + dstImage = new YUVImage(h, yuvAlign, w, subsamp); else dstBuf = new byte[TJ.bufSize(h, w, subsamp)]; for (i = 0; i < h * w * 4; i++) { @@ -926,7 +926,7 @@ final class TJUnitTest { if (argv[i].equalsIgnoreCase("-yuv")) doYUV = true; else if (argv[i].equalsIgnoreCase("-noyuvpad")) - pad = 1; + yuvAlign = 1; else if (argv[i].equalsIgnoreCase("-lossless")) lossless = true; else if (argv[i].equalsIgnoreCase("-bi")) { diff --git a/java/doc/index-all.html b/java/doc/index-all.html index 54f5807f..1a06aadc 100644 --- a/java/doc/index-all.html +++ b/java/doc/index-all.html @@ -74,8 +74,9 @@
BufferedImage instance.BufferedImage
+ instance.BufferedImage
- instance containing the decompressed/decoded image.YUVImage instance.YUVImage instance.
YUVImage instance containing the decompressed image planes.YUVImage instance containing the decompressed image planes.
YUVImage instance containing the decompressed image.YUVImage
+ instance containing the decompressed image.
YUVImage instance.YUVImage instance.YUVImage instance containing the encoded image.YUVImage
+ instance containing the encoded image.YUVImage instance containing the encoded image planes.YUVImage instance containing the encoded image planes.OP_*)OP_*)TJTransformer.transform() from copying any extra markers (including EXIF
- and ICC profile data) from the source image to the output image.OPT_*)OPT_*)YUVImage instance.YUVImage instance.srcImage with the newly created
instance.srcImage with the newly created
instance.jpegImage with the newly created instance.jpegImage with the newly created instance.imageSize bytes stored in
- jpegImage with the newly created instance.imageSize bytes stored in jpegImage
+ with the newly created instance.yuvImage with the newly created
instance.jpegImage with the newly created instance.jpegImage with the newly created
+ instance.imageSize bytes stored in
+ source image of length imageSize bytes stored in
jpegImage with the newly created instance.TJDecompressor instances, each of
- which has a transformed JPEG image associated with it.TJDecompressor
+ instances, each of which has a transformed JPEG image associated with it.YUVImage instance backed by a unified image
- buffer, and allocate memory for the image buffer.YUVImage instance backed by a unified buffer,
+ and allocate memory for the buffer.YUVImage instance from an existing unified image
+YUVImage instance from an existing unified
buffer.static intERR_WARNING
-static intFLAG_ACCURATEDCT
-static intFLAG_BOTTOMUP
-static intFLAG_FASTDCT
-static intFLAG_FASTUPSAMPLE
static intFLAG_STOPONWARNING
static intbufSizeYUV(int width,
- int pad,
+ int align,
int height,
int subsamp)
-static TJScalingFactor[]getScalingFactors()
-CS_YCCK) and
- decompressing YCCK JPEG images into CMYK pixels.
+ packed-pixel CMYK images into YCCK JPEG images (see CS_YCCK) and
+ decompressing YCCK JPEG images into packed-pixel CMYK images.
public static final int CS_GRAY
public static final int FLAG_BOTTOMUP-
public static final int FLAG_FASTUPSAMPLE
public static final int FLAG_FASTDCT-
public static final int FLAG_ACCURATEDCT-
public static final int FLAG_STOPONWARNING
NOTE: due to the design of the TurboJPEG Java API, only certain methods
(specifically, TJDecompressor.decompress*() methods
- with a void return type) will complete and leave the output image in a
- fully recoverable state after a non-fatal error occurs.
public static final int ERR_WARNING-
NOTE: due to the design of the TurboJPEG Java API, only certain methods
(specifically, TJDecompressor.decompress*() methods
- with a void return type) will complete and leave the output image in a
- fully recoverable state after a non-fatal error occurs.
subsamp - the level of chrominance subsampling (one of
- SAMP_*)SAMP_*)
subsamp - the level of chrominance subsampling (one of
- SAMP_*)SAMP_*)
public static int getPixelSize(int pixelFormat)
pixelFormat - the pixel format (one of PF_*)pixelFormat - the pixel format (one of PF_*)TJ.PF_BGRX is stored in char pixel[],
then the red component will be
pixel[TJ.getRedOffset(TJ.PF_BGRX)].
-pixelFormat - the pixel format (one of PF_*)pixelFormat - the pixel format (one of PF_*)TJ.PF_BGRX is stored in char pixel[],
then the green component will be
pixel[TJ.getGreenOffset(TJ.PF_BGRX)].
-pixelFormat - the pixel format (one of PF_*)pixelFormat - the pixel format (one of PF_*)TJ.PF_BGRX is stored in char pixel[],
then the blue component will be
pixel[TJ.getBlueOffset(TJ.PF_BGRX)].
-pixelFormat - the pixel format (one of PF_*)pixelFormat - the pixel format (one of PF_*)TJ.PF_BGRA is stored in char pixel[],
then the alpha component will be
pixel[TJ.getAlphaOffset(TJ.PF_BGRA)].
-pixelFormat - the pixel format (one of PF_*)pixelFormat - the pixel format (one of PF_*)width - the width (in pixels) of the JPEG imageheight - the height (in pixels) of the JPEG imagejpegSubsamp - the level of chrominance subsampling to be used when
- generating the JPEG image (one of TJ.SAMP_*)TJ.SAMP_*)
public static int bufSizeYUV(int width,
- int pad,
+ int align,
int height,
int subsamp)
-width - the width (in pixels) of the YUV imagepad - 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.)height - the height (in pixels) of the YUV imagesubsamp - the level of chrominance subsampling used in the YUV
- image (one of TJ.SAMP_*)width - the width (in pixels) of the YUV imagealign - row alignment (in bytes) of the YUV image (must be a power of
+ 2.) Setting this parameter to n specifies that each row in each plane of
+ the YUV image will be padded to the nearest multiple of n bytes
+ (1 = unpadded.)height - the height (in pixels) of the YUV imagesubsamp - the level of chrominance subsampling used in the YUV
+ image (one of TJ.SAMP_*)componentID - ID number of the image plane (0 = Y, 1 = U/Cb,
2 = V/Cr)width - width (in pixels) of the YUV image. NOTE: this is the width
- of the whole image, not the plane width.stride - bytes per line in the image plane.height - height (in pixels) of the YUV image. NOTE: this is the
+ of the whole image, not the plane width.stride - bytes per row in the image plane.height - height (in pixels) of the YUV image. NOTE: this is the
height of the whole image, not the plane height.subsamp - the level of chrominance subsampling used in the YUV
- image (one of TJ.SAMP_*)TJ.SAMP_*)
+YUVImage for a description of plane width.
componentID - ID number of the image plane (0 = Y, 1 = U/Cb,
2 = V/Cr)width - width (in pixels) of the YUV imagesubsamp - the level of chrominance subsampling used in the YUV image
- (one of TJ.SAMP_*)TJ.SAMP_*)
YUVImage for a description of plane height.
componentID - ID number of the image plane (0 = Y, 1 = U/Cb,
2 = V/Cr)height - height (in pixels) of the YUV imagesubsamp - the level of chrominance subsampling used in the YUV image
- (one of TJ.SAMP_*)TJ.SAMP_*)
public static TJScalingFactor[] getScalingFactors()-
srcImage with the newly created
instance.srcImage with the newly created
instance.voidcompress(byte[] dstBuf,
int flags)
-byte[]compress(int flags)
-YUVImageencodeYUV(int[] strides,
int flags)
-YUVImage instance containing the encoded image planes.YUVImage instance containing the encoded image planes.YUVImageencodeYUV(int pad,
+encodeYUV(int align,
int flags)
-Encode the uncompressed source image associated with this compressor
- instance into a unified YUV planar image buffer and return a
- YUVImage instance containing the encoded image.
+Encode the packed-pixel source image associated with this compressor
+ instance into a unified planar YUV image and return a YUVImage
+ instance containing the encoded image.
voidencodeYUV(YUVImage dstImage,
int flags)
-YUVImage instance.YUVImage instance.voidsetSourceImage(YUVImage srcImage)
-srcImage with the newly created
instance.srcImage - see setSourceImage(byte[], int, int, int, int, int, int) for descriptionx - see setSourceImage(byte[], int, int, int, int, int, int) for descriptiony - see setSourceImage(byte[], int, int, int, int, int, int) for descriptionwidth - see setSourceImage(byte[], int, int, int, int, int, int) for descriptionpitch - see setSourceImage(byte[], int, int, int, int, int, int) for descriptionheight - see setSourceImage(byte[], int, int, int, int, int, int) for descriptionpixelFormat - pixel format of the source image (one of
@@ -338,7 +338,7 @@ implements java.io.Closeable
int width,
int height)
throws TJException
-srcImage with the newly created
instance.srcImage - see
@@ -373,19 +373,19 @@ implements java.io.Closeable
int height,
int pixelFormat)
throws TJException
-srcImage - image buffer containing RGB, grayscale, or CMYK pixels to
- be compressed or encoded. This buffer is not modified.x - x offset (in pixels) of the region in the source image from which
+srcImage - buffer containing a packed-pixel RGB, grayscale, or CMYK
+ source image to be compressed or encoded. This buffer is not modified.x - x offset (in pixels) of the region in the source image from which
the JPEG or YUV image should be compressed/encodedy - y offset (in pixels) of the region in the source image from which
the JPEG or YUV image should be compressed/encodedwidth - width (in pixels) of the region in the source image from
- which the JPEG or YUV image should be compressed/encodedpitch - bytes per line of the source image. Normally, this should be
- width * TJ.pixelSize(pixelFormat) if the source image is
- unpadded, but you can use this parameter to, for instance, specify that
- the scanlines in the source image are padded to a 4-byte boundary or to
- compress/encode a JPEG or YUV image from a region of a larger source
- image. You can also be clever and use this parameter to skip lines, etc.
- Setting this parameter to 0 is the equivalent of setting it to
+ which the JPEG or YUV image should be compressed/encodedpitch - bytes per row in the source image. Normally this should be
+ width * TJ.pixelSize(pixelFormat), if the source image is
+ unpadded. However, you can use this parameter to, for instance, specify
+ that the rows in the source image are padded to the nearest multiple of 4
+ bytes or to compress/encode a JPEG or YUV image from a region of a larger
+ source image. You can also be clever and use this parameter to skip rows,
+ etc. Setting this parameter to 0 is the equivalent of setting it to
width * TJ.pixelSize(pixelFormat).height - height (in pixels) of the region in the source image from
which the JPEG or YUV image should be compressed/encodedpixelFormat - pixel format of the source image (one of
TJ.PF_*)srcImage - a BufferedImage instance containing RGB or
- grayscale pixels to be compressed or encoded. This image is not modified.x - x offset (in pixels) of the region in the source image from which
+srcImage - a BufferedImage instance containing a
+ packed-pixel RGB or grayscale source image to be compressed or encoded.
+ This image is not modified.x - x offset (in pixels) of the region in the source image from which
the JPEG or YUV image should be compressed/encodedy - y offset (in pixels) of the region in the source image from which
the JPEG or YUV image should be compressed/encodedwidth - width (in pixels) of the region in the source image from
which the JPEG or YUV image should be compressed/encoded (0 = use the
@@ -427,10 +428,9 @@ implements java.io.Closeable
public void setSourceImage(YUVImage srcImage) throws TJException-
srcImage - YUV planar image to be compressed. This image is not
- modified.srcImage - planar YUV source image to be compressed. This image is
+ not modified.TJExceptionTJ.CS_YCbCr) or from CMYK to YCCK (see TJ.CS_YCCK) 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 to small changes in color.)
- This is called "chrominance subsampling".
+ image with little perceptible loss of image clarity. (The human eye is
+ more sensitive to small changes in brightness than to small changes in
+ color.) This is called "chrominance subsampling".
- NOTE: This method has no effect when compressing a JPEG image from a YUV
- planar source. In that case, the level of chrominance subsampling in
- the JPEG image is determined by the source. Furthermore, this method has
- no effect when encoding to a pre-allocated YUVImage instance. In
- that case, the level of chrominance subsampling is determined by the
- destination.
YUVImage instance. In that case, the level of chrominance
+ subsampling is determined by the destination image.newSubsamp - the level of chrominance subsampling to use in
subsequent compress/encode oeprations (one of
TJ.SAMP_*)public void compress(byte[] dstBuf,
int flags)
throws TJException
-dstBuf - buffer that will receive the JPEG image. Use
TJ.bufSize(int, int, int) to determine the maximum size for this buffer based on
the source image's width and height and the desired level of chrominance
@@ -509,8 +510,8 @@ implements java.io.Closeable
public byte[] compress(int flags)
throws TJException
-flags - the bitwise OR of one or more of
TJ.FLAG_*public void encodeYUV(YUVImage dstImage, int flags) throws TJException-
YUVImage instance. This method uses the accelerated color
- conversion routines in TurboJPEG's underlying codec but does not execute
- any of the other steps in the JPEG compression process. Encoding
- CMYK source images to YUV is not supported.dstImage - YUVImage instance that will receive the YUV planar
+YUVImage instance. This method performs color conversion (which
+ is accelerated in the libjpeg-turbo implementation) but does not execute
+ any of the other steps in the JPEG compression process. Encoding CMYK
+ source images into YUV images is not supported.dstImage - YUVImage instance that will receive the planar YUV
imageflags - the bitwise OR of one or more of
TJ.FLAG_*public YUVImage encodeYUV(int pad, +public YUVImage encodeYUV(int align, int flags) throws TJException-Encode the uncompressed source image associated with this compressor - instance into a unified YUV planar image buffer and return a --YUVImageinstance containing the encoded image. This method - uses the accelerated color conversion routines in TurboJPEG's underlying - codec but does not execute any of the other steps in the JPEG compression - process. Encoding CMYK source images to YUV is not supported.
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.)flags - the bitwise OR of one or more of
+YUVImage
+ instance containing the encoded image. This method performs color
+ conversion (which is accelerated in the libjpeg-turbo implementation) but
+ does not execute any of the other steps in the JPEG compression process.
+ Encoding CMYK source images into YUV images is not supported.align - row alignment (in bytes) of the YUV image (must be a power of
+ 2.) Setting this parameter to n will cause each row in each plane of the
+ YUV image to be padded to the nearest multiple of n bytes (1 = unpadded.)flags - the bitwise OR of one or more of
TJ.FLAG_*YUVImage instance containing the unified planar YUV
+ encoded imageTJExceptionpublic YUVImage encodeYUV(int[] strides, int flags) throws TJException-
YUVImage instance containing the encoded image planes. This
- method uses the accelerated color conversion routines in TurboJPEG's
- underlying codec but does not execute any of the other steps in the JPEG
- compression process. Encoding CMYK source images to YUV is not supported.YUVImage instance containing the encoded image planes. This
+ method performs color conversion (which is accelerated in the
+ libjpeg-turbo implementation) but does not execute any of the other steps
+ in the JPEG compression process. Encoding CMYK source images into YUV
+ images is not supported.strides - an array of integers, each specifying the number of bytes
- per line in the corresponding plane of the output image. Setting the
- stride for any plane to 0 is the same as setting it to the component width
- of the plane. If strides is null, then the strides for all
- planes will be set to their respective component widths. You can adjust
- the strides in order to add an arbitrary amount of line padding to each
- plane.flags - the bitwise OR of one or more of
+ per row in the corresponding plane of the YUV source image. Setting the
+ stride for any plane to 0 is the same as setting it to the plane width
+ (see YUVImage.) If strides is null, then the strides
+ for all planes will be set to their respective plane widths. You can
+ adjust the strides in order to add an arbitrary amount of row padding to
+ each plane.flags - the bitwise OR of one or more of
TJ.FLAG_*YUVImage instance containing the encoded image planesTJExceptionplaneRegion - rectangle containing the width and height of the
component plane to which coeffBuffer belongscomponentID - ID number of the component plane to which
- coeffBuffer belongs (Y, Cb, and Cr have, respectively, ID's
+ coeffBuffer belongs. (Y, Cb, and Cr have, respectively, ID's
of 0, 1, and 2 in typical JPEG images.)transformID - ID number of the transformed image to which
coeffBuffer belongs. This is the same as the index of the
transform in the transforms array that was passed to TJTransformer.transform().transform - a TJTransform instance that specifies the
diff --git a/java/doc/org/libjpegturbo/turbojpeg/TJDecompressor.html b/java/doc/org/libjpegturbo/turbojpeg/TJDecompressor.html
index c27a8abf..37c77670 100644
--- a/java/doc/org/libjpegturbo/turbojpeg/TJDecompressor.html
+++ b/java/doc/org/libjpegturbo/turbojpeg/TJDecompressor.html
@@ -184,20 +184,22 @@ implements java.io.Closeable
TJDecompressor(byte[] jpegImage)
jpegImage with the newly created instance.jpegImage with the newly created instance.
TJDecompressor(byte[] jpegImage,
int imageSize)
imageSize bytes stored in
- jpegImage with the newly created instance.imageSize bytes stored in jpegImage
+ with the newly created instance.
TJDecompressor(YUVImage yuvImage)
-yuvImage with the newly created
instance.voiddecompress(java.awt.image.BufferedImage dstImage,
int flags)
-BufferedImage instance.BufferedImage
+ instance.BufferedImage
- instance containing the decompressed/decoded image.YUVImage instance containing the decompressed image planes.YUVImage instance containing the decompressed image planes.
YUVImagedecompressToYUV(int desiredWidth,
- int pad,
+ int align,
int desiredHeight,
int flags)
YUVImage instance containing the decompressed image.YUVImage
+ instance containing the decompressed image.
decompressToYUV(YUVImage dstImage,
int flags)
YUVImage instance.YUVImage instance.
byte[]getJPEGBuf()
-voidsetSourceImage(YUVImage srcImage)
-public TJDecompressor(byte[] jpegImage)
throws TJException
jpegImage with the newly created instance.jpegImage - JPEG image buffer (size of the JPEG image is assumed to
- be the length of the array.) This buffer is not modified.jpegImage with the newly created instance.jpegImage - buffer containing a JPEG source image or tables-only
+ datastream. (The size of the JPEG image or datastream is assumed to be
+ the length of the array.) This buffer is not modified.TJExceptionimageSize bytes stored in
- jpegImage with the newly created instance.jpegImage - JPEG image buffer. This buffer is not modified.imageSize - size of the JPEG image (in bytes)imageSize bytes stored in jpegImage
+ with the newly created instance.jpegImage - buffer containing a JPEG source image or tables-only
+ datastream. This buffer is not modified.imageSize - size of the JPEG source image or tables-only datastream
+ (in bytes)TJExceptionpublic TJDecompressor(YUVImage yuvImage) throws TJException-
yuvImage with the newly created
instance.yuvImage - YUVImage instance containing a YUV planar
+yuvImage - YUVImage instance containing a planar YUV source
image to be decoded. This image is not modified.TJExceptionjpegImage - buffer containing a JPEG image or an "abbreviated table
- specification" (AKA "tables-only") datastream. This buffer is not
- modified.imageSize - size of the JPEG image (in bytes)jpegImage - buffer containing a JPEG source image or tables-only
+ datastream. This buffer is not modified.imageSize - size of the JPEG source image or tables-only datastream
+ (in bytes)TJExceptionpublic void setSourceImage(YUVImage srcImage)-
srcImage - YUVImage instance containing a YUV planar image to
- be decoded. This image is not modified.srcImage - YUVImage instance containing a planar YUV source
+ image to be decoded. This image is not modified.public byte[] getJPEGBuf()-
desiredWidth - desired width (in pixels) of the decompressed image.
- Setting this to 0 is the same as setting it to the width of the JPEG image
- (in other words, the width will not be considered when determining the
- scaled image size.)desiredHeight - desired height (in pixels) of the decompressed image.
+ Setting this to 0 is the same as setting it to the width of the JPEG
+ image. (In other words, the width will not be considered when determining
+ the scaled image size.)desiredHeight - desired height (in pixels) of the decompressed image.
Setting this to 0 is the same as setting it to the height of the JPEG
- image (in other words, the height will not be considered when determining
- the scaled image size.)desiredWidth - desired width (in pixels) of the decompressed image.
- Setting this to 0 is the same as setting it to the width of the JPEG image
- (in other words, the width will not be considered when determining the
- scaled image size.)desiredHeight - desired height (in pixels) of the decompressed image.
+ Setting this to 0 is the same as setting it to the width of the JPEG
+ image. (In other words, the width will not be considered when determining
+ the scaled image size.)desiredHeight - desired height (in pixels) of the decompressed image.
Setting this to 0 is the same as setting it to the height of the JPEG
- image (in other words, the height will not be considered when determining
- the scaled image size.)
- NOTE: The output image is fully recoverable if this method throws a
+ NOTE: The destination image is fully recoverable if this method throws a
non-fatal TJException (unless
TJ.FLAG_STOPONWARNING is specified.)
dstBuf - buffer that will receive the decompressed/decoded image.
- If the source image is a JPEG image, then this buffer should normally be
- pitch * scaledHeight bytes in size, where
- scaledHeight can be determined by calling
- scalingFactor.getScaled(jpegHeight)
- with one of the scaling factors returned from TJ.getScalingFactors() or by calling getScaledHeight(int, int). If the
- source image is a YUV image, then this buffer should normally be
- pitch * height bytes in size, where height is
- the height of the YUV image. However, the buffer may also be larger than
- the dimensions of the source image, in which case the x,
- y, and pitch parameters can be used to specify
- the region into which the source image should be decompressed/decoded.x - x offset (in pixels) of the region in the destination image into
+dstBuf - buffer that will receive the packed-pixel
+ decompressed/decoded image. If the source image is a JPEG image, then
+ this buffer should normally be pitch * scaledHeight bytes in
+ size, where scaledHeight can be determined by calling
+ scalingFactor.getScaled(jpegHeight)
+ with one of the scaling factors returned from TJ.getScalingFactors()
+ or by calling getScaledHeight(int, int). If the source image is a YUV
+ image, then this buffer should normally be pitch * height
+ bytes in size, where height is the height of the YUV image.
+ However, the buffer may also be larger than the dimensions of the source
+ image, in which case the x, y, and
+ pitch parameters can be used to specify the region into which
+ the source image should be decompressed/decoded.x - x offset (in pixels) of the region in the destination image into
which the source image should be decompressed/decodedy - y offset (in pixels) of the region in the destination image into
which the source image should be decompressed/decodeddesiredWidth - If the source image is a JPEG image, then this
specifies the desired width (in pixels) of the decompressed image (or
@@ -805,18 +815,18 @@ implements java.io.Closeable
than the source image dimensions, then TurboJPEG will use scaling in the
JPEG decompressor to generate the largest possible image that will fit
within the desired dimensions. Setting this to 0 is the same as setting
- it to the width of the JPEG image (in other words, the width will not be
+ it to the width of the JPEG image. (In other words, the width will not be
considered when determining the scaled image size.) This parameter is
- ignored if the source image is a YUV image.pitch - bytes per line of the destination image. Normally, this
- should be set to scaledWidth * TJ.pixelSize(pixelFormat) if
- the destination image is unpadded, but you can use this to, for instance,
- pad each line of the destination image to a 4-byte boundary or to
- decompress/decode the source image into a region of a larger image. NOTE:
- if the source image is a JPEG image, then scaledWidth can be
- determined by calling
- scalingFactor.getScaled(jpegWidth)
- or by calling getScaledWidth(int, int). If the source image is a
- YUV image, then scaledWidth is the width of the YUV image.
+ ignored if the source image is a YUV image.pitch - bytes per row in the destination image. Normally this should
+ be set to scaledWidth * TJ.pixelSize(pixelFormat), if the
+ destination image will be unpadded. However, you can use this to, for
+ instance, pad each row of the destination image to the nearest multiple of
+ 4 bytes or to decompress/decode the source image into a region of a larger
+ image. NOTE: if the source image is a JPEG image, then
+ scaledWidth can be determined by calling
+ scalingFactor.getScaled(jpegWidth)
+ or by calling getScaledWidth(int, int). If the source image is a YUV
+ image, then scaledWidth is the width of the YUV image.
Setting this parameter to 0 is the equivalent of setting it to
scaledWidth * TJ.pixelSize(pixelFormat).desiredHeight - If the source image is a JPEG image, then this
specifies the desired height (in pixels) of the decompressed image (or
@@ -824,8 +834,8 @@ implements java.io.Closeable
than the source image dimensions, then TurboJPEG will use scaling in the
JPEG decompressor to generate the largest possible image that will fit
within the desired dimensions. Setting this to 0 is the same as setting
- it to the height of the JPEG image (in other words, the height will not be
- considered when determining the scaled image size.) This parameter is
+ it to the height of the JPEG image. (In other words, the height will not
+ be considered when determining the scaled image size.) This parameter is
ignored if the source image is a YUV image.pixelFormat - pixel format of the decompressed/decoded image (one of
TJ.PF_*)flags - the bitwise OR of one or more of
TJ.FLAG_*desiredWidth - see
decompress(byte[], int, int, int, int, int, int, int)
for descriptionpitch - see
@@ -856,7 +867,7 @@ implements java.io.Closeable
for descriptionpixelFormat - pixel format of the decompressed image (one of
TJ.PF_*)flags - the bitwise OR of one or more of
TJ.FLAG_*TJExceptionYUVImage instance. This method performs JPEG decompression
- but leaves out the color conversion step, so a planar YUV image is
- generated instead of an RGB or grayscale image. This method cannot be
- used to decompress JPEG source images with the CMYK or YCCK colorspace.
+ instance into a planar YUV image and store it in the given
+ YUVImage instance. This method performs JPEG decompression but
+ leaves out the color conversion step, so a planar YUV image is generated
+ instead of a packed-pixel image. This method cannot be used to decompress
+ JPEG source images with the CMYK or YCCK colorspace.
- NOTE: The YUV planar output image is fully recoverable if this method
+ NOTE: The planar YUV destination image is fully recoverable if this method
throws a non-fatal TJException (unless
TJ.FLAG_STOPONWARNING is specified.)
dstImage - YUVImage instance that will receive the YUV planar
- image. The level of subsampling specified in this YUVImage
- instance must match that of the JPEG image, and the width and height
- specified in the YUVImage instance must match one of the
- scaled image sizes that TurboJPEG is capable of generating from the JPEG
- source image.flags - the bitwise OR of one or more of
+dstImage - YUVImage instance that will receive the planar YUV
+ decompressed image. The level of subsampling specified in this
+ YUVImage instance must match that of the JPEG image, and the width
+ and height specified in the YUVImage instance must match one of
+ the scaled image sizes that the decompressor is capable of generating from
+ the JPEG source image.flags - the bitwise OR of one or more of
TJ.FLAG_*TJExceptionYUVImage instance containing the decompressed image planes.
- This method performs JPEG decompression but leaves out the color
- conversion step, so a planar YUV image is generated instead of an RGB or
- grayscale image. This method cannot be used to decompress JPEG source
- images with the CMYK or YCCK colorspace.YUVImage instance containing the decompressed image planes. This
+ method performs JPEG decompression but leaves out the color conversion
+ step, so a planar YUV image is generated instead of a packed-pixel image.
+ This method cannot be used to decompress JPEG source images with the CMYK
+ or YCCK colorspace.desiredWidth - desired width (in pixels) of the YUV image. If the
desired image dimensions are different than the dimensions 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 dimensions. Setting this to 0 is the same as setting it to
- the width of the JPEG image (in other words, the width will not be
+ the width of the JPEG image. (In other words, the width will not be
considered when determining the scaled image size.)strides - an array of integers, each specifying the number of bytes
- per line in the corresponding plane of the output image. Setting the
- stride for any plane to 0 is the same as setting it to the scaled
- component width of the plane. If strides is NULL, then the
- strides for all planes will be set to their respective scaled component
- widths. You can adjust the strides in order to add an arbitrary amount of
- line padding to each plane.desiredHeight - desired height (in pixels) of the YUV image. If the
+ per row in the corresponding plane of the YUV image. Setting the stride
+ for any plane to 0 is the same as setting it to the scaled plane width
+ (see YUVImage.) If strides is null, then the strides
+ for all planes will be set to their respective scaled plane widths. You
+ can adjust the strides in order to add an arbitrary amount of row padding
+ to each plane.desiredHeight - desired height (in pixels) of the YUV image. If the
desired image dimensions are different than the dimensions 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 dimensions. Setting this to 0 is the same as setting it to
- the height of the JPEG image (in other words, the height will not be
+ the height of the JPEG image. (In other words, the height will not be
considered when determining the scaled image size.)flags - the bitwise OR of one or more of
TJ.FLAG_*YUVImage instance containing the decompressed image
+ planesTJExceptionpublic YUVImage decompressToYUV(int desiredWidth, - int pad, + int align, int desiredHeight, int flags) throws TJException
YUVImage instance containing the decompressed image. This
- method performs JPEG decompression but leaves out the color conversion
- step, so a planar YUV image is generated instead of an RGB or grayscale
- image. This method cannot be used to decompress JPEG source images with
- the CMYK or YCCK colorspace.YUVImage
+ instance containing the decompressed image. This method performs JPEG
+ decompression but leaves out the color conversion step, so a planar YUV
+ image is generated instead of a packed-pixel image. This method cannot be
+ used to decompress JPEG source images with the CMYK or YCCK colorspace.
desiredWidth - desired width (in pixels) of the YUV image. If the
desired image dimensions are different than the dimensions 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 dimensions. Setting this to 0 is the same as setting it to
- the width of the JPEG image (in other words, the width will not be
- considered when determining the scaled image size.)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.)desiredHeight - desired height (in pixels) of the YUV image. If the
+ the width of the JPEG image. (In other words, the width will not be
+ considered when determining the scaled image size.)align - row alignment (in bytes) of the YUV image (must be a power of
+ 2.) Setting this parameter to n will cause each row in each plane of the
+ YUV image to be padded to the nearest multiple of n bytes (1 = unpadded.)desiredHeight - desired height (in pixels) of the YUV image. If the
desired image dimensions are different than the dimensions 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 dimensions. Setting this to 0 is the same as setting it to
- the height of the JPEG image (in other words, the height will not be
+ the height of the JPEG image. (In other words, the height will not be
considered when determining the scaled image size.)flags - the bitwise OR of one or more of
TJ.FLAG_*YUVImage instance containing the unified planar YUV
+ decompressed imageTJException
- NOTE: The output image is fully recoverable if this method throws a
+ NOTE: The destination image is fully recoverable if this method throws a
non-fatal TJException (unless
TJ.FLAG_STOPONWARNING is specified.)
dstBuf - buffer that will receive the decompressed/decoded image.
- If the source image is a JPEG image, then this buffer should normally be
- stride * scaledHeight pixels in size, where
- scaledHeight can be determined by calling
- scalingFactor.getScaled(jpegHeight)
- with one of the scaling factors returned from TJ.getScalingFactors() or by calling getScaledHeight(int, int). If the
- source image is a YUV image, then this buffer should normally be
- stride * height pixels in size, where height is
- the height of the YUV image. However, the buffer may also be larger than
- the dimensions of the JPEG image, in which case the x,
- y, and stride parameters can be used to specify
- the region into which the source image should be decompressed.x - x offset (in pixels) of the region in the destination image into
+dstBuf - buffer that will receive the packed-pixel
+ decompressed/decoded image. If the source image is a JPEG image, then
+ this buffer should normally be stride * scaledHeight pixels
+ in size, where scaledHeight can be determined by calling
+ scalingFactor.getScaled(jpegHeight)
+ with one of the scaling factors returned from TJ.getScalingFactors()
+ or by calling getScaledHeight(int, int). If the source image is a YUV
+ image, then this buffer should normally be stride * height
+ pixels in size, where height is the height of the YUV image.
+ However, the buffer may also be larger than the dimensions of the JPEG
+ image, in which case the x, y, and
+ stride parameters can be used to specify the region into
+ which the source image should be decompressed.x - x offset (in pixels) of the region in the destination image into
which the source image should be decompressed/decodedy - y offset (in pixels) of the region in the destination image into
which the source image should be decompressed/decodeddesiredWidth - If the source image is a JPEG image, then this
specifies the desired width (in pixels) of the decompressed image (or
@@ -1014,16 +1027,16 @@ implements java.io.Closeable
than the source image dimensions, then TurboJPEG will use scaling in the
JPEG decompressor to generate the largest possible image that will fit
within the desired dimensions. Setting this to 0 is the same as setting
- it to the width of the JPEG image (in other words, the width will not be
+ it to the width of the JPEG image. (In other words, the width will not be
considered when determining the scaled image size.) This parameter is
- ignored if the source image is a YUV image.stride - pixels per line of the destination image. Normally, this
+ ignored if the source image is a YUV image.stride - pixels per row in the destination image. Normally this
should be set to scaledWidth, but you can use this to, for
instance, decompress the JPEG image into a region of a larger image.
NOTE: if the source image is a JPEG image, then scaledWidth
- can be determined by calling
- scalingFactor.getScaled(jpegWidth)
- or by calling getScaledWidth(int, int). If the source image is a
- YUV image, then scaledWidth is the width of the YUV image.
+ can be determined by calling
+ scalingFactor.getScaled(jpegWidth)
+ or by calling getScaledWidth(int, int). If the source image is a YUV
+ image, then scaledWidth is the width of the YUV image.
Setting this parameter to 0 is the equivalent of setting it to
scaledWidth.desiredHeight - If the source image is a JPEG image, then this
specifies the desired height (in pixels) of the decompressed image (or
@@ -1031,8 +1044,8 @@ implements java.io.Closeable
than the source image dimensions, then TurboJPEG will use scaling in the
JPEG decompressor to generate the largest possible image that will fit
within the desired dimensions. Setting this to 0 is the same as setting
- it to the height of the JPEG image (in other words, the height will not be
- considered when determining the scaled image size.) This parameter is
+ it to the height of the JPEG image. (In other words, the height will not
+ be considered when determining the scaled image size.) This parameter is
ignored if the source image is a YUV image.pixelFormat - pixel format of the decompressed image (one of
TJ.PF_*)flags - the bitwise OR of one or more of
TJ.FLAG_*public void decompress(java.awt.image.BufferedImage dstImage,
int flags)
throws TJException
-BufferedImage instance.
+BufferedImage
+ instance.
- NOTE: The output image is fully recoverable if this method throws a
+ NOTE: The destination image is fully recoverable if this method throws a
non-fatal TJException (unless
TJ.FLAG_STOPONWARNING is specified.)
dstImage - a BufferedImage instance that will receive
- the decompressed/decoded image. If the source image is a JPEG image, then
- the width and height of the BufferedImage instance must match
- one of the scaled image sizes that TurboJPEG is capable of generating from
- the JPEG image. If the source image is a YUV image, then the width and
- height of the BufferedImage instance must match the width and
- height of the YUV image.flags - the bitwise OR of one or more of
+ the packed-pixel decompressed/decoded image. If the source image is a
+ JPEG image, then the width and height of the BufferedImage
+ instance must match one of the scaled image sizes that the decompressor is
+ capable of generating from the JPEG image. If the source image is a YUV
+ image, then the width and height of the BufferedImage
+ instance must match the width and height of the YUV image.flags - the bitwise OR of one or more of
TJ.FLAG_*TJExceptionBufferedImage
- instance containing the decompressed/decoded image.desiredWidth - see
decompress(byte[], int, int, int, int, int, int, int) for
descriptiondesiredHeight - see
@@ -1090,7 +1104,7 @@ implements java.io.Closeable
instance that will be created (for instance,
BufferedImage.TYPE_INT_RGB)flags - the bitwise OR of one or more of
TJ.FLAG_*BufferedImage instance containing the
+BufferedImage instance containing the packed-pixel
decompressed/decoded image.TJExceptionintop
-OP_*)OP_*)static intOPT_ARITHMETIC
-static intOPT_COPYNONE
TJTransformer.transform() from copying any extra markers (including EXIF
- and ICC profile data) from the source image to the output image.static intOPT_GRAY
-static intOPT_PROGRESSIVE
-intoptions
-OPT_*)OPT_*)TJ.getMCUWidth(int)
and TJ.getMCUHeight(int)), then there will be partial MCU blocks on the
- right and/or bottom edges. It is not possible to move these partial MCU
+ right and/or bottom edges. It is not possible to move these partial MCU
blocks to the top or left of the image, so any transform that would
require that is "imperfect." If this option is not specified, then any
partial MCU blocks that cannot be transformed will be left in place, which
@@ -554,8 +555,8 @@ extends java.awt.Rectangle
public static final int OPT_GRAY-
public static final int OPT_PROGRESSIVE-
public static final int OPT_COPYNONE
TJTransformer.transform() from copying any extra markers (including EXIF
- and ICC profile data) from the source image to the output image.public static final int OPT_ARITHMETIC-
public int op-
OP_*)OP_*)public int options-
OPT_*)OPT_*)x).h - the height of the cropping region. Setting this to 0 is the
equivalent of setting it to (height of the source JPEG image -
- y).op - one of the transform operations (OP_*)options - the bitwise OR of one or more of the transform options
- (OPT_*)cf - an instance of an object that implements the TJCustomFilter interface, or null if no custom filter is neededy).op - one of the transform operations (OP_*)options - the bitwise OR of one or more of the transform options
+ (OPT_*)cf - an instance of an object that implements the TJCustomFilter interface, or null if no custom filter is neededr - a Rectangle instance that specifies the cropping
region. See TJTransform(int, int, int, int, int, int, TJCustomFilter) for more
- detail.op - one of the transform operations (OP_*)options - the bitwise OR of one or more of the transform options
- (OPT_*)cf - an instance of an object that implements the TJCustomFilter interface, or null if no custom filter is neededop - one of the transform operations (OP_*)options - the bitwise OR of one or more of the transform options
+ (OPT_*)cf - an instance of an object that implements the TJCustomFilter interface, or null if no custom filter is neededTJTransformer(byte[] jpegImage)
jpegImage with the newly created instance.jpegImage with the newly created
+ instance.
TJTransformer(byte[] jpegImage,
int imageSize)
imageSize bytes stored in
+ source image of length imageSize bytes stored in
jpegImage with the newly created instance.int[]
getTransformedSizes()
transform(byte[][] dstBufs,
TJTransform[] transforms,
int flags)
-TJDecompressor[]transform(TJTransform[] transforms,
int flags)
-TJDecompressor instances, each of
- which has a transformed JPEG image associated with it.TJDecompressor
+ instances, each of which has a transformed JPEG image associated with it.jpegImage with the newly created instance.jpegImage - JPEG image buffer (size of the JPEG image is assumed to
- be the length of the array.) This buffer is not modified.jpegImage with the newly created
+ instance.jpegImage - buffer containing the JPEG source image to transform.
+ (The size of the JPEG image is assumed to be the length of the array.)
+ This buffer is not modified.TJExceptionimageSize bytes stored in
+ source image of length imageSize bytes stored in
jpegImage with the newly created instance.jpegImage - JPEG image buffer. This buffer is not modified.imageSize - size of the JPEG image (in bytes)jpegImage - buffer containing the JPEG source image to transform.
+ This buffer is not modified.imageSize - size of the JPEG source image (in bytes)TJExceptiondstBufs - an array of image buffers. dstbufs[i] will
- receive a JPEG image that has been transformed using the parameters in
- transforms[i]. Use TJ.bufSize(int, int, int) to determine the
- maximum size for each buffer based on the transformed or cropped width and
- height and the level of subsampling used in the source image.transforms - an array of TJTransform instances, each of
+dstBufs - an array of JPEG destination buffers.
+ dstbufs[i] will receive a JPEG image that has been
+ transformed using the parameters in transforms[i]. Use
+ TJ.bufSize(int, int, int) to determine the maximum size for each buffer based on
+ the transformed or cropped width and height and the level of subsampling
+ used in the source image.transforms - an array of TJTransform instances, each of
which specifies the transform parameters and/or cropping region for the
- corresponding transformed output imageflags - the bitwise OR of one or more of
+ corresponding transformed JPEG imageflags - the bitwise OR of one or more of
TJ.FLAG_*TJExceptionTJDecompressor instances, each of
- which has a transformed JPEG image associated with it.TJDecompressor
+ instances, each of which has a transformed JPEG image associated with it.transforms - an array of TJTransform instances, each of
which specifies the transform parameters and/or cropping region for the
- corresponding transformed output imageflags - the bitwise OR of one or more of
+ corresponding transformed JPEG imageflags - the bitwise OR of one or more of
TJ.FLAG_*TJDecompressor instances, each of
which has a transformed JPEG image associated with it.public int[] getTransformedSizes()
public class YUVImage
extends java.lang.Object
-YUVImage instance
@@ -106,30 +106,32 @@ extends java.lang.Object
operations and as the source image for compress-from-YUV and YUV decode
operations.
- Technically, the JPEG format uses the YCbCr colorspace (which technically is - not a "colorspace" but rather a "color transform"), but per the convention - of the digital video community, the TurboJPEG API uses "YUV" to refer to an - image format consisting of Y, Cb, and Cr image planes. + Technically, the JPEG format uses the YCbCr colorspace (which is technically + not a colorspace but a color transform), but per the convention of the + digital video community, the TurboJPEG API uses "YUV" to refer to an image + format consisting of Y, Cb, and Cr image planes.
Each plane is simply a 2D array of bytes, each byte representing the value of one of the components (Y, Cb, or Cr) at a particular location in the image. The width and height of each plane are determined by the image width, height, and level of chrominance subsampling. The luminance plane width is the image width padded to the nearest multiple of the horizontal - subsampling factor (2 in the case of 4:2:0 and 4:2:2, 4 in the case of - 4:1:1, 1 in the case of 4:4:4 or grayscale.) Similarly, the luminance plane - height is the image height padded to the nearest multiple of the vertical - subsampling factor (2 in the case of 4:2:0 or 4:4:0, 1 in the case of 4:4:4 - or grayscale.) The chrominance plane width is equal to the luminance plane - width divided by the horizontal subsampling factor, and the chrominance - plane height is equal to the luminance plane height divided by the vertical - subsampling factor. + subsampling factor (1 in the case of 4:4:4, grayscale, or 4:4:0; 2 in the + case of 4:2:2 or 4:2:0; 4 in the case of 4:1:1.) Similarly, the luminance + plane height is the image height padded to the nearest multiple of the + vertical subsampling factor (1 in the case of 4:4:4, 4:2:2, grayscale, or + 4:1:1; 2 in the case of 4:2:0 or 4:4:0.) This is irrespective of any + additional padding that may be specified as an argument to the various + YUVImage methods. The chrominance plane width is equal to the luminance + plane width divided by the horizontal subsampling factor, and the + chrominance plane height is equal to the luminance plane height divided by + the vertical subsampling factor.
For example, if the source image is 35 x 35 pixels and 4:2:2 subsampling is used, then the luminance plane would be 36 x 35 bytes, and each of the - chrominance planes would be 18 x 35 bytes. If you specify a line padding of - 4 bytes on top of this, then the luminance plane would be 36 x 35 bytes, and - each of the chrominance planes would be 20 x 35 bytes.
protected intyuvHeight yuvAlign protected int[]yuvOffsets protected intyuvHeight protected intyuvPad protected int[]yuvOffsets protected byte[][]YUVImage(byte[] yuvImage,
int width,
- int pad,
+ int align,
int height,
int subsamp)
-YUVImage instance from an existing unified image
+YUVImage instance from an existing unified
buffer.YUVImage(int width,
- int pad,
+ int align,
int height,
int subsamp)
-YUVImage instance backed by a unified image
- buffer, and allocate memory for the image buffer.YUVImage instance backed by a unified buffer,
+ and allocate memory for the buffer.byte[]getBuf()
-intgetPad()
-intgetSize()
-int[]getStrides()
-voidsetBuf(byte[] yuvImage,
int width,
- int pad,
+ int align,
int height,
int subsamp)
-YUVImage instance.YUVImage instance.protected int[] yuvStrides
protected int yuvPad+
protected int yuvAlign
YUVImage instance backed by separate image
planes, and allocate memory for the image planes.width - width (in pixels) of the YUV imagestrides - an array of integers, each specifying the number of bytes
- per line in the corresponding plane of the YUV image. Setting the stride
+ per row in the corresponding plane of the YUV image. Setting the stride
for any plane to 0 is the same as setting it to the plane width (see
above.) If strides is null, then the
strides for all planes will be set to their respective plane widths. When
@@ -458,13 +460,15 @@ extends java.lang.Object
public YUVImage(int width,
- int pad,
+ int align,
int height,
int subsamp)
-YUVImage instance backed by a unified image
- buffer, and allocate memory for the image buffer.width - width (in pixels) of the YUV imagepad - Each line of each plane in the YUV image buffer will be padded
- to this number of bytes (must be a power of 2.)height - height (in pixels) of the YUV imagesubsamp - the level of chrominance subsampling to be used in the YUV
+YUVImage instance backed by a unified buffer,
+ and allocate memory for the buffer.width - width (in pixels) of the YUV imagealign - row alignment (in bytes) of the YUV image (must be a power of
+ 2.) Setting this parameter to n specifies that each row in each plane of
+ the YUV image will be padded to the nearest multiple of n bytes
+ (1 = unpadded.)height - height (in pixels) of the YUV imagesubsamp - the level of chrominance subsampling to be used in the YUV
image (one of TJ.SAMP_*)planes - an array of buffers representing the Y, U (Cb), and V (Cr)
image planes (or just the Y plane, if the image is grayscale.) These
planes can be contiguous or non-contiguous in memory. Plane
- i should be at least offsets[i] +
- TJ.planeSizeYUV(i, width, strides[i], height, subsamp)
+ i should be at least offsets[i] +
+ TJ.planeSizeYUV(i, width, strides[i], height, subsamp)
bytes in size.offsets - If this YUVImage instance represents a
subregion of a larger image, then offsets[i] specifies the
offset (in bytes) of the subregion within plane i of the
larger image. Setting this to null is the same as setting the offsets for
all planes to 0.width - width (in pixels) of the new YUV image (or subregion)strides - an array of integers, each specifying the number of bytes
- per line in the corresponding plane of the YUV image. Setting the stride
+ per row in the corresponding plane of the YUV image. Setting the stride
for any plane to 0 is the same as setting it to the plane width (see
above.) If strides is null, then the
strides for all planes will be set to their respective plane widths. You
- can adjust the strides in order to add an arbitrary amount of line padding
+ can adjust the strides in order to add an arbitrary amount of row padding
to each plane or to specify that this YUVImage instance is a
subregion of a larger image (in which case, strides[i] should
be set to the plane width of plane i in the larger image.)height - height (in pixels) of the new YUV image (or subregion)subsamp - the level of chrominance subsampling used in the YUV
@@ -511,18 +515,19 @@ extends java.lang.Object
public YUVImage(byte[] yuvImage,
int width,
- int pad,
+ int align,
int height,
int subsamp)
-YUVImage instance from an existing unified image
+YUVImage instance from an existing unified
buffer.yuvImage - image buffer that contains or will contain YUV planar
- image data. Use TJ.bufSizeYUV(int, int, int, int) to determine the minimum size for
- this buffer. The Y, U (Cb), and V (Cr) image planes are stored
- sequentially in the buffer (see above for a description
- of the image format.)width - width (in pixels) of the YUV imagepad - the line padding used in the YUV image buffer. For
- instance, if each line in each plane of the buffer is padded to the
- nearest multiple of 4 bytes, then pad should be set to 4.height - height (in pixels) of the YUV imagesubsamp - the level of chrominance subsampling used in the YUV
+yuvImage - buffer that contains or will receive a unified planar YUV
+ image. Use TJ.bufSizeYUV(int, int, int, int) to determine the minimum size for this
+ buffer. The Y, U (Cb), and V (Cr) image planes are stored sequentially in
+ the buffer. (See above for a description of the image
+ format.)width - width (in pixels) of the YUV imagealign - row alignment (in bytes) of the YUV image (must be a power of
+ 2.) Setting this parameter to n specifies that each row in each plane of
+ the YUV image will be padded to the nearest multiple of n bytes
+ (1 = unpadded.)height - height (in pixels) of the YUV imagesubsamp - the level of chrominance subsampling used in the YUV
image (one of TJ.SAMP_*)planes - an array of buffers representing the Y, U (Cb), and V (Cr)
image planes (or just the Y plane, if the image is grayscale.) These
planes can be contiguous or non-contiguous in memory. Plane
- i should be at least offsets[i] +
- TJ.planeSizeYUV(i, width, strides[i], height, subsamp)
+ i should be at least offsets[i] +
+ TJ.planeSizeYUV(i, width, strides[i], height, subsamp)
bytes in size.offsets - If this YUVImage instance represents a
subregion of a larger image, then offsets[i] specifies the
offset (in bytes) of the subregion within plane i of the
larger image. Setting this to null is the same as setting the offsets for
all planes to 0.width - width (in pixels) of the YUV image (or subregion)strides - an array of integers, each specifying the number of bytes
- per line in the corresponding plane of the YUV image. Setting the stride
+ per row in the corresponding plane of the YUV image. Setting the stride
for any plane to 0 is the same as setting it to the plane width (see
above.) If strides is null, then the
strides for all planes will be set to their respective plane widths. You
- can adjust the strides in order to add an arbitrary amount of line padding
- to each plane or to specify that this YUVImage image is a
+ can adjust the strides in order to add an arbitrary amount of row padding
+ to each plane or to specify that this YUVImage instance is a
subregion of a larger image (in which case, strides[i] should
be set to the plane width of plane i in the larger image.)height - height (in pixels) of the YUV image (or subregion)subsamp - the level of chrominance subsampling used in the YUV
image (one of TJ.SAMP_*)public void setBuf(byte[] yuvImage,
int width,
- int pad,
+ int align,
int height,
int subsamp)
-YUVImage instance.yuvImage - image buffer that contains or will contain YUV planar
- image data. Use TJ.bufSizeYUV(int, int, int, int) to determine the minimum size for
- this buffer. The Y, U (Cb), and V (Cr) image planes are stored
- sequentially in the buffer (see above for a description
- of the image format.)width - width (in pixels) of the YUV imagepad - the line padding used in the YUV image buffer. For
- instance, if each line in each plane of the buffer is padded to the
- nearest multiple of 4 bytes, then pad should be set to 4.height - height (in pixels) of the YUV imagesubsamp - the level of chrominance subsampling used in the YUV
+YUVImage instance.yuvImage - buffer that contains or will receive a unified planar YUV
+ image. Use TJ.bufSizeYUV(int, int, int, int) to determine the minimum size for this
+ buffer. The Y, U (Cb), and V (Cr) image planes are stored sequentially in
+ the buffer. (See above for a description of the image
+ format.)width - width (in pixels) of the YUV imagealign - row alignment (in bytes) of the YUV image (must be a power of
+ 2.) Setting this parameter to n specifies that each row in each plane of
+ the YUV image will be padded to the nearest multiple of n bytes
+ (1 = unpadded.)height - height (in pixels) of the YUV imagesubsamp - the level of chrominance subsampling used in the YUV
image (one of TJ.SAMP_*)public int getPad()-
public int[] getStrides()-
public byte[] getBuf()-
public int getSize()-
int op-
OP_*)OP_*)int options-
OPT_*)OPT_*)SAMP_*)
+ * {@link #SAMP_444 SAMP_*})
*
* @return the MCU block width for the given level of chrominance
* subsampling.
@@ -105,7 +105,7 @@ public final class TJ {
* subsampling.
*
* @param subsamp the level of chrominance subsampling (one of
- * SAMP_*)
+ * {@link #SAMP_444 SAMP_*})
*
* @return the MCU block height for the given level of chrominance
* subsampling.
@@ -205,8 +205,8 @@ public final class TJ {
* vice versa, but the mapping is typically not 1:1 or reversible, nor can it
* be defined with a simple formula. Thus, such a conversion is out of scope
* for a codec library. However, the TurboJPEG API allows for compressing
- * CMYK pixels into a YCCK JPEG image (see {@link #CS_YCCK}) and
- * decompressing YCCK JPEG images into CMYK pixels.
+ * packed-pixel CMYK images into YCCK JPEG images (see {@link #CS_YCCK}) and
+ * decompressing YCCK JPEG images into packed-pixel CMYK images.
*/
public static final int PF_CMYK = 11;
@@ -214,7 +214,7 @@ public final class TJ {
/**
* Returns the pixel size (in bytes) for the given pixel format.
*
- * @param pixelFormat the pixel format (one of PF_*)
+ * @param pixelFormat the pixel format (one of {@link #PF_RGB PF_*})
*
* @return the pixel size (in bytes) for the given pixel format.
*/
@@ -235,7 +235,7 @@ public final class TJ {
* then the red component will be
* pixel[TJ.getRedOffset(TJ.PF_BGRX)].
*
- * @param pixelFormat the pixel format (one of PF_*)
+ * @param pixelFormat the pixel format (one of {@link #PF_RGB PF_*})
*
* @return the red offset for the given pixel format, or -1 if the pixel
* format does not have a red component.
@@ -257,7 +257,7 @@ public final class TJ {
* then the green component will be
* pixel[TJ.getGreenOffset(TJ.PF_BGRX)].
*
- * @param pixelFormat the pixel format (one of PF_*)
+ * @param pixelFormat the pixel format (one of {@link #PF_RGB PF_*})
*
* @return the green offset for the given pixel format, or -1 if the pixel
* format does not have a green component.
@@ -279,7 +279,7 @@ public final class TJ {
* then the blue component will be
* pixel[TJ.getBlueOffset(TJ.PF_BGRX)].
*
- * @param pixelFormat the pixel format (one of PF_*)
+ * @param pixelFormat the pixel format (one of {@link #PF_RGB PF_*})
*
* @return the blue offset for the given pixel format, or -1 if the pixel
* format does not have a blue component.
@@ -301,7 +301,7 @@ public final class TJ {
* then the alpha component will be
* pixel[TJ.getAlphaOffset(TJ.PF_BGRA)].
*
- * @param pixelFormat the pixel format (one of PF_*)
+ * @param pixelFormat the pixel format (one of {@link #PF_RGB PF_*})
*
* @return the alpha offset for the given pixel format, or -1 if the pixel
* format does not have a alpha component.
@@ -324,8 +324,9 @@ public final class TJ {
* RGB colorspace. When compressing the JPEG image, the R, G, and B
* components in the source image are reordered into image planes, but no
* colorspace conversion or subsampling is performed. RGB JPEG images can be
- * decompressed to any of the extended RGB pixel formats or grayscale, but
- * they cannot be decompressed to YUV images.
+ * decompressed to packed-pixel images with any of the extended RGB or
+ * grayscale pixel formats, but they cannot be decompressed to planar YUV
+ * images.
*/
public static final int CS_RGB = 0;
/**
@@ -339,26 +340,28 @@ public final class TJ {
* transformation allowed the same signal to drive both black & white and
* color televisions, but JPEG images use YCbCr primarily because it allows
* the color data to be optionally subsampled for the purposes of reducing
- * bandwidth or disk space. YCbCr is the most common JPEG colorspace, and
- * YCbCr JPEG images can be compressed from and decompressed to any of the
- * extended RGB pixel formats or grayscale, or they can be decompressed to
- * YUV planar images.
+ * network or disk usage. YCbCr is the most common JPEG colorspace, and
+ * YCbCr JPEG images can be compressed from and decompressed to packed-pixel
+ * images with any of the extended RGB or grayscale pixel formats. YCbCr
+ * JPEG images can also be compressed from and decompressed to planar YUV
+ * images.
*/
@SuppressWarnings("checkstyle:ConstantName")
public static final int CS_YCbCr = 1;
/**
* Grayscale colorspace. The JPEG image retains only the luminance data (Y
* component), and any color data from the source image is discarded.
- * Grayscale JPEG images can be compressed from and decompressed to any of
- * the extended RGB pixel formats or grayscale, or they can be decompressed
- * to YUV planar images.
+ * Grayscale JPEG images can be compressed from and decompressed to
+ * packed-pixel images with any of the extended RGB or grayscale pixel
+ * formats, or they can be compressed from and decompressed to planar YUV
+ * images.
*/
public static final int CS_GRAY = 2;
/**
* CMYK colorspace. When compressing the JPEG image, the C, M, Y, and K
* components in the source image are reordered into image planes, but no
* colorspace conversion or subsampling is performed. CMYK JPEG images can
- * only be decompressed to CMYK pixels.
+ * only be decompressed to packed-pixel images with the CMYK pixel format.
*/
public static final int CS_CMYK = 3;
/**
@@ -368,54 +371,52 @@ public final class TJ {
* reversibly transformed into YCCK, and as with YCbCr, the chrominance
* components in the YCCK pixels can be subsampled without incurring major
* perceptual loss. YCCK JPEG images can only be compressed from and
- * decompressed to CMYK pixels.
+ * decompressed to packed-pixel images with the CMYK pixel format.
*/
public static final int CS_YCCK = 4;
/**
- * The uncompressed source/destination image is stored in bottom-up (Windows,
- * OpenGL) order, not top-down (X11) order.
+ * Rows in the packed-pixel source/destination image are stored in bottom-up
+ * (Windows, OpenGL) order rather than in top-down (X11) order.
*/
public static final int FLAG_BOTTOMUP = (1 << 1);
/**
* 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.
+ * subsampling, use the fastest chrominance upsampling algorithm available.
+ * 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.
*/
public static final int FLAG_FASTUPSAMPLE = (1 << 8);
/**
- * Use the fastest DCT/IDCT algorithm available in the underlying codec. The
- * default if this flag is not specified is implementation-specific. For
- * example, the implementation of TurboJPEG for libjpeg[-turbo] uses the fast
+ * Use the fastest DCT/IDCT algorithm available. The default if this flag is
+ * not specified is implementation-specific. For example, the implementation
+ * of the TurboJPEG API in libjpeg-turbo uses the fast algorithm by default
+ * when compressing, because this has been shown to have only a very slight
+ * effect on accuracy, but it uses the accurate algorithm when decompressing,
+ * because this has been shown to have a larger effect.
+ */
+ public static final int FLAG_FASTDCT = (1 << 11);
+ /**
+ * Use the most accurate DCT/IDCT algorithm available. The default if this
+ * flag is not specified is implementation-specific. For example, the
+ * implementation of the TurboJPEG API in libjpeg-turbo uses the fast
* algorithm by default when compressing, because this has been shown to have
* only a very slight effect on accuracy, but it uses the accurate algorithm
* when decompressing, because this has been shown to have a larger effect.
*/
- public static final int FLAG_FASTDCT = (1 << 11);
- /**
- * Use the most accurate DCT/IDCT algorithm available in the underlying
- * codec. The default if this flag is not specified is
- * implementation-specific. For example, the implementation of TurboJPEG for
- * libjpeg[-turbo] uses the fast algorithm by default when compressing,
- * because this has been shown to have only a very slight effect on accuracy,
- * but it uses the accurate algorithm when decompressing, because this has
- * been shown to have a larger effect.
- */
public static final int FLAG_ACCURATEDCT = (1 << 12);
/**
* Immediately discontinue the current compression/decompression/transform
- * operation if the underlying codec throws a warning (non-fatal error). The
- * default behavior is to allow the operation to complete unless a fatal
- * error is encountered.
+ * operation if a warning (non-fatal error) occurs. The default behavior is
+ * to allow the operation to complete unless a fatal error is encountered.
* * NOTE: due to the design of the TurboJPEG Java API, only certain methods * (specifically, {@link TJDecompressor TJDecompressor.decompress*()} methods - * with a void return type) will complete and leave the output image in a - * fully recoverable state after a non-fatal error occurs. + * with a void return type) will complete and leave the destination image in + * a fully recoverable state after a non-fatal error occurs. */ public static final int FLAG_STOPONWARNING = (1 << 13); /** @@ -456,7 +457,7 @@ public final class TJ { *
* NOTE: due to the design of the TurboJPEG Java API, only certain methods
* (specifically, {@link TJDecompressor TJDecompressor.decompress*()} methods
- * with a void return type) will complete and leave the output image in a
- * fully recoverable state after a non-fatal error occurs.
+ * with a void return type) will complete and leave the destination image in
+ * a fully recoverable state after a non-fatal error occurs.
*/
public static final int ERR_WARNING = 0;
/**
@@ -492,7 +493,7 @@ public final class TJ {
* @param height the height (in pixels) of the JPEG image
*
* @param jpegSubsamp the level of chrominance subsampling to be used when
- * generating the JPEG image (one of {@link TJ TJ.SAMP_*})
+ * generating the JPEG image (one of {@link #SAMP_444 TJ.SAMP_*})
*
* @return the maximum size of the buffer (in bytes) required to hold a JPEG
* image with the given width, height, and level of chrominance subsampling.
@@ -500,23 +501,27 @@ public final class TJ {
public static native int bufSize(int width, int height, int jpegSubsamp);
/**
- * Returns the size of the buffer (in bytes) required to hold a YUV planar
- * image with the given width, height, and level of chrominance subsampling.
+ * Returns the size of the buffer (in bytes) required to hold a unified
+ * planar YUV image with the given width, height, and level of chrominance
+ * subsampling.
*
* @param width the width (in pixels) of the YUV image
*
- * @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 align row alignment (in bytes) of the YUV image (must be a power of
+ * 2.) Setting this parameter to n specifies that each row in each plane of
+ * the YUV image will be padded to the nearest multiple of n bytes
+ * (1 = unpadded.)
*
* @param height the height (in pixels) of the YUV image
*
* @param subsamp the level of chrominance subsampling used in the YUV
- * image (one of {@link TJ TJ.SAMP_*})
+ * image (one of {@link #SAMP_444 TJ.SAMP_*})
*
- * @return the size of the buffer (in bytes) required to hold a YUV planar
- * image with the given width, height, and level of chrominance subsampling.
+ * @return the size of the buffer (in bytes) required to hold a unified
+ * planar YUV image with the given width, height, and level of chrominance
+ * subsampling.
*/
- public static native int bufSizeYUV(int width, int pad, int height,
+ public static native int bufSizeYUV(int width, int align, int height,
int subsamp);
/**
@@ -529,16 +534,16 @@ public final class TJ {
* @param width width (in pixels) of the YUV image. NOTE: this is the width
* of the whole image, not the plane width.
*
- * @param stride bytes per line in the image plane.
+ * @param stride bytes per row in the image plane.
*
* @param height height (in pixels) of the YUV image. NOTE: this is the
* height of the whole image, not the plane height.
*
* @param subsamp the level of chrominance subsampling used in the YUV
- * image (one of {@link TJ TJ.SAMP_*})
+ * image (one of {@link #SAMP_444 TJ.SAMP_*})
*
- * @return the size of the buffer (in bytes) required to hold a YUV planar
- * image with the given parameters.
+ * @return the size of the buffer (in bytes) required to hold a YUV image
+ * plane with the given parameters.
*/
public static native int planeSizeYUV(int componentID, int width, int stride,
int height, int subsamp);
@@ -553,7 +558,7 @@ public final class TJ {
* @param width width (in pixels) of the YUV image
*
* @param subsamp the level of chrominance subsampling used in the YUV image
- * (one of {@link TJ TJ.SAMP_*})
+ * (one of {@link #SAMP_444 TJ.SAMP_*})
*
* @return the plane width of a YUV image plane with the given parameters.
*/
@@ -569,7 +574,7 @@ public final class TJ {
* @param height height (in pixels) of the YUV image
*
* @param subsamp the level of chrominance subsampling used in the YUV image
- * (one of {@link TJ TJ.SAMP_*})
+ * (one of {@link #SAMP_444 TJ.SAMP_*})
*
* @return the plane height of a YUV image plane with the given parameters.
*/
@@ -577,11 +582,11 @@ public final class TJ {
int subsamp);
/**
- * Returns a list of fractional scaling factors that the JPEG decompressor in
- * this implementation of TurboJPEG supports.
+ * Returns a list of fractional scaling factors that the JPEG decompressor
+ * supports.
*
- * @return a list of fractional scaling factors that the JPEG decompressor in
- * this implementation of TurboJPEG supports.
+ * @return a list of fractional scaling factors that the JPEG decompressor
+ * supports.
*/
public static native TJScalingFactor[] getScalingFactors();
diff --git a/java/org/libjpegturbo/turbojpeg/TJCompressor.java b/java/org/libjpegturbo/turbojpeg/TJCompressor.java
index d7d2976f..305a9d13 100644
--- a/java/org/libjpegturbo/turbojpeg/TJCompressor.java
+++ b/java/org/libjpegturbo/turbojpeg/TJCompressor.java
@@ -1,5 +1,5 @@
/*
- * Copyright (C)2011-2015, 2018, 2020, 2022 D. R. Commander.
+ * Copyright (C)2011-2015, 2018, 2020, 2022-2023 D. R. Commander.
* All Rights Reserved.
* Copyright (C)2015 Viktor Szathmáry. All Rights Reserved.
*
@@ -50,7 +50,7 @@ public class TJCompressor implements Closeable {
}
/**
- * Create a TurboJPEG compressor instance and associate the uncompressed
+ * Create a TurboJPEG compressor instance and associate the packed-pixel
* source image stored in srcImage with the newly created
* instance.
*
@@ -75,7 +75,7 @@ public class TJCompressor implements Closeable {
}
/**
- * Create a TurboJPEG compressor instance and associate the uncompressed
+ * Create a TurboJPEG compressor instance and associate the packed-pixel
* source image stored in srcImage with the newly created
* instance.
*
@@ -100,11 +100,11 @@ public class TJCompressor implements Closeable {
}
/**
- * Associate an uncompressed RGB, grayscale, or CMYK source image with this
+ * Associate a packed-pixel RGB, grayscale, or CMYK source image with this
* compressor instance.
*
- * @param srcImage image buffer containing RGB, grayscale, or CMYK pixels to
- * be compressed or encoded. This buffer is not modified.
+ * @param srcImage buffer containing a packed-pixel RGB, grayscale, or CMYK
+ * source image to be compressed or encoded. This buffer is not modified.
*
* @param x x offset (in pixels) of the region in the source image from which
* the JPEG or YUV image should be compressed/encoded
@@ -115,13 +115,13 @@ public class TJCompressor implements Closeable {
* @param width width (in pixels) of the region in the source image from
* which the JPEG or YUV image should be compressed/encoded
*
- * @param pitch bytes per line of the source image. Normally, this should be
- * width * TJ.pixelSize(pixelFormat) if the source image is
- * unpadded, but you can use this parameter to, for instance, specify that
- * the scanlines in the source image are padded to a 4-byte boundary or to
- * compress/encode a JPEG or YUV image from a region of a larger source
- * image. You can also be clever and use this parameter to skip lines, etc.
- * Setting this parameter to 0 is the equivalent of setting it to
+ * @param pitch bytes per row in the source image. Normally this should be
+ * width * TJ.pixelSize(pixelFormat), if the source image is
+ * unpadded. However, you can use this parameter to, for instance, specify
+ * that the rows in the source image are padded to the nearest multiple of 4
+ * bytes or to compress/encode a JPEG or YUV image from a region of a larger
+ * source image. You can also be clever and use this parameter to skip rows,
+ * etc. Setting this parameter to 0 is the equivalent of setting it to
* width * TJ.pixelSize(pixelFormat).
*
* @param height height (in pixels) of the region in the source image from
@@ -152,11 +152,12 @@ public class TJCompressor implements Closeable {
}
/**
- * Associate an uncompressed RGB or grayscale source image with this
+ * Associate a packed-pixel RGB or grayscale source image with this
* compressor instance.
*
- * @param srcImage a BufferedImage instance containing RGB or
- * grayscale pixels to be compressed or encoded. This image is not modified.
+ * @param srcImage a BufferedImage instance containing a
+ * packed-pixel RGB or grayscale source image to be compressed or encoded.
+ * This image is not modified.
*
* @param x x offset (in pixels) of the region in the source image from which
* the JPEG or YUV image should be compressed/encoded
@@ -238,11 +239,10 @@ public class TJCompressor implements Closeable {
}
/**
- * Associate an uncompressed YUV planar source image with this compressor
- * instance.
+ * Associate a planar YUV source image with this compressor instance.
*
- * @param srcImage YUV planar image to be compressed. This image is not
- * modified.
+ * @param srcImage planar YUV source image to be compressed. This image is
+ * not modified.
*/
public void setSourceImage(YUVImage srcImage) throws TJException {
if (handle == 0) init();
@@ -259,16 +259,16 @@ public class TJCompressor implements Closeable {
* {@link TJ#CS_YCbCr}) or from CMYK to YCCK (see {@link TJ#CS_YCCK}) 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 to small changes in color.)
- * This is called "chrominance subsampling".
+ * image with little perceptible loss of image clarity. (The human eye is
+ * more sensitive to small changes in brightness than to small changes in
+ * color.) This is called "chrominance subsampling".
*
- * NOTE: This method has no effect when compressing a JPEG image from a YUV
- * planar source. In that case, the level of chrominance subsampling in
- * the JPEG image is determined by the source. Furthermore, this method has
- * no effect when encoding to a pre-allocated {@link YUVImage} instance. In
- * that case, the level of chrominance subsampling is determined by the
- * destination.
+ * NOTE: This method has no effect when compressing a JPEG image from a
+ * planar YUV source image. In that case, the level of chrominance
+ * subsampling in the JPEG image is determined by the source image.
+ * Furthermore, this method has no effect when encoding to a pre-allocated
+ * {@link YUVImage} instance. In that case, the level of chrominance
+ * subsampling is determined by the destination image.
*
* @param newSubsamp the level of chrominance subsampling to use in
* subsequent compress/encode oeprations (one of
@@ -300,8 +300,9 @@ public class TJCompressor implements Closeable {
}
/**
- * Compress the uncompressed source image associated with this compressor
- * instance and output a JPEG image to the given destination buffer.
+ * Compress the packed-pixel or planar YUV source image associated with this
+ * compressor instance and output a JPEG image to the given destination
+ * buffer.
*
* @param dstBuf buffer that will receive the JPEG image. Use
* {@link TJ#bufSize} to determine the maximum size for this buffer based on
@@ -340,8 +341,8 @@ public class TJCompressor implements Closeable {
}
/**
- * Compress the uncompressed source image associated with this compressor
- * instance and return a buffer containing a JPEG image.
+ * Compress the packed-pixel or planar YUV source image associated with this
+ * compressor instance and return a buffer containing a JPEG image.
*
* @param flags the bitwise OR of one or more of
* {@link TJ#FLAG_BOTTOMUP TJ.FLAG_*}
@@ -365,14 +366,14 @@ public class TJCompressor implements Closeable {
}
/**
- * Encode the uncompressed source image associated with this compressor
- * instance into a YUV planar image and store it in the given
- * YUVImage instance. This method uses the accelerated color
- * conversion routines in TurboJPEG's underlying codec but does not execute
- * any of the other steps in the JPEG compression process. Encoding
- * CMYK source images to YUV is not supported.
+ * Encode the packed-pixel source image associated with this compressor
+ * instance into a planar YUV image and store it in the given
+ * {@link YUVImage} instance. This method performs color conversion (which
+ * is accelerated in the libjpeg-turbo implementation) but does not execute
+ * any of the other steps in the JPEG compression process. Encoding CMYK
+ * source images into YUV images is not supported.
*
- * @param dstImage {@link YUVImage} instance that will receive the YUV planar
+ * @param dstImage {@link YUVImage} instance that will receive the planar YUV
* image
*
* @param flags the bitwise OR of one or more of
@@ -402,52 +403,54 @@ public class TJCompressor implements Closeable {
}
/**
- * Encode the uncompressed source image associated with this compressor
- * instance into a unified YUV planar image buffer and return a
- * YUVImage instance containing the encoded image. This method
- * uses the accelerated color conversion routines in TurboJPEG's underlying
- * codec but does not execute any of the other steps in the JPEG compression
- * process. Encoding CMYK source images to YUV is not supported.
+ * Encode the packed-pixel source image associated with this compressor
+ * instance into a unified planar YUV image and return a {@link YUVImage}
+ * instance containing the encoded image. This method performs color
+ * conversion (which is accelerated in the libjpeg-turbo implementation) but
+ * does not execute any of the other steps in the JPEG compression process.
+ * Encoding CMYK source images into YUV images is not supported.
*
- * @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.)
+ * @param align row alignment (in bytes) of the YUV image (must be a power of
+ * 2.) Setting this parameter to n will cause each row in each plane of the
+ * YUV image to be padded to the nearest multiple of n bytes (1 = unpadded.)
*
* @param flags the bitwise OR of one or more of
* {@link TJ#FLAG_BOTTOMUP TJ.FLAG_*}
*
- * @return a YUV planar image.
+ * @return a {@link YUVImage} instance containing the unified planar YUV
+ * encoded image
*/
- public YUVImage encodeYUV(int pad, int flags) throws TJException {
+ public YUVImage encodeYUV(int align, int flags) throws TJException {
checkSourceImage();
checkSubsampling();
- if (pad < 1 || ((pad & (pad - 1)) != 0))
+ if (align < 1 || ((align & (align - 1)) != 0))
throw new IllegalStateException("Invalid argument in encodeYUV()");
- YUVImage dstYUVImage = new YUVImage(srcWidth, pad, srcHeight, subsamp);
+ YUVImage dstYUVImage = new YUVImage(srcWidth, align, srcHeight, subsamp);
encodeYUV(dstYUVImage, flags);
return dstYUVImage;
}
/**
- * Encode the uncompressed source image associated with this compressor
+ * Encode the packed-pixel source image associated with this compressor
* instance into separate Y, U (Cb), and V (Cr) image planes and return a
- * YUVImage instance containing the encoded image planes. This
- * method uses the accelerated color conversion routines in TurboJPEG's
- * underlying codec but does not execute any of the other steps in the JPEG
- * compression process. Encoding CMYK source images to YUV is not supported.
+ * {@link YUVImage} instance containing the encoded image planes. This
+ * method performs color conversion (which is accelerated in the
+ * libjpeg-turbo implementation) but does not execute any of the other steps
+ * in the JPEG compression process. Encoding CMYK source images into YUV
+ * images is not supported.
*
* @param strides an array of integers, each specifying the number of bytes
- * per line in the corresponding plane of the output image. Setting the
- * stride for any plane to 0 is the same as setting it to the component width
- * of the plane. If strides is null, then the strides for all
- * planes will be set to their respective component widths. You can adjust
- * the strides in order to add an arbitrary amount of line padding to each
- * plane.
+ * per row in the corresponding plane of the YUV source image. Setting the
+ * stride for any plane to 0 is the same as setting it to the plane width
+ * (see {@link YUVImage}.) If strides is null, then the strides
+ * for all planes will be set to their respective plane widths. You can
+ * adjust the strides in order to add an arbitrary amount of row padding to
+ * each plane.
*
* @param flags the bitwise OR of one or more of
* {@link TJ#FLAG_BOTTOMUP TJ.FLAG_*}
*
- * @return a YUV planar image.
+ * @return a {@link YUVImage} instance containing the encoded image planes
*/
public YUVImage encodeYUV(int[] strides, int flags) throws TJException {
checkSourceImage();
@@ -549,6 +552,5 @@ public class TJCompressor implements Closeable {
private int subsamp = -1;
private int jpegQuality = -1;
private int compressedSize = 0;
- private int yuvPad = 4;
private ByteOrder byteOrder = null;
}
diff --git a/java/org/libjpegturbo/turbojpeg/TJCustomFilter.java b/java/org/libjpegturbo/turbojpeg/TJCustomFilter.java
index 9a34587a..3a66fd9e 100644
--- a/java/org/libjpegturbo/turbojpeg/TJCustomFilter.java
+++ b/java/org/libjpegturbo/turbojpeg/TJCustomFilter.java
@@ -1,5 +1,5 @@
/*
- * Copyright (C)2011, 2013 D. R. Commander. All Rights Reserved.
+ * Copyright (C)2011, 2013, 2023 D. R. Commander. All Rights Reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
@@ -58,7 +58,7 @@ public interface TJCustomFilter {
* component plane to which coeffBuffer belongs
*
* @param componentID ID number of the component plane to which
- * coeffBuffer belongs (Y, Cb, and Cr have, respectively, ID's
+ * coeffBuffer belongs. (Y, Cb, and Cr have, respectively, ID's
* of 0, 1, and 2 in typical JPEG images.)
*
* @param transformID ID number of the transformed image to which
diff --git a/java/org/libjpegturbo/turbojpeg/TJDecompressor.java b/java/org/libjpegturbo/turbojpeg/TJDecompressor.java
index c115d47e..d5b9afd9 100644
--- a/java/org/libjpegturbo/turbojpeg/TJDecompressor.java
+++ b/java/org/libjpegturbo/turbojpeg/TJDecompressor.java
@@ -1,5 +1,6 @@
/*
- * Copyright (C)2011-2015, 2018, 2022 D. R. Commander. All Rights Reserved.
+ * Copyright (C)2011-2015, 2018, 2022-2023 D. R. Commander.
+ * All Rights Reserved.
* Copyright (C)2015 Viktor Szathmáry. All Rights Reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -50,10 +51,12 @@ public class TJDecompressor implements Closeable {
/**
* Create a TurboJPEG decompressor instance and associate the JPEG source
- * image stored in jpegImage with the newly created instance.
+ * image or "abbreviated table specification" (AKA "tables-only") datastream
+ * stored in jpegImage with the newly created instance.
*
- * @param jpegImage JPEG image buffer (size of the JPEG image is assumed to
- * be the length of the array.) This buffer is not modified.
+ * @param jpegImage buffer containing a JPEG source image or tables-only
+ * datastream. (The size of the JPEG image or datastream is assumed to be
+ * the length of the array.) This buffer is not modified.
*/
public TJDecompressor(byte[] jpegImage) throws TJException {
init();
@@ -62,12 +65,15 @@ public class TJDecompressor implements Closeable {
/**
* Create a TurboJPEG decompressor instance and associate the JPEG source
- * image of length imageSize bytes stored in
- * jpegImage with the newly created instance.
+ * image or "abbreviated table specification" (AKA "tables-only") datastream
+ * of length imageSize bytes stored in jpegImage
+ * with the newly created instance.
*
- * @param jpegImage JPEG image buffer. This buffer is not modified.
+ * @param jpegImage buffer containing a JPEG source image or tables-only
+ * datastream. This buffer is not modified.
*
- * @param imageSize size of the JPEG image (in bytes)
+ * @param imageSize size of the JPEG source image or tables-only datastream
+ * (in bytes)
*/
public TJDecompressor(byte[] jpegImage, int imageSize) throws TJException {
init();
@@ -75,11 +81,11 @@ public class TJDecompressor implements Closeable {
}
/**
- * Create a TurboJPEG decompressor instance and associate the YUV planar
+ * Create a TurboJPEG decompressor instance and associate the planar YUV
* source image stored in yuvImage with the newly created
* instance.
*
- * @param yuvImage {@link YUVImage} instance containing a YUV planar
+ * @param yuvImage {@link YUVImage} instance containing a planar YUV source
* image to be decoded. This image is not modified.
*/
@SuppressWarnings("checkstyle:HiddenField")
@@ -100,11 +106,11 @@ public class TJDecompressor implements Closeable {
* when decompressing video streams in which all frames share the same
* quantization and Huffman tables.
*
- * @param jpegImage buffer containing a JPEG image or an "abbreviated table
- * specification" (AKA "tables-only") datastream. This buffer is not
- * modified.
+ * @param jpegImage buffer containing a JPEG source image or tables-only
+ * datastream. This buffer is not modified.
*
- * @param imageSize size of the JPEG image (in bytes)
+ * @param imageSize size of the JPEG source image or tables-only datastream
+ * (in bytes)
*/
public void setSourceImage(byte[] jpegImage, int imageSize)
throws TJException {
@@ -117,12 +123,12 @@ public class TJDecompressor implements Closeable {
}
/**
- * Associate the specified YUV planar source image with this decompressor
- * instance. Subsequent decompress operations will decode this image into an
- * RGB or grayscale destination image.
+ * Associate the specified planar YUV source image with this decompressor
+ * instance. Subsequent decompress operations will decode this image into a
+ * packed-pixel RGB or grayscale destination image.
*
- * @param srcImage {@link YUVImage} instance containing a YUV planar image to
- * be decoded. This image is not modified.
+ * @param srcImage {@link YUVImage} instance containing a planar YUV source
+ * image to be decoded. This image is not modified.
*/
public void setSourceImage(YUVImage srcImage) {
if (srcImage == null)
@@ -215,9 +221,9 @@ public class TJDecompressor implements Closeable {
}
/**
- * Returns the JPEG image buffer associated with this decompressor instance.
+ * Returns the JPEG buffer associated with this decompressor instance.
*
- * @return the JPEG image buffer associated with this decompressor instance.
+ * @return the JPEG buffer associated with this decompressor instance.
*/
public byte[] getJPEGBuf() {
if (jpegBuf == null)
@@ -244,14 +250,14 @@ public class TJDecompressor implements Closeable {
* height.
*
* @param desiredWidth desired width (in pixels) of the decompressed image.
- * Setting this to 0 is the same as setting it to the width of the JPEG image
- * (in other words, the width will not be considered when determining the
- * scaled image size.)
+ * Setting this to 0 is the same as setting it to the width of the JPEG
+ * image. (In other words, the width will not be considered when determining
+ * the scaled image size.)
*
* @param desiredHeight desired height (in pixels) of the decompressed image.
* Setting this to 0 is the same as setting it to the height of the JPEG
- * image (in other words, the height will not be considered when determining
- * the scaled image size.)
+ * image. (In other words, the height will not be considered when
+ * determining the scaled image size.)
*
* @return the width of the largest scaled-down image that the TurboJPEG
* decompressor can generate without exceeding the desired image width and
@@ -285,14 +291,14 @@ public class TJDecompressor implements Closeable {
* height.
*
* @param desiredWidth desired width (in pixels) of the decompressed image.
- * Setting this to 0 is the same as setting it to the width of the JPEG image
- * (in other words, the width will not be considered when determining the
- * scaled image size.)
+ * Setting this to 0 is the same as setting it to the width of the JPEG
+ * image. (In other words, the width will not be considered when determining
+ * the scaled image size.)
*
* @param desiredHeight desired height (in pixels) of the decompressed image.
* Setting this to 0 is the same as setting it to the height of the JPEG
- * image (in other words, the height will not be considered when determining
- * the scaled image size.)
+ * image. (In other words, the height will not be considered when
+ * determining the scaled image size.)
*
* @return the height of the largest scaled-down image that the TurboJPEG
* decompressor can generate without exceeding the desired image width and
@@ -321,27 +327,27 @@ public class TJDecompressor implements Closeable {
}
/**
- * Decompress the JPEG source image or decode the YUV source image associated
- * with this decompressor instance and output a grayscale, RGB, or CMYK image
- * to the given destination buffer.
+ * Decompress the JPEG source image or decode the planar YUV source image
+ * associated with this decompressor instance and output a packed-pixel
+ * grayscale, RGB, or CMYK image to the given destination buffer.
*
- * NOTE: The output image is fully recoverable if this method throws a
+ * NOTE: The destination image is fully recoverable if this method throws a
* non-fatal {@link TJException} (unless
* {@link TJ#FLAG_STOPONWARNING TJ.FLAG_STOPONWARNING} is specified.)
*
- * @param dstBuf buffer that will receive the decompressed/decoded image.
- * If the source image is a JPEG image, then this buffer should normally be
- * pitch * scaledHeight bytes in size, where
- * scaledHeight can be determined by calling
- * scalingFactor.{@link TJScalingFactor#getScaled getScaled}(jpegHeight)
- * with one of the scaling factors returned from {@link
- * TJ#getScalingFactors} or by calling {@link #getScaledHeight}. If the
- * source image is a YUV image, then this buffer should normally be
- * pitch * height bytes in size, where height is
- * the height of the YUV image. However, the buffer may also be larger than
- * the dimensions of the source image, in which case the x,
- * y, and pitch parameters can be used to specify
- * the region into which the source image should be decompressed/decoded.
+ * @param dstBuf buffer that will receive the packed-pixel
+ * decompressed/decoded image. If the source image is a JPEG image, then
+ * this buffer should normally be pitch * scaledHeight bytes in
+ * size, where scaledHeight can be determined by calling
+ * scalingFactor.{@link TJScalingFactor#getScaled getScaled}(jpegHeight)
+ * with one of the scaling factors returned from {@link TJ#getScalingFactors}
+ * or by calling {@link #getScaledHeight}. If the source image is a YUV
+ * image, then this buffer should normally be pitch * height
+ * bytes in size, where height is the height of the YUV image.
+ * However, the buffer may also be larger than the dimensions of the source
+ * image, in which case the x, y, and
+ * pitch parameters can be used to specify the region into which
+ * the source image should be decompressed/decoded.
*
* @param x x offset (in pixels) of the region in the destination image into
* which the source image should be decompressed/decoded
@@ -355,20 +361,20 @@ public class TJDecompressor implements Closeable {
* than the source image dimensions, then TurboJPEG will use scaling in the
* JPEG decompressor to generate the largest possible image that will fit
* within the desired dimensions. Setting this to 0 is the same as setting
- * it to the width of the JPEG image (in other words, the width will not be
+ * it to the width of the JPEG image. (In other words, the width will not be
* considered when determining the scaled image size.) This parameter is
* ignored if the source image is a YUV image.
*
- * @param pitch bytes per line of the destination image. Normally, this
- * should be set to scaledWidth * TJ.pixelSize(pixelFormat) if
- * the destination image is unpadded, but you can use this to, for instance,
- * pad each line of the destination image to a 4-byte boundary or to
- * decompress/decode the source image into a region of a larger image. NOTE:
- * if the source image is a JPEG image, then scaledWidth can be
- * determined by calling
- * scalingFactor.{@link TJScalingFactor#getScaled getScaled}(jpegWidth)
- * or by calling {@link #getScaledWidth}. If the source image is a
- * YUV image, then scaledWidth is the width of the YUV image.
+ * @param pitch bytes per row in the destination image. Normally this should
+ * be set to scaledWidth * TJ.pixelSize(pixelFormat), if the
+ * destination image will be unpadded. However, you can use this to, for
+ * instance, pad each row of the destination image to the nearest multiple of
+ * 4 bytes or to decompress/decode the source image into a region of a larger
+ * image. NOTE: if the source image is a JPEG image, then
+ * scaledWidth can be determined by calling
+ * scalingFactor.{@link TJScalingFactor#getScaled getScaled}(jpegWidth)
+ * or by calling {@link #getScaledWidth}. If the source image is a YUV
+ * image, then scaledWidth is the width of the YUV image.
* Setting this parameter to 0 is the equivalent of setting it to
* scaledWidth * TJ.pixelSize(pixelFormat).
*
@@ -378,8 +384,8 @@ public class TJDecompressor implements Closeable {
* than the source image dimensions, then TurboJPEG will use scaling in the
* JPEG decompressor to generate the largest possible image that will fit
* within the desired dimensions. Setting this to 0 is the same as setting
- * it to the height of the JPEG image (in other words, the height will not be
- * considered when determining the scaled image size.) This parameter is
+ * it to the height of the JPEG image. (In other words, the height will not
+ * be considered when determining the scaled image size.) This parameter is
* ignored if the source image is a YUV image.
*
* @param pixelFormat pixel format of the decompressed/decoded image (one of
@@ -408,8 +414,9 @@ public class TJDecompressor implements Closeable {
}
/**
- * Decompress the JPEG source image associated with this decompressor
- * instance and return a buffer containing the decompressed image.
+ * Decompress the JPEG source image or decode the planar YUV source image
+ * associated with this decompressor instance and return a buffer containing
+ * the packed-pixel decompressed image.
*
* @param desiredWidth see
* {@link #decompress(byte[], int, int, int, int, int, int, int)}
@@ -429,7 +436,7 @@ public class TJDecompressor implements Closeable {
* @param flags the bitwise OR of one or more of
* {@link TJ#FLAG_BOTTOMUP TJ.FLAG_*}
*
- * @return a buffer containing the decompressed image.
+ * @return a buffer containing the packed-pixel decompressed image.
*/
public byte[] decompress(int desiredWidth, int pitch, int desiredHeight,
int pixelFormat, int flags) throws TJException {
@@ -450,22 +457,22 @@ public class TJDecompressor implements Closeable {
/**
* Decompress the JPEG source image associated with this decompressor
- * instance into a YUV planar image and store it in the given
- * YUVImage instance. This method performs JPEG decompression
- * but leaves out the color conversion step, so a planar YUV image is
- * generated instead of an RGB or grayscale image. This method cannot be
- * used to decompress JPEG source images with the CMYK or YCCK colorspace.
+ * instance into a planar YUV image and store it in the given
+ * {@link YUVImage} instance. This method performs JPEG decompression but
+ * leaves out the color conversion step, so a planar YUV image is generated
+ * instead of a packed-pixel image. This method cannot be used to decompress
+ * JPEG source images with the CMYK or YCCK colorspace.
*
- * NOTE: The YUV planar output image is fully recoverable if this method
+ * NOTE: The planar YUV destination image is fully recoverable if this method
* throws a non-fatal {@link TJException} (unless
* {@link TJ#FLAG_STOPONWARNING TJ.FLAG_STOPONWARNING} is specified.)
*
- * @param dstImage {@link YUVImage} instance that will receive the YUV planar
- * image. The level of subsampling specified in this YUVImage
- * instance must match that of the JPEG image, and the width and height
- * specified in the YUVImage instance must match one of the
- * scaled image sizes that TurboJPEG is capable of generating from the JPEG
- * source image.
+ * @param dstImage {@link YUVImage} instance that will receive the planar YUV
+ * decompressed image. The level of subsampling specified in this
+ * {@link YUVImage} instance must match that of the JPEG image, and the width
+ * and height specified in the {@link YUVImage} instance must match one of
+ * the scaled image sizes that the decompressor is capable of generating from
+ * the JPEG source image.
*
* @param flags the bitwise OR of one or more of
* {@link TJ#FLAG_BOTTOMUP TJ.FLAG_*}
@@ -482,7 +489,7 @@ public class TJDecompressor implements Closeable {
dstImage.getHeight());
if (scaledWidth != dstImage.getWidth() ||
scaledHeight != dstImage.getHeight())
- throw new IllegalArgumentException("YUVImage dimensions do not match one of the scaled image sizes that TurboJPEG is capable of generating.");
+ throw new IllegalArgumentException("YUVImage dimensions do not match one of the scaled image sizes that the decompressor is capable of generating.");
if (jpegSubsamp != dstImage.getSubsamp())
throw new IllegalArgumentException("YUVImage subsampling level does not match that of the JPEG image");
@@ -494,40 +501,41 @@ public class TJDecompressor implements Closeable {
/**
* Decompress the JPEG source image associated with this decompressor
* instance into a set of Y, U (Cb), and V (Cr) image planes and return a
- * YUVImage instance containing the decompressed image planes.
- * This method performs JPEG decompression but leaves out the color
- * conversion step, so a planar YUV image is generated instead of an RGB or
- * grayscale image. This method cannot be used to decompress JPEG source
- * images with the CMYK or YCCK colorspace.
+ * {@link YUVImage} instance containing the decompressed image planes. This
+ * method performs JPEG decompression but leaves out the color conversion
+ * step, so a planar YUV image is generated instead of a packed-pixel image.
+ * This method cannot be used to decompress JPEG source images with the CMYK
+ * or YCCK colorspace.
*
* @param desiredWidth desired width (in pixels) of the YUV image. If the
* desired image dimensions are different than the dimensions 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 dimensions. Setting this to 0 is the same as setting it to
- * the width of the JPEG image (in other words, the width will not be
+ * the width of the JPEG image. (In other words, the width will not be
* considered when determining the scaled image size.)
*
* @param strides an array of integers, each specifying the number of bytes
- * per line in the corresponding plane of the output image. Setting the
- * stride for any plane to 0 is the same as setting it to the scaled
- * component width of the plane. If strides is NULL, then the
- * strides for all planes will be set to their respective scaled component
- * widths. You can adjust the strides in order to add an arbitrary amount of
- * line padding to each plane.
+ * per row in the corresponding plane of the YUV image. Setting the stride
+ * for any plane to 0 is the same as setting it to the scaled plane width
+ * (see {@link YUVImage}.) If strides is null, then the strides
+ * for all planes will be set to their respective scaled plane widths. You
+ * can adjust the strides in order to add an arbitrary amount of row padding
+ * to each plane.
*
* @param desiredHeight desired height (in pixels) of the YUV image. If the
* desired image dimensions are different than the dimensions 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 dimensions. Setting this to 0 is the same as setting it to
- * the height of the JPEG image (in other words, the height will not be
+ * the height of the JPEG image. (In other words, the height will not be
* considered when determining the scaled image size.)
*
* @param flags the bitwise OR of one or more of
* {@link TJ#FLAG_BOTTOMUP TJ.FLAG_*}
*
- * @return a YUV planar image.
+ * @return a {@link YUVImage} instance containing the decompressed image
+ * planes
*/
public YUVImage decompressToYUV(int desiredWidth, int[] strides,
int desiredHeight,
@@ -551,40 +559,41 @@ public class TJDecompressor implements Closeable {
/**
* Decompress the JPEG source image associated with this decompressor
- * instance into a unified YUV planar image buffer and return a
- * YUVImage instance containing the decompressed image. This
- * method performs JPEG decompression but leaves out the color conversion
- * step, so a planar YUV image is generated instead of an RGB or grayscale
- * image. This method cannot be used to decompress JPEG source images with
- * the CMYK or YCCK colorspace.
+ * instance into a unified planar YUV image and return a {@link YUVImage}
+ * instance containing the decompressed image. This method performs JPEG
+ * decompression but leaves out the color conversion step, so a planar YUV
+ * image is generated instead of a packed-pixel image. This method cannot be
+ * used to decompress JPEG source images with the CMYK or YCCK colorspace.
*
* @param desiredWidth desired width (in pixels) of the YUV image. If the
* desired image dimensions are different than the dimensions 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 dimensions. Setting this to 0 is the same as setting it to
- * the width of the JPEG image (in other words, the width will not be
+ * the width of the JPEG image. (In other words, the width will not 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.)
+ * @param align row alignment (in bytes) of the YUV image (must be a power of
+ * 2.) Setting this parameter to n will cause each row in each plane of the
+ * YUV image to be padded to the nearest multiple of n bytes (1 = unpadded.)
*
* @param desiredHeight desired height (in pixels) of the YUV image. If the
* desired image dimensions are different than the dimensions 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 dimensions. Setting this to 0 is the same as setting it to
- * the height of the JPEG image (in other words, the height will not be
+ * the height of the JPEG image. (In other words, the height will not be
* considered when determining the scaled image size.)
*
* @param flags the bitwise OR of one or more of
* {@link TJ#FLAG_BOTTOMUP TJ.FLAG_*}
*
- * @return a YUV planar image.
+ * @return a {@link YUVImage} instance containing the unified planar YUV
+ * decompressed image
*/
- public YUVImage decompressToYUV(int desiredWidth, int pad, int desiredHeight,
- int flags) throws TJException {
+ public YUVImage decompressToYUV(int desiredWidth, int align,
+ int desiredHeight, int flags)
+ throws TJException {
if (flags < 0)
throw new IllegalArgumentException("Invalid argument in decompressToYUV()");
if (jpegWidth < 1 || jpegHeight < 1 || jpegSubsamp < 0)
@@ -596,34 +605,34 @@ public class TJDecompressor implements Closeable {
int scaledWidth = getScaledWidth(desiredWidth, desiredHeight);
int scaledHeight = getScaledHeight(desiredWidth, desiredHeight);
- YUVImage dstYUVImage = new YUVImage(scaledWidth, pad, scaledHeight,
+ YUVImage dstYUVImage = new YUVImage(scaledWidth, align, scaledHeight,
jpegSubsamp);
decompressToYUV(dstYUVImage, flags);
return dstYUVImage;
}
/**
- * Decompress the JPEG source image or decode the YUV source image associated
- * with this decompressor instance and output a grayscale, RGB, or CMYK image
- * to the given destination buffer.
+ * Decompress the JPEG source image or decode the planar YUV source image
+ * associated with this decompressor instance and output a packed-pixel
+ * grayscale, RGB, or CMYK image to the given destination buffer.
*
- * NOTE: The output image is fully recoverable if this method throws a
+ * NOTE: The destination image is fully recoverable if this method throws a
* non-fatal {@link TJException} (unless
* {@link TJ#FLAG_STOPONWARNING TJ.FLAG_STOPONWARNING} is specified.)
*
- * @param dstBuf buffer that will receive the decompressed/decoded image.
- * If the source image is a JPEG image, then this buffer should normally be
- * stride * scaledHeight pixels in size, where
- * scaledHeight can be determined by calling
- * scalingFactor.{@link TJScalingFactor#getScaled getScaled}(jpegHeight)
- * with one of the scaling factors returned from {@link
- * TJ#getScalingFactors} or by calling {@link #getScaledHeight}. If the
- * source image is a YUV image, then this buffer should normally be
- * stride * height pixels in size, where height is
- * the height of the YUV image. However, the buffer may also be larger than
- * the dimensions of the JPEG image, in which case the x,
- * y, and stride parameters can be used to specify
- * the region into which the source image should be decompressed.
+ * @param dstBuf buffer that will receive the packed-pixel
+ * decompressed/decoded image. If the source image is a JPEG image, then
+ * this buffer should normally be stride * scaledHeight pixels
+ * in size, where scaledHeight can be determined by calling
+ * scalingFactor.{@link TJScalingFactor#getScaled getScaled}(jpegHeight)
+ * with one of the scaling factors returned from {@link TJ#getScalingFactors}
+ * or by calling {@link #getScaledHeight}. If the source image is a YUV
+ * image, then this buffer should normally be stride * height
+ * pixels in size, where height is the height of the YUV image.
+ * However, the buffer may also be larger than the dimensions of the JPEG
+ * image, in which case the x, y, and
+ * stride parameters can be used to specify the region into
+ * which the source image should be decompressed.
*
* @param x x offset (in pixels) of the region in the destination image into
* which the source image should be decompressed/decoded
@@ -637,18 +646,18 @@ public class TJDecompressor implements Closeable {
* than the source image dimensions, then TurboJPEG will use scaling in the
* JPEG decompressor to generate the largest possible image that will fit
* within the desired dimensions. Setting this to 0 is the same as setting
- * it to the width of the JPEG image (in other words, the width will not be
+ * it to the width of the JPEG image. (In other words, the width will not be
* considered when determining the scaled image size.) This parameter is
* ignored if the source image is a YUV image.
*
- * @param stride pixels per line of the destination image. Normally, this
+ * @param stride pixels per row in the destination image. Normally this
* should be set to scaledWidth, but you can use this to, for
* instance, decompress the JPEG image into a region of a larger image.
* NOTE: if the source image is a JPEG image, then scaledWidth
- * can be determined by calling
- * scalingFactor.{@link TJScalingFactor#getScaled getScaled}(jpegWidth)
- * or by calling {@link #getScaledWidth}. If the source image is a
- * YUV image, then scaledWidth is the width of the YUV image.
+ * can be determined by calling
+ * scalingFactor.{@link TJScalingFactor#getScaled getScaled}(jpegWidth)
+ * or by calling {@link #getScaledWidth}. If the source image is a YUV
+ * image, then scaledWidth is the width of the YUV image.
* Setting this parameter to 0 is the equivalent of setting it to
* scaledWidth.
*
@@ -658,8 +667,8 @@ public class TJDecompressor implements Closeable {
* than the source image dimensions, then TurboJPEG will use scaling in the
* JPEG decompressor to generate the largest possible image that will fit
* within the desired dimensions. Setting this to 0 is the same as setting
- * it to the height of the JPEG image (in other words, the height will not be
- * considered when determining the scaled image size.) This parameter is
+ * it to the height of the JPEG image. (In other words, the height will not
+ * be considered when determining the scaled image size.) This parameter is
* ignored if the source image is a YUV image.
*
* @param pixelFormat pixel format of the decompressed image (one of
@@ -688,21 +697,22 @@ public class TJDecompressor implements Closeable {
}
/**
- * Decompress the JPEG source image or decode the YUV source image associated
- * with this decompressor instance and output a decompressed/decoded image to
- * the given BufferedImage instance.
+ * Decompress the JPEG source image or decode the planar YUV source image
+ * associated with this decompressor instance and output a packed-pixel
+ * decompressed/decoded image to the given BufferedImage
+ * instance.
*
- * NOTE: The output image is fully recoverable if this method throws a
+ * NOTE: The destination image is fully recoverable if this method throws a
* non-fatal {@link TJException} (unless
* {@link TJ#FLAG_STOPONWARNING TJ.FLAG_STOPONWARNING} is specified.)
*
* @param dstImage a BufferedImage instance that will receive
- * the decompressed/decoded image. If the source image is a JPEG image, then
- * the width and height of the BufferedImage instance must match
- * one of the scaled image sizes that TurboJPEG is capable of generating from
- * the JPEG image. If the source image is a YUV image, then the width and
- * height of the BufferedImage instance must match the width and
- * height of the YUV image.
+ * the packed-pixel decompressed/decoded image. If the source image is a
+ * JPEG image, then the width and height of the BufferedImage
+ * instance must match one of the scaled image sizes that the decompressor is
+ * capable of generating from the JPEG image. If the source image is a YUV
+ * image, then the width and height of the BufferedImage
+ * instance must match the width and height of the YUV image.
*
* @param flags the bitwise OR of one or more of
* {@link TJ#FLAG_BOTTOMUP TJ.FLAG_*}
@@ -725,7 +735,7 @@ public class TJDecompressor implements Closeable {
scaledWidth = getScaledWidth(desiredWidth, desiredHeight);
scaledHeight = getScaledHeight(desiredWidth, desiredHeight);
if (scaledWidth != desiredWidth || scaledHeight != desiredHeight)
- throw new IllegalArgumentException("BufferedImage dimensions do not match one of the scaled image sizes that TurboJPEG is capable of generating.");
+ throw new IllegalArgumentException("BufferedImage dimensions do not match one of the scaled image sizes that the decompressor is capable of generating.");
}
int pixelFormat; boolean intPixels = false;
if (byteOrder == null)
@@ -795,7 +805,7 @@ public class TJDecompressor implements Closeable {
/**
* Decompress the JPEG source image or decode the YUV source image associated
* with this decompressor instance and return a BufferedImage
- * instance containing the decompressed/decoded image.
+ * instance containing the packed-pixel decompressed/decoded image.
*
* @param desiredWidth see
* {@link #decompress(byte[], int, int, int, int, int, int, int)} for
@@ -812,7 +822,7 @@ public class TJDecompressor implements Closeable {
* @param flags the bitwise OR of one or more of
* {@link TJ#FLAG_BOTTOMUP TJ.FLAG_*}
*
- * @return a BufferedImage instance containing the
+ * @return a BufferedImage instance containing the packed-pixel
* decompressed/decoded image.
*/
public BufferedImage decompress(int desiredWidth, int desiredHeight,
diff --git a/java/org/libjpegturbo/turbojpeg/TJTransform.java b/java/org/libjpegturbo/turbojpeg/TJTransform.java
index 214768cf..db5472eb 100644
--- a/java/org/libjpegturbo/turbojpeg/TJTransform.java
+++ b/java/org/libjpegturbo/turbojpeg/TJTransform.java
@@ -1,5 +1,6 @@
/*
- * Copyright (C)2011, 2013, 2018, 2022 D. R. Commander. All Rights Reserved.
+ * Copyright (C)2011, 2013, 2018, 2022-2023 D. R. Commander.
+ * All Rights Reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
@@ -97,7 +98,7 @@ public class TJTransform extends Rectangle {
* the level of chrominance subsampling used. If the image's width or height
* is not evenly divisible by the MCU block size (see {@link TJ#getMCUWidth}
* and {@link TJ#getMCUHeight}), then there will be partial MCU blocks on the
- * right and/or bottom edges. It is not possible to move these partial MCU
+ * right and/or bottom edges. It is not possible to move these partial MCU
* blocks to the top or left of the image, so any transform that would
* require that is "imperfect." If this option is not specified, then any
* partial MCU blocks that cannot be transformed will be left in place, which
@@ -114,8 +115,8 @@ public class TJTransform extends Rectangle {
*/
public static final int OPT_CROP = (1 << 2);
/**
- * This option will discard the color data in the input image and produce
- * a grayscale output image.
+ * This option will discard the color data in the source image and produce a
+ * grayscale destination image.
*/
public static final int OPT_GRAY = (1 << 3);
/**
@@ -127,7 +128,7 @@ public class TJTransform extends Rectangle {
*/
public static final int OPT_NOOUTPUT = (1 << 4);
/**
- * This option will enable progressive entropy coding in the output image
+ * This option will enable progressive entropy coding in the JPEG image
* generated by this particular transform. Progressive entropy coding will
* generally improve compression relative to baseline entropy coding (the
* default), but it will reduce compression and decompression performance
@@ -137,11 +138,11 @@ public class TJTransform extends Rectangle {
/**
* This option will prevent {@link TJTransformer#transform
* TJTransformer.transform()} from copying any extra markers (including EXIF
- * and ICC profile data) from the source image to the output image.
+ * and ICC profile data) from the source image to the destination image.
*/
public static final int OPT_COPYNONE = (1 << 6);
/**
- * This option will enable arithmetic entropy coding in the output image
+ * This option will enable arithmetic entropy coding in the JPEG image
* generated by this particular transform. Arithmetic entropy coding will
* generally improve compression relative to Huffman entropy coding (the
* default), but it will reduce compression and decompression performance
@@ -173,10 +174,10 @@ public class TJTransform extends Rectangle {
* equivalent of setting it to (height of the source JPEG image -
* y).
*
- * @param op one of the transform operations (OP_*)
+ * @param op one of the transform operations ({@link #OP_NONE OP_*})
*
* @param options the bitwise OR of one or more of the transform options
- * (OPT_*)
+ * ({@link #OPT_PERFECT OPT_*})
*
* @param cf an instance of an object that implements the {@link
* TJCustomFilter} interface, or null if no custom filter is needed
@@ -198,10 +199,10 @@ public class TJTransform extends Rectangle {
* #TJTransform(int, int, int, int, int, int, TJCustomFilter)} for more
* detail.
*
- * @param op one of the transform operations (OP_*)
+ * @param op one of the transform operations ({@link #OP_NONE OP_*})
*
* @param options the bitwise OR of one or more of the transform options
- * (OPT_*)
+ * ({@link #OPT_PERFECT OPT_*})
*
* @param cf an instance of an object that implements the {@link
* TJCustomFilter} interface, or null if no custom filter is needed
@@ -216,13 +217,14 @@ public class TJTransform extends Rectangle {
}
/**
- * Transform operation (one of OP_*)
+ * Transform operation (one of {@link #OP_NONE OP_*})
*/
@SuppressWarnings("checkstyle:VisibilityModifier")
public int op = 0;
/**
- * Transform options (bitwise OR of one or more of OPT_*)
+ * Transform options (bitwise OR of one or more of
+ * {@link #OPT_PERFECT OPT_*})
*/
@SuppressWarnings("checkstyle:VisibilityModifier")
public int options = 0;
diff --git a/java/org/libjpegturbo/turbojpeg/TJTransformer.java b/java/org/libjpegturbo/turbojpeg/TJTransformer.java
index d7a56f35..2cbf0bfb 100644
--- a/java/org/libjpegturbo/turbojpeg/TJTransformer.java
+++ b/java/org/libjpegturbo/turbojpeg/TJTransformer.java
@@ -1,5 +1,5 @@
/*
- * Copyright (C)2011, 2013-2015 D. R. Commander. All Rights Reserved.
+ * Copyright (C)2011, 2013-2015, 2023 D. R. Commander. All Rights Reserved.
* Copyright (C)2015 Viktor Szathmáry. All Rights Reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -43,10 +43,12 @@ public class TJTransformer extends TJDecompressor {
/**
* Create a TurboJPEG lossless transformer instance and associate the JPEG
- * image stored in jpegImage with the newly created instance.
+ * source image stored in jpegImage with the newly created
+ * instance.
*
- * @param jpegImage JPEG image buffer (size of the JPEG image is assumed to
- * be the length of the array.) This buffer is not modified.
+ * @param jpegImage buffer containing the JPEG source image to transform.
+ * (The size of the JPEG image is assumed to be the length of the array.)
+ * This buffer is not modified.
*/
public TJTransformer(byte[] jpegImage) throws TJException {
init();
@@ -55,12 +57,13 @@ public class TJTransformer extends TJDecompressor {
/**
* Create a TurboJPEG lossless transformer instance and associate the JPEG
- * image of length imageSize bytes stored in
+ * source image of length imageSize bytes stored in
* jpegImage with the newly created instance.
*
- * @param jpegImage JPEG image buffer. This buffer is not modified.
+ * @param jpegImage buffer containing the JPEG source image to transform.
+ * This buffer is not modified.
*
- * @param imageSize size of the JPEG image (in bytes)
+ * @param imageSize size of the JPEG source image (in bytes)
*/
public TJTransformer(byte[] jpegImage, int imageSize) throws TJException {
init();
@@ -68,28 +71,29 @@ public class TJTransformer extends TJDecompressor {
}
/**
- * Losslessly transform the JPEG image associated with this transformer
- * instance into one or more JPEG images stored in the given destination
- * buffers. 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 method 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.
+ * Losslessly transform the JPEG source image associated with this
+ * transformer instance into one or more JPEG images stored in the given
+ * destination buffers. 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 method
+ * 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.
*
- * @param dstBufs an array of image buffers. dstbufs[i] will
- * receive a JPEG image that has been transformed using the parameters in
- * transforms[i]. Use {@link TJ#bufSize} to determine the
- * maximum size for each buffer based on the transformed or cropped width and
- * height and the level of subsampling used in the source image.
+ * @param dstBufs an array of JPEG destination buffers.
+ * dstbufs[i] will receive a JPEG image that has been
+ * transformed using the parameters in transforms[i]. Use
+ * {@link TJ#bufSize} to determine the maximum size for each buffer based on
+ * the transformed or cropped width and height and the level of subsampling
+ * used in the source image.
*
* @param transforms an array of {@link TJTransform} instances, each of
* which specifies the transform parameters and/or cropping region for the
- * corresponding transformed output image
+ * corresponding transformed JPEG image
*
* @param flags the bitwise OR of one or more of
* {@link TJ#FLAG_BOTTOMUP TJ.FLAG_*}
@@ -103,13 +107,13 @@ public class TJTransformer extends TJDecompressor {
}
/**
- * Losslessly transform the JPEG image associated with this transformer
- * instance and return an array of {@link TJDecompressor} instances, each of
- * which has a transformed JPEG image associated with it.
+ * Losslessly transform the JPEG source image associated with this
+ * transformer instance and return an array of {@link TJDecompressor}
+ * instances, each of which has a transformed JPEG image associated with it.
*
* @param transforms an array of {@link TJTransform} instances, each of
* which specifies the transform parameters and/or cropping region for the
- * corresponding transformed output image
+ * corresponding transformed JPEG image
*
* @param flags the bitwise OR of one or more of
* {@link TJ#FLAG_BOTTOMUP TJ.FLAG_*}
@@ -139,10 +143,10 @@ public class TJTransformer extends TJDecompressor {
/**
* Returns an array containing the sizes of the transformed JPEG images
- * generated by the most recent transform operation.
+ * (in bytes) generated by the most recent transform operation.
*
* @return an array containing the sizes of the transformed JPEG images
- * generated by the most recent transform operation.
+ * (in bytes) generated by the most recent transform operation.
*/
public int[] getTransformedSizes() {
if (transformedSizes == null)
diff --git a/java/org/libjpegturbo/turbojpeg/YUVImage.java b/java/org/libjpegturbo/turbojpeg/YUVImage.java
index 4da9843a..94830464 100644
--- a/java/org/libjpegturbo/turbojpeg/YUVImage.java
+++ b/java/org/libjpegturbo/turbojpeg/YUVImage.java
@@ -1,5 +1,5 @@
/*
- * Copyright (C)2014, 2017 D. R. Commander. All Rights Reserved.
+ * Copyright (C)2014, 2017, 2023 D. R. Commander. All Rights Reserved.
* Copyright (C)2015 Viktor Szathmáry. All Rights Reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -30,7 +30,7 @@
package org.libjpegturbo.turbojpeg;
/**
- * This class encapsulates a YUV planar image and the metadata
+ * This class encapsulates a planar YUV image and the metadata
* associated with it. The TurboJPEG API allows both the JPEG compression and
* decompression pipelines to be split into stages: YUV encode, compress from
* YUV, decompress to YUV, and YUV decode. A YUVImage instance
@@ -38,30 +38,32 @@ package org.libjpegturbo.turbojpeg;
* operations and as the source image for compress-from-YUV and YUV decode
* operations.
*
- * Technically, the JPEG format uses the YCbCr colorspace (which technically is - * not a "colorspace" but rather a "color transform"), but per the convention - * of the digital video community, the TurboJPEG API uses "YUV" to refer to an - * image format consisting of Y, Cb, and Cr image planes. + * Technically, the JPEG format uses the YCbCr colorspace (which is technically + * not a colorspace but a color transform), but per the convention of the + * digital video community, the TurboJPEG API uses "YUV" to refer to an image + * format consisting of Y, Cb, and Cr image planes. *
* Each plane is simply a 2D array of bytes, each byte representing the value * of one of the components (Y, Cb, or Cr) at a particular location in the * image. The width and height of each plane are determined by the image * width, height, and level of chrominance subsampling. The luminance plane * width is the image width padded to the nearest multiple of the horizontal - * subsampling factor (2 in the case of 4:2:0 and 4:2:2, 4 in the case of - * 4:1:1, 1 in the case of 4:4:4 or grayscale.) Similarly, the luminance plane - * height is the image height padded to the nearest multiple of the vertical - * subsampling factor (2 in the case of 4:2:0 or 4:4:0, 1 in the case of 4:4:4 - * or grayscale.) The chrominance plane width is equal to the luminance plane - * width divided by the horizontal subsampling factor, and the chrominance - * plane height is equal to the luminance plane height divided by the vertical - * subsampling factor. + * subsampling factor (1 in the case of 4:4:4, grayscale, or 4:4:0; 2 in the + * case of 4:2:2 or 4:2:0; 4 in the case of 4:1:1.) Similarly, the luminance + * plane height is the image height padded to the nearest multiple of the + * vertical subsampling factor (1 in the case of 4:4:4, 4:2:2, grayscale, or + * 4:1:1; 2 in the case of 4:2:0 or 4:4:0.) This is irrespective of any + * additional padding that may be specified as an argument to the various + * YUVImage methods. The chrominance plane width is equal to the luminance + * plane width divided by the horizontal subsampling factor, and the + * chrominance plane height is equal to the luminance plane height divided by + * the vertical subsampling factor. *
* For example, if the source image is 35 x 35 pixels and 4:2:2 subsampling is
* used, then the luminance plane would be 36 x 35 bytes, and each of the
- * chrominance planes would be 18 x 35 bytes. If you specify a line padding of
- * 4 bytes on top of this, then the luminance plane would be 36 x 35 bytes, and
- * each of the chrominance planes would be 20 x 35 bytes.
+ * chrominance planes would be 18 x 35 bytes. If you specify a row alignment
+ * of 4 bytes on top of this, then the luminance plane would be 36 x 35 bytes,
+ * and each of the chrominance planes would be 20 x 35 bytes.
*/
public class YUVImage {
@@ -75,7 +77,7 @@ public class YUVImage {
* @param width width (in pixels) of the YUV image
*
* @param strides an array of integers, each specifying the number of bytes
- * per line in the corresponding plane of the YUV image. Setting the stride
+ * per row in the corresponding plane of the YUV image. Setting the stride
* for any plane to 0 is the same as setting it to the plane width (see
* {@link YUVImage above}.) If strides is null, then the
* strides for all planes will be set to their respective plane widths. When
@@ -92,22 +94,24 @@ public class YUVImage {
}
/**
- * Create a new YUVImage instance backed by a unified image
- * buffer, and allocate memory for the image buffer.
+ * Create a new YUVImage instance backed by a unified buffer,
+ * and allocate memory for the buffer.
*
* @param width width (in pixels) of the YUV image
*
- * @param pad Each line of each plane in the YUV image buffer will be padded
- * to this number of bytes (must be a power of 2.)
+ * @param align row alignment (in bytes) of the YUV image (must be a power of
+ * 2.) Setting this parameter to n specifies that each row in each plane of
+ * the YUV image will be padded to the nearest multiple of n bytes
+ * (1 = unpadded.)
*
* @param height height (in pixels) of the YUV image
*
* @param subsamp the level of chrominance subsampling to be used in the YUV
* image (one of {@link TJ#SAMP_444 TJ.SAMP_*})
*/
- public YUVImage(int width, int pad, int height, int subsamp) {
- setBuf(new byte[TJ.bufSizeYUV(width, pad, height, subsamp)], width, pad,
- height, subsamp);
+ public YUVImage(int width, int align, int height, int subsamp) {
+ setBuf(new byte[TJ.bufSizeYUV(width, align, height, subsamp)], width,
+ align, height, subsamp);
}
/**
@@ -117,8 +121,8 @@ public class YUVImage {
* @param planes an array of buffers representing the Y, U (Cb), and V (Cr)
* image planes (or just the Y plane, if the image is grayscale.) These
* planes can be contiguous or non-contiguous in memory. Plane
- * i should be at least offsets[i] +
- * {@link TJ#planeSizeYUV TJ.planeSizeYUV}(i, width, strides[i], height, subsamp)
+ * i should be at least offsets[i] +
+ * {@link TJ#planeSizeYUV TJ.planeSizeYUV}(i, width, strides[i], height, subsamp)
* bytes in size.
*
* @param offsets If this YUVImage instance represents a
@@ -130,11 +134,11 @@ public class YUVImage {
* @param width width (in pixels) of the new YUV image (or subregion)
*
* @param strides an array of integers, each specifying the number of bytes
- * per line in the corresponding plane of the YUV image. Setting the stride
+ * per row in the corresponding plane of the YUV image. Setting the stride
* for any plane to 0 is the same as setting it to the plane width (see
* {@link YUVImage above}.) If strides is null, then the
* strides for all planes will be set to their respective plane widths. You
- * can adjust the strides in order to add an arbitrary amount of line padding
+ * can adjust the strides in order to add an arbitrary amount of row padding
* to each plane or to specify that this YUVImage instance is a
* subregion of a larger image (in which case, strides[i] should
* be set to the plane width of plane i in the larger image.)
@@ -150,29 +154,30 @@ public class YUVImage {
}
/**
- * Create a new YUVImage instance from an existing unified image
+ * Create a new YUVImage instance from an existing unified
* buffer.
*
- * @param yuvImage image buffer that contains or will contain YUV planar
- * image data. Use {@link TJ#bufSizeYUV} to determine the minimum size for
- * this buffer. The Y, U (Cb), and V (Cr) image planes are stored
- * sequentially in the buffer (see {@link YUVImage above} for a description
- * of the image format.)
+ * @param yuvImage buffer that contains or will receive a unified planar YUV
+ * image. Use {@link TJ#bufSizeYUV} to determine the minimum size for this
+ * buffer. The Y, U (Cb), and V (Cr) image planes are stored sequentially in
+ * the buffer. (See {@link YUVImage above} for a description of the image
+ * format.)
*
* @param width width (in pixels) of the YUV image
*
- * @param pad the line padding used in the YUV image buffer. For
- * instance, if each line in each plane of the buffer is padded to the
- * nearest multiple of 4 bytes, then pad should be set to 4.
+ * @param align row alignment (in bytes) of the YUV image (must be a power of
+ * 2.) Setting this parameter to n specifies that each row in each plane of
+ * the YUV image will be padded to the nearest multiple of n bytes
+ * (1 = unpadded.)
*
* @param height height (in pixels) of the YUV image
*
* @param subsamp the level of chrominance subsampling used in the YUV
* image (one of {@link TJ#SAMP_444 TJ.SAMP_*})
*/
- public YUVImage(byte[] yuvImage, int width, int pad, int height,
+ public YUVImage(byte[] yuvImage, int width, int align, int height,
int subsamp) {
- setBuf(yuvImage, width, pad, height, subsamp);
+ setBuf(yuvImage, width, align, height, subsamp);
}
/**
@@ -181,8 +186,8 @@ public class YUVImage {
* @param planes an array of buffers representing the Y, U (Cb), and V (Cr)
* image planes (or just the Y plane, if the image is grayscale.) These
* planes can be contiguous or non-contiguous in memory. Plane
- * i should be at least offsets[i] +
- * {@link TJ#planeSizeYUV TJ.planeSizeYUV}(i, width, strides[i], height, subsamp)
+ * i should be at least offsets[i] +
+ * {@link TJ#planeSizeYUV TJ.planeSizeYUV}(i, width, strides[i], height, subsamp)
* bytes in size.
*
* @param offsets If this YUVImage instance represents a
@@ -194,12 +199,12 @@ public class YUVImage {
* @param width width (in pixels) of the YUV image (or subregion)
*
* @param strides an array of integers, each specifying the number of bytes
- * per line in the corresponding plane of the YUV image. Setting the stride
+ * per row in the corresponding plane of the YUV image. Setting the stride
* for any plane to 0 is the same as setting it to the plane width (see
* {@link YUVImage above}.) If strides is null, then the
* strides for all planes will be set to their respective plane widths. You
- * can adjust the strides in order to add an arbitrary amount of line padding
- * to each plane or to specify that this YUVImage image is a
+ * can adjust the strides in order to add an arbitrary amount of row padding
+ * to each plane or to specify that this YUVImage instance is a
* subregion of a larger image (in which case, strides[i] should
* be set to the plane width of plane i in the larger image.)
*
@@ -263,32 +268,34 @@ public class YUVImage {
}
/**
- * Assign a unified image buffer to this YUVImage instance.
+ * Assign a unified buffer to this YUVImage instance.
*
- * @param yuvImage image buffer that contains or will contain YUV planar
- * image data. Use {@link TJ#bufSizeYUV} to determine the minimum size for
- * this buffer. The Y, U (Cb), and V (Cr) image planes are stored
- * sequentially in the buffer (see {@link YUVImage above} for a description
- * of the image format.)
+ * @param yuvImage buffer that contains or will receive a unified planar YUV
+ * image. Use {@link TJ#bufSizeYUV} to determine the minimum size for this
+ * buffer. The Y, U (Cb), and V (Cr) image planes are stored sequentially in
+ * the buffer. (See {@link YUVImage above} for a description of the image
+ * format.)
*
* @param width width (in pixels) of the YUV image
*
- * @param pad the line padding used in the YUV image buffer. For
- * instance, if each line in each plane of the buffer is padded to the
- * nearest multiple of 4 bytes, then pad should be set to 4.
+ * @param align row alignment (in bytes) of the YUV image (must be a power of
+ * 2.) Setting this parameter to n specifies that each row in each plane of
+ * the YUV image will be padded to the nearest multiple of n bytes
+ * (1 = unpadded.)
*
* @param height height (in pixels) of the YUV image
*
* @param subsamp the level of chrominance subsampling used in the YUV
* image (one of {@link TJ#SAMP_444 TJ.SAMP_*})
*/
- public void setBuf(byte[] yuvImage, int width, int pad, int height,
+ public void setBuf(byte[] yuvImage, int width, int align, int height,
int subsamp) {
- if (yuvImage == null || width < 1 || pad < 1 || ((pad & (pad - 1)) != 0) ||
- height < 1 || subsamp < 0 || subsamp >= TJ.NUMSAMP)
+ if (yuvImage == null || width < 1 || align < 1 ||
+ ((align & (align - 1)) != 0) || height < 1 || subsamp < 0 ||
+ subsamp >= TJ.NUMSAMP)
throw new IllegalArgumentException("Invalid argument in YUVImage::setBuf()");
- if (yuvImage.length < TJ.bufSizeYUV(width, pad, height, subsamp))
- throw new IllegalArgumentException("YUV image buffer is not large enough");
+ if (yuvImage.length < TJ.bufSizeYUV(width, align, height, subsamp))
+ throw new IllegalArgumentException("YUV buffer is not large enough");
int nc = (subsamp == TJ.SAMP_GRAY ? 1 : 3);
byte[][] planes = new byte[nc][];
@@ -296,9 +303,9 @@ public class YUVImage {
int[] offsets = new int[nc];
planes[0] = yuvImage;
- strides[0] = pad(TJ.planeWidth(0, width, subsamp), pad);
+ strides[0] = pad(TJ.planeWidth(0, width, subsamp), align);
if (subsamp != TJ.SAMP_GRAY) {
- strides[1] = strides[2] = pad(TJ.planeWidth(1, width, subsamp), pad);
+ strides[1] = strides[2] = pad(TJ.planeWidth(1, width, subsamp), align);
planes[1] = planes[2] = yuvImage;
offsets[1] = offsets[0] +
strides[0] * TJ.planeHeight(0, height, subsamp);
@@ -306,7 +313,7 @@ public class YUVImage {
strides[1] * TJ.planeHeight(1, height, subsamp);
}
- yuvPad = pad;
+ yuvAlign = align;
setBuf(planes, offsets, width, strides, height, subsamp);
}
@@ -333,23 +340,23 @@ public class YUVImage {
}
/**
- * Returns the line padding used in the YUV image buffer (if this image is
+ * Returns the row alignment (in bytes) of the YUV buffer (if this image is
* stored in a unified buffer rather than separate image planes.)
*
- * @return the line padding used in the YUV image buffer
+ * @return the row alignment of the YUV buffer
*/
public int getPad() {
if (yuvPlanes == null)
throw new IllegalStateException(NO_ASSOC_ERROR);
- if (yuvPad < 1 || ((yuvPad & (yuvPad - 1)) != 0))
+ if (yuvAlign < 1 || ((yuvAlign & (yuvAlign - 1)) != 0))
throw new IllegalStateException("Image is not stored in a unified buffer");
- return yuvPad;
+ return yuvAlign;
}
/**
- * Returns the number of bytes per line of each plane in the YUV image.
+ * Returns the number of bytes per row of each plane in the YUV image.
*
- * @return the number of bytes per line of each plane in the YUV image
+ * @return the number of bytes per row of each plane in the YUV image
*/
public int[] getStrides() {
if (yuvStrides == null)
@@ -395,10 +402,10 @@ public class YUVImage {
}
/**
- * Returns the YUV image buffer (if this image is stored in a unified
- * buffer rather than separate image planes.)
+ * Returns the YUV buffer (if this image is stored in a unified buffer rather
+ * than separate image planes.)
*
- * @return the YUV image buffer
+ * @return the YUV buffer
*/
public byte[] getBuf() {
if (yuvPlanes == null || yuvSubsamp < 0 || yuvSubsamp >= TJ.NUMSAMP)
@@ -412,22 +419,22 @@ public class YUVImage {
}
/**
- * Returns the size (in bytes) of the YUV image buffer (if this image is
- * stored in a unified buffer rather than separate image planes.)
+ * Returns the size (in bytes) of the YUV buffer (if this image is stored in
+ * a unified buffer rather than separate image planes.)
*
- * @return the size (in bytes) of the YUV image buffer
+ * @return the size (in bytes) of the YUV buffer
*/
public int getSize() {
if (yuvPlanes == null || yuvSubsamp < 0 || yuvSubsamp >= TJ.NUMSAMP)
throw new IllegalStateException(NO_ASSOC_ERROR);
int nc = (yuvSubsamp == TJ.SAMP_GRAY ? 1 : 3);
- if (yuvPad < 1)
+ if (yuvAlign < 1)
throw new IllegalStateException("Image is not stored in a unified buffer");
for (int i = 1; i < nc; i++) {
if (yuvPlanes[i] != yuvPlanes[0])
throw new IllegalStateException("Image is not stored in a unified buffer");
}
- return TJ.bufSizeYUV(yuvWidth, yuvPad, yuvHeight, yuvSubsamp);
+ return TJ.bufSizeYUV(yuvWidth, yuvAlign, yuvHeight, yuvSubsamp);
}
private static int pad(int v, int p) {
@@ -438,7 +445,7 @@ public class YUVImage {
protected byte[][] yuvPlanes = null;
protected int[] yuvOffsets = null;
protected int[] yuvStrides = null;
- protected int yuvPad = 0;
+ protected int yuvAlign = 1;
protected int yuvWidth = 0;
protected int yuvHeight = 0;
protected int yuvSubsamp = -1;
diff --git a/jversion.h.in b/jversion.h.in
index d1a8d989..42a4e736 100644
--- a/jversion.h.in
+++ b/jversion.h.in
@@ -4,7 +4,7 @@
* This file was part of the Independent JPEG Group's software:
* Copyright (C) 1991-2020, Thomas G. Lane, Guido Vollbeding.
* libjpeg-turbo Modifications:
- * Copyright (C) 2010, 2012-2022, D. R. Commander.
+ * Copyright (C) 2010, 2012-2023, D. R. Commander.
* For conditions of distribution and use, see the accompanying README.ijg
* file.
*
@@ -37,7 +37,7 @@
*/
#define JCOPYRIGHT \
- "Copyright (C) 2009-2022 D. R. Commander\n" \
+ "Copyright (C) 2009-2023 D. R. Commander\n" \
"Copyright (C) 2015, 2020 Google, Inc.\n" \
"Copyright (C) 2019-2020 Arm Limited\n" \
"Copyright (C) 2015-2016, 2018 Matthieu Darbois\n" \
diff --git a/tjbench.c b/tjbench.c
index cfda0dc0..0456e609 100644
--- a/tjbench.c
+++ b/tjbench.c
@@ -1,5 +1,5 @@
/*
- * Copyright (C)2009-2019, 2021-2022 D. R. Commander. All Rights Reserved.
+ * Copyright (C)2009-2019, 2021-2023 D. R. Commander. All Rights Reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
@@ -82,7 +82,7 @@ int tjErrorLine = -1, tjErrorCode = -1;
}
int flags = TJFLAG_NOREALLOC, compOnly = 0, decompOnly = 0, doYUV = 0,
- quiet = 0, doTile = 0, pf = TJPF_BGR, yuvPad = 1, doWrite = 1;
+ quiet = 0, doTile = 0, pf = TJPF_BGR, yuvAlign = 1, doWrite = 1;
char *ext = "ppm";
const char *pixFormatStr[TJ_NUMPF] = {
"RGB", "BGR", "RGBX", "BGRX", "XBGR", "XRGB", "GRAY", "", "", "", "", "CMYK"
@@ -187,7 +187,7 @@ static int decomp(unsigned char *srcBuf, unsigned char **jpegBuf,
if (doYUV) {
int width = doTile ? tilew : scaledw;
int height = doTile ? tileh : scaledh;
- unsigned long yuvSize = tjBufSizeYUV2(width, yuvPad, height, subsamp);
+ unsigned long yuvSize = tjBufSizeYUV2(width, yuvAlign, height, subsamp);
if (yuvSize == (unsigned long)-1)
THROW_TJ("allocating YUV buffer");
@@ -214,10 +214,10 @@ static int decomp(unsigned char *srcBuf, unsigned char **jpegBuf,
double startDecode;
if (tjDecompressToYUV2(handle, jpegBuf[tile], jpegSize[tile], yuvBuf,
- width, yuvPad, height, flags) == -1)
+ width, yuvAlign, height, flags) == -1)
THROW_TJ("executing tjDecompressToYUV2()");
startDecode = getTime();
- if (tjDecodeYUV(handle, yuvBuf, yuvPad, subsamp, dstPtr2, width,
+ if (tjDecodeYUV(handle, yuvBuf, yuvAlign, subsamp, dstPtr2, width,
pitch, height, pf, flags) == -1)
THROW_TJ("executing tjDecodeYUV()");
if (iter >= 0) elapsedDecode += getTime() - startDecode;
@@ -283,7 +283,7 @@ static int decomp(unsigned char *srcBuf, unsigned char **jpegBuf,
SNPRINTF(ptr, 1024 - (ptr - tempStr), "-err.%s", ext);
if (srcBuf && sf.num == 1 && sf.denom == 1) {
if (!quiet) printf("Compression error written to %s.\n", tempStr);
- if (subsamp == TJ_GRAYSCALE) {
+ if (subsamp == TJSAMP_GRAY) {
unsigned long index, index2;
for (row = 0, index = 0; row < h; row++, index += pitch) {
@@ -385,7 +385,7 @@ static int fullTest(unsigned char *srcBuf, int w, int h, int subsamp,
THROW_TJ("executing tjInitCompress()");
if (doYUV) {
- yuvSize = tjBufSizeYUV2(tilew, yuvPad, tileh, subsamp);
+ yuvSize = tjBufSizeYUV2(tilew, yuvAlign, tileh, subsamp);
if (yuvSize == (unsigned long)-1)
THROW_TJ("allocating YUV buffer");
if ((yuvBuf = (unsigned char *)malloc(yuvSize)) == NULL)
@@ -412,10 +412,10 @@ static int fullTest(unsigned char *srcBuf, int w, int h, int subsamp,
double startEncode = getTime();
if (tjEncodeYUV3(handle, srcPtr2, width, pitch, height, pf, yuvBuf,
- yuvPad, subsamp, flags) == -1)
+ yuvAlign, subsamp, flags) == -1)
THROW_TJ("executing tjEncodeYUV3()");
if (iter >= 0) elapsedEncode += getTime() - startEncode;
- if (tjCompressFromYUV(handle, yuvBuf, width, yuvPad, height,
+ if (tjCompressFromYUV(handle, yuvBuf, width, yuvAlign, height,
subsamp, &jpegBuf[tile], &jpegSize[tile],
jpegQual, flags) == -1)
THROW_TJ("executing tjCompressFromYUV()");
@@ -637,7 +637,7 @@ static int decompTest(char *fileName)
tw = h; th = w; ttilew = tileh; ttileh = tilew;
}
- if (xformOpt & TJXOPT_GRAY) tsubsamp = TJ_GRAYSCALE;
+ if (xformOpt & TJXOPT_GRAY) tsubsamp = TJSAMP_GRAY;
if (xformOp == TJXOP_HFLIP || xformOp == TJXOP_ROT180)
tw = tw - (tw % tjMCUWidth[tsubsamp]);
if (xformOp == TJXOP_VFLIP || xformOp == TJXOP_ROT180)
@@ -794,8 +794,8 @@ static void usage(char *progName)
printf("-quiet = Output results in tabular rather than verbose format\n");
printf("-yuv = Test YUV encoding/decoding functions\n");
printf("-yuvpad
= If testing YUV encoding/decoding, this specifies the number of\n"); - printf(" bytes to which each row of each plane in the intermediate YUV image is\n"); - printf(" padded (default = 1)\n"); + printf(" bytes by which each row of each plane in the intermediate YUV image is\n"); + printf(" evenly divisible (default = 1)\n"); printf("-scale M/N = Scale down the width/height of the decompressed JPEG image by a\n"); printf(" factor of M/N (M/N = "); for (i = 0; i < nsf; i++) { @@ -962,12 +962,12 @@ int main(int argc, char *argv[]) else if (!strcasecmp(argv[i], "-bmp")) ext = "bmp"; else if (!strcasecmp(argv[i], "-yuv")) { - printf("Testing YUV planar encoding/decoding\n\n"); + printf("Testing planar YUV encoding/decoding\n\n"); doYUV = 1; } else if (!strcasecmp(argv[i], "-yuvpad") && i < argc - 1) { int tempi = atoi(argv[++i]); - if (tempi >= 1) yuvPad = tempi; + if (tempi >= 1) yuvAlign = tempi; } else if (!strcasecmp(argv[i], "-subsamp") && i < argc - 1) { i++; if (toupper(argv[i][0]) == 'G') subsamp = TJSAMP_GRAY; diff --git a/tjunittest.c b/tjunittest.c index f010be25..d903b4fd 100644 --- a/tjunittest.c +++ b/tjunittest.c @@ -1,6 +1,6 @@ /* - * Copyright (C)2009-2014, 2017-2019, 2022 D. R. Commander. - * All Rights Reserved. + * Copyright (C)2009-2014, 2017-2019, 2022-2023 D. R. Commander. + * All Rights Reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are met: @@ -57,7 +57,7 @@ static void usage(char *progName) printf("Options:\n"); printf("-yuv = test YUV encoding/decoding support\n"); printf("-noyuvpad = do not pad each line of each Y, U, and V plane to the nearest\n"); - printf(" 4-byte boundary\n"); + printf(" multiple of 4 bytes\n"); printf("-lossless = test lossless JPEG compression/decompression\n"); printf("-alloc = test automatic buffer allocation\n"); printf("-bmp = tjLoadImage()/tjSaveImage() unit test\n\n"); @@ -96,7 +96,7 @@ const int _4byteFormats[] = { const int _onlyGray[] = { TJPF_GRAY }; const int _onlyRGB[] = { TJPF_RGB }; -int doYUV = 0, lossless = 0, alloc = 0, pad = 4, psv = 1; +int doYUV = 0, lossless = 0, alloc = 0, yuvAlign = 4, psv = 1; int exitStatus = 0; #define BAILOUT() { exitStatus = -1; goto bailout; } @@ -283,7 +283,7 @@ static int checkBufYUV(unsigned char *buf, int w, int h, int subsamp, int hsf = tjMCUWidth[subsamp] / 8, vsf = tjMCUHeight[subsamp] / 8; int pw = PAD(w, hsf), ph = PAD(h, vsf); int cw = pw / hsf, ch = ph / vsf; - int ypitch = PAD(pw, pad), uvpitch = PAD(cw, pad); + int ypitch = PAD(pw, yuvAlign), uvpitch = PAD(cw, yuvAlign); int retval = 1; int halfway = 16 * sf.num / sf.denom; int blocksize = 8 * sf.num / sf.denom; @@ -382,7 +382,7 @@ static void compTest(tjhandle handle, unsigned char **dstBuf, if (!alloc) flags |= TJFLAG_NOREALLOC; if (doYUV) { - unsigned long yuvSize = tjBufSizeYUV2(w, pad, h, subsamp); + unsigned long yuvSize = tjBufSizeYUV2(w, yuvAlign, h, subsamp); tjscalingfactor sf = { 1, 1 }; tjhandle handle2 = tjInitCompress(); @@ -393,15 +393,15 @@ static void compTest(tjhandle handle, unsigned char **dstBuf, memset(yuvBuf, 0, yuvSize); printf("%s %s -> YUV %s ... ", pfStr, buStrLong, subNameLong[subsamp]); - TRY_TJ(tjEncodeYUV3(handle2, srcBuf, w, 0, h, pf, yuvBuf, pad, subsamp, - flags)); + TRY_TJ(tjEncodeYUV3(handle2, srcBuf, w, 0, h, pf, yuvBuf, yuvAlign, + subsamp, flags)); tjDestroy(handle2); if (checkBufYUV(yuvBuf, w, h, subsamp, sf)) printf("Passed.\n"); else printf("FAILED!\n"); printf("YUV %s %s -> JPEG Q%d ... ", subNameLong[subsamp], buStrLong, jpegQual); - TRY_TJ(tjCompressFromYUV(handle, yuvBuf, w, pad, h, subsamp, dstBuf, + TRY_TJ(tjCompressFromYUV(handle, yuvBuf, w, yuvAlign, h, subsamp, dstBuf, dstSize, jpegQual, flags)); } else { printf("%s %s -> %s Q%d ... ", pfStr, buStrLong, subNameLong[subsamp], @@ -445,7 +445,7 @@ static void _decompTest(tjhandle handle, unsigned char *jpegBuf, memset(dstBuf, 0, dstSize); if (doYUV) { - unsigned long yuvSize = tjBufSizeYUV2(scaledWidth, pad, scaledHeight, + unsigned long yuvSize = tjBufSizeYUV2(scaledWidth, yuvAlign, scaledHeight, subsamp); tjhandle handle2 = tjInitDecompress(); @@ -459,16 +459,20 @@ static void _decompTest(tjhandle handle, unsigned char *jpegBuf, if (sf.num != 1 || sf.denom != 1) printf("%d/%d ... ", sf.num, sf.denom); else printf("... "); - TRY_TJ(tjDecompressToYUV2(handle, jpegBuf, jpegSize, yuvBuf, scaledWidth, - pad, scaledHeight, flags)); + /* We pass scaledWidth + 1 and scaledHeight + 1 to validate that + tjDecompressToYUV2() generates the largest possible scaled image that + fits within the desired dimensions, as documented. */ + TRY_TJ(tjDecompressToYUV2(handle, jpegBuf, jpegSize, yuvBuf, + scaledWidth + 1, yuvAlign, scaledHeight + 1, + flags)); if (checkBufYUV(yuvBuf, scaledWidth, scaledHeight, subsamp, sf)) printf("Passed.\n"); else printf("FAILED!\n"); printf("YUV %s -> %s %s ... ", subNameLong[subsamp], pixFormatStr[pf], (flags & TJFLAG_BOTTOMUP) ? "Bottom-Up" : "Top-Down "); - TRY_TJ(tjDecodeYUV(handle2, yuvBuf, pad, subsamp, dstBuf, scaledWidth, 0, - scaledHeight, pf, flags)); + TRY_TJ(tjDecodeYUV(handle2, yuvBuf, yuvAlign, subsamp, dstBuf, scaledWidth, + 0, scaledHeight, pf, flags)); tjDestroy(handle2); } else { printf("JPEG -> %s %s ", pixFormatStr[pf], @@ -476,8 +480,11 @@ static void _decompTest(tjhandle handle, unsigned char *jpegBuf, if (sf.num != 1 || sf.denom != 1) printf("%d/%d ... ", sf.num, sf.denom); else printf("... "); - TRY_TJ(tjDecompress2(handle, jpegBuf, jpegSize, dstBuf, scaledWidth, 0, - scaledHeight, pf, flags)); + /* We pass scaledWidth + 1 and scaledHeight + 1 to validate that + tjDecompress2() generates the largest possible scaled image that fits + within the desired dimensions, as documented. */ + TRY_TJ(tjDecompress2(handle, jpegBuf, jpegSize, dstBuf, scaledWidth + 1, 0, + scaledHeight + 1, pf, flags)); } if (checkBuf(dstBuf, scaledWidth, scaledHeight, pf, subsamp, sf, flags)) @@ -597,6 +604,10 @@ static void overflowTest(void) CHECKSIZE(TJBUFSIZE()); size = tjBufSizeYUV2(37838, 1, 37838, TJSAMP_444); CHECKSIZE(tjBufSizeYUV2()); + size = tjBufSizeYUV2(37837, 3, 37837, TJSAMP_444); + CHECKSIZE(tjBufSizeYUV2()); + size = tjBufSizeYUV2(37837, -1, 37837, TJSAMP_444); + CHECKSIZE(tjBufSizeYUV2()); size = TJBUFSIZEYUV(37838, 37838, TJSAMP_444); CHECKSIZE(TJBUFSIZEYUV()); size = tjBufSizeYUV(37838, 37838, TJSAMP_444); @@ -636,7 +647,7 @@ static void bufSizeTest(void) if ((srcBuf = (unsigned char *)malloc(w * h * 4)) == NULL) THROW("Memory allocation failure"); if (!alloc || doYUV) { - if (doYUV) dstSize = tjBufSizeYUV2(w, pad, h, subsamp); + if (doYUV) dstSize = tjBufSizeYUV2(w, yuvAlign, h, subsamp); else dstSize = tjBufSize(w, h, subsamp); if ((dstBuf = (unsigned char *)tjAlloc(dstSize)) == NULL) THROW("Memory allocation failure"); @@ -648,8 +659,8 @@ static void bufSizeTest(void) } if (doYUV) { - TRY_TJ(tjEncodeYUV3(handle, srcBuf, w, 0, h, TJPF_BGRX, dstBuf, pad, - subsamp, 0)); + TRY_TJ(tjEncodeYUV3(handle, srcBuf, w, 0, h, TJPF_BGRX, dstBuf, + yuvAlign, subsamp, 0)); } else { TRY_TJ(tjCompress2(handle, srcBuf, w, 0, h, TJPF_BGRX, &dstBuf, &dstSize, subsamp, quality, flags)); @@ -662,7 +673,7 @@ static void bufSizeTest(void) if ((srcBuf = (unsigned char *)malloc(h * w * 4)) == NULL) THROW("Memory allocation failure"); if (!alloc || doYUV) { - if (doYUV) dstSize = tjBufSizeYUV2(h, pad, w, subsamp); + if (doYUV) dstSize = tjBufSizeYUV2(h, yuvAlign, w, subsamp); else dstSize = tjBufSize(h, w, subsamp); if ((dstBuf = (unsigned char *)tjAlloc(dstSize)) == NULL) THROW("Memory allocation failure"); @@ -674,8 +685,8 @@ static void bufSizeTest(void) } if (doYUV) { - TRY_TJ(tjEncodeYUV3(handle, srcBuf, h, 0, w, TJPF_BGRX, dstBuf, pad, - subsamp, 0)); + TRY_TJ(tjEncodeYUV3(handle, srcBuf, h, 0, w, TJPF_BGRX, dstBuf, + yuvAlign, subsamp, 0)); } else { TRY_TJ(tjCompress2(handle, srcBuf, h, 0, w, TJPF_BGRX, &dstBuf, &dstSize, subsamp, quality, flags)); @@ -918,7 +929,7 @@ int main(int argc, char *argv[]) if (argc > 1) { for (i = 1; i < argc; i++) { if (!strcasecmp(argv[i], "-yuv")) doYUV = 1; - else if (!strcasecmp(argv[i], "-noyuvpad")) pad = 1; + else if (!strcasecmp(argv[i], "-noyuvpad")) yuvAlign = 1; else if (!strcasecmp(argv[i], "-lossless")) lossless = 1; else if (!strcasecmp(argv[i], "-alloc")) alloc = 1; else if (!strcasecmp(argv[i], "-bmp")) return bmpTest(); diff --git a/turbojpeg-jni.c b/turbojpeg-jni.c index ec59bb80..f886a8ec 100644 --- a/turbojpeg-jni.c +++ b/turbojpeg-jni.c @@ -1,5 +1,5 @@ /* - * Copyright (C)2011-2022 D. R. Commander. All Rights Reserved. + * Copyright (C)2011-2023 D. R. Commander. All Rights Reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are met: @@ -142,9 +142,9 @@ bailout: /* TurboJPEG 1.4.x: TJ::bufSizeYUV() */ JNIEXPORT jint JNICALL Java_org_libjpegturbo_turbojpeg_TJ_bufSizeYUV__IIII - (JNIEnv *env, jclass cls, jint width, jint pad, jint height, jint subsamp) + (JNIEnv *env, jclass cls, jint width, jint align, jint height, jint subsamp) { - jint retval = (jint)tjBufSizeYUV2(width, pad, height, subsamp); + jint retval = (jint)tjBufSizeYUV2(width, align, height, subsamp); if (retval == -1) THROW_ARG(tjGetErrorStr()); diff --git a/turbojpeg-mapfile b/turbojpeg-mapfile index 34995b12..9d2b7daf 100644 --- a/turbojpeg-mapfile +++ b/turbojpeg-mapfile @@ -1,14 +1,14 @@ TURBOJPEG_1.0 { global: - tjInitCompress; - tjCompress; TJBUFSIZE; - tjInitDecompress; - tjDecompressHeader; + tjCompress; tjDecompress; + tjDecompressHeader; tjDestroy; tjGetErrorStr; + tjInitCompress; + tjInitDecompress; local: *; }; diff --git a/turbojpeg-mapfile.jni b/turbojpeg-mapfile.jni index f86209d1..5e301138 100644 --- a/turbojpeg-mapfile.jni +++ b/turbojpeg-mapfile.jni @@ -1,14 +1,14 @@ TURBOJPEG_1.0 { global: - tjInitCompress; - tjCompress; TJBUFSIZE; - tjInitDecompress; - tjDecompressHeader; + tjCompress; tjDecompress; + tjDecompressHeader; tjDestroy; tjGetErrorStr; + tjInitCompress; + tjInitDecompress; local: *; }; diff --git a/turbojpeg.c b/turbojpeg.c index 9c59265d..6d32edca 100644 --- a/turbojpeg.c +++ b/turbojpeg.c @@ -1,5 +1,5 @@ /* - * Copyright (C)2009-2022 D. R. Commander. All Rights Reserved. + * Copyright (C)2009-2023 D. R. Commander. All Rights Reserved. * Copyright (C)2021 Alex Richardson. All Rights Reserved. * * Redistribution and use in source and binary forms, with or without @@ -97,7 +97,7 @@ static void my_emit_message(j_common_ptr cinfo, int msg_level) } -/* Global structures, macros, etc. */ +/********************** Global structures, macros, etc. **********************/ enum { COMPRESS = 1, DECOMPRESS = 2 }; @@ -374,7 +374,7 @@ static int getSubsamp(j_decompress_ptr dinfo) if (dinfo->num_components == 1 && dinfo->jpeg_color_space == JCS_GRAYSCALE) return TJSAMP_GRAY; - for (i = 0; i < NUMSUBOPT; i++) { + for (i = 0; i < TJ_NUMSAMP; i++) { if (dinfo->num_components == pixelsize[i] || ((dinfo->jpeg_color_space == JCS_YCCK || dinfo->jpeg_color_space == JCS_CMYK) && @@ -443,8 +443,9 @@ static int getSubsamp(j_decompress_ptr dinfo) } -/* General API functions */ +/*************************** General API functions ***************************/ +/* TurboJPEG 2.0+ */ DLLEXPORT char *tjGetErrorStr2(tjhandle handle) { tjinstance *this = (tjinstance *)handle; @@ -457,12 +458,14 @@ DLLEXPORT char *tjGetErrorStr2(tjhandle handle) } +/* TurboJPEG 1.0+ */ DLLEXPORT char *tjGetErrorStr(void) { return errStr; } +/* TurboJPEG 2.0+ */ DLLEXPORT int tjGetErrorCode(tjhandle handle) { tjinstance *this = (tjinstance *)handle; @@ -472,6 +475,7 @@ DLLEXPORT int tjGetErrorCode(tjhandle handle) } +/* TurboJPEG 1.0+ */ DLLEXPORT int tjDestroy(tjhandle handle) { GET_INSTANCE(handle); @@ -489,19 +493,21 @@ DLLEXPORT int tjDestroy(tjhandle handle) with turbojpeg.dll for compatibility reasons. However, these functions can potentially be used for other purposes by different implementations. */ +/* TurboJPEG 1.2+ */ DLLEXPORT void tjFree(unsigned char *buf) { free(buf); } +/* TurboJPEG 1.2+ */ DLLEXPORT unsigned char *tjAlloc(int bytes) { return (unsigned char *)malloc(bytes); } -/* Compressor */ +/******************************** Compressor *********************************/ static tjhandle _tjInitCompress(tjinstance *this) { @@ -533,6 +539,7 @@ static tjhandle _tjInitCompress(tjinstance *this) return (tjhandle)this; } +/* TurboJPEG 1.0+ */ DLLEXPORT tjhandle tjInitCompress(void) { tjinstance *this = NULL; @@ -548,12 +555,13 @@ DLLEXPORT tjhandle tjInitCompress(void) } +/* TurboJPEG 1.2+ */ DLLEXPORT unsigned long tjBufSize(int width, int height, int jpegSubsamp) { unsigned long long retval = 0; int mcuw, mcuh, chromasf; - if (width < 1 || height < 1 || jpegSubsamp < 0 || jpegSubsamp >= NUMSUBOPT) + if (width < 1 || height < 1 || jpegSubsamp < 0 || jpegSubsamp >= TJ_NUMSAMP) THROWG("tjBufSize(): Invalid argument"); /* This allows for rare corner cases in which a JPEG image can actually be @@ -570,6 +578,7 @@ bailout: return (unsigned long)retval; } +/* TurboJPEG 1.0+ */ DLLEXPORT unsigned long TJBUFSIZE(int width, int height) { unsigned long long retval = 0; @@ -589,19 +598,20 @@ bailout: } -DLLEXPORT unsigned long tjBufSizeYUV2(int width, int pad, int height, +/* TurboJPEG 1.4+ */ +DLLEXPORT unsigned long tjBufSizeYUV2(int width, int align, int height, int subsamp) { unsigned long long retval = 0; int nc, i; - if (subsamp < 0 || subsamp >= NUMSUBOPT) + if (align < 1 || !IS_POW2(align) || subsamp < 0 || subsamp >= TJ_NUMSAMP) THROWG("tjBufSizeYUV2(): Invalid argument"); nc = (subsamp == TJSAMP_GRAY ? 1 : 3); for (i = 0; i < nc; i++) { int pw = tjPlaneWidth(i, width, subsamp); - int stride = PAD(pw, pad); + int stride = PAD(pw, align); int ph = tjPlaneHeight(i, height, subsamp); if (pw < 0 || ph < 0) return -1; @@ -614,17 +624,20 @@ bailout: return (unsigned long)retval; } +/* TurboJPEG 1.2+ */ DLLEXPORT unsigned long tjBufSizeYUV(int width, int height, int subsamp) { return tjBufSizeYUV2(width, 4, height, subsamp); } +/* TurboJPEG 1.1+ */ DLLEXPORT unsigned long TJBUFSIZEYUV(int width, int height, int subsamp) { return tjBufSizeYUV(width, height, subsamp); } +/* TurboJPEG 1.4+ */ DLLEXPORT int tjPlaneWidth(int componentID, int width, int subsamp) { int pw, nc, retval = 0; @@ -646,6 +659,7 @@ bailout: } +/* TurboJPEG 1.4+ */ DLLEXPORT int tjPlaneHeight(int componentID, int height, int subsamp) { int ph, nc, retval = 0; @@ -667,13 +681,14 @@ bailout: } +/* TurboJPEG 1.4+ */ DLLEXPORT unsigned long tjPlaneSizeYUV(int componentID, int width, int stride, int height, int subsamp) { unsigned long long retval = 0; int pw, ph; - if (width < 1 || height < 1 || subsamp < 0 || subsamp >= NUMSUBOPT) + if (width < 1 || height < 1 || subsamp < 0 || subsamp >= TJ_NUMSAMP) THROWG("tjPlaneSizeYUV(): Invalid argument"); pw = tjPlaneWidth(componentID, width, subsamp); @@ -692,6 +707,7 @@ bailout: } +/* TurboJPEG 1.2+ */ DLLEXPORT int tjCompress2(tjhandle handle, const unsigned char *srcBuf, int width, int pitch, int height, int pixelFormat, unsigned char **jpegBuf, unsigned long *jpegSize, @@ -708,7 +724,7 @@ DLLEXPORT int tjCompress2(tjhandle handle, const unsigned char *srcBuf, if (srcBuf == NULL || width <= 0 || pitch < 0 || height <= 0 || pixelFormat < 0 || pixelFormat >= TJ_NUMPF || jpegBuf == NULL || - jpegSize == NULL || jpegSubsamp < 0 || jpegSubsamp >= NUMSUBOPT || + jpegSize == NULL || jpegSubsamp < 0 || jpegSubsamp >= TJ_NUMSAMP || jpegQual < 0 || jpegQual > 100) THROW("tjCompress2(): Invalid argument"); @@ -763,6 +779,7 @@ bailout: return retval; } +/* TurboJPEG 1.0+ */ DLLEXPORT int tjCompress(tjhandle handle, unsigned char *srcBuf, int width, int pitch, int height, int pixelSize, unsigned char *jpegBuf, unsigned long *jpegSize, @@ -786,6 +803,7 @@ DLLEXPORT int tjCompress(tjhandle handle, unsigned char *srcBuf, int width, } +/* TurboJPEG 1.4+ */ DLLEXPORT int tjEncodeYUVPlanes(tjhandle handle, const unsigned char *srcBuf, int width, int pitch, int height, int pixelFormat, unsigned char **dstPlanes, @@ -812,13 +830,13 @@ DLLEXPORT int tjEncodeYUVPlanes(tjhandle handle, const unsigned char *srcBuf, if (srcBuf == NULL || width <= 0 || pitch < 0 || height <= 0 || pixelFormat < 0 || pixelFormat >= TJ_NUMPF || !dstPlanes || - !dstPlanes[0] || subsamp < 0 || subsamp >= NUMSUBOPT) + !dstPlanes[0] || subsamp < 0 || subsamp >= TJ_NUMSAMP) THROW("tjEncodeYUVPlanes(): Invalid argument"); if (subsamp != TJSAMP_GRAY && (!dstPlanes[1] || !dstPlanes[2])) THROW("tjEncodeYUVPlanes(): Invalid argument"); if (pixelFormat == TJPF_CMYK) - THROW("tjEncodeYUVPlanes(): Cannot generate YUV images from CMYK pixels"); + THROW("tjEncodeYUVPlanes(): Cannot generate YUV images from packed-pixel CMYK images"); if (pitch == 0) pitch = width * tjPixelSize[pixelFormat]; @@ -946,9 +964,10 @@ bailout: return retval; } +/* TurboJPEG 1.4+ */ DLLEXPORT int tjEncodeYUV3(tjhandle handle, const unsigned char *srcBuf, int width, int pitch, int height, int pixelFormat, - unsigned char *dstBuf, int pad, int subsamp, + unsigned char *dstBuf, int align, int subsamp, int flags) { unsigned char *dstPlanes[3]; @@ -958,14 +977,14 @@ DLLEXPORT int tjEncodeYUV3(tjhandle handle, const unsigned char *srcBuf, if (!this) THROWG("tjEncodeYUV3(): Invalid handle"); this->isInstanceError = FALSE; - if (width <= 0 || height <= 0 || dstBuf == NULL || pad < 0 || - !IS_POW2(pad) || subsamp < 0 || subsamp >= NUMSUBOPT) + if (width <= 0 || height <= 0 || dstBuf == NULL || align < 1 || + !IS_POW2(align) || subsamp < 0 || subsamp >= TJ_NUMSAMP) THROW("tjEncodeYUV3(): Invalid argument"); pw0 = tjPlaneWidth(0, width, subsamp); ph0 = tjPlaneHeight(0, height, subsamp); dstPlanes[0] = dstBuf; - strides[0] = PAD(pw0, pad); + strides[0] = PAD(pw0, align); if (subsamp == TJSAMP_GRAY) { strides[1] = strides[2] = 0; dstPlanes[1] = dstPlanes[2] = NULL; @@ -973,7 +992,7 @@ DLLEXPORT int tjEncodeYUV3(tjhandle handle, const unsigned char *srcBuf, int pw1 = tjPlaneWidth(1, width, subsamp); int ph1 = tjPlaneHeight(1, height, subsamp); - strides[1] = strides[2] = PAD(pw1, pad); + strides[1] = strides[2] = PAD(pw1, align); dstPlanes[1] = dstPlanes[0] + strides[0] * ph0; dstPlanes[2] = dstPlanes[1] + strides[1] * ph1; } @@ -985,6 +1004,7 @@ bailout: return retval; } +/* TurboJPEG 1.2+ */ DLLEXPORT int tjEncodeYUV2(tjhandle handle, unsigned char *srcBuf, int width, int pitch, int height, int pixelFormat, unsigned char *dstBuf, int subsamp, int flags) @@ -993,6 +1013,7 @@ DLLEXPORT int tjEncodeYUV2(tjhandle handle, unsigned char *srcBuf, int width, dstBuf, 4, subsamp, flags); } +/* TurboJPEG 1.1+ */ DLLEXPORT int tjEncodeYUV(tjhandle handle, unsigned char *srcBuf, int width, int pitch, int height, int pixelSize, unsigned char *dstBuf, int subsamp, int flags) @@ -1003,6 +1024,7 @@ DLLEXPORT int tjEncodeYUV(tjhandle handle, unsigned char *srcBuf, int width, } +/* TurboJPEG 1.4+ */ DLLEXPORT int tjCompressFromYUVPlanes(tjhandle handle, const unsigned char **srcPlanes, int width, const int *strides, @@ -1029,7 +1051,7 @@ DLLEXPORT int tjCompressFromYUVPlanes(tjhandle handle, THROW("tjCompressFromYUVPlanes(): Instance has not been initialized for compression"); if (!srcPlanes || !srcPlanes[0] || width <= 0 || height <= 0 || - subsamp < 0 || subsamp >= NUMSUBOPT || jpegBuf == NULL || + subsamp < 0 || subsamp >= TJ_NUMSAMP || jpegBuf == NULL || jpegSize == NULL || jpegQual < 0 || jpegQual > 100) THROW("tjCompressFromYUVPlanes(): Invalid argument"); if (subsamp != TJSAMP_GRAY && (!srcPlanes[1] || !srcPlanes[2])) @@ -1143,8 +1165,9 @@ bailout: return retval; } +/* TurboJPEG 1.4+ */ DLLEXPORT int tjCompressFromYUV(tjhandle handle, const unsigned char *srcBuf, - int width, int pad, int height, int subsamp, + int width, int align, int height, int subsamp, unsigned char **jpegBuf, unsigned long *jpegSize, int jpegQual, int flags) @@ -1156,14 +1179,14 @@ DLLEXPORT int tjCompressFromYUV(tjhandle handle, const unsigned char *srcBuf, if (!this) THROWG("tjCompressFromYUV(): Invalid handle"); this->isInstanceError = FALSE; - if (srcBuf == NULL || width <= 0 || pad < 1 || height <= 0 || subsamp < 0 || - subsamp >= NUMSUBOPT) + if (srcBuf == NULL || width <= 0 || align < 1 || !IS_POW2(align) || + height <= 0 || subsamp < 0 || subsamp >= TJ_NUMSAMP) THROW("tjCompressFromYUV(): Invalid argument"); pw0 = tjPlaneWidth(0, width, subsamp); ph0 = tjPlaneHeight(0, height, subsamp); srcPlanes[0] = srcBuf; - strides[0] = PAD(pw0, pad); + strides[0] = PAD(pw0, align); if (subsamp == TJSAMP_GRAY) { strides[1] = strides[2] = 0; srcPlanes[1] = srcPlanes[2] = NULL; @@ -1171,7 +1194,7 @@ DLLEXPORT int tjCompressFromYUV(tjhandle handle, const unsigned char *srcBuf, int pw1 = tjPlaneWidth(1, width, subsamp); int ph1 = tjPlaneHeight(1, height, subsamp); - strides[1] = strides[2] = PAD(pw1, pad); + strides[1] = strides[2] = PAD(pw1, align); srcPlanes[1] = srcPlanes[0] + strides[0] * ph0; srcPlanes[2] = srcPlanes[1] + strides[1] * ph1; } @@ -1184,7 +1207,7 @@ bailout: } -/* Decompressor */ +/******************************* Decompressor ********************************/ static tjhandle _tjInitDecompress(tjinstance *this) { @@ -1214,6 +1237,7 @@ static tjhandle _tjInitDecompress(tjinstance *this) return (tjhandle)this; } +/* TurboJPEG 1.0+ */ DLLEXPORT tjhandle tjInitDecompress(void) { tjinstance *this; @@ -1229,6 +1253,7 @@ DLLEXPORT tjhandle tjInitDecompress(void) } +/* TurboJPEG 2.2+ */ DLLEXPORT int tjDecompressHeader4(tjhandle handle, const unsigned char *jpegBuf, unsigned long jpegSize, int *width, @@ -1289,6 +1314,7 @@ bailout: return retval; } +/* TurboJPEG 1.4+ */ DLLEXPORT int tjDecompressHeader3(tjhandle handle, const unsigned char *jpegBuf, unsigned long jpegSize, int *width, @@ -1301,6 +1327,7 @@ DLLEXPORT int tjDecompressHeader3(tjhandle handle, jpegSubsamp, jpegColorspace, &flags); } +/* TurboJPEG 1.1+ */ DLLEXPORT int tjDecompressHeader2(tjhandle handle, unsigned char *jpegBuf, unsigned long jpegSize, int *width, int *height, int *jpegSubsamp) @@ -1311,6 +1338,7 @@ DLLEXPORT int tjDecompressHeader2(tjhandle handle, unsigned char *jpegBuf, jpegSubsamp, &jpegColorspace); } +/* TurboJPEG 1.0+ */ DLLEXPORT int tjDecompressHeader(tjhandle handle, unsigned char *jpegBuf, unsigned long jpegSize, int *width, int *height) @@ -1322,19 +1350,21 @@ DLLEXPORT int tjDecompressHeader(tjhandle handle, unsigned char *jpegBuf, } -DLLEXPORT tjscalingfactor *tjGetScalingFactors(int *numscalingfactors) +/* TurboJPEG 1.2+ */ +DLLEXPORT tjscalingfactor *tjGetScalingFactors(int *numScalingFactors) { - if (numscalingfactors == NULL) { + if (numScalingFactors == NULL) { SNPRINTF(errStr, JMSG_LENGTH_MAX, "tjGetScalingFactors(): Invalid argument"); return NULL; } - *numscalingfactors = NUMSF; + *numScalingFactors = NUMSF; return (tjscalingfactor *)sf; } +/* TurboJPEG 1.2+ */ DLLEXPORT int tjDecompress2(tjhandle handle, const unsigned char *jpegBuf, unsigned long jpegSize, unsigned char *dstBuf, int width, int pitch, int height, int pixelFormat, @@ -1422,6 +1452,7 @@ bailout: return retval; } +/* TurboJPEG 1.0+ */ DLLEXPORT int tjDecompress(tjhandle handle, unsigned char *jpegBuf, unsigned long jpegSize, unsigned char *dstBuf, int width, int pitch, int height, int pixelSize, @@ -1483,6 +1514,7 @@ static void my_reset_marker_reader(j_decompress_ptr dinfo) { } +/* TurboJPEG 1.4+ */ DLLEXPORT int tjDecodeYUVPlanes(tjhandle handle, const unsigned char **srcPlanes, const int *strides, int subsamp, @@ -1508,7 +1540,7 @@ DLLEXPORT int tjDecodeYUVPlanes(tjhandle handle, if ((this->init & DECOMPRESS) == 0) THROW("tjDecodeYUVPlanes(): Instance has not been initialized for decompression"); - if (!srcPlanes || !srcPlanes[0] || subsamp < 0 || subsamp >= NUMSUBOPT || + if (!srcPlanes || !srcPlanes[0] || subsamp < 0 || subsamp >= TJ_NUMSAMP || dstBuf == NULL || width <= 0 || pitch < 0 || height <= 0 || pixelFormat < 0 || pixelFormat >= TJ_NUMPF) THROW("tjDecodeYUVPlanes(): Invalid argument"); @@ -1521,7 +1553,7 @@ DLLEXPORT int tjDecodeYUVPlanes(tjhandle handle, } if (pixelFormat == TJPF_CMYK) - THROW("tjDecodeYUVPlanes(): Cannot decode YUV images into CMYK pixels."); + THROW("tjDecodeYUVPlanes(): Cannot decode YUV images into packed-pixel CMYK images."); if (pitch == 0) pitch = width * tjPixelSize[pixelFormat]; dinfo->image_width = width; @@ -1629,8 +1661,9 @@ bailout: return retval; } +/* TurboJPEG 1.4+ */ DLLEXPORT int tjDecodeYUV(tjhandle handle, const unsigned char *srcBuf, - int pad, int subsamp, unsigned char *dstBuf, + int align, int subsamp, unsigned char *dstBuf, int width, int pitch, int height, int pixelFormat, int flags) { @@ -1641,14 +1674,14 @@ DLLEXPORT int tjDecodeYUV(tjhandle handle, const unsigned char *srcBuf, if (!this) THROWG("tjDecodeYUV(): Invalid handle"); this->isInstanceError = FALSE; - if (srcBuf == NULL || pad < 0 || !IS_POW2(pad) || subsamp < 0 || - subsamp >= NUMSUBOPT || width <= 0 || height <= 0) + if (srcBuf == NULL || align < 1 || !IS_POW2(align) || subsamp < 0 || + subsamp >= TJ_NUMSAMP || width <= 0 || height <= 0) THROW("tjDecodeYUV(): Invalid argument"); pw0 = tjPlaneWidth(0, width, subsamp); ph0 = tjPlaneHeight(0, height, subsamp); srcPlanes[0] = srcBuf; - strides[0] = PAD(pw0, pad); + strides[0] = PAD(pw0, align); if (subsamp == TJSAMP_GRAY) { strides[1] = strides[2] = 0; srcPlanes[1] = srcPlanes[2] = NULL; @@ -1656,7 +1689,7 @@ DLLEXPORT int tjDecodeYUV(tjhandle handle, const unsigned char *srcBuf, int pw1 = tjPlaneWidth(1, width, subsamp); int ph1 = tjPlaneHeight(1, height, subsamp); - strides[1] = strides[2] = PAD(pw1, pad); + strides[1] = strides[2] = PAD(pw1, align); srcPlanes[1] = srcPlanes[0] + strides[0] * ph0; srcPlanes[2] = srcPlanes[1] + strides[1] * ph1; } @@ -1668,6 +1701,7 @@ bailout: return retval; } +/* TurboJPEG 1.4+ */ DLLEXPORT int tjDecompressToYUVPlanes(tjhandle handle, const unsigned char *jpegBuf, unsigned long jpegSize, @@ -1801,7 +1835,7 @@ DLLEXPORT int tjDecompressToYUVPlanes(tjhandle handle, for (i = 0; i < dinfo->num_components; i++) { jpeg_component_info *compptr = &dinfo->comp_info[i]; - if (jpegSubsamp == TJ_420) { + if (jpegSubsamp == TJSAMP_420) { /* When 4:2:0 subsampling is used with IDCT scaling, libjpeg will try to be clever and use the IDCT to perform upsampling on the U and V planes. For instance, if the output image is to be scaled by 1/2 @@ -1848,9 +1882,10 @@ bailout: return retval; } +/* TurboJPEG 1.4+ */ DLLEXPORT int tjDecompressToYUV2(tjhandle handle, const unsigned char *jpegBuf, unsigned long jpegSize, unsigned char *dstBuf, - int width, int pad, int height, int flags) + int width, int align, int height, int flags) { unsigned char *dstPlanes[3]; int pw0, ph0, strides[3], retval = -1, jpegSubsamp = -1; @@ -1860,7 +1895,7 @@ DLLEXPORT int tjDecompressToYUV2(tjhandle handle, const unsigned char *jpegBuf, this->jerr.stopOnWarning = (flags & TJFLAG_STOPONWARNING) ? TRUE : FALSE; if (jpegBuf == NULL || jpegSize <= 0 || dstBuf == NULL || width < 0 || - pad < 1 || !IS_POW2(pad) || height < 0) + align < 1 || !IS_POW2(align) || height < 0) THROW("tjDecompressToYUV2(): Invalid argument"); if (setjmp(this->jerr.setjmp_buffer)) { @@ -1877,7 +1912,6 @@ DLLEXPORT int tjDecompressToYUV2(tjhandle handle, const unsigned char *jpegBuf, jpegwidth = dinfo->image_width; jpegheight = dinfo->image_height; if (width == 0) width = jpegwidth; if (height == 0) height = jpegheight; - for (i = 0; i < NUMSF; i++) { scaledw = TJSCALED(jpegwidth, sf[i]); scaledh = TJSCALED(jpegheight, sf[i]); @@ -1887,10 +1921,12 @@ DLLEXPORT int tjDecompressToYUV2(tjhandle handle, const unsigned char *jpegBuf, if (i >= NUMSF) THROW("tjDecompressToYUV2(): Could not scale down to desired image dimensions"); + width = scaledw; height = scaledh; + pw0 = tjPlaneWidth(0, width, jpegSubsamp); ph0 = tjPlaneHeight(0, height, jpegSubsamp); dstPlanes[0] = dstBuf; - strides[0] = PAD(pw0, pad); + strides[0] = PAD(pw0, align); if (jpegSubsamp == TJSAMP_GRAY) { strides[1] = strides[2] = 0; dstPlanes[1] = dstPlanes[2] = NULL; @@ -1898,7 +1934,7 @@ DLLEXPORT int tjDecompressToYUV2(tjhandle handle, const unsigned char *jpegBuf, int pw1 = tjPlaneWidth(1, width, jpegSubsamp); int ph1 = tjPlaneHeight(1, height, jpegSubsamp); - strides[1] = strides[2] = PAD(pw1, pad); + strides[1] = strides[2] = PAD(pw1, align); dstPlanes[1] = dstPlanes[0] + strides[0] * ph0; dstPlanes[2] = dstPlanes[1] + strides[1] * ph1; } @@ -1912,6 +1948,7 @@ bailout: return retval; } +/* TurboJPEG 1.1+ */ DLLEXPORT int tjDecompressToYUV(tjhandle handle, unsigned char *jpegBuf, unsigned long jpegSize, unsigned char *dstBuf, int flags) @@ -1920,8 +1957,9 @@ DLLEXPORT int tjDecompressToYUV(tjhandle handle, unsigned char *jpegBuf, } -/* Transformer */ +/******************************** Transformer ********************************/ +/* TurboJPEG 1.2+ */ DLLEXPORT tjhandle tjInitTransform(void) { tjinstance *this = NULL; @@ -1941,6 +1979,7 @@ DLLEXPORT tjhandle tjInitTransform(void) } +/* TurboJPEG 1.2+ */ DLLEXPORT int tjTransform(tjhandle handle, const unsigned char *jpegBuf, unsigned long jpegSize, int n, unsigned char **dstBufs, unsigned long *dstSizes, @@ -2111,6 +2150,9 @@ bailout: } +/*************************** Packed-Pixel Image I/O **************************/ + +/* TurboJPEG 2.0+ */ DLLEXPORT unsigned char *tjLoadImage(const char *filename, int *width, int align, int *height, int *pixelFormat, int flags) @@ -2213,6 +2255,7 @@ bailout: } +/* TurboJPEG 2.0+ */ DLLEXPORT int tjSaveImage(const char *filename, unsigned char *buffer, int width, int pitch, int height, int pixelFormat, int flags) diff --git a/turbojpeg.h b/turbojpeg.h index adac92c6..fa6bf2f8 100644 --- a/turbojpeg.h +++ b/turbojpeg.h @@ -1,5 +1,5 @@ /* - * Copyright (C)2009-2015, 2017, 2020-2022 D. R. Commander. + * Copyright (C)2009-2015, 2017, 2020-2023 D. R. Commander. * All Rights Reserved. * * Redistribution and use in source and binary forms, with or without @@ -54,23 +54,24 @@ * Each plane is simply a 2D array of bytes, each byte representing the value * of one of the components (Y, Cb, or Cr) at a particular location in the * image. The width and height of each plane are determined by the image - * width, height, and level of chrominance subsampling. The luminance plane + * width, height, and level of chrominance subsampling. The luminance plane * width is the image width padded to the nearest multiple of the horizontal - * subsampling factor (2 in the case of 4:2:0 and 4:2:2, 4 in the case of - * 4:1:1, 1 in the case of 4:4:4 or grayscale.) Similarly, the luminance plane - * height is the image height padded to the nearest multiple of the vertical - * subsampling factor (2 in the case of 4:2:0 or 4:4:0, 1 in the case of 4:4:4 - * or grayscale.) This is irrespective of any additional padding that may be - * specified as an argument to the various YUV functions. The chrominance - * plane width is equal to the luminance plane width divided by the horizontal - * subsampling factor, and the chrominance plane height is equal to the - * luminance plane height divided by the vertical subsampling factor. + * subsampling factor (1 in the case of 4:4:4, grayscale, or 4:4:0; 2 in the + * case of 4:2:2 or 4:2:0; 4 in the case of 4:1:1.) Similarly, the luminance + * plane height is the image height padded to the nearest multiple of the + * vertical subsampling factor (1 in the case of 4:4:4, 4:2:2, grayscale, or + * 4:1:1; 2 in the case of 4:2:0 or 4:4:0.) This is irrespective of any + * additional padding that may be specified as an argument to the various YUV + * functions. The chrominance plane width is equal to the luminance plane + * width divided by the horizontal subsampling factor, and the chrominance + * plane height is equal to the luminance plane height divided by the vertical + * subsampling factor. * * For example, if the source image is 35 x 35 pixels and 4:2:2 subsampling is * used, then the luminance plane would be 36 x 35 bytes, and each of the - * chrominance planes would be 18 x 35 bytes. If you specify a line padding of - * 4 bytes on top of this, then the luminance plane would be 36 x 35 bytes, and - * each of the chrominance planes would be 20 x 35 bytes. + * chrominance planes would be 18 x 35 bytes. If you specify a row alignment + * of 4 bytes on top of this, then the luminance plane would be 36 x 35 bytes, + * and each of the chrominance planes would be 20 x 35 bytes. * * @{ */ @@ -86,8 +87,8 @@ * When pixels are converted from RGB to YCbCr (see #TJCS_YCbCr) or from CMYK * to YCCK (see #TJCS_YCCK) 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 to + * to produce a smaller image with little perceptible loss of image clarity. + * (The human eye is more sensitive to small changes in brightness than to * small changes in color.) This is called "chrominance subsampling". */ enum TJSAMP { @@ -245,8 +246,8 @@ enum TJPF { * vice versa, but the mapping is typically not 1:1 or reversible, nor can it * be defined with a simple formula. Thus, such a conversion is out of scope * for a codec library. However, the TurboJPEG API allows for compressing - * CMYK pixels into a YCCK JPEG image (see #TJCS_YCCK) and decompressing YCCK - * JPEG images into CMYK pixels. + * packed-pixel CMYK images into YCCK JPEG images (see #TJCS_YCCK) and + * decompressing YCCK JPEG images into packed-pixel CMYK images. */ TJPF_CMYK, /** @@ -258,9 +259,10 @@ enum TJPF { /** * Red offset (in bytes) for a given pixel format. This specifies the number * of bytes that the red component is offset from the start of the pixel. For - * instance, if a pixel of format TJ_BGRX is stored in char pixel[], - * then the red component will be pixel[tjRedOffset[TJ_BGRX]]. This - * will be -1 if the pixel format does not have a red component. + * instance, if a pixel of format TJPF_BGRX is stored in + * `unsigned char pixel[]`, then the red component will be + *`pixel[tjRedOffset[TJPF_BGRX]]`. This will be -1 if the pixel format does + * not have a red component. */ static const int tjRedOffset[TJ_NUMPF] = { 0, 2, 0, 2, 3, 1, -1, 0, 2, 3, 1, -1 @@ -268,31 +270,32 @@ static const int tjRedOffset[TJ_NUMPF] = { /** * Green offset (in bytes) for a given pixel format. This specifies the number * of bytes that the green component is offset from the start of the pixel. - * For instance, if a pixel of format TJ_BGRX is stored in - * char pixel[], then the green component will be - * pixel[tjGreenOffset[TJ_BGRX]]. This will be -1 if the pixel format - * does not have a green component. + * For instance, if a pixel of format TJPF_BGRX is stored in + * `unsigned char pixel[]`, then the green component will be + * `pixel[tjGreenOffset[TJPF_BGRX]]`. This will be -1 if the pixel format does + * not have a green component. */ static const int tjGreenOffset[TJ_NUMPF] = { 1, 1, 1, 1, 2, 2, -1, 1, 1, 2, 2, -1 }; /** * Blue offset (in bytes) for a given pixel format. This specifies the number - * of bytes that the Blue component is offset from the start of the pixel. For - * instance, if a pixel of format TJ_BGRX is stored in char pixel[], - * then the blue component will be pixel[tjBlueOffset[TJ_BGRX]]. This - * will be -1 if the pixel format does not have a blue component. + * of bytes that the blue component is offset from the start of the pixel. For + * instance, if a pixel of format TJPF_BGRX is stored in + * `unsigned char pixel[]`, then the blue component will be + * `pixel[tjBlueOffset[TJPF_BGRX]]`. This will be -1 if the pixel format does + * not have a blue component. */ static const int tjBlueOffset[TJ_NUMPF] = { 2, 0, 2, 0, 1, 3, -1, 2, 0, 1, 3, -1 }; /** * Alpha offset (in bytes) for a given pixel format. This specifies the number - * of bytes that the Alpha component is offset from the start of the pixel. - * For instance, if a pixel of format TJ_BGRA is stored in - * char pixel[], then the alpha component will be - * pixel[tjAlphaOffset[TJ_BGRA]]. This will be -1 if the pixel format - * does not have an alpha component. + * of bytes that the alpha component is offset from the start of the pixel. + * For instance, if a pixel of format TJPF_BGRA is stored in + * `unsigned char pixel[]`, then the alpha component will be + * `pixel[tjAlphaOffset[TJPF_BGRA]]`. This will be -1 if the pixel format does + * not have an alpha component. */ static const int tjAlphaOffset[TJ_NUMPF] = { -1, -1, -1, -1, -1, -1, -1, 3, 3, 0, 0, -1 @@ -318,8 +321,9 @@ enum TJCS { * RGB colorspace. When compressing the JPEG image, the R, G, and B * components in the source image are reordered into image planes, but no * colorspace conversion or subsampling is performed. RGB JPEG images can be - * decompressed to any of the extended RGB pixel formats or grayscale, but - * they cannot be decompressed to YUV images. + * decompressed to packed-pixel images with any of the extended RGB or + * grayscale pixel formats, but they cannot be decompressed to planar YUV + * images. */ TJCS_RGB = 0, /** @@ -332,25 +336,27 @@ enum TJCS { * original image. Originally, the analog equivalent of this transformation * allowed the same signal to drive both black & white and color televisions, * but JPEG images use YCbCr primarily because it allows the color data to be - * optionally subsampled for the purposes of reducing bandwidth or disk - * space. YCbCr is the most common JPEG colorspace, and YCbCr JPEG images - * can be compressed from and decompressed to any of the extended RGB pixel - * formats or grayscale, or they can be decompressed to YUV planar images. + * optionally subsampled for the purposes of reducing network or disk usage. + * YCbCr is the most common JPEG colorspace, and YCbCr JPEG images can be + * compressed from and decompressed to packed-pixel images with any of the + * extended RGB or grayscale pixel formats. YCbCr JPEG images can also be + * compressed from and decompressed to planar YUV images. */ TJCS_YCbCr, /** * Grayscale colorspace. The JPEG image retains only the luminance data (Y * component), and any color data from the source image is discarded. - * Grayscale JPEG images can be compressed from and decompressed to any of - * the extended RGB pixel formats or grayscale, or they can be decompressed - * to YUV planar images. + * Grayscale JPEG images can be compressed from and decompressed to + * packed-pixel images with any of the extended RGB or grayscale pixel + * formats, or they can be compressed from and decompressed to planar YUV + * images. */ TJCS_GRAY, /** * CMYK colorspace. When compressing the JPEG image, the C, M, Y, and K * components in the source image are reordered into image planes, but no * colorspace conversion or subsampling is performed. CMYK JPEG images can - * only be decompressed to CMYK pixels. + * only be decompressed to packed-pixel images with the CMYK pixel format. */ TJCS_CMYK, /** @@ -360,56 +366,54 @@ enum TJCS { * reversibly transformed into YCCK, and as with YCbCr, the chrominance * components in the YCCK pixels can be subsampled without incurring major * perceptual loss. YCCK JPEG images can only be compressed from and - * decompressed to CMYK pixels. + * decompressed to packed-pixel images with the CMYK pixel format. */ TJCS_YCCK }; /** - * The uncompressed source/destination image is stored in bottom-up (Windows, - * OpenGL) order, not top-down (X11) order. + * Rows in the packed-pixel source/destination image are stored in bottom-up + * (Windows, OpenGL) order rather than in top-down (X11) order. */ #define TJFLAG_BOTTOMUP (1 << 1) /** * 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. + * subsampling, use the fastest chrominance upsampling algorithm available. + * 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 (1 << 8) /** - * Disable buffer (re)allocation. If passed to one of the JPEG compression or - * transform functions, this flag will cause those functions to generate an - * error if the JPEG image buffer is invalid or too small rather than - * attempting to allocate or reallocate that buffer. This reproduces the - * behavior of earlier versions of TurboJPEG. + * Disable JPEG buffer (re)allocation. If passed to one of the JPEG + * compression or transform functions, this flag will cause those functions to + * generate an error if the JPEG destination buffer is invalid or too small, + * rather than attempt to allocate or reallocate that buffer. */ #define TJFLAG_NOREALLOC (1 << 10) /** - * Use the fastest DCT/IDCT algorithm available in the underlying codec. The - * default if this flag is not specified is implementation-specific. For - * example, the implementation of TurboJPEG for libjpeg[-turbo] uses the fast - * algorithm by default when compressing, because this has been shown to have - * only a very slight effect on accuracy, but it uses the accurate algorithm - * when decompressing, because this has been shown to have a larger effect. + * Use the fastest DCT/IDCT algorithm available. The default if this flag is + * not specified is implementation-specific. For example, the implementation + * of the TurboJPEG API in libjpeg-turbo uses the fast algorithm by default + * when compressing, because this has been shown to have only a very slight + * effect on accuracy, but it uses the accurate algorithm when decompressing, + * because this has been shown to have a larger effect. */ #define TJFLAG_FASTDCT (1 << 11) /** - * Use the most accurate DCT/IDCT algorithm available in the underlying codec. - * The default if this flag is not specified is implementation-specific. For - * example, the implementation of TurboJPEG for libjpeg[-turbo] uses the fast - * algorithm by default when compressing, because this has been shown to have - * only a very slight effect on accuracy, but it uses the accurate algorithm - * when decompressing, because this has been shown to have a larger effect. + * Use the most accurate DCT/IDCT algorithm available. The default if this + * flag is not specified is implementation-specific. For example, the + * implementation of the TurboJPEG API in libjpeg-turbo uses the fast algorithm + * by default when compressing, because this has been shown to have only a very + * slight effect on accuracy, but it uses the accurate algorithm when + * decompressing, because this has been shown to have a larger effect. */ #define TJFLAG_ACCURATEDCT (1 << 12) /** * Immediately discontinue the current compression/decompression/transform - * operation if the underlying codec throws a warning (non-fatal error). The - * default behavior is to allow the operation to complete unless a fatal error - * is encountered. + * operation if a warning (non-fatal error) occurs. The default behavior is to + * allow the operation to complete unless a fatal error is encountered. */ #define TJFLAG_STOPONWARNING (1 << 13) /** @@ -449,7 +453,7 @@ enum TJCS { * - DCT/IDCT algorithm selection * - Progressive entropy coding * - Arithmetic entropy coding - * - Compression from/decompression to YUV planar images + * - Compression from/decompression to planar YUV images * - Decompression scaling * - Lossless transformations */ @@ -466,8 +470,8 @@ enum TJCS { */ enum TJERR { /** - * The error was non-fatal and recoverable, but the image may still be - * corrupt. + * The error was non-fatal and recoverable, but the destination image may + * still be corrupt. */ TJERR_WARNING = 0, /** @@ -534,9 +538,9 @@ enum TJXOP { /** * This option will cause #tjTransform() to return an error if the transform is * not perfect. Lossless transforms operate on MCU blocks, whose size depends - * on the level of chrominance subsampling used (see #tjMCUWidth - * and #tjMCUHeight.) If the image's width or height is not evenly divisible - * by the MCU block size, then there will be partial MCU blocks on the right + * on the level of chrominance subsampling used (see #tjMCUWidth and + * #tjMCUHeight.) If the image's width or height is not evenly divisible by + * the MCU block size, then there will be partial MCU blocks on the right * and/or bottom edges. It is not possible to move these partial MCU blocks to * the top or left of the image, so any transform that would require that is * "imperfect." If this option is not specified, then any partial MCU blocks @@ -555,19 +559,19 @@ enum TJXOP { */ #define TJXOPT_CROP (1 << 2) /** - * This option will discard the color data in the input image and produce - * a grayscale output image. + * This option will discard the color data in the source image and produce a + * grayscale destination image. */ #define TJXOPT_GRAY (1 << 3) /** * This option will prevent #tjTransform() from outputting a JPEG image for - * this particular transform (this can be used in conjunction with a custom + * this particular transform. (This can be used in conjunction with a custom * filter to capture the transformed DCT coefficients without transcoding * them.) */ #define TJXOPT_NOOUTPUT (1 << 4) /** - * This option will enable progressive entropy coding in the output image + * This option will enable progressive entropy coding in the JPEG image * generated by this particular transform. Progressive entropy coding will * generally improve compression relative to baseline entropy coding (the * default), but it will reduce compression and decompression performance @@ -576,12 +580,12 @@ enum TJXOP { #define TJXOPT_PROGRESSIVE (1 << 5) /** * This option will prevent #tjTransform() from copying any extra markers - * (including EXIF and ICC profile data) from the source image to the output - * image. + * (including EXIF and ICC profile data) from the source image to the + * destination image. */ #define TJXOPT_COPYNONE (1 << 6) /** - * This option will enable arithmetic entropy coding in the output image + * This option will enable arithmetic entropy coding in the JPEG image * generated by this particular transform. Arithmetic entropy coding will * generally improve compression relative to Huffman entropy coding (the * default), but it will reduce compression and decompression performance @@ -619,12 +623,12 @@ typedef struct { */ int y; /** - * The width of the cropping region. Setting this to 0 is the equivalent of + * The width of the cropping region. Setting this to 0 is the equivalent of * setting it to the width of the source JPEG image - x. */ int w; /** - * The height of the cropping region. Setting this to 0 is the equivalent of + * The height of the cropping region. Setting this to 0 is the equivalent of * setting it to the height of the source JPEG image - y. */ int h; @@ -643,7 +647,8 @@ typedef struct tjtransform { */ int op; /** - * The bitwise OR of one of more of the @ref TJXOPT_CROP "transform options" + * The bitwise OR of one of more of the @ref TJXOPT_ARITHMETIC + * "transform options" */ int options; /** @@ -652,10 +657,10 @@ typedef struct tjtransform { */ void *data; /** - * A callback function that can be used to modify the DCT coefficients - * after they are losslessly transformed but before they are transcoded to a - * new JPEG image. This allows for custom filters or other transformations - * to be applied in the frequency domain. + * A callback function that can be used to modify the DCT coefficients after + * they are losslessly transformed but before they are transcoded to a new + * JPEG image. This allows for custom filters or other transformations to be + * applied in the frequency domain. * * @param coeffs pointer to an array of transformed DCT coefficients. (NOTE: * this pointer is not guaranteed to be valid once the callback returns, so @@ -663,21 +668,21 @@ typedef struct tjtransform { * or library should make a copy of them within the body of the callback.) * * @param arrayRegion #tjregion 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 + * 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. * * @param planeRegion #tjregion structure containing the width and height of - * the component plane to which coeffs belongs + * 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 0, 1, - * and 2 in typical JPEG images.) + * @param componentID ID 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.) * - * @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 #tjTransform(). + * @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 #tjTransform(). * * @param transform a pointer to a #tjtransform structure that specifies the * parameters and/or cropping region for this transform @@ -696,14 +701,14 @@ typedef void *tjhandle; /** - * Pad the given width to the nearest 32-bit boundary + * Pad the given width to the nearest multiple of 4 */ #define TJPAD(width) (((width) + 3) & (~3)) /** - * Compute the scaled value of dimension using the given scaling - * factor. This macro performs the integer equivalent of ceil(dimension * - * scalingFactor). + * Compute the scaled value of `dimension` using the given scaling factor. + * This macro performs the integer equivalent of `ceil(dimension * + * scalingFactor)`. */ #define TJSCALED(dimension, scalingFactor) \ (((dimension) * scalingFactor.num + scalingFactor.denom - 1) / \ @@ -718,27 +723,27 @@ extern "C" { /** * Create a TurboJPEG compressor instance. * - * @return a handle to the newly-created instance, or NULL if an error - * occurred (see #tjGetErrorStr2().) + * @return a handle to the newly-created instance, or NULL if an error occurred + * (see #tjGetErrorStr2().) */ DLLEXPORT tjhandle tjInitCompress(void); /** - * Compress an RGB, grayscale, or CMYK image into a JPEG image. + * Compress a packed-pixel RGB, grayscale, or CMYK image into a JPEG image. * * @param handle a handle to a TurboJPEG compressor or transformer instance * - * @param srcBuf pointer to an image buffer containing RGB, grayscale, or - * CMYK pixels to be compressed + * @param srcBuf pointer to a buffer containing a packed-pixel RGB, grayscale, + * or CMYK source image to be compressed * * @param width width (in pixels) of the source image * - * @param pitch bytes per line in the source image. Normally, this should be - * width * #tjPixelSize[pixelFormat] if the image is unpadded, or - * #TJPAD(width * #tjPixelSize[pixelFormat]) if each line of the image - * is padded to the nearest 32-bit boundary, as is the case for Windows - * bitmaps. You can also be clever and use this parameter to skip lines, etc. + * @param pitch bytes per row in the source image. Normally this should be + * width * #tjPixelSize[pixelFormat], if the image is unpadded, or + * #TJPAD(width * #tjPixelSize[pixelFormat]) if each row of the image + * is padded to the nearest multiple of 4 bytes, as is the case for Windows + * bitmaps. You can also be clever and use this parameter to skip rows, etc. * Setting this parameter to 0 is the equivalent of setting it to * width * #tjPixelSize[pixelFormat]. * @@ -747,29 +752,28 @@ DLLEXPORT tjhandle tjInitCompress(void); * @param pixelFormat pixel format of the source image (see @ref TJPF * "Pixel formats".) * - * @param jpegBuf address of a pointer to an image buffer that will receive the - * JPEG image. TurboJPEG has the ability to reallocate the JPEG buffer - * to accommodate the size of the JPEG image. Thus, you can choose to: + * @param jpegBuf address of a pointer to a byte buffer that will receive the + * JPEG image. TurboJPEG has the ability to reallocate the JPEG buffer to + * accommodate the size of the JPEG image. Thus, you can choose to: * -# pre-allocate the JPEG buffer with an arbitrary size using #tjAlloc() and * let TurboJPEG grow the buffer as needed, - * -# set *jpegBuf to NULL to tell TurboJPEG to allocate the buffer - * for you, or + * -# set `*jpegBuf` 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(). This should ensure that the buffer never has to be - * re-allocated (setting #TJFLAG_NOREALLOC guarantees that it won't be.) + * re-allocated. (Setting #TJFLAG_NOREALLOC guarantees that it won't be.) * . - * If you choose option 1, *jpegSize should be set to the size of your + * If you choose option 1, then `*jpegSize` should be set to the size of your * pre-allocated buffer. In any case, unless you have set #TJFLAG_NOREALLOC, - * you should always check *jpegBuf upon return from this function, as - * it may have changed. + * you should always check `*jpegBuf` upon return from this function, as it may + * have changed. * * @param jpegSize pointer to an unsigned long variable that holds the size of - * the JPEG image buffer. If *jpegBuf points to a pre-allocated - * buffer, then *jpegSize should be set to the size of the buffer. - * Upon return, *jpegSize will contain the size of the JPEG image (in - * bytes.) If *jpegBuf points to a JPEG image buffer that is being - * reused from a previous call to one of the JPEG compression functions, then - * *jpegSize is ignored. + * the JPEG buffer. If `*jpegBuf` points to a pre-allocated buffer, then + * `*jpegSize` should be set to the size of the buffer. Upon return, + * `*jpegSize` will contain the size of the JPEG image (in bytes.) If + * `*jpegBuf` points to a JPEG buffer that is being reused from a previous call + * to one of the JPEG compression functions, then `*jpegSize` is ignored. * * @param jpegSubsamp the level of chrominance subsampling to be used when * generating the JPEG image (see @ref TJSAMP @@ -789,7 +793,7 @@ DLLEXPORT tjhandle tjInitCompress(void); * * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr2() * and #tjGetErrorCode().) -*/ + */ DLLEXPORT int tjCompress2(tjhandle handle, const unsigned char *srcBuf, int width, int pitch, int height, int pixelFormat, unsigned char **jpegBuf, unsigned long *jpegSize, @@ -797,55 +801,55 @@ DLLEXPORT int tjCompress2(tjhandle handle, const unsigned char *srcBuf, /** - * Compress a YUV planar image into a JPEG image. + * Compress a unified planar YUV image into a JPEG image. * * @param handle a handle to a TurboJPEG compressor or transformer instance * - * @param srcBuf pointer to an image buffer containing a YUV planar image to be - * compressed. The size of this buffer should match the value returned by - * #tjBufSizeYUV2() for the given image width, height, padding, and level of - * chrominance subsampling. The Y, U (Cb), and V (Cr) image planes should be - * stored sequentially in the source buffer (refer to @ref YUVnotes - * "YUV Image Format Notes".) + * @param srcBuf pointer to a buffer containing a unified planar YUV source + * image to be compressed. The size of this buffer should match the value + * returned by #tjBufSizeYUV2() for the given image width, height, row + * alignment, and level of chrominance subsampling. The Y, U (Cb), and V (Cr) + * image planes should be stored sequentially in the buffer. (Refer to + * @ref YUVnotes "YUV Image Format Notes".) * * @param width width (in pixels) of the source image. If the width is not an * even multiple of the MCU block width (see #tjMCUWidth), then an intermediate - * buffer copy will be performed within TurboJPEG. + * buffer copy will be performed. * - * @param pad the line padding used in the source image. For instance, if each - * line in each plane of the YUV image is padded to the nearest multiple of 4 - * bytes, then pad should be set to 4. + * @param align row alignment (in bytes) of the source image (must be a power + * of 2.) Setting this parameter to n indicates that each row in each plane of + * the source image is padded to the nearest multiple of n bytes + * (1 = unpadded.) * * @param height height (in pixels) of the source image. If the height is not * an even multiple of the MCU block height (see #tjMCUHeight), then an - * intermediate buffer copy will be performed within TurboJPEG. + * intermediate buffer copy will be performed. * - * @param subsamp the level of chrominance subsampling used in the source - * image (see @ref TJSAMP "Chrominance subsampling options".) + * @param subsamp the level of chrominance subsampling used in the source image + * (see @ref TJSAMP "Chrominance subsampling options".) * - * @param jpegBuf address of a pointer to an image buffer that will receive the + * @param jpegBuf address of a pointer to a byte buffer that will receive the * JPEG image. TurboJPEG has the ability to reallocate the JPEG buffer to * accommodate the size of the JPEG image. Thus, you can choose to: * -# pre-allocate the JPEG buffer with an arbitrary size using #tjAlloc() and * let TurboJPEG grow the buffer as needed, - * -# set *jpegBuf to NULL to tell TurboJPEG to allocate the buffer - * for you, or + * -# set `*jpegBuf` 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(). This should ensure that the buffer never has to be - * re-allocated (setting #TJFLAG_NOREALLOC guarantees that it won't be.) + * re-allocated. (Setting #TJFLAG_NOREALLOC guarantees that it won't be.) * . - * If you choose option 1, *jpegSize should be set to the size of your + * If you choose option 1, then `*jpegSize` should be set to the size of your * pre-allocated buffer. In any case, unless you have set #TJFLAG_NOREALLOC, - * you should always check *jpegBuf upon return from this function, as - * it may have changed. + * you should always check `*jpegBuf` upon return from this function, as it may + * have changed. * * @param jpegSize pointer to an unsigned long variable that holds the size of - * the JPEG image buffer. If *jpegBuf points to a pre-allocated - * buffer, then *jpegSize should be set to the size of the buffer. - * Upon return, *jpegSize will contain the size of the JPEG image (in - * bytes.) If *jpegBuf points to a JPEG image buffer that is being - * reused from a previous call to one of the JPEG compression functions, then - * *jpegSize is ignored. + * the JPEG buffer. If `*jpegBuf` points to a pre-allocated buffer, then + * `*jpegSize` should be set to the size of the buffer. Upon return, + * `*jpegSize` will contain the size of the JPEG image (in bytes.) If + * `*jpegBuf` points to a JPEG buffer that is being reused from a previous call + * to one of the JPEG compression functions, then `*jpegSize` is ignored. * * @param jpegQual the image quality of the generated JPEG image (1 = worst, * 100 = best) @@ -855,9 +859,9 @@ DLLEXPORT int tjCompress2(tjhandle handle, const unsigned char *srcBuf, * * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr2() * and #tjGetErrorCode().) -*/ + */ DLLEXPORT int tjCompressFromYUV(tjhandle handle, const unsigned char *srcBuf, - int width, int pad, int height, int subsamp, + int width, int align, int height, int subsamp, unsigned char **jpegBuf, unsigned long *jpegSize, int jpegQual, int flags); @@ -870,55 +874,54 @@ DLLEXPORT int tjCompressFromYUV(tjhandle handle, const unsigned char *srcBuf, * * @param srcPlanes an array of pointers to Y, U (Cb), and V (Cr) image planes * (or just a Y plane, if compressing a grayscale image) that contain a YUV - * image to be compressed. These planes can be contiguous or non-contiguous in - * memory. The size of each plane should match the value returned by - * #tjPlaneSizeYUV() for the given image width, height, strides, and level of - * chrominance subsampling. Refer to @ref YUVnotes "YUV Image Format Notes" - * for more details. + * source image to be compressed. These planes can be contiguous or + * non-contiguous in memory. The size of each plane should match the value + * returned by #tjPlaneSizeYUV() for the given image width, height, strides, + * and level of chrominance subsampling. Refer to @ref YUVnotes + * "YUV Image Format Notes" for more details. * * @param width width (in pixels) of the source image. If the width is not an * even multiple of the MCU block width (see #tjMCUWidth), then an intermediate - * buffer copy will be performed within TurboJPEG. + * buffer copy will be performed. * * @param strides an array of integers, each specifying the number of bytes per - * line in the corresponding plane of the YUV source image. Setting the stride + * row in the corresponding plane of the YUV source image. Setting the stride * for any plane to 0 is the same as setting it to the plane width (see - * @ref YUVnotes "YUV Image Format Notes".) If strides is NULL, then - * the strides for all planes will be set to their respective plane widths. - * You can adjust the strides in order to specify an arbitrary amount of line + * @ref YUVnotes "YUV Image Format Notes".) If `strides` is NULL, then the + * strides for all planes will be set to their respective plane widths. You + * can adjust the strides in order to specify an arbitrary amount of row * padding in each plane or to create a JPEG image from a subregion of a larger - * YUV planar image. + * planar YUV image. * * @param height height (in pixels) of the source image. If the height is not * an even multiple of the MCU block height (see #tjMCUHeight), then an - * intermediate buffer copy will be performed within TurboJPEG. + * intermediate buffer copy will be performed. * - * @param subsamp the level of chrominance subsampling used in the source - * image (see @ref TJSAMP "Chrominance subsampling options".) + * @param subsamp the level of chrominance subsampling used in the source image + * (see @ref TJSAMP "Chrominance subsampling options".) * - * @param jpegBuf address of a pointer to an image buffer that will receive the + * @param jpegBuf address of a pointer to a byte buffer that will receive the * JPEG image. TurboJPEG has the ability to reallocate the JPEG buffer to * accommodate the size of the JPEG image. Thus, you can choose to: * -# pre-allocate the JPEG buffer with an arbitrary size using #tjAlloc() and * let TurboJPEG grow the buffer as needed, - * -# set *jpegBuf to NULL to tell TurboJPEG to allocate the buffer - * for you, or + * -# set `*jpegBuf` 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(). This should ensure that the buffer never has to be - * re-allocated (setting #TJFLAG_NOREALLOC guarantees that it won't be.) + * re-allocated. (Setting #TJFLAG_NOREALLOC guarantees that it won't be.) * . - * If you choose option 1, *jpegSize should be set to the size of your + * If you choose option 1, then `*jpegSize` should be set to the size of your * pre-allocated buffer. In any case, unless you have set #TJFLAG_NOREALLOC, - * you should always check *jpegBuf upon return from this function, as - * it may have changed. + * you should always check `*jpegBuf` upon return from this function, as it may + * have changed. * * @param jpegSize pointer to an unsigned long variable that holds the size of - * the JPEG image buffer. If *jpegBuf points to a pre-allocated - * buffer, then *jpegSize should be set to the size of the buffer. - * Upon return, *jpegSize will contain the size of the JPEG image (in - * bytes.) If *jpegBuf points to a JPEG image buffer that is being - * reused from a previous call to one of the JPEG compression functions, then - * *jpegSize is ignored. + * the JPEG buffer. If `*jpegBuf` points to a pre-allocated buffer, then + * `*jpegSize` should be set to the size of the buffer. Upon return, + * `*jpegSize` will contain the size of the JPEG image (in bytes.) If + * `*jpegBuf` points to a JPEG buffer that is being reused from a previous call + * to one of the JPEG compression functions, then `*jpegSize` is ignored. * * @param jpegQual the image quality of the generated JPEG image (1 = worst, * 100 = best) @@ -928,7 +931,7 @@ DLLEXPORT int tjCompressFromYUV(tjhandle handle, const unsigned char *srcBuf, * * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr2() * and #tjGetErrorCode().) -*/ + */ DLLEXPORT int tjCompressFromYUVPlanes(tjhandle handle, const unsigned char **srcPlanes, int width, const int *strides, @@ -942,11 +945,11 @@ DLLEXPORT int tjCompressFromYUVPlanes(tjhandle handle, * 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 + * is that the JPEG format uses 16-bit coefficients, so it is possible for a + * very high-quality source image with very high-frequency content to expand + * rather than compress when converted to the JPEG format. Such images + * represent very rare corner cases, but since there is no way to predict the + * size of a JPEG image prior to compression, the corner cases have to be * handled. * * @param width width (in pixels) of the image @@ -964,23 +967,24 @@ DLLEXPORT unsigned long tjBufSize(int width, int height, int jpegSubsamp); /** - * The size of the buffer (in bytes) required to hold a YUV planar image with - * the given parameters. + * The size of the buffer (in bytes) required to hold a unified planar YUV + * image with the given parameters. * * @param width width (in pixels) of the image * - * @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 align row alignment (in bytes) of the image (must be a power of 2.) + * Setting this parameter to n specifies that each row in each plane of the + * image will be padded to the nearest multiple of n bytes (1 = unpadded.) * * @param height height (in pixels) of the image * * @param subsamp level of chrominance subsampling in the image (see * @ref TJSAMP "Chrominance subsampling options".) * - * @return the size of the buffer (in bytes) required to hold the image, or - * -1 if the arguments are out of bounds. + * @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 tjBufSizeYUV2(int width, int pad, int height, +DLLEXPORT unsigned long tjBufSizeYUV2(int width, int align, int height, int subsamp); @@ -993,7 +997,7 @@ DLLEXPORT unsigned long tjBufSizeYUV2(int width, int pad, int height, * @param width width (in pixels) of the YUV image. NOTE: this is the width of * the whole image, not the plane width. * - * @param stride bytes per line in the image plane. Setting this to 0 is the + * @param stride bytes per row in the image plane. Setting this to 0 is the * equivalent of setting it to the plane width. * * @param height height (in pixels) of the YUV image. NOTE: this is the height @@ -1044,23 +1048,23 @@ DLLEXPORT int tjPlaneHeight(int componentID, int height, int subsamp); /** - * Encode an RGB or grayscale image into a YUV planar image. This function - * uses the accelerated color conversion routines in the underlying - * codec but does not execute any of the other steps in the JPEG compression - * process. + * Encode a packed-pixel RGB or grayscale image into a unified planar YUV + * image. This function performs color conversion (which is accelerated in the + * libjpeg-turbo implementation) but does not execute any of the other steps in + * the JPEG compression process. * * @param handle a handle to a TurboJPEG compressor or transformer instance * - * @param srcBuf pointer to an image buffer containing RGB or grayscale pixels - * to be encoded + * @param srcBuf pointer to a buffer containing a packed-pixel RGB or grayscale + * source image to be encoded * * @param width width (in pixels) of the source image * - * @param pitch bytes per line in the source image. Normally, this should be - * width * #tjPixelSize[pixelFormat] if the image is unpadded, or - * #TJPAD(width * #tjPixelSize[pixelFormat]) if each line of the image - * is padded to the nearest 32-bit boundary, as is the case for Windows - * bitmaps. You can also be clever and use this parameter to skip lines, etc. + * @param pitch bytes per row in the source image. Normally this should be + * width * #tjPixelSize[pixelFormat], if the image is unpadded, or + * #TJPAD(width * #tjPixelSize[pixelFormat]) if each row of the image + * is padded to the nearest multiple of 4 bytes, as is the case for Windows + * bitmaps. You can also be clever and use this parameter to skip rows, etc. * Setting this parameter to 0 is the equivalent of setting it to * width * #tjPixelSize[pixelFormat]. * @@ -1069,53 +1073,54 @@ DLLEXPORT int tjPlaneHeight(int componentID, int height, int subsamp); * @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 #tjBufSizeYUV2() to determine the appropriate size for this buffer based - * on the image width, height, padding, and level of chrominance subsampling. - * The Y, U (Cb), and V (Cr) image planes will be stored sequentially in the - * buffer (refer to @ref YUVnotes "YUV Image Format Notes".) + * @param dstBuf pointer to a buffer that will receive the unified planar YUV + * image. Use #tjBufSizeYUV2() to determine the appropriate size for this + * buffer based on the image width, height, row alignment, and level of + * chrominance subsampling. The Y, U (Cb), and V (Cr) image planes will be + * stored sequentially in the buffer. (Refer to @ref YUVnotes + * "YUV Image Format Notes".) * - * @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 align row alignment (in bytes) of the YUV image (must be a power of + * 2.) Setting this parameter to n will cause each row in each plane of the + * YUV image to be padded to the nearest multiple of n bytes (1 = unpadded.) + * To generate images suitable for X Video, `align` 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".) 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. + * 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_ACCURATEDCT * "flags" * * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr2() * and #tjGetErrorCode().) -*/ + */ DLLEXPORT int tjEncodeYUV3(tjhandle handle, const unsigned char *srcBuf, int width, int pitch, int height, int pixelFormat, - unsigned char *dstBuf, int pad, int subsamp, + unsigned char *dstBuf, int align, int subsamp, int flags); /** - * Encode an RGB or grayscale image into separate Y, U (Cb), and V (Cr) image - * planes. This function uses the accelerated color conversion routines in the - * underlying codec but does not execute any of the other steps in the JPEG - * compression process. + * Encode a packed-pixel RGB or grayscale image into separate Y, U (Cb), and + * V (Cr) image planes. This function performs color conversion (which is + * accelerated in the libjpeg-turbo implementation) but does not execute any of + * the other steps in the JPEG compression process. * * @param handle a handle to a TurboJPEG compressor or transformer instance * - * @param srcBuf pointer to an image buffer containing RGB or grayscale pixels - * to be encoded + * @param srcBuf pointer to a buffer containing a packed-pixel RGB or grayscale + * source image to be encoded * * @param width width (in pixels) of the source image * - * @param pitch bytes per line in the source image. Normally, this should be - * width * #tjPixelSize[pixelFormat] if the image is unpadded, or - * #TJPAD(width * #tjPixelSize[pixelFormat]) if each line of the image - * is padded to the nearest 32-bit boundary, as is the case for Windows - * bitmaps. You can also be clever and use this parameter to skip lines, etc. + * @param pitch bytes per row in the source image. Normally this should be + * width * #tjPixelSize[pixelFormat], if the image is unpadded, or + * #TJPAD(width * #tjPixelSize[pixelFormat]) if each row of the image + * is padded to the nearest multiple of 4 bytes, as is the case for Windows + * bitmaps. You can also be clever and use this parameter to skip rows, etc. * Setting this parameter to 0 is the equivalent of setting it to * width * #tjPixelSize[pixelFormat]. * @@ -1132,26 +1137,26 @@ DLLEXPORT int tjEncodeYUV3(tjhandle handle, const unsigned char *srcBuf, * Refer to @ref YUVnotes "YUV Image Format Notes" for more details. * * @param strides an array of integers, each specifying the number of bytes per - * line in the corresponding plane of the output image. Setting the stride for - * any plane to 0 is the same as setting it to the plane width (see - * @ref YUVnotes "YUV Image Format Notes".) If strides is NULL, then - * the strides for all planes will be set to their respective plane widths. - * You can adjust the strides in order to add an arbitrary amount of line - * padding to each plane or to encode an RGB or grayscale image into a - * subregion of a larger YUV planar image. + * row in the corresponding plane of the YUV image. Setting the stride for any + * plane to 0 is the same as setting it to the plane width (see @ref YUVnotes + * "YUV Image Format Notes".) If `strides` is NULL, then the strides for all + * planes will be set to their respective plane widths. You can adjust the + * strides in order to add an arbitrary amount of row padding to each plane or + * to encode an RGB or grayscale image into a subregion of a larger planar YUV + * image. * * @param subsamp the level of chrominance subsampling to be used when * generating the YUV image (see @ref TJSAMP * "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. + * 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_ACCURATEDCT * "flags" * * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr2() * and #tjGetErrorCode().) -*/ + */ DLLEXPORT int tjEncodeYUVPlanes(tjhandle handle, const unsigned char *srcBuf, int width, int pitch, int height, int pixelFormat, unsigned char **dstPlanes, @@ -1161,9 +1166,9 @@ DLLEXPORT int tjEncodeYUVPlanes(tjhandle handle, const unsigned char *srcBuf, /** * Create a TurboJPEG decompressor instance. * - * @return a handle to the newly-created instance, or NULL if an error - * occurred (see #tjGetErrorStr2().) -*/ + * @return a handle to the newly-created instance, or NULL if an error occurred + * (see #tjGetErrorStr2().) + */ DLLEXPORT tjhandle tjInitDecompress(void); @@ -1173,7 +1178,7 @@ DLLEXPORT tjhandle tjInitDecompress(void); * * @param handle a handle to a TurboJPEG decompressor or transformer instance * - * @param jpegBuf pointer to a buffer containing a JPEG image or an + * @param jpegBuf pointer to a byte buffer containing a JPEG image or an * "abbreviated table specification" (AKA "tables-only") datastream. Passing a * tables-only datastream to this function primes the decompressor with * quantization and Huffman tables that can be used when decompressing @@ -1184,22 +1189,22 @@ DLLEXPORT tjhandle tjInitDecompress(void); * @param jpegSize size of the JPEG image or tables-only datastream (in bytes) * * @param width pointer to an integer variable that will receive the width (in - * pixels) of the JPEG image. If jpegBuf points to a tables-only - * datastream, then width is ignored. + * pixels) of the JPEG image. If `jpegBuf` points to a tables-only datastream, + * then `width` is ignored. * * @param height pointer to an integer variable that will receive the height - * (in pixels) of the JPEG image. If jpegBuf points to a tables-only - * datastream, then height is ignored. + * (in pixels) of the JPEG image. If `jpegBuf` points to a tables-only + * datastream, then `height` is ignored. * * @param jpegSubsamp pointer to an integer variable that will receive the * level of chrominance subsampling used when the JPEG image was compressed - * (see @ref TJSAMP "Chrominance subsampling options".) If jpegBuf - * points to a tables-only datastream, then jpegSubsamp is ignored. + * (see @ref TJSAMP "Chrominance subsampling options".) If `jpegBuf` points to + * a tables-only datastream, then `jpegSubsamp` is ignored. * * @param jpegColorspace pointer to an integer variable that will receive one * of the JPEG colorspace constants, indicating the colorspace of the JPEG - * image (see @ref TJCS "JPEG colorspaces".) If jpegBuf - * points to a tables-only datastream, then jpegColorspace is ignored. + * image (see @ref TJCS "JPEG colorspaces".) If `jpegBuf` points to a + * tables-only datastream, then `jpegColorspace` is ignored. * * @param jpegFlags pointer to an integer variable that will receive the * bitwise OR of one or more of the @ref TJFLAG_ACCURATEDCT "flags", such as @@ -1209,7 +1214,7 @@ DLLEXPORT tjhandle tjInitDecompress(void); * * @return 0 if successful, or -1 if an error occurred (see #tjGetErrorStr2() * and #tjGetErrorCode().) -*/ + */ DLLEXPORT int tjDecompressHeader4(tjhandle handle, const unsigned char *jpegBuf, unsigned long jpegSize, int *width, @@ -1218,58 +1223,60 @@ DLLEXPORT int tjDecompressHeader4(tjhandle handle, /** - * Returns a list of fractional scaling factors that the JPEG decompressor in - * this implementation of TurboJPEG supports. + * Returns a list of fractional scaling factors that the JPEG decompressor + * supports. * - * @param numscalingfactors pointer to an integer variable that will receive + * @param numScalingFactors pointer to an integer variable that will receive * the number of elements in the list * * @return a pointer to a list of fractional scaling factors, or NULL if an * error is encountered (see #tjGetErrorStr2().) -*/ -DLLEXPORT tjscalingfactor *tjGetScalingFactors(int *numscalingfactors); + */ +DLLEXPORT tjscalingfactor *tjGetScalingFactors(int *numScalingFactors); /** - * Decompress a JPEG image to an RGB, grayscale, or CMYK image. + * Decompress a JPEG image into a packed-pixel RGB, grayscale, or CMYK image. * * @param handle a handle to a TurboJPEG decompressor or transformer instance * - * @param jpegBuf pointer to a buffer containing the JPEG image to decompress + * @param jpegBuf pointer to a byte 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 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. + * @param dstBuf pointer to a buffer that will receive the packed-pixel + * 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. * * @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. + * 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 pitch bytes per line in 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 + * @param pitch bytes per row in the destination image. Normally this should + * be set to scaledWidth * #tjPixelSize[pixelFormat], if the + * destination image should be unpadded, or + * #TJPAD(scaledWidth * #tjPixelSize[pixelFormat]) if each row of the + * destination image should be padded to the nearest multiple of 4 bytes, 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 rows, etc. Setting this parameter to 0 is the + * equivalent of setting it to * scaledWidth * #tjPixelSize[pixelFormat]. * * @param height desired 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. + * 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 pixelFormat pixel format of the destination image (see @ref * TJPF "Pixel formats".) @@ -1287,44 +1294,45 @@ DLLEXPORT int tjDecompress2(tjhandle handle, const unsigned char *jpegBuf, /** - * 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. + * Decompress a JPEG image into a unified planar YUV image. This function + * performs JPEG decompression but leaves out the color conversion step, so a + * planar YUV image is generated instead of a packed-pixel image. * * @param handle a handle to a TurboJPEG decompressor or transformer instance * - * @param jpegBuf pointer to a buffer containing the JPEG image to decompress + * @param jpegBuf pointer to a byte 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 #tjBufSizeYUV2() to determine the appropriate size for this buffer based - * on the image width, height, padding, and level of subsampling. The Y, - * U (Cb), and V (Cr) image planes will be stored sequentially in the buffer - * (refer to @ref YUVnotes "YUV Image Format Notes".) + * @param dstBuf pointer to a buffer that will receive the unified planar YUV + * decompressed image. Use #tjBufSizeYUV2() to determine the appropriate size + * for this buffer based on the scaled image width, scaled image height, row + * alignment, and level of chrominance subsampling. The Y, U (Cb), and V (Cr) + * image planes will be stored sequentially in the buffer. (Refer to + * @ref YUVnotes "YUV Image Format Notes".) * * @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. If the scaled width is not an even multiple of the MCU - * block width (see #tjMCUWidth), then an intermediate buffer copy will be - * performed within TurboJPEG. + * 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. If the scaled width is not an even multiple of the MCU block width + * (see #tjMCUWidth), then an intermediate buffer copy will be performed. * - * @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 align row alignment (in bytes) of the YUV image (must be a power of + * 2.) Setting this parameter to n will cause each row in each plane of the + * YUV image to be padded to the nearest multiple of n bytes (1 = unpadded.) + * To generate images suitable for X Video, `align` 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. If the scaled height is not an even multiple of the MCU - * block height (see #tjMCUHeight), then an intermediate buffer copy will be - * performed within TurboJPEG. + * 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 the scaled height is not an even multiple of the MCU block + * height (see #tjMCUHeight), then an intermediate buffer copy will be + * performed. * * @param flags the bitwise OR of one or more of the @ref TJFLAG_ACCURATEDCT * "flags" @@ -1334,54 +1342,55 @@ DLLEXPORT int tjDecompress2(tjhandle handle, const unsigned char *jpegBuf, */ DLLEXPORT int tjDecompressToYUV2(tjhandle handle, const unsigned char *jpegBuf, unsigned long jpegSize, unsigned char *dstBuf, - int width, int pad, int height, int flags); + int width, int align, int height, int flags); /** * Decompress a JPEG image into separate Y, U (Cb), and V (Cr) image * planes. This function performs JPEG decompression but leaves out the color - * conversion step, so a planar YUV image is generated instead of an RGB image. + * conversion step, so a planar YUV image is generated instead of a + * packed-pixel image. * * @param handle a handle to a TurboJPEG decompressor or transformer instance * - * @param jpegBuf pointer to a buffer containing the JPEG image to decompress + * @param jpegBuf pointer to a byte buffer containing the JPEG image to + * decompress * * @param jpegSize size of the JPEG image (in bytes) * * @param dstPlanes an array of pointers to Y, U (Cb), and V (Cr) image planes * (or just a Y plane, if decompressing a grayscale image) that will receive - * the YUV image. These planes can be contiguous or non-contiguous in memory. - * Use #tjPlaneSizeYUV() to determine the appropriate size for each plane based - * on the scaled image width, scaled image height, strides, and level of - * chrominance subsampling. Refer to @ref YUVnotes "YUV Image Format Notes" - * for more details. + * the decompressed image. These planes can be contiguous or non-contiguous in + * memory. Use #tjPlaneSizeYUV() to determine the appropriate size for each + * plane based on the scaled image width, scaled image height, strides, and + * level of chrominance subsampling. Refer to @ref YUVnotes + * "YUV Image Format Notes" for more details. * * @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. If the scaled width is not an even multiple of the MCU - * block width (see #tjMCUWidth), then an intermediate buffer copy will be - * performed within TurboJPEG. + * 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. If the scaled width is not an even multiple of the MCU block width + * (see #tjMCUWidth), then an intermediate buffer copy will be performed. * * @param strides an array of integers, each specifying the number of bytes per - * line in the corresponding plane of the output image. Setting the stride for - * any plane to 0 is the same as setting it to the scaled plane width (see - * @ref YUVnotes "YUV Image Format Notes".) If strides is NULL, then - * the strides for all planes will be set to their respective scaled plane - * widths. You can adjust the strides in order to add an arbitrary amount of - * line padding to each plane or to decompress the JPEG image into a subregion - * of a larger YUV planar image. + * row in the corresponding plane of the YUV image. Setting the stride for any + * plane to 0 is the same as setting it to the scaled plane width (see + * @ref YUVnotes "YUV Image Format Notes".) If `strides` is NULL, then the + * strides for all planes will be set to their respective scaled plane widths. + * You can adjust the strides in order to add an arbitrary amount of row + * padding to each plane or to decompress the JPEG image into a subregion of a + * larger planar YUV image. * * @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. If the scaled height is not an even multiple of the MCU - * block height (see #tjMCUHeight), then an intermediate buffer copy will be - * performed within TurboJPEG. + * 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 the scaled height is not an even multiple of the MCU block + * height (see #tjMCUHeight), then an intermediate buffer copy will be + * performed. * * @param flags the bitwise OR of one or more of the @ref TJFLAG_ACCURATEDCT * "flags" @@ -1397,40 +1406,42 @@ DLLEXPORT int tjDecompressToYUVPlanes(tjhandle handle, /** - * Decode a YUV planar image into an RGB or grayscale image. This function - * uses the accelerated color conversion routines in the underlying - * codec but does not execute any of the other steps in the JPEG decompression - * process. + * Decode a unified planar YUV image into a packed-pixel RGB or grayscale + * image. This function performs color conversion (which is accelerated in the + * libjpeg-turbo implementation) but does not execute any of the other steps in + * the JPEG decompression process. * * @param handle a handle to a TurboJPEG decompressor or transformer instance * - * @param srcBuf pointer to an image buffer containing a YUV planar image to be - * decoded. The size of this buffer should match the value returned by - * #tjBufSizeYUV2() for the given image width, height, padding, and level of - * chrominance subsampling. The Y, U (Cb), and V (Cr) image planes should be - * stored sequentially in the source buffer (refer to @ref YUVnotes - * "YUV Image Format Notes".) + * @param srcBuf pointer to a buffer containing a unified planar YUV source + * image to be decoded. The size of this buffer should match the value + * returned by #tjBufSizeYUV2() for the given image width, height, row + * alignment, and level of chrominance subsampling. The Y, U (Cb), and V (Cr) + * image planes should be stored sequentially in the source buffer. (Refer to + * @ref YUVnotes "YUV Image Format Notes".) * - * @param pad Use this parameter to specify that the width of each line in each - * plane of the YUV source image is padded to the nearest multiple of this - * number of bytes (must be a power of 2.) + * @param align row alignment (in bytes) of the YUV source image (must be a + * power of 2.) Setting this parameter to n indicates that each row in each + * plane of the YUV source image is padded to the nearest multiple of n bytes + * (1 = unpadded.) * * @param subsamp the level of chrominance subsampling used in the YUV source * image (see @ref TJSAMP "Chrominance subsampling options".) * - * @param dstBuf pointer to an image buffer that will receive the decoded - * image. This buffer should normally be pitch * height bytes in - * size, but the dstBuf pointer can also be used to decode into a - * specific region of a larger buffer. + * @param dstBuf pointer to a buffer that will receive the packed-pixel decoded + * image. This buffer should normally be `pitch * height` bytes in size, but + * the `dstBuf` pointer can also be used to decode into a specific region of a + * larger buffer. * * @param width width (in pixels) of the source and destination images * - * @param pitch bytes per line in the destination image. Normally, this should - * be width * #tjPixelSize[pixelFormat] if the destination image is - * unpadded, or #TJPAD(width * #tjPixelSize[pixelFormat]) if each line - * of the destination image should be padded to the nearest 32-bit boundary, as - * is the case for Windows bitmaps. You can also be clever and use the pitch - * parameter to skip lines, etc. Setting this parameter to 0 is the equivalent + * @param pitch bytes per row in the destination image. Normally this should + * be set to width * #tjPixelSize[pixelFormat], if the destination + * image should be unpadded, or + * #TJPAD(width * #tjPixelSize[pixelFormat]) if each row of the + * destination image should be padded to the nearest multiple of 4 bytes, as is + * the case for Windows bitmaps. You can also be clever and use the pitch + * parameter to skip rows, etc. Setting this parameter to 0 is the equivalent * of setting it to width * #tjPixelSize[pixelFormat]. * * @param height height (in pixels) of the source and destination images @@ -1445,16 +1456,16 @@ DLLEXPORT int tjDecompressToYUVPlanes(tjhandle handle, * and #tjGetErrorCode().) */ DLLEXPORT int tjDecodeYUV(tjhandle handle, const unsigned char *srcBuf, - int pad, int subsamp, unsigned char *dstBuf, + int align, int subsamp, unsigned char *dstBuf, int width, int pitch, int height, int pixelFormat, int flags); /** - * Decode a set of Y, U (Cb), and V (Cr) image planes into an RGB or grayscale - * image. This function uses the accelerated color conversion routines in the - * underlying codec but does not execute any of the other steps in the JPEG - * decompression process. + * Decode a set of Y, U (Cb), and V (Cr) image planes into a packed-pixel RGB + * or grayscale image. This function performs color conversion (which is + * accelerated in the libjpeg-turbo implementation) but does not execute any of + * the other steps in the JPEG decompression process. * * @param handle a handle to a TurboJPEG decompressor or transformer instance * @@ -1467,29 +1478,30 @@ DLLEXPORT int tjDecodeYUV(tjhandle handle, const unsigned char *srcBuf, * details. * * @param strides an array of integers, each specifying the number of bytes per - * line in the corresponding plane of the YUV source image. Setting the stride + * row in the corresponding plane of the YUV source image. Setting the stride * for any plane to 0 is the same as setting it to the plane width (see - * @ref YUVnotes "YUV Image Format Notes".) If strides is NULL, then - * the strides for all planes will be set to their respective plane widths. - * You can adjust the strides in order to specify an arbitrary amount of line - * padding in each plane or to decode a subregion of a larger YUV planar image. + * @ref YUVnotes "YUV Image Format Notes".) If `strides` is NULL, then the + * strides for all planes will be set to their respective plane widths. You + * can adjust the strides in order to specify an arbitrary amount of row + * padding in each plane or to decode a subregion of a larger planar YUV image. * * @param subsamp the level of chrominance subsampling used in the YUV source * image (see @ref TJSAMP "Chrominance subsampling options".) * - * @param dstBuf pointer to an image buffer that will receive the decoded - * image. This buffer should normally be pitch * height bytes in - * size, but the dstBuf pointer can also be used to decode into a - * specific region of a larger buffer. + * @param dstBuf pointer to a buffer that will receive the packed-pixel decoded + * image. This buffer should normally be `pitch * height` bytes in size, but + * the `dstBuf` pointer can also be used to decode into a specific region of a + * larger buffer. * * @param width width (in pixels) of the source and destination images * - * @param pitch bytes per line in the destination image. Normally, this should - * be width * #tjPixelSize[pixelFormat] if the destination image is - * unpadded, or #TJPAD(width * #tjPixelSize[pixelFormat]) if each line - * of the destination image should be padded to the nearest 32-bit boundary, as - * is the case for Windows bitmaps. You can also be clever and use the pitch - * parameter to skip lines, etc. Setting this parameter to 0 is the equivalent + * @param pitch bytes per row in the destination image. Normally this should + * be set to width * #tjPixelSize[pixelFormat], if the destination + * image should be unpadded, or + * #TJPAD(width * #tjPixelSize[pixelFormat]) if each row of the + * destination image should be padded to the nearest multiple of 4 bytes, as is + * the case for Windows bitmaps. You can also be clever and use the pitch + * parameter to skip rows, etc. Setting this parameter to 0 is the equivalent * of setting it to width * #tjPixelSize[pixelFormat]. * * @param height height (in pixels) of the source and destination images @@ -1528,50 +1540,51 @@ DLLEXPORT tjhandle tjInitTransform(void); * 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. + * 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 source image to + * @param jpegBuf pointer to a byte buffer containing the JPEG source image to * transform * * @param jpegSize size of the JPEG source image (in bytes) * * @param n the number of transformed JPEG images to generate * - * @param dstBufs pointer 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: - * -# pre-allocate the JPEG buffer with an arbitrary size using #tjAlloc() and - * let TurboJPEG grow the buffer as needed, - * -# set dstBufs[i] to NULL to tell TurboJPEG to allocate the buffer - * for you, or + * @param dstBufs pointer to an array of n byte 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 + * destination buffer to accommodate the size of the transformed JPEG image. + * Thus, you can choose to: + * -# pre-allocate the JPEG destination buffer with an arbitrary size using + * #tjAlloc() and let TurboJPEG grow the buffer as needed, + * -# 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 transformed or cropped width and height. Under normal * circumstances, this should ensure that the buffer never has to be - * re-allocated (setting #TJFLAG_NOREALLOC guarantees that it won't be.) Note, - * however, that there are some rare cases (such as transforming images with a - * large amount of embedded EXIF or ICC profile data) in which the output image - * will be larger than the worst-case size, and #TJFLAG_NOREALLOC cannot be - * used in those cases. + * re-allocated. (Setting #TJFLAG_NOREALLOC guarantees that it won't be.) + * Note, however, that there are some rare cases (such as transforming images + * with a large amount of embedded EXIF or ICC profile data) in which the + * transformed JPEG image will be larger than the worst-case size, and + * #TJFLAG_NOREALLOC cannot be used in those cases. * . - * 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. + * If you choose option 1, then `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. * * @param dstSizes pointer 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.) + * `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 transformed JPEG image (in bytes.) * * @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. + * corresponding transformed JPEG image. * * @param flags the bitwise OR of one or more of the @ref TJFLAG_ACCURATEDCT * "flags" @@ -1597,10 +1610,10 @@ DLLEXPORT int tjDestroy(tjhandle handle); /** - * Allocate an image buffer for use with TurboJPEG. You should always use - * this function to allocate the JPEG destination buffer(s) for the compression - * and transform functions unless you are disabling automatic buffer - * (re)allocation (by setting #TJFLAG_NOREALLOC.) + * Allocate a byte buffer for use with TurboJPEG. You should always use this + * function to allocate the JPEG destination buffer(s) for the compression and + * transform functions unless you are disabling automatic buffer (re)allocation + * (by setting #TJFLAG_NOREALLOC.) * * @param bytes the number of bytes to allocate * @@ -1613,44 +1626,43 @@ DLLEXPORT unsigned char *tjAlloc(int bytes); /** - * Load an uncompressed image from disk into memory. + * Load a packed-pixel image from disk into memory. * - * @param filename name of a file containing an uncompressed image in Windows + * @param filename name of a file containing a packed-pixel image in Windows * BMP or PBMPLUS (PPM/PGM) format * * @param width pointer to an integer variable that will receive the width (in - * pixels) of the uncompressed image + * pixels) of the packed-pixel image * - * @param align row alignment of the image buffer to be returned (must be a - * power of 2.) For instance, setting this parameter to 4 will cause all rows - * in the image buffer to be padded to the nearest 32-bit boundary, and setting - * this parameter to 1 will cause all rows in the image buffer to be unpadded. + * @param align row alignment of the packed-pixel buffer to be returned (must + * be a power of 2.) Setting this parameter to n will cause all rows in the + * buffer to be padded to the nearest multiple of n bytes (1 = unpadded.) * * @param height pointer to an integer variable that will receive the height - * (in pixels) of the uncompressed image + * (in pixels) of the packed-pixel image * * @param pixelFormat pointer to an integer variable that specifies or will - * receive the pixel format of the uncompressed image buffer. The behavior of - * #tjLoadImage() will vary depending on the value of *pixelFormat - * passed to the function: - * - @ref TJPF_UNKNOWN : The uncompressed image buffer returned by the function - * will use the most optimal pixel format for the file type, and - * *pixelFormat will contain the ID of this pixel format upon - * successful return from the function. - * - @ref TJPF_GRAY : Only PGM files and 8-bit BMP files with a grayscale - * colormap can be loaded. + * receive the pixel format of the packed-pixel buffer. The behavior of + * #tjLoadImage() will vary depending on the value of `*pixelFormat` passed to + * the function: + * - @ref TJPF_UNKNOWN : The packed-pixel buffer returned by this function will + * use the most optimal pixel format for the file type, and `*pixelFormat` will + * contain the ID of that pixel format upon successful return from this + * function. + * - @ref TJPF_GRAY : Only PGM files and 8-bit-per-pixel BMP files with a + * grayscale colormap can be loaded. * - @ref TJPF_CMYK : The RGB or grayscale pixels stored in the file will be * converted using a quick & dirty algorithm that is suitable only for testing - * purposes (proper conversion between CMYK and other formats requires a color - * management system.) - * - Other @ref TJPF "pixel formats" : The uncompressed image buffer will use - * the specified pixel format, and pixel format conversion will be performed if + * purposes. (Proper conversion between CMYK and other formats requires a + * color management system.) + * - Other @ref TJPF "pixel formats" : The packed-pixel buffer will use the + * specified pixel format, and pixel format conversion will be performed if * necessary. * * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP * "flags". * - * @return a pointer to a newly-allocated buffer containing the uncompressed + * @return a pointer to a newly-allocated buffer containing the packed-pixel * image, converted to the chosen pixel format and with the chosen row * alignment, or NULL if an error occurred (see #tjGetErrorStr2().) This * buffer should be freed using #tjFree(). @@ -1661,31 +1673,31 @@ DLLEXPORT unsigned char *tjLoadImage(const char *filename, int *width, /** - * Save an uncompressed image from memory to disk. + * Save a packed-pixel image from memory to disk. * - * @param filename name of a file to which to save the uncompressed image. - * The image will be stored in Windows BMP or PBMPLUS (PPM/PGM) format, - * depending on the file extension. + * @param filename name of a file to which to save the packed-pixel image. The + * image will be stored in Windows BMP or PBMPLUS (PPM/PGM) format, depending + * on the file extension. * - * @param buffer pointer to an image buffer containing RGB, grayscale, or - * CMYK pixels to be saved + * @param buffer pointer to a buffer containing a packed-pixel RGB, grayscale, + * or CMYK image to be saved * - * @param width width (in pixels) of the uncompressed image + * @param width width (in pixels) of the packed-pixel image * - * @param pitch bytes per line in the image buffer. Setting this parameter to - * 0 is the equivalent of setting it to + * @param pitch bytes per row in the packed-pixel image. Setting this + * parameter to 0 is the equivalent of setting it to * width * #tjPixelSize[pixelFormat]. * - * @param height height (in pixels) of the uncompressed image + * @param height height (in pixels) of the packed-pixel image * - * @param pixelFormat pixel format of the image buffer (see @ref TJPF + * @param pixelFormat pixel format of the packed-pixel image (see @ref TJPF * "Pixel formats".) If this parameter is set to @ref TJPF_GRAY, then the - * image will be stored in PGM or 8-bit (indexed color) BMP format. Otherwise, - * the image will be stored in PPM or 24-bit BMP format. If this parameter - * is set to @ref TJPF_CMYK, then the CMYK pixels will be converted to RGB - * using a quick & dirty algorithm that is suitable only for testing (proper - * conversion between CMYK and other formats requires a color management - * system.) + * image will be stored in PGM or 8-bit-per-pixel (indexed color) BMP format. + * Otherwise, the image will be stored in PPM or 24-bit-per-pixel BMP format. + * If this parameter is set to @ref TJPF_CMYK, then the CMYK pixels will be + * converted to RGB using a quick & dirty algorithm that is suitable only for + * testing purposes. (Proper conversion between CMYK and other formats + * requires a color management system.) * * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP * "flags". @@ -1698,8 +1710,8 @@ DLLEXPORT int tjSaveImage(const char *filename, unsigned char *buffer, /** - * Free an image buffer previously allocated by TurboJPEG. You should always - * use this function to free JPEG destination buffer(s) that were automatically + * Free a byte buffer previously allocated by TurboJPEG. You should always use + * this function to free JPEG destination buffer(s) that were automatically * (re)allocated by the compression and transform functions or that were * manually allocated using #tjAlloc(). * @@ -1737,14 +1749,10 @@ DLLEXPORT char *tjGetErrorStr2(tjhandle handle); DLLEXPORT int tjGetErrorCode(tjhandle handle); -/* Deprecated functions and macros */ -#define TJFLAG_FORCEMMX 8 -#define TJFLAG_FORCESSE 16 -#define TJFLAG_FORCESSE2 32 -#define TJFLAG_FORCESSE3 128 - - /* Backward compatibility functions and macros (nothing to see here) */ + +/* TurboJPEG 1.0+ */ + #define NUMSUBOPT TJ_NUMSAMP #define TJ_444 TJSAMP_444 #define TJ_422 TJSAMP_422 @@ -1760,53 +1768,64 @@ DLLEXPORT int tjGetErrorCode(tjhandle handle); #define TJ_ALPHAFIRST 64 #define TJ_FORCESSE3 TJFLAG_FORCESSE3 #define TJ_FASTUPSAMPLE TJFLAG_FASTUPSAMPLE -#define TJ_YUV 512 DLLEXPORT unsigned long TJBUFSIZE(int width, int height); -DLLEXPORT unsigned long TJBUFSIZEYUV(int width, int height, int jpegSubsamp); - -DLLEXPORT unsigned long tjBufSizeYUV(int width, int height, int subsamp); - DLLEXPORT int 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); -DLLEXPORT int tjEncodeYUV(tjhandle handle, unsigned char *srcBuf, int width, - int pitch, int height, int pixelSize, - unsigned char *dstBuf, int subsamp, int flags); - -DLLEXPORT int tjEncodeYUV2(tjhandle handle, unsigned char *srcBuf, int width, - int pitch, int height, int pixelFormat, - unsigned char *dstBuf, int subsamp, int flags); +DLLEXPORT int tjDecompress(tjhandle handle, unsigned char *jpegBuf, + unsigned long jpegSize, unsigned char *dstBuf, + int width, int pitch, int height, int pixelSize, + int flags); DLLEXPORT int tjDecompressHeader(tjhandle handle, unsigned char *jpegBuf, unsigned long jpegSize, int *width, int *height); +DLLEXPORT char *tjGetErrorStr(void); + +/* TurboJPEG 1.1+ */ + +#define TJ_YUV 512 + +DLLEXPORT unsigned long TJBUFSIZEYUV(int width, int height, int jpegSubsamp); + DLLEXPORT int tjDecompressHeader2(tjhandle handle, unsigned char *jpegBuf, unsigned long jpegSize, int *width, int *height, int *jpegSubsamp); +DLLEXPORT int tjDecompressToYUV(tjhandle handle, unsigned char *jpegBuf, + unsigned long jpegSize, unsigned char *dstBuf, + int flags); + +DLLEXPORT int tjEncodeYUV(tjhandle handle, unsigned char *srcBuf, int width, + int pitch, int height, int pixelSize, + unsigned char *dstBuf, int subsamp, int flags); + +/* TurboJPEG 1.2+ */ + +#define TJFLAG_FORCEMMX 8 +#define TJFLAG_FORCESSE 16 +#define TJFLAG_FORCESSE2 32 +#define TJFLAG_FORCESSE3 128 + +DLLEXPORT unsigned long tjBufSizeYUV(int width, int height, int subsamp); + +DLLEXPORT int tjEncodeYUV2(tjhandle handle, unsigned char *srcBuf, int width, + int pitch, int height, int pixelFormat, + unsigned char *dstBuf, int subsamp, int flags); + +/* TurboJPEG 1.4+ */ + DLLEXPORT int tjDecompressHeader3(tjhandle handle, const unsigned char *jpegBuf, unsigned long jpegSize, int *width, int *height, int *jpegSubsamp, int *jpegColorspace); -DLLEXPORT int tjDecompress(tjhandle handle, unsigned char *jpegBuf, - unsigned long jpegSize, unsigned char *dstBuf, - int width, int pitch, int height, int pixelSize, - int flags); - -DLLEXPORT int tjDecompressToYUV(tjhandle handle, unsigned char *jpegBuf, - unsigned long jpegSize, unsigned char *dstBuf, - int flags); - -DLLEXPORT char *tjGetErrorStr(void); - - /** * @} */