Clean up and consolidate notes regarding the YUV image format. This also corrects a factual error regarding the padding of the luminance plane-- because we now support 4:1:1, the component width is not necessarily padded to the nearest multiple of 2 if horizontal subsampling is used.

doc/html/group___turbo_j_p_e_g.html

@@ -302,7 +302,11 @@ Variables</h2></td></tr>
 <a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
 <p>TurboJPEG API. </p>
 <p>This API provides an interface for generating, decoding, and transforming planar YUV and JPEG images in memory.</p>
-<dl class="section note"><dt>Note</dt><dd>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. </dd></dl>
+<p><a class="anchor" id="YUVnotes"></a></p>
+<h2>YUV Image Format Notes</h2>
+<p>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.</p>
+<p>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 "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.) This is irrespective of any additional padding that may be specified as an argument to the various YUV functions. 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.</p>
+<p>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. </p>
 <h2 class="groupheader">Macro Definition Documentation</h2>
 <a class="anchor" id="ga39f57a6fb02d9cf32e7b6890099b5a71"></a>
 <div class="memitem">
@@ -1070,14 +1074,13 @@ If you choose option 1, <code>*jpegSize</code> should be set to the size of your
 </div><div class="memdoc">
 
 <p>Compress a YUV planar image into a JPEG image. </p>
-<dl class="section note"><dt>Note</dt><dd>If the width or height of the YUV image is not an even multiple of the MCU block size (see <a class="el" href="group___turbo_j_p_e_g.html#ga9e61e7cd47a15a173283ba94e781308c" title="MCU block width (in pixels) for a given level of chrominance subsampling.">tjMCUWidth</a> and <a class="el" href="group___turbo_j_p_e_g.html#gabd247bb9fecb393eca57366feb8327bf" title="MCU block height (in pixels) for a given level of chrominance subsampling.">tjMCUHeight</a>), then an intermediate buffer copy will be performed within TurboJPEG.</dd></dl>
 <dl class="params"><dt>Parameters</dt><dd>
   <table class="params">
     <tr><td class="paramname">handle</td><td>a handle to a TurboJPEG compressor or transformer instance </td></tr>
-    <tr><td class="paramname">srcBuf</td><td>pointer to an image buffer containing a YUV planar image to be compressed. The Y, U (Cb), and V (Cr) image planes should be stored sequentially in the buffer, and the size of each plane is determined by the specified width, height, padding, and level of chrominance subsampling. If the chrominance components are subsampled along the horizontal dimension, then the width of the luminance plane should be padded to the nearest multiple of 2 (same goes for the height of the luminance plane, if the chrominance components are subsampled along the vertical dimension.) This is irrespective of any additional padding specified in the <code>pad</code> parameter. </td></tr>
+    <tr><td class="paramname">srcBuf</td><td>pointer to an image buffer containing a YUV planar image to be compressed. The size of this buffer should match the value returned by <a class="el" href="group___turbo_j_p_e_g.html#gaf451664a62c1f6c7cc5a6401f32908c9" title="The size of the buffer (in bytes) required to hold a YUV planar image with the given parameters...">tjBufSizeYUV2()</a> for the given image width, height, padding, and level of chrominance subsampling. The Y, U (Cb), and V (Cr) image planes should be stored sequentially in the source buffer (refer to <a class="el" href="group___turbo_j_p_e_g.html#YUVnotes">YUV Image Format Notes</a>.) </td></tr>
-    <tr><td class="paramname">width</td><td>width (in pixels) of the source image </td></tr>
+    <tr><td class="paramname">width</td><td>width (in pixels) of the source image. If the width is not an even multiple of the MCU block width (see <a class="el" href="group___turbo_j_p_e_g.html#ga9e61e7cd47a15a173283ba94e781308c" title="MCU block width (in pixels) for a given level of chrominance subsampling.">tjMCUWidth</a>), then an intermediate buffer copy will be performed within TurboJPEG. </td></tr>
     <tr><td class="paramname">pad</td><td>the line padding used in the source image. For instance, if each line in each plane of the YUV image is padded to the nearest multiple of 4 bytes, then <code>pad</code> should be set to 4. </td></tr>
-    <tr><td class="paramname">height</td><td>height (in pixels) of the source image </td></tr>
+    <tr><td class="paramname">height</td><td>height (in pixels) of the source image. If the height is not an even multiple of the MCU block height (see <a class="el" href="group___turbo_j_p_e_g.html#gabd247bb9fecb393eca57366feb8327bf" title="MCU block height (in pixels) for a given level of chrominance subsampling.">tjMCUHeight</a>), then an intermediate buffer copy will be performed within TurboJPEG. </td></tr>
     <tr><td class="paramname">subsamp</td><td>the level of chrominance subsampling used in the source image (see <a class="el" href="group___turbo_j_p_e_g.html#ga1d047060ea80bb9820d540bb928e9074">Chrominance subsampling options</a>.) </td></tr>
     <tr><td class="paramname">jpegBuf</td><td>address of a pointer to an image buffer that will receive the JPEG image. TurboJPEG has the ability to reallocate the JPEG buffer to accommodate the size of the JPEG image. Thus, you can choose to:<ol type="1">
 <li>pre-allocate the JPEG buffer with an arbitrary size using <a class="el" href="group___turbo_j_p_e_g.html#ga5c9234bda6d993cdaffdd89bf81a00ff" title="Allocate an image buffer for use with TurboJPEG.">tjAlloc()</a> and let TurboJPEG grow the buffer as needed,</li>
