java/org/libjpegturbo/turbojpeg/TJ.java

   1 /*
   2  * Copyright (C)2011-2013, 2017-2018, 2020-2023 D. R. Commander.
   3  *                                              All Rights Reserved.
   4  * Copyright (C)2015 Viktor Szathmáry.  All Rights Reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions are met:
   8  *
   9  * - Redistributions of source code must retain the above copyright notice,
  10  *   this list of conditions and the following disclaimer.
  11  * - Redistributions in binary form must reproduce the above copyright notice,
  12  *   this list of conditions and the following disclaimer in the documentation
  13  *   and/or other materials provided with the distribution.
  14  * - Neither the name of the libjpeg-turbo Project nor the names of its
  15  *   contributors may be used to endorse or promote products derived from this
  16  *   software without specific prior written permission.
  17  *
  18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS",
  19  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21  * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
  22  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28  * POSSIBILITY OF SUCH DAMAGE.
  29  */
  30
  31 package org.libjpegturbo.turbojpeg;
  32
  33 import java.awt.Rectangle;
  34
  35 /**
  36  * TurboJPEG utility class (cannot be instantiated)
  37  */
  38 public final class TJ {
  39
  40   private TJ() {}
  41
  42   /**
  43    * The number of chrominance subsampling options
  44    */
  45   public static final int NUMSAMP   = 7;
  46   /**
  47    * 4:4:4 chrominance subsampling (no chrominance subsampling).  The JPEG
  48    * or YUV image will contain one chrominance component for every pixel in the
  49    * source image.
  50    */
  51   public static final int SAMP_444  = 0;
  52   /**
  53    * 4:2:2 chrominance subsampling.  The JPEG or YUV image will contain one
  54    * chrominance component for every 2x1 block of pixels in the source image.
  55    */
  56   public static final int SAMP_422  = 1;
  57   /**
  58    * 4:2:0 chrominance subsampling.  The JPEG or YUV image will contain one
  59    * chrominance component for every 2x2 block of pixels in the source image.
  60    */
  61   public static final int SAMP_420  = 2;
  62   /**
  63    * Grayscale.  The JPEG or YUV image will contain no chrominance components.
  64    */
  65   public static final int SAMP_GRAY = 3;
  66   /**
  67    * 4:4:0 chrominance subsampling.  The JPEG or YUV image will contain one
  68    * chrominance component for every 1x2 block of pixels in the source image.
  69    * Note that 4:4:0 subsampling is not fully accelerated in libjpeg-turbo.
  70    */
  71   public static final int SAMP_440  = 4;
  72   /**
  73    * 4:1:1 chrominance subsampling.  The JPEG or YUV image will contain one
  74    * chrominance component for every 4x1 block of pixels in the source image.
  75    * JPEG images compressed with 4:1:1 subsampling will be almost exactly the
  76    * same size as those compressed with 4:2:0 subsampling, and in the
  77    * aggregate, both subsampling methods produce approximately the same
  78    * perceptual quality.  However, 4:1:1 is better able to reproduce sharp
  79    * horizontal features.  Note that 4:1:1 subsampling is not fully accelerated
  80    * in libjpeg-turbo.
  81    */
  82   public static final int SAMP_411  = 5;
  83   /**
  84    * 4:4:1 chrominance subsampling.  The JPEG or YUV image will contain one
  85    * chrominance component for every 1x4 block of pixels in the source image.
  86    * JPEG images compressed with 4:4:1 subsampling will be almost exactly the
  87    * same size as those compressed with 4:2:0 subsampling, and in the
  88    * aggregate, both subsampling methods produce approximately the same
  89    * perceptual quality.  However, 4:4:1 is better able to reproduce sharp
  90    * vertical features.  Note that 4:4:1 subsampling is not fully accelerated
  91    * in libjpeg-turbo.
  92    */
  93   public static final int SAMP_441  = 6;
  94   /**
  95    * Unknown subsampling.  The JPEG image uses an unusual type of chrominance
  96    * subsampling.  Such images can be decompressed into packed-pixel images,
  97    * but they cannot be
  98    * <ul>
  99    * <li> decompressed into planar YUV images,
 100    * <li> losslessly transformed if {@link TJTransform#OPT_CROP} is specified,
 101    * or
 102    * <li> partially decompressed using a cropping region.
 103    * </ul>
 104    */
 105   public static final int SAMP_UNKNOWN = -1;
 106
 107   /**
 108    * Returns the MCU block width for the given level of chrominance
 109    * subsampling.
 110    *
 111    * @param subsamp the level of chrominance subsampling (one of
 112    * {@link #SAMP_444 SAMP_*})
 113    *
 114    * @return the MCU block width for the given level of chrominance
 115    * subsampling.
 116    */
 117   public static int getMCUWidth(int subsamp) {
 118     checkSubsampling(subsamp);
 119     return MCU_WIDTH[subsamp];
 120   }
 121
 122   private static final int[] MCU_WIDTH = {
 123     8, 16, 16, 8, 8, 32, 8
 124   };
 125
 126
 127   /**
 128    * Returns the MCU block height for the given level of chrominance
 129    * subsampling.
 130    *
 131    * @param subsamp the level of chrominance subsampling (one of
 132    * {@link #SAMP_444 SAMP_*})
 133    *
 134    * @return the MCU block height for the given level of chrominance
 135    * subsampling.
 136    */
 137   public static int getMCUHeight(int subsamp) {
 138     checkSubsampling(subsamp);
 139     return MCU_HEIGHT[subsamp];
 140   }
 141
 142   private static final int[] MCU_HEIGHT = {
 143     8, 8, 16, 8, 16, 8, 32
 144   };
 145
 146
 147   /**
 148    * The number of pixel formats
 149    */
 150   public static final int NUMPF   = 12;
 151   /**
 152    * RGB pixel format.  The red, green, and blue components in the image are
 153    * stored in 3-sample pixels in the order R, G, B from lowest to highest
 154    * memory address within each pixel.
 155    */
 156   public static final int PF_RGB  = 0;
 157   /**
 158    * BGR pixel format.  The red, green, and blue components in the image are
 159    * stored in 3-sample pixels in the order B, G, R from lowest to highest
 160    * memory address within each pixel.
 161    */
 162   public static final int PF_BGR  = 1;
 163   /**
 164    * RGBX pixel format.  The red, green, and blue components in the image are
 165    * stored in 4-sample pixels in the order R, G, B from lowest to highest
 166    * memory address within each pixel.  The X component is ignored when
 167    * compressing and undefined when decompressing.
 168    */
 169   public static final int PF_RGBX = 2;
 170   /**
 171    * BGRX pixel format.  The red, green, and blue components in the image are
 172    * stored in 4-sample pixels in the order B, G, R from lowest to highest
 173    * memory address within each pixel.  The X component is ignored when
 174    * compressing and undefined when decompressing.
 175    */
 176   public static final int PF_BGRX = 3;
 177   /**
 178    * XBGR pixel format.  The red, green, and blue components in the image are
 179    * stored in 4-sample pixels in the order R, G, B from highest to lowest
 180    * memory address within each pixel.  The X component is ignored when
 181    * compressing and undefined when decompressing.
 182    */
 183   public static final int PF_XBGR = 4;
 184   /**
 185    * XRGB pixel format.  The red, green, and blue components in the image are
 186    * stored in 4-sample pixels in the order B, G, R from highest to lowest
 187    * memory address within each pixel.  The X component is ignored when
 188    * compressing and undefined when decompressing.
 189    */
 190   public static final int PF_XRGB = 5;
 191   /**
 192    * Grayscale pixel format.  Each 1-sample pixel represents a luminance
 193    * (brightness) level from 0 to the maximum sample value (255 for 8-bit
 194    * samples, 4095 for 12-bit samples, and 65535 for 16-bit samples.)
 195    */
 196   public static final int PF_GRAY = 6;
 197   /**
 198    * RGBA pixel format.  This is the same as {@link #PF_RGBX}, except that when
 199    * decompressing, the X component is guaranteed to be equal to the maximum
 200    * sample value, which can be interpreted as an opaque alpha channel.
 201    */
 202   public static final int PF_RGBA = 7;
 203   /**
 204    * BGRA pixel format.  This is the same as {@link #PF_BGRX}, except that when
 205    * decompressing, the X component is guaranteed to be equal to the maximum
 206    * sample value, which can be interpreted as an opaque alpha channel.
 207    */
 208   public static final int PF_BGRA = 8;
 209   /**
 210    * ABGR pixel format.  This is the same as {@link #PF_XBGR}, except that when
 211    * decompressing, the X component is guaranteed to be equal to the maximum
 212    * sample value, which can be interpreted as an opaque alpha channel.
 213    */
 214   public static final int PF_ABGR = 9;
 215   /**
 216    * ARGB pixel format.  This is the same as {@link #PF_XRGB}, except that when
 217    * decompressing, the X component is guaranteed to be equal to the maximum
 218    * sample value, which can be interpreted as an opaque alpha channel.
 219    */
 220   public static final int PF_ARGB = 10;
 221   /**
 222    * CMYK pixel format.  Unlike RGB, which is an additive color model used
 223    * primarily for display, CMYK (Cyan/Magenta/Yellow/Key) is a subtractive
 224    * color model used primarily for printing.  In the CMYK color model, the
 225    * value of each color component typically corresponds to an amount of cyan,
 226    * magenta, yellow, or black ink that is applied to a white background.  In
 227    * order to convert between CMYK and RGB, it is necessary to use a color
 228    * management system (CMS.)  A CMS will attempt to map colors within the
 229    * printer's gamut to perceptually similar colors in the display's gamut and
 230    * vice versa, but the mapping is typically not 1:1 or reversible, nor can it
 231    * be defined with a simple formula.  Thus, such a conversion is out of scope
 232    * for a codec library.  However, the TurboJPEG API allows for compressing
 233    * packed-pixel CMYK images into YCCK JPEG images (see {@link #CS_YCCK}) and
 234    * decompressing YCCK JPEG images into packed-pixel CMYK images.
 235    */
 236   public static final int PF_CMYK = 11;
 237
 238
 239   /**
 240    * Returns the pixel size (in samples) for the given pixel format.
 241    *
 242    * @param pixelFormat the pixel format (one of {@link #PF_RGB PF_*})
 243    *
 244    * @return the pixel size (in samples) for the given pixel format.
 245    */
 246   public static int getPixelSize(int pixelFormat) {
 247     checkPixelFormat(pixelFormat);
 248     return PIXEL_SIZE[pixelFormat];
 249   }
 250
 251   private static final int[] PIXEL_SIZE = {
 252     3, 3, 4, 4, 4, 4, 1, 4, 4, 4, 4, 4
 253   };
 254
 255
 256   /**
 257    * For the given pixel format, returns the number of samples that the red
 258    * component is offset from the start of the pixel.  For instance, if an
 259    * 8-bit-per-sample pixel of format <code>TJ.PF_BGRX</code> is stored in
 260    * <code>char pixel[]</code>, then the red component will be
 261    * <code>pixel[TJ.getRedOffset(TJ.PF_BGRX)]</code>.
 262    *
 263    * @param pixelFormat the pixel format (one of {@link #PF_RGB PF_*})
 264    *
 265    * @return the red offset for the given pixel format, or -1 if the pixel
 266    * format does not have a red component.
 267    */
 268   public static int getRedOffset(int pixelFormat) {
 269     checkPixelFormat(pixelFormat);
 270     return RED_OFFSET[pixelFormat];
 271   }
 272
 273   private static final int[] RED_OFFSET = {
 274     0, 2, 0, 2, 3, 1, -1, 0, 2, 3, 1, -1
 275   };
 276
 277
 278   /**
 279    * For the given pixel format, returns the number of samples that the green
 280    * component is offset from the start of the pixel.  For instance, if an
 281    * 8-bit-per-sample pixel of format <code>TJ.PF_BGRX</code> is stored in
 282    * <code>char pixel[]</code>, then the green component will be
 283    * <code>pixel[TJ.getGreenOffset(TJ.PF_BGRX)]</code>.
 284    *
 285    * @param pixelFormat the pixel format (one of {@link #PF_RGB PF_*})
 286    *
 287    * @return the green offset for the given pixel format, or -1 if the pixel
 288    * format does not have a green component.
 289    */
 290   public static int getGreenOffset(int pixelFormat) {
 291     checkPixelFormat(pixelFormat);
 292     return GREEN_OFFSET[pixelFormat];
 293   }
 294
 295   private static final int[] GREEN_OFFSET = {
 296     1, 1, 1, 1, 2, 2, -1, 1, 1, 2, 2, -1
 297   };
 298
 299
 300   /**
 301    * For the given pixel format, returns the number of samples that the blue
 302    * component is offset from the start of the pixel.  For instance, if an
 303    * 8-bit-per-sample pixel of format <code>TJ.PF_BGRX</code> is stored in
 304    * <code>char pixel[]</code>, then the blue component will be
 305    * <code>pixel[TJ.getBlueOffset(TJ.PF_BGRX)]</code>.
 306    *
 307    * @param pixelFormat the pixel format (one of {@link #PF_RGB PF_*})
 308    *
 309    * @return the blue offset for the given pixel format, or -1 if the pixel
 310    * format does not have a blue component.
 311    */
 312   public static int getBlueOffset(int pixelFormat) {
 313     checkPixelFormat(pixelFormat);
 314     return BLUE_OFFSET[pixelFormat];
 315   }
 316
 317   private static final int[] BLUE_OFFSET = {
 318     2, 0, 2, 0, 1, 3, -1, 2, 0, 1, 3, -1
 319   };
 320
 321
 322   /**
 323    * For the given pixel format, returns the number of samples that the alpha
 324    * component is offset from the start of the pixel.  For instance, if an
 325    * 8-bit-per-sample pixel of format <code>TJ.PF_BGRA</code> is stored in
 326    * <code>char pixel[]</code>, then the alpha component will be
 327    * <code>pixel[TJ.getAlphaOffset(TJ.PF_BGRA)]</code>.
 328    *
 329    * @param pixelFormat the pixel format (one of {@link #PF_RGB PF_*})
 330    *
 331    * @return the alpha offset for the given pixel format, or -1 if the pixel
 332    * format does not have a alpha component.
 333    */
 334   public static int getAlphaOffset(int pixelFormat) {
 335     checkPixelFormat(pixelFormat);
 336     return ALPHA_OFFSET[pixelFormat];
 337   }
 338
 339   private static final int[] ALPHA_OFFSET = {
 340     -1, -1, -1, -1, -1, -1, -1, 3, 3, 0, 0, -1
 341   };
 342
 343
 344   /**
 345    * The number of JPEG colorspaces
 346    */
 347   public static final int NUMCS = 5;
 348   /**
 349    * RGB colorspace.  When compressing the JPEG image, the R, G, and B
 350    * components in the source image are reordered into image planes, but no
 351    * colorspace conversion or subsampling is performed.  RGB JPEG images can be
 352    * compressed from and decompressed to packed-pixel images with any of the
 353    * extended RGB or grayscale pixel formats, but they cannot be compressed
 354    * from or decompressed to planar YUV images.
 355    */
 356   public static final int CS_RGB = 0;
 357   /**
 358    * YCbCr colorspace.  YCbCr is not an absolute colorspace but rather a
 359    * mathematical transformation of RGB designed solely for storage and
 360    * transmission.  YCbCr images must be converted to RGB before they can
 361    * actually be displayed.  In the YCbCr colorspace, the Y (luminance)
 362    * component represents the black &amp; white portion of the original image,
 363    * and the Cb and Cr (chrominance) components represent the color portion of
 364    * the original image.  Originally, the analog equivalent of this
 365    * transformation allowed the same signal to drive both black &amp; white and
 366    * color televisions, but JPEG images use YCbCr primarily because it allows
 367    * the color data to be optionally subsampled for the purposes of reducing
 368    * network or disk usage.  YCbCr is the most common JPEG colorspace, and
 369    * YCbCr JPEG images can be compressed from and decompressed to packed-pixel
 370    * images with any of the extended RGB or grayscale pixel formats.  YCbCr
 371    * JPEG images can also be compressed from and decompressed to planar YUV
 372    * images.
 373    */
 374   @SuppressWarnings("checkstyle:ConstantName")
 375   public static final int CS_YCbCr = 1;
 376   /**
 377    * Grayscale colorspace.  The JPEG image retains only the luminance data (Y
 378    * component), and any color data from the source image is discarded.
 379    * Grayscale JPEG images can be compressed from and decompressed to
 380    * packed-pixel images with any of the extended RGB or grayscale pixel
 381    * formats, or they can be compressed from and decompressed to planar YUV
 382    * images.
 383    */
 384   public static final int CS_GRAY = 2;
 385   /**
 386    * CMYK colorspace.  When compressing the JPEG image, the C, M, Y, and K
 387    * components in the source image are reordered into image planes, but no
 388    * colorspace conversion or subsampling is performed.  CMYK JPEG images can
 389    * only be compressed from and decompressed to packed-pixel images with the
 390    * CMYK pixel format.
 391    */
 392   public static final int CS_CMYK = 3;
 393   /**
 394    * YCCK colorspace.  YCCK (AKA "YCbCrK") is not an absolute colorspace but
 395    * rather a mathematical transformation of CMYK designed solely for storage
 396    * and transmission.  It is to CMYK as YCbCr is to RGB.  CMYK pixels can be
 397    * reversibly transformed into YCCK, and as with YCbCr, the chrominance
 398    * components in the YCCK pixels can be subsampled without incurring major
 399    * perceptual loss.  YCCK JPEG images can only be compressed from and
 400    * decompressed to packed-pixel images with the CMYK pixel format.
 401    */
 402   public static final int CS_YCCK = 4;
 403
 404
 405   /**
 406    * Error handling behavior
 407    *
 408    * <p><b>Value</b>
 409    * <ul>
 410    * <li> <code>0</code> <i>[default]</i> Allow the current
 411    * compression/decompression/transform operation to complete unless a fatal
 412    * error is encountered.
 413    * <li> <code>1</code> Immediately discontinue the current
 414    * compression/decompression/transform operation if a warning (non-fatal
 415    * error) occurs.
 416    * </ul>
 417    */
 418   public static final int PARAM_STOPONWARNING = 0;
 419   /**
 420    * Row order in packed-pixel source/destination images
 421    *
 422    * <p><b>Value</b>
 423    * <ul>
 424    * <li> <code>0</code> <i>[default]</i> top-down (X11) order
 425    * <li> <code>1</code> bottom-up (Windows, OpenGL) order
 426    * </ul>
 427    */
 428   public static final int PARAM_BOTTOMUP = 1;
 429   /**
 430    * Perceptual quality of lossy JPEG images [compression only]
 431    *
 432    * <p><b>Value</b>
 433    * <ul>
 434    * <li> <code>1</code>-<code>100</code> (<code>1</code> = worst quality but
 435    * best compression, <code>100</code> = best quality but worst compression)
 436    * <i>[no default; must be explicitly specified]</i>
 437    * </ul>
 438    */
 439   public static final int PARAM_QUALITY = 3;
 440   /**
 441    * Chrominance subsampling level
 442    *
 443    * <p>The JPEG or YUV image uses (decompression, decoding) or will use (lossy
 444    * compression, encoding) the specified level of chrominance subsampling.
 445    *
 446    * <p>When pixels are converted from RGB to YCbCr (see {@link #CS_YCbCr}) or
 447    * from CMYK to YCCK (see {@link #CS_YCCK}) as part of the JPEG compression
 448    * process, some of the Cb and Cr (chrominance) components can be discarded
 449    * or averaged together to produce a smaller image with little perceptible
 450    * loss of image clarity.  (The human eye is more sensitive to small changes
 451    * in brightness than to small changes in color.)  This is called
 452    * "chrominance subsampling".
 453    *
 454    * <p><b>Value</b>
 455    * <ul>
 456    * <li> One of {@link TJ#SAMP_444 TJ.SAMP_*} <i>[no default; must be
 457    * explicitly specified for lossy compression, encoding, and decoding]</i>
 458    * </ul>
 459    */
 460   public static final int PARAM_SUBSAMP = 4;
 461   /**
 462    * JPEG width (in pixels) [decompression only, read-only]
 463    */
 464   public static final int PARAM_JPEGWIDTH = 5;
 465   /**
 466    * JPEG height (in pixels) [decompression only, read-only]
 467    */
 468   public static final int PARAM_JPEGHEIGHT = 6;
 469   /**
 470    * JPEG data precision (bits per sample) [decompression only, read-only]
 471    *
 472    * <p>The JPEG image uses the specified number of bits per sample.
 473    *
 474    * <p><b>Value</b>
 475    * <ul>
 476    * <li> <code>8</code>, <code>12</code>, or <code>16</code>
 477    * </ul>
 478    *
 479    * <p>12-bit data precision implies {@link #PARAM_OPTIMIZE} unless
 480    * {@link #PARAM_ARITHMETIC} is set.
 481    */
 482   public static final int PARAM_PRECISION = 7;
 483   /**
 484    * JPEG colorspace
 485    *
 486    * <p>The JPEG image uses (decompression) or will use (lossy compression) the
 487    * specified colorspace.
 488    *
 489    * <p><b>Value</b>
 490    * <ul>
 491    * <li> One of {@link TJ#CS_RGB TJ.CS_*} <i>[default for lossy compression:
 492    * automatically selected based on the subsampling level and pixel
 493    * format]</i>
 494    * </ul>
 495    */
 496   public static final int PARAM_COLORSPACE = 8;
 497   /**
 498    * Chrominance upsampling algorithm [lossy decompression only]
 499    *
 500    * <p><b>Value</b>
 501    * <ul>
 502    * <li> <code>0</code> <i>[default]</i> Use smooth upsampling when
 503    * decompressing a JPEG image that was compressed using chrominance
 504    * subsampling.  This creates a smooth transition between neighboring
 505    * chrominance components in order to reduce upsampling artifacts in the
 506    * decompressed image.
 507    * <li> <code>1</code> Use the fastest chrominance upsampling algorithm
 508    * available, which may combine upsampling with color conversion.
 509    * </ul>
 510    */
 511   public static final int PARAM_FASTUPSAMPLE = 9;
 512   /**
 513    * DCT/IDCT algorithm [lossy compression and decompression]
 514    *
 515    * <p><b>Value</b>
 516    * <ul>
 517    * <li> <code>0</code> <i>[default]</i> Use the most accurate DCT/IDCT
 518    * algorithm available.
 519    * <li> <code>1</code> Use the fastest DCT/IDCT algorithm available.
 520    * </ul>
 521    *
 522    * <p>This parameter is provided mainly for backward compatibility with
 523    * libjpeg, which historically implemented several different DCT/IDCT
 524    * algorithms because of performance limitations with 1990s CPUs.  In the
 525    * libjpeg-turbo implementation of the TurboJPEG API:
 526    *
 527    * <ul>
 528    * <li> The "fast" and "accurate" DCT/IDCT algorithms perform similarly on
 529    * modern x86/x86-64 CPUs that support AVX2 instructions.
 530    * <li> The "fast" algorithm is generally only about 5-15% faster than the
 531    * "accurate" algorithm on other types of CPUs.
 532    * <li> The difference in accuracy between the "fast" and "accurate"
 533    * algorithms is the most pronounced at JPEG quality levels above 90 and
 534    * tends to be more pronounced with decompression than with compression.
 535    * <li> The "fast" algorithm degrades and is not fully accelerated for JPEG
 536    * quality levels above 97, so it will be slower than the "accurate"
 537    * algorithm.
 538    * </ul>
 539    */
 540   public static final int PARAM_FASTDCT = 10;
 541   /**
 542    * Optimized baseline entropy coding [lossy compression only]
 543    *
 544    * <p><b>Value</b>
 545    * <ul>
 546    * <li> <code>0</code> <i>[default]</i> The JPEG image will use the default
 547    * Huffman tables.
 548    * <li> <code>1</code> Optimal Huffman tables will be computed for the JPEG
 549    * image.  For lossless transformation, this can also be specified using
 550    * {@link TJTransform#OPT_OPTIMIZE}.
 551    * </ul>
 552    *
 553    * <p>Optimized baseline entropy coding will improve compression slightly
 554    * (generally 5% or less), but it will reduce compression performance
 555    * considerably.
 556    */
 557   public static final int PARAM_OPTIMIZE = 11;
 558   /**
 559    * Progressive entropy coding
 560    *
 561    * <p><b>Value</b>
 562    * <ul>
 563    * <li> <code>0</code> <i>[default for compression, lossless
 564    * transformation]</i> The lossy JPEG image uses (decompression) or will use
 565    * (compression, lossless transformation) baseline entropy coding.
 566    * <li> <code>1</code> The lossy JPEG image uses (decompression) or will use
 567    * (compression, lossless transformation) progressive entropy coding.  For
 568    * lossless transformation, this can also be specified using
 569    * {@link TJTransform#OPT_PROGRESSIVE}.
 570    * </ul>
 571    *
 572    * <p>Progressive entropy coding will generally improve compression relative
 573    * to baseline entropy coding, but it will reduce compression and
 574    * decompression performance considerably.  Can be combined with
 575    * {@link #PARAM_ARITHMETIC}.  Implies {@link #PARAM_OPTIMIZE} unless
 576    * {@link #PARAM_ARITHMETIC} is also set.
 577    */
 578   public static final int PARAM_PROGRESSIVE = 12;
 579   /**
 580    * Progressive JPEG scan limit for lossy JPEG images [decompression, lossless
 581    * transformation]
 582    *
 583    * <p>Setting this parameter will cause the decompression and transform
 584    * functions to return an error if the number of scans in a progressive JPEG
 585    * image exceeds the specified limit.  The primary purpose of this is to
 586    * allow security-critical applications to guard against an exploit of the
 587    * progressive JPEG format described in
 588    * <a href="https://libjpeg-turbo.org/pmwiki/uploads/About/TwoIssueswiththeJPEGStandard.pdf" target="_blank">this report</a>.
 589    *
 590    * <p><b>Value</b>
 591    * <ul>
 592    * <li> maximum number of progressive JPEG scans that the decompression and
 593    * transform functions will process <i>[default: <code>0</code> (no
 594    * limit)]</i>
 595    * </ul>
 596    *
 597    * @see #PARAM_PROGRESSIVE
 598    */
 599   public static final int PARAM_SCANLIMIT = 13;
 600   /**
 601    * Arithmetic entropy coding
 602    *
 603    * <p><b>Value</b>
 604    * <ul>
 605    * <li> <code>0</code> <i>[default for compression, lossless
 606    * transformation]</i> The lossy JPEG image uses (decompression) or will use
 607    * (compression, lossless transformation) Huffman entropy coding.
 608    * <li> <code>1</code> The lossy JPEG image uses (decompression) or will use
 609    * (compression, lossless transformation) arithmetic entropy coding.  For
 610    * lossless transformation, this can also be specified using
 611    * {@link TJTransform#OPT_ARITHMETIC}.
 612    * </ul>
 613    *
 614    * <p>Arithmetic entropy coding will generally improve compression relative
 615    * to Huffman entropy coding, but it will reduce compression and
 616    * decompression performance considerably.  Can be combined with
 617    * {@link #PARAM_PROGRESSIVE}.
 618    */
 619   public static final int PARAM_ARITHMETIC = 14;
 620   /**
 621    * Lossless JPEG
 622    *
 623    * <p><b>Value</b>
 624    * <ul>
 625    * <li> <code>0</code> <i>[default for compression]</i> The JPEG image is
 626    * (decompression) or will be (compression) lossy/DCT-based.
 627    * <li> <code>1</code> The JPEG image is (decompression) or will be
 628    * (compression) lossless/predictive.
 629    * </ul>
 630    *
 631    * <p>In most cases, compressing and decompressing lossless JPEG images is
 632    * considerably slower than compressing and decompressing lossy JPEG images.
 633    * Also note that the following features are not available with lossless JPEG
 634    * images:
 635    * <ul>
 636    * <li> Colorspace conversion (lossless JPEG images always use
 637    * {@link #CS_RGB}, {@link #CS_GRAY}, or {@link #CS_CMYK}, depending on the
 638    * pixel format of the source image)
 639    * <li> Chrominance subsampling (lossless JPEG images always use
 640    * {@link #SAMP_444})
 641    * <li> JPEG quality selection
 642    * <li> DCT/IDCT algorithm selection
 643    * <li> Progressive entropy coding
 644    * <li> Arithmetic entropy coding
 645    * <li> Compression from/decompression to planar YUV images
 646    * <li> Decompression scaling
 647    * <li> Lossless transformation
 648    * </ul>
 649    *
 650    * @see #PARAM_LOSSLESSPSV
 651    * @see #PARAM_LOSSLESSPT
 652    */
 653   public static final int PARAM_LOSSLESS = 15;
 654   /**
 655    * Lossless JPEG predictor selection value (PSV)
 656    *
 657    * <p><b>Value</b>
 658    * <ul>
 659    * <li> <code>1</code>-<code>7</code> <i>[default for compression:
 660    * <code>1</code>]</i>
 661    * </ul>
 662    *
 663    * @see #PARAM_LOSSLESS
 664    */
 665   public static final int PARAM_LOSSLESSPSV = 16;
 666   /**
 667    * Lossless JPEG point transform (Pt)
 668    *
 669    * <p><b>Value</b>
 670    * <ul>
 671    * <li> <code>0</code> through <i><b>precision</b> - 1</i>, where
 672    * <b><i>precision</i></b> is the JPEG data precision in bits <i>[default for
 673    * compression: <code>0</code>]</i>
 674    * </ul>
 675    *
 676    * <p>A point transform value of <code>0</code> is necessary in order to
 677    * generate a fully lossless JPEG image.  (A non-zero point transform value
 678    * right-shifts the input samples by the specified number of bits, which is
 679    * effectively a form of lossy color quantization.)
 680    *
 681    * @see #PARAM_LOSSLESS
 682    * @see #PARAM_PRECISION
 683    */
 684   public static final int PARAM_LOSSLESSPT = 17;
 685   /**
 686    * JPEG restart marker interval in MCU blocks (lossy) or samples (lossless)
 687    * [compression only]
 688    *
 689    * <p>The nature of entropy coding is such that a corrupt JPEG image cannot
 690    * be decompressed beyond the point of corruption unless it contains restart
 691    * markers.  A restart marker stops and restarts the entropy coding algorithm
 692    * so that, if a JPEG image is corrupted, decompression can resume at the
 693    * next marker.  Thus, adding more restart markers improves the fault
 694    * tolerance of the JPEG image, but adding too many restart markers can
 695    * adversely affect the compression ratio and performance.
 696    *
 697    * <p><b>Value</b>
 698    * <ul>
 699    * <li> the number of MCU blocks or samples between each restart marker
 700    * <i>[default: <code>0</code> (no restart markers)]</i>
 701    * </ul>
 702    *
 703    * <p> Setting this parameter to a non-zero value sets
 704    * {@link #PARAM_RESTARTROWS} to 0.
 705    */
 706   public static final int PARAM_RESTARTBLOCKS = 18;
 707   /**
 708    * JPEG restart marker interval in MCU rows (lossy) or sample rows (lossless)
 709    * [compression only]
 710    *
 711    * <p>See {@link #PARAM_RESTARTBLOCKS} for a description of restart markers.
 712    *
 713    * <p><b>Value</b>
 714    * <ul>
 715    * <li> the number of MCU rows or sample rows between each restart marker
 716    * <i>[default: <code>0</code> (no restart markers)]</i>
 717    * </ul>
 718    *
 719    * <p>Setting this parameter to a non-zero value sets
 720    * {@link #PARAM_RESTARTBLOCKS} to 0.
 721    */
 722   public static final int PARAM_RESTARTROWS = 19;
 723   /**
 724    * JPEG horizontal pixel density
 725    *
 726    * <p><b>Value</b>
 727    * <ul>
 728    * <li> The JPEG image has (decompression) or will have (compression) the
 729    * specified horizontal pixel density <i>[default for compression:
 730    * <code>1</code>]</i>.
 731    * </ul>
 732    *
 733    * <p>This value is stored in or read from the JPEG header.  It does not
 734    * affect the contents of the JPEG image.
 735    *
 736    * @see #PARAM_DENSITYUNITS
 737    */
 738   public static final int PARAM_XDENSITY = 20;
 739   /**
 740    * JPEG vertical pixel density
 741    *
 742    * <p><b>Value</b>
 743    * <ul>
 744    * <li> The JPEG image has (decompression) or will have (compression) the
 745    * specified vertical pixel density <i>[default for compression:
 746    * <code>1</code>]</i>.
 747    * </ul>
 748    *
 749    * <p>This value is stored in or read from the JPEG header.  It does not
 750    * affect the contents of the JPEG image.
 751    *
 752    * @see #PARAM_DENSITYUNITS
 753    */
 754   public static final int PARAM_YDENSITY = 21;
 755   /**
 756    * JPEG pixel density units
 757    *
 758    * <p><b>Value</b>
 759    * <ul>
 760    * <li> <code>0</code> <i>[default for compression]</i> The pixel density of
 761    * the JPEG image is expressed (decompression) or will be expressed
 762    * (compression) in unknown units.
 763    * <li> <code>1</code> The pixel density of the JPEG image is expressed
 764    * (decompression) or will be expressed (compression) in units of
 765    * pixels/inch.
 766    * <li> <code>2</code> The pixel density of the JPEG image is expressed
 767    * (decompression) or will be expressed (compression) in units of pixels/cm.
 768    * </ul>
 769    *
 770    * <p>This value is stored in or read from the JPEG header.  It does not
 771    * affect the contents of the JPEG image.
 772    *
 773    * @see #PARAM_XDENSITY
 774    * @see #PARAM_YDENSITY
 775    */
 776   public static final int PARAM_DENSITYUNITS = 22;
 777
 778
 779   /**
 780    * @deprecated Use {@link #PARAM_BOTTOMUP} instead.
 781    */
 782   @Deprecated
 783   public static final int FLAG_BOTTOMUP      = 2;
 784   /**
 785    * @deprecated Use {@link #PARAM_FASTUPSAMPLE} instead.
 786    */
 787   @Deprecated
 788   public static final int FLAG_FASTUPSAMPLE  = 256;
 789   /**
 790    * @deprecated Use {@link #PARAM_FASTDCT} instead.
 791    */
 792   @Deprecated
 793   public static final int FLAG_FASTDCT       = 2048;
 794   /**
 795    * @deprecated Use {@link #PARAM_FASTDCT} instead.
 796    */
 797   @Deprecated
 798   public static final int FLAG_ACCURATEDCT   = 4096;
 799   /**
 800    * @deprecated Use {@link #PARAM_STOPONWARNING} instead.
 801    */
 802   @Deprecated
 803   public static final int FLAG_STOPONWARNING = 8192;
 804   /**
 805    * @deprecated Use {@link #PARAM_PROGRESSIVE} instead.
 806    */
 807   @Deprecated
 808   public static final int FLAG_PROGRESSIVE   = 16384;
 809   /**
 810    * @deprecated Use {@link #PARAM_SCANLIMIT} instead.
 811    */
 812   @Deprecated
 813   public static final int FLAG_LIMITSCANS    = 32768;
 814
 815
 816   /**
 817    * The number of error codes
 818    */
 819   public static final int NUMERR = 2;
 820   /**
 821    * The error was non-fatal and recoverable, but the destination image may
 822    * still be corrupt.
 823    * <p>
 824    * NOTE: due to the design of the TurboJPEG Java API, only certain methods
 825    * (specifically, {@link TJDecompressor TJDecompressor.decompress*()} methods
 826    * with a void return type) will complete and leave the destination image in
 827    * a fully recoverable state after a non-fatal error occurs.
 828    */
 829   public static final int ERR_WARNING = 0;
 830   /**
 831    * The error was fatal and non-recoverable.
 832    */
 833   public static final int ERR_FATAL = 1;
 834
 835
 836   /**
 837    * Returns the maximum size of the buffer (in bytes) required to hold a JPEG
 838    * image with the given width, height, and level of chrominance subsampling.
 839    *
 840    * @param width the width (in pixels) of the JPEG image
 841    *
 842    * @param height the height (in pixels) of the JPEG image
 843    *
 844    * @param jpegSubsamp the level of chrominance subsampling to be used when
 845    * generating the JPEG image (one of {@link #SAMP_444 TJ.SAMP_*}.)
 846    * {@link #SAMP_UNKNOWN} is treated like {@link #SAMP_444}, since a buffer
 847    * large enough to hold a JPEG image with no subsampling should also be large
 848    * enough to hold a JPEG image with an arbitrary level of subsampling.  Note
 849    * that lossless JPEG images always use {@link #SAMP_444}.
 850    *
 851    * @return the maximum size of the buffer (in bytes) required to hold a JPEG
 852    * image with the given width, height, and level of chrominance subsampling.
 853    */
 854   public static native int bufSize(int width, int height, int jpegSubsamp);
 855
 856   /**
 857    * Returns the size of the buffer (in bytes) required to hold a unified
 858    * planar YUV image with the given width, height, and level of chrominance
 859    * subsampling.
 860    *
 861    * @param width the width (in pixels) of the YUV image
 862    *
 863    * @param align row alignment (in bytes) of the YUV image (must be a power of
 864    * 2.)  Setting this parameter to n specifies that each row in each plane of
 865    * the YUV image will be padded to the nearest multiple of n bytes
 866    * (1 = unpadded.)
 867    *
 868    * @param height the height (in pixels) of the YUV image
 869    *
 870    * @param subsamp the level of chrominance subsampling used in the YUV
 871    * image (one of {@link #SAMP_444 TJ.SAMP_*})
 872    *
 873    * @return the size of the buffer (in bytes) required to hold a unified
 874    * planar YUV image with the given width, height, and level of chrominance
 875    * subsampling.
 876    */
 877   public static native int bufSizeYUV(int width, int align, int height,
 878                                       int subsamp);
 879
 880   /**
 881    * Returns the size of the buffer (in bytes) required to hold a YUV image
 882    * plane with the given parameters.
 883    *
 884    * @param componentID ID number of the image plane (0 = Y, 1 = U/Cb,
 885    * 2 = V/Cr)
 886    *
 887    * @param width width (in pixels) of the YUV image.  NOTE: this is the width
 888    * of the whole image, not the plane width.
 889    *
 890    * @param stride bytes per row in the image plane.
 891    *
 892    * @param height height (in pixels) of the YUV image.  NOTE: this is the
 893    * height of the whole image, not the plane height.
 894    *
 895    * @param subsamp the level of chrominance subsampling used in the YUV
 896    * image (one of {@link #SAMP_444 TJ.SAMP_*})
 897    *
 898    * @return the size of the buffer (in bytes) required to hold a YUV image
 899    * plane with the given parameters.
 900    */
 901   public static native int planeSizeYUV(int componentID, int width, int stride,
 902                                         int height, int subsamp);
 903
 904   /**
 905    * Returns the plane width of a YUV image plane with the given parameters.
 906    * Refer to {@link YUVImage} for a description of plane width.
 907    *
 908    * @param componentID ID number of the image plane (0 = Y, 1 = U/Cb,
 909    * 2 = V/Cr)
 910    *
 911    * @param width width (in pixels) of the YUV image
 912    *
 913    * @param subsamp the level of chrominance subsampling used in the YUV image
 914    * (one of {@link #SAMP_444 TJ.SAMP_*})
 915    *
 916    * @return the plane width of a YUV image plane with the given parameters.
 917    */
 918   public static native int planeWidth(int componentID, int width, int subsamp);
 919
 920   /**
 921    * Returns the plane height of a YUV image plane with the given parameters.
 922    * Refer to {@link YUVImage} for a description of plane height.
 923    *
 924    * @param componentID ID number of the image plane (0 = Y, 1 = U/Cb,
 925    * 2 = V/Cr)
 926    *
 927    * @param height height (in pixels) of the YUV image
 928    *
 929    * @param subsamp the level of chrominance subsampling used in the YUV image
 930    * (one of {@link #SAMP_444 TJ.SAMP_*})
 931    *
 932    * @return the plane height of a YUV image plane with the given parameters.
 933    */
 934   public static native int planeHeight(int componentID, int height,
 935                                        int subsamp);
 936
 937   /**
 938    * Returns a list of fractional scaling factors that the JPEG decompressor
 939    * supports.
 940    *
 941    * @return a list of fractional scaling factors that the JPEG decompressor
 942    * supports.
 943    */
 944   public static native TJScalingFactor[] getScalingFactors();
 945
 946   /**
 947    * A {@link TJScalingFactor} instance that specifies a scaling factor of 1/1
 948    * (no scaling)
 949    */
 950   public static final TJScalingFactor UNSCALED = new TJScalingFactor(1, 1);
 951
 952   /**
 953    * A <code>java.awt.Rectangle</code> instance that specifies no cropping
 954    */
 955   public static final Rectangle UNCROPPED = new Rectangle(0, 0, 0, 0);
 956
 957   static {
 958     TJLoader.load();
 959   }
 960
 961   private static void checkPixelFormat(int pixelFormat) {
 962     if (pixelFormat < 0 || pixelFormat >= NUMPF)
 963       throw new IllegalArgumentException("Invalid pixel format");
 964   }
 965
 966   private static void checkSubsampling(int subsamp) {
 967     if (subsamp < 0 || subsamp >= NUMSAMP)
 968       throw new IllegalArgumentException("Invalid subsampling type");
 969   }
 970
 971 }