| DRC | f8e0055 | 2011-02-04 11:06:36 +0000 | [diff] [blame] | 1 | TurboJPEG/OSS JNI Wrapper |
| 2 | ========================= |
| 3 | |
| 4 | TurboJPEG/OSS can optionally be built with a Java Native Interface wrapper, |
| 5 | which allows the TurboJPEG/OSS dynamic library to be loaded and used directly |
| DRC | c5a4199 | 2011-02-08 06:54:36 +0000 | [diff] [blame] | 6 | from Java applications. The Java front end for this is defined in several |
| 7 | classes located under org/libjpegturbo/turbojpeg. The source code for these |
| 8 | Java classes is licensed under a BSD-style license, so the files can be |
| DRC | f8e0055 | 2011-02-04 11:06:36 +0000 | [diff] [blame] | 9 | incorporated directly into both open source and proprietary projects without |
| 10 | restriction. |
| 11 | |
| DRC | 2413cb8 | 2011-02-08 02:11:37 +0000 | [diff] [blame] | 12 | TJExample.java, which should also be located in the same directory as this |
| DRC | f8e0055 | 2011-02-04 11:06:36 +0000 | [diff] [blame] | 13 | README file, demonstrates how to use the TurboJPEG/OSS Java front end to |
| 14 | compress and decompress JPEG images in memory. |
| 15 | |
| DRC | c5a4199 | 2011-02-08 06:54:36 +0000 | [diff] [blame] | 16 | javac TJExample.java |
| DRC | f8e0055 | 2011-02-04 11:06:36 +0000 | [diff] [blame] | 17 | |
| 18 | builds .class files for both the front end and example code. |
| 19 | |
| 20 | |
| DRC | 7c99822 | 2011-03-10 07:25:41 +0000 | [diff] [blame^] | 21 | Performance Pitfalls |
| 22 | -------------------- |
| 23 | |
| 24 | The TurboJPEG Java front end defines several convenience methods which can |
| 25 | allocate image buffers or instantiate classes to hold the result of compress, |
| 26 | decompress, or transform operations. However, if you use these methods, then |
| 27 | be mindful of the amount of new data you are creating on the heap. It may be |
| 28 | necessary to manually invoke the garbage collector to prevent heap exhaustion |
| 29 | or to prevent performance degradation. Background garbage collection can kill |
| 30 | performance, particularly in a multi-threaded environment (Java pauses all |
| 31 | threads when the GC runs.) |
| 32 | |
| 33 | The Java front end always gives you the option of pre-allocating your own |
| 34 | source and destination buffers, which allows you to re-use these buffers for |
| 35 | compressing/decompressing multiple images. If the image sequence you are |
| 36 | compressing or decompressing consists of images of the same size, then |
| 37 | pre-allocating the buffers is recommended. |
| 38 | |
| 39 | |
| DRC | f8e0055 | 2011-02-04 11:06:36 +0000 | [diff] [blame] | 40 | Note for OS X users |
| 41 | ------------------- |
| 42 | |
| 43 | /usr/lib, the directory under which libturbojpeg.dylib is installed on Mac |
| 44 | systems, is not part of the normal Java library path. Thus, when running a |
| 45 | Java application that uses TurboJPEG/OSS on Mac systems, you will need to pass |
| 46 | an argument of -Djava.library.path=/usr/lib to java. |
| DRC | ed6526f | 2011-02-05 05:41:18 +0000 | [diff] [blame] | 47 | |
| 48 | |
| 49 | Note for Solaris users |
| 50 | ---------------------- |
| 51 | |
| 52 | /opt/libjpeg-turbo/lib, the directory under which libturbojpeg.so is installed |
| 53 | on Solaris systems, is not part of the normal Java library path. Thus, when |
| 54 | running a Java application that uses TurboJPEG/OSS on Solaris systems, you will |
| 55 | need to pass an argument of -Djava.library.path=/opt/libjpeg-turbo/lib to java. |
| 56 | If using a 64-bit data model, then instead pass an argument of |
| 57 | -Djava.library.path=/opt/libjpeg-turbo/lib/amd64 to use the 64-bit version of |
| 58 | libturbojpeg.so. |
| DRC | f2214c2 | 2011-02-05 05:51:46 +0000 | [diff] [blame] | 59 | |
| 60 | |
| 61 | Note for MinGW users |
| 62 | -------------------- |
| 63 | |
| 64 | When libjpeg-turbo is built with MinGW, the TurboJPEG/OSS dynamic library is |
| 65 | named libturbojpeg.dll instead of turbojpeg.dll. This is in keeping with the |
| 66 | convention of MinGW, and it also avoids a filename conflict when the GCC and |
| 67 | Visual C++ versions of the libjpeg-turbo SDK are installed on the same system. |
| 68 | However, the TurboJPEG/OSS JNI wrapper will not work on Windows unless the DLL |
| 69 | is named turbojpeg.dll. You can work around this by renaming the DLL or by |
| DRC | 2413cb8 | 2011-02-08 02:11:37 +0000 | [diff] [blame] | 70 | simply changing the LoadLibrary() calls in TurboJPEG.java so that they load |
| DRC | f2214c2 | 2011-02-05 05:51:46 +0000 | [diff] [blame] | 71 | "libturbojpeg" instead of "turbojpeg". |