ryan/mozjpeg
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

TurboJPEG 3 API overhaul

Browse Source 
(ChangeLog update forthcoming)

- Prefix all function names with "tj3" and remove version suffixes from
  function names.  (Future API overhauls will increment the prefix to
  "tj4", etc., thus retaining backward API/ABI compatibility without
  versioning each individual function.)

- Replace stateless boolean flags (including TJ*FLAG_ARITHMETIC and
  TJ*FLAG_LOSSLESS, which were never released) with stateful integer
  parameters, the value of which persists between function calls.
  * Use parameters for the JPEG quality and subsampling as well, in
    order to eliminate the awkwardness of specifying function arguments
    that weren't relevant for lossless compression.
  * tj3DecompressHeader() now stores all relevant information about the
    JPEG image, including the width, height, subsampling type, entropy
    coding type, etc. in parameters rather than returning that
    information in its arguments.
  * TJ*FLAG_LIMITSCANS has been reimplemented as an integer parameter
    (TJ*PARAM_SCANLIMIT) that allows the number of scans to be
    specified.

- Use the const keyword for all pointer arguments to unmodified
  buffers, as well as for both dimensions of 2D pointers.  Addresses
  #395.

- Use size_t rather than unsigned long to represent buffer sizes, since
  unsigned long is a 32-bit type on Windows.  Addresses #24.

- Return 0 from all buffer size functions if an error occurs, rather
  than awkwardly trying to return -1 in an unsigned data type.

- Implement 12-bit and 16-bit data precision using dedicated
  compression, decompression, and image I/O functions/methods.
  * Suffix the names of all data-precision-specific functions with 8,
    12, or 16.
  * Because the YUV functions are intended to be used for video, they
    are currently only implemented with 8-bit data precision, but they
    can be expanded to 12-bit data precision in the future, if
    necessary.
  * Extend TJUnitTest and TJBench to test 12-bit and 16-bit data
    precision, using a new -precision option.
  * Add appropriate regression tests for all of the above to the 'test'
    target.
  * Extend tjbenchtest to test 12-bit and 16-bit data precision, and
    add separate 'tjtest12' and 'tjtest16' targets.
  * BufferedImage I/O in the Java API is currently limited to 8-bit
    data precision, since the BufferedImage class does not
    straightforwardly support higher data precisions.
  * Extend the PPM reader to convert 12-bit and 16-bit PBMPLUS files
    to grayscale or CMYK pixels, as it already does for 8-bit files.

- Properly accommodate lossless JPEG using dedicated parameters
  (TJ*PARAM_LOSSLESS, TJ*PARAM_LOSSLESSPSV, and TJ*PARAM_LOSSLESSPT),
  rather than using a flag and awkwardly repurposing the JPEG quality.
  Update TJBench to properly reflect whether a JPEG image is lossless.

- Re-organize the TJBench usage screen.

- Update the Java docs using Java 11, to improve the formatting and
  eliminate HTML frames.

- Use the accurate integer DCT algorithm by default for both
  compression and decompression, since the "fast" algorithm is a legacy
  feature, it does not pass the ISO compliance tests, and it is not
  actually faster on modern x86 CPUs.
  * Remove the -accuratedct option from TJBench and TJExample.

- Re-implement the 'tjtest' target using a CMake script that enables
  the appropriate tests, depending on the data precision and whether or
  not the Java API is part of the build.

- Consolidate the C and Java versions of tjbenchtest into one script.

- Consolidate the C and Java versions of tjexampletest into one script.

- Combine all initialization functions into a single function
  (tj3Init()) that accepts an integer parameter specifying the
  subsystems to initialize.

- Enable decompression scaling explicitly, using a new function/method
  (tj3SetScalingFactor()/TJDecompressor.setScalingFactor()), rather
  than implicitly using awkward "desired width"/"desired height"
  parameters.

- Introduce a new macro/constant (TJUNSCALED/TJ.UNSCALED) that maps to
  a scaling factor of 1/1.

- Implement partial image decompression, using a new function/method
  (tj3SetCroppingRegion()/TJDecompressor.setCroppingRegion()) and
  TJBench option (-crop).  Extend tjbenchtest to test the new feature.
  Addresses #1.

- Allow the JPEG colorspace to be specified explicitly when
  compressing, using a new parameter (TJ*PARAM_COLORSPACE).  This
  allows JPEG images with the RGB and CMYK colorspaces to be created.