@@ -1168,11 +1171,11 @@ If you choose option 1, <code>*jpegSize</code> should be set to the size of your
 </div><div class="memdoc">
 
 <p>Decode a YUV planar image into an RGB or grayscale image. </p>
-<p>This function uses the accelerated color conversion routines in the underlying codec but does not execute any of the other steps in the JPEG decompression process. The Y, U (Cb), and V (Cr) image planes should be stored sequentially in the source buffer, and the size of each plane is determined by the width and height of the source image, as well as the specified padding and level of chrominance subsampling. If the chrominance components are subsampled along the horizontal dimension, then the width of the luminance plane should be padded to the nearest multiple of 2 in the input image (same goes for the height of the luminance plane, if the chrominance components are subsampled along the vertical dimension.)</p>
+<p>This function uses the accelerated color conversion routines in the underlying codec but does not execute any of the other steps in the JPEG decompression process.</p>
 <dl class="params"><dt>Parameters</dt><dd>
   <table class="params">
     <tr><td class="paramname">handle</td><td>a handle to a TurboJPEG decompressor or transformer instance </td></tr>
-    <tr><td class="paramname">srcBuf</td><td>pointer to an image buffer containing a YUV planar image to be decoded. The size of this buffer should match the value returned by <a class="el" href="group___turbo_j_p_e_g.html#gaf451664a62c1f6c7cc5a6401f32908c9" title="The size of the buffer (in bytes) required to hold a YUV planar image with the given parameters...">tjBufSizeYUV2()</a> for the given image width, height, padding, and level of chrominance subsampling. </td></tr>
+    <tr><td class="paramname">srcBuf</td><td>pointer to an image buffer containing a YUV planar image to be decoded. The size of this buffer should match the value returned by <a class="el" href="group___turbo_j_p_e_g.html#gaf451664a62c1f6c7cc5a6401f32908c9" title="The size of the buffer (in bytes) required to hold a YUV planar image with the given parameters...">tjBufSizeYUV2()</a> for the given image width, height, padding, and level of chrominance subsampling. The Y, U (Cb), and V (Cr) image planes should be stored sequentially in the source buffer (refer to <a class="el" href="group___turbo_j_p_e_g.html#YUVnotes">YUV Image Format Notes</a>.) </td></tr>
     <tr><td class="paramname">pad</td><td>Use this parameter to specify that the width of each line in each plane of the YUV source image is padded to the nearest multiple of this number of bytes (must be a power of 2.) </td></tr>
     <tr><td class="paramname">subsamp</td><td>the level of chrominance subsampling used in the YUV source image (see <a class="el" href="group___turbo_j_p_e_g.html#ga1d047060ea80bb9820d540bb928e9074">Chrominance subsampling options</a>.) </td></tr>
     <tr><td class="paramname">dstBuf</td><td>pointer to an image buffer that will receive the decoded image. This buffer should normally be <code>pitch * height</code> bytes in size, but the <code>dstBuf</code> pointer can also be used to decode into a specific region of a larger buffer. </td></tr>
@@ -1405,17 +1408,16 @@ If you choose option 1, <code>*jpegSize</code> should be set to the size of your
 </div><div class="memdoc">
 
 <p>Decompress a JPEG image to a YUV planar image. </p>
-<p>This function performs JPEG decompression but leaves out the color conversion step, so a planar YUV image is generated instead of an RGB image. The structure of the planes in this image is the same as in the images generated by <a class="el" href="group___turbo_j_p_e_g.html#ga0a5ffbf7cb58a5b6a8201114fe889360" title="Encode an RGB or grayscale image into a YUV planar image.">tjEncodeYUV3()</a>.</p>
+<p>This function performs JPEG decompression but leaves out the color conversion step, so a planar YUV image is generated instead of an RGB image.</p>
-<dl class="section note"><dt>Note</dt><dd>If the width or height of the JPEG image is not an even multiple of the MCU block size (see <a class="el" href="group___turbo_j_p_e_g.html#ga9e61e7cd47a15a173283ba94e781308c" title="MCU block width (in pixels) for a given level of chrominance subsampling.">tjMCUWidth</a> and <a class="el" href="group___turbo_j_p_e_g.html#gabd247bb9fecb393eca57366feb8327bf" title="MCU block height (in pixels) for a given level of chrominance subsampling.">tjMCUHeight</a>), then an intermediate buffer copy will be performed within TurboJPEG.</dd></dl>
 <dl class="params"><dt>Parameters</dt><dd>
   <table class="params">
     <tr><td class="paramname">handle</td><td>a handle to a TurboJPEG decompressor or transformer instance </td></tr>
     <tr><td class="paramname">jpegBuf</td><td>pointer to a buffer containing the JPEG image to decompress </td></tr>
     <tr><td class="paramname">jpegSize</td><td>size of the JPEG image (in bytes) </td></tr>
