/*

 * Copyright (C)2014, 2017 D. R. Commander.  All Rights Reserved.

 * Copyright (C)2015 Viktor Szathmรกry.  All Rights Reserved.

 *

 * Redistribution and use in source and binary forms, with or without

 * modification, are permitted provided that the following conditions are met:

 *

 * - Redistributions of source code must retain the above copyright notice,

 *   this list of conditions and the following disclaimer.

 * - Redistributions in binary form must reproduce the above copyright notice,

 *   this list of conditions and the following disclaimer in the documentation

 *   and/or other materials provided with the distribution.

 * - Neither the name of the libjpeg-turbo Project nor the names of its

 *   contributors may be used to endorse or promote products derived from this

 *   software without specific prior written permission.

 *

 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS",

 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

 * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE

 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR

 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF

 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS

 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN

 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)

 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE

 * POSSIBILITY OF SUCH DAMAGE.

 */

package org.libjpegturbo.turbojpeg;

/**

 * This class encapsulates a YUV planar image and the metadata

 * associated with it.  The TurboJPEG API allows both the JPEG compression and

 * decompression pipelines to be split into stages:  YUV encode, compress from

 * YUV, decompress to YUV, and YUV decode.  A YUVImage instance

 * serves as the destination image for YUV encode and decompress-to-YUV

 * operations and as the source image for compress-from-YUV and YUV decode

 * operations.

 * 

 * Technically, the JPEG format uses the YCbCr colorspace (which technically is

 * not a "colorspace" but rather a "color transform"), but per the convention

 * of the digital video community, the TurboJPEG API uses "YUV" to refer to an

 * image format consisting of Y, Cb, and Cr image planes.

 * 

 * Each plane is simply a 2D array of bytes, each byte representing the value

 * of one of the components (Y, Cb, or Cr) at a particular location in the

 * image.  The width and height of each plane are determined by the image

 * width, height, and level of chrominance subsampling.  The luminance plane

 * width is the image width padded to the nearest multiple of the horizontal

 * subsampling factor (2 in the case of 4:2:0 and 4:2:2, 4 in the case of

 * 4:1:1, 1 in the case of 4:4:4 or grayscale.)  Similarly, the luminance plane

 * height is the image height padded to the nearest multiple of the vertical

 * subsampling factor (2 in the case of 4:2:0 or 4:4:0, 1 in the case of 4:4:4

 * or grayscale.)  The chrominance plane width is equal to the luminance plane

 * width divided by the horizontal subsampling factor, and the chrominance

 * plane height is equal to the luminance plane height divided by the vertical

 * subsampling factor.

 * 

 * For example, if the source image is 35 x 35 pixels and 4:2:2 subsampling is

 * used, then the luminance plane would be 36 x 35 bytes, and each of the

 * chrominance planes would be 18 x 35 bytes.  If you specify a line padding of

 * 4 bytes on top of this, then the luminance plane would be 36 x 35 bytes, and

 * each of the chrominance planes would be 20 x 35 bytes.

 */

public class YUVImage {

  private static final String NO_ASSOC_ERROR =

    "No image data is associated with this instance";

  /**

   * Create a new YUVImage instance backed by separate image

   * planes, and allocate memory for the image planes.

   *

   * @param width width (in pixels) of the YUV image

   *

   * @param strides an array of integers, each specifying the number of bytes

   * per line in the corresponding plane of the YUV image.  Setting the stride

   * for any plane to 0 is the same as setting it to the plane width (see

   * {@link YUVImage above}.)  If strides is null, then the

   * strides for all planes will be set to their respective plane widths.  When

   * using this constructor, the stride for each plane must be equal to or

   * greater than the plane width.

   *

   * @param height height (in pixels) of the YUV image

   *

   * @param subsamp the level of chrominance subsampling to be used in the YUV

   * image (one of {@link TJ#SAMP_444 TJ.SAMP_*})

   */

  public YUVImage(int width, int[] strides, int height, int subsamp) {

    setBuf(null, null, width, strides, height, subsamp, true);

  }

  /**

   * Create a new YUVImage instance backed by a unified image

   * buffer, and allocate memory for the image buffer.

   *

   * @param width width (in pixels) of the YUV image

   *

   * @param pad Each line of each plane in the YUV image buffer will be padded

   * to this number of bytes (must be a power of 2.)

   *

   * @param height height (in pixels) of the YUV image

   *

   * @param subsamp the level of chrominance subsampling to be used in the YUV

   * image (one of {@link TJ#SAMP_444 TJ.SAMP_*})

   */