- Remove the error/difference image feature from TJBench.  Identical
  images to the ones that TJBench created can be generated using
  ImageMagick with
  'magick composite <original_image> <output_image> -compose difference <diff_image>'

- Handle JPEG images with unknown subsampling types.  TJ*PARAM_SUBSAMP
  is set to TJ*SAMP_UNKNOWN (== -1) for such images, but they can still
  be decompressed fully into packed-pixel images or losslessly
  transformed (with the exception of lossless cropping.)  They cannot
  be partially decompressed or decompressed into planar YUV images.
  Note also that TJBench, due to its lack of support for imperfect
  transforms, requires that the subsampling type be known when
  rotating, flipping, or transversely transposing an image.  Addresses
  #436

- The Java version of TJBench now has identical functionality to the C
  version.  This was accomplished by (somewhat hackishly) calling the
  TurboJPEG C image I/O functions through JNI and copying the pixels
  between the C heap and the Java heap.

- Add parameters (TJ*PARAM_RESTARTROWS and TJ*PARAM_RESTARTBLOCKS) and
  a TJBench option (-restart) to allow the restart marker interval to
  be specified when compressing.  Eliminate the undocumented TJ_RESTART
  environment variable.

- Add a parameter (TJ*PARAM_OPTIMIZE), a transform option
  (TJ*OPT_OPTIMIZE), and a TJBench option (-optimize) to allow
  optimized baseline Huffman coding to be specified when compressing.
  Eliminate the undocumented TJ_OPTIMIZE environment variable.

- Add parameters (TJ*PARAM_XDENSITY, TJ*PARAM_DENSITY, and
  TJ*DENSITYUNITS) to allow the pixel density to be specified when
  compressing or saving a Windows BMP image and to be queried when
  decompressing or loading a Windows BMP image.  Addresses #77.

- Refactor the fuzz targets to use the new API.
  * Extend decompression coverage to 12-bit and 16-bit data precision.
  * Replace the awkward cjpeg12 and cjpeg16 targets with proper
    TurboJPEG-based compress12, compress12-lossless, and
    compress16-lossless targets

- Fix innocuous UBSan warnings uncovered by the new fuzzers.

- Implement previous versions of the TurboJPEG API by wrapping the new
  functions (tested by running the 2.1.x versions of TJBench, via
  tjbenchtest, and TJUnitTest against the new implementation.)
  * Remove all JNI functions for deprecated Java methods and implement
    the deprecated methods using pure Java wrappers.  It should be
    understood that backward API compatibility in Java applies only to
    the Java classes and that one cannot mix and match a JAR file from
    one version of libjpeg-turbo with a JNI library from another
    version.

- tj3Destroy() now silently accepts a NULL handle.

- tj3Alloc() and tj3Free() now return/accept void pointers, as malloc()
  and free() do.

- The image I/O functions now accept a TurboJPEG instance handle, which
  is used to transmit/receive parameters and to receive error
  information.

Closes #517
This commit is contained in:
DRC
2023-01-05 06:36:46 -06:00
parent 1a1ea4eeba
commit fc01f4673b
132 changed files with 41404 additions and 10163 deletions
Download Patch File Download Diff File Expand all files Collapse all files

610
java/org/libjpegturbo/turbojpeg/TJ.java
View File