-    <tr><td class="paramname">dstBuf</td><td>pointer to an image buffer that will receive the YUV image. Use <a class="el" href="group___turbo_j_p_e_g.html#gaf451664a62c1f6c7cc5a6401f32908c9" title="The size of the buffer (in bytes) required to hold a YUV planar image with the given parameters...">tjBufSizeYUV2()</a> to determine the appropriate size for this buffer based on the image width, height, padding, and level of subsampling. </td></tr>
+    <tr><td class="paramname">dstBuf</td><td>pointer to an image buffer that will receive the YUV image. Use <a class="el" href="group___turbo_j_p_e_g.html#gaf451664a62c1f6c7cc5a6401f32908c9" title="The size of the buffer (in bytes) required to hold a YUV planar image with the given parameters...">tjBufSizeYUV2()</a> to determine the appropriate size for this buffer based on the image width, height, padding, and level of subsampling. The Y, U (Cb), and V (Cr) image planes will be stored sequentially in the buffer (refer to <a class="el" href="group___turbo_j_p_e_g.html#YUVnotes">YUV Image Format Notes</a>.) </td></tr>
-    <tr><td class="paramname">width</td><td>desired width (in pixels) of the YUV image. If this is different than the width of the JPEG image being decompressed, then TurboJPEG will use scaling in the JPEG decompressor to generate the largest possible image that will fit within the desired width. If <code>width</code> is set to 0, then only the height will be considered when determining the scaled image size. </td></tr>
+    <tr><td class="paramname">width</td><td>desired width (in pixels) of the YUV image. If this is different than the width of the JPEG image being decompressed, then TurboJPEG will use scaling in the JPEG decompressor to generate the largest possible image that will fit within the desired width. If <code>width</code> is set to 0, then only the height will be considered when determining the scaled image size. If the scaled width is not an even multiple of the MCU block width (see <a class="el" href="group___turbo_j_p_e_g.html#ga9e61e7cd47a15a173283ba94e781308c" title="MCU block width (in pixels) for a given level of chrominance subsampling.">tjMCUWidth</a>), then an intermediate buffer copy will be performed within TurboJPEG. </td></tr>
     <tr><td class="paramname">pad</td><td>the width of each line in each plane of the YUV image will be padded to the nearest multiple of this number of bytes (must be a power of 2.) To generate images suitable for X Video, <code>pad</code> should be set to 4. </td></tr>
-    <tr><td class="paramname">height</td><td>desired height (in pixels) of the YUV image. If this is different than the height of the JPEG image being decompressed, then TurboJPEG will use scaling in the JPEG decompressor to generate the largest possible image that will fit within the desired height. If <code>height</code> is set to 0, then only the width will be considered when determining the scaled image size. </td></tr>
+    <tr><td class="paramname">height</td><td>desired height (in pixels) of the YUV image. If this is different than the height of the JPEG image being decompressed, then TurboJPEG will use scaling in the JPEG decompressor to generate the largest possible image that will fit within the desired height. If <code>height</code> is set to 0, then only the width will be considered when determining the scaled image size. If the scaled height is not an even multiple of the MCU block height (see <a class="el" href="group___turbo_j_p_e_g.html#gabd247bb9fecb393eca57366feb8327bf" title="MCU block height (in pixels) for a given level of chrominance subsampling.">tjMCUHeight</a>), then an intermediate buffer copy will be performed within TurboJPEG. </td></tr>
     <tr><td class="paramname">flags</td><td>the bitwise OR of one or more of the <a class="el" href="group___turbo_j_p_e_g.html#ga72ecf4ebe6eb702d3c6f5ca27455e1ec">flags</a>.</td></tr>
   </table>
   </dd>
@@ -1522,7 +1524,7 @@ If you choose option 1, <code>*jpegSize</code> should be set to the size of your
 </div><div class="memdoc">
 
 <p>Encode an RGB or grayscale image into a YUV planar image. </p>
