| 1 |
TurboJPEG Java Wrapper |
| 2 |
====================== |
| 3 |
|
| 4 |
The TurboJPEG shared library can optionally be built with a Java Native |
| 5 |
Interface wrapper, which allows the library to be loaded and used directly from |
| 6 |
Java applications. The Java front end for this is defined in several classes |
| 7 |
located under org/libjpegturbo/turbojpeg. The source code for these Java |
| 8 |
classes is licensed under a BSD-style license, so the files can be incorporated |
| 9 |
directly into both open source and proprietary projects without restriction. A |
| 10 |
Java archive (JAR) file containing these classes is also shipped with the |
| 11 |
"official" distribution packages of libjpeg-turbo. |
| 12 |
|
| 13 |
TJComp.java, TJDecomp.java, and TJTran.java, which should be located in the |
| 14 |
same directory as this README file, demonstrate how to use the TurboJPEG Java |
| 15 |
API to compress, decompress, and transform JPEG images in memory. |
| 16 |
|
| 17 |
|
| 18 |
Performance Pitfalls |
| 19 |
-------------------- |
| 20 |
|
| 21 |
The TurboJPEG Java API defines several convenience methods that can allocate |
| 22 |
image buffers or instantiate classes to hold the result of compress, |
| 23 |
decompress, or transform operations. However, if you use these methods, then |
| 24 |
be mindful of the amount of new data you are creating on the heap. It may be |
| 25 |
necessary to manually invoke the garbage collector to prevent heap exhaustion |
| 26 |
or to prevent performance degradation. Background garbage collection can kill |
| 27 |
performance, particularly in a multi-threaded environment (Java pauses all |
| 28 |
threads when the GC runs.) |
| 29 |
|
| 30 |
The TurboJPEG Java API always gives you the option of pre-allocating your own |
| 31 |
source and destination buffers, which allows you to re-use those buffers for |
| 32 |
compressing/decompressing multiple images. If the image sequence you are |
| 33 |
compressing or decompressing consists of images of the same size, then |
| 34 |
pre-allocating the buffers is recommended. |
| 35 |
|
| 36 |
|
| 37 |
Installation Directory |
| 38 |
---------------------- |
| 39 |
|
| 40 |
The TurboJPEG Java Wrapper will look for the TurboJPEG JNI library |
| 41 |
(libturbojpeg.so, libturbojpeg.dylib, or turbojpeg.dll) in the system library |
| 42 |
paths or in any paths specified in LD_LIBRARY_PATH (Un*x), DYLD_LIBRARY_PATH |
| 43 |
(Mac), or PATH (Windows.) Failing this, on Un*x and Mac systems, the wrapper |
| 44 |
will look for the JNI library under the library directory configured when |
| 45 |
libjpeg-turbo was built. If that library directory is |
| 46 |
/opt/libjpeg-turbo/lib32, then /opt/libjpeg-turbo/lib64 is also searched, and |
| 47 |
vice versa. |
| 48 |
|
| 49 |
If you installed the JNI library into another directory, then you will need |
| 50 |
to pass an argument of -Djava.library.path={path_to_JNI_library} to java, or |
| 51 |
manipulate LD_LIBRARY_PATH, DYLD_LIBRARY_PATH, or PATH to include the directory |
| 52 |
containing the JNI library. |