From 7cf01068d01ad27a42b682b81e1829073f00680a Mon Sep 17 00:00:00 2001 From: dcommander Date: Sun, 17 Aug 2014 12:23:49 +0000 Subject: Refactored YUVImage Java class so that it supports both unified YUV image buffers as well as separate YUV image planes; modified the JNI functions accordingly and added new helper functions to the TurboJPEG C API (tjPlaneWidth(), tjPlaneHeight(), tjPlaneSizeYUV()) to facilitate those modifications; changed potentially confusing "component width" and "component height" terms to "plane width" and "plane height" and modified variable names in turbojpeg.c to reflect this; numerous other documentation tweaks git-svn-id: svn://svn.code.sf.net/p/libjpeg-turbo/code/trunk@1360 632fc199-4ca6-4c93-a231-07263d6284db --- java/doc/org/libjpegturbo/turbojpeg/YUVImage.html | 319 ++++++++++++++++++---- 1 file changed, 272 insertions(+), 47 deletions(-) (limited to 'java/doc/org/libjpegturbo/turbojpeg/YUVImage.html') diff --git a/java/doc/org/libjpegturbo/turbojpeg/YUVImage.html b/java/doc/org/libjpegturbo/turbojpeg/YUVImage.html index 3e7a6e8..0a3e0a5 100644 --- a/java/doc/org/libjpegturbo/turbojpeg/YUVImage.html +++ b/java/doc/org/libjpegturbo/turbojpeg/YUVImage.html @@ -108,20 +108,18 @@ extends java.lang.Object 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 at a particular location in the image. The - "component width" and "component height" of each plane are determined by the - image width, height, and level of chrominance subsampling. For the - luminance plane, the component 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 component height of the luminance plane 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 component width of the chrominance planes is equal to the - component width of the luminance plane divided by the horizontal subsampling - factor, and the component height of the chrominance planes is equal to the - component height of the luminance plane divided by the vertical subsampling - factor. + 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 @@ -151,18 +149,26 @@ extends java.lang.Object handle  -protected byte[] -yuvBuf  - - protected int yuvHeight  + +protected int[] +yuvOffsets  + protected int yuvPad  +protected byte[][] +yuvPlanes  + + +protected int[] +yuvStrides  + + protected int yuvSubsamp  @@ -185,21 +191,42 @@ extends java.lang.Object Constructor and Description -YUVImage(byte[] yuvImage, +YUVImage(byte[][] planes, + int[] offsets, + int width, + int[] strides, + int height, + int subsamp) +

Create a new YUVImage instance from a set of existing image + planes.
+ + + +YUVImage(byte[] yuvImage, int width, int pad, int height, int subsamp) -
Create a YUVImage instance from an existing YUV planar image +
Create a new YUVImage instance from an existing unified image buffer.
+ +YUVImage(int width, + int[] strides, + int height, + int subsamp) +
Create a new YUVImage instance backed by separate image + planes, and allocate memory for the image planes.
+ + -YUVImage(int width, +YUVImage(int width, int pad, int height, int subsamp) -
Create a YUVImage instance with a new image buffer.
+
Create a new YUVImage instance backed by a unified image + buffer, and allocate memory for the image buffer.
@@ -220,48 +247,80 @@ extends java.lang.Object byte[] getBuf() -
Returns the YUV image buffer
+
Returns the YUV image buffer (if this image is stored in a unified + buffer rather than separate image planes.)
int getHeight() -
Returns the height of the YUV image.
+
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 line padding used in the YUV image buffer.
+
Returns the line padding used in the YUV image 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 image buffer
+
Returns the size (in bytes) of the YUV image buffer (if this image is + stored in a unified buffer rather than separate image planes.)
+int[] +getStrides() +
Returns the number of bytes per line 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.
+
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 this YUVImage instance.
void -setBuf(byte[] yuvImage, +setBuf(byte[] yuvImage, int width, int pad, int height, int subsamp) -
Assign an existing YUV planar image buffer to this YUVImage - instance.
+
Assign a unified image buffer to this YUVImage instance.
@@ -295,13 +354,31 @@ extends java.lang.Object 
protected long handle
- +
  • -

    yuvBuf

    -
    protected byte[] yuvBuf
    +

    yuvPlanes

    +
    protected byte[][] yuvPlanes
    +
    • +
+ + + +
    +
  • +

    yuvOffsets

    +
    protected int[] yuvOffsets
    +
    • +
+ + + +
    +
  • +

    yuvStrides

    +
    protected int[] yuvStrides
@@ -348,6 +425,31 @@ extends java.lang.Object

Constructor Detail

+ + + +
    +
  • +

    YUVImage

    +
    public YUVImage(int width,
+        int[] strides,
+        int height,
+        int subsamp)
+         throws java.lang.Exception
    +
    Create a new YUVImage instance backed by separate image + planes, and allocate memory for the image planes.
    +
    Parameters:
    width - width (in pixels) of the YUV image
    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 + 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.
    height - height (in pixels) of the YUV image
    subsamp - the level of chrominance subsampling to be used in the YUV + image (one of TJ.SAMP_*)
    +
    Throws:
    +
    java.lang.Exception
    +
    • +
@@ -359,7 +461,8 @@ extends java.lang.Object int height, int subsamp) throws java.lang.Exception -
Create a YUVImage instance with a new image buffer.
+
Create a new YUVImage instance backed by a unified image + buffer, and allocate memory for the image buffer.
Parameters:
width - width (in pixels) of the YUV image
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.)
height - height (in pixels) of the YUV image
subsamp - the level of chrominance subsampling to be used in the YUV image (one of TJ.SAMP_*)
@@ -367,6 +470,44 @@ extends java.lang.Object
java.lang.Exception
+ + + +
    +
  • +

    YUVImage

    +
    public YUVImage(byte[][] planes,
+        int[] offsets,
+        int width,
+        int[] strides,
+        int height,
+        int subsamp)
+         throws java.lang.Exception
    +
    Create a new YUVImage 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. Plane + i should be at least offsets[i] + + TJ.planeSizeYUV(i, width, strides[i], height, subsamp) + bytes in size.
    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.
    width - width (in pixels) of the new YUV image (or subregion)
    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 + 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.)
    height - height (in pixels) of the new YUV image (or subregion)
    subsamp - the level of chrominance subsampling used in the YUV + image (one of TJ.SAMP_*)
    +
    Throws:
    +
    java.lang.Exception
    +
    • +