-<p>This function uses the accelerated color conversion routines in the underlying codec but does not execute any of the other steps in the JPEG compression process. The Y, U (Cb), and V (Cr) image planes are stored sequentially into the destination buffer, and the size of each plane is determined by the width and height of the source image, as well as the specified padding and level of chrominance subsampling. If the chrominance components are subsampled along the horizontal dimension, then the width of the luminance plane is padded to the nearest multiple of 2 in the output image (same goes for the height of the luminance plane, if the chrominance components are subsampled along the vertical dimension.)</p>
+<p>This function uses the accelerated color conversion routines in the underlying codec but does not execute any of the other steps in the JPEG compression process.</p>
 <dl class="params"><dt>Parameters</dt><dd>
   <table class="params">
     <tr><td class="paramname">handle</td><td>a handle to a TurboJPEG compressor or transformer instance </td></tr>
@@ -1531,7 +1533,7 @@ If you choose option 1, <code>*jpegSize</code> should be set to the size of your
     <tr><td class="paramname">pitch</td><td>bytes per line of the source image. Normally, this should be <code>width * <a class="el" href="group___turbo_j_p_e_g.html#gad77cf8fe5b2bfd3cb3f53098146abb4c" title="Pixel size (in bytes) for a given pixel format.">tjPixelSize</a>[pixelFormat]</code> if the image is unpadded, or <code><a class="el" href="group___turbo_j_p_e_g.html#ga0aba955473315e405295d978f0c16511" title="Pad the given width to the nearest 32-bit boundary.">TJPAD</a>(width * <a class="el" href="group___turbo_j_p_e_g.html#gad77cf8fe5b2bfd3cb3f53098146abb4c" title="Pixel size (in bytes) for a given pixel format.">tjPixelSize</a>[pixelFormat])</code> if each line of the image is padded to the nearest 32-bit boundary, as is the case for Windows bitmaps. You can also be clever and use this parameter to skip lines, etc. Setting this parameter to 0 is the equivalent of setting it to <code>width * <a class="el" href="group___turbo_j_p_e_g.html#gad77cf8fe5b2bfd3cb3f53098146abb4c" title="Pixel size (in bytes) for a given pixel format.">tjPixelSize</a>[pixelFormat]</code>. </td></tr>
     <tr><td class="paramname">height</td><td>height (in pixels) of the source image </td></tr>
     <tr><td class="paramname">pixelFormat</td><td>pixel format of the source image (see <a class="el" href="group___turbo_j_p_e_g.html#gac916144e26c3817ac514e64ae5d12e2a">Pixel formats</a>.) </td></tr>
-    <tr><td class="paramname">dstBuf</td><td>pointer to an image buffer that will receive the YUV image. Use <a class="el" href="group___turbo_j_p_e_g.html#gaf451664a62c1f6c7cc5a6401f32908c9" title="The size of the buffer (in bytes) required to hold a YUV planar image with the given parameters...">tjBufSizeYUV2()</a> to determine the appropriate size for this buffer based on the image width, height, padding, and level of chrominance subsampling. </td></tr>
+    <tr><td class="paramname">dstBuf</td><td>pointer to an image buffer that will receive the YUV image. Use <a class="el" href="group___turbo_j_p_e_g.html#gaf451664a62c1f6c7cc5a6401f32908c9" title="The size of the buffer (in bytes) required to hold a YUV planar image with the given parameters...">tjBufSizeYUV2()</a> to determine the appropriate size for this buffer based on the image width, height, padding, and level of chrominance subsampling. The Y, U (Cb), and V (Cr) image planes will be stored sequentially in the buffer (refer to <a class="el" href="group___turbo_j_p_e_g.html#YUVnotes">YUV Image Format Notes</a>.) </td></tr>
     <tr><td class="paramname">pad</td><td>the width of each line in each plane of the YUV image will be padded to the nearest multiple of this number of bytes (must be a power of 2.) To generate images suitable for X Video, <code>pad</code> should be set to 4. </td></tr>
     <tr><td class="paramname">subsamp</td><td>the level of chrominance subsampling to be used when generating the YUV image (see <a class="el" href="group___turbo_j_p_e_g.html#ga1d047060ea80bb9820d540bb928e9074">Chrominance subsampling options</a>.) To generate images suitable for X Video, <code>subsamp</code> should be set to <a class="el" href="group___turbo_j_p_e_g.html#gga1d047060ea80bb9820d540bb928e9074a63085dbf683cfe39e513cdb6343e3737">TJSAMP_420</a>. This produces an image compatible with the I420 (AKA "YUV420P") format. </td></tr>
     <tr><td class="paramname">flags</td><td>the bitwise OR of one or more of the <a class="el" href="group___turbo_j_p_e_g.html#ga72ecf4ebe6eb702d3c6f5ca27455e1ec">flags</a>.</td></tr>

java/doc/index-all.html

@@ -857,7 +857,7 @@
 <dd>&nbsp;</dd>
 <dt><a href="./org/libjpegturbo/turbojpeg/YUVImage.html" title="class in org.libjpegturbo.turbojpeg"><span class="strong">YUVImage</span></a> - Class in <a href="./org/libjpegturbo/turbojpeg/package-summary.html">org.libjpegturbo.turbojpeg</a></dt>
 <dd>
