Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
Small JPEG Decoder Library v0.93b Dec. 28, 2001 Copyright (C) 1994-2000 Rich Geldreich web: http://www.voicenet.com/~richgel email: firstname.lastname@example.org --- Introduction This C++ library decodes JPEG images. It's not the most full-featured JPEG library available, but it's relatively fast, completely free (LGPL license), uses little memory, and should be easy to understand and further optimize (mostly because it's so small: the entire library is only a few thousand lines long). The very common Huffman DCT-based sequential and progressive modes of operation are supported. This library only handles JPEG decompression, upsampling, and colorspace conversion. It does not handle pixel format conversion, quantization, dithering, etc. --- Who's this library for? If your application's input set is limited in some way (say, you're making a game or some other app that has prepared resources), this library may suite your needs. This library may also prove useful to those that want to read JPEG images on very small 32-bit platforms or embedded devices. See the porting section, below. (This code has been successfully ported to work on SH3, ARM, and MIPS CPU's.) I do not recommend using this library in a product that requires extremely high image quality or is going to be reading many arbitrary images supplied by the user, unless you know exactly what you're doing. The library does not support the more rare sampling factors/colorspaces, and only uses a box filter to upsample the chrominance components. I have tested this particular implementation with over 175 megabytes of JPEG images from a variety of sources. Still, this is not a trivial piece of software, so please e-mail me if you find any bugs. --- Alternatives Intel has a free JPEG Library that is also quite fast, but they don't distribute the source: http://developer.intel.com/vtune/PERFLIBST/ijl/index.htm If you are creating a product that requires the highest quality and most compatibility I recommend using the Independent JPEG Group's free library (includes source): http://www.ijg.org --- Features Simple (very little code, especially when compared to other JPEG libraries) Free (LGPL license) A lot of optional MMX specific optimizations: IDCT (using Intel's free MMX IDCT module) Merged H2V2 upsampler/YCbCr->RGB conversion Fast "getbits" Supports the most common (widely used) image types: Grayscale YCbCr colorspace: H1V1, H1V2, H2V1, or H2V2 sampling factors Progressive images --- Instructions Make sure you have Visual C++ 6.0 Service Pack 3 or higher. Load the workspace file, located at jpgd/jpgd.dsw. The example console mode program, jpg2tga, requires two parameters for it to do anything: a source filename (a valid JPEG image), and a destination filename (TGA). Example: jpg2tga input.jpg output.tga The image input.jpg will be written to ouput.tga. You may then view output.tga to verify that everything worked as expected. There are a number of useful test images in the "test_images" folder that can be used to help verify that the decoder is working properly. Notes: I hardcoded the "use_mmx" parameter to true in the jpeg_decoder constructor call.. If you don't have an MMX capable processor you will need to change this code. (A production program should check if the processor supports MMX at run-time and adjust this parameter accordingly.) You should be able to compile and link using VC++ 5.0 if you remake the projects/workspace. --- Decoder Streams To decode JPEG streams straight from memory, or from some other source, study the jpeg_decoder_stream class which is defined in jpegdecoder.h. All data input is handled through an object which has this interface as its base class. An example decoder stream class that reads JPEG files from standard FILE streams is included (see jpeg_decoder_file_stream). The jpg2tga example program uses this decoder stream class. --- Porting I've modified the library so it's much easier to selectively remove the inline x86 assembler and MMX specific code. See the following macros in jpegdecoder.h: #define SUPPORT_X86ASM #define SUPPORT_MMX --- Intel C/C++ Compiler Notes: To use the Intel C/C++ Compiler (v4.0 or higher): Make sure the "Intel C/C++ Compiler" checkbox is checked in the "Select Compiler" tool. If it's not, the h2v2.cpp module will not include the MMX implementation. The h2v2.obj module in the included libs was compiled with the Intel Compiler-- I hope this causes no trouble for those that don't have this product. It shouldn't, but if it does, just recompile. For some reason, the get_bits_2_mmx() method isn't inlined properly by ICC, causing a crash in Release builds. This is why all modules except h2v2.cpp have the _USE_NON_INTEL_COMPILER symbol defined. For now, if you must use ICC to compile the library, either disable inlining or don't define the SUPPORT_MMX symbol (jpgdecoder.h). --- Partial Update History v.93a: Fixed dumb bug in the decode_next_row functions that could cause bogus non-zero coefficients from leaking through in rare cases. v.93: prep_in_buffer() now saves/restores the MMX state before the jpeg_decoder_stream's read() method is called. Moved a lot of the inline asm/MMX code to jpegdecoder.inl to simplify the main header file. Added the SUPPORT_X86ASM and SUPPORT_MMX defines, to ease porting to non-x86 platforms (see the top of jpegdecoder.h). v.92: Removed Intel's old MMX IDCT module, replaced with a newer, free module from their web site that was specifically designed for JPEG. I have detected no overflow problems with this IDCT. Rewrote the MMX intrinsic code in the h2v2.cpp module. Should be faster and more accurate now. Added MMX specific getbits()/Huffman decoding methods. Coefficient decoding is the main bottleneck (approximately 50%!) when MMX is enabled so it must be done quickly. Changed main decoder so it does not clear the entire coefficient buffer every row. This was really slowing the entire decoder down! Changed merged upsampling/colorspace conversion methods to write the destination pixels to a different buffer. Also changed the RGB output format from 3 bytes/pixel to 4 bytes/pixel (more efficient for MMX code to write). --- History Some years ago, a friend (Matt Pritchard, now with Ensemble Studios) and I wrote a 16-bit real mode DOS image viewer named "PowerView" (PV). Matt convinced me that we needed to add JPEG support -- no small feat, especially considering that at the time (1994) JPEG was still rather new. The Independent JPEG Group's (www.ijg.org) library was definitely an option, but its sheer bulk seemed like it would have broken PV. (PV's memory situation was bleak: less than ~500k for all code/near and far data. It supported EMS/XMS, but only for special cases. Things got so bad that I had to use Borland's run-time code swapping/paging system to free up low RAM. Modifying the IJG code to handle this reliably seemed like much more trouble than it was worth.) Also, incorporating so much of someone else's code was sure to make the program less reliable, overall. We also wanted to stand out from the crowd, so I decided to create our own implementation. Approximately one week later, the baseline decoder was working. The upsampling/colorspace conversion code, Huffman decoder, and IDCT modules where written entirely in real-mode assembler. The IDCT module performed no multiplies, just lots of overlapped/pipelined, 32-bit adds from EMS memory lookup tables. (Each 32-bit add summed two individual 16-bit quantities.) It also employed an interesting "fast path" optimization: using macros, an individual IDCT was created for each possible input case because many AC coefficients are 0 after quantization. (I will probably port this IDCT to 32-bit code and release it soon. It performs a lot of table lookups to a 64k buffer, so I wonder how well it will perform on today's machines.) Much later on, after the web became very popular, I added support for progressive images. A short time after, I wrote a rather complete JPEG encoder from scratch. This code will be much easier to port because I wrote it keeping portability in mind. I'm probably going to release this code within the next few months. --- Future Changes Partial list: I would like to replace the IJG's integer IDCT module (named IDCT.CPP in this lib) with something else, because it's copyrighted by Thomas G. Lane of the IJG. I am not sure if including this small bit of code requires the user to include the usual "Parts of this code where written by the IJG...", etc. statement in their product documentation or "About" dialog. Possibly add AMD 3D-Now or P3 specific modules. Add bilinear filtering to the upsampler/colorspace conversion code. Right now, only a simple box filter is implemented, which can sometimes cause noticeable artifacts. It would be interesting to see how practical it is to use Direct3D for upsampling and colorspace conversion. Upsampling could be done by using SetRenderTarget() with filtered texture mapping, and various blending operations for colorspace conversion. I'm almost positive this is doable, but I'm not sure if 8-bits per component is really enough. --- License Except for those modules which are copyrighted by others, this library is covered under the LGPL license. Please see license.txt. idct.cpp is from the IJG. It's copyrighted by Thomas G. Lane. Please see the top of this file for more information.