@@ -379,10 +520,10 @@ extends java.lang.Object int height, int subsamp) throws java.lang.Exception -
Create a YUVImage instance from an existing YUV planar image +
Create a new YUVImage instance from an existing unified image buffer.
Parameters:
yuvImage - image buffer that contains or will contain YUV planar - image data. Use TJ.bufSizeYUV(int, int, int, int) to determine the minimum size for + image data. Use TJ.bufSizeYUV(int, int, int, int) to determine the minimum size for this buffer. The Y, U (Cb), and V (Cr) image planes are stored sequentially in the buffer (see above for a description of the image format.)
width - width (in pixels) of the YUV image
pad - the line padding used in the YUV image buffer. For @@ -401,6 +542,43 @@ extends java.lang.Object

Method Detail

+ + + +
    +
  • +

    setBuf

    +
    public void setBuf(byte[][] planes,
+          int[] offsets,
+          int width,
+          int[] strides,
+          int height,
+          int subsamp)
+            throws java.lang.Exception
    +
    Assign a set of image planes to this YUVImage 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. Plane + i should be at least offsets[i] + + TJ.planeSizeYUV(i, width, strides[i], height, subsamp) + bytes in size.
    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.
    width - width (in pixels) of the YUV image (or subregion)
    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 + 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.)
    height - height (in pixels) of the YUV image (or subregion)
    subsamp - the level of chrominance subsampling used in the YUV + image (one of TJ.SAMP_*)
    +
    Throws:
    +
    java.lang.Exception
    +
    • +
@@ -413,10 +591,9 @@ extends java.lang.Object int height, int subsamp) throws java.lang.Exception -
Assign an existing YUV planar image buffer to this YUVImage - instance.
+
Assign a unified image buffer to this YUVImage instance.
Parameters:
yuvImage - image buffer that contains or will contain YUV planar - image data. Use TJ.bufSizeYUV(int, int, int, int) to determine the minimum size for + image data. Use TJ.bufSizeYUV(int, int, int, int) to determine the minimum size for this buffer. The Y, U (Cb), and V (Cr) image planes are stored sequentially in the buffer (see above for a description of the image format.)
width - width (in pixels) of the YUV image
pad - the line padding used in the YUV image buffer. For @@ -435,8 +612,8 @@ extends java.lang.Object

getWidth

public int getWidth()
              throws java.lang.Exception
-
Returns the width of the YUV image.
-
Returns:
the width of the YUV image
+
Returns the width of the YUV image (or subregion.)
+
Returns:
the width of the YUV image (or subregion)
Throws:
java.lang.Exception
@@ -449,8 +626,8 @@ extends java.lang.Object

getHeight

public int getHeight()
               throws java.lang.Exception
-
Returns the height of the YUV image.
-
Returns:
the height of the YUV image
+
Returns the height of the YUV image (or subregion.)
+
Returns:
the height of the YUV image (or subregion)
Throws:
java.lang.Exception
@@ -463,12 +640,43 @@ extends java.lang.Object

getPad

public int getPad()
            throws java.lang.Exception
-
Returns the line padding used in the YUV image buffer.
+
Returns the line padding used in the YUV image buffer (if this image is + stored in a unified buffer rather than separate image planes.)
Returns:
the line padding used in the YUV image buffer
Throws:
java.lang.Exception
+ + + +
    +
  • +

    getStrides

    +
    public int[] getStrides()
+                 throws java.lang.Exception
    +
    Returns the number of bytes per line of each plane in the YUV image.
    +
    Returns:
    the number of bytes per line of each plane in the YUV image
    +
    Throws:
    +
    java.lang.Exception
    +
    • +
+ + + +
    +
  • +

    getOffsets

    +
    public int[] getOffsets()
+                 throws java.lang.Exception
    +
    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
    +
    Throws:
    +
    java.lang.Exception
    +
    • +
@@ -484,6 +692,21 @@ extends java.lang.Object
java.lang.Exception
+ + + +
    +
  • +

    getPlanes

    +
    public byte[][] getPlanes()
+                   throws java.lang.Exception
    +
    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
    +
    Throws:
    +
    java.lang.Exception
    +
    • +
@@ -492,7 +715,8 @@ extends java.lang.Object

getBuf

public byte[] getBuf()
               throws java.lang.Exception
-
Returns the YUV image buffer
+
Returns the YUV image buffer (if this image is stored in a unified + buffer rather than separate image planes.)
Returns:
the YUV image buffer
Throws:
java.lang.Exception
@@ -506,7 +730,8 @@ extends java.lang.Object

getSize

public int getSize()
             throws java.lang.Exception
-
Returns the size (in bytes) of the YUV image buffer
+
Returns the size (in bytes) of the YUV image buffer (if this image is + stored in a unified buffer rather than separate image planes.)
Returns:
the size (in bytes) of the YUV image buffer
Throws:
java.lang.Exception
-- cgit v1.2.3