-<div class="block">This class encapsulates a YUV planar image buffer and the metadata
+<div class="block">This class encapsulates a YUV planar image and the metadata
  associated with it.</div>
 </dd>
 <dt><span class="strong"><a href="./org/libjpegturbo/turbojpeg/YUVImage.html#YUVImage(int, int, int, int)">YUVImage(int, int, int, int)</a></span> - Constructor for class org.libjpegturbo.turbojpeg.<a href="./org/libjpegturbo/turbojpeg/YUVImage.html" title="class in org.libjpegturbo.turbojpeg">YUVImage</a></dt>

java/doc/org/libjpegturbo/turbojpeg/YUVImage.html

@@ -94,7 +94,7 @@
 <br>
 <pre>public class <span class="strong">YUVImage</span>
 extends java.lang.Object</pre>
-<div class="block">This class encapsulates a YUV planar image buffer and the metadata
+<div class="block">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 <code>YUVImage</code> instance
@@ -105,18 +105,28 @@ extends java.lang.Object</pre>
  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.  In this image
+ image format consisting of Y, Cb, and Cr image planes.
- format, the Y, Cb (U), and Cr (V) planes are stored sequentially in the same
+ <p>
- image buffer, and the size of each plane is determined by the image width,
+ Each plane is simply a 2D array of bytes, each byte representing the value
- height, line padding, and level of chrominance subsampling.  If the
+ of one of the components at a particular location in the image.  The
- chrominance components are subsampled along the horizontal dimension, then
+ "component width" and "component height" of each plane are determined by the
- the width of the luminance plane would be padded to the nearest multiple of
+ image width, height, and level of chrominance subsampling.  For the
- 2 (same goes for the height of the luminance plane, if the chrominance
+ luminance plane, the component width is the image width padded to the
- components are subsampled along the vertical dimension.)  For instance, if
+ nearest multiple of the horizontal subsampling factor (2 in the case of
- the source image is 35 x 35 pixels and 4:2:2 subsampling is used, then the
+ 4:2:0 and 4:2:2, 4 in the case of 4:1:1, 1 in the case of 4:4:4 or
- luminance plane would be 36 x 35 bytes, and each of the chrominance planes
+ grayscale.)  Similarly, the component height of the luminance plane is the
- would be 18 x 35 bytes.  If you specify, for instance, a line padding of 4
+ image height padded to the nearest multiple of the vertical subsampling
- bytes on top of this, then the luminance plane would be 36 x 35 bytes, and
+ 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.
+ <p>
+ 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.</div>
 </li>
 </ul>
@@ -372,9 +382,10 @@ extends java.lang.Object</pre>
 <div class="block">Create a <code>YUVImage</code> instance from an existing YUV planar image
  buffer.</div>
 <dl><dt><span class="strong">Parameters:</span></dt><dd><code>yuvImage</code> - image buffer that contains or will contain YUV planar
- image data.  See <a href="../../../org/libjpegturbo/turbojpeg/YUVImage.html" title="class in org.libjpegturbo.turbojpeg"><code>above</code></a> for a description of the image
+ image data.  Use <a href="../../../org/libjpegturbo/turbojpeg/TJ.html#bufSizeYUV(int, int, int, int)"><code>TJ.bufSizeYUV(int, int, int, int)</code></a> to determine the minimum size for
- format.  Use <a href="../../../org/libjpegturbo/turbojpeg/TJ.html#bufSizeYUV(int, int, int, int)"><code>TJ.bufSizeYUV(int, int, int, int)</code></a> to determine the minimum size for this
+ this buffer.  The Y, U (Cb), and V (Cr) image planes are stored
- buffer.</dd><dd><code>width</code> - width (in pixels) of the YUV image</dd><dd><code>pad</code> - the line padding used in the YUV image buffer.  For
+ sequentially in the buffer (see <a href="../../../org/libjpegturbo/turbojpeg/YUVImage.html" title="class in org.libjpegturbo.turbojpeg"><code>above</code></a> for a description
+ of the image format.)</dd><dd><code>width</code> - width (in pixels) of the YUV image</dd><dd><code>pad</code> - 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 <code>pad</code> should be set to 4.</dd><dd><code>height</code> - height (in pixels) of the YUV image</dd><dd><code>subsamp</code> - the level of chrominance subsampling used in the YUV
  image (one of <a href="../../../org/libjpegturbo/turbojpeg/TJ.html#SAMP_444"><code>TJ.SAMP_*</code></a>)</dd>
@@ -405,9 +416,10 @@ extends java.lang.Object</pre>
 <div class="block">Assign an existing YUV planar image buffer to this <code>YUVImage</code>
  instance.</div>
 <dl><dt><span class="strong">Parameters:</span></dt><dd><code>yuvImage</code> - image buffer that contains or will contain YUV planar