  public YUVImage(int width, int pad, int height, int subsamp) {

    setBuf(new byte[TJ.bufSizeYUV(width, pad, height, subsamp)], width, pad,

           height, subsamp);

  }

  /**

   * Create a new YUVImage instance from a set of existing image

   * planes.

   *

   * @param planes an array of buffers representing the Y, U (Cb), and V (Cr)

   * image planes (or just the Y plane, if the image is grayscale.)   These

   * planes can be contiguous or non-contiguous in memory.  Plane

   * i should be at least offsets[i] +

   * {@link TJ#planeSizeYUV TJ.planeSizeYUV}(i, width, strides[i], height, subsamp)

   * bytes in size.

   *

   * @param offsets If this YUVImage instance represents a

   * subregion of a larger image, then offsets[i] specifies the

   * offset (in bytes) of the subregion within plane i of the

   * larger image.  Setting this to null is the same as setting the offsets for

   * all planes to 0.

   *

   * @param width width (in pixels) of the new YUV image (or subregion)

   *

   * @param strides an array of integers, each specifying the number of bytes

   * per line in the corresponding plane of the YUV image.  Setting the stride

   * for any plane to 0 is the same as setting it to the plane width (see

   * {@link YUVImage above}.)  If strides is null, then the

   * strides for all planes will be set to their respective plane widths.  You

   * can adjust the strides in order to add an arbitrary amount of line padding

   * to each plane or to specify that this YUVImage instance is a

   * subregion of a larger image (in which case, strides[i] should

   * be set to the plane width of plane i in the larger image.)

   *

   * @param height height (in pixels) of the new YUV image (or subregion)

   *

   * @param subsamp the level of chrominance subsampling used in the YUV

   * image (one of {@link TJ#SAMP_444 TJ.SAMP_*})

   */

  public YUVImage(byte[][] planes, int[] offsets, int width, int[] strides,

                  int height, int subsamp) {

    setBuf(planes, offsets, width, strides, height, subsamp, false);

  }

  /**

   * Create a new YUVImage instance from an existing unified image

   * buffer.

   *

   * @param yuvImage image buffer that contains or will contain YUV planar

   * image data.  Use {@link TJ#bufSizeYUV} to determine the minimum size for

   * this buffer.  The Y, U (Cb), and V (Cr) image planes are stored

   * sequentially in the buffer (see {@link YUVImage above} for a description

   * of the image format.)

   *

   * @param width width (in pixels) of the YUV image

   *

   * @param pad the line padding used in the YUV image buffer.  For

   * instance, if each line in each plane of the buffer is padded to the

   * nearest multiple of 4 bytes, then pad should be set to 4.

   *

   * @param height height (in pixels) of the YUV image

   *

   * @param subsamp the level of chrominance subsampling used in the YUV

   * image (one of {@link TJ#SAMP_444 TJ.SAMP_*})

   */

  public YUVImage(byte[] yuvImage, int width, int pad, int height,

                  int subsamp) {

    setBuf(yuvImage, width, pad, height, subsamp);

  }

  /**

   * Assign a set of image planes to this YUVImage instance.

   *

   * @param planes an array of buffers representing the Y, U (Cb), and V (Cr)

   * image planes (or just the Y plane, if the image is grayscale.)  These

   * planes can be contiguous or non-contiguous in memory.  Plane

   * i should be at least offsets[i] +

   * {@link TJ#planeSizeYUV TJ.planeSizeYUV}(i, width, strides[i], height, subsamp)

   * bytes in size.

   *

   * @param offsets If this YUVImage instance represents a

   * subregion of a larger image, then offsets[i] specifies the

   * offset (in bytes) of the subregion within plane i of the

   * larger image.  Setting this to null is the same as setting the offsets for

   * all planes to 0.

   *

   * @param width width (in pixels) of the YUV image (or subregion)

   *

   * @param strides an array of integers, each specifying the number of bytes

   * per line in the corresponding plane of the YUV image.  Setting the stride

   * for any plane to 0 is the same as setting it to the plane width (see

   * {@link YUVImage above}.)  If strides is null, then the

   * strides for all planes will be set to their respective plane widths.  You

   * can adjust the strides in order to add an arbitrary amount of line padding

   * to each plane or to specify that this YUVImage image is a

   * subregion of a larger image (in which case, strides[i] should

   * be set to the plane width of plane i in the larger image.)

   *

   * @param height height (in pixels) of the YUV image (or subregion)

   *

   * @param subsamp the level of chrominance subsampling used in the YUV

   * image (one of {@link TJ#SAMP_444 TJ.SAMP_*})

   */

