Java code cleanup + Java docs

git-svn-id: svn://svn.code.sf.net/p/libjpeg-turbo/code/trunk@518 632fc199-4ca6-4c93-a231-07263d6284db

1 files changed, 78 insertions, 8 deletions

diff --git a/java/org/libjpegturbo/turbojpeg/TJTransformer.java b/java/org/libjpegturbo/turbojpeg/TJTransformer.java
index 5978365..22b2599 100644
--- a/java/org/libjpegturbo/turbojpeg/TJTransformer.java
+++ b/java/org/libjpegturbo/turbojpeg/TJTransformer.java
@@ -28,29 +28,92 @@
 
 package org.libjpegturbo.turbojpeg;
 
+/**
+ * TurboJPEG lossless transformer
+ */
 public class TJTransformer extends TJDecompressor {
 
+  /**
+   * Create a TurboJPEG lossless transformer instance.
+   */
   public TJTransformer() throws Exception {
     init();
   }
 
-  public TJTransformer(byte[] buf) throws Exception {
+  /**
+   * Create a TurboJPEG lossless transformer instance and associate the JPEG
+   * image stored in <code>jpegImage</code> with the newly-created instance.
+   *
+   * @param jpegImage JPEG image buffer (size of JPEG image is assumed to be
+   * the length of the buffer)
+   */
+  public TJTransformer(byte[] jpegImage) throws Exception {
     init();
-    setJPEGBuffer(buf, buf.length);
+    setJPEGBuffer(jpegImage, jpegImage.length);
   }
 
-  public TJTransformer(byte[] buf, int bufSize) throws Exception {
+  /**
+   * Create a TurboJPEG lossless transformer instance and associate the JPEG
+   * image of length <code>imageSize</code> bytes stored in
+   * <code>jpegImage</code> with the newly-created instance.
+   *
+   * @param jpegImage JPEG image buffer
+   *
+   * @param imageSize size of JPEG image (in bytes)
+   */
+  public TJTransformer(byte[] jpegImage, int imageSize) throws Exception {
     init();
-    setJPEGBuffer(buf, bufSize);
+    setJPEGBuffer(jpegImage, imageSize);
   }
 
+  /**
+   * Losslessly transform the JPEG image associated with this transformer
+   * instance into one or more JPEG images stored in the given destination
+   * buffers.  Lossless transforms work by moving the raw coefficients from one
+   * JPEG image structure to another without altering the values of the
+   * coefficients.  While this is typically faster than decompressing the
+   * image, transforming it, and re-compressing it, lossless transforms are not
+   * free.  Each lossless transform requires reading and Huffman decoding all
+   * of the coefficients in the source image, regardless of the size of the
+   * destination image.  Thus, this function provides a means of generating
+   * multiple transformed images from the same source or of applying multiple
+   * transformations simultaneously, in order to eliminate the need to read the
+   * source coefficients multiple times.
+   *
+   * @param dstBufs an array of n image buffers.  <code>dstbufs[i]</code> will
+   * receive a JPEG image that has been transformed using the parameters in
+   * <code>transforms[i]</code>.  Use {@link TJ#bufSizeYUV} to determine the
+   * maximum size for each buffer based on the cropped width and height.
+   *
+   * @param transforms an array of n {@link TJTransform} instances, each of
+   * which specifies the transform parameters and/or cropping region for the
+   * corresponding transformed output image
+   *
+   * @param flags the bitwise OR of one or more of the flags described in
+   * {@link TJ}
+   */
   public void transform(byte[][] dstBufs, TJTransform[] transforms,
     int flags) throws Exception {
     if(jpegBuf == null) throw new Exception("JPEG buffer not initialized");
     transformedSizes = transform(jpegBuf, jpegBufSize, dstBufs, transforms,
       flags);
   }
-
+  
+  /**
+   * Losslessly transform the JPEG image associated with this transformer
+   * instance and return an array of {@link TJDecompressor} instances, each of
+   * which has a transformed JPEG image associated with it.
+   *
+   * @param transforms an array of n {@link TJTransform} instances, each of
+   * which specifies the transform parameters and/or cropping region for the
+   * corresponding transformed output image
+   *
+   * @return an array of {@link TJDecompressor} instances, each of
+   * which has a transformed JPEG image associated with it
+   *
+   * @param flags the bitwise OR of one or more of the flags described in
+   * {@link TJ}
+   */
   public TJDecompressor[] transform(TJTransform[] transforms, int flags)
     throws Exception {
     byte[][] dstBufs = new byte[transforms.length][];
@@ -58,7 +121,7 @@ public class TJTransformer extends TJDecompressor {
       throw new Exception("JPEG buffer not initialized");
     for(int i = 0; i < transforms.length; i++) {
       int w = jpegWidth, h = jpegHeight;
-      if((transforms[i].options & TJ.XFORM_CROP) != 0) {
+      if((transforms[i].options & TJTransform.OPT_CROP) != 0) {
         if(transforms[i].width != 0) w = transforms[i].width;
         if(transforms[i].height != 0) h = transforms[i].height;
       }
@@ -68,9 +131,16 @@ public class TJTransformer extends TJDecompressor {
     transform(dstBufs, transforms, flags);
     for(int i = 0; i < transforms.length; i++)
       tjd[i] = new TJDecompressor(dstBufs[i], transformedSizes[i]);
-	  return tjd;
+    return tjd;
   }
-
+  
+  /**
+   * Returns an array containing the sizes of the transformed JPEG images from
+   * the most recent call to {@link #transform transform()}.
+   *
+   * @return an array containing the sizes of the transformed JPEG images from
+   * the most recent call to {@link #transform transform()}
+   */
   public int[] getTransformedSizes() throws Exception {
     if(transformedSizes == null)
       throw new Exception("No image has been transformed yet");