1 /* 2 * Copyright (C)2011-2013 D. R. Commander. All Rights Reserved. 3 * Copyright (C)2015 Viktor Szathmry. All Rights Reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 8 * - Redistributions of source code must retain the above copyright notice, 9 * this list of conditions and the following disclaimer. 10 * - Redistributions in binary form must reproduce the above copyright notice, 11 * this list of conditions and the following disclaimer in the documentation 12 * and/or other materials provided with the distribution. 13 * - Neither the name of the libjpeg-turbo Project nor the names of its 14 * contributors may be used to endorse or promote products derived from this 15 * software without specific prior written permission. 16 * 17 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS", 18 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE 21 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27 * POSSIBILITY OF SUCH DAMAGE. 28 */ 29 30 package org.libjpegturbo.turbojpeg; 31 32 /** 33 * TurboJPEG utility class (cannot be instantiated) 34 */ 35 public final class TJ { 36 37 38 /** 39 * The number of chrominance subsampling options 40 */ 41 public static final int NUMSAMP = 6; 42 /** 43 * 4:4:4 chrominance subsampling (no chrominance subsampling). The JPEG 44 * or YUV image will contain one chrominance component for every pixel in the 45 * source image. 46 */ 47 public static final int SAMP_444 = 0; 48 /** 49 * 4:2:2 chrominance subsampling. The JPEG or YUV image will contain one 50 * chrominance component for every 2x1 block of pixels in the source image. 51 */ 52 public static final int SAMP_422 = 1; 53 /** 54 * 4:2:0 chrominance subsampling. The JPEG or YUV image will contain one 55 * chrominance component for every 2x2 block of pixels in the source image. 56 */ 57 public static final int SAMP_420 = 2; 58 /** 59 * Grayscale. The JPEG or YUV image will contain no chrominance components. 60 */ 61 public static final int SAMP_GRAY = 3; 62 /** 63 * 4:4:0 chrominance subsampling. The JPEG or YUV image will contain one 64 * chrominance component for every 1x2 block of pixels in the source image. 65 * Note that 4:4:0 subsampling is not fully accelerated in libjpeg-turbo. 66 */ 67 public static final int SAMP_440 = 4; 68 /** 69 * 4:1:1 chrominance subsampling. The JPEG or YUV image will contain one 70 * chrominance component for every 4x1 block of pixels in the source image. 71 * JPEG images compressed with 4:1:1 subsampling will be almost exactly the 72 * same size as those compressed with 4:2:0 subsampling, and in the 73 * aggregate, both subsampling methods produce approximately the same 74 * perceptual quality. However, 4:1:1 is better able to reproduce sharp 75 * horizontal features. Note that 4:1:1 subsampling is not fully accelerated 76 * in libjpeg-turbo. 77 */ 78 public static final int SAMP_411 = 5; 79 80 81 /** 82 * Returns the MCU block width for the given level of chrominance 83 * subsampling. 84 * 85 * @param subsamp the level of chrominance subsampling (one of 86 * <code>SAMP_*</code>) 87 * 88 * @return the MCU block width for the given level of chrominance 89 * subsampling. 90 */ 91 public static int getMCUWidth(int subsamp) { 92 checkSubsampling(subsamp); 93 return mcuWidth[subsamp]; 94 } 95 96 private static final int[] mcuWidth = { 97 8, 16, 16, 8, 8, 32 98 }; 99 100 101 /** 102 * Returns the MCU block height for the given level of chrominance 103 * subsampling. 104 * 105 * @param subsamp the level of chrominance subsampling (one of 106 * <code>SAMP_*</code>) 107 * 108 * @return the MCU block height for the given level of chrominance 109 * subsampling. 110 */ 111 public static int getMCUHeight(int subsamp) { 112 checkSubsampling(subsamp); 113 return mcuHeight[subsamp]; 114 } 115 116 private static final int[] mcuHeight = { 117 8, 8, 16, 8, 16, 8 118 }; 119 120 121 /** 122 * The number of pixel formats 123 */ 124 public static final int NUMPF = 12; 125 /** 126 * RGB pixel format. The red, green, and blue components in the image are 127 * stored in 3-byte pixels in the order R, G, B from lowest to highest byte 128 * address within each pixel. 129 */ 130 public static final int PF_RGB = 0; 131 /** 132 * BGR pixel format. The red, green, and blue components in the image are 133 * stored in 3-byte pixels in the order B, G, R from lowest to highest byte 134 * address within each pixel. 135 */ 136 public static final int PF_BGR = 1; 137 /** 138 * RGBX pixel format. The red, green, and blue components in the image are 139 * stored in 4-byte pixels in the order R, G, B from lowest to highest byte 140 * address within each pixel. The X component is ignored when compressing 141 * and undefined when decompressing. 142 */ 143 public static final int PF_RGBX = 2; 144 /** 145 * BGRX pixel format. The red, green, and blue components in the image are 146 * stored in 4-byte pixels in the order B, G, R from lowest to highest byte 147 * address within each pixel. The X component is ignored when compressing 148 * and undefined when decompressing. 149 */ 150 public static final int PF_BGRX = 3; 151 /** 152 * XBGR pixel format. The red, green, and blue components in the image are 153 * stored in 4-byte pixels in the order R, G, B from highest to lowest byte 154 * address within each pixel. The X component is ignored when compressing 155 * and undefined when decompressing. 156 */ 157 public static final int PF_XBGR = 4; 158 /** 159 * XRGB pixel format. The red, green, and blue components in the image are 160 * stored in 4-byte pixels in the order B, G, R from highest to lowest byte 161 * address within each pixel. The X component is ignored when compressing 162 * and undefined when decompressing. 163 */ 164 public static final int PF_XRGB = 5; 165 /** 166 * Grayscale pixel format. Each 1-byte pixel represents a luminance 167 * (brightness) level from 0 to 255. 168 */ 169 public static final int PF_GRAY = 6; 170 /** 171 * RGBA pixel format. This is the same as {@link #PF_RGBX}, except that when 172 * decompressing, the X byte is guaranteed to be 0xFF, which can be 173 * interpreted as an opaque alpha channel. 174 */ 175 public static final int PF_RGBA = 7; 176 /** 177 * BGRA pixel format. This is the same as {@link #PF_BGRX}, except that when 178 * decompressing, the X byte is guaranteed to be 0xFF, which can be 179 * interpreted as an opaque alpha channel. 180 */ 181 public static final int PF_BGRA = 8; 182 /** 183 * ABGR pixel format. This is the same as {@link #PF_XBGR}, except that when 184 * decompressing, the X byte is guaranteed to be 0xFF, which can be 185 * interpreted as an opaque alpha channel. 186 */ 187 public static final int PF_ABGR = 9; 188 /** 189 * ARGB pixel format. This is the same as {@link #PF_XRGB}, except that when 190 * decompressing, the X byte is guaranteed to be 0xFF, which can be 191 * interpreted as an opaque alpha channel. 192 */ 193 public static final int PF_ARGB = 10; 194 /** 195 * CMYK pixel format. Unlike RGB, which is an additive color model used 196 * primarily for display, CMYK (Cyan/Magenta/Yellow/Key) is a subtractive 197 * color model used primarily for printing. In the CMYK color model, the 198 * value of each color component typically corresponds to an amount of cyan, 199 * magenta, yellow, or black ink that is applied to a white background. In 200 * order to convert between CMYK and RGB, it is necessary to use a color 201 * management system (CMS.) A CMS will attempt to map colors within the 202 * printer's gamut to perceptually similar colors in the display's gamut and 203 * vice versa, but the mapping is typically not 1:1 or reversible, nor can it 204 * be defined with a simple formula. Thus, such a conversion is out of scope 205 * for a codec library. However, the TurboJPEG API allows for compressing 206 * CMYK pixels into a YCCK JPEG image (see {@link #CS_YCCK}) and 207 * decompressing YCCK JPEG images into CMYK pixels. 208 */ 209 public static final int PF_CMYK = 11; 210 211 212 /** 213 * Returns the pixel size (in bytes) for the given pixel format. 214 * 215 * @param pixelFormat the pixel format (one of <code>PF_*</code>) 216 * 217 * @return the pixel size (in bytes) for the given pixel format. 218 */ 219 public static int getPixelSize(int pixelFormat) { 220 checkPixelFormat(pixelFormat); 221 return pixelSize[pixelFormat]; 222 } 223 224 private static final int[] pixelSize = { 225 3, 3, 4, 4, 4, 4, 1, 4, 4, 4, 4, 4 226 }; 227 228 229 /** 230 * For the given pixel format, returns the number of bytes that the red 231 * component is offset from the start of the pixel. For instance, if a pixel 232 * of format <code>TJ.PF_BGRX</code> is stored in <code>char pixel[]</code>, 233 * then the red component will be 234 * <code>pixel[TJ.getRedOffset(TJ.PF_BGRX)]</code>. 235 * 236 * @param pixelFormat the pixel format (one of <code>PF_*</code>) 237 * 238 * @return the red offset for the given pixel format. 239 */ 240 public static int getRedOffset(int pixelFormat) { 241 checkPixelFormat(pixelFormat); 242 return redOffset[pixelFormat]; 243 } 244 245 private static final int[] redOffset = { 246 0, 2, 0, 2, 3, 1, 0, 0, 2, 3, 1, -1 247 }; 248 249 250 /** 251 * For the given pixel format, returns the number of bytes that the green 252 * component is offset from the start of the pixel. For instance, if a pixel 253 * of format <code>TJ.PF_BGRX</code> is stored in <code>char pixel[]</code>, 254 * then the green component will be 255 * <code>pixel[TJ.getGreenOffset(TJ.PF_BGRX)]</code>. 256 * 257 * @param pixelFormat the pixel format (one of <code>PF_*</code>) 258 * 259 * @return the green offset for the given pixel format. 260 */ 261 public static int getGreenOffset(int pixelFormat) { 262 checkPixelFormat(pixelFormat); 263 return greenOffset[pixelFormat]; 264 } 265 266 private static final int[] greenOffset = { 267 1, 1, 1, 1, 2, 2, 0, 1, 1, 2, 2, -1 268 }; 269 270 271 /** 272 * For the given pixel format, returns the number of bytes that the blue 273 * component is offset from the start of the pixel. For instance, if a pixel 274 * of format <code>TJ.PF_BGRX</code> is stored in <code>char pixel[]</code>, 275 * then the blue component will be 276 * <code>pixel[TJ.getBlueOffset(TJ.PF_BGRX)]</code>. 277 * 278 * @param pixelFormat the pixel format (one of <code>PF_*</code>) 279 * 280 * @return the blue offset for the given pixel format. 281 */ 282 public static int getBlueOffset(int pixelFormat) { 283 checkPixelFormat(pixelFormat); 284 return blueOffset[pixelFormat]; 285 } 286 287 private static final int[] blueOffset = { 288 2, 0, 2, 0, 1, 3, 0, 2, 0, 1, 3, -1 289 }; 290 291 292 /** 293 * The number of JPEG colorspaces 294 */ 295 public static final int NUMCS = 5; 296 /** 297 * RGB colorspace. When compressing the JPEG image, the R, G, and B 298 * components in the source image are reordered into image planes, but no 299 * colorspace conversion or subsampling is performed. RGB JPEG images can be 300 * decompressed to any of the extended RGB pixel formats or grayscale, but 301 * they cannot be decompressed to YUV images. 302 */ 303 public static final int CS_RGB = 0; 304 /** 305 * YCbCr colorspace. YCbCr is not an absolute colorspace but rather a 306 * mathematical transformation of RGB designed solely for storage and 307 * transmission. YCbCr images must be converted to RGB before they can 308 * actually be displayed. In the YCbCr colorspace, the Y (luminance) 309 * component represents the black & white portion of the original image, and 310 * the Cb and Cr (chrominance) components represent the color portion of the 311 * original image. Originally, the analog equivalent of this transformation 312 * allowed the same signal to drive both black & white and color televisions, 313 * but JPEG images use YCbCr primarily because it allows the color data to be 314 * optionally subsampled for the purposes of reducing bandwidth or disk 315 * space. YCbCr is the most common JPEG colorspace, and YCbCr JPEG images 316 * can be compressed from and decompressed to any of the extended RGB pixel 317 * formats or grayscale, or they can be decompressed to YUV planar images. 318 */ 319 public static final int CS_YCbCr = 1; 320 /** 321 * Grayscale colorspace. The JPEG image retains only the luminance data (Y 322 * component), and any color data from the source image is discarded. 323 * Grayscale JPEG images can be compressed from and decompressed to any of 324 * the extended RGB pixel formats or grayscale, or they can be decompressed 325 * to YUV planar images. 326 */ 327 public static final int CS_GRAY = 2; 328 /** 329 * CMYK colorspace. When compressing the JPEG image, the C, M, Y, and K 330 * components in the source image are reordered into image planes, but no 331 * colorspace conversion or subsampling is performed. CMYK JPEG images can 332 * only be decompressed to CMYK pixels. 333 */ 334 public static final int CS_CMYK = 3; 335 /** 336 * YCCK colorspace. YCCK (AKA "YCbCrK") is not an absolute colorspace but 337 * rather a mathematical transformation of CMYK designed solely for storage 338 * and transmission. It is to CMYK as YCbCr is to RGB. CMYK pixels can be 339 * reversibly transformed into YCCK, and as with YCbCr, the chrominance 340 * components in the YCCK pixels can be subsampled without incurring major 341 * perceptual loss. YCCK JPEG images can only be compressed from and 342 * decompressed to CMYK pixels. 343 */ 344 public static final int CS_YCCK = 4; 345 346 347 /** 348 * The uncompressed source/destination image is stored in bottom-up (Windows, 349 * OpenGL) order, not top-down (X11) order. 350 */ 351 public static final int FLAG_BOTTOMUP = 2; 352 353 @Deprecated 354 public static final int FLAG_FORCEMMX = 8; 355 @Deprecated 356 public static final int FLAG_FORCESSE = 16; 357 @Deprecated 358 public static final int FLAG_FORCESSE2 = 32; 359 @Deprecated 360 public static final int FLAG_FORCESSE3 = 128; 361 362 /** 363 * When decompressing an image that was compressed using chrominance 364 * subsampling, use the fastest chrominance upsampling algorithm available in 365 * the underlying codec. The default is to use smooth upsampling, which 366 * creates a smooth transition between neighboring chrominance components in 367 * order to reduce upsampling artifacts in the decompressed image. 368 */ 369 public static final int FLAG_FASTUPSAMPLE = 256; 370 /** 371 * Use the fastest DCT/IDCT algorithm available in the underlying codec. The 372 * default if this flag is not specified is implementation-specific. For 373 * example, the implementation of TurboJPEG for libjpeg[-turbo] uses the fast 374 * algorithm by default when compressing, because this has been shown to have 375 * only a very slight effect on accuracy, but it uses the accurate algorithm 376 * when decompressing, because this has been shown to have a larger effect. 377 */ 378 public static final int FLAG_FASTDCT = 2048; 379 /** 380 * Use the most accurate DCT/IDCT algorithm available in the underlying 381 * codec. The default if this flag is not specified is 382 * implementation-specific. For example, the implementation of TurboJPEG for 383 * libjpeg[-turbo] uses the fast algorithm by default when compressing, 384 * because this has been shown to have only a very slight effect on accuracy, 385 * but it uses the accurate algorithm when decompressing, because this has 386 * been shown to have a larger effect. 387 */ 388 public static final int FLAG_ACCURATEDCT = 4096; 389 390 391 /** 392 * Returns the maximum size of the buffer (in bytes) required to hold a JPEG 393 * image with the given width, height, and level of chrominance subsampling. 394 * 395 * @param width the width (in pixels) of the JPEG image 396 * 397 * @param height the height (in pixels) of the JPEG image 398 * 399 * @param jpegSubsamp the level of chrominance subsampling to be used when 400 * generating the JPEG image (one of {@link TJ TJ.SAMP_*}) 401 * 402 * @return the maximum size of the buffer (in bytes) required to hold a JPEG 403 * image with the given width, height, and level of chrominance subsampling. 404 */ 405 public static native int bufSize(int width, int height, int jpegSubsamp); 406 407 /** 408 * Returns the size of the buffer (in bytes) required to hold a YUV planar 409 * image with the given width, height, and level of chrominance subsampling. 410 * 411 * @param width the width (in pixels) of the YUV image 412 * 413 * @param pad the width of each line in each plane of the image is padded to 414 * the nearest multiple of this number of bytes (must be a power of 2.) 415 * 416 * @param height the height (in pixels) of the YUV image 417 * 418 * @param subsamp the level of chrominance subsampling used in the YUV 419 * image (one of {@link TJ TJ.SAMP_*}) 420 * 421 * @return the size of the buffer (in bytes) required to hold a YUV planar 422 * image with the given width, height, and level of chrominance subsampling. 423 */ 424 public static native int bufSizeYUV(int width, int pad, int height, 425 int subsamp); 426 427 /** 428 * @deprecated Use {@link #bufSizeYUV(int, int, int, int)} instead. 429 */ 430 @Deprecated 431 public static native int bufSizeYUV(int width, int height, int subsamp); 432 433 /** 434 * Returns the size of the buffer (in bytes) required to hold a YUV image 435 * plane with the given parameters. 436 * 437 * @param componentID ID number of the image plane (0 = Y, 1 = U/Cb, 438 * 2 = V/Cr) 439 * 440 * @param width width (in pixels) of the YUV image. NOTE: this is the width 441 * of the whole image, not the plane width. 442 * 443 * @param stride bytes per line in the image plane. 444 * 445 * @param height height (in pixels) of the YUV image. NOTE: this is the 446 * height of the whole image, not the plane height. 447 * 448 * @param subsamp the level of chrominance subsampling used in the YUV 449 * image (one of {@link TJ TJ.SAMP_*}) 450 * 451 * @return the size of the buffer (in bytes) required to hold a YUV planar 452 * image with the given parameters. 453 */ 454 public static native int planeSizeYUV(int componentID, int width, int stride, 455 int height, int subsamp); 456 457 /** 458 * Returns the plane width of a YUV image plane with the given parameters. 459 * Refer to {@link YUVImage YUVImage} for a description of plane width. 460 * 461 * @param componentID ID number of the image plane (0 = Y, 1 = U/Cb, 462 * 2 = V/Cr) 463 * 464 * @param width width (in pixels) of the YUV image 465 * 466 * @param subsamp the level of chrominance subsampling used in the YUV image 467 * (one of {@link TJ TJ.SAMP_*}) 468 * 469 * @return the plane width of a YUV image plane with the given parameters. 470 */ 471 public static native int planeWidth(int componentID, int width, int subsamp); 472 473 /** 474 * Returns the plane height of a YUV image plane with the given parameters. 475 * Refer to {@link YUVImage YUVImage} for a description of plane height. 476 * 477 * @param componentID ID number of the image plane (0 = Y, 1 = U/Cb, 478 * 2 = V/Cr) 479 * 480 * @param height height (in pixels) of the YUV image 481 * 482 * @param subsamp the level of chrominance subsampling used in the YUV image 483 * (one of {@link TJ TJ.SAMP_*}) 484 * 485 * @return the plane height of a YUV image plane with the given parameters. 486 */ 487 public static native int planeHeight(int componentID, int height, 488 int subsamp); 489 490 /** 491 * Returns a list of fractional scaling factors that the JPEG decompressor in 492 * this implementation of TurboJPEG supports. 493 * 494 * @return a list of fractional scaling factors that the JPEG decompressor in 495 * this implementation of TurboJPEG supports. 496 */ 497 public static native TJScalingFactor[] getScalingFactors(); 498 499 static { 500 TJLoader.load(); 501 } 502 503 private static void checkPixelFormat(int pixelFormat) { 504 if (pixelFormat < 0 || pixelFormat >= NUMPF) 505 throw new IllegalArgumentException("Invalid pixel format"); 506 } 507 508 private static void checkSubsampling(int subsamp) { 509 if (subsamp < 0 || subsamp >= NUMSAMP) 510 throw new IllegalArgumentException("Invalid subsampling type"); 511 } 512 513 } 514