  public void setBuf(byte[][] planes, int[] offsets, int width, int[] strides,

                     int height, int subsamp) {

    setBuf(planes, offsets, width, strides, height, subsamp, false);

  }

  private void setBuf(byte[][] planes, int[] offsets, int width, int[] strides,

                     int height, int subsamp, boolean alloc) {

    if ((planes == null && !alloc) || width < 1 || height < 1 || subsamp < 0 ||

        subsamp >= TJ.NUMSAMP)

      throw new IllegalArgumentException("Invalid argument in YUVImage::setBuf()");

    int nc = (subsamp == TJ.SAMP_GRAY ? 1 : 3);

    if ((planes != null && planes.length != nc) ||

        (offsets != null && offsets.length != nc) ||

        (strides != null && strides.length != nc))

      throw new IllegalArgumentException("YUVImage::setBuf(): planes, offsets, or strides array is the wrong size");

    if (planes == null)

      planes = new byte[nc][];

    if (offsets == null)

      offsets = new int[nc];

    if (strides == null)

      strides = new int[nc];

    for (int i = 0; i < nc; i++) {

      int pw = TJ.planeWidth(i, width, subsamp);

      int ph = TJ.planeHeight(i, height, subsamp);

      int planeSize = TJ.planeSizeYUV(i, width, strides[i], height, subsamp);

      if (strides[i] == 0)

        strides[i] = pw;

      if (alloc) {

        if (strides[i] < pw)

          throw new IllegalArgumentException("Stride must be >= plane width when allocating a new YUV image");

        planes[i] = new byte[strides[i] * ph];

      }

      if (planes[i] == null || offsets[i] < 0)

        throw new IllegalArgumentException("Invalid argument in YUVImage::setBuf()");

      if (strides[i] < 0 && offsets[i] - planeSize + pw < 0)

        throw new IllegalArgumentException("Stride for plane " + i +

                                           " would cause memory to be accessed below plane boundary");

      if (planes[i].length < offsets[i] + planeSize)

        throw new IllegalArgumentException("Image plane " + i +

                                           " is not large enough");

    }

    yuvPlanes = planes;

    yuvOffsets = offsets;

    yuvWidth = width;

    yuvStrides = strides;

    yuvHeight = height;

    yuvSubsamp = subsamp;

  }

  /**

   * Assign a unified image buffer to this YUVImage instance.

   *

   * @param yuvImage image buffer that contains or will contain YUV planar

   * image data.  Use {@link TJ#bufSizeYUV} to determine the minimum size for

   * this buffer.  The Y, U (Cb), and V (Cr) image planes are stored

   * sequentially in the buffer (see {@link YUVImage above} for a description

   * of the image format.)

   *

   * @param width width (in pixels) of the YUV image

   *

   * @param pad the line padding used in the YUV image buffer.  For

   * instance, if each line in each plane of the buffer is padded to the

   * nearest multiple of 4 bytes, then pad should be set to 4.

   *

   * @param height height (in pixels) of the YUV image

   *

   * @param subsamp the level of chrominance subsampling used in the YUV

   * image (one of {@link TJ#SAMP_444 TJ.SAMP_*})

   */

  public void setBuf(byte[] yuvImage, int width, int pad, int height,

                     int subsamp) {

    if (yuvImage == null || width < 1 || pad < 1 || ((pad & (pad - 1)) != 0) ||

        height < 1 || subsamp < 0 || subsamp >= TJ.NUMSAMP)

      throw new IllegalArgumentException("Invalid argument in YUVImage::setBuf()");

    if (yuvImage.length < TJ.bufSizeYUV(width, pad, height, subsamp))

      throw new IllegalArgumentException("YUV image buffer is not large enough");

    int nc = (subsamp == TJ.SAMP_GRAY ? 1 : 3);

    byte[][] planes = new byte[nc][];

    int[] strides = new int[nc];

    int[] offsets = new int[nc];

    planes[0] = yuvImage;

    strides[0] = pad(TJ.planeWidth(0, width, subsamp), pad);

    if (subsamp != TJ.SAMP_GRAY) {

      strides[1] = strides[2] = pad(TJ.planeWidth(1, width, subsamp), pad);

      planes[1] = planes[2] = yuvImage;

      offsets[1] = offsets[0] +

        strides[0] * TJ.planeHeight(0, height, subsamp);

      offsets[2] = offsets[1] +

        strides[1] * TJ.planeHeight(1, height, subsamp);

    }

    yuvPad = pad;

    setBuf(planes, offsets, width, strides, height, subsamp);

  }