@@ -30,6 +30,8 @@
package org.libjpegturbo.turbojpeg;
import java.awt.Rectangle;
/**
* TurboJPEG utility class (cannot be instantiated)
*/
@@ -78,7 +80,18 @@ public final class TJ {
* in libjpeg-turbo.
*/
public static final int SAMP_411 = 5;
/**
* Unknown subsampling. The JPEG image uses an unusual type of chrominance
* subsampling. Such images can be decompressed into packed-pixel images,
* but they cannot be
* <ul>
* <li> decompressed into planar YUV images,
* <li> losslessly transformed if {@link TJTransform#OPT_CROP} is specified,
* or
* <li> partially decompressed using a cropping region.
* </ul>
*/
public static final int SAMP_UNKNOWN = -1;
/**
* Returns the MCU block width for the given level of chrominance
@@ -126,71 +139,72 @@ public final class TJ {
public static final int NUMPF = 12;
/**
* RGB pixel format. The red, green, and blue components in the image are
* stored in 3-byte pixels in the order R, G, B from lowest to highest byte
* address within each pixel.
* stored in 3-sample pixels in the order R, G, B from lowest to highest
* memory address within each pixel.
*/
public static final int PF_RGB = 0;
/**
* BGR pixel format. The red, green, and blue components in the image are
* stored in 3-byte pixels in the order B, G, R from lowest to highest byte
* address within each pixel.
* stored in 3-sample pixels in the order B, G, R from lowest to highest
* memory address within each pixel.
*/
public static final int PF_BGR = 1;
/**
* RGBX pixel format. The red, green, and blue components in the image are
* stored in 4-byte pixels in the order R, G, B from lowest to highest byte
* address within each pixel. The X component is ignored when compressing
* and undefined when decompressing.
* stored in 4-sample pixels in the order R, G, B from lowest to highest
* memory address within each pixel. The X component is ignored when
* compressing and undefined when decompressing.
*/
public static final int PF_RGBX = 2;
/**
* BGRX pixel format. The red, green, and blue components in the image are
* stored in 4-byte pixels in the order B, G, R from lowest to highest byte
* address within each pixel. The X component is ignored when compressing
* and undefined when decompressing.
* stored in 4-sample pixels in the order B, G, R from lowest to highest
* memory address within each pixel. The X component is ignored when
* compressing and undefined when decompressing.
*/
public static final int PF_BGRX = 3;
/**
* XBGR pixel format. The red, green, and blue components in the image are
* stored in 4-byte pixels in the order R, G, B from highest to lowest byte
* address within each pixel. The X component is ignored when compressing
* and undefined when decompressing.
* stored in 4-sample pixels in the order R, G, B from highest to lowest
* memory address within each pixel. The X component is ignored when
* compressing and undefined when decompressing.
*/
public static final int PF_XBGR = 4;
/**
* XRGB pixel format. The red, green, and blue components in the image are
* stored in 4-byte pixels in the order B, G, R from highest to lowest byte
* address within each pixel. The X component is ignored when compressing
* and undefined when decompressing.
* stored in 4-sample pixels in the order B, G, R from highest to lowest
* memory address within each pixel. The X component is ignored when
* compressing and undefined when decompressing.
*/
public static final int PF_XRGB = 5;
/**
* Grayscale pixel format. Each 1-byte pixel represents a luminance
* (brightness) level from 0 to 255.
* Grayscale pixel format. Each 1-sample pixel represents a luminance
* (brightness) level from 0 to the maximum sample value (255 for 8-bit
* samples, 4095 for 12-bit samples, and 65535 for 16-bit samples.)
*/
public static final int PF_GRAY = 6;
/**
* RGBA pixel format. This is the same as {@link #PF_RGBX}, except that when
* decompressing, the X byte is guaranteed to be 0xFF, which can be
* interpreted as an opaque alpha channel.
* decompressing, the X component is guaranteed to be equal to the maximum
* sample value, which can be interpreted as an opaque alpha channel.
*/
public static final int PF_RGBA = 7;
/**
* BGRA pixel format. This is the same as {@link #PF_BGRX}, except that when
* decompressing, the X byte is guaranteed to be 0xFF, which can be
* interpreted as an opaque alpha channel.
* decompressing, the X component is guaranteed to be equal to the maximum
* sample value, which can be interpreted as an opaque alpha channel.
*/
public static final int PF_BGRA = 8;
/**
* ABGR pixel format. This is the same as {@link #PF_XBGR}, except that when
* decompressing, the X byte is guaranteed to be 0xFF, which can be
* interpreted as an opaque alpha channel.
* decompressing, the X component is guaranteed to be equal to the maximum
* sample value, which can be interpreted as an opaque alpha channel.
*/
public static final int PF_ABGR = 9;
/**
* ARGB pixel format. This is the same as {@link #PF_XRGB}, except that when
* decompressing, the X byte is guaranteed to be 0xFF, which can be
* interpreted as an opaque alpha channel.
* decompressing, the X component is guaranteed to be equal to the maximum
* sample value, which can be interpreted as an opaque alpha channel.
*/
public static final int PF_ARGB = 10;
/**
@@ -212,11 +226,11 @@ public final class TJ {
/**
* Returns the pixel size (in bytes) for the given pixel format.
* Returns the pixel size (in samples) for the given pixel format.
*
* @param pixelFormat the pixel format (one of {@link #PF_RGB PF_*})
*
* @return the pixel size (in bytes) for the given pixel format.
* @return the pixel size (in samples) for the given pixel format.
*/
public static int getPixelSize(int pixelFormat) {
checkPixelFormat(pixelFormat);
@@ -229,10 +243,10 @@ public final class TJ {
/**
* For the given pixel format, returns the number of bytes that the red
* component is offset from the start of the pixel. For instance, if a pixel
* of format <code>TJ.PF_BGRX</code> is stored in <code>char pixel[]</code>,
* then the red component will be
* For the given pixel format, returns the number of samples that the red
* component is offset from the start of the pixel. For instance, if an
* 8-bit-per-sample pixel of format <code>TJ.PF_BGRX</code> is stored in
* <code>char pixel[]</code>, then the red component will be
* <code>pixel[TJ.getRedOffset(TJ.PF_BGRX)]</code>.
*
* @param pixelFormat the pixel format (one of {@link #PF_RGB PF_*})
@@ -251,10 +265,10 @@ public final class TJ {
/**
* For the given pixel format, returns the number of bytes that the green
* component is offset from the start of the pixel. For instance, if a pixel
* of format <code>TJ.PF_BGRX</code> is stored in <code>char pixel[]</code>,
* then the green component will be
* For the given pixel format, returns the number of samples that the green
* component is offset from the start of the pixel. For instance, if an
* 8-bit-per-sample pixel of format <code>TJ.PF_BGRX</code> is stored in
* <code>char pixel[]</code>, then the green component will be
* <code>pixel[TJ.getGreenOffset(TJ.PF_BGRX)]</code>.
*
* @param pixelFormat the pixel format (one of {@link #PF_RGB PF_*})
@@ -273,10 +287,10 @@ public final class TJ {
/**
* For the given pixel format, returns the number of bytes that the blue
* component is offset from the start of the pixel. For instance, if a pixel
* of format <code>TJ.PF_BGRX</code> is stored in <code>char pixel[]</code>,
* then the blue component will be
* For the given pixel format, returns the number of samples that the blue
* component is offset from the start of the pixel. For instance, if an
* 8-bit-per-sample pixel of format <code>TJ.PF_BGRX</code> is stored in
* <code>char pixel[]</code>, then the blue component will be
* <code>pixel[TJ.getBlueOffset(TJ.PF_BGRX)]</code>.
*
* @param pixelFormat the pixel format (one of {@link #PF_RGB PF_*})
@@ -295,10 +309,10 @@ public final class TJ {
/**
* For the given pixel format, returns the number of bytes that the alpha
* component is offset from the start of the pixel. For instance, if a pixel
* of format <code>TJ.PF_BGRA</code> is stored in <code>char pixel[]</code>,
* then the alpha component will be
* For the given pixel format, returns the number of samples that the alpha
* component is offset from the start of the pixel. For instance, if an
* 8-bit-per-sample pixel of format <code>TJ.PF_BGRA</code> is stored in
* <code>char pixel[]</code>, then the alpha component will be
* <code>pixel[TJ.getAlphaOffset(TJ.PF_BGRA)]</code>.
*
* @param pixelFormat the pixel format (one of {@link #PF_RGB PF_*})
@@ -324,9 +338,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 packed-pixel images with any of the extended RGB or
* grayscale pixel formats, but they cannot be decompressed to planar YUV
* images.
* compressed from and decompressed to packed-pixel images with any of the
* extended RGB or grayscale pixel formats, but they cannot be compressed
* from or decompressed to planar YUV images.
*/
public static final int CS_RGB = 0;
/**
@@ -361,7 +375,8 @@ public final class TJ {
* 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 packed-pixel images with the CMYK pixel format.
* only be compressed from and decompressed to packed-pixel images with the
* CMYK pixel format.
*/
public static final int CS_CMYK = 3;
/**
@@ -377,92 +392,414 @@ public final class TJ {
/**
* 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.
* 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. 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_ACCURATEDCT = (1 << 12);
/**
* 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.
* <p>
* 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 destination image in
* a fully recoverable state after a non-fatal error occurs.
*/
public static final int FLAG_STOPONWARNING = (1 << 13);
/**
* Use progressive entropy coding in JPEG images generated by compression and
* transform operations. 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 {@link #FLAG_ARITHMETIC}.
*/
public static final int FLAG_PROGRESSIVE = (1 << 14);
/**
* Limit the number of progressive JPEG scans that the decompression and
* transform operations will process. If a progressive JPEG image contains
* an unreasonably large number of scans, then this flag will cause the
* decompression and transform operations to throw an error. The primary
* purpose of this is to allow security-critical applications to guard
* against an exploit of the progressive JPEG format described in
* <a href="https://libjpeg-turbo.org/pmwiki/uploads/About/TwoIssueswiththeJPEGStandard.pdf" target="_blank">this report</a>.
*/
public static final int FLAG_LIMITSCANS = (1 << 15);
/**
* Use arithmetic entropy coding in JPEG images generated by compression and
* transform operations. 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 {@link #FLAG_PROGRESSIVE}.
*/
public static final int FLAG_ARITHMETIC = (1 << 16);
/**
* Generate a lossless JPEG image when compressing. In most cases,
* compressing and decompressing lossless JPEG images is considerably slower
* than compressing and decompressing lossy JPEG images. Also note that the
* following features are not available with lossless JPEG images:
* Error handling behavior
*
* <p><b>Value</b>
* <ul>
* <li> Colorspace conversion
* <li> Chrominance subsampling
* <li> <code>0</code> <i>[default]</i> Allow the current
* compression/decompression/transform operation to complete unless a fatal
* error is encountered.
* <li> <code>1</code> Immediately discontinue the current
* compression/decompression/transform operation if a warning (non-fatal
* error) occurs.
* </ul>
*/
public static final int PARAM_STOPONWARNING = 0;
/**
* Row order in packed-pixel source/destination images
*
* <p><b>Value</b>
* <ul>
* <li> <code>0</code> <i>[default]</i> top-down (X11) order
* <li> <code>1</code> bottom-up (Windows, OpenGL) order
* </ul>
*/
public static final int PARAM_BOTTOMUP = 1;
/**
* Perceptual quality of lossy JPEG images [compression only]
*
* <p><b>Value</b>
* <ul>
* <li> <code>1</code>-<code>100</code> (<code>1</code> = worst quality but
* best compression, <code>100</code> = best quality but worst compression)
* <i>[no default; must be explicitly specified]</i>
* </ul>
*/
public static final int PARAM_QUALITY = 3;
/**
* Chrominance subsampling level
*
* <p>The JPEG or YUV image uses (decompression, decoding) or will use (lossy
* compression, encoding) the specified level of chrominance subsampling.
*
* <p>When pixels are converted from RGB to YCbCr (see {@link #CS_YCbCr}) or
* from CMYK to YCCK (see {@link #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".
*
* <p><b>Value</b>
* <ul>
* <li> One of {@link TJ#SAMP_444 TJ.SAMP_*} <i>[no default; must be
* explicitly specified for lossy compression, encoding, and decoding]</i>
* </ul>
*/
public static final int PARAM_SUBSAMP = 4;
/**
* JPEG width (in pixels) [decompression only, read-only]
*/
public static final int PARAM_JPEGWIDTH = 5;
/**
* JPEG height (in pixels) [decompression only, read-only]
*/
public static final int PARAM_JPEGHEIGHT = 6;
/**
* JPEG data precision (bits per sample) [decompression only, read-only]
*
* <p>The JPEG image uses the specified number of bits per sample.
*
* <p><b>Value</b>
* <ul>
* <li> <code>8</code>, <code>12</code>, or <code>16</code>
* </ul>
*
* <p>12-bit data precision implies {@link #PARAM_OPTIMIZE}.
*/
public static final int PARAM_PRECISION = 7;
/**
* JPEG colorspace
*
* <p>The JPEG image uses (decompression) or will use (lossy compression) the
* specified colorspace.
*
* <p><b>Value</b>
* <ul>
* <li> One of {@link TJ#CS_RGB TJ.CS_*} <i>[default for lossy compression:
* automatically selected based on the subsampling level and pixel
* format]</i>
* </ul>
*/
public static final int PARAM_COLORSPACE = 8;
/**
* Chrominance upsampling algorithm [lossy decompression only]
*
* <p><b>Value</b>
* <ul>
* <li> <code>0</code> <i>[default]</i> Use smooth upsampling when
* decompressing a JPEG image that was compressed using chrominance
* subsampling. This creates a smooth transition between neighboring
* chrominance components in order to reduce upsampling artifacts in the
* decompressed image.
* <li> <code>1</code> Use the fastest chrominance upsampling algorithm
* available, which may combine upsampling with color conversion.
* </ul>
*/
public static final int PARAM_FASTUPSAMPLE = 9;
/**
* DCT/IDCT algorithm [lossy compression and decompression]
*
* <p><b>Value</b>
* <ul>
* <li> <code>0</code> <i>[default]</i> Use the most accurate DCT/IDCT
* algorithm available.
* <li> <code>1</code> Use the fastest DCT/IDCT algorithm available.
* </ul>
*
* <p>This parameter is provided mainly for backward compatibility with
* libjpeg, which historically implemented several different DCT/IDCT
* algorithms because of performance limitations with 1990s CPUs. In the
* libjpeg-turbo implementation of the TurboJPEG API:
*
* <ul>
* <li> The "fast" and "accurate" DCT/IDCT algorithms perform similarly on
* modern x86/x86-64 CPUs that support AVX2 instructions.
* <li> The "fast" algorithm is generally only about 5-15% faster than the
* "accurate" algorithm on other types of CPUs.
* <li> The difference in accuracy between the "fast" and "accurate"
* algorithms is the most pronounced at JPEG quality levels above 90 and
* tends to be more pronounced with decompression than with compression.
* <li> The "fast" algorithm degrades and is not fully accelerated for JPEG
* quality levels above 97, so it will be slower than the "accurate"
* algorithm.
* </ul>
*/
public static final int PARAM_FASTDCT = 10;
/**
* Optimized baseline entropy coding [lossy compression only]
*
* <p><b>Value</b>
* <ul>
* <li> <code>0</code> <i>[default]</i> The JPEG image will use the default
* Huffman tables.
* <li> <code>1</code> Optimal Huffman tables will be computed for the JPEG
* image. For lossless transformation, this can also be specified using
* {@link TJTransform#OPT_OPTIMIZE}.
* </ul>
*
* <p>Optimized baseline entropy coding will improve compression slightly
* (generally 5% or less), but it will reduce compression performance
* considerably.
*/
public static final int PARAM_OPTIMIZE = 11;
/**
* Progressive entropy coding
*
* <p><b>Value</b>
* <ul>
* <li> <code>0</code> <i>[default for compression, lossless
* transformation]</i> The lossy JPEG image uses (decompression) or will use
* (compression, lossless transformation) baseline entropy coding.
* <li> <code>1</code> The lossy JPEG image uses (decompression) or will use
* (compression, lossless transformation) progressive entropy coding. For
* lossless transformation, this can also be specified using
* {@link TJTransform#OPT_PROGRESSIVE}.
* </ul>
*
* <p>Progressive entropy coding will generally improve compression relative
* to baseline entropy coding, but it will reduce compression and
* decompression performance considerably. Implies {@link #PARAM_OPTIMIZE}.
* Can be combined with {@link #PARAM_ARITHMETIC}.
*/
public static final int PARAM_PROGRESSIVE = 12;
/**
* Progressive JPEG scan limit for lossy JPEG images [decompression, lossless
* transformation]
*
* <p>Setting this parameter will cause the decompression and transform
* functions to return an error if the number of scans in a progressive JPEG
* image exceeds the specified limit. The primary purpose of this is to
* allow security-critical applications to guard against an exploit of the
* progressive JPEG format described in
* <a href="https://libjpeg-turbo.org/pmwiki/uploads/About/TwoIssueswiththeJPEGStandard.pdf" target="_blank">this report</a>.
*
* <p><b>Value</b>
* <ul>
* <li> maximum number of progressive JPEG scans that the decompression and
* transform functions will process <i>[default: <code>0</code> (no
* limit)]</i>
* </ul>
*
* @see #PARAM_PROGRESSIVE
*/
public static final int PARAM_SCANLIMIT = 13;
/**
* Arithmetic entropy coding
*
* <p><b>Value</b>
* <ul>
* <li> <code>0</code> <i>[default for compression, lossless
* transformation]</i> The lossy JPEG image uses (decompression) or will use
* (compression, lossless transformation) Huffman entropy coding.
* <li> <code>1</code> The lossy JPEG image uses (decompression) or will use
* (compression, lossless transformation) arithmetic entropy coding. For
* lossless transformation, this can also be specified using
* {@link TJTransform#OPT_ARITHMETIC}.
* </ul>
*
* <p>Arithmetic entropy coding will generally improve compression relative
* to Huffman entropy coding, but it will reduce compression and
* decompression performance considerably. Can be combined with
* {@link #PARAM_PROGRESSIVE}. Arithmetic entropy coding is currently only
* implemented for 8-bit samples.
*/
public static final int PARAM_ARITHMETIC = 14;
/**
* Lossless JPEG
*
* <p><b>Value</b>
* <ul>
* <li> <code>0</code> <i>[default for compression]</i> The JPEG image is
* (decompression) or will be (compression) lossy/DCT-based.
* <li> <code>1</code> The JPEG image is (decompression) or will be
* (compression) lossless/predictive.
* </ul>
*
* <p>In most cases, compressing and decompressing lossless JPEG images is
* considerably slower than compressing and decompressing lossy JPEG images.
* Also note that the following features are not available with lossless JPEG
* images:
* <ul>
* <li> Colorspace conversion (lossless JPEG images always use
* {@link #CS_RGB}, {@link #CS_GRAY}, or {@link #CS_CMYK}, depending on the
* pixel format of the source image)
* <li> Chrominance subsampling (lossless JPEG images always use
* {@link #SAMP_444})
* <li> JPEG quality selection
* <li> DCT/IDCT algorithm selection
* <li> Progressive entropy coding
* <li> Arithmetic entropy coding
* <li> Compression from/decompression to planar YUV images
* <li> Decompression scaling
* <li> Lossless transformations
* <li> Lossless transformation
* </ul>
*
* @see #PARAM_LOSSLESSPSV
* @see #PARAM_LOSSLESSPT
*/
public static final int FLAG_LOSSLESS = (1 << 17);
public static final int PARAM_LOSSLESS = 15;
/**
* Lossless JPEG predictor selection value (PSV)
*
* <p><b>Value</b>
* <ul>
* <li> <code>1</code>-<code>7</code> <i>[default for compression:
* <code>1</code>]</i>
* </ul>
*
* @see #PARAM_LOSSLESS
*/
public static final int PARAM_LOSSLESSPSV = 16;
/**
* Lossless JPEG point transform (Pt)
*
* <p><b>Value</b>
* <ul>
* <li> <code>0</code> through <i><b>precision</b> - 1</i>, where
* <b><i>precision</i></b> is the JPEG data precision in bits <i>[default for
* compression: <code>0</code>]</i>
* </ul>
*
* <p>A point transform value of <code>0</code> is necessary in order to
* generate 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.)
*
* @see #PARAM_LOSSLESS
* @see #PARAM_PRECISION
*/
public static final int PARAM_LOSSLESSPT = 17;
/**
* JPEG restart marker interval in MCU blocks (lossy) or samples (lossless)
* [compression only]
*
* <p>The nature of entropy coding is such that a corrupt JPEG image cannot
* be decompressed beyond the point of corruption unless it contains restart
* markers. A restart marker stops and restarts the entropy coding algorithm
* so that, if a JPEG image is corrupted, decompression can resume at the
* next marker. Thus, adding more restart markers improves the fault
* tolerance of the JPEG image, but adding too many restart markers can
* adversely affect the compression ratio and performance.
*
* <p><b>Value</b>
* <ul>
* <li> the number of MCU blocks or samples between each restart marker
* <i>[default: <code>0</code> (no restart markers)]</i>
* </ul>
*
* <p> Setting this parameter to a non-zero value sets
* {@link #PARAM_RESTARTROWS} to 0.
*/
public static final int PARAM_RESTARTBLOCKS = 18;
/**
* JPEG restart marker interval in MCU rows (lossy) or sample rows (lossless)
* [compression only]
*
* <p>See {@link #PARAM_RESTARTBLOCKS} for a description of restart markers.
*
* <p><b>Value</b>
* <ul>
* <li> the number of MCU rows or sample rows between each restart marker
* <i>[default: <code>0</code> (no restart markers)]</i>
* </ul>
*
* <p>Setting this parameter to a non-zero value sets
* {@link #PARAM_RESTARTBLOCKS} to 0.
*/
public static final int PARAM_RESTARTROWS = 19;
/**
* JPEG horizontal pixel density
*
* <p><b>Value</b>
* <ul>
* <li> The JPEG image has (decompression) or will have (compression) the
* specified horizontal pixel density <i>[default for compression:
* <code>1</code>]</i>.
* </ul>
*
* <p>This value is stored in or read from the JPEG header. It does not
* affect the contents of the JPEG image.
*
* @see #PARAM_DENSITYUNITS
*/
public static final int PARAM_XDENSITY = 20;
/**
* JPEG vertical pixel density
*
* <p><b>Value</b>
* <ul>
* <li> The JPEG image has (decompression) or will have (compression) the
* specified vertical pixel density <i>[default for compression:
* <code>1</code>]</i>.
* </ul>
*
* <p>This value is stored in or read from the JPEG header. It does not
* affect the contents of the JPEG image.
*
* @see #PARAM_DENSITYUNITS
*/
public static final int PARAM_YDENSITY = 21;
/**
* JPEG pixel density units
*
* <p><b>Value</b>
* <ul>
* <li> <code>0</code> <i>[default for compression]</i> The pixel density of
* the JPEG image is expressed (decompression) or will be expressed
* (compression) in unknown units.
* <li> <code>1</code> The pixel density of the JPEG image is expressed
* (decompression) or will be expressed (compression) in units of
* pixels/inch.
* <li> <code>2</code> The pixel density of the JPEG image is expressed
* (decompression) or will be expressed (compression) in units of pixels/cm.
* </ul>
*
* <p>This value is stored in or read from the JPEG header. It does not
* affect the contents of the JPEG image.
*
* @see #PARAM_XDENSITY
* @see #PARAM_YDENSITY
*/
public static final int PARAM_DENSITYUNITS = 22;
/**
* @deprecated Use {@link #PARAM_BOTTOMUP} instead.
*/
@Deprecated
public static final int FLAG_BOTTOMUP = 2;
/**
* @deprecated Use {@link #PARAM_FASTUPSAMPLE} instead.
*/
@Deprecated
public static final int FLAG_FASTUPSAMPLE = 256;
/**
* @deprecated Use {@link #PARAM_FASTDCT} instead.
*/
@Deprecated
public static final int FLAG_FASTDCT = 2048;
/**
* @deprecated Use {@link #PARAM_FASTDCT} instead.
*/
@Deprecated
public static final int FLAG_ACCURATEDCT = 4096;
/**
* @deprecated Use {@link #PARAM_STOPONWARNING} instead.
*/
@Deprecated
public static final int FLAG_STOPONWARNING = 8192;
/**
* @deprecated Use {@link #PARAM_PROGRESSIVE} instead.
*/
@Deprecated
public static final int FLAG_PROGRESSIVE = 16384;
/**
* @deprecated Use {@link #PARAM_SCANLIMIT} instead.
*/
@Deprecated
public static final int FLAG_LIMITSCANS = 32768;
/**
* The number of error codes
@@ -493,7 +830,11 @@ 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 #SAMP_444 TJ.SAMP_*})
* generating the JPEG image (one of {@link #SAMP_444 TJ.SAMP_*}.)
* {@link #SAMP_UNKNOWN} is treated like {@link #SAMP_444}, since a buffer
* large enough to hold a JPEG image with no subsampling should also be large
* enough to hold a JPEG image with an arbitrary level of subsampling. Note
* that lossless JPEG images always use {@link #SAMP_444}.
*
* @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.
@@ -550,7 +891,7 @@ public final class TJ {
/**
* Returns the plane width of a YUV image plane with the given parameters.
* Refer to {@link YUVImage YUVImage} for a description of plane width.
* Refer to {@link YUVImage} for a description of plane width.
*
* @param componentID ID number of the image plane (0 = Y, 1 = U/Cb,
* 2 = V/Cr)
@@ -566,7 +907,7 @@ public final class TJ {
/**
* Returns the plane height of a YUV image plane with the given parameters.
* Refer to {@link YUVImage YUVImage} for a description of plane height.
* Refer to {@link YUVImage} for a description of plane height.
*
* @param componentID ID number of the image plane (0 = Y, 1 = U/Cb,
* 2 = V/Cr)
@@ -590,6 +931,17 @@ public final class TJ {
*/
public static native TJScalingFactor[] getScalingFactors();
/**
* A {@link TJScalingFactor} instance that specifies a scaling factor of 1/1
* (no scaling)
*/
public static final TJScalingFactor UNSCALED = new TJScalingFactor(1, 1);
/**
* A <code>java.awt.Rectangle</code> instance that specifies no cropping
*/
public static final Rectangle UNCROPPED = new Rectangle(0, 0, 0, 0);
static {
TJLoader.load();
}