Class YUVImage
- java.lang.Object
-
- org.libjpegturbo.turbojpeg.YUVImage
-
public class YUVImage extends java.lang.Object
This class encapsulates a planar YUV 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. AYUVImage
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 is technically not a colorspace but 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 (1 in the case of 4:4:4, grayscale, 4:4:0, or 4:4:1; 2 in the case of 4:2:2 or 4:2:0; 4 in the case of 4:1:1.) Similarly, the luminance plane height is the image height padded to the nearest multiple of the vertical subsampling factor (1 in the case of 4:4:4, 4:2:2, grayscale, 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 irrespective of any additional padding that may be specified as an argument to the various YUVImage methods. 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 row alignment 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.
-
-
Constructor Summary
Constructors Constructor Description YUVImage(byte[][] planes, int[] offsets, int width, int[] strides, int height, int subsamp)
Create a newYUVImage
instance from a set of existing image planes.YUVImage(byte[] yuvImage, int width, int align, int height, int subsamp)
Create a newYUVImage
instance from an existing unified buffer.YUVImage(int width, int[] strides, int height, int subsamp)
Create a newYUVImage
instance backed by separate image planes, and allocate memory for the image planes.YUVImage(int width, int align, int height, int subsamp)
Create a newYUVImage
instance backed by a unified buffer, and allocate memory for the buffer.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description byte[]
getBuf()
Returns the YUV buffer (if this image is stored in a unified buffer rather than separate image planes.)int
getHeight()
Returns the height of the YUV image (or subregion.)int[]
getOffsets()
Returns the offsets (in bytes) of each plane within the planes of a larger YUV image.int
getPad()
Returns the row alignment (in bytes) of the YUV buffer (if this image is stored in a unified buffer rather than separate image planes.)byte[][]
getPlanes()
Returns the YUV image planes.int
getSize()
Returns the size (in bytes) of the YUV buffer (if this image is stored in a unified buffer rather than separate image planes.)int[]
getStrides()
Returns the number of bytes per row of each plane in the YUV image.int
getSubsamp()
Returns the level of chrominance subsampling used in the YUV image.int
getWidth()
Returns the width of the YUV image (or subregion.)void
setBuf(byte[][] planes, int[] offsets, int width, int[] strides, int height, int subsamp)
Assign a set of image planes to thisYUVImage
instance.void
setBuf(byte[] yuvImage, int width, int align, int height, int subsamp)
Assign a unified buffer to thisYUVImage
instance.
-
-
-
Constructor Detail
-
YUVImage
public YUVImage(int width, int[] strides, int height, int subsamp)
Create a newYUVImage
instance backed by separate image planes, and allocate memory for the image planes.- Parameters:
width
- width (in pixels) of the YUV imagestrides
- an array of integers, each specifying the number of bytes per row 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 (seeabove
.) Ifstrides
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.height
- height (in pixels) of the YUV imagesubsamp
- the level of chrominance subsampling to be used in the YUV image (one ofTJ.SAMP_*
)
-
YUVImage
public YUVImage(int width, int align, int height, int subsamp)
Create a newYUVImage
instance backed by a unified buffer, and allocate memory for the buffer.- Parameters:
width
- width (in pixels) of the YUV imagealign
- row alignment (in bytes) of the YUV image (must be a power of 2.) Setting this parameter to n specifies that each row in each plane of the YUV image will be padded to the nearest multiple of n bytes (1 = unpadded.)height
- height (in pixels) of the YUV imagesubsamp
- the level of chrominance subsampling to be used in the YUV image (one ofTJ.SAMP_*
)
-
YUVImage
public YUVImage(byte[][] planes, int[] offsets, int width, int[] strides, int height, int subsamp)
Create a newYUVImage
instance from a set of existing image planes.- Parameters:
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. Planei
should be at leastoffsets[i] +
bytes in size.TJ.planeSizeYUV
(i, width, strides[i], height, subsamp)offsets
- If thisYUVImage
instance represents a subregion of a larger image, thenoffsets[i]
specifies the offset (in bytes) of the subregion within planei
of the larger image. Setting this to null is the same as setting the offsets for all planes to 0.width
- width (in pixels) of the new YUV image (or subregion)strides
- an array of integers, each specifying the number of bytes per row 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 (seeabove
.) Ifstrides
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 row padding to each plane or to specify that thisYUVImage
instance is a subregion of a larger image (in which case,strides[i]
should be set to the plane width of planei
in the larger image.)height
- height (in pixels) of the new YUV image (or subregion)subsamp
- the level of chrominance subsampling used in the YUV image (one ofTJ.SAMP_*
)
-
YUVImage
public YUVImage(byte[] yuvImage, int width, int align, int height, int subsamp)
Create a newYUVImage
instance from an existing unified buffer.- Parameters:
yuvImage
- buffer that contains or will receive a unified planar YUV image. UseTJ.bufSizeYUV()
to determine the minimum size for this buffer. The Y, U (Cb), and V (Cr) image planes are stored sequentially in the buffer. (Seeabove
for a description of the image format.)width
- width (in pixels) of the YUV imagealign
- row alignment (in bytes) of the YUV image (must be a power of 2.) Setting this parameter to n specifies that each row in each plane of the YUV image will be padded to the nearest multiple of n bytes (1 = unpadded.)height
- height (in pixels) of the YUV imagesubsamp
- the level of chrominance subsampling used in the YUV image (one ofTJ.SAMP_*
)
-
-
Method Detail
-
setBuf
public void setBuf(byte[][] planes, int[] offsets, int width, int[] strides, int height, int subsamp)
Assign a set of image planes to thisYUVImage
instance.- Parameters:
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. Planei
should be at leastoffsets[i] +
bytes in size.TJ.planeSizeYUV
(i, width, strides[i], height, subsamp)offsets
- If thisYUVImage
instance represents a subregion of a larger image, thenoffsets[i]
specifies the offset (in bytes) of the subregion within planei
of the larger image. Setting this to null is the same as setting the offsets for all planes to 0.width
- width (in pixels) of the YUV image (or subregion)strides
- an array of integers, each specifying the number of bytes per row 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 (seeabove
.) Ifstrides
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 row padding to each plane or to specify that thisYUVImage
instance is a subregion of a larger image (in which case,strides[i]
should be set to the plane width of planei
in the larger image.)height
- height (in pixels) of the YUV image (or subregion)subsamp
- the level of chrominance subsampling used in the YUV image (one ofTJ.SAMP_*
)
-
setBuf
public void setBuf(byte[] yuvImage, int width, int align, int height, int subsamp)
Assign a unified buffer to thisYUVImage
instance.- Parameters:
yuvImage
- buffer that contains or will receive a unified planar YUV image. UseTJ.bufSizeYUV()
to determine the minimum size for this buffer. The Y, U (Cb), and V (Cr) image planes are stored sequentially in the buffer. (Seeabove
for a description of the image format.)width
- width (in pixels) of the YUV imagealign
- row alignment (in bytes) of the YUV image (must be a power of 2.) Setting this parameter to n specifies that each row in each plane of the YUV image will be padded to the nearest multiple of n bytes (1 = unpadded.)height
- height (in pixels) of the YUV imagesubsamp
- the level of chrominance subsampling used in the YUV image (one ofTJ.SAMP_*
)
-
getWidth
public int getWidth()
Returns the width of the YUV image (or subregion.)- Returns:
- the width of the YUV image (or subregion)
-
getHeight
public int getHeight()
Returns the height of the YUV image (or subregion.)- Returns:
- the height of the YUV image (or subregion)
-
getPad
public int getPad()
Returns the row alignment (in bytes) of the YUV buffer (if this image is stored in a unified buffer rather than separate image planes.)- Returns:
- the row alignment of the YUV buffer
-
getStrides
public int[] getStrides()
Returns the number of bytes per row of each plane in the YUV image.- Returns:
- the number of bytes per row of each plane in the YUV image
-
getOffsets
public int[] getOffsets()
Returns the offsets (in bytes) of each plane within the planes of a larger YUV image.- Returns:
- the offsets (in bytes) of each plane within the planes of a larger YUV image
-
getSubsamp
public int getSubsamp()
Returns the level of chrominance subsampling used in the YUV image. SeeTJ.SAMP_*
.- Returns:
- the level of chrominance subsampling used in the YUV image
-
getPlanes
public byte[][] getPlanes()
Returns the YUV image planes. If the image is stored in a unified buffer, then all image planes will point to that buffer.- Returns:
- the YUV image planes
-
getBuf
public byte[] getBuf()
Returns the YUV buffer (if this image is stored in a unified buffer rather than separate image planes.)- Returns:
- the YUV buffer
-
getSize
public int getSize()
Returns the size (in bytes) of the YUV buffer (if this image is stored in a unified buffer rather than separate image planes.)- Returns:
- the size (in bytes) of the YUV buffer
-
-