  /**

   * Returns the width of the YUV image (or subregion.)

   *

   * @return the width of the YUV image (or subregion)

   */

  public int getWidth() {

    if (yuvWidth < 1)

      throw new IllegalStateException(NO_ASSOC_ERROR);

    return yuvWidth;

  }

  /**

   * Returns the height of the YUV image (or subregion.)

   *

   * @return the height of the YUV image (or subregion)

   */

  public int getHeight() {

    if (yuvHeight < 1)

      throw new IllegalStateException(NO_ASSOC_ERROR);

    return yuvHeight;

  }

  /**

   * Returns the line padding used in the YUV image buffer (if this image is

   * stored in a unified buffer rather than separate image planes.)

   *

   * @return the line padding used in the YUV image buffer

   */

  public int getPad() {

    if (yuvPlanes == null)

      throw new IllegalStateException(NO_ASSOC_ERROR);

    if (yuvPad < 1 || ((yuvPad & (yuvPad - 1)) != 0))

      throw new IllegalStateException("Image is not stored in a unified buffer");

    return yuvPad;

  }

  /**

   * Returns the number of bytes per line of each plane in the YUV image.

   *

   * @return the number of bytes per line of each plane in the YUV image

   */

  public int[] getStrides() {

    if (yuvStrides == null)

      throw new IllegalStateException(NO_ASSOC_ERROR);

    return yuvStrides;

  }

  /**

   * Returns the offsets (in bytes) of each plane within the planes of a larger

   * YUV image.

   *

   * @return the offsets (in bytes) of each plane within the planes of a larger

   * YUV image

   */

  public int[] getOffsets() {

    if (yuvOffsets == null)

      throw new IllegalStateException(NO_ASSOC_ERROR);

    return yuvOffsets;

  }

  /**

   * Returns the level of chrominance subsampling used in the YUV image.  See

   * {@link TJ#SAMP_444 TJ.SAMP_*}.

   *

   * @return the level of chrominance subsampling used in the YUV image

   */

  public int getSubsamp() {

    if (yuvSubsamp < 0 || yuvSubsamp >= TJ.NUMSAMP)

      throw new IllegalStateException(NO_ASSOC_ERROR);

    return yuvSubsamp;

  }

  /**

   * Returns the YUV image planes.  If the image is stored in a unified buffer,

   * then all image planes will point to that buffer.

   *

   * @return the YUV image planes

   */

  public byte[][] getPlanes() {

    if (yuvPlanes == null)

      throw new IllegalStateException(NO_ASSOC_ERROR);

    return yuvPlanes;

  }

  /**

   * Returns the YUV image buffer (if this image is stored in a unified

   * buffer rather than separate image planes.)

   *

   * @return the YUV image buffer

   */

  public byte[] getBuf() {

    if (yuvPlanes == null || yuvSubsamp < 0 || yuvSubsamp >= TJ.NUMSAMP)

      throw new IllegalStateException(NO_ASSOC_ERROR);

    int nc = (yuvSubsamp == TJ.SAMP_GRAY ? 1 : 3);

    for (int i = 1; i < nc; i++) {

      if (yuvPlanes[i] != yuvPlanes[0])

        throw new IllegalStateException("Image is not stored in a unified buffer");

    }

    return yuvPlanes[0];

  }

  /**

   * Returns the size (in bytes) of the YUV image buffer (if this image is

   * stored in a unified buffer rather than separate image planes.)

   *

   * @return the size (in bytes) of the YUV image buffer

   */

  public int getSize() {

    if (yuvPlanes == null || yuvSubsamp < 0 || yuvSubsamp >= TJ.NUMSAMP)

      throw new IllegalStateException(NO_ASSOC_ERROR);

    int nc = (yuvSubsamp == TJ.SAMP_GRAY ? 1 : 3);

    if (yuvPad < 1)

      throw new IllegalStateException("Image is not stored in a unified buffer");

    for (int i = 1; i < nc; i++) {

      if (yuvPlanes[i] != yuvPlanes[0])

        throw new IllegalStateException("Image is not stored in a unified buffer");

    }

    return TJ.bufSizeYUV(yuvWidth, yuvPad, yuvHeight, yuvSubsamp);

  }

  private static int pad(int v, int p) {

    return (v + p - 1) & (~(p - 1));

  }

  protected long handle = 0;

  protected byte[][] yuvPlanes = null;

  protected int[] yuvOffsets = null;

  protected int[] yuvStrides = null;

  protected int yuvPad = 0;

  protected int yuvWidth = 0;

  protected int yuvHeight = 0;

  protected int yuvSubsamp = -1;

}