- image data.  See <a href="../../../org/libjpegturbo/turbojpeg/YUVImage.html" title="class in org.libjpegturbo.turbojpeg"><code>above</code></a> for a description of the image
+ image data.  Use <a href="../../../org/libjpegturbo/turbojpeg/TJ.html#bufSizeYUV(int, int, int, int)"><code>TJ.bufSizeYUV(int, int, int, int)</code></a> to determine the minimum size for
- format.  Use <a href="../../../org/libjpegturbo/turbojpeg/TJ.html#bufSizeYUV(int, int, int, int)"><code>TJ.bufSizeYUV(int, int, int, int)</code></a> to determine the minimum size for this
+ this buffer.  The Y, U (Cb), and V (Cr) image planes are stored
- buffer.</dd><dd><code>width</code> - width (in pixels) of the YUV image</dd><dd><code>pad</code> - the line padding used in the YUV image buffer.  For
+ sequentially in the buffer (see <a href="../../../org/libjpegturbo/turbojpeg/YUVImage.html" title="class in org.libjpegturbo.turbojpeg"><code>above</code></a> for a description
+ of the image format.)</dd><dd><code>width</code> - width (in pixels) of the YUV image</dd><dd><code>pad</code> - 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 <code>pad</code> should be set to 4.</dd><dd><code>height</code> - height (in pixels) of the YUV image</dd><dd><code>subsamp</code> - the level of chrominance subsampling used in the YUV
  image (one of <a href="../../../org/libjpegturbo/turbojpeg/TJ.html#SAMP_444"><code>TJ.SAMP_*</code></a>)</dd>

java/doc/org/libjpegturbo/turbojpeg/package-summary.html

@@ -127,7 +127,7 @@
 <tr class="altColor">
 <td class="colFirst"><a href="../../../org/libjpegturbo/turbojpeg/YUVImage.html" title="class in org.libjpegturbo.turbojpeg">YUVImage</a></td>
 <td class="colLast">
-<div class="block">This class encapsulates a YUV planar image buffer and the metadata
+<div class="block">This class encapsulates a YUV planar image and the metadata
  associated with it.</div>
 </td>
 </tr>

java/org/libjpegturbo/turbojpeg/YUVImage.java

@@ -29,7 +29,7 @@
 package org.libjpegturbo.turbojpeg;
 
 /**
- * This class encapsulates a YUV planar image buffer and the metadata
+ * 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 <code>YUVImage</code> instance
@@ -40,18 +40,28 @@ package org.libjpegturbo.turbojpeg;
  * 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.  In this image
+ * image format consisting of Y, Cb, and Cr image planes.
- * format, the Y, Cb (U), and Cr (V) planes are stored sequentially in the same
+ * <p>
- * image buffer, and the size of each plane is determined by the image width,
+ * Each plane is simply a 2D array of bytes, each byte representing the value
- * height, line padding, and level of chrominance subsampling.  If the
+ * of one of the components at a particular location in the image.  The
- * chrominance components are subsampled along the horizontal dimension, then
+ * "component width" and "component height" of each plane are determined by the
- * the width of the luminance plane would be padded to the nearest multiple of
+ * image width, height, and level of chrominance subsampling.  For the
- * 2 (same goes for the height of the luminance plane, if the chrominance
+ * luminance plane, the component width is the image width padded to the
- * components are subsampled along the vertical dimension.)  For instance, if
+ * nearest multiple of the horizontal subsampling factor (2 in the case of
- * the source image is 35 x 35 pixels and 4:2:2 subsampling is used, then the
+ * 4:2:0 and 4:2:2, 4 in the case of 4:1:1, 1 in the case of 4:4:4 or
- * luminance plane would be 36 x 35 bytes, and each of the chrominance planes
+ * grayscale.)  Similarly, the component height of the luminance plane is the
- * would be 18 x 35 bytes.  If you specify, for instance, a line padding of 4
+ * image height padded to the nearest multiple of the vertical subsampling
- * bytes on top of this, then the luminance plane would be 36 x 35 bytes, and
+ * 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.
+ * <p>
+ * 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 {
@@ -83,9 +93,10 @@ public class YUVImage {
    * buffer.
    *
    * @param yuvImage image buffer that contains or will contain YUV planar
-   * image data.  See {@link YUVImage above} for a description of the image
+   * image data.  Use {@link TJ#bufSizeYUV} to determine the minimum size for
-   * format.  Use {@link TJ#bufSizeYUV} to determine the minimum size for this
+   * this buffer.  The Y, U (Cb), and V (Cr) image planes are stored
-   * buffer.
+   * sequentially in the buffer (see {@link YUVImage above} for a description
+   * of the image format.)
    *
    * @param width width (in pixels) of the YUV image
    *
@@ -108,9 +119,10 @@ public class YUVImage {
    * instance.
    *
    * @param yuvImage image buffer that contains or will contain YUV planar
-   * image data.  See {@link YUVImage above} for a description of the image
+   * image data.  Use {@link TJ#bufSizeYUV} to determine the minimum size for
-   * format.  Use {@link TJ#bufSizeYUV} to determine the minimum size for this
+   * this buffer.  The Y, U (Cb), and V (Cr) image planes are stored
-   * buffer.
+   * sequentially in the buffer (see {@link YUVImage above} for a description
+   * of the image format.)
    *
    * @param width width (in pixels) of the YUV image
    *

turbojpeg.h

@@ -42,10 +42,36 @@
  * TurboJPEG API.  This API provides an interface for generating, decoding, and
  * transforming planar YUV and JPEG images in memory.
  *
- * @note Technically, the JPEG format uses the YCbCr colorspace (which is
+ * @anchor YUVnotes
- * technically not a colorspace but a color transform), but per the convention
+ * YUV Image Format Notes
- * of the digital video community, the TurboJPEG API uses "YUV" to refer to an
+ * ----------------------
- * image format consisting of Y, Cb, and Cr image planes.
+ * 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 "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.)  This is irrespective of any additional padding that may be
+ * specified as an argument to the various YUV functions.  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.
+ *
+ * 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.
  *
  * @{
  */
@@ -641,27 +667,22 @@ DLLEXPORT int DLLCALL tjCompress2(tjhandle handle, unsigned char *srcBuf,
 /**
  * Compress a YUV planar image into a JPEG image.
  *
- * @note If the width or height of the YUV image is not an even multiple of the
- * MCU block size (see #tjMCUWidth and #tjMCUHeight), then an intermediate
- * buffer copy will be performed within TurboJPEG.
- *
  * @param handle a handle to a TurboJPEG compressor or transformer instance
- * @param srcBuf pointer to an image buffer containing a YUV planar image
+ * @param srcBuf pointer to an image buffer containing a YUV planar image to be
- *        to be compressed.  The Y, U (Cb), and V (Cr) image planes should be
+ *        compressed.  The size of this buffer should match the value returned
- *        stored sequentially in the buffer, and the size of each plane
+ *        by #tjBufSizeYUV2() for the given image width, height, padding, and
- *        is determined by the specified width, height, padding, and level of
+ *        level of chrominance subsampling.  The Y, U (Cb), and V (Cr) image
- *        chrominance subsampling.  If the chrominance components are
+ *        planes should be stored sequentially in the source buffer (refer to
- *        subsampled along the horizontal dimension, then the width of the
+ *        @ref YUVnotes "YUV Image Format Notes".)
- *        luminance plane should be padded to the nearest multiple of 2 (same
+ * @param width width (in pixels) of the source image.  If the width is not an
- *        goes for the height of the luminance plane, if the chrominance
+ *        even multiple of the MCU block width (see #tjMCUWidth), then an
- *        components are subsampled along the vertical dimension.)  This is
+ *        intermediate buffer copy will be performed within TurboJPEG.
- *        irrespective of any additional padding specified in the <tt>pad</tt>
- *        parameter.
- * @param width width (in pixels) of the source image
  * @param pad the line padding used in the source image.  For instance, if each
  *        line in each plane of the YUV image is padded to the nearest multiple
  *        of 4 bytes, then <tt>pad</tt> should be set to 4.
- * @param height height (in pixels) of the source image
+ * @param height height (in pixels) of the source image.  If the height is not
+ *        an even multiple of the MCU block height (see #tjMCUHeight), then an
+ *        intermediate buffer copy will be performed within TurboJPEG.
  * @param subsamp the level of chrominance subsampling used in the source
  *        image (see @ref TJSAMP "Chrominance subsampling options".)
  * @param jpegBuf address of a pointer to an image buffer that will receive the
@@ -742,14 +763,7 @@ DLLEXPORT unsigned long DLLCALL tjBufSizeYUV2(int width, int pad, int height,
  * Encode an RGB or grayscale image into a YUV planar image.  This function
  * uses the accelerated color conversion routines in the underlying
  * codec but does not execute any of the other steps in the JPEG compression
- * process.  The Y, U (Cb), and V (Cr) image planes are stored sequentially
+ * process.  
- * into the destination buffer, and the size of each plane is determined by the
- * width and height of the source image, as well as the specified padding and
- * level of chrominance subsampling.  If the chrominance components are
- * subsampled along the horizontal dimension, then the width of the luminance
- * plane is padded to the nearest multiple of 2 in the output image (same goes
- * for the height of the luminance plane, if the chrominance components are
- * subsampled along the vertical dimension.)
  *
  * @param handle a handle to a TurboJPEG compressor or transformer instance
  * @param srcBuf pointer to an image buffer containing RGB or grayscale pixels
@@ -768,7 +782,9 @@ DLLEXPORT unsigned long DLLCALL tjBufSizeYUV2(int width, int pad, int height,
  * @param dstBuf pointer to an image buffer that will receive the YUV image.
  *        Use #tjBufSizeYUV2() to determine the appropriate size for this
  *        buffer based on the image width, height, padding, and level of
- *        chrominance subsampling.
+ *        chrominance subsampling.  The Y, U (Cb), and V (Cr) image planes will
+ *        be stored sequentially in the buffer (refer to @ref YUVnotes
+ *        "YUV Image Format Notes".)
  * @param pad the width of each line in each plane of the YUV image will be
  *        padded to the nearest multiple of this number of bytes (must be a
  *        power of 2.)  To generate images suitable for X Video, <tt>pad</tt>
@@ -885,12 +901,7 @@ DLLEXPORT int DLLCALL tjDecompress2(tjhandle handle,
 /**
  * Decompress a JPEG image to a YUV planar image.  This function performs JPEG
  * decompression but leaves out the color conversion step, so a planar YUV
- * image is generated instead of an RGB image.  The structure of the planes in
+ * image is generated instead of an RGB image.
- * this image is the same as in the images generated by #tjEncodeYUV3().
- *
- * @note If the width or height of the JPEG image is not an even multiple of
- * the MCU block size (see #tjMCUWidth and #tjMCUHeight), then an intermediate
- * buffer copy will be performed within TurboJPEG.
  *
  * @param handle a handle to a TurboJPEG decompressor or transformer instance
  * @param jpegBuf pointer to a buffer containing the JPEG image to decompress
@@ -898,13 +909,17 @@ DLLEXPORT int DLLCALL tjDecompress2(tjhandle handle,
  * @param dstBuf pointer to an image buffer that will receive the YUV image.
  *        Use #tjBufSizeYUV2() to determine the appropriate size for this
  *        buffer based on the image width, height, padding, and level of
- *        subsampling.
+ *        subsampling.  The Y, U (Cb), and V (Cr) image planes will be stored
+ *        sequentially in the buffer (refer to @ref YUVnotes
+ *        "YUV Image Format Notes".)
  * @param width desired width (in pixels) of the YUV image.  If this is
  *        different than the width of the JPEG image being decompressed, then
  *        TurboJPEG will use scaling in the JPEG decompressor to generate the
  *        largest possible image that will fit within the desired width.  If
  *        <tt>width</tt> is set to 0, then only the height will be considered
- *        when determining the scaled image size.
+ *        when determining the scaled image size.  If the scaled width is not
+ *        an even multiple of the MCU block width (see #tjMCUWidth), then an
+ *        intermediate buffer copy will be performed within TurboJPEG.
  * @param pad the width of each line in each plane of the YUV image will be
  *        padded to the nearest multiple of this number of bytes (must be a
  *        power of 2.)  To generate images suitable for X Video, <tt>pad</tt>
@@ -914,7 +929,9 @@ DLLEXPORT int DLLCALL tjDecompress2(tjhandle handle,
  *        TurboJPEG will use scaling in the JPEG decompressor to generate the
  *        largest possible image that will fit within the desired height.  If
  *        <tt>height</tt> is set to 0, then only the width will be considered
- *        when determining the scaled image size.
+ *        when determining the scaled image size.  If the scaled height is not
+ *        an even multiple of the MCU block height (see #tjMCUHeight), then an
+ *        intermediate buffer copy will be performed within TurboJPEG.
  * @param flags the bitwise OR of one or more of the @ref TJFLAG_BOTTOMUP
  *        "flags".
  *
@@ -929,20 +946,15 @@ DLLEXPORT int DLLCALL tjDecompressToYUV2(tjhandle handle,
  * Decode a YUV planar image into an RGB or grayscale image.  This function
  * uses the accelerated color conversion routines in the underlying
  * codec but does not execute any of the other steps in the JPEG decompression
- * process.  The Y, U (Cb), and V (Cr) image planes should be stored
+ * process.
- * sequentially in the source buffer, and the size of each plane is determined
- * by the width and height of the source image, as well as the specified
- * padding and level of chrominance subsampling.  If the chrominance components
- * are subsampled along the horizontal dimension, then the width of the
- * luminance plane should be padded to the nearest multiple of 2 in the input
- * image (same goes for the height of the luminance plane, if the chrominance
- * components are subsampled along the vertical dimension.)
  *
  * @param handle a handle to a TurboJPEG decompressor or transformer instance
  * @param srcBuf pointer to an image buffer containing a YUV planar image to be
  *        decoded.  The size of this buffer should match the value returned
  *        by #tjBufSizeYUV2() for the given image width, height, padding, and
- *        level of chrominance subsampling.
+ *        level of chrominance subsampling.  The Y, U (Cb), and V (Cr) image
+ *        planes should be stored sequentially in the source buffer (refer to
+ *        @ref YUVnotes "YUV Image Format Notes".)
  * @param pad Use this parameter to specify that the width of each line in each
  *        plane of the YUV source image is padded to the nearest multiple of
  *        this number of bytes (must be a power of 2.)