java/org/libjpegturbo/turbojpeg/YUVImage.java

   1 /*
   2  * Copyright (C)2014, 2017, 2023 D. R. Commander.  All Rights Reserved.
   3  * Copyright (C)2015 Viktor Szathmáry.  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  * This class encapsulates a planar YUV image and the metadata
  34  * associated with it.  The TurboJPEG API allows both the JPEG compression and
  35  * decompression pipelines to be split into stages:  YUV encode, compress from
  36  * YUV, decompress to YUV, and YUV decode.  A <code>YUVImage</code> instance
  37  * serves as the destination image for YUV encode and decompress-to-YUV
  38  * operations and as the source image for compress-from-YUV and YUV decode
  39  * operations.
  40  * <p>
  41  * Technically, the JPEG format uses the YCbCr colorspace (which is technically
  42  * not a colorspace but a color transform), but per the convention of the
  43  * digital video community, the TurboJPEG API uses "YUV" to refer to an image
  44  * format consisting of Y, Cb, and Cr image planes.
  45  * <p>
  46  * Each plane is simply a 2D array of bytes, each byte representing the value
  47  * of one of the components (Y, Cb, or Cr) at a particular location in the
  48  * image.  The width and height of each plane are determined by the image
  49  * width, height, and level of chrominance subsampling.  The luminance plane
  50  * width is the image width padded to the nearest multiple of the horizontal
  51  * subsampling factor (1 in the case of 4:4:4, grayscale, 4:4:0, or 4:4:1; 2 in
  52  * the case of 4:2:2 or 4:2:0; 4 in the case of 4:1:1.)  Similarly, the
  53  * luminance plane height is the image height padded to the nearest multiple of
  54  * the vertical subsampling factor (1 in the case of 4:4:4, 4:2:2, grayscale,
  55  * or 4:1:1; 2 in the case of 4:2:0 or 4:4:0; 4 in the case of 4:4:1.)  This is
  56  * irrespective of any additional padding that may be specified as an argument
  57  * to the various YUVImage methods.  The chrominance plane width is equal to
  58  * the luminance plane width divided by the horizontal subsampling factor, and
  59  * the chrominance plane height is equal to the luminance plane height divided
  60  * by the vertical subsampling factor.
  61  * <p>
  62  * For example, if the source image is 35 x 35 pixels and 4:2:2 subsampling is
  63  * used, then the luminance plane would be 36 x 35 bytes, and each of the
  64  * chrominance planes would be 18 x 35 bytes.  If you specify a row alignment
  65  * of 4 bytes on top of this, then the luminance plane would be 36 x 35 bytes,
  66  * and each of the chrominance planes would be 20 x 35 bytes.
  67  */
  68 public class YUVImage {
  69
  70   private static final String NO_ASSOC_ERROR =
  71     "No image data is associated with this instance";
  72
  73   /**
  74    * Create a new <code>YUVImage</code> instance backed by separate image
  75    * planes, and allocate memory for the image planes.
  76    *
  77    * @param width width (in pixels) of the YUV image
  78    *
  79    * @param strides an array of integers, each specifying the number of bytes
  80    * per row in the corresponding plane of the YUV image.  Setting the stride
  81    * for any plane to 0 is the same as setting it to the plane width (see
  82    * {@link YUVImage above}.)  If <code>strides</code> is null, then the
  83    * strides for all planes will be set to their respective plane widths.  When
  84    * using this constructor, the stride for each plane must be equal to or
  85    * greater than the plane width.
  86    *
  87    * @param height height (in pixels) of the YUV image
  88    *
  89    * @param subsamp the level of chrominance subsampling to be used in the YUV
  90    * image (one of {@link TJ#SAMP_444 TJ.SAMP_*})
  91    */
  92   public YUVImage(int width, int[] strides, int height, int subsamp) {
  93     setBuf(null, null, width, strides, height, subsamp, true);
  94   }
  95
  96   /**
  97    * Create a new <code>YUVImage</code> instance backed by a unified buffer,
  98    * and allocate memory for the buffer.
  99    *
 100    * @param width width (in pixels) of the YUV image
 101    *
 102    * @param align row alignment (in bytes) of the YUV image (must be a power of
 103    * 2.)  Setting this parameter to n specifies that each row in each plane of
 104    * the YUV image will be padded to the nearest multiple of n bytes
 105    * (1 = unpadded.)
 106    *
 107    * @param height height (in pixels) of the YUV image
 108    *
 109    * @param subsamp the level of chrominance subsampling to be used in the YUV
 110    * image (one of {@link TJ#SAMP_444 TJ.SAMP_*})
 111    */
 112   public YUVImage(int width, int align, int height, int subsamp) {
 113     setBuf(new byte[TJ.bufSizeYUV(width, align, height, subsamp)], width,
 114            align, height, subsamp);
 115   }
 116
 117   /**
 118    * Create a new <code>YUVImage</code> instance from a set of existing image
 119    * planes.
 120    *
 121    * @param planes an array of buffers representing the Y, U (Cb), and V (Cr)
 122    * image planes (or just the Y plane, if the image is grayscale.)   These
 123    * planes can be contiguous or non-contiguous in memory.  Plane
 124    * <code>i</code> should be at least <code>offsets[i] +
 125    * {@link TJ#planeSizeYUV TJ.planeSizeYUV}(i, width, strides[i], height, subsamp)</code>
 126    * bytes in size.
 127    *
 128    * @param offsets If this <code>YUVImage</code> instance represents a
 129    * subregion of a larger image, then <code>offsets[i]</code> specifies the
 130    * offset (in bytes) of the subregion within plane <code>i</code> of the
 131    * larger image.  Setting this to null is the same as setting the offsets for
 132    * all planes to 0.
 133    *
 134    * @param width width (in pixels) of the new YUV image (or subregion)
 135    *
 136    * @param strides an array of integers, each specifying the number of bytes
 137    * per row in the corresponding plane of the YUV image.  Setting the stride
 138    * for any plane to 0 is the same as setting it to the plane width (see
 139    * {@link YUVImage above}.)  If <code>strides</code> is null, then the
 140    * strides for all planes will be set to their respective plane widths.  You
 141    * can adjust the strides in order to add an arbitrary amount of row padding
 142    * to each plane or to specify that this <code>YUVImage</code> instance is a
 143    * subregion of a larger image (in which case, <code>strides[i]</code> should
 144    * be set to the plane width of plane <code>i</code> in the larger image.)
 145    *
 146    * @param height height (in pixels) of the new YUV image (or subregion)
 147    *
 148    * @param subsamp the level of chrominance subsampling used in the YUV
 149    * image (one of {@link TJ#SAMP_444 TJ.SAMP_*})
 150    */
 151   public YUVImage(byte[][] planes, int[] offsets, int width, int[] strides,
 152                   int height, int subsamp) {
 153     setBuf(planes, offsets, width, strides, height, subsamp, false);
 154   }
 155
 156   /**
 157    * Create a new <code>YUVImage</code> instance from an existing unified
 158    * buffer.
 159    *
 160    * @param yuvImage buffer that contains or will receive a unified planar YUV
 161    * image.  Use {@link TJ#bufSizeYUV TJ.bufSizeYUV()} to determine the minimum
 162    * size for this buffer.  The Y, U (Cb), and V (Cr) image planes are stored
 163    * sequentially in the buffer.  (See {@link YUVImage above} for a description
 164    * of the image format.)
 165    *
 166    * @param width width (in pixels) of the YUV image
 167    *
 168    * @param align row alignment (in bytes) of the YUV image (must be a power of
 169    * 2.)  Setting this parameter to n specifies that each row in each plane of
 170    * the YUV image will be padded to the nearest multiple of n bytes
 171    * (1 = unpadded.)
 172    *
 173    * @param height height (in pixels) of the YUV image
 174    *
 175    * @param subsamp the level of chrominance subsampling used in the YUV
 176    * image (one of {@link TJ#SAMP_444 TJ.SAMP_*})
 177    */
 178   public YUVImage(byte[] yuvImage, int width, int align, int height,
 179                   int subsamp) {
 180     setBuf(yuvImage, width, align, height, subsamp);
 181   }
 182
 183   /**
 184    * Assign a set of image planes to this <code>YUVImage</code> instance.
 185    *
 186    * @param planes an array of buffers representing the Y, U (Cb), and V (Cr)
 187    * image planes (or just the Y plane, if the image is grayscale.)  These
 188    * planes can be contiguous or non-contiguous in memory.  Plane
 189    * <code>i</code> should be at least <code>offsets[i] +
 190    * {@link TJ#planeSizeYUV TJ.planeSizeYUV}(i, width, strides[i], height, subsamp)</code>
 191    * bytes in size.
 192    *
 193    * @param offsets If this <code>YUVImage</code> instance represents a
 194    * subregion of a larger image, then <code>offsets[i]</code> specifies the
 195    * offset (in bytes) of the subregion within plane <code>i</code> of the
 196    * larger image.  Setting this to null is the same as setting the offsets for
 197    * all planes to 0.
 198    *
 199    * @param width width (in pixels) of the YUV image (or subregion)
 200    *
 201    * @param strides an array of integers, each specifying the number of bytes
 202    * per row in the corresponding plane of the YUV image.  Setting the stride
 203    * for any plane to 0 is the same as setting it to the plane width (see
 204    * {@link YUVImage above}.)  If <code>strides</code> is null, then the
 205    * strides for all planes will be set to their respective plane widths.  You
 206    * can adjust the strides in order to add an arbitrary amount of row padding
 207    * to each plane or to specify that this <code>YUVImage</code> instance is a
 208    * subregion of a larger image (in which case, <code>strides[i]</code> should
 209    * be set to the plane width of plane <code>i</code> in the larger image.)
 210    *
 211    * @param height height (in pixels) of the YUV image (or subregion)
 212    *
 213    * @param subsamp the level of chrominance subsampling used in the YUV
 214    * image (one of {@link TJ#SAMP_444 TJ.SAMP_*})
 215    */
 216   public void setBuf(byte[][] planes, int[] offsets, int width, int[] strides,
 217                      int height, int subsamp) {
 218     setBuf(planes, offsets, width, strides, height, subsamp, false);
 219   }
 220
 221   private void setBuf(byte[][] planes, int[] offsets, int width, int[] strides,
 222                      int height, int subsamp, boolean alloc) {
 223     if ((planes == null && !alloc) || width < 1 || height < 1 || subsamp < 0 ||
 224         subsamp >= TJ.NUMSAMP)
 225       throw new IllegalArgumentException("Invalid argument in YUVImage::setBuf()");
 226
 227     int nc = (subsamp == TJ.SAMP_GRAY ? 1 : 3);
 228     if ((planes != null && planes.length != nc) ||
 229         (offsets != null && offsets.length != nc) ||
 230         (strides != null && strides.length != nc))
 231       throw new IllegalArgumentException("YUVImage::setBuf(): planes, offsets, or strides array is the wrong size");
 232
 233     if (planes == null)
 234       planes = new byte[nc][];
 235     if (offsets == null)
 236       offsets = new int[nc];
 237     if (strides == null)
 238       strides = new int[nc];
 239
 240     for (int i = 0; i < nc; i++) {
 241       int pw = TJ.planeWidth(i, width, subsamp);
 242       int ph = TJ.planeHeight(i, height, subsamp);
 243       int planeSize = TJ.planeSizeYUV(i, width, strides[i], height, subsamp);
 244
 245       if (strides[i] == 0)
 246         strides[i] = pw;
 247       if (alloc) {
 248         if (strides[i] < pw)
 249           throw new IllegalArgumentException("Stride must be >= plane width when allocating a new YUV image");
 250         planes[i] = new byte[strides[i] * ph];
 251       }
 252       if (planes[i] == null || offsets[i] < 0)
 253         throw new IllegalArgumentException("Invalid argument in YUVImage::setBuf()");
 254       if (strides[i] < 0 && offsets[i] - planeSize + pw < 0)
 255         throw new IllegalArgumentException("Stride for plane " + i +
 256                                            " would cause memory to be accessed below plane boundary");
 257       if (planes[i].length < offsets[i] + planeSize)
 258         throw new IllegalArgumentException("Image plane " + i +
 259                                            " is not large enough");
 260     }
 261
 262     yuvPlanes = planes;
 263     yuvOffsets = offsets;
 264     yuvWidth = width;
 265     yuvStrides = strides;
 266     yuvHeight = height;
 267     yuvSubsamp = subsamp;
 268   }
 269
 270   /**
 271    * Assign a unified buffer to this <code>YUVImage</code> instance.
 272    *
 273    * @param yuvImage buffer that contains or will receive a unified planar YUV
 274    * image.  Use {@link TJ#bufSizeYUV TJ.bufSizeYUV()} to determine the minimum
 275    * size for this buffer.  The Y, U (Cb), and V (Cr) image planes are stored
 276    * sequentially in the buffer.  (See {@link YUVImage above} for a description
 277    * of the image format.)
 278    *
 279    * @param width width (in pixels) of the YUV image
 280    *
 281    * @param align row alignment (in bytes) of the YUV image (must be a power of
 282    * 2.)  Setting this parameter to n specifies that each row in each plane of
 283    * the YUV image will be padded to the nearest multiple of n bytes
 284    * (1 = unpadded.)
 285    *
 286    * @param height height (in pixels) of the YUV image
 287    *
 288    * @param subsamp the level of chrominance subsampling used in the YUV
 289    * image (one of {@link TJ#SAMP_444 TJ.SAMP_*})
 290    */
 291   public void setBuf(byte[] yuvImage, int width, int align, int height,
 292                      int subsamp) {
 293     if (yuvImage == null || width < 1 || align < 1 ||
 294         ((align & (align - 1)) != 0) || height < 1 || subsamp < 0 ||
 295         subsamp >= TJ.NUMSAMP)
 296       throw new IllegalArgumentException("Invalid argument in YUVImage::setBuf()");
 297     if (yuvImage.length < TJ.bufSizeYUV(width, align, height, subsamp))
 298       throw new IllegalArgumentException("YUV buffer is not large enough");
 299
 300     int nc = (subsamp == TJ.SAMP_GRAY ? 1 : 3);
 301     byte[][] planes = new byte[nc][];
 302     int[] strides = new int[nc];
 303     int[] offsets = new int[nc];
 304
 305     planes[0] = yuvImage;
 306     strides[0] = pad(TJ.planeWidth(0, width, subsamp), align);
 307     if (subsamp != TJ.SAMP_GRAY) {
 308       strides[1] = strides[2] = pad(TJ.planeWidth(1, width, subsamp), align);
 309       planes[1] = planes[2] = yuvImage;
 310       offsets[1] = offsets[0] +
 311         strides[0] * TJ.planeHeight(0, height, subsamp);
 312       offsets[2] = offsets[1] +
 313         strides[1] * TJ.planeHeight(1, height, subsamp);
 314     }
 315
 316     yuvAlign = align;
 317     setBuf(planes, offsets, width, strides, height, subsamp);
 318   }
 319
 320   /**
 321    * Returns the width of the YUV image (or subregion.)
 322    *
 323    * @return the width of the YUV image (or subregion)
 324    */
 325   public int getWidth() {
 326     if (yuvWidth < 1)
 327       throw new IllegalStateException(NO_ASSOC_ERROR);
 328     return yuvWidth;
 329   }
 330
 331   /**
 332    * Returns the height of the YUV image (or subregion.)
 333    *
 334    * @return the height of the YUV image (or subregion)
 335    */
 336   public int getHeight() {
 337     if (yuvHeight < 1)
 338       throw new IllegalStateException(NO_ASSOC_ERROR);
 339     return yuvHeight;
 340   }
 341
 342   /**
 343    * Returns the row alignment (in bytes) of the YUV buffer (if this image is
 344    * stored in a unified buffer rather than separate image planes.)
 345    *
 346    * @return the row alignment of the YUV buffer
 347    */
 348   public int getPad() {
 349     if (yuvPlanes == null)
 350       throw new IllegalStateException(NO_ASSOC_ERROR);
 351     if (yuvAlign < 1 || ((yuvAlign & (yuvAlign - 1)) != 0))
 352       throw new IllegalStateException("Image is not stored in a unified buffer");
 353     return yuvAlign;
 354   }
 355
 356   /**
 357    * Returns the number of bytes per row of each plane in the YUV image.
 358    *
 359    * @return the number of bytes per row of each plane in the YUV image
 360    */
 361   public int[] getStrides() {
 362     if (yuvStrides == null)
 363       throw new IllegalStateException(NO_ASSOC_ERROR);
 364     return yuvStrides;
 365   }
 366
 367   /**
 368    * Returns the offsets (in bytes) of each plane within the planes of a larger
 369    * YUV image.
 370    *
 371    * @return the offsets (in bytes) of each plane within the planes of a larger
 372    * YUV image
 373    */
 374   public int[] getOffsets() {
 375     if (yuvOffsets == null)
 376       throw new IllegalStateException(NO_ASSOC_ERROR);
 377     return yuvOffsets;
 378   }
 379
 380   /**
 381    * Returns the level of chrominance subsampling used in the YUV image.  See
 382    * {@link TJ#SAMP_444 TJ.SAMP_*}.
 383    *
 384    * @return the level of chrominance subsampling used in the YUV image
 385    */
 386   public int getSubsamp() {
 387     if (yuvSubsamp < 0 || yuvSubsamp >= TJ.NUMSAMP)
 388       throw new IllegalStateException(NO_ASSOC_ERROR);
 389     return yuvSubsamp;
 390   }
 391
 392   /**
 393    * Returns the YUV image planes.  If the image is stored in a unified buffer,
 394    * then all image planes will point to that buffer.
 395    *
 396    * @return the YUV image planes
 397    */
 398   public byte[][] getPlanes() {
 399     if (yuvPlanes == null)
 400       throw new IllegalStateException(NO_ASSOC_ERROR);
 401     return yuvPlanes;
 402   }
 403
 404   /**
 405    * Returns the YUV buffer (if this image is stored in a unified buffer rather
 406    * than separate image planes.)
 407    *
 408    * @return the YUV buffer
 409    */
 410   public byte[] getBuf() {
 411     if (yuvPlanes == null || yuvSubsamp < 0 || yuvSubsamp >= TJ.NUMSAMP)
 412       throw new IllegalStateException(NO_ASSOC_ERROR);
 413     int nc = (yuvSubsamp == TJ.SAMP_GRAY ? 1 : 3);
 414     for (int i = 1; i < nc; i++) {
 415       if (yuvPlanes[i] != yuvPlanes[0])
 416         throw new IllegalStateException("Image is not stored in a unified buffer");
 417     }
 418     return yuvPlanes[0];
 419   }
 420
 421   /**
 422    * Returns the size (in bytes) of the YUV buffer (if this image is stored in
 423    * a unified buffer rather than separate image planes.)
 424    *
 425    * @return the size (in bytes) of the YUV buffer
 426    */
 427   public int getSize() {
 428     if (yuvPlanes == null || yuvSubsamp < 0 || yuvSubsamp >= TJ.NUMSAMP)
 429       throw new IllegalStateException(NO_ASSOC_ERROR);
 430     int nc = (yuvSubsamp == TJ.SAMP_GRAY ? 1 : 3);
 431     if (yuvAlign < 1)
 432       throw new IllegalStateException("Image is not stored in a unified buffer");
 433     for (int i = 1; i < nc; i++) {
 434       if (yuvPlanes[i] != yuvPlanes[0])
 435         throw new IllegalStateException("Image is not stored in a unified buffer");
 436     }
 437     return TJ.bufSizeYUV(yuvWidth, yuvAlign, yuvHeight, yuvSubsamp);
 438   }
 439
 440   private static int pad(int v, int p) {
 441     return (v + p - 1) & (~(p - 1));
 442   }
 443
 444   private long handle = 0;
 445   private byte[][] yuvPlanes = null;
 446   private int[] yuvOffsets = null;
 447   private int[] yuvStrides = null;
 448   private int yuvAlign = 1;
 449   private int yuvWidth = 0;
 450   private int yuvHeight = 0;
 451   private int yuvSubsamp = -1;
 452 }