diff --git a/Makefile.am b/Makefile.am index 81c6d6b9..43b5f98a 100644 --- a/Makefile.am +++ b/Makefile.am @@ -31,7 +31,7 @@ endif TSTHDRS = rrutil.h rrtimer.h -noinst_PROGRAMS = jpgtest jpegut cjpeg djpeg +noinst_PROGRAMS = jpgtest jpegut cjpeg djpeg jpegtran rdjpgcom wrjpgcom jpgtest_SOURCES = $(TSTHDRS) jpgtest.cxx bmp.h bmp.c @@ -56,3 +56,31 @@ djpeg_LDADD = $(top_srcdir)/libjpeg.la djpeg_CFLAGS = -DBMP_SUPPORTED -DGIF_SUPPORTED -DPPM_SUPPORTED \ -DTARGA_SUPPORTED + +jpegtran_SOURCES = jpegtran.c rdswitch.c cdjpeg.c transupp.c + +jpegtran_LDADD = $(top_srcdir)/libjpeg.la + +rdjpgcom_SOURCES = wrjpgcom.c + +rdjpgcom_LDADD = $(top_srcdir)/libjpeg.la + +wrjpgcom_SOURCES = wrjpgcom.c + +wrjpgcom_LDADD = $(top_srcdir)/libjpeg.la + +test: cjpeg djpeg jpegtran + $(RM) testout* + $(top_srcdir)/jpegut + $(top_srcdir)/djpeg -dct int -ppm -outfile testout.ppm $(top_srcdir)/testorig.jpg + $(top_srcdir)/djpeg -dct int -bmp -colors 256 -outfile testout.bmp $(top_srcdir)/testorig.jpg + $(top_srcdir)/cjpeg -dct int -outfile testout.jpg $(top_srcdir)/testimg.ppm + $(top_srcdir)/djpeg -dct int -ppm -outfile testoutp.ppm $(top_srcdir)/testprog.jpg + $(top_srcdir)/cjpeg -dct int -progressive -opt -outfile testoutp.jpg $(top_srcdir)/testimg.ppm + $(top_srcdir)/jpegtran -outfile testoutt.jpg $(top_srcdir)/testprog.jpg + cmp $(top_srcdir)/testimg.ppm testout.ppm + cmp $(top_srcdir)/testimg.bmp testout.bmp + cmp $(top_srcdir)/testimg.jpg testout.jpg + cmp $(top_srcdir)/testimg.ppm testoutp.ppm + cmp $(top_srcdir)/testimgp.jpg testoutp.jpg + cmp $(top_srcdir)/testorig.jpg testoutt.jpg diff --git a/README_TigerVNC.txt b/README_TigerVNC.txt deleted file mode 100644 index c73070a6..00000000 --- a/README_TigerVNC.txt +++ /dev/null @@ -1,5 +0,0 @@ -This directory includes a copy of the Independent JPEG Group's JPEG -library (see the README file for more information). Not all the files -from the original distribution have been included into the TigerVNC -codebase. To obtain the original library, please see the README file, -section "ARCHIVE LOCATIONS". diff --git a/change.log b/change.log new file mode 100644 index 00000000..74102c0d --- /dev/null +++ b/change.log @@ -0,0 +1,217 @@ +CHANGE LOG for Independent JPEG Group's JPEG software + + +Version 6b 27-Mar-1998 +----------------------- + +jpegtran has new features for lossless image transformations (rotation +and flipping) as well as "lossless" reduction to grayscale. + +jpegtran now copies comments by default; it has a -copy switch to enable +copying all APPn blocks as well, or to suppress comments. (Formerly it +always suppressed comments and APPn blocks.) jpegtran now also preserves +JFIF version and resolution information. + +New decompressor library feature: COM and APPn markers found in the input +file can be saved in memory for later use by the application. (Before, +you had to code this up yourself with a custom marker processor.) + +There is an unused field "void * client_data" now in compress and decompress +parameter structs; this may be useful in some applications. + +JFIF version number information is now saved by the decoder and accepted by +the encoder. jpegtran uses this to copy the source file's version number, +to ensure "jpegtran -copy all" won't create bogus files that contain JFXX +extensions but claim to be version 1.01. Applications that generate their +own JFXX extension markers also (finally) have a supported way to cause the +encoder to emit JFIF version number 1.02. + +djpeg's trace mode reports JFIF 1.02 thumbnail images as such, rather +than as unknown APP0 markers. + +In -verbose mode, djpeg and rdjpgcom will try to print the contents of +APP12 markers as text. Some digital cameras store useful text information +in APP12 markers. + +Handling of truncated data streams is more robust: blocks beyond the one in +which the error occurs will be output as uniform gray, or left unchanged +if decoding a progressive JPEG. The appearance no longer depends on the +Huffman tables being used. + +Huffman tables are checked for validity much more carefully than before. + +To avoid the Unisys LZW patent, djpeg's GIF output capability has been +changed to produce "uncompressed GIFs", and cjpeg's GIF input capability +has been removed altogether. We're not happy about it either, but there +seems to be no good alternative. + +The configure script now supports building libjpeg as a shared library +on many flavors of Unix (all the ones that GNU libtool knows how to +build shared libraries for). Use "./configure --enable-shared" to +try this out. + +New jconfig file and makefiles for Microsoft Visual C++ and Developer Studio. +Also, a jconfig file and a build script for Metrowerks CodeWarrior +on Apple Macintosh. makefile.dj has been updated for DJGPP v2, and there +are miscellaneous other minor improvements in the makefiles. + +jmemmac.c now knows how to create temporary files following Mac System 7 +conventions. + +djpeg's -map switch is now able to read raw-format PPM files reliably. + +cjpeg -progressive -restart no longer generates any unnecessary DRI markers. + +Multiple calls to jpeg_simple_progression for a single JPEG object +no longer leak memory. + + +Version 6a 7-Feb-96 +-------------------- + +Library initialization sequence modified to detect version mismatches +and struct field packing mismatches between library and calling application. +This change requires applications to be recompiled, but does not require +any application source code change. + +All routine declarations changed to the style "GLOBAL(type) name ...", +that is, GLOBAL, LOCAL, METHODDEF, EXTERN are now macros taking the +routine's return type as an argument. This makes it possible to add +Microsoft-style linkage keywords to all the routines by changing just +these macros. Note that any application code that was using these macros +will have to be changed. + +DCT coefficient quantization tables are now stored in normal array order +rather than zigzag order. Application code that calls jpeg_add_quant_table, +or otherwise manipulates quantization tables directly, will need to be +changed. If you need to make such code work with either older or newer +versions of the library, a test like "#if JPEG_LIB_VERSION >= 61" is +recommended. + +djpeg's trace capability now dumps DQT tables in natural order, not zigzag +order. This allows the trace output to be made into a "-qtables" file +more easily. + +New system-dependent memory manager module for use on Apple Macintosh. + +Fix bug in cjpeg's -smooth option: last one or two scanlines would be +duplicates of the prior line unless the image height mod 16 was 1 or 2. + +Repair minor problems in VMS, BCC, MC6 makefiles. + +New configure script based on latest GNU Autoconf. + +Correct the list of include files needed by MetroWerks C for ccommand(). + +Numerous small documentation updates. + + +Version 6 2-Aug-95 +------------------- + +Progressive JPEG support: library can read and write full progressive JPEG +files. A "buffered image" mode supports incremental decoding for on-the-fly +display of progressive images. Simply recompiling an existing IJG-v5-based +decoder with v6 should allow it to read progressive files, though of course +without any special progressive display. + +New "jpegtran" application performs lossless transcoding between different +JPEG formats; primarily, it can be used to convert baseline to progressive +JPEG and vice versa. In support of jpegtran, the library now allows lossless +reading and writing of JPEG files as DCT coefficient arrays. This ability +may be of use in other applications. + +Notes for programmers: +* We changed jpeg_start_decompress() to be able to suspend; this makes all +decoding modes available to suspending-input applications. However, +existing applications that use suspending input will need to be changed +to check the return value from jpeg_start_decompress(). You don't need to +do anything if you don't use a suspending data source. +* We changed the interface to the virtual array routines: access_virt_array +routines now take a count of the number of rows to access this time. The +last parameter to request_virt_array routines is now interpreted as the +maximum number of rows that may be accessed at once, but not necessarily +the height of every access. + + +Version 5b 15-Mar-95 +--------------------- + +Correct bugs with grayscale images having v_samp_factor > 1. + +jpeg_write_raw_data() now supports output suspension. + +Correct bugs in "configure" script for case of compiling in +a directory other than the one containing the source files. + +Repair bug in jquant1.c: sometimes didn't use as many colors as it could. + +Borland C makefile and jconfig file work under either MS-DOS or OS/2. + +Miscellaneous improvements to documentation. + + +Version 5a 7-Dec-94 +-------------------- + +Changed color conversion roundoff behavior so that grayscale values are +represented exactly. (This causes test image files to change.) + +Make ordered dither use 16x16 instead of 4x4 pattern for a small quality +improvement. + +New configure script based on latest GNU Autoconf. +Fix configure script to handle CFLAGS correctly. +Rename *.auto files to *.cfg, so that configure script still works if +file names have been truncated for DOS. + +Fix bug in rdbmp.c: didn't allow for extra data between header and image. + +Modify rdppm.c/wrppm.c to handle 2-byte raw PPM/PGM formats for 12-bit data. + +Fix several bugs in rdrle.c. + +NEED_SHORT_EXTERNAL_NAMES option was broken. + +Revise jerror.h/jerror.c for more flexibility in message table. + +Repair oversight in jmemname.c NO_MKTEMP case: file could be there +but unreadable. + + +Version 5 24-Sep-94 +-------------------- + +Version 5 represents a nearly complete redesign and rewrite of the IJG +software. Major user-visible changes include: + * Automatic configuration simplifies installation for most Unix systems. + * A range of speed vs. image quality tradeoffs are supported. + This includes resizing of an image during decompression: scaling down + by a factor of 1/2, 1/4, or 1/8 is handled very efficiently. + * New programs rdjpgcom and wrjpgcom allow insertion and extraction + of text comments in a JPEG file. + +The application programmer's interface to the library has changed completely. +Notable improvements include: + * We have eliminated the use of callback routines for handling the + uncompressed image data. The application now sees the library as a + set of routines that it calls to read or write image data on a + scanline-by-scanline basis. + * The application image data is represented in a conventional interleaved- + pixel format, rather than as a separate array for each color channel. + This can save a copying step in many programs. + * The handling of compressed data has been cleaned up: the application can + supply routines to source or sink the compressed data. It is possible to + suspend processing on source/sink buffer overrun, although this is not + supported in all operating modes. + * All static state has been eliminated from the library, so that multiple + instances of compression or decompression can be active concurrently. + * JPEG abbreviated datastream formats are supported, ie, quantization and + Huffman tables can be stored separately from the image data. + * And not only that, but the documentation of the library has improved + considerably! + + +The last widely used release before the version 5 rewrite was version 4A of +18-Feb-93. Change logs before that point have been discarded, since they +are not of much interest after the rewrite. diff --git a/coderules.doc b/coderules.doc new file mode 100644 index 00000000..0ab5d9bd --- /dev/null +++ b/coderules.doc @@ -0,0 +1,118 @@ +IJG JPEG LIBRARY: CODING RULES + +Copyright (C) 1991-1996, Thomas G. Lane. +This file is part of the Independent JPEG Group's software. +For conditions of distribution and use, see the accompanying README file. + + +Since numerous people will be contributing code and bug fixes, it's important +to establish a common coding style. The goal of using similar coding styles +is much more important than the details of just what that style is. + +In general we follow the recommendations of "Recommended C Style and Coding +Standards" revision 6.1 (Cannon et al. as modified by Spencer, Keppel and +Brader). This document is available in the IJG FTP archive (see +jpeg/doc/cstyle.ms.tbl.Z, or cstyle.txt.Z for those without nroff/tbl). + +Block comments should be laid out thusly: + +/* + * Block comments in this style. + */ + +We indent statements in K&R style, e.g., + if (test) { + then-part; + } else { + else-part; + } +with two spaces per indentation level. (This indentation convention is +handled automatically by GNU Emacs and many other text editors.) + +Multi-word names should be written in lower case with underscores, e.g., +multi_word_name (not multiWordName). Preprocessor symbols and enum constants +are similar but upper case (MULTI_WORD_NAME). Names should be unique within +the first fifteen characters. (On some older systems, global names must be +unique within six characters. We accommodate this without cluttering the +source code by using macros to substitute shorter names.) + +We use function prototypes everywhere; we rely on automatic source code +transformation to feed prototype-less C compilers. Transformation is done +by the simple and portable tool 'ansi2knr.c' (courtesy of Ghostscript). +ansi2knr is not very bright, so it imposes a format requirement on function +declarations: the function name MUST BEGIN IN COLUMN 1. Thus all functions +should be written in the following style: + +LOCAL(int *) +function_name (int a, char *b) +{ + code... +} + +Note that each function definition must begin with GLOBAL(type), LOCAL(type), +or METHODDEF(type). These macros expand to "static type" or just "type" as +appropriate. They provide a readable indication of the routine's usage and +can readily be changed for special needs. (For instance, special linkage +keywords can be inserted for use in Windows DLLs.) + +ansi2knr does not transform method declarations (function pointers in +structs). We handle these with a macro JMETHOD, defined as + #ifdef HAVE_PROTOTYPES + #define JMETHOD(type,methodname,arglist) type (*methodname) arglist + #else + #define JMETHOD(type,methodname,arglist) type (*methodname) () + #endif +which is used like this: + struct function_pointers { + JMETHOD(void, init_entropy_encoder, (int somearg, jparms *jp)); + JMETHOD(void, term_entropy_encoder, (void)); + }; +Note the set of parentheses surrounding the parameter list. + +A similar solution is used for forward and external function declarations +(see the EXTERN and JPP macros). + +If the code is to work on non-ANSI compilers, we cannot rely on a prototype +declaration to coerce actual parameters into the right types. Therefore, use +explicit casts on actual parameters whenever the actual parameter type is not +identical to the formal parameter. Beware of implicit conversions to "int". + +It seems there are some non-ANSI compilers in which the sizeof() operator +is defined to return int, yet size_t is defined as long. Needless to say, +this is brain-damaged. Always use the SIZEOF() macro in place of sizeof(), +so that the result is guaranteed to be of type size_t. + + +The JPEG library is intended to be used within larger programs. Furthermore, +we want it to be reentrant so that it can be used by applications that process +multiple images concurrently. The following rules support these requirements: + +1. Avoid direct use of file I/O, "malloc", error report printouts, etc; +pass these through the common routines provided. + +2. Minimize global namespace pollution. Functions should be declared static +wherever possible. (Note that our method-based calling conventions help this +a lot: in many modules only the initialization function will ever need to be +called directly, so only that function need be externally visible.) All +global function names should begin with "jpeg_", and should have an +abbreviated name (unique in the first six characters) substituted by macro +when NEED_SHORT_EXTERNAL_NAMES is set. + +3. Don't use global variables; anything that must be used in another module +should be in the common data structures. + +4. Don't use static variables except for read-only constant tables. Variables +that should be private to a module can be placed into private structures (see +the system architecture document, structure.doc). + +5. Source file names should begin with "j" for files that are part of the +library proper; source files that are not part of the library, such as cjpeg.c +and djpeg.c, do not begin with "j". Keep source file names to eight +characters (plus ".c" or ".h", etc) to make life easy for MS-DOSers. Keep +compression and decompression code in separate source files --- some +applications may want only one half of the library. + +Note: these rules (particularly #4) are not followed religiously in the +modules that are used in cjpeg/djpeg but are not part of the JPEG library +proper. Those modules are not really intended to be used in other +applications. diff --git a/example.c b/example.c new file mode 100644 index 00000000..7fc354f0 --- /dev/null +++ b/example.c @@ -0,0 +1,433 @@ +/* + * example.c + * + * This file illustrates how to use the IJG code as a subroutine library + * to read or write JPEG image files. You should look at this code in + * conjunction with the documentation file libjpeg.doc. + * + * This code will not do anything useful as-is, but it may be helpful as a + * skeleton for constructing routines that call the JPEG library. + * + * We present these routines in the same coding style used in the JPEG code + * (ANSI function definitions, etc); but you are of course free to code your + * routines in a different style if you prefer. + */ + +#include + +/* + * Include file for users of JPEG library. + * You will need to have included system headers that define at least + * the typedefs FILE and size_t before you can include jpeglib.h. + * (stdio.h is sufficient on ANSI-conforming systems.) + * You may also wish to include "jerror.h". + */ + +#include "jpeglib.h" + +/* + * is used for the optional error recovery mechanism shown in + * the second part of the example. + */ + +#include + + + +/******************** JPEG COMPRESSION SAMPLE INTERFACE *******************/ + +/* This half of the example shows how to feed data into the JPEG compressor. + * We present a minimal version that does not worry about refinements such + * as error recovery (the JPEG code will just exit() if it gets an error). + */ + + +/* + * IMAGE DATA FORMATS: + * + * The standard input image format is a rectangular array of pixels, with + * each pixel having the same number of "component" values (color channels). + * Each pixel row is an array of JSAMPLEs (which typically are unsigned chars). + * If you are working with color data, then the color values for each pixel + * must be adjacent in the row; for example, R,G,B,R,G,B,R,G,B,... for 24-bit + * RGB color. + * + * For this example, we'll assume that this data structure matches the way + * our application has stored the image in memory, so we can just pass a + * pointer to our image buffer. In particular, let's say that the image is + * RGB color and is described by: + */ + +extern JSAMPLE * image_buffer; /* Points to large array of R,G,B-order data */ +extern int image_height; /* Number of rows in image */ +extern int image_width; /* Number of columns in image */ + + +/* + * Sample routine for JPEG compression. We assume that the target file name + * and a compression quality factor are passed in. + */ + +GLOBAL(void) +write_JPEG_file (char * filename, int quality) +{ + /* This struct contains the JPEG compression parameters and pointers to + * working space (which is allocated as needed by the JPEG library). + * It is possible to have several such structures, representing multiple + * compression/decompression processes, in existence at once. We refer + * to any one struct (and its associated working data) as a "JPEG object". + */ + struct jpeg_compress_struct cinfo; + /* This struct represents a JPEG error handler. It is declared separately + * because applications often want to supply a specialized error handler + * (see the second half of this file for an example). But here we just + * take the easy way out and use the standard error handler, which will + * print a message on stderr and call exit() if compression fails. + * Note that this struct must live as long as the main JPEG parameter + * struct, to avoid dangling-pointer problems. + */ + struct jpeg_error_mgr jerr; + /* More stuff */ + FILE * outfile; /* target file */ + JSAMPROW row_pointer[1]; /* pointer to JSAMPLE row[s] */ + int row_stride; /* physical row width in image buffer */ + + /* Step 1: allocate and initialize JPEG compression object */ + + /* We have to set up the error handler first, in case the initialization + * step fails. (Unlikely, but it could happen if you are out of memory.) + * This routine fills in the contents of struct jerr, and returns jerr's + * address which we place into the link field in cinfo. + */ + cinfo.err = jpeg_std_error(&jerr); + /* Now we can initialize the JPEG compression object. */ + jpeg_create_compress(&cinfo); + + /* Step 2: specify data destination (eg, a file) */ + /* Note: steps 2 and 3 can be done in either order. */ + + /* Here we use the library-supplied code to send compressed data to a + * stdio stream. You can also write your own code to do something else. + * VERY IMPORTANT: use "b" option to fopen() if you are on a machine that + * requires it in order to write binary files. + */ + if ((outfile = fopen(filename, "wb")) == NULL) { + fprintf(stderr, "can't open %s\n", filename); + exit(1); + } + jpeg_stdio_dest(&cinfo, outfile); + + /* Step 3: set parameters for compression */ + + /* First we supply a description of the input image. + * Four fields of the cinfo struct must be filled in: + */ + cinfo.image_width = image_width; /* image width and height, in pixels */ + cinfo.image_height = image_height; + cinfo.input_components = 3; /* # of color components per pixel */ + cinfo.in_color_space = JCS_RGB; /* colorspace of input image */ + /* Now use the library's routine to set default compression parameters. + * (You must set at least cinfo.in_color_space before calling this, + * since the defaults depend on the source color space.) + */ + jpeg_set_defaults(&cinfo); + /* Now you can set any non-default parameters you wish to. + * Here we just illustrate the use of quality (quantization table) scaling: + */ + jpeg_set_quality(&cinfo, quality, TRUE /* limit to baseline-JPEG values */); + + /* Step 4: Start compressor */ + + /* TRUE ensures that we will write a complete interchange-JPEG file. + * Pass TRUE unless you are very sure of what you're doing. + */ + jpeg_start_compress(&cinfo, TRUE); + + /* Step 5: while (scan lines remain to be written) */ + /* jpeg_write_scanlines(...); */ + + /* Here we use the library's state variable cinfo.next_scanline as the + * loop counter, so that we don't have to keep track ourselves. + * To keep things simple, we pass one scanline per call; you can pass + * more if you wish, though. + */ + row_stride = image_width * 3; /* JSAMPLEs per row in image_buffer */ + + while (cinfo.next_scanline < cinfo.image_height) { + /* jpeg_write_scanlines expects an array of pointers to scanlines. + * Here the array is only one element long, but you could pass + * more than one scanline at a time if that's more convenient. + */ + row_pointer[0] = & image_buffer[cinfo.next_scanline * row_stride]; + (void) jpeg_write_scanlines(&cinfo, row_pointer, 1); + } + + /* Step 6: Finish compression */ + + jpeg_finish_compress(&cinfo); + /* After finish_compress, we can close the output file. */ + fclose(outfile); + + /* Step 7: release JPEG compression object */ + + /* This is an important step since it will release a good deal of memory. */ + jpeg_destroy_compress(&cinfo); + + /* And we're done! */ +} + + +/* + * SOME FINE POINTS: + * + * In the above loop, we ignored the return value of jpeg_write_scanlines, + * which is the number of scanlines actually written. We could get away + * with this because we were only relying on the value of cinfo.next_scanline, + * which will be incremented correctly. If you maintain additional loop + * variables then you should be careful to increment them properly. + * Actually, for output to a stdio stream you needn't worry, because + * then jpeg_write_scanlines will write all the lines passed (or else exit + * with a fatal error). Partial writes can only occur if you use a data + * destination module that can demand suspension of the compressor. + * (If you don't know what that's for, you don't need it.) + * + * If the compressor requires full-image buffers (for entropy-coding + * optimization or a multi-scan JPEG file), it will create temporary + * files for anything that doesn't fit within the maximum-memory setting. + * (Note that temp files are NOT needed if you use the default parameters.) + * On some systems you may need to set up a signal handler to ensure that + * temporary files are deleted if the program is interrupted. See libjpeg.doc. + * + * Scanlines MUST be supplied in top-to-bottom order if you want your JPEG + * files to be compatible with everyone else's. If you cannot readily read + * your data in that order, you'll need an intermediate array to hold the + * image. See rdtarga.c or rdbmp.c for examples of handling bottom-to-top + * source data using the JPEG code's internal virtual-array mechanisms. + */ + + + +/******************** JPEG DECOMPRESSION SAMPLE INTERFACE *******************/ + +/* This half of the example shows how to read data from the JPEG decompressor. + * It's a bit more refined than the above, in that we show: + * (a) how to modify the JPEG library's standard error-reporting behavior; + * (b) how to allocate workspace using the library's memory manager. + * + * Just to make this example a little different from the first one, we'll + * assume that we do not intend to put the whole image into an in-memory + * buffer, but to send it line-by-line someplace else. We need a one- + * scanline-high JSAMPLE array as a work buffer, and we will let the JPEG + * memory manager allocate it for us. This approach is actually quite useful + * because we don't need to remember to deallocate the buffer separately: it + * will go away automatically when the JPEG object is cleaned up. + */ + + +/* + * ERROR HANDLING: + * + * The JPEG library's standard error handler (jerror.c) is divided into + * several "methods" which you can override individually. This lets you + * adjust the behavior without duplicating a lot of code, which you might + * have to update with each future release. + * + * Our example here shows how to override the "error_exit" method so that + * control is returned to the library's caller when a fatal error occurs, + * rather than calling exit() as the standard error_exit method does. + * + * We use C's setjmp/longjmp facility to return control. This means that the + * routine which calls the JPEG library must first execute a setjmp() call to + * establish the return point. We want the replacement error_exit to do a + * longjmp(). But we need to make the setjmp buffer accessible to the + * error_exit routine. To do this, we make a private extension of the + * standard JPEG error handler object. (If we were using C++, we'd say we + * were making a subclass of the regular error handler.) + * + * Here's the extended error handler struct: + */ + +struct my_error_mgr { + struct jpeg_error_mgr pub; /* "public" fields */ + + jmp_buf setjmp_buffer; /* for return to caller */ +}; + +typedef struct my_error_mgr * my_error_ptr; + +/* + * Here's the routine that will replace the standard error_exit method: + */ + +METHODDEF(void) +my_error_exit (j_common_ptr cinfo) +{ + /* cinfo->err really points to a my_error_mgr struct, so coerce pointer */ + my_error_ptr myerr = (my_error_ptr) cinfo->err; + + /* Always display the message. */ + /* We could postpone this until after returning, if we chose. */ + (*cinfo->err->output_message) (cinfo); + + /* Return control to the setjmp point */ + longjmp(myerr->setjmp_buffer, 1); +} + + +/* + * Sample routine for JPEG decompression. We assume that the source file name + * is passed in. We want to return 1 on success, 0 on error. + */ + + +GLOBAL(int) +read_JPEG_file (char * filename) +{ + /* This struct contains the JPEG decompression parameters and pointers to + * working space (which is allocated as needed by the JPEG library). + */ + struct jpeg_decompress_struct cinfo; + /* We use our private extension JPEG error handler. + * Note that this struct must live as long as the main JPEG parameter + * struct, to avoid dangling-pointer problems. + */ + struct my_error_mgr jerr; + /* More stuff */ + FILE * infile; /* source file */ + JSAMPARRAY buffer; /* Output row buffer */ + int row_stride; /* physical row width in output buffer */ + + /* In this example we want to open the input file before doing anything else, + * so that the setjmp() error recovery below can assume the file is open. + * VERY IMPORTANT: use "b" option to fopen() if you are on a machine that + * requires it in order to read binary files. + */ + + if ((infile = fopen(filename, "rb")) == NULL) { + fprintf(stderr, "can't open %s\n", filename); + return 0; + } + + /* Step 1: allocate and initialize JPEG decompression object */ + + /* We set up the normal JPEG error routines, then override error_exit. */ + cinfo.err = jpeg_std_error(&jerr.pub); + jerr.pub.error_exit = my_error_exit; + /* Establish the setjmp return context for my_error_exit to use. */ + if (setjmp(jerr.setjmp_buffer)) { + /* If we get here, the JPEG code has signaled an error. + * We need to clean up the JPEG object, close the input file, and return. + */ + jpeg_destroy_decompress(&cinfo); + fclose(infile); + return 0; + } + /* Now we can initialize the JPEG decompression object. */ + jpeg_create_decompress(&cinfo); + + /* Step 2: specify data source (eg, a file) */ + + jpeg_stdio_src(&cinfo, infile); + + /* Step 3: read file parameters with jpeg_read_header() */ + + (void) jpeg_read_header(&cinfo, TRUE); + /* We can ignore the return value from jpeg_read_header since + * (a) suspension is not possible with the stdio data source, and + * (b) we passed TRUE to reject a tables-only JPEG file as an error. + * See libjpeg.doc for more info. + */ + + /* Step 4: set parameters for decompression */ + + /* In this example, we don't need to change any of the defaults set by + * jpeg_read_header(), so we do nothing here. + */ + + /* Step 5: Start decompressor */ + + (void) jpeg_start_decompress(&cinfo); + /* We can ignore the return value since suspension is not possible + * with the stdio data source. + */ + + /* We may need to do some setup of our own at this point before reading + * the data. After jpeg_start_decompress() we have the correct scaled + * output image dimensions available, as well as the output colormap + * if we asked for color quantization. + * In this example, we need to make an output work buffer of the right size. + */ + /* JSAMPLEs per row in output buffer */ + row_stride = cinfo.output_width * cinfo.output_components; + /* Make a one-row-high sample array that will go away when done with image */ + buffer = (*cinfo.mem->alloc_sarray) + ((j_common_ptr) &cinfo, JPOOL_IMAGE, row_stride, 1); + + /* Step 6: while (scan lines remain to be read) */ + /* jpeg_read_scanlines(...); */ + + /* Here we use the library's state variable cinfo.output_scanline as the + * loop counter, so that we don't have to keep track ourselves. + */ + while (cinfo.output_scanline < cinfo.output_height) { + /* jpeg_read_scanlines expects an array of pointers to scanlines. + * Here the array is only one element long, but you could ask for + * more than one scanline at a time if that's more convenient. + */ + (void) jpeg_read_scanlines(&cinfo, buffer, 1); + /* Assume put_scanline_someplace wants a pointer and sample count. */ + put_scanline_someplace(buffer[0], row_stride); + } + + /* Step 7: Finish decompression */ + + (void) jpeg_finish_decompress(&cinfo); + /* We can ignore the return value since suspension is not possible + * with the stdio data source. + */ + + /* Step 8: Release JPEG decompression object */ + + /* This is an important step since it will release a good deal of memory. */ + jpeg_destroy_decompress(&cinfo); + + /* After finish_decompress, we can close the input file. + * Here we postpone it until after no more JPEG errors are possible, + * so as to simplify the setjmp error logic above. (Actually, I don't + * think that jpeg_destroy can do an error exit, but why assume anything...) + */ + fclose(infile); + + /* At this point you may want to check to see whether any corrupt-data + * warnings occurred (test whether jerr.pub.num_warnings is nonzero). + */ + + /* And we're done! */ + return 1; +} + + +/* + * SOME FINE POINTS: + * + * In the above code, we ignored the return value of jpeg_read_scanlines, + * which is the number of scanlines actually read. We could get away with + * this because we asked for only one line at a time and we weren't using + * a suspending data source. See libjpeg.doc for more info. + * + * We cheated a bit by calling alloc_sarray() after jpeg_start_decompress(); + * we should have done it beforehand to ensure that the space would be + * counted against the JPEG max_memory setting. In some systems the above + * code would risk an out-of-memory error. However, in general we don't + * know the output image dimensions before jpeg_start_decompress(), unless we + * call jpeg_calc_output_dimensions(). See libjpeg.doc for more about this. + * + * Scanlines are returned in the same order as they appear in the JPEG file, + * which is standardly top-to-bottom. If you must emit data bottom-to-top, + * you can use one of the virtual arrays provided by the JPEG memory manager + * to invert the data. See wrbmp.c for an example. + * + * As with compression, some operating modes may require temporary files. + * On some systems you may need to set up a signal handler to ensure that + * temporary files are deleted if the program is interrupted. See libjpeg.doc. + */ diff --git a/filelist.doc b/filelist.doc new file mode 100644 index 00000000..e14982ca --- /dev/null +++ b/filelist.doc @@ -0,0 +1,210 @@ +IJG JPEG LIBRARY: FILE LIST + +Copyright (C) 1994-1998, Thomas G. Lane. +This file is part of the Independent JPEG Group's software. +For conditions of distribution and use, see the accompanying README file. + + +Here is a road map to the files in the IJG JPEG distribution. The +distribution includes the JPEG library proper, plus two application +programs ("cjpeg" and "djpeg") which use the library to convert JPEG +files to and from some other popular image formats. A third application +"jpegtran" uses the library to do lossless conversion between different +variants of JPEG. There are also two stand-alone applications, +"rdjpgcom" and "wrjpgcom". + + +THE JPEG LIBRARY +================ + +Include files: + +jpeglib.h JPEG library's exported data and function declarations. +jconfig.h Configuration declarations. Note: this file is not present + in the distribution; it is generated during installation. +jmorecfg.h Additional configuration declarations; need not be changed + for a standard installation. +jerror.h Declares JPEG library's error and trace message codes. +jinclude.h Central include file used by all IJG .c files to reference + system include files. +jpegint.h JPEG library's internal data structures. +jchuff.h Private declarations for Huffman encoder modules. +jdhuff.h Private declarations for Huffman decoder modules. +jdct.h Private declarations for forward & reverse DCT subsystems. +jmemsys.h Private declarations for memory management subsystem. +jversion.h Version information. + +Applications using the library should include jpeglib.h (which in turn +includes jconfig.h and jmorecfg.h). Optionally, jerror.h may be included +if the application needs to reference individual JPEG error codes. The +other include files are intended for internal use and would not normally +be included by an application program. (cjpeg/djpeg/etc do use jinclude.h, +since its function is to improve portability of the whole IJG distribution. +Most other applications will directly include the system include files they +want, and hence won't need jinclude.h.) + + +C source code files: + +These files contain most of the functions intended to be called directly by +an application program: + +jcapimin.c Application program interface: core routines for compression. +jcapistd.c Application program interface: standard compression. +jdapimin.c Application program interface: core routines for decompression. +jdapistd.c Application program interface: standard decompression. +jcomapi.c Application program interface routines common to compression + and decompression. +jcparam.c Compression parameter setting helper routines. +jctrans.c API and library routines for transcoding compression. +jdtrans.c API and library routines for transcoding decompression. + +Compression side of the library: + +jcinit.c Initialization: determines which other modules to use. +jcmaster.c Master control: setup and inter-pass sequencing logic. +jcmainct.c Main buffer controller (preprocessor => JPEG compressor). +jcprepct.c Preprocessor buffer controller. +jccoefct.c Buffer controller for DCT coefficient buffer. +jccolor.c Color space conversion. +jcsample.c Downsampling. +jcdctmgr.c DCT manager (DCT implementation selection & control). +jfdctint.c Forward DCT using slow-but-accurate integer method. +jfdctfst.c Forward DCT using faster, less accurate integer method. +jfdctflt.c Forward DCT using floating-point arithmetic. +jchuff.c Huffman entropy coding for sequential JPEG. +jcphuff.c Huffman entropy coding for progressive JPEG. +jcmarker.c JPEG marker writing. +jdatadst.c Data destination manager for stdio output. + +Decompression side of the library: + +jdmaster.c Master control: determines which other modules to use. +jdinput.c Input controller: controls input processing modules. +jdmainct.c Main buffer controller (JPEG decompressor => postprocessor). +jdcoefct.c Buffer controller for DCT coefficient buffer. +jdpostct.c Postprocessor buffer controller. +jdmarker.c JPEG marker reading. +jdhuff.c Huffman entropy decoding for sequential JPEG. +jdphuff.c Huffman entropy decoding for progressive JPEG. +jddctmgr.c IDCT manager (IDCT implementation selection & control). +jidctint.c Inverse DCT using slow-but-accurate integer method. +jidctfst.c Inverse DCT using faster, less accurate integer method. +jidctflt.c Inverse DCT using floating-point arithmetic. +jidctred.c Inverse DCTs with reduced-size outputs. +jdsample.c Upsampling. +jdcolor.c Color space conversion. +jdmerge.c Merged upsampling/color conversion (faster, lower quality). +jquant1.c One-pass color quantization using a fixed-spacing colormap. +jquant2.c Two-pass color quantization using a custom-generated colormap. + Also handles one-pass quantization to an externally given map. +jdatasrc.c Data source manager for stdio input. + +Support files for both compression and decompression: + +jerror.c Standard error handling routines (application replaceable). +jmemmgr.c System-independent (more or less) memory management code. +jutils.c Miscellaneous utility routines. + +jmemmgr.c relies on a system-dependent memory management module. The IJG +distribution includes the following implementations of the system-dependent +module: + +jmemnobs.c "No backing store": assumes adequate virtual memory exists. +jmemansi.c Makes temporary files with ANSI-standard routine tmpfile(). +jmemname.c Makes temporary files with program-generated file names. +jmemdos.c Custom implementation for MS-DOS (16-bit environment only): + can use extended and expanded memory as well as temp files. +jmemmac.c Custom implementation for Apple Macintosh. + +Exactly one of the system-dependent modules should be configured into an +installed JPEG library (see install.doc for hints about which one to use). +On unusual systems you may find it worthwhile to make a special +system-dependent memory manager. + + +Non-C source code files: + +jmemdosa.asm 80x86 assembly code support for jmemdos.c; used only in + MS-DOS-specific configurations of the JPEG library. + + +CJPEG/DJPEG/JPEGTRAN +==================== + +Include files: + +cdjpeg.h Declarations shared by cjpeg/djpeg/jpegtran modules. +cderror.h Additional error and trace message codes for cjpeg et al. +transupp.h Declarations for jpegtran support routines in transupp.c. + +C source code files: + +cjpeg.c Main program for cjpeg. +djpeg.c Main program for djpeg. +jpegtran.c Main program for jpegtran. +cdjpeg.c Utility routines used by all three programs. +rdcolmap.c Code to read a colormap file for djpeg's "-map" switch. +rdswitch.c Code to process some of cjpeg's more complex switches. + Also used by jpegtran. +transupp.c Support code for jpegtran: lossless image manipulations. + +Image file reader modules for cjpeg: + +rdbmp.c BMP file input. +rdgif.c GIF file input (now just a stub). +rdppm.c PPM/PGM file input. +rdrle.c Utah RLE file input. +rdtarga.c Targa file input. + +Image file writer modules for djpeg: + +wrbmp.c BMP file output. +wrgif.c GIF file output (a mere shadow of its former self). +wrppm.c PPM/PGM file output. +wrrle.c Utah RLE file output. +wrtarga.c Targa file output. + + +RDJPGCOM/WRJPGCOM +================= + +C source code files: + +rdjpgcom.c Stand-alone rdjpgcom application. +wrjpgcom.c Stand-alone wrjpgcom application. + +These programs do not depend on the IJG library. They do use +jconfig.h and jinclude.h, only to improve portability. + + +ADDITIONAL FILES +================ + +Documentation (see README for a guide to the documentation files): + +README Master documentation file. +*.doc Other documentation files. +*.1 Documentation in Unix man page format. +change.log Version-to-version change highlights. +example.c Sample code for calling JPEG library. + +Configuration/installation files and programs (see install.doc for more info): + +configure Unix shell script to perform automatic configuration. +ltconfig Support scripts for configure (from GNU libtool). +ltmain.sh +config.guess +config.sub +install-sh Install shell script for those Unix systems lacking one. +ckconfig.c Program to generate jconfig.h on non-Unix systems. +jconfig.doc Template for making jconfig.h by hand. +makefile.* Sample makefiles for particular systems. +jconfig.* Sample jconfig.h for particular systems. +ansi2knr.c De-ANSIfier for pre-ANSI C compilers (courtesy of + L. Peter Deutsch and Aladdin Enterprises). + +Test files (see install.doc for test procedure): + +test*.* Source and comparison files for confidence test. + These are binary image files, NOT text files. diff --git a/install.doc b/install.doc new file mode 100644 index 00000000..3702b986 --- /dev/null +++ b/install.doc @@ -0,0 +1,1063 @@ +INSTALLATION INSTRUCTIONS for the Independent JPEG Group's JPEG software + +Copyright (C) 1991-1998, Thomas G. Lane. +This file is part of the Independent JPEG Group's software. +For conditions of distribution and use, see the accompanying README file. + + +This file explains how to configure and install the IJG software. We have +tried to make this software extremely portable and flexible, so that it can be +adapted to almost any environment. The downside of this decision is that the +installation process is complicated. We have provided shortcuts to simplify +the task on common systems. But in any case, you will need at least a little +familiarity with C programming and program build procedures for your system. + +If you are only using this software as part of a larger program, the larger +program's installation procedure may take care of configuring the IJG code. +For example, Ghostscript's installation script will configure the IJG code. +You don't need to read this file if you just want to compile Ghostscript. + +If you are on a Unix machine, you may not need to read this file at all. +Try doing + ./configure + make + make test +If that doesn't complain, do + make install +(better do "make -n install" first to see if the makefile will put the files +where you want them). Read further if you run into snags or want to customize +the code for your system. + + +TABLE OF CONTENTS +----------------- + +Before you start +Configuring the software: + using the automatic "configure" script + using one of the supplied jconfig and makefile files + by hand +Building the software +Testing the software +Installing the software +Optional stuff +Optimization +Hints for specific systems + + +BEFORE YOU START +================ + +Before installing the software you must unpack the distributed source code. +Since you are reading this file, you have probably already succeeded in this +task. However, there is a potential for error if you needed to convert the +files to the local standard text file format (for example, if you are on +MS-DOS you may have converted LF end-of-line to CR/LF). You must apply +such conversion to all the files EXCEPT those whose names begin with "test". +The test files contain binary data; if you change them in any way then the +self-test will give bad results. + +Please check the last section of this file to see if there are hints for the +specific machine or compiler you are using. + + +CONFIGURING THE SOFTWARE +======================== + +To configure the IJG code for your system, you need to create two files: + * jconfig.h: contains values for system-dependent #define symbols. + * Makefile: controls the compilation process. +(On a non-Unix machine, you may create "project files" or some other +substitute for a Makefile. jconfig.h is needed in any environment.) + +We provide three different ways to generate these files: + * On a Unix system, you can just run the "configure" script. + * We provide sample jconfig files and makefiles for popular machines; + if your machine matches one of the samples, just copy the right sample + files to jconfig.h and Makefile. + * If all else fails, read the instructions below and make your own files. + + +Configuring the software using the automatic "configure" script +--------------------------------------------------------------- + +If you are on a Unix machine, you can just type + ./configure +and let the configure script construct appropriate configuration files. +If you're using "csh" on an old version of System V, you might need to type + sh configure +instead to prevent csh from trying to execute configure itself. +Expect configure to run for a few minutes, particularly on slower machines; +it works by compiling a series of test programs. + +Configure was created with GNU Autoconf and it follows the usual conventions +for GNU configure scripts. It makes a few assumptions that you may want to +override. You can do this by providing optional switches to configure: + +* If you want to build libjpeg as a shared library, say + ./configure --enable-shared +To get both shared and static libraries, say + ./configure --enable-shared --enable-static +Note that these switches invoke GNU libtool to take care of system-dependent +shared library building methods. If things don't work this way, please try +running configure without either switch; that should build a static library +without using libtool. If that works, your problem is probably with libtool +not with the IJG code. libtool is fairly new and doesn't support all flavors +of Unix yet. (You might be able to find a newer version of libtool than the +one included with libjpeg; see ftp.gnu.org. Report libtool problems to +bug-libtool@gnu.org.) + +* Configure will use gcc (GNU C compiler) if it's available, otherwise cc. +To force a particular compiler to be selected, use the CC option, for example + ./configure CC='cc' +The same method can be used to include any unusual compiler switches. +For example, on HP-UX you probably want to say + ./configure CC='cc -Aa' +to get HP's compiler to run in ANSI mode. + +* The default CFLAGS setting is "-O" for non-gcc compilers, "-O2" for gcc. +You can override this by saying, for example, + ./configure CFLAGS='-g' +if you want to compile with debugging support. + +* Configure will set up the makefile so that "make install" will install files +into /usr/local/bin, /usr/local/man, etc. You can specify an installation +prefix other than "/usr/local" by giving configure the option "--prefix=PATH". + +* If you don't have a lot of swap space, you may need to enable the IJG +software's internal virtual memory mechanism. To do this, give the option +"--enable-maxmem=N" where N is the default maxmemory limit in megabytes. +This is discussed in more detail under "Selecting a memory manager", below. +You probably don't need to worry about this on reasonably-sized Unix machines, +unless you plan to process very large images. + +Configure has some other features that are useful if you are cross-compiling +or working in a network of multiple machine types; but if you need those +features, you probably already know how to use them. + + +Configuring the software using one of the supplied jconfig and makefile files +----------------------------------------------------------------------------- + +If you have one of these systems, you can just use the provided configuration +files: + +Makefile jconfig file System and/or compiler + +makefile.manx jconfig.manx Amiga, Manx Aztec C +makefile.sas jconfig.sas Amiga, SAS C +makeproj.mac jconfig.mac Apple Macintosh, Metrowerks CodeWarrior +mak*jpeg.st jconfig.st Atari ST/STE/TT, Pure C or Turbo C +makefile.bcc jconfig.bcc MS-DOS or OS/2, Borland C +makefile.dj jconfig.dj MS-DOS, DJGPP (Delorie's port of GNU C) +makefile.mc6 jconfig.mc6 MS-DOS, Microsoft C (16-bit only) +makefile.wat jconfig.wat MS-DOS, OS/2, or Windows NT, Watcom C +makefile.vc jconfig.vc Windows NT/95, MS Visual C++ +make*.ds jconfig.vc Windows NT/95, MS Developer Studio +makefile.mms jconfig.vms Digital VMS, with MMS software +makefile.vms jconfig.vms Digital VMS, without MMS software + +Copy the proper jconfig file to jconfig.h and the makefile to Makefile (or +whatever your system uses as the standard makefile name). For more info see +the appropriate system-specific hints section near the end of this file. + + +Configuring the software by hand +-------------------------------- + +First, generate a jconfig.h file. If you are moderately familiar with C, +the comments in jconfig.doc should be enough information to do this; just +copy jconfig.doc to jconfig.h and edit it appropriately. Otherwise, you may +prefer to use the ckconfig.c program. You will need to compile and execute +ckconfig.c by hand --- we hope you know at least enough to do that. +ckconfig.c may not compile the first try (in fact, the whole idea is for it +to fail if anything is going to). If you get compile errors, fix them by +editing ckconfig.c according to the directions given in ckconfig.c. Once +you get it to run, it will write a suitable jconfig.h file, and will also +print out some advice about which makefile to use. + +You may also want to look at the canned jconfig files, if there is one for a +system similar to yours. + +Second, select a makefile and copy it to Makefile (or whatever your system +uses as the standard makefile name). The most generic makefiles we provide +are + makefile.ansi: if your C compiler supports function prototypes + makefile.unix: if not. +(You have function prototypes if ckconfig.c put "#define HAVE_PROTOTYPES" +in jconfig.h.) You may want to start from one of the other makefiles if +there is one for a system similar to yours. + +Look over the selected Makefile and adjust options as needed. In particular +you may want to change the CC and CFLAGS definitions. For instance, if you +are using GCC, set CC=gcc. If you had to use any compiler switches to get +ckconfig.c to work, make sure the same switches are in CFLAGS. + +If you are on a system that doesn't use makefiles, you'll need to set up +project files (or whatever you do use) to compile all the source files and +link them into executable files cjpeg, djpeg, jpegtran, rdjpgcom, and wrjpgcom. +See the file lists in any of the makefiles to find out which files go into +each program. Note that the provided makefiles all make a "library" file +libjpeg first, but you don't have to do that if you don't want to; the file +lists identify which source files are actually needed for compression, +decompression, or both. As a last resort, you can make a batch script that +just compiles everything and links it all together; makefile.vms is an example +of this (it's for VMS systems that have no make-like utility). + +Here are comments about some specific configuration decisions you'll +need to make: + +Command line style +------------------ + +These programs can use a Unix-like command line style which supports +redirection and piping, like this: + cjpeg inputfile >outputfile + cjpeg outputfile + source program | cjpeg >outputfile +The simpler "two file" command line style is just + cjpeg inputfile outputfile +You may prefer the two-file style, particularly if you don't have pipes. + +You MUST use two-file style on any system that doesn't cope well with binary +data fed through stdin/stdout; this is true for some MS-DOS compilers, for +example. If you're not on a Unix system, it's safest to assume you need +two-file style. (But if your compiler provides either the Posix-standard +fdopen() library routine or a Microsoft-compatible setmode() routine, you +can safely use the Unix command line style, by defining USE_FDOPEN or +USE_SETMODE respectively.) + +To use the two-file style, make jconfig.h say "#define TWO_FILE_COMMANDLINE". + +Selecting a memory manager +-------------------------- + +The IJG code is capable of working on images that are too big to fit in main +memory; data is swapped out to temporary files as necessary. However, the +code to do this is rather system-dependent. We provide five different +memory managers: + +* jmemansi.c This version uses the ANSI-standard library routine tmpfile(), + which not all non-ANSI systems have. On some systems + tmpfile() may put the temporary file in a non-optimal + location; if you don't like what it does, use jmemname.c. + +* jmemname.c This version creates named temporary files. For anything + except a Unix machine, you'll need to configure the + select_file_name() routine appropriately; see the comments + near the head of jmemname.c. If you use this version, define + NEED_SIGNAL_CATCHER in jconfig.h to make sure the temp files + are removed if the program is aborted. + +* jmemnobs.c (That stands for No Backing Store :-).) This will compile on + almost any system, but it assumes you have enough main memory + or virtual memory to hold the biggest images you work with. + +* jmemdos.c This should be used with most 16-bit MS-DOS compilers. + See the system-specific notes about MS-DOS for more info. + IMPORTANT: if you use this, define USE_MSDOS_MEMMGR in + jconfig.h, and include the assembly file jmemdosa.asm in the + programs. The supplied makefiles and jconfig files for + 16-bit MS-DOS compilers already do both. + +* jmemmac.c Custom version for Apple Macintosh; see the system-specific + notes for Macintosh for more info. + +To use a particular memory manager, change the SYSDEPMEM variable in your +makefile to equal the corresponding object file name (for example, jmemansi.o +or jmemansi.obj for jmemansi.c). + +If you have plenty of (real or virtual) main memory, just use jmemnobs.c. +"Plenty" means about ten bytes for every pixel in the largest images +you plan to process, so a lot of systems don't meet this criterion. +If yours doesn't, try jmemansi.c first. If that doesn't compile, you'll have +to use jmemname.c; be sure to adjust select_file_name() for local conditions. +You may also need to change unlink() to remove() in close_backing_store(). + +Except with jmemnobs.c or jmemmac.c, you need to adjust the DEFAULT_MAX_MEM +setting to a reasonable value for your system (either by adding a #define for +DEFAULT_MAX_MEM to jconfig.h, or by adding a -D switch to the Makefile). +This value limits the amount of data space the program will attempt to +allocate. Code and static data space isn't counted, so the actual memory +needs for cjpeg or djpeg are typically 100 to 150Kb more than the max-memory +setting. Larger max-memory settings reduce the amount of I/O needed to +process a large image, but too large a value can result in "insufficient +memory" failures. On most Unix machines (and other systems with virtual +memory), just set DEFAULT_MAX_MEM to several million and forget it. At the +other end of the spectrum, for MS-DOS machines you probably can't go much +above 300K to 400K. (On MS-DOS the value refers to conventional memory only. +Extended/expanded memory is handled separately by jmemdos.c.) + + +BUILDING THE SOFTWARE +===================== + +Now you should be able to compile the software. Just say "make" (or +whatever's necessary to start the compilation). Have a cup of coffee. + +Here are some things that could go wrong: + +If your compiler complains about undefined structures, you should be able to +shut it up by putting "#define INCOMPLETE_TYPES_BROKEN" in jconfig.h. + +If you have trouble with missing system include files or inclusion of the +wrong ones, read jinclude.h. This shouldn't happen if you used configure +or ckconfig.c to set up jconfig.h. + +There are a fair number of routines that do not use all of their parameters; +some compilers will issue warnings about this, which you can ignore. There +are also a few configuration checks that may give "unreachable code" warnings. +Any other warning deserves investigation. + +If you don't have a getenv() library routine, define NO_GETENV. + +Also see the system-specific hints, below. + + +TESTING THE SOFTWARE +==================== + +As a quick test of functionality we've included a small sample image in +several forms: + testorig.jpg Starting point for the djpeg tests. + testimg.ppm The output of djpeg testorig.jpg + testimg.bmp The output of djpeg -bmp -colors 256 testorig.jpg + testimg.jpg The output of cjpeg testimg.ppm + testprog.jpg Progressive-mode equivalent of testorig.jpg. + testimgp.jpg The output of cjpeg -progressive -optimize testimg.ppm +(The first- and second-generation .jpg files aren't identical since JPEG is +lossy.) If you can generate duplicates of the testimg* files then you +probably have working programs. + +With most of the makefiles, "make test" will perform the necessary +comparisons. + +If you're using a makefile that doesn't provide the test option, run djpeg +and cjpeg by hand and compare the output files to testimg* with whatever +binary file comparison tool you have. The files should be bit-for-bit +identical. + +If the programs complain "MAX_ALLOC_CHUNK is wrong, please fix", then you +need to reduce MAX_ALLOC_CHUNK to a value that fits in type size_t. +Try adding "#define MAX_ALLOC_CHUNK 65520L" to jconfig.h. A less likely +configuration error is "ALIGN_TYPE is wrong, please fix": defining ALIGN_TYPE +as long should take care of that one. + +If the cjpeg test run fails with "Missing Huffman code table entry", it's a +good bet that you needed to define RIGHT_SHIFT_IS_UNSIGNED. Go back to the +configuration step and run ckconfig.c. (This is a good plan for any other +test failure, too.) + +If you are using Unix (one-file) command line style on a non-Unix system, +it's a good idea to check that binary I/O through stdin/stdout actually +works. You should get the same results from "djpeg out.ppm" +as from "djpeg -outfile out.ppm testorig.jpg". Note that the makefiles all +use the latter style and therefore do not exercise stdin/stdout! If this +check fails, try recompiling with USE_SETMODE or USE_FDOPEN defined. +If it still doesn't work, better use two-file style. + +If you chose a memory manager other than jmemnobs.c, you should test that +temporary-file usage works. Try "djpeg -bmp -colors 256 -max 0 testorig.jpg" +and make sure its output matches testimg.bmp. If you have any really large +images handy, try compressing them with -optimize and/or decompressing with +-colors 256 to make sure your DEFAULT_MAX_MEM setting is not too large. + +NOTE: this is far from an exhaustive test of the JPEG software; some modules, +such as 1-pass color quantization, are not exercised at all. It's just a +quick test to give you some confidence that you haven't missed something +major. + + +INSTALLING THE SOFTWARE +======================= + +Once you're done with the above steps, you can install the software by +copying the executable files (cjpeg, djpeg, jpegtran, rdjpgcom, and wrjpgcom) +to wherever you normally install programs. On Unix systems, you'll also want +to put the man pages (cjpeg.1, djpeg.1, jpegtran.1, rdjpgcom.1, wrjpgcom.1) +in the man-page directory. The pre-fab makefiles don't support this step +since there's such a wide variety of installation procedures on different +systems. + +If you generated a Makefile with the "configure" script, you can just say + make install +to install the programs and their man pages into the standard places. +(You'll probably need to be root to do this.) We recommend first saying + make -n install +to see where configure thought the files should go. You may need to edit +the Makefile, particularly if your system's conventions for man page +filenames don't match what configure expects. + +If you want to install the IJG library itself, for use in compiling other +programs besides ours, then you need to put the four include files + jpeglib.h jerror.h jconfig.h jmorecfg.h +into your include-file directory, and put the library file libjpeg.a +(extension may vary depending on system) wherever library files go. +If you generated a Makefile with "configure", it will do what it thinks +is the right thing if you say + make install-lib + + +OPTIONAL STUFF +============== + +Progress monitor: + +If you like, you can #define PROGRESS_REPORT (in jconfig.h) to enable display +of percent-done progress reports. The routine provided in cdjpeg.c merely +prints percentages to stderr, but you can customize it to do something +fancier. + +Utah RLE file format support: + +We distribute the software with support for RLE image files (Utah Raster +Toolkit format) disabled, because the RLE support won't compile without the +Utah library. If you have URT version 3.1 or later, you can enable RLE +support as follows: + 1. #define RLE_SUPPORTED in jconfig.h. + 2. Add a -I option to CFLAGS in the Makefile for the directory + containing the URT .h files (typically the "include" + subdirectory of the URT distribution). + 3. Add -L... -lrle to LDLIBS in the Makefile, where ... specifies + the directory containing the URT "librle.a" file (typically the + "lib" subdirectory of the URT distribution). + +Support for 12-bit-deep pixel data: + +The JPEG standard allows either 8-bit or 12-bit data precision. (For color, +this means 8 or 12 bits per channel, of course.) If you need to work with +deeper than 8-bit data, you can compile the IJG code for 12-bit operation. +To do so: + 1. In jmorecfg.h, define BITS_IN_JSAMPLE as 12 rather than 8. + 2. In jconfig.h, undefine BMP_SUPPORTED, RLE_SUPPORTED, and TARGA_SUPPORTED, + because the code for those formats doesn't handle 12-bit data and won't + even compile. (The PPM code does work, as explained below. The GIF + code works too; it scales 8-bit GIF data to and from 12-bit depth + automatically.) + 3. Compile. Don't expect "make test" to pass, since the supplied test + files are for 8-bit data. + +Currently, 12-bit support does not work on 16-bit-int machines. + +Note that a 12-bit version will not read 8-bit JPEG files, nor vice versa; +so you'll want to keep around a regular 8-bit compilation as well. +(Run-time selection of data depth, to allow a single copy that does both, +is possible but would probably slow things down considerably; it's very low +on our to-do list.) + +The PPM reader (rdppm.c) can read 12-bit data from either text-format or +binary-format PPM and PGM files. Binary-format PPM/PGM files which have a +maxval greater than 255 are assumed to use 2 bytes per sample, LSB first +(little-endian order). As of early 1995, 2-byte binary format is not +officially supported by the PBMPLUS library, but it is expected that a +future release of PBMPLUS will support it. Note that the PPM reader will +read files of any maxval regardless of the BITS_IN_JSAMPLE setting; incoming +data is automatically rescaled to either maxval=255 or maxval=4095 as +appropriate for the cjpeg bit depth. + +The PPM writer (wrppm.c) will normally write 2-byte binary PPM or PGM +format, maxval 4095, when compiled with BITS_IN_JSAMPLE=12. Since this +format is not yet widely supported, you can disable it by compiling wrppm.c +with PPM_NORAWWORD defined; then the data is scaled down to 8 bits to make a +standard 1-byte/sample PPM or PGM file. (Yes, this means still another copy +of djpeg to keep around. But hopefully you won't need it for very long. +Poskanzer's supposed to get that new PBMPLUS release out Real Soon Now.) + +Of course, if you are working with 12-bit data, you probably have it stored +in some other, nonstandard format. In that case you'll probably want to +write your own I/O modules to read and write your format. + +Note that a 12-bit version of cjpeg always runs in "-optimize" mode, in +order to generate valid Huffman tables. This is necessary because our +default Huffman tables only cover 8-bit data. + +Removing code: + +If you need to make a smaller version of the JPEG software, some optional +functions can be removed at compile time. See the xxx_SUPPORTED #defines in +jconfig.h and jmorecfg.h. If at all possible, we recommend that you leave in +decoder support for all valid JPEG files, to ensure that you can read anyone's +output. Taking out support for image file formats that you don't use is the +most painless way to make the programs smaller. Another possibility is to +remove some of the DCT methods: in particular, the "IFAST" method may not be +enough faster than the others to be worth keeping on your machine. (If you +do remove ISLOW or IFAST, be sure to redefine JDCT_DEFAULT or JDCT_FASTEST +to a supported method, by adding a #define in jconfig.h.) + + +OPTIMIZATION +============ + +Unless you own a Cray, you'll probably be interested in making the JPEG +software go as fast as possible. This section covers some machine-dependent +optimizations you may want to try. We suggest that before trying any of +this, you first get the basic installation to pass the self-test step. +Repeat the self-test after any optimization to make sure that you haven't +broken anything. + +The integer DCT routines perform a lot of multiplications. These +multiplications must yield 32-bit results, but none of their input values +are more than 16 bits wide. On many machines, notably the 680x0 and 80x86 +CPUs, a 16x16=>32 bit multiply instruction is faster than a full 32x32=>32 +bit multiply. Unfortunately there is no portable way to specify such a +multiplication in C, but some compilers can generate one when you use the +right combination of casts. See the MULTIPLYxxx macro definitions in +jdct.h. If your compiler makes "int" be 32 bits and "short" be 16 bits, +defining SHORTxSHORT_32 is fairly likely to work. When experimenting with +alternate definitions, be sure to test not only whether the code still works +(use the self-test), but also whether it is actually faster --- on some +compilers, alternate definitions may compute the right answer, yet be slower +than the default. Timing cjpeg on a large PGM (grayscale) input file is the +best way to check this, as the DCT will be the largest fraction of the runtime +in that mode. (Note: some of the distributed compiler-specific jconfig files +already contain #define switches to select appropriate MULTIPLYxxx +definitions.) + +If your machine has sufficiently fast floating point hardware, you may find +that the float DCT method is faster than the integer DCT methods, even +after tweaking the integer multiply macros. In that case you may want to +make the float DCT be the default method. (The only objection to this is +that float DCT results may vary slightly across machines.) To do that, add +"#define JDCT_DEFAULT JDCT_FLOAT" to jconfig.h. Even if you don't change +the default, you should redefine JDCT_FASTEST, which is the method selected +by djpeg's -fast switch. Don't forget to update the documentation files +(usage.doc and/or cjpeg.1, djpeg.1) to agree with what you've done. + +If access to "short" arrays is slow on your machine, it may be a win to +define type JCOEF as int rather than short. This will cost a good deal of +memory though, particularly in some multi-pass modes, so don't do it unless +you have memory to burn and short is REALLY slow. + +If your compiler can compile function calls in-line, make sure the INLINE +macro in jmorecfg.h is defined as the keyword that marks a function +inline-able. Some compilers have a switch that tells the compiler to inline +any function it thinks is profitable (e.g., -finline-functions for gcc). +Enabling such a switch is likely to make the compiled code bigger but faster. + +In general, it's worth trying the maximum optimization level of your compiler, +and experimenting with any optional optimizations such as loop unrolling. +(Unfortunately, far too many compilers have optimizer bugs ... be prepared to +back off if the code fails self-test.) If you do any experimentation along +these lines, please report the optimal settings to jpeg-info@uunet.uu.net so +we can mention them in future releases. Be sure to specify your machine and +compiler version. + + +HINTS FOR SPECIFIC SYSTEMS +========================== + +We welcome reports on changes needed for systems not mentioned here. Submit +'em to jpeg-info@uunet.uu.net. Also, if configure or ckconfig.c is wrong +about how to configure the JPEG software for your system, please let us know. + + +Acorn RISC OS: + +(Thanks to Simon Middleton for these hints on compiling with Desktop C.) +After renaming the files according to Acorn conventions, take a copy of +makefile.ansi, change all occurrences of 'libjpeg.a' to 'libjpeg.o' and +change these definitions as indicated: + +CFLAGS= -throwback -IC: -Wn +LDLIBS=C:o.Stubs +SYSDEPMEM=jmemansi.o +LN=Link +AR=LibFile -c -o + +Also add a new line '.c.o:; $(cc) $< $(cflags) -c -o $@'. Remove the +lines '$(RM) libjpeg.o' and '$(AR2) libjpeg.o' and the 'jconfig.h' +dependency section. + +Copy jconfig.doc to jconfig.h. Edit jconfig.h to define TWO_FILE_COMMANDLINE +and CHAR_IS_UNSIGNED. + +Run the makefile using !AMU not !Make. If you want to use the 'clean' and +'test' makefile entries then you will have to fiddle with the syntax a bit +and rename the test files. + + +Amiga: + +SAS C 6.50 reportedly is too buggy to compile the IJG code properly. +A patch to update to 6.51 is available from SAS or AmiNet FTP sites. + +The supplied config files are set up to use jmemname.c as the memory +manager, with temporary files being created on the device named by +"JPEGTMP:". + + +Atari ST/STE/TT: + +Copy the project files makcjpeg.st, makdjpeg.st, maktjpeg.st, and makljpeg.st +to cjpeg.prj, djpeg.prj, jpegtran.prj, and libjpeg.prj respectively. The +project files should work as-is with Pure C. For Turbo C, change library +filenames "pc..." to "tc..." in each project file. Note that libjpeg.prj +selects jmemansi.c as the recommended memory manager. You'll probably want to +adjust the DEFAULT_MAX_MEM setting --- you want it to be a couple hundred K +less than your normal free memory. Put "#define DEFAULT_MAX_MEM nnnn" into +jconfig.h to do this. + +To use the 68881/68882 coprocessor for the floating point DCT, add the +compiler option "-8" to the project files and replace pcfltlib.lib with +pc881lib.lib in cjpeg.prj and djpeg.prj. Or if you don't have a +coprocessor, you may prefer to remove the float DCT code by undefining +DCT_FLOAT_SUPPORTED in jmorecfg.h (since without a coprocessor, the float +code will be too slow to be useful). In that case, you can delete +pcfltlib.lib from the project files. + +Note that you must make libjpeg.lib before making cjpeg.ttp, djpeg.ttp, +or jpegtran.ttp. You'll have to perform the self-test by hand. + +We haven't bothered to include project files for rdjpgcom and wrjpgcom. +Those source files should just be compiled by themselves; they don't +depend on the JPEG library. + +There is a bug in some older versions of the Turbo C library which causes the +space used by temporary files created with "tmpfile()" not to be freed after +an abnormal program exit. If you check your disk afterwards, you will find +cluster chains that are allocated but not used by a file. This should not +happen in cjpeg/djpeg/jpegtran, since we enable a signal catcher to explicitly +close temp files before exiting. But if you use the JPEG library with your +own code, be sure to supply a signal catcher, or else use a different +system-dependent memory manager. + + +Cray: + +Should you be so fortunate as to be running JPEG on a Cray YMP, there is a +compiler bug in old versions of Cray's Standard C (prior to 3.1). If you +still have an old compiler, you'll need to insert a line reading +"#pragma novector" just before the loop + for (i = 1; i <= (int) htbl->bits[l]; i++) + huffsize[p++] = (char) l; +in fix_huff_tbl (in V5beta1, line 204 of jchuff.c and line 176 of jdhuff.c). +[This bug may or may not still occur with the current IJG code, but it's +probably a dead issue anyway...] + + +HP-UX: + +If you have HP-UX 7.05 or later with the "software development" C compiler, +you should run the compiler in ANSI mode. If using the configure script, +say + ./configure CC='cc -Aa' +(or -Ae if you prefer). If configuring by hand, use makefile.ansi and add +"-Aa" to the CFLAGS line in the makefile. + +If you have a pre-7.05 system, or if you are using the non-ANSI C compiler +delivered with a minimum HP-UX system, then you must use makefile.unix +(and do NOT add -Aa); or just run configure without the CC option. + +On HP 9000 series 800 machines, the HP C compiler is buggy in revisions prior +to A.08.07. If you get complaints about "not a typedef name", you'll have to +use makefile.unix, or run configure without the CC option. + + +Macintosh, generic comments: + +The supplied user-interface files (cjpeg.c, djpeg.c, etc) are set up to +provide a Unix-style command line interface. You can use this interface on +the Mac by means of the ccommand() library routine provided by Metrowerks +CodeWarrior or Think C. This is only appropriate for testing the library, +however; to make a user-friendly equivalent of cjpeg/djpeg you'd really want +to develop a Mac-style user interface. There isn't a complete example +available at the moment, but there are some helpful starting points: +1. Sam Bushell's free "To JPEG" applet provides drag-and-drop conversion to +JPEG under System 7 and later. This only illustrates how to use the +compression half of the library, but it does a very nice job of that part. +The CodeWarrior source code is available from http://www.pobox.com/~jsam. +2. Jim Brunner prepared a Mac-style user interface for both compression and +decompression. Unfortunately, it hasn't been updated since IJG v4, and +the library's API has changed considerably since then. Still it may be of +some help, particularly as a guide to compiling the IJG code under Think C. +Jim's code is available from the Info-Mac archives, at sumex-aim.stanford.edu +or mirrors thereof; see file /info-mac/dev/src/jpeg-convert-c.hqx. + +jmemmac.c is the recommended memory manager back end for Macintosh. It uses +NewPtr/DisposePtr instead of malloc/free, and has a Mac-specific +implementation of jpeg_mem_available(). It also creates temporary files that +follow Mac conventions. (That part of the code relies on System-7-or-later OS +functions. See the comments in jmemmac.c if you need to run it on System 6.) +NOTE that USE_MAC_MEMMGR must be defined in jconfig.h to use jmemmac.c. + +You can also use jmemnobs.c, if you don't care about handling images larger +than available memory. If you use any memory manager back end other than +jmemmac.c, we recommend replacing "malloc" and "free" by "NewPtr" and +"DisposePtr", because Mac C libraries often have peculiar implementations of +malloc/free. (For instance, free() may not return the freed space to the +Mac Memory Manager. This is undesirable for the IJG code because jmemmgr.c +already clumps space requests.) + + +Macintosh, Metrowerks CodeWarrior: + +The Unix-command-line-style interface can be used by defining USE_CCOMMAND. +You'll also need to define TWO_FILE_COMMANDLINE to avoid stdin/stdout. +This means that when using the cjpeg/djpeg programs, you'll have to type the +input and output file names in the "Arguments" text-edit box, rather than +using the file radio buttons. (Perhaps USE_FDOPEN or USE_SETMODE would +eliminate the problem, but I haven't heard from anyone who's tried it.) + +On 680x0 Macs, Metrowerks defines type "double" as a 10-byte IEEE extended +float. jmemmgr.c won't like this: it wants sizeof(ALIGN_TYPE) to be a power +of 2. Add "#define ALIGN_TYPE long" to jconfig.h to eliminate the complaint. + +The supplied configuration file jconfig.mac can be used for your jconfig.h; +it includes all the recommended symbol definitions. If you have AppleScript +installed, you can run the supplied script makeproj.mac to create CodeWarrior +project files for the library and the testbed applications, then build the +library and applications. (Thanks to Dan Sears and Don Agro for this nifty +hack, which saves us from trying to maintain CodeWarrior project files as part +of the IJG distribution...) + + +Macintosh, Think C: + +The documentation in Jim Brunner's "JPEG Convert" source code (see above) +includes detailed build instructions for Think C; it's probably somewhat +out of date for the current release, but may be helpful. + +If you want to build the minimal command line version, proceed as follows. +You'll have to prepare project files for the programs; we don't include any +in the distribution since they are not text files. Use the file lists in +any of the supplied makefiles as a guide. Also add the ANSI and Unix C +libraries in a separate segment. You may need to divide the JPEG files into +more than one segment; we recommend dividing compression and decompression +modules. Define USE_CCOMMAND in jconfig.h so that the ccommand() routine is +called. You must also define TWO_FILE_COMMANDLINE because stdin/stdout +don't handle binary data correctly. + +On 680x0 Macs, Think C defines type "double" as a 12-byte IEEE extended float. +jmemmgr.c won't like this: it wants sizeof(ALIGN_TYPE) to be a power of 2. +Add "#define ALIGN_TYPE long" to jconfig.h to eliminate the complaint. + +jconfig.mac should work as a jconfig.h configuration file for Think C, +but the makeproj.mac AppleScript script is specific to CodeWarrior. Sorry. + + +MIPS R3000: + +MIPS's cc version 1.31 has a rather nasty optimization bug. Don't use -O +if you have that compiler version. (Use "cc -V" to check the version.) +Note that the R3000 chip is found in workstations from DEC and others. + + +MS-DOS, generic comments for 16-bit compilers: + +The IJG code is designed to work well in 80x86 "small" or "medium" memory +models (i.e., data pointers are 16 bits unless explicitly declared "far"; +code pointers can be either size). You may be able to use small model to +compile cjpeg or djpeg by itself, but you will probably have to use medium +model for any larger application. This won't make much difference in +performance. You *will* take a noticeable performance hit if you use a +large-data memory model, and you should avoid "huge" model if at all +possible. Be sure that NEED_FAR_POINTERS is defined in jconfig.h if you use +a small-data memory model; be sure it is NOT defined if you use a large-data +model. (The supplied makefiles and jconfig files for Borland and Microsoft C +compile in medium model and define NEED_FAR_POINTERS.) + +The DOS-specific memory manager, jmemdos.c, should be used if possible. +It needs some assembly-code routines which are in jmemdosa.asm; make sure +your makefile assembles that file and includes it in the library. If you +don't have a suitable assembler, you can get pre-assembled object files for +jmemdosa by FTP from ftp.uu.net:/graphics/jpeg/jdosaobj.zip. (DOS-oriented +distributions of the IJG source code often include these object files.) + +When using jmemdos.c, jconfig.h must define USE_MSDOS_MEMMGR and must set +MAX_ALLOC_CHUNK to less than 64K (65520L is a typical value). If your +C library's far-heap malloc() can't allocate blocks that large, reduce +MAX_ALLOC_CHUNK to whatever it can handle. + +If you can't use jmemdos.c for some reason --- for example, because you +don't have an assembler to assemble jmemdosa.asm --- you'll have to fall +back to jmemansi.c or jmemname.c. You'll probably still need to set +MAX_ALLOC_CHUNK in jconfig.h, because most DOS C libraries won't malloc() +more than 64K at a time. IMPORTANT: if you use jmemansi.c or jmemname.c, +you will have to compile in a large-data memory model in order to get the +right stdio library. Too bad. + +wrjpgcom needs to be compiled in large model, because it malloc()s a 64KB +work area to hold the comment text. If your C library's malloc can't +handle that, reduce MAX_COM_LENGTH as necessary in wrjpgcom.c. + +Most MS-DOS compilers treat stdin/stdout as text files, so you must use +two-file command line style. But if your compiler has either fdopen() or +setmode(), you can use one-file style if you like. To do this, define +USE_SETMODE or USE_FDOPEN so that stdin/stdout will be set to binary mode. +(USE_SETMODE seems to work with more DOS compilers than USE_FDOPEN.) You +should test that I/O through stdin/stdout produces the same results as I/O +to explicitly named files... the "make test" procedures in the supplied +makefiles do NOT use stdin/stdout. + + +MS-DOS, generic comments for 32-bit compilers: + +None of the above comments about memory models apply if you are using a +32-bit flat-memory-space environment, such as DJGPP or Watcom C. (And you +should use one if you have it, as performance will be much better than +8086-compatible code!) For flat-memory-space compilers, do NOT define +NEED_FAR_POINTERS, and do NOT use jmemdos.c. Use jmemnobs.c if the +environment supplies adequate virtual memory, otherwise use jmemansi.c or +jmemname.c. + +You'll still need to be careful about binary I/O through stdin/stdout. +See the last paragraph of the previous section. + + +MS-DOS, Borland C: + +Be sure to convert all the source files to DOS text format (CR/LF newlines). +Although Borland C will often work OK with unmodified Unix (LF newlines) +source files, sometimes it will give bogus compile errors. +"Illegal character '#'" is the most common such error. (This is true with +Borland C 3.1, but perhaps is fixed in newer releases.) + +If you want one-file command line style, just undefine TWO_FILE_COMMANDLINE. +jconfig.bcc already includes #define USE_SETMODE to make this work. +(fdopen does not work correctly.) + + +MS-DOS, Microsoft C: + +makefile.mc6 works with Microsoft C, DOS Visual C++, etc. It should only +be used if you want to build a 16-bit (small or medium memory model) program. + +If you want one-file command line style, just undefine TWO_FILE_COMMANDLINE. +jconfig.mc6 already includes #define USE_SETMODE to make this work. +(fdopen does not work correctly.) + +Note that this makefile assumes that the working copy of itself is called +"makefile". If you want to call it something else, say "makefile.mak", +be sure to adjust the dependency line that reads "$(RFILE) : makefile". +Otherwise the make will fail because it doesn't know how to create "makefile". +Worse, some releases of Microsoft's make utilities give an incorrect error +message in this situation. + +Old versions of MS C fail with an "out of macro expansion space" error +because they can't cope with the macro TRACEMS8 (defined in jerror.h). +If this happens to you, the easiest solution is to change TRACEMS8 to +expand to nothing. You'll lose the ability to dump out JPEG coefficient +tables with djpeg -debug -debug, but at least you can compile. + +Original MS C 6.0 is very buggy; it compiles incorrect code unless you turn +off optimization entirely (remove -O from CFLAGS). 6.00A is better, but it +still generates bad code if you enable loop optimizations (-Ol or -Ox). + +MS C 8.0 crashes when compiling jquant1.c with optimization switch /Oo ... +which is on by default. To work around this bug, compile that one file +with /Oo-. + + +Microsoft Windows (all versions), generic comments: + +Some Windows system include files define typedef boolean as "unsigned char". +The IJG code also defines typedef boolean, but we make it "int" by default. +This doesn't affect the IJG programs because we don't import those Windows +include files. But if you use the JPEG library in your own program, and some +of your program's files import one definition of boolean while some import the +other, you can get all sorts of mysterious problems. A good preventive step +is to make the IJG library use "unsigned char" for boolean. To do that, +add something like this to your jconfig.h file: + /* Define "boolean" as unsigned char, not int, per Windows custom */ + #ifndef __RPCNDR_H__ /* don't conflict if rpcndr.h already read */ + typedef unsigned char boolean; + #endif + #define HAVE_BOOLEAN /* prevent jmorecfg.h from redefining it */ +(This is already in jconfig.vc, by the way.) + +windef.h contains the declarations + #define far + #define FAR far +Since jmorecfg.h tries to define FAR as empty, you may get a compiler +warning if you include both jpeglib.h and windef.h (which windows.h +includes). To suppress the warning, you can put "#ifndef FAR"/"#endif" +around the line "#define FAR" in jmorecfg.h. + +When using the library in a Windows application, you will almost certainly +want to modify or replace the error handler module jerror.c, since our +default error handler does a couple of inappropriate things: + 1. it tries to write error and warning messages on stderr; + 2. in event of a fatal error, it exits by calling exit(). + +A simple stopgap solution for problem 1 is to replace the line + fprintf(stderr, "%s\n", buffer); +(in output_message in jerror.c) with + MessageBox(GetActiveWindow(),buffer,"JPEG Error",MB_OK|MB_ICONERROR); +It's highly recommended that you at least do that much, since otherwise +error messages will disappear into nowhere. (Beginning with IJG v6b, this +code is already present in jerror.c; just define USE_WINDOWS_MESSAGEBOX in +jconfig.h to enable it.) + +The proper solution for problem 2 is to return control to your calling +application after a library error. This can be done with the setjmp/longjmp +technique discussed in libjpeg.doc and illustrated in example.c. (NOTE: +some older Windows C compilers provide versions of setjmp/longjmp that +don't actually work under Windows. You may need to use the Windows system +functions Catch and Throw instead.) + +The recommended memory manager under Windows is jmemnobs.c; in other words, +let Windows do any virtual memory management needed. You should NOT use +jmemdos.c nor jmemdosa.asm under Windows. + +For Windows 3.1, we recommend compiling in medium or large memory model; +for newer Windows versions, use a 32-bit flat memory model. (See the MS-DOS +sections above for more info about memory models.) In the 16-bit memory +models only, you'll need to put + #define MAX_ALLOC_CHUNK 65520L /* Maximum request to malloc() */ +into jconfig.h to limit allocation chunks to 64Kb. (Without that, you'd +have to use huge memory model, which slows things down unnecessarily.) +jmemnobs.c works without modification in large or flat memory models, but to +use medium model, you need to modify its jpeg_get_large and jpeg_free_large +routines to allocate far memory. In any case, you might like to replace +its calls to malloc and free with direct calls on Windows memory allocation +functions. + +You may also want to modify jdatasrc.c and jdatadst.c to use Windows file +operations rather than fread/fwrite. This is only necessary if your C +compiler doesn't provide a competent implementation of C stdio functions. + +You might want to tweak the RGB_xxx macros in jmorecfg.h so that the library +will accept or deliver color pixels in BGR sample order, not RGB; BGR order +is usually more convenient under Windows. Note that this change will break +the sample applications cjpeg/djpeg, but the library itself works fine. + + +Many people want to convert the IJG library into a DLL. This is reasonably +straightforward, but watch out for the following: + + 1. Don't try to compile as a DLL in small or medium memory model; use +large model, or even better, 32-bit flat model. Many places in the IJG code +assume the address of a local variable is an ordinary (not FAR) pointer; +that isn't true in a medium-model DLL. + + 2. Microsoft C cannot pass file pointers between applications and DLLs. +(See Microsoft Knowledge Base, PSS ID Number Q50336.) So jdatasrc.c and +jdatadst.c don't work if you open a file in your application and then pass +the pointer to the DLL. One workaround is to make jdatasrc.c/jdatadst.c +part of your main application rather than part of the DLL. + + 3. You'll probably need to modify the macros GLOBAL() and EXTERN() to +attach suitable linkage keywords to the exported routine names. Similarly, +you'll want to modify METHODDEF() and JMETHOD() to ensure function pointers +are declared in a way that lets application routines be called back through +the function pointers. These macros are in jmorecfg.h. Typical definitions +for a 16-bit DLL are: + #define GLOBAL(type) type _far _pascal _loadds _export + #define EXTERN(type) extern type _far _pascal _loadds + #define METHODDEF(type) static type _far _pascal + #define JMETHOD(type,methodname,arglist) \ + type (_far _pascal *methodname) arglist +For a 32-bit DLL you may want something like + #define GLOBAL(type) __declspec(dllexport) type + #define EXTERN(type) extern __declspec(dllexport) type +Although not all the GLOBAL routines are actually intended to be called by +the application, the performance cost of making them all DLL entry points is +negligible. + +The unmodified IJG library presents a very C-specific application interface, +so the resulting DLL is only usable from C or C++ applications. There has +been some talk of writing wrapper code that would present a simpler interface +usable from other languages, such as Visual Basic. This is on our to-do list +but hasn't been very high priority --- any volunteers out there? + + +Microsoft Windows, Borland C: + +The provided jconfig.bcc should work OK in a 32-bit Windows environment, +but you'll need to tweak it in a 16-bit environment (you'd need to define +NEED_FAR_POINTERS and MAX_ALLOC_CHUNK). Beware that makefile.bcc will need +alteration if you want to use it for Windows --- in particular, you should +use jmemnobs.c not jmemdos.c under Windows. + +Borland C++ 4.5 fails with an internal compiler error when trying to compile +jdmerge.c in 32-bit mode. If enough people complain, perhaps Borland will fix +it. In the meantime, the simplest known workaround is to add a redundant +definition of the variable range_limit in h2v1_merged_upsample(), at the head +of the block that handles odd image width (about line 268 in v6 jdmerge.c): + /* If image width is odd, do the last output column separately */ + if (cinfo->output_width & 1) { + register JSAMPLE * range_limit = cinfo->sample_range_limit; /* ADD THIS */ + cb = GETJSAMPLE(*inptr1); +Pretty bizarre, especially since the very similar routine h2v2_merged_upsample +doesn't trigger the bug. +Recent reports suggest that this bug does not occur with "bcc32a" (the +Pentium-optimized version of the compiler). + +Another report from a user of Borland C 4.5 was that incorrect code (leading +to a color shift in processed images) was produced if any of the following +optimization switch combinations were used: + -Ot -Og + -Ot -Op + -Ot -Om +So try backing off on optimization if you see such a problem. (Are there +several different releases all numbered "4.5"??) + + +Microsoft Windows, Microsoft Visual C++: + +jconfig.vc should work OK with any Microsoft compiler for a 32-bit memory +model. makefile.vc is intended for command-line use. (If you are using +the Developer Studio environment, you may prefer the DevStudio project +files; see below.) + +Some users feel that it's easier to call the library from C++ code if you +force VC++ to treat the library as C++ code, which you can do by renaming +all the *.c files to *.cpp (and adjusting the makefile to match). This +avoids the need to put extern "C" { ... } around #include "jpeglib.h" in +your C++ application. + + +Microsoft Windows, Microsoft Developer Studio: + +We include makefiles that should work as project files in DevStudio 4.2 or +later. There is a library makefile that builds the IJG library as a static +Win32 library, and an application makefile that builds the sample applications +as Win32 console applications. (Even if you only want the library, we +recommend building the applications so that you can run the self-test.) + +To use: +1. Copy jconfig.vc to jconfig.h, makelib.ds to jpeg.mak, and + makeapps.ds to apps.mak. (Note that the renaming is critical!) +2. Click on the .mak files to construct project workspaces. + (If you are using DevStudio more recent than 4.2, you'll probably + get a message saying that the makefiles are being updated.) +3. Build the library project, then the applications project. +4. Move the application .exe files from `app`\Release to an + appropriate location on your path. +5. To perform the self-test, execute the command line + NMAKE /f makefile.vc test + + +OS/2, Borland C++: + +Watch out for optimization bugs in older Borland compilers; you may need +to back off the optimization switch settings. See the comments in +makefile.bcc. + + +SGI: + +On some SGI systems, you may need to set "AR2= ar -ts" in the Makefile. +If you are using configure, you can do this by saying + ./configure RANLIB='ar -ts' +This change is not needed on all SGIs. Use it only if the make fails at the +stage of linking the completed programs. + +On the MIPS R4000 architecture (Indy, etc.), the compiler option "-mips2" +reportedly speeds up the float DCT method substantially, enough to make it +faster than the default int method (but still slower than the fast int +method). If you use -mips2, you may want to alter the default DCT method to +be float. To do this, put "#define JDCT_DEFAULT JDCT_FLOAT" in jconfig.h. + + +VMS: + +On an Alpha/VMS system with MMS, be sure to use the "/Marco=Alpha=1" +qualifier with MMS when building the JPEG package. + +VAX/VMS v5.5-1 may have problems with the test step of the build procedure +reporting differences when it compares the original and test images. If the +error points to the last block of the files, it is most likely bogus and may +be safely ignored. It seems to be because the files are Stream_LF and +Backup/Compare has difficulty with the (presumably) null padded files. +This problem was not observed on VAX/VMS v6.1 or AXP/VMS v6.1. diff --git a/jpegtran.1 b/jpegtran.1 new file mode 100644 index 00000000..6de18e2a --- /dev/null +++ b/jpegtran.1 @@ -0,0 +1,238 @@ +.TH JPEGTRAN 1 "3 August 1997" +.SH NAME +jpegtran \- lossless transformation of JPEG files +.SH SYNOPSIS +.B jpegtran +[ +.I options +] +[ +.I filename +] +.LP +.SH DESCRIPTION +.LP +.B jpegtran +performs various useful transformations of JPEG files. +It can translate the coded representation from one variant of JPEG to another, +for example from baseline JPEG to progressive JPEG or vice versa. It can also +perform some rearrangements of the image data, for example turning an image +from landscape to portrait format by rotation. +.PP +.B jpegtran +works by rearranging the compressed data (DCT coefficients), without +ever fully decoding the image. Therefore, its transformations are lossless: +there is no image degradation at all, which would not be true if you used +.B djpeg +followed by +.B cjpeg +to accomplish the same conversion. But by the same token, +.B jpegtran +cannot perform lossy operations such as changing the image quality. +.PP +.B jpegtran +reads the named JPEG/JFIF file, or the standard input if no file is +named, and produces a JPEG/JFIF file on the standard output. +.SH OPTIONS +All switch names may be abbreviated; for example, +.B \-optimize +may be written +.B \-opt +or +.BR \-o . +Upper and lower case are equivalent. +British spellings are also accepted (e.g., +.BR \-optimise ), +though for brevity these are not mentioned below. +.PP +To specify the coded JPEG representation used in the output file, +.B jpegtran +accepts a subset of the switches recognized by +.BR cjpeg : +.TP +.B \-optimize +Perform optimization of entropy encoding parameters. +.TP +.B \-progressive +Create progressive JPEG file. +.TP +.BI \-restart " N" +Emit a JPEG restart marker every N MCU rows, or every N MCU blocks if "B" is +attached to the number. +.TP +.BI \-scans " file" +Use the scan script given in the specified text file. +.PP +See +.BR cjpeg (1) +for more details about these switches. +If you specify none of these switches, you get a plain baseline-JPEG output +file. The quality setting and so forth are determined by the input file. +.PP +The image can be losslessly transformed by giving one of these switches: +.TP +.B \-flip horizontal +Mirror image horizontally (left-right). +.TP +.B \-flip vertical +Mirror image vertically (top-bottom). +.TP +.B \-rotate 90 +Rotate image 90 degrees clockwise. +.TP +.B \-rotate 180 +Rotate image 180 degrees. +.TP +.B \-rotate 270 +Rotate image 270 degrees clockwise (or 90 ccw). +.TP +.B \-transpose +Transpose image (across UL-to-LR axis). +.TP +.B \-transverse +Transverse transpose (across UR-to-LL axis). +.PP +The transpose transformation has no restrictions regarding image dimensions. +The other transformations operate rather oddly if the image dimensions are not +a multiple of the iMCU size (usually 8 or 16 pixels), because they can only +transform complete blocks of DCT coefficient data in the desired way. +.PP +.BR jpegtran 's +default behavior when transforming an odd-size image is designed +to preserve exact reversibility and mathematical consistency of the +transformation set. As stated, transpose is able to flip the entire image +area. Horizontal mirroring leaves any partial iMCU column at the right edge +untouched, but is able to flip all rows of the image. Similarly, vertical +mirroring leaves any partial iMCU row at the bottom edge untouched, but is +able to flip all columns. The other transforms can be built up as sequences +of transpose and flip operations; for consistency, their actions on edge +pixels are defined to be the same as the end result of the corresponding +transpose-and-flip sequence. +.PP +For practical use, you may prefer to discard any untransformable edge pixels +rather than having a strange-looking strip along the right and/or bottom edges +of a transformed image. To do this, add the +.B \-trim +switch: +.TP +.B \-trim +Drop non-transformable edge blocks. +.PP +Obviously, a transformation with +.B \-trim +is not reversible, so strictly speaking +.B jpegtran +with this switch is not lossless. Also, the expected mathematical +equivalences between the transformations no longer hold. For example, +.B \-rot 270 -trim +trims only the bottom edge, but +.B \-rot 90 -trim +followed by +.B \-rot 180 -trim +trims both edges. +.PP +Another not-strictly-lossless transformation switch is: +.TP +.B \-grayscale +Force grayscale output. +.PP +This option discards the chrominance channels if the input image is YCbCr +(ie, a standard color JPEG), resulting in a grayscale JPEG file. The +luminance channel is preserved exactly, so this is a better method of reducing +to grayscale than decompression, conversion, and recompression. This switch +is particularly handy for fixing a monochrome picture that was mistakenly +encoded as a color JPEG. (In such a case, the space savings from getting rid +of the near-empty chroma channels won't be large; but the decoding time for +a grayscale JPEG is substantially less than that for a color JPEG.) +.PP +.B jpegtran +also recognizes these switches that control what to do with "extra" markers, +such as comment blocks: +.TP +.B \-copy none +Copy no extra markers from source file. This setting suppresses all +comments and other excess baggage present in the source file. +.TP +.B \-copy comments +Copy only comment markers. This setting copies comments from the source file, +but discards any other inessential data. +.TP +.B \-copy all +Copy all extra markers. This setting preserves miscellaneous markers +found in the source file, such as JFIF thumbnails and Photoshop settings. +In some files these extra markers can be sizable. +.PP +The default behavior is +.BR "\-copy comments" . +(Note: in IJG releases v6 and v6a, +.B jpegtran +always did the equivalent of +.BR "\-copy none" .) +.PP +Additional switches recognized by jpegtran are: +.TP +.BI \-maxmemory " N" +Set limit for amount of memory to use in processing large images. Value is +in thousands of bytes, or millions of bytes if "M" is attached to the +number. For example, +.B \-max 4m +selects 4000000 bytes. If more space is needed, temporary files will be used. +.TP +.BI \-outfile " name" +Send output image to the named file, not to standard output. +.TP +.B \-verbose +Enable debug printout. More +.BR \-v 's +give more output. Also, version information is printed at startup. +.TP +.B \-debug +Same as +.BR \-verbose . +.SH EXAMPLES +.LP +This example converts a baseline JPEG file to progressive form: +.IP +.B jpegtran \-progressive +.I foo.jpg +.B > +.I fooprog.jpg +.PP +This example rotates an image 90 degrees clockwise, discarding any +unrotatable edge pixels: +.IP +.B jpegtran \-rot 90 -trim +.I foo.jpg +.B > +.I foo90.jpg +.SH ENVIRONMENT +.TP +.B JPEGMEM +If this environment variable is set, its value is the default memory limit. +The value is specified as described for the +.B \-maxmemory +switch. +.B JPEGMEM +overrides the default value specified when the program was compiled, and +itself is overridden by an explicit +.BR \-maxmemory . +.SH SEE ALSO +.BR cjpeg (1), +.BR djpeg (1), +.BR rdjpgcom (1), +.BR wrjpgcom (1) +.br +Wallace, Gregory K. "The JPEG Still Picture Compression Standard", +Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44. +.SH AUTHOR +Independent JPEG Group +.SH BUGS +Arithmetic coding is not supported for legal reasons. +.PP +The transform options can't transform odd-size images perfectly. Use +.B \-trim +if you don't like the results without it. +.PP +The entire image is read into memory and then written out again, even in +cases where this isn't really necessary. Expect swapping on large images, +especially when using the more complex transform options. diff --git a/jpegtran.c b/jpegtran.c new file mode 100644 index 00000000..20ef111b --- /dev/null +++ b/jpegtran.c @@ -0,0 +1,504 @@ +/* + * jpegtran.c + * + * Copyright (C) 1995-1997, Thomas G. Lane. + * This file is part of the Independent JPEG Group's software. + * For conditions of distribution and use, see the accompanying README file. + * + * This file contains a command-line user interface for JPEG transcoding. + * It is very similar to cjpeg.c, but provides lossless transcoding between + * different JPEG file formats. It also provides some lossless and sort-of- + * lossless transformations of JPEG data. + */ + +#include "cdjpeg.h" /* Common decls for cjpeg/djpeg applications */ +#include "transupp.h" /* Support routines for jpegtran */ +#include "jversion.h" /* for version message */ + +#ifdef USE_CCOMMAND /* command-line reader for Macintosh */ +#ifdef __MWERKS__ +#include /* Metrowerks needs this */ +#include /* ... and this */ +#endif +#ifdef THINK_C +#include /* Think declares it here */ +#endif +#endif + + +/* + * Argument-parsing code. + * The switch parser is designed to be useful with DOS-style command line + * syntax, ie, intermixed switches and file names, where only the switches + * to the left of a given file name affect processing of that file. + * The main program in this file doesn't actually use this capability... + */ + + +static const char * progname; /* program name for error messages */ +static char * outfilename; /* for -outfile switch */ +static JCOPY_OPTION copyoption; /* -copy switch */ +static jpeg_transform_info transformoption; /* image transformation options */ + + +LOCAL(void) +usage (void) +/* complain about bad command line */ +{ + fprintf(stderr, "usage: %s [switches] ", progname); +#ifdef TWO_FILE_COMMANDLINE + fprintf(stderr, "inputfile outputfile\n"); +#else + fprintf(stderr, "[inputfile]\n"); +#endif + + fprintf(stderr, "Switches (names may be abbreviated):\n"); + fprintf(stderr, " -copy none Copy no extra markers from source file\n"); + fprintf(stderr, " -copy comments Copy only comment markers (default)\n"); + fprintf(stderr, " -copy all Copy all extra markers\n"); +#ifdef ENTROPY_OPT_SUPPORTED + fprintf(stderr, " -optimize Optimize Huffman table (smaller file, but slow compression)\n"); +#endif +#ifdef C_PROGRESSIVE_SUPPORTED + fprintf(stderr, " -progressive Create progressive JPEG file\n"); +#endif +#if TRANSFORMS_SUPPORTED + fprintf(stderr, "Switches for modifying the image:\n"); + fprintf(stderr, " -grayscale Reduce to grayscale (omit color data)\n"); + fprintf(stderr, " -flip [horizontal|vertical] Mirror image (left-right or top-bottom)\n"); + fprintf(stderr, " -rotate [90|180|270] Rotate image (degrees clockwise)\n"); + fprintf(stderr, " -transpose Transpose image\n"); + fprintf(stderr, " -transverse Transverse transpose image\n"); + fprintf(stderr, " -trim Drop non-transformable edge blocks\n"); +#endif /* TRANSFORMS_SUPPORTED */ + fprintf(stderr, "Switches for advanced users:\n"); + fprintf(stderr, " -restart N Set restart interval in rows, or in blocks with B\n"); + fprintf(stderr, " -maxmemory N Maximum memory to use (in kbytes)\n"); + fprintf(stderr, " -outfile name Specify name for output file\n"); + fprintf(stderr, " -verbose or -debug Emit debug output\n"); + fprintf(stderr, "Switches for wizards:\n"); +#ifdef C_ARITH_CODING_SUPPORTED + fprintf(stderr, " -arithmetic Use arithmetic coding\n"); +#endif +#ifdef C_MULTISCAN_FILES_SUPPORTED + fprintf(stderr, " -scans file Create multi-scan JPEG per script file\n"); +#endif + exit(EXIT_FAILURE); +} + + +LOCAL(void) +select_transform (JXFORM_CODE transform) +/* Silly little routine to detect multiple transform options, + * which we can't handle. + */ +{ +#if TRANSFORMS_SUPPORTED + if (transformoption.transform == JXFORM_NONE || + transformoption.transform == transform) { + transformoption.transform = transform; + } else { + fprintf(stderr, "%s: can only do one image transformation at a time\n", + progname); + usage(); + } +#else + fprintf(stderr, "%s: sorry, image transformation was not compiled\n", + progname); + exit(EXIT_FAILURE); +#endif +} + + +LOCAL(int) +parse_switches (j_compress_ptr cinfo, int argc, char **argv, + int last_file_arg_seen, boolean for_real) +/* Parse optional switches. + * Returns argv[] index of first file-name argument (== argc if none). + * Any file names with indexes <= last_file_arg_seen are ignored; + * they have presumably been processed in a previous iteration. + * (Pass 0 for last_file_arg_seen on the first or only iteration.) + * for_real is FALSE on the first (dummy) pass; we may skip any expensive + * processing. + */ +{ + int argn; + char * arg; + boolean simple_progressive; + char * scansarg = NULL; /* saves -scans parm if any */ + + /* Set up default JPEG parameters. */ + simple_progressive = FALSE; + outfilename = NULL; + copyoption = JCOPYOPT_DEFAULT; + transformoption.transform = JXFORM_NONE; + transformoption.trim = FALSE; + transformoption.force_grayscale = FALSE; + cinfo->err->trace_level = 0; + + /* Scan command line options, adjust parameters */ + + for (argn = 1; argn < argc; argn++) { + arg = argv[argn]; + if (*arg != '-') { + /* Not a switch, must be a file name argument */ + if (argn <= last_file_arg_seen) { + outfilename = NULL; /* -outfile applies to just one input file */ + continue; /* ignore this name if previously processed */ + } + break; /* else done parsing switches */ + } + arg++; /* advance past switch marker character */ + + if (keymatch(arg, "arithmetic", 1)) { + /* Use arithmetic coding. */ +#ifdef C_ARITH_CODING_SUPPORTED + cinfo->arith_code = TRUE; +#else + fprintf(stderr, "%s: sorry, arithmetic coding not supported\n", + progname); + exit(EXIT_FAILURE); +#endif + + } else if (keymatch(arg, "copy", 1)) { + /* Select which extra markers to copy. */ + if (++argn >= argc) /* advance to next argument */ + usage(); + if (keymatch(argv[argn], "none", 1)) { + copyoption = JCOPYOPT_NONE; + } else if (keymatch(argv[argn], "comments", 1)) { + copyoption = JCOPYOPT_COMMENTS; + } else if (keymatch(argv[argn], "all", 1)) { + copyoption = JCOPYOPT_ALL; + } else + usage(); + + } else if (keymatch(arg, "debug", 1) || keymatch(arg, "verbose", 1)) { + /* Enable debug printouts. */ + /* On first -d, print version identification */ + static boolean printed_version = FALSE; + + if (! printed_version) { + fprintf(stderr, "Independent JPEG Group's JPEGTRAN, version %s\n%s\n", + JVERSION, JCOPYRIGHT); + printed_version = TRUE; + } + cinfo->err->trace_level++; + + } else if (keymatch(arg, "flip", 1)) { + /* Mirror left-right or top-bottom. */ + if (++argn >= argc) /* advance to next argument */ + usage(); + if (keymatch(argv[argn], "horizontal", 1)) + select_transform(JXFORM_FLIP_H); + else if (keymatch(argv[argn], "vertical", 1)) + select_transform(JXFORM_FLIP_V); + else + usage(); + + } else if (keymatch(arg, "grayscale", 1) || keymatch(arg, "greyscale",1)) { + /* Force to grayscale. */ +#if TRANSFORMS_SUPPORTED + transformoption.force_grayscale = TRUE; +#else + select_transform(JXFORM_NONE); /* force an error */ +#endif + + } else if (keymatch(arg, "maxmemory", 3)) { + /* Maximum memory in Kb (or Mb with 'm'). */ + long lval; + char ch = 'x'; + + if (++argn >= argc) /* advance to next argument */ + usage(); + if (sscanf(argv[argn], "%ld%c", &lval, &ch) < 1) + usage(); + if (ch == 'm' || ch == 'M') + lval *= 1000L; + cinfo->mem->max_memory_to_use = lval * 1000L; + + } else if (keymatch(arg, "optimize", 1) || keymatch(arg, "optimise", 1)) { + /* Enable entropy parm optimization. */ +#ifdef ENTROPY_OPT_SUPPORTED + cinfo->optimize_coding = TRUE; +#else + fprintf(stderr, "%s: sorry, entropy optimization was not compiled\n", + progname); + exit(EXIT_FAILURE); +#endif + + } else if (keymatch(arg, "outfile", 4)) { + /* Set output file name. */ + if (++argn >= argc) /* advance to next argument */ + usage(); + outfilename = argv[argn]; /* save it away for later use */ + + } else if (keymatch(arg, "progressive", 1)) { + /* Select simple progressive mode. */ +#ifdef C_PROGRESSIVE_SUPPORTED + simple_progressive = TRUE; + /* We must postpone execution until num_components is known. */ +#else + fprintf(stderr, "%s: sorry, progressive output was not compiled\n", + progname); + exit(EXIT_FAILURE); +#endif + + } else if (keymatch(arg, "restart", 1)) { + /* Restart interval in MCU rows (or in MCUs with 'b'). */ + long lval; + char ch = 'x'; + + if (++argn >= argc) /* advance to next argument */ + usage(); + if (sscanf(argv[argn], "%ld%c", &lval, &ch) < 1) + usage(); + if (lval < 0 || lval > 65535L) + usage(); + if (ch == 'b' || ch == 'B') { + cinfo->restart_interval = (unsigned int) lval; + cinfo->restart_in_rows = 0; /* else prior '-restart n' overrides me */ + } else { + cinfo->restart_in_rows = (int) lval; + /* restart_interval will be computed during startup */ + } + + } else if (keymatch(arg, "rotate", 2)) { + /* Rotate 90, 180, or 270 degrees (measured clockwise). */ + if (++argn >= argc) /* advance to next argument */ + usage(); + if (keymatch(argv[argn], "90", 2)) + select_transform(JXFORM_ROT_90); + else if (keymatch(argv[argn], "180", 3)) + select_transform(JXFORM_ROT_180); + else if (keymatch(argv[argn], "270", 3)) + select_transform(JXFORM_ROT_270); + else + usage(); + + } else if (keymatch(arg, "scans", 1)) { + /* Set scan script. */ +#ifdef C_MULTISCAN_FILES_SUPPORTED + if (++argn >= argc) /* advance to next argument */ + usage(); + scansarg = argv[argn]; + /* We must postpone reading the file in case -progressive appears. */ +#else + fprintf(stderr, "%s: sorry, multi-scan output was not compiled\n", + progname); + exit(EXIT_FAILURE); +#endif + + } else if (keymatch(arg, "transpose", 1)) { + /* Transpose (across UL-to-LR axis). */ + select_transform(JXFORM_TRANSPOSE); + + } else if (keymatch(arg, "transverse", 6)) { + /* Transverse transpose (across UR-to-LL axis). */ + select_transform(JXFORM_TRANSVERSE); + + } else if (keymatch(arg, "trim", 3)) { + /* Trim off any partial edge MCUs that the transform can't handle. */ + transformoption.trim = TRUE; + + } else { + usage(); /* bogus switch */ + } + } + + /* Post-switch-scanning cleanup */ + + if (for_real) { + +#ifdef C_PROGRESSIVE_SUPPORTED + if (simple_progressive) /* process -progressive; -scans can override */ + jpeg_simple_progression(cinfo); +#endif + +#ifdef C_MULTISCAN_FILES_SUPPORTED + if (scansarg != NULL) /* process -scans if it was present */ + if (! read_scan_script(cinfo, scansarg)) + usage(); +#endif + } + + return argn; /* return index of next arg (file name) */ +} + + +/* + * The main program. + */ + +int +main (int argc, char **argv) +{ + struct jpeg_decompress_struct srcinfo; + struct jpeg_compress_struct dstinfo; + struct jpeg_error_mgr jsrcerr, jdsterr; +#ifdef PROGRESS_REPORT + struct cdjpeg_progress_mgr progress; +#endif + jvirt_barray_ptr * src_coef_arrays; + jvirt_barray_ptr * dst_coef_arrays; + int file_index; + FILE * input_file; + FILE * output_file; + + /* On Mac, fetch a command line. */ +#ifdef USE_CCOMMAND + argc = ccommand(&argv); +#endif + + progname = argv[0]; + if (progname == NULL || progname[0] == 0) + progname = "jpegtran"; /* in case C library doesn't provide it */ + + /* Initialize the JPEG decompression object with default error handling. */ + srcinfo.err = jpeg_std_error(&jsrcerr); + jpeg_create_decompress(&srcinfo); + /* Initialize the JPEG compression object with default error handling. */ + dstinfo.err = jpeg_std_error(&jdsterr); + jpeg_create_compress(&dstinfo); + + /* Now safe to enable signal catcher. + * Note: we assume only the decompression object will have virtual arrays. + */ +#ifdef NEED_SIGNAL_CATCHER + enable_signal_catcher((j_common_ptr) &srcinfo); +#endif + + /* Scan command line to find file names. + * It is convenient to use just one switch-parsing routine, but the switch + * values read here are mostly ignored; we will rescan the switches after + * opening the input file. Also note that most of the switches affect the + * destination JPEG object, so we parse into that and then copy over what + * needs to affects the source too. + */ + + file_index = parse_switches(&dstinfo, argc, argv, 0, FALSE); + jsrcerr.trace_level = jdsterr.trace_level; + srcinfo.mem->max_memory_to_use = dstinfo.mem->max_memory_to_use; + +#ifdef TWO_FILE_COMMANDLINE + /* Must have either -outfile switch or explicit output file name */ + if (outfilename == NULL) { + if (file_index != argc-2) { + fprintf(stderr, "%s: must name one input and one output file\n", + progname); + usage(); + } + outfilename = argv[file_index+1]; + } else { + if (file_index != argc-1) { + fprintf(stderr, "%s: must name one input and one output file\n", + progname); + usage(); + } + } +#else + /* Unix style: expect zero or one file name */ + if (file_index < argc-1) { + fprintf(stderr, "%s: only one input file\n", progname); + usage(); + } +#endif /* TWO_FILE_COMMANDLINE */ + + /* Open the input file. */ + if (file_index < argc) { + if ((input_file = fopen(argv[file_index], READ_BINARY)) == NULL) { + fprintf(stderr, "%s: can't open %s\n", progname, argv[file_index]); + exit(EXIT_FAILURE); + } + } else { + /* default input file is stdin */ + input_file = read_stdin(); + } + + /* Open the output file. */ + if (outfilename != NULL) { + if ((output_file = fopen(outfilename, WRITE_BINARY)) == NULL) { + fprintf(stderr, "%s: can't open %s\n", progname, outfilename); + exit(EXIT_FAILURE); + } + } else { + /* default output file is stdout */ + output_file = write_stdout(); + } + +#ifdef PROGRESS_REPORT + start_progress_monitor((j_common_ptr) &dstinfo, &progress); +#endif + + /* Specify data source for decompression */ + jpeg_stdio_src(&srcinfo, input_file); + + /* Enable saving of extra markers that we want to copy */ + jcopy_markers_setup(&srcinfo, copyoption); + + /* Read file header */ + (void) jpeg_read_header(&srcinfo, TRUE); + + /* Any space needed by a transform option must be requested before + * jpeg_read_coefficients so that memory allocation will be done right. + */ +#if TRANSFORMS_SUPPORTED + jtransform_request_workspace(&srcinfo, &transformoption); +#endif + + /* Read source file as DCT coefficients */ + src_coef_arrays = jpeg_read_coefficients(&srcinfo); + + /* Initialize destination compression parameters from source values */ + jpeg_copy_critical_parameters(&srcinfo, &dstinfo); + + /* Adjust destination parameters if required by transform options; + * also find out which set of coefficient arrays will hold the output. + */ +#if TRANSFORMS_SUPPORTED + dst_coef_arrays = jtransform_adjust_parameters(&srcinfo, &dstinfo, + src_coef_arrays, + &transformoption); +#else + dst_coef_arrays = src_coef_arrays; +#endif + + /* Adjust default compression parameters by re-parsing the options */ + file_index = parse_switches(&dstinfo, argc, argv, 0, TRUE); + + /* Specify data destination for compression */ + jpeg_stdio_dest(&dstinfo, output_file); + + /* Start compressor (note no image data is actually written here) */ + jpeg_write_coefficients(&dstinfo, dst_coef_arrays); + + /* Copy to the output file any extra markers that we want to preserve */ + jcopy_markers_execute(&srcinfo, &dstinfo, copyoption); + + /* Execute image transformation, if any */ +#if TRANSFORMS_SUPPORTED + jtransform_execute_transformation(&srcinfo, &dstinfo, + src_coef_arrays, + &transformoption); +#endif + + /* Finish compression and release memory */ + jpeg_finish_compress(&dstinfo); + jpeg_destroy_compress(&dstinfo); + (void) jpeg_finish_decompress(&srcinfo); + jpeg_destroy_decompress(&srcinfo); + + /* Close files, if we opened them */ + if (input_file != stdin) + fclose(input_file); + if (output_file != stdout) + fclose(output_file); + +#ifdef PROGRESS_REPORT + end_progress_monitor((j_common_ptr) &dstinfo); +#endif + + /* All done. */ + exit(jsrcerr.num_warnings + jdsterr.num_warnings ?EXIT_WARNING:EXIT_SUCCESS); + return 0; /* suppress no-return-value warnings */ +} diff --git a/libjpeg.doc b/libjpeg.doc new file mode 100644 index 00000000..689b206c --- /dev/null +++ b/libjpeg.doc @@ -0,0 +1,3006 @@ +USING THE IJG JPEG LIBRARY + +Copyright (C) 1994-1998, Thomas G. Lane. +This file is part of the Independent JPEG Group's software. +For conditions of distribution and use, see the accompanying README file. + + +This file describes how to use the IJG JPEG library within an application +program. Read it if you want to write a program that uses the library. + +The file example.c provides heavily commented skeleton code for calling the +JPEG library. Also see jpeglib.h (the include file to be used by application +programs) for full details about data structures and function parameter lists. +The library source code, of course, is the ultimate reference. + +Note that there have been *major* changes from the application interface +presented by IJG version 4 and earlier versions. The old design had several +inherent limitations, and it had accumulated a lot of cruft as we added +features while trying to minimize application-interface changes. We have +sacrificed backward compatibility in the version 5 rewrite, but we think the +improvements justify this. + + +TABLE OF CONTENTS +----------------- + +Overview: + Functions provided by the library + Outline of typical usage +Basic library usage: + Data formats + Compression details + Decompression details + Mechanics of usage: include files, linking, etc +Advanced features: + Compression parameter selection + Decompression parameter selection + Special color spaces + Error handling + Compressed data handling (source and destination managers) + I/O suspension + Progressive JPEG support + Buffered-image mode + Abbreviated datastreams and multiple images + Special markers + Raw (downsampled) image data + Really raw data: DCT coefficients + Progress monitoring + Memory management + Memory usage + Library compile-time options + Portability considerations + Notes for MS-DOS implementors + +You should read at least the overview and basic usage sections before trying +to program with the library. The sections on advanced features can be read +if and when you need them. + + +OVERVIEW +======== + +Functions provided by the library +--------------------------------- + +The IJG JPEG library provides C code to read and write JPEG-compressed image +files. The surrounding application program receives or supplies image data a +scanline at a time, using a straightforward uncompressed image format. All +details of color conversion and other preprocessing/postprocessing can be +handled by the library. + +The library includes a substantial amount of code that is not covered by the +JPEG standard but is necessary for typical applications of JPEG. These +functions preprocess the image before JPEG compression or postprocess it after +decompression. They include colorspace conversion, downsampling/upsampling, +and color quantization. The application indirectly selects use of this code +by specifying the format in which it wishes to supply or receive image data. +For example, if colormapped output is requested, then the decompression +library automatically invokes color quantization. + +A wide range of quality vs. speed tradeoffs are possible in JPEG processing, +and even more so in decompression postprocessing. The decompression library +provides multiple implementations that cover most of the useful tradeoffs, +ranging from very-high-quality down to fast-preview operation. On the +compression side we have generally not provided low-quality choices, since +compression is normally less time-critical. It should be understood that the +low-quality modes may not meet the JPEG standard's accuracy requirements; +nonetheless, they are useful for viewers. + +A word about functions *not* provided by the library. We handle a subset of +the ISO JPEG standard; most baseline, extended-sequential, and progressive +JPEG processes are supported. (Our subset includes all features now in common +use.) Unsupported ISO options include: + * Hierarchical storage + * Lossless JPEG + * Arithmetic entropy coding (unsupported for legal reasons) + * DNL marker + * Nonintegral subsampling ratios +We support both 8- and 12-bit data precision, but this is a compile-time +choice rather than a run-time choice; hence it is difficult to use both +precisions in a single application. + +By itself, the library handles only interchange JPEG datastreams --- in +particular the widely used JFIF file format. The library can be used by +surrounding code to process interchange or abbreviated JPEG datastreams that +are embedded in more complex file formats. (For example, this library is +used by the free LIBTIFF library to support JPEG compression in TIFF.) + + +Outline of typical usage +------------------------ + +The rough outline of a JPEG compression operation is: + + Allocate and initialize a JPEG compression object + Specify the destination for the compressed data (eg, a file) + Set parameters for compression, including image size & colorspace + jpeg_start_compress(...); + while (scan lines remain to be written) + jpeg_write_scanlines(...); + jpeg_finish_compress(...); + Release the JPEG compression object + +A JPEG compression object holds parameters and working state for the JPEG +library. We make creation/destruction of the object separate from starting +or finishing compression of an image; the same object can be re-used for a +series of image compression operations. This makes it easy to re-use the +same parameter settings for a sequence of images. Re-use of a JPEG object +also has important implications for processing abbreviated JPEG datastreams, +as discussed later. + +The image data to be compressed is supplied to jpeg_write_scanlines() from +in-memory buffers. If the application is doing file-to-file compression, +reading image data from the source file is the application's responsibility. +The library emits compressed data by calling a "data destination manager", +which typically will write the data into a file; but the application can +provide its own destination manager to do something else. + +Similarly, the rough outline of a JPEG decompression operation is: + + Allocate and initialize a JPEG decompression object + Specify the source of the compressed data (eg, a file) + Call jpeg_read_header() to obtain image info + Set parameters for decompression + jpeg_start_decompress(...); + while (scan lines remain to be read) + jpeg_read_scanlines(...); + jpeg_finish_decompress(...); + Release the JPEG decompression object + +This is comparable to the compression outline except that reading the +datastream header is a separate step. This is helpful because information +about the image's size, colorspace, etc is available when the application +selects decompression parameters. For example, the application can choose an +output scaling ratio that will fit the image into the available screen size. + +The decompression library obtains compressed data by calling a data source +manager, which typically will read the data from a file; but other behaviors +can be obtained with a custom source manager. Decompressed data is delivered +into in-memory buffers passed to jpeg_read_scanlines(). + +It is possible to abort an incomplete compression or decompression operation +by calling jpeg_abort(); or, if you do not need to retain the JPEG object, +simply release it by calling jpeg_destroy(). + +JPEG compression and decompression objects are two separate struct types. +However, they share some common fields, and certain routines such as +jpeg_destroy() can work on either type of object. + +The JPEG library has no static variables: all state is in the compression +or decompression object. Therefore it is possible to process multiple +compression and decompression operations concurrently, using multiple JPEG +objects. + +Both compression and decompression can be done in an incremental memory-to- +memory fashion, if suitable source/destination managers are used. See the +section on "I/O suspension" for more details. + + +BASIC LIBRARY USAGE +=================== + +Data formats +------------ + +Before diving into procedural details, it is helpful to understand the +image data format that the JPEG library expects or returns. + +The standard input image format is a rectangular array of pixels, with each +pixel having the same number of "component" or "sample" values (color +channels). You must specify how many components there are and the colorspace +interpretation of the components. Most applications will use RGB data +(three components per pixel) or grayscale data (one component per pixel). +PLEASE NOTE THAT RGB DATA IS THREE SAMPLES PER PIXEL, GRAYSCALE ONLY ONE. +A remarkable number of people manage to miss this, only to find that their +programs don't work with grayscale JPEG files. + +There is no provision for colormapped input. JPEG files are always full-color +or full grayscale (or sometimes another colorspace such as CMYK). You can +feed in a colormapped image by expanding it to full-color format. However +JPEG often doesn't work very well with source data that has been colormapped, +because of dithering noise. This is discussed in more detail in the JPEG FAQ +and the other references mentioned in the README file. + +Pixels are stored by scanlines, with each scanline running from left to +right. The component values for each pixel are adjacent in the row; for +example, R,G,B,R,G,B,R,G,B,... for 24-bit RGB color. Each scanline is an +array of data type JSAMPLE --- which is typically "unsigned char", unless +you've changed jmorecfg.h. (You can also change the RGB pixel layout, say +to B,G,R order, by modifying jmorecfg.h. But see the restrictions listed in +that file before doing so.) + +A 2-D array of pixels is formed by making a list of pointers to the starts of +scanlines; so the scanlines need not be physically adjacent in memory. Even +if you process just one scanline at a time, you must make a one-element +pointer array to conform to this structure. Pointers to JSAMPLE rows are of +type JSAMPROW, and the pointer to the pointer array is of type JSAMPARRAY. + +The library accepts or supplies one or more complete scanlines per call. +It is not possible to process part of a row at a time. Scanlines are always +processed top-to-bottom. You can process an entire image in one call if you +have it all in memory, but usually it's simplest to process one scanline at +a time. + +For best results, source data values should have the precision specified by +BITS_IN_JSAMPLE (normally 8 bits). For instance, if you choose to compress +data that's only 6 bits/channel, you should left-justify each value in a +byte before passing it to the compressor. If you need to compress data +that has more than 8 bits/channel, compile with BITS_IN_JSAMPLE = 12. +(See "Library compile-time options", later.) + + +The data format returned by the decompressor is the same in all details, +except that colormapped output is supported. (Again, a JPEG file is never +colormapped. But you can ask the decompressor to perform on-the-fly color +quantization to deliver colormapped output.) If you request colormapped +output then the returned data array contains a single JSAMPLE per pixel; +its value is an index into a color map. The color map is represented as +a 2-D JSAMPARRAY in which each row holds the values of one color component, +that is, colormap[i][j] is the value of the i'th color component for pixel +value (map index) j. Note that since the colormap indexes are stored in +JSAMPLEs, the maximum number of colors is limited by the size of JSAMPLE +(ie, at most 256 colors for an 8-bit JPEG library). + + +Compression details +------------------- + +Here we revisit the JPEG compression outline given in the overview. + +1. Allocate and initialize a JPEG compression object. + +A JPEG compression object is a "struct jpeg_compress_struct". (It also has +a bunch of subsidiary structures which are allocated via malloc(), but the +application doesn't control those directly.) This struct can be just a local +variable in the calling routine, if a single routine is going to execute the +whole JPEG compression sequence. Otherwise it can be static or allocated +from malloc(). + +You will also need a structure representing a JPEG error handler. The part +of this that the library cares about is a "struct jpeg_error_mgr". If you +are providing your own error handler, you'll typically want to embed the +jpeg_error_mgr struct in a larger structure; this is discussed later under +"Error handling". For now we'll assume you are just using the default error +handler. The default error handler will print JPEG error/warning messages +on stderr, and it will call exit() if a fatal error occurs. + +You must initialize the error handler structure, store a pointer to it into +the JPEG object's "err" field, and then call jpeg_create_compress() to +initialize the rest of the JPEG object. + +Typical code for this step, if you are using the default error handler, is + + struct jpeg_compress_struct cinfo; + struct jpeg_error_mgr jerr; + ... + cinfo.err = jpeg_std_error(&jerr); + jpeg_create_compress(&cinfo); + +jpeg_create_compress allocates a small amount of memory, so it could fail +if you are out of memory. In that case it will exit via the error handler; +that's why the error handler must be initialized first. + + +2. Specify the destination for the compressed data (eg, a file). + +As previously mentioned, the JPEG library delivers compressed data to a +"data destination" module. The library includes one data destination +module which knows how to write to a stdio stream. You can use your own +destination module if you want to do something else, as discussed later. + +If you use the standard destination module, you must open the target stdio +stream beforehand. Typical code for this step looks like: + + FILE * outfile; + ... + if ((outfile = fopen(filename, "wb")) == NULL) { + fprintf(stderr, "can't open %s\n", filename); + exit(1); + } + jpeg_stdio_dest(&cinfo, outfile); + +where the last line invokes the standard destination module. + +WARNING: it is critical that the binary compressed data be delivered to the +output file unchanged. On non-Unix systems the stdio library may perform +newline translation or otherwise corrupt binary data. To suppress this +behavior, you may need to use a "b" option to fopen (as shown above), or use +setmode() or another routine to put the stdio stream in binary mode. See +cjpeg.c and djpeg.c for code that has been found to work on many systems. + +You can select the data destination after setting other parameters (step 3), +if that's more convenient. You may not change the destination between +calling jpeg_start_compress() and jpeg_finish_compress(). + + +3. Set parameters for compression, including image size & colorspace. + +You must supply information about the source image by setting the following +fields in the JPEG object (cinfo structure): + + image_width Width of image, in pixels + image_height Height of image, in pixels + input_components Number of color channels (samples per pixel) + in_color_space Color space of source image + +The image dimensions are, hopefully, obvious. JPEG supports image dimensions +of 1 to 64K pixels in either direction. The input color space is typically +RGB or grayscale, and input_components is 3 or 1 accordingly. (See "Special +color spaces", later, for more info.) The in_color_space field must be +assigned one of the J_COLOR_SPACE enum constants, typically JCS_RGB or +JCS_GRAYSCALE. + +JPEG has a large number of compression parameters that determine how the +image is encoded. Most applications don't need or want to know about all +these parameters. You can set all the parameters to reasonable defaults by +calling jpeg_set_defaults(); then, if there are particular values you want +to change, you can do so after that. The "Compression parameter selection" +section tells about all the parameters. + +You must set in_color_space correctly before calling jpeg_set_defaults(), +because the defaults depend on the source image colorspace. However the +other three source image parameters need not be valid until you call +jpeg_start_compress(). There's no harm in calling jpeg_set_defaults() more +than once, if that happens to be convenient. + +Typical code for a 24-bit RGB source image is + + cinfo.image_width = Width; /* image width and height, in pixels */ + cinfo.image_height = Height; + cinfo.input_components = 3; /* # of color components per pixel */ + cinfo.in_color_space = JCS_RGB; /* colorspace of input image */ + + jpeg_set_defaults(&cinfo); + /* Make optional parameter settings here */ + + +4. jpeg_start_compress(...); + +After you have established the data destination and set all the necessary +source image info and other parameters, call jpeg_start_compress() to begin +a compression cycle. This will initialize internal state, allocate working +storage, and emit the first few bytes of the JPEG datastream header. + +Typical code: + + jpeg_start_compress(&cinfo, TRUE); + +The "TRUE" parameter ensures that a complete JPEG interchange datastream +will be written. This is appropriate in most cases. If you think you might +want to use an abbreviated datastream, read the section on abbreviated +datastreams, below. + +Once you have called jpeg_start_compress(), you may not alter any JPEG +parameters or other fields of the JPEG object until you have completed +the compression cycle. + + +5. while (scan lines remain to be written) + jpeg_write_scanlines(...); + +Now write all the required image data by calling jpeg_write_scanlines() +one or more times. You can pass one or more scanlines in each call, up +to the total image height. In most applications it is convenient to pass +just one or a few scanlines at a time. The expected format for the passed +data is discussed under "Data formats", above. + +Image data should be written in top-to-bottom scanline order. The JPEG spec +contains some weasel wording about how top and bottom are application-defined +terms (a curious interpretation of the English language...) but if you want +your files to be compatible with everyone else's, you WILL use top-to-bottom +order. If the source data must be read in bottom-to-top order, you can use +the JPEG library's virtual array mechanism to invert the data efficiently. +Examples of this can be found in the sample application cjpeg. + +The library maintains a count of the number of scanlines written so far +in the next_scanline field of the JPEG object. Usually you can just use +this variable as the loop counter, so that the loop test looks like +"while (cinfo.next_scanline < cinfo.image_height)". + +Code for this step depends heavily on the way that you store the source data. +example.c shows the following code for the case of a full-size 2-D source +array containing 3-byte RGB pixels: + + JSAMPROW row_pointer[1]; /* pointer to a single row */ + int row_stride; /* physical row width in buffer */ + + row_stride = image_width * 3; /* JSAMPLEs per row in image_buffer */ + + while (cinfo.next_scanline < cinfo.image_height) { + row_pointer[0] = & image_buffer[cinfo.next_scanline * row_stride]; + jpeg_write_scanlines(&cinfo, row_pointer, 1); + } + +jpeg_write_scanlines() returns the number of scanlines actually written. +This will normally be equal to the number passed in, so you can usually +ignore the return value. It is different in just two cases: + * If you try to write more scanlines than the declared image height, + the additional scanlines are ignored. + * If you use a suspending data destination manager, output buffer overrun + will cause the compressor to return before accepting all the passed lines. + This feature is discussed under "I/O suspension", below. The normal + stdio destination manager will NOT cause this to happen. +In any case, the return value is the same as the change in the value of +next_scanline. + + +6. jpeg_finish_compress(...); + +After all the image data has been written, call jpeg_finish_compress() to +complete the compression cycle. This step is ESSENTIAL to ensure that the +last bufferload of data is written to the data destination. +jpeg_finish_compress() also releases working memory associated with the JPEG +object. + +Typical code: + + jpeg_finish_compress(&cinfo); + +If using the stdio destination manager, don't forget to close the output +stdio stream (if necessary) afterwards. + +If you have requested a multi-pass operating mode, such as Huffman code +optimization, jpeg_finish_compress() will perform the additional passes using +data buffered by the first pass. In this case jpeg_finish_compress() may take +quite a while to complete. With the default compression parameters, this will +not happen. + +It is an error to call jpeg_finish_compress() before writing the necessary +total number of scanlines. If you wish to abort compression, call +jpeg_abort() as discussed below. + +After completing a compression cycle, you may dispose of the JPEG object +as discussed next, or you may use it to compress another image. In that case +return to step 2, 3, or 4 as appropriate. If you do not change the +destination manager, the new datastream will be written to the same target. +If you do not change any JPEG parameters, the new datastream will be written +with the same parameters as before. Note that you can change the input image +dimensions freely between cycles, but if you change the input colorspace, you +should call jpeg_set_defaults() to adjust for the new colorspace; and then +you'll need to repeat all of step 3. + + +7. Release the JPEG compression object. + +When you are done with a JPEG compression object, destroy it by calling +jpeg_destroy_compress(). This will free all subsidiary memory (regardless of +the previous state of the object). Or you can call jpeg_destroy(), which +works for either compression or decompression objects --- this may be more +convenient if you are sharing code between compression and decompression +cases. (Actually, these routines are equivalent except for the declared type +of the passed pointer. To avoid gripes from ANSI C compilers, jpeg_destroy() +should be passed a j_common_ptr.) + +If you allocated the jpeg_compress_struct structure from malloc(), freeing +it is your responsibility --- jpeg_destroy() won't. Ditto for the error +handler structure. + +Typical code: + + jpeg_destroy_compress(&cinfo); + + +8. Aborting. + +If you decide to abort a compression cycle before finishing, you can clean up +in either of two ways: + +* If you don't need the JPEG object any more, just call + jpeg_destroy_compress() or jpeg_destroy() to release memory. This is + legitimate at any point after calling jpeg_create_compress() --- in fact, + it's safe even if jpeg_create_compress() fails. + +* If you want to re-use the JPEG object, call jpeg_abort_compress(), or call + jpeg_abort() which works on both compression and decompression objects. + This will return the object to an idle state, releasing any working memory. + jpeg_abort() is allowed at any time after successful object creation. + +Note that cleaning up the data destination, if required, is your +responsibility; neither of these routines will call term_destination(). +(See "Compressed data handling", below, for more about that.) + +jpeg_destroy() and jpeg_abort() are the only safe calls to make on a JPEG +object that has reported an error by calling error_exit (see "Error handling" +for more info). The internal state of such an object is likely to be out of +whack. Either of these two routines will return the object to a known state. + + +Decompression details +--------------------- + +Here we revisit the JPEG decompression outline given in the overview. + +1. Allocate and initialize a JPEG decompression object. + +This is just like initialization for compression, as discussed above, +except that the object is a "struct jpeg_decompress_struct" and you +call jpeg_create_decompress(). Error handling is exactly the same. + +Typical code: + + struct jpeg_decompress_struct cinfo; + struct jpeg_error_mgr jerr; + ... + cinfo.err = jpeg_std_error(&jerr); + jpeg_create_decompress(&cinfo); + +(Both here and in the IJG code, we usually use variable name "cinfo" for +both compression and decompression objects.) + + +2. Specify the source of the compressed data (eg, a file). + +As previously mentioned, the JPEG library reads compressed data from a "data +source" module. The library includes one data source module which knows how +to read from a stdio stream. You can use your own source module if you want +to do something else, as discussed later. + +If you use the standard source module, you must open the source stdio stream +beforehand. Typical code for this step looks like: + + FILE * infile; + ... + if ((infile = fopen(filename, "rb")) == NULL) { + fprintf(stderr, "can't open %s\n", filename); + exit(1); + } + jpeg_stdio_src(&cinfo, infile); + +where the last line invokes the standard source module. + +WARNING: it is critical that the binary compressed data be read unchanged. +On non-Unix systems the stdio library may perform newline translation or +otherwise corrupt binary data. To suppress this behavior, you may need to use +a "b" option to fopen (as shown above), or use setmode() or another routine to +put the stdio stream in binary mode. See cjpeg.c and djpeg.c for code that +has been found to work on many systems. + +You may not change the data source between calling jpeg_read_header() and +jpeg_finish_decompress(). If you wish to read a series of JPEG images from +a single source file, you should repeat the jpeg_read_header() to +jpeg_finish_decompress() sequence without reinitializing either the JPEG +object or the data source module; this prevents buffered input data from +being discarded. + + +3. Call jpeg_read_header() to obtain image info. + +Typical code for this step is just + + jpeg_read_header(&cinfo, TRUE); + +This will read the source datastream header markers, up to the beginning +of the compressed data proper. On return, the image dimensions and other +info have been stored in the JPEG object. The application may wish to +consult this information before selecting decompression parameters. + +More complex code is necessary if + * A suspending data source is used --- in that case jpeg_read_header() + may return before it has read all the header data. See "I/O suspension", + below. The normal stdio source manager will NOT cause this to happen. + * Abbreviated JPEG files are to be processed --- see the section on + abbreviated datastreams. Standard applications that deal only in + interchange JPEG files need not be concerned with this case either. + +It is permissible to stop at this point if you just wanted to find out the +image dimensions and other header info for a JPEG file. In that case, +call jpeg_destroy() when you are done with the JPEG object, or call +jpeg_abort() to return it to an idle state before selecting a new data +source and reading another header. + + +4. Set parameters for decompression. + +jpeg_read_header() sets appropriate default decompression parameters based on +the properties of the image (in particular, its colorspace). However, you +may well want to alter these defaults before beginning the decompression. +For example, the default is to produce full color output from a color file. +If you want colormapped output you must ask for it. Other options allow the +returned image to be scaled and allow various speed/quality tradeoffs to be +selected. "Decompression parameter selection", below, gives details. + +If the defaults are appropriate, nothing need be done at this step. + +Note that all default values are set by each call to jpeg_read_header(). +If you reuse a decompression object, you cannot expect your parameter +settings to be preserved across cycles, as you can for compression. +You must set desired parameter values each time. + + +5. jpeg_start_decompress(...); + +Once the parameter values are satisfactory, call jpeg_start_decompress() to +begin decompression. This will initialize internal state, allocate working +memory, and prepare for returning data. + +Typical code is just + + jpeg_start_decompress(&cinfo); + +If you have requested a multi-pass operating mode, such as 2-pass color +quantization, jpeg_start_decompress() will do everything needed before data +output can begin. In this case jpeg_start_decompress() may take quite a while +to complete. With a single-scan (non progressive) JPEG file and default +decompression parameters, this will not happen; jpeg_start_decompress() will +return quickly. + +After this call, the final output image dimensions, including any requested +scaling, are available in the JPEG object; so is the selected colormap, if +colormapped output has been requested. Useful fields include + + output_width image width and height, as scaled + output_height + out_color_components # of color components in out_color_space + output_components # of color components returned per pixel + colormap the selected colormap, if any + actual_number_of_colors number of entries in colormap + +output_components is 1 (a colormap index) when quantizing colors; otherwise it +equals out_color_components. It is the number of JSAMPLE values that will be +emitted per pixel in the output arrays. + +Typically you will need to allocate data buffers to hold the incoming image. +You will need output_width * output_components JSAMPLEs per scanline in your +output buffer, and a total of output_height scanlines will be returned. + +Note: if you are using the JPEG library's internal memory manager to allocate +data buffers (as djpeg does), then the manager's protocol requires that you +request large buffers *before* calling jpeg_start_decompress(). This is a +little tricky since the output_XXX fields are not normally valid then. You +can make them valid by calling jpeg_calc_output_dimensions() after setting the +relevant parameters (scaling, output color space, and quantization flag). + + +6. while (scan lines remain to be read) + jpeg_read_scanlines(...); + +Now you can read the decompressed image data by calling jpeg_read_scanlines() +one or more times. At each call, you pass in the maximum number of scanlines +to be read (ie, the height of your working buffer); jpeg_read_scanlines() +will return up to that many lines. The return value is the number of lines +actually read. The format of the returned data is discussed under "Data +formats", above. Don't forget that grayscale and color JPEGs will return +different data formats! + +Image data is returned in top-to-bottom scanline order. If you must write +out the image in bottom-to-top order, you can use the JPEG library's virtual +array mechanism to invert the data efficiently. Examples of this can be +found in the sample application djpeg. + +The library maintains a count of the number of scanlines returned so far +in the output_scanline field of the JPEG object. Usually you can just use +this variable as the loop counter, so that the loop test looks like +"while (cinfo.output_scanline < cinfo.output_height)". (Note that the test +should NOT be against image_height, unless you never use scaling. The +image_height field is the height of the original unscaled image.) +The return value always equals the change in the value of output_scanline. + +If you don't use a suspending data source, it is safe to assume that +jpeg_read_scanlines() reads at least one scanline per call, until the +bottom of the image has been reached. + +If you use a buffer larger than one scanline, it is NOT safe to assume that +jpeg_read_scanlines() fills it. (The current implementation returns only a +few scanlines per call, no matter how large a buffer you pass.) So you must +always provide a loop that calls jpeg_read_scanlines() repeatedly until the +whole image has been read. + + +7. jpeg_finish_decompress(...); + +After all the image data has been read, call jpeg_finish_decompress() to +complete the decompression cycle. This causes working memory associated +with the JPEG object to be released. + +Typical code: + + jpeg_finish_decompress(&cinfo); + +If using the stdio source manager, don't forget to close the source stdio +stream if necessary. + +It is an error to call jpeg_finish_decompress() before reading the correct +total number of scanlines. If you wish to abort decompression, call +jpeg_abort() as discussed below. + +After completing a decompression cycle, you may dispose of the JPEG object as +discussed next, or you may use it to decompress another image. In that case +return to step 2 or 3 as appropriate. If you do not change the source +manager, the next image will be read from the same source. + + +8. Release the JPEG decompression object. + +When you are done with a JPEG decompression object, destroy it by calling +jpeg_destroy_decompress() or jpeg_destroy(). The previous discussion of +destroying compression objects applies here too. + +Typical code: + + jpeg_destroy_decompress(&cinfo); + + +9. Aborting. + +You can abort a decompression cycle by calling jpeg_destroy_decompress() or +jpeg_destroy() if you don't need the JPEG object any more, or +jpeg_abort_decompress() or jpeg_abort() if you want to reuse the object. +The previous discussion of aborting compression cycles applies here too. + + +Mechanics of usage: include files, linking, etc +----------------------------------------------- + +Applications using the JPEG library should include the header file jpeglib.h +to obtain declarations of data types and routines. Before including +jpeglib.h, include system headers that define at least the typedefs FILE and +size_t. On ANSI-conforming systems, including is sufficient; on +older Unix systems, you may need to define size_t. + +If the application needs to refer to individual JPEG library error codes, also +include jerror.h to define those symbols. + +jpeglib.h indirectly includes the files jconfig.h and jmorecfg.h. If you are +installing the JPEG header files in a system directory, you will want to +install all four files: jpeglib.h, jerror.h, jconfig.h, jmorecfg.h. + +The most convenient way to include the JPEG code into your executable program +is to prepare a library file ("libjpeg.a", or a corresponding name on non-Unix +machines) and reference it at your link step. If you use only half of the +library (only compression or only decompression), only that much code will be +included from the library, unless your linker is hopelessly brain-damaged. +The supplied makefiles build libjpeg.a automatically (see install.doc). + +While you can build the JPEG library as a shared library if the whim strikes +you, we don't really recommend it. The trouble with shared libraries is that +at some point you'll probably try to substitute a new version of the library +without recompiling the calling applications. That generally doesn't work +because the parameter struct declarations usually change with each new +version. In other words, the library's API is *not* guaranteed binary +compatible across versions; we only try to ensure source-code compatibility. +(In hindsight, it might have been smarter to hide the parameter structs from +applications and introduce a ton of access functions instead. Too late now, +however.) + +On some systems your application may need to set up a signal handler to ensure +that temporary files are deleted if the program is interrupted. This is most +critical if you are on MS-DOS and use the jmemdos.c memory manager back end; +it will try to grab extended memory for temp files, and that space will NOT be +freed automatically. See cjpeg.c or djpeg.c for an example signal handler. + +It may be worth pointing out that the core JPEG library does not actually +require the stdio library: only the default source/destination managers and +error handler need it. You can use the library in a stdio-less environment +if you replace those modules and use jmemnobs.c (or another memory manager of +your own devising). More info about the minimum system library requirements +may be found in jinclude.h. + + +ADVANCED FEATURES +================= + +Compression parameter selection +------------------------------- + +This section describes all the optional parameters you can set for JPEG +compression, as well as the "helper" routines provided to assist in this +task. Proper setting of some parameters requires detailed understanding +of the JPEG standard; if you don't know what a parameter is for, it's best +not to mess with it! See REFERENCES in the README file for pointers to +more info about JPEG. + +It's a good idea to call jpeg_set_defaults() first, even if you plan to set +all the parameters; that way your code is more likely to work with future JPEG +libraries that have additional parameters. For the same reason, we recommend +you use a helper routine where one is provided, in preference to twiddling +cinfo fields directly. + +The helper routines are: + +jpeg_set_defaults (j_compress_ptr cinfo) + This routine sets all JPEG parameters to reasonable defaults, using + only the input image's color space (field in_color_space, which must + already be set in cinfo). Many applications will only need to use + this routine and perhaps jpeg_set_quality(). + +jpeg_set_colorspace (j_compress_ptr cinfo, J_COLOR_SPACE colorspace) + Sets the JPEG file's colorspace (field jpeg_color_space) as specified, + and sets other color-space-dependent parameters appropriately. See + "Special color spaces", below, before using this. A large number of + parameters, including all per-component parameters, are set by this + routine; if you want to twiddle individual parameters you should call + jpeg_set_colorspace() before rather than after. + +jpeg_default_colorspace (j_compress_ptr cinfo) + Selects an appropriate JPEG colorspace based on cinfo->in_color_space, + and calls jpeg_set_colorspace(). This is actually a subroutine of + jpeg_set_defaults(). It's broken out in case you want to change + just the colorspace-dependent JPEG parameters. + +jpeg_set_quality (j_compress_ptr cinfo, int quality, boolean force_baseline) + Constructs JPEG quantization tables appropriate for the indicated + quality setting. The quality value is expressed on the 0..100 scale + recommended by IJG (cjpeg's "-quality" switch uses this routine). + Note that the exact mapping from quality values to tables may change + in future IJG releases as more is learned about DCT quantization. + If the force_baseline parameter is TRUE, then the quantization table + entries are constrained to the range 1..255 for full JPEG baseline + compatibility. In the current implementation, this only makes a + difference for quality settings below 25, and it effectively prevents + very small/low quality files from being generated. The IJG decoder + is capable of reading the non-baseline files generated at low quality + settings when force_baseline is FALSE, but other decoders may not be. + +jpeg_set_linear_quality (j_compress_ptr cinfo, int scale_factor, + boolean force_baseline) + Same as jpeg_set_quality() except that the generated tables are the + sample tables given in the JPEC spec section K.1, multiplied by the + specified scale factor (which is expressed as a percentage; thus + scale_factor = 100 reproduces the spec's tables). Note that larger + scale factors give lower quality. This entry point is useful for + conforming to the Adobe PostScript DCT conventions, but we do not + recommend linear scaling as a user-visible quality scale otherwise. + force_baseline again constrains the computed table entries to 1..255. + +int jpeg_quality_scaling (int quality) + Converts a value on the IJG-recommended quality scale to a linear + scaling percentage. Note that this routine may change or go away + in future releases --- IJG may choose to adopt a scaling method that + can't be expressed as a simple scalar multiplier, in which case the + premise of this routine collapses. Caveat user. + +jpeg_add_quant_table (j_compress_ptr cinfo, int which_tbl, + const unsigned int *basic_table, + int scale_factor, boolean force_baseline) + Allows an arbitrary quantization table to be created. which_tbl + indicates which table slot to fill. basic_table points to an array + of 64 unsigned ints given in normal array order. These values are + multiplied by scale_factor/100 and then clamped to the range 1..65535 + (or to 1..255 if force_baseline is TRUE). + CAUTION: prior to library version 6a, jpeg_add_quant_table expected + the basic table to be given in JPEG zigzag order. If you need to + write code that works with either older or newer versions of this + routine, you must check the library version number. Something like + "#if JPEG_LIB_VERSION >= 61" is the right test. + +jpeg_simple_progression (j_compress_ptr cinfo) + Generates a default scan script for writing a progressive-JPEG file. + This is the recommended method of creating a progressive file, + unless you want to make a custom scan sequence. You must ensure that + the JPEG color space is set correctly before calling this routine. + + +Compression parameters (cinfo fields) include: + +J_DCT_METHOD dct_method + Selects the algorithm used for the DCT step. Choices are: + JDCT_ISLOW: slow but accurate integer algorithm + JDCT_IFAST: faster, less accurate integer method + JDCT_FLOAT: floating-point method + JDCT_DEFAULT: default method (normally JDCT_ISLOW) + JDCT_FASTEST: fastest method (normally JDCT_IFAST) + The FLOAT method is very slightly more accurate than the ISLOW method, + but may give different results on different machines due to varying + roundoff behavior. The integer methods should give the same results + on all machines. On machines with sufficiently fast FP hardware, the + floating-point method may also be the fastest. The IFAST method is + considerably less accurate than the other two; its use is not + recommended if high quality is a concern. JDCT_DEFAULT and + JDCT_FASTEST are macros configurable by each installation. + +J_COLOR_SPACE jpeg_color_space +int num_components + The JPEG color space and corresponding number of components; see + "Special color spaces", below, for more info. We recommend using + jpeg_set_color_space() if you want to change these. + +boolean optimize_coding + TRUE causes the compressor to compute optimal Huffman coding tables + for the image. This requires an extra pass over the data and + therefore costs a good deal of space and time. The default is + FALSE, which tells the compressor to use the supplied or default + Huffman tables. In most cases optimal tables save only a few percent + of file size compared to the default tables. Note that when this is + TRUE, you need not supply Huffman tables at all, and any you do + supply will be overwritten. + +unsigned int restart_interval +int restart_in_rows + To emit restart markers in the JPEG file, set one of these nonzero. + Set restart_interval to specify the exact interval in MCU blocks. + Set restart_in_rows to specify the interval in MCU rows. (If + restart_in_rows is not 0, then restart_interval is set after the + image width in MCUs is computed.) Defaults are zero (no restarts). + One restart marker per MCU row is often a good choice. + NOTE: the overhead of restart markers is higher in grayscale JPEG + files than in color files, and MUCH higher in progressive JPEGs. + If you use restarts, you may want to use larger intervals in those + cases. + +const jpeg_scan_info * scan_info +int num_scans + By default, scan_info is NULL; this causes the compressor to write a + single-scan sequential JPEG file. If not NULL, scan_info points to + an array of scan definition records of length num_scans. The + compressor will then write a JPEG file having one scan for each scan + definition record. This is used to generate noninterleaved or + progressive JPEG files. The library checks that the scan array + defines a valid JPEG scan sequence. (jpeg_simple_progression creates + a suitable scan definition array for progressive JPEG.) This is + discussed further under "Progressive JPEG support". + +int smoothing_factor + If non-zero, the input image is smoothed; the value should be 1 for + minimal smoothing to 100 for maximum smoothing. Consult jcsample.c + for details of the smoothing algorithm. The default is zero. + +boolean write_JFIF_header + If TRUE, a JFIF APP0 marker is emitted. jpeg_set_defaults() and + jpeg_set_colorspace() set this TRUE if a JFIF-legal JPEG color space + (ie, YCbCr or grayscale) is selected, otherwise FALSE. + +UINT8 JFIF_major_version +UINT8 JFIF_minor_version + The version number to be written into the JFIF marker. + jpeg_set_defaults() initializes the version to 1.01 (major=minor=1). + You should set it to 1.02 (major=1, minor=2) if you plan to write + any JFIF 1.02 extension markers. + +UINT8 density_unit +UINT16 X_density +UINT16 Y_density + The resolution information to be written into the JFIF marker; + not used otherwise. density_unit may be 0 for unknown, + 1 for dots/inch, or 2 for dots/cm. The default values are 0,1,1 + indicating square pixels of unknown size. + +boolean write_Adobe_marker + If TRUE, an Adobe APP14 marker is emitted. jpeg_set_defaults() and + jpeg_set_colorspace() set this TRUE if JPEG color space RGB, CMYK, + or YCCK is selected, otherwise FALSE. It is generally a bad idea + to set both write_JFIF_header and write_Adobe_marker. In fact, + you probably shouldn't change the default settings at all --- the + default behavior ensures that the JPEG file's color space can be + recognized by the decoder. + +JQUANT_TBL * quant_tbl_ptrs[NUM_QUANT_TBLS] + Pointers to coefficient quantization tables, one per table slot, + or NULL if no table is defined for a slot. Usually these should + be set via one of the above helper routines; jpeg_add_quant_table() + is general enough to define any quantization table. The other + routines will set up table slot 0 for luminance quality and table + slot 1 for chrominance. + +JHUFF_TBL * dc_huff_tbl_ptrs[NUM_HUFF_TBLS] +JHUFF_TBL * ac_huff_tbl_ptrs[NUM_HUFF_TBLS] + Pointers to Huffman coding tables, one per table slot, or NULL if + no table is defined for a slot. Slots 0 and 1 are filled with the + JPEG sample tables by jpeg_set_defaults(). If you need to allocate + more table structures, jpeg_alloc_huff_table() may be used. + Note that optimal Huffman tables can be computed for an image + by setting optimize_coding, as discussed above; there's seldom + any need to mess with providing your own Huffman tables. + +There are some additional cinfo fields which are not documented here +because you currently can't change them; for example, you can't set +arith_code TRUE because arithmetic coding is unsupported. + + +Per-component parameters are stored in the struct cinfo.comp_info[i] for +component number i. Note that components here refer to components of the +JPEG color space, *not* the source image color space. A suitably large +comp_info[] array is allocated by jpeg_set_defaults(); if you choose not +to use that routine, it's up to you to allocate the array. + +int component_id + The one-byte identifier code to be recorded in the JPEG file for + this component. For the standard color spaces, we recommend you + leave the default values alone. + +int h_samp_factor +int v_samp_factor + Horizontal and vertical sampling factors for the component; must + be 1..4 according to the JPEG standard. Note that larger sampling + factors indicate a higher-resolution component; many people find + this behavior quite unintuitive. The default values are 2,2 for + luminance components and 1,1 for chrominance components, except + for grayscale where 1,1 is used. + +int quant_tbl_no + Quantization table number for component. The default value is + 0 for luminance components and 1 for chrominance components. + +int dc_tbl_no +int ac_tbl_no + DC and AC entropy coding table numbers. The default values are + 0 for luminance components and 1 for chrominance components. + +int component_index + Must equal the component's index in comp_info[]. (Beginning in + release v6, the compressor library will fill this in automatically; + you don't have to.) + + +Decompression parameter selection +--------------------------------- + +Decompression parameter selection is somewhat simpler than compression +parameter selection, since all of the JPEG internal parameters are +recorded in the source file and need not be supplied by the application. +(Unless you are working with abbreviated files, in which case see +"Abbreviated datastreams", below.) Decompression parameters control +the postprocessing done on the image to deliver it in a format suitable +for the application's use. Many of the parameters control speed/quality +tradeoffs, in which faster decompression may be obtained at the price of +a poorer-quality image. The defaults select the highest quality (slowest) +processing. + +The following fields in the JPEG object are set by jpeg_read_header() and +may be useful to the application in choosing decompression parameters: + +JDIMENSION image_width Width and height of image +JDIMENSION image_height +int num_components Number of color components +J_COLOR_SPACE jpeg_color_space Colorspace of image +boolean saw_JFIF_marker TRUE if a JFIF APP0 marker was seen + UINT8 JFIF_major_version Version information from JFIF marker + UINT8 JFIF_minor_version + UINT8 density_unit Resolution data from JFIF marker + UINT16 X_density + UINT16 Y_density +boolean saw_Adobe_marker TRUE if an Adobe APP14 marker was seen + UINT8 Adobe_transform Color transform code from Adobe marker + +The JPEG color space, unfortunately, is something of a guess since the JPEG +standard proper does not provide a way to record it. In practice most files +adhere to the JFIF or Adobe conventions, and the decoder will recognize these +correctly. See "Special color spaces", below, for more info. + + +The decompression parameters that determine the basic properties of the +returned image are: + +J_COLOR_SPACE out_color_space + Output color space. jpeg_read_header() sets an appropriate default + based on jpeg_color_space; typically it will be RGB or grayscale. + The application can change this field to request output in a different + colorspace. For example, set it to JCS_GRAYSCALE to get grayscale + output from a color file. (This is useful for previewing: grayscale + output is faster than full color since the color components need not + be processed.) Note that not all possible color space transforms are + currently implemented; you may need to extend jdcolor.c if you want an + unusual conversion. + +unsigned int scale_num, scale_denom + Scale the image by the fraction scale_num/scale_denom. Default is + 1/1, or no scaling. Currently, the only supported scaling ratios + are 1/1, 1/2, 1/4, and 1/8. (The library design allows for arbitrary + scaling ratios but this is not likely to be implemented any time soon.) + Smaller scaling ratios permit significantly faster decoding since + fewer pixels need be processed and a simpler IDCT method can be used. + +boolean quantize_colors + If set TRUE, colormapped output will be delivered. Default is FALSE, + meaning that full-color output will be delivered. + +The next three parameters are relevant only if quantize_colors is TRUE. + +int desired_number_of_colors + Maximum number of colors to use in generating a library-supplied color + map (the actual number of colors is returned in a different field). + Default 256. Ignored when the application supplies its own color map. + +boolean two_pass_quantize + If TRUE, an extra pass over the image is made to select a custom color + map for the image. This usually looks a lot better than the one-size- + fits-all colormap that is used otherwise. Default is TRUE. Ignored + when the application supplies its own color map. + +J_DITHER_MODE dither_mode + Selects color dithering method. Supported values are: + JDITHER_NONE no dithering: fast, very low quality + JDITHER_ORDERED ordered dither: moderate speed and quality + JDITHER_FS Floyd-Steinberg dither: slow, high quality + Default is JDITHER_FS. (At present, ordered dither is implemented + only in the single-pass, standard-colormap case. If you ask for + ordered dither when two_pass_quantize is TRUE or when you supply + an external color map, you'll get F-S dithering.) + +When quantize_colors is TRUE, the target color map is described by the next +two fields. colormap is set to NULL by jpeg_read_header(). The application +can supply a color map by setting colormap non-NULL and setting +actual_number_of_colors to the map size. Otherwise, jpeg_start_decompress() +selects a suitable color map and sets these two fields itself. +[Implementation restriction: at present, an externally supplied colormap is +only accepted for 3-component output color spaces.] + +JSAMPARRAY colormap + The color map, represented as a 2-D pixel array of out_color_components + rows and actual_number_of_colors columns. Ignored if not quantizing. + CAUTION: if the JPEG library creates its own colormap, the storage + pointed to by this field is released by jpeg_finish_decompress(). + Copy the colormap somewhere else first, if you want to save it. + +int actual_number_of_colors + The number of colors in the color map. + +Additional decompression parameters that the application may set include: + +J_DCT_METHOD dct_method + Selects the algorithm used for the DCT step. Choices are the same + as described above for compression. + +boolean do_fancy_upsampling + If TRUE, do careful upsampling of chroma components. If FALSE, + a faster but sloppier method is used. Default is TRUE. The visual + impact of the sloppier method is often very small. + +boolean do_block_smoothing + If TRUE, interblock smoothing is applied in early stages of decoding + progressive JPEG files; if FALSE, not. Default is TRUE. Early + progression stages look "fuzzy" with smoothing, "blocky" without. + In any case, block smoothing ceases to be applied after the first few + AC coefficients are known to full accuracy, so it is relevant only + when using buffered-image mode for progressive images. + +boolean enable_1pass_quant +boolean enable_external_quant +boolean enable_2pass_quant + These are significant only in buffered-image mode, which is + described in its own section below. + + +The output image dimensions are given by the following fields. These are +computed from the source image dimensions and the decompression parameters +by jpeg_start_decompress(). You can also call jpeg_calc_output_dimensions() +to obtain the values that will result from the current parameter settings. +This can be useful if you are trying to pick a scaling ratio that will get +close to a desired target size. It's also important if you are using the +JPEG library's memory manager to allocate output buffer space, because you +are supposed to request such buffers *before* jpeg_start_decompress(). + +JDIMENSION output_width Actual dimensions of output image. +JDIMENSION output_height +int out_color_components Number of color components in out_color_space. +int output_components Number of color components returned. +int rec_outbuf_height Recommended height of scanline buffer. + +When quantizing colors, output_components is 1, indicating a single color map +index per pixel. Otherwise it equals out_color_components. The output arrays +are required to be output_width * output_components JSAMPLEs wide. + +rec_outbuf_height is the recommended minimum height (in scanlines) of the +buffer passed to jpeg_read_scanlines(). If the buffer is smaller, the +library will still work, but time will be wasted due to unnecessary data +copying. In high-quality modes, rec_outbuf_height is always 1, but some +faster, lower-quality modes set it to larger values (typically 2 to 4). +If you are going to ask for a high-speed processing mode, you may as well +go to the trouble of honoring rec_outbuf_height so as to avoid data copying. +(An output buffer larger than rec_outbuf_height lines is OK, but won't +provide any material speed improvement over that height.) + + +Special color spaces +-------------------- + +The JPEG standard itself is "color blind" and doesn't specify any particular +color space. It is customary to convert color data to a luminance/chrominance +color space before compressing, since this permits greater compression. The +existing de-facto JPEG file format standards specify YCbCr or grayscale data +(JFIF), or grayscale, RGB, YCbCr, CMYK, or YCCK (Adobe). For special +applications such as multispectral images, other color spaces can be used, +but it must be understood that such files will be unportable. + +The JPEG library can handle the most common colorspace conversions (namely +RGB <=> YCbCr and CMYK <=> YCCK). It can also deal with data of an unknown +color space, passing it through without conversion. If you deal extensively +with an unusual color space, you can easily extend the library to understand +additional color spaces and perform appropriate conversions. + +For compression, the source data's color space is specified by field +in_color_space. This is transformed to the JPEG file's color space given +by jpeg_color_space. jpeg_set_defaults() chooses a reasonable JPEG color +space depending on in_color_space, but you can override this by calling +jpeg_set_colorspace(). Of course you must select a supported transformation. +jccolor.c currently supports the following transformations: + RGB => YCbCr + RGB => GRAYSCALE + YCbCr => GRAYSCALE + CMYK => YCCK +plus the null transforms: GRAYSCALE => GRAYSCALE, RGB => RGB, +YCbCr => YCbCr, CMYK => CMYK, YCCK => YCCK, and UNKNOWN => UNKNOWN. + +The de-facto file format standards (JFIF and Adobe) specify APPn markers that +indicate the color space of the JPEG file. It is important to ensure that +these are written correctly, or omitted if the JPEG file's color space is not +one of the ones supported by the de-facto standards. jpeg_set_colorspace() +will set the compression parameters to include or omit the APPn markers +properly, so long as it is told the truth about the JPEG color space. +For example, if you are writing some random 3-component color space without +conversion, don't try to fake out the library by setting in_color_space and +jpeg_color_space to JCS_YCbCr; use JCS_UNKNOWN. You may want to write an +APPn marker of your own devising to identify the colorspace --- see "Special +markers", below. + +When told that the color space is UNKNOWN, the library will default to using +luminance-quality compression parameters for all color components. You may +well want to change these parameters. See the source code for +jpeg_set_colorspace(), in jcparam.c, for details. + +For decompression, the JPEG file's color space is given in jpeg_color_space, +and this is transformed to the output color space out_color_space. +jpeg_read_header's setting of jpeg_color_space can be relied on if the file +conforms to JFIF or Adobe conventions, but otherwise it is no better than a +guess. If you know the JPEG file's color space for certain, you can override +jpeg_read_header's guess by setting jpeg_color_space. jpeg_read_header also +selects a default output color space based on (its guess of) jpeg_color_space; +set out_color_space to override this. Again, you must select a supported +transformation. jdcolor.c currently supports + YCbCr => GRAYSCALE + YCbCr => RGB + GRAYSCALE => RGB + YCCK => CMYK +as well as the null transforms. (Since GRAYSCALE=>RGB is provided, an +application can force grayscale JPEGs to look like color JPEGs if it only +wants to handle one case.) + +The two-pass color quantizer, jquant2.c, is specialized to handle RGB data +(it weights distances appropriately for RGB colors). You'll need to modify +the code if you want to use it for non-RGB output color spaces. Note that +jquant2.c is used to map to an application-supplied colormap as well as for +the normal two-pass colormap selection process. + +CAUTION: it appears that Adobe Photoshop writes inverted data in CMYK JPEG +files: 0 represents 100% ink coverage, rather than 0% ink as you'd expect. +This is arguably a bug in Photoshop, but if you need to work with Photoshop +CMYK files, you will have to deal with it in your application. We cannot +"fix" this in the library by inverting the data during the CMYK<=>YCCK +transform, because that would break other applications, notably Ghostscript. +Photoshop versions prior to 3.0 write EPS files containing JPEG-encoded CMYK +data in the same inverted-YCCK representation used in bare JPEG files, but +the surrounding PostScript code performs an inversion using the PS image +operator. I am told that Photoshop 3.0 will write uninverted YCCK in +EPS/JPEG files, and will omit the PS-level inversion. (But the data +polarity used in bare JPEG files will not change in 3.0.) In either case, +the JPEG library must not invert the data itself, or else Ghostscript would +read these EPS files incorrectly. + + +Error handling +-------------- + +When the default error handler is used, any error detected inside the JPEG +routines will cause a message to be printed on stderr, followed by exit(). +You can supply your own error handling routines to override this behavior +and to control the treatment of nonfatal warnings and trace/debug messages. +The file example.c illustrates the most common case, which is to have the +application regain control after an error rather than exiting. + +The JPEG library never writes any message directly; it always goes through +the error handling routines. Three classes of messages are recognized: + * Fatal errors: the library cannot continue. + * Warnings: the library can continue, but the data is corrupt, and a + damaged output image is likely to result. + * Trace/informational messages. These come with a trace level indicating + the importance of the message; you can control the verbosity of the + program by adjusting the maximum trace level that will be displayed. + +You may, if you wish, simply replace the entire JPEG error handling module +(jerror.c) with your own code. However, you can avoid code duplication by +only replacing some of the routines depending on the behavior you need. +This is accomplished by calling jpeg_std_error() as usual, but then overriding +some of the method pointers in the jpeg_error_mgr struct, as illustrated by +example.c. + +All of the error handling routines will receive a pointer to the JPEG object +(a j_common_ptr which points to either a jpeg_compress_struct or a +jpeg_decompress_struct; if you need to tell which, test the is_decompressor +field). This struct includes a pointer to the error manager struct in its +"err" field. Frequently, custom error handler routines will need to access +additional data which is not known to the JPEG library or the standard error +handler. The most convenient way to do this is to embed either the JPEG +object or the jpeg_error_mgr struct in a larger structure that contains +additional fields; then casting the passed pointer provides access to the +additional fields. Again, see example.c for one way to do it. (Beginning +with IJG version 6b, there is also a void pointer "client_data" in each +JPEG object, which the application can also use to find related data. +The library does not touch client_data at all.) + +The individual methods that you might wish to override are: + +error_exit (j_common_ptr cinfo) + Receives control for a fatal error. Information sufficient to + generate the error message has been stored in cinfo->err; call + output_message to display it. Control must NOT return to the caller; + generally this routine will exit() or longjmp() somewhere. + Typically you would override this routine to get rid of the exit() + default behavior. Note that if you continue processing, you should + clean up the JPEG object with jpeg_abort() or jpeg_destroy(). + +output_message (j_common_ptr cinfo) + Actual output of any JPEG message. Override this to send messages + somewhere other than stderr. Note that this method does not know + how to generate a message, only where to send it. + +format_message (j_common_ptr cinfo, char * buffer) + Constructs a readable error message string based on the error info + stored in cinfo->err. This method is called by output_message. Few + applications should need to override this method. One possible + reason for doing so is to implement dynamic switching of error message + language. + +emit_message (j_common_ptr cinfo, int msg_level) + Decide whether or not to emit a warning or trace message; if so, + calls output_message. The main reason for overriding this method + would be to abort on warnings. msg_level is -1 for warnings, + 0 and up for trace messages. + +Only error_exit() and emit_message() are called from the rest of the JPEG +library; the other two are internal to the error handler. + +The actual message texts are stored in an array of strings which is pointed to +by the field err->jpeg_message_table. The messages are numbered from 0 to +err->last_jpeg_message, and it is these code numbers that are used in the +JPEG library code. You could replace the message texts (for instance, with +messages in French or German) by changing the message table pointer. See +jerror.h for the default texts. CAUTION: this table will almost certainly +change or grow from one library version to the next. + +It may be useful for an application to add its own message texts that are +handled by the same mechanism. The error handler supports a second "add-on" +message table for this purpose. To define an addon table, set the pointer +err->addon_message_table and the message numbers err->first_addon_message and +err->last_addon_message. If you number the addon messages beginning at 1000 +or so, you won't have to worry about conflicts with the library's built-in +messages. See the sample applications cjpeg/djpeg for an example of using +addon messages (the addon messages are defined in cderror.h). + +Actual invocation of the error handler is done via macros defined in jerror.h: + ERREXITn(...) for fatal errors + WARNMSn(...) for corrupt-data warnings + TRACEMSn(...) for trace and informational messages. +These macros store the message code and any additional parameters into the +error handler struct, then invoke the error_exit() or emit_message() method. +The variants of each macro are for varying numbers of additional parameters. +The additional parameters are inserted into the generated message using +standard printf() format codes. + +See jerror.h and jerror.c for further details. + + +Compressed data handling (source and destination managers) +---------------------------------------------------------- + +The JPEG compression library sends its compressed data to a "destination +manager" module. The default destination manager just writes the data to a +stdio stream, but you can provide your own manager to do something else. +Similarly, the decompression library calls a "source manager" to obtain the +compressed data; you can provide your own source manager if you want the data +to come from somewhere other than a stdio stream. + +In both cases, compressed data is processed a bufferload at a time: the +destination or source manager provides a work buffer, and the library invokes +the manager only when the buffer is filled or emptied. (You could define a +one-character buffer to force the manager to be invoked for each byte, but +that would be rather inefficient.) The buffer's size and location are +controlled by the manager, not by the library. For example, if you desired to +decompress a JPEG datastream that was all in memory, you could just make the +buffer pointer and length point to the original data in memory. Then the +buffer-reload procedure would be invoked only if the decompressor ran off the +end of the datastream, which would indicate an erroneous datastream. + +The work buffer is defined as an array of datatype JOCTET, which is generally +"char" or "unsigned char". On a machine where char is not exactly 8 bits +wide, you must define JOCTET as a wider data type and then modify the data +source and destination modules to transcribe the work arrays into 8-bit units +on external storage. + +A data destination manager struct contains a pointer and count defining the +next byte to write in the work buffer and the remaining free space: + + JOCTET * next_output_byte; /* => next byte to write in buffer */ + size_t free_in_buffer; /* # of byte spaces remaining in buffer */ + +The library increments the pointer and decrements the count until the buffer +is filled. The manager's empty_output_buffer method must reset the pointer +and count. The manager is expected to remember the buffer's starting address +and total size in private fields not visible to the library. + +A data destination manager provides three methods: + +init_destination (j_compress_ptr cinfo) + Initialize destination. This is called by jpeg_start_compress() + before any data is actually written. It must initialize + next_output_byte and free_in_buffer. free_in_buffer must be + initialized to a positive value. + +empty_output_buffer (j_compress_ptr cinfo) + This is called whenever the buffer has filled (free_in_buffer + reaches zero). In typical applications, it should write out the + *entire* buffer (use the saved start address and buffer length; + ignore the current state of next_output_byte and free_in_buffer). + Then reset the pointer & count to the start of the buffer, and + return TRUE indicating that the buffer has been dumped. + free_in_buffer must be set to a positive value when TRUE is + returned. A FALSE return should only be used when I/O suspension is + desired (this operating mode is discussed in the next section). + +term_destination (j_compress_ptr cinfo) + Terminate destination --- called by jpeg_finish_compress() after all + data has been written. In most applications, this must flush any + data remaining in the buffer. Use either next_output_byte or + free_in_buffer to determine how much data is in the buffer. + +term_destination() is NOT called by jpeg_abort() or jpeg_destroy(). If you +want the destination manager to be cleaned up during an abort, you must do it +yourself. + +You will also need code to create a jpeg_destination_mgr struct, fill in its +method pointers, and insert a pointer to the struct into the "dest" field of +the JPEG compression object. This can be done in-line in your setup code if +you like, but it's probably cleaner to provide a separate routine similar to +the jpeg_stdio_dest() routine of the supplied destination manager. + +Decompression source managers follow a parallel design, but with some +additional frammishes. The source manager struct contains a pointer and count +defining the next byte to read from the work buffer and the number of bytes +remaining: + + const JOCTET * next_input_byte; /* => next byte to read from buffer */ + size_t bytes_in_buffer; /* # of bytes remaining in buffer */ + +The library increments the pointer and decrements the count until the buffer +is emptied. The manager's fill_input_buffer method must reset the pointer and +count. In most applications, the manager must remember the buffer's starting +address and total size in private fields not visible to the library. + +A data source manager provides five methods: + +init_source (j_decompress_ptr cinfo) + Initialize source. This is called by jpeg_read_header() before any + data is actually read. Unlike init_destination(), it may leave + bytes_in_buffer set to 0 (in which case a fill_input_buffer() call + will occur immediately). + +fill_input_buffer (j_decompress_ptr cinfo) + This is called whenever bytes_in_buffer has reached zero and more + data is wanted. In typical applications, it should read fresh data + into the buffer (ignoring the current state of next_input_byte and + bytes_in_buffer), reset the pointer & count to the start of the + buffer, and return TRUE indicating that the buffer has been reloaded. + It is not necessary to fill the buffer entirely, only to obtain at + least one more byte. bytes_in_buffer MUST be set to a positive value + if TRUE is returned. A FALSE return should only be used when I/O + suspension is desired (this mode is discussed in the next section). + +skip_input_data (j_decompress_ptr cinfo, long num_bytes) + Skip num_bytes worth of data. The buffer pointer and count should + be advanced over num_bytes input bytes, refilling the buffer as + needed. This is used to skip over a potentially large amount of + uninteresting data (such as an APPn marker). In some applications + it may be possible to optimize away the reading of the skipped data, + but it's not clear that being smart is worth much trouble; large + skips are uncommon. bytes_in_buffer may be zero on return. + A zero or negative skip count should be treated as a no-op. + +resync_to_restart (j_decompress_ptr cinfo, int desired) + This routine is called only when the decompressor has failed to find + a restart (RSTn) marker where one is expected. Its mission is to + find a suitable point for resuming decompression. For most + applications, we recommend that you just use the default resync + procedure, jpeg_resync_to_restart(). However, if you are able to back + up in the input data stream, or if you have a-priori knowledge about + the likely location of restart markers, you may be able to do better. + Read the read_restart_marker() and jpeg_resync_to_restart() routines + in jdmarker.c if you think you'd like to implement your own resync + procedure. + +term_source (j_decompress_ptr cinfo) + Terminate source --- called by jpeg_finish_decompress() after all + data has been read. Often a no-op. + +For both fill_input_buffer() and skip_input_data(), there is no such thing +as an EOF return. If the end of the file has been reached, the routine has +a choice of exiting via ERREXIT() or inserting fake data into the buffer. +In most cases, generating a warning message and inserting a fake EOI marker +is the best course of action --- this will allow the decompressor to output +however much of the image is there. In pathological cases, the decompressor +may swallow the EOI and again demand data ... just keep feeding it fake EOIs. +jdatasrc.c illustrates the recommended error recovery behavior. + +term_source() is NOT called by jpeg_abort() or jpeg_destroy(). If you want +the source manager to be cleaned up during an abort, you must do it yourself. + +You will also need code to create a jpeg_source_mgr struct, fill in its method +pointers, and insert a pointer to the struct into the "src" field of the JPEG +decompression object. This can be done in-line in your setup code if you +like, but it's probably cleaner to provide a separate routine similar to the +jpeg_stdio_src() routine of the supplied source manager. + +For more information, consult the stdio source and destination managers +in jdatasrc.c and jdatadst.c. + + +I/O suspension +-------------- + +Some applications need to use the JPEG library as an incremental memory-to- +memory filter: when the compressed data buffer is filled or emptied, they want +control to return to the outer loop, rather than expecting that the buffer can +be emptied or reloaded within the data source/destination manager subroutine. +The library supports this need by providing an "I/O suspension" mode, which we +describe in this section. + +The I/O suspension mode is not a panacea: nothing is guaranteed about the +maximum amount of time spent in any one call to the library, so it will not +eliminate response-time problems in single-threaded applications. If you +need guaranteed response time, we suggest you "bite the bullet" and implement +a real multi-tasking capability. + +To use I/O suspension, cooperation is needed between the calling application +and the data source or destination manager; you will always need a custom +source/destination manager. (Please read the previous section if you haven't +already.) The basic idea is that the empty_output_buffer() or +fill_input_buffer() routine is a no-op, merely returning FALSE to indicate +that it has done nothing. Upon seeing this, the JPEG library suspends +operation and returns to its caller. The surrounding application is +responsible for emptying or refilling the work buffer before calling the +JPEG library again. + +Compression suspension: + +For compression suspension, use an empty_output_buffer() routine that returns +FALSE; typically it will not do anything else. This will cause the +compressor to return to the caller of jpeg_write_scanlines(), with the return +value indicating that not all the supplied scanlines have been accepted. +The application must make more room in the output buffer, adjust the output +buffer pointer/count appropriately, and then call jpeg_write_scanlines() +again, pointing to the first unconsumed scanline. + +When forced to suspend, the compressor will backtrack to a convenient stopping +point (usually the start of the current MCU); it will regenerate some output +data when restarted. Therefore, although empty_output_buffer() is only +called when the buffer is filled, you should NOT write out the entire buffer +after a suspension. Write only the data up to the current position of +next_output_byte/free_in_buffer. The data beyond that point will be +regenerated after resumption. + +Because of the backtracking behavior, a good-size output buffer is essential +for efficiency; you don't want the compressor to suspend often. (In fact, an +overly small buffer could lead to infinite looping, if a single MCU required +more data than would fit in the buffer.) We recommend a buffer of at least +several Kbytes. You may want to insert explicit code to ensure that you don't +call jpeg_write_scanlines() unless there is a reasonable amount of space in +the output buffer; in other words, flush the buffer before trying to compress +more data. + +The compressor does not allow suspension while it is trying to write JPEG +markers at the beginning and end of the file. This means that: + * At the beginning of a compression operation, there must be enough free + space in the output buffer to hold the header markers (typically 600 or + so bytes). The recommended buffer size is bigger than this anyway, so + this is not a problem as long as you start with an empty buffer. However, + this restriction might catch you if you insert large special markers, such + as a JFIF thumbnail image, without flushing the buffer afterwards. + * When you call jpeg_finish_compress(), there must be enough space in the + output buffer to emit any buffered data and the final EOI marker. In the + current implementation, half a dozen bytes should suffice for this, but + for safety's sake we recommend ensuring that at least 100 bytes are free + before calling jpeg_finish_compress(). + +A more significant restriction is that jpeg_finish_compress() cannot suspend. +This means you cannot use suspension with multi-pass operating modes, namely +Huffman code optimization and multiple-scan output. Those modes write the +whole file during jpeg_finish_compress(), which will certainly result in +buffer overrun. (Note that this restriction applies only to compression, +not decompression. The decompressor supports input suspension in all of its +operating modes.) + +Decompression suspension: + +For decompression suspension, use a fill_input_buffer() routine that simply +returns FALSE (except perhaps during error recovery, as discussed below). +This will cause the decompressor to return to its caller with an indication +that suspension has occurred. This can happen at four places: + * jpeg_read_header(): will return JPEG_SUSPENDED. + * jpeg_start_decompress(): will return FALSE, rather than its usual TRUE. + * jpeg_read_scanlines(): will return the number of scanlines already + completed (possibly 0). + * jpeg_finish_decompress(): will return FALSE, rather than its usual TRUE. +The surrounding application must recognize these cases, load more data into +the input buffer, and repeat the call. In the case of jpeg_read_scanlines(), +increment the passed pointers past any scanlines successfully read. + +Just as with compression, the decompressor will typically backtrack to a +convenient restart point before suspending. When fill_input_buffer() is +called, next_input_byte/bytes_in_buffer point to the current restart point, +which is where the decompressor will backtrack to if FALSE is returned. +The data beyond that position must NOT be discarded if you suspend; it needs +to be re-read upon resumption. In most implementations, you'll need to shift +this data down to the start of your work buffer and then load more data after +it. Again, this behavior means that a several-Kbyte work buffer is essential +for decent performance; furthermore, you should load a reasonable amount of +new data before resuming decompression. (If you loaded, say, only one new +byte each time around, you could waste a LOT of cycles.) + +The skip_input_data() source manager routine requires special care in a +suspension scenario. This routine is NOT granted the ability to suspend the +decompressor; it can decrement bytes_in_buffer to zero, but no more. If the +requested skip distance exceeds the amount of data currently in the input +buffer, then skip_input_data() must set bytes_in_buffer to zero and record the +additional skip distance somewhere else. The decompressor will immediately +call fill_input_buffer(), which should return FALSE, which will cause a +suspension return. The surrounding application must then arrange to discard +the recorded number of bytes before it resumes loading the input buffer. +(Yes, this design is rather baroque, but it avoids complexity in the far more +common case where a non-suspending source manager is used.) + +If the input data has been exhausted, we recommend that you emit a warning +and insert dummy EOI markers just as a non-suspending data source manager +would do. This can be handled either in the surrounding application logic or +within fill_input_buffer(); the latter is probably more efficient. If +fill_input_buffer() knows that no more data is available, it can set the +pointer/count to point to a dummy EOI marker and then return TRUE just as +though it had read more data in a non-suspending situation. + +The decompressor does not attempt to suspend within standard JPEG markers; +instead it will backtrack to the start of the marker and reprocess the whole +marker next time. Hence the input buffer must be large enough to hold the +longest standard marker in the file. Standard JPEG markers should normally +not exceed a few hundred bytes each (DHT tables are typically the longest). +We recommend at least a 2K buffer for performance reasons, which is much +larger than any correct marker is likely to be. For robustness against +damaged marker length counts, you may wish to insert a test in your +application for the case that the input buffer is completely full and yet +the decoder has suspended without consuming any data --- otherwise, if this +situation did occur, it would lead to an endless loop. (The library can't +provide this test since it has no idea whether "the buffer is full", or +even whether there is a fixed-size input buffer.) + +The input buffer would need to be 64K to allow for arbitrary COM or APPn +markers, but these are handled specially: they are either saved into allocated +memory, or skipped over by calling skip_input_data(). In the former case, +suspension is handled correctly, and in the latter case, the problem of +buffer overrun is placed on skip_input_data's shoulders, as explained above. +Note that if you provide your own marker handling routine for large markers, +you should consider how to deal with buffer overflow. + +Multiple-buffer management: + +In some applications it is desirable to store the compressed data in a linked +list of buffer areas, so as to avoid data copying. This can be handled by +having empty_output_buffer() or fill_input_buffer() set the pointer and count +to reference the next available buffer; FALSE is returned only if no more +buffers are available. Although seemingly straightforward, there is a +pitfall in this approach: the backtrack that occurs when FALSE is returned +could back up into an earlier buffer. For example, when fill_input_buffer() +is called, the current pointer & count indicate the backtrack restart point. +Since fill_input_buffer() will set the pointer and count to refer to a new +buffer, the restart position must be saved somewhere else. Suppose a second +call to fill_input_buffer() occurs in the same library call, and no +additional input data is available, so fill_input_buffer must return FALSE. +If the JPEG library has not moved the pointer/count forward in the current +buffer, then *the correct restart point is the saved position in the prior +buffer*. Prior buffers may be discarded only after the library establishes +a restart point within a later buffer. Similar remarks apply for output into +a chain of buffers. + +The library will never attempt to backtrack over a skip_input_data() call, +so any skipped data can be permanently discarded. You still have to deal +with the case of skipping not-yet-received data, however. + +It's much simpler to use only a single buffer; when fill_input_buffer() is +called, move any unconsumed data (beyond the current pointer/count) down to +the beginning of this buffer and then load new data into the remaining buffer +space. This approach requires a little more data copying but is far easier +to get right. + + +Progressive JPEG support +------------------------ + +Progressive JPEG rearranges the stored data into a series of scans of +increasing quality. In situations where a JPEG file is transmitted across a +slow communications link, a decoder can generate a low-quality image very +quickly from the first scan, then gradually improve the displayed quality as +more scans are received. The final image after all scans are complete is +identical to that of a regular (sequential) JPEG file of the same quality +setting. Progressive JPEG files are often slightly smaller than equivalent +sequential JPEG files, but the possibility of incremental display is the main +reason for using progressive JPEG. + +The IJG encoder library generates progressive JPEG files when given a +suitable "scan script" defining how to divide the data into scans. +Creation of progressive JPEG files is otherwise transparent to the encoder. +Progressive JPEG files can also be read transparently by the decoder library. +If the decoding application simply uses the library as defined above, it +will receive a final decoded image without any indication that the file was +progressive. Of course, this approach does not allow incremental display. +To perform incremental display, an application needs to use the decoder +library's "buffered-image" mode, in which it receives a decoded image +multiple times. + +Each displayed scan requires about as much work to decode as a full JPEG +image of the same size, so the decoder must be fairly fast in relation to the +data transmission rate in order to make incremental display useful. However, +it is possible to skip displaying the image and simply add the incoming bits +to the decoder's coefficient buffer. This is fast because only Huffman +decoding need be done, not IDCT, upsampling, colorspace conversion, etc. +The IJG decoder library allows the application to switch dynamically between +displaying the image and simply absorbing the incoming bits. A properly +coded application can automatically adapt the number of display passes to +suit the time available as the image is received. Also, a final +higher-quality display cycle can be performed from the buffered data after +the end of the file is reached. + +Progressive compression: + +To create a progressive JPEG file (or a multiple-scan sequential JPEG file), +set the scan_info cinfo field to point to an array of scan descriptors, and +perform compression as usual. Instead of constructing your own scan list, +you can call the jpeg_simple_progression() helper routine to create a +recommended progression sequence; this method should be used by all +applications that don't want to get involved in the nitty-gritty of +progressive scan sequence design. (If you want to provide user control of +scan sequences, you may wish to borrow the scan script reading code found +in rdswitch.c, so that you can read scan script files just like cjpeg's.) +When scan_info is not NULL, the compression library will store DCT'd data +into a buffer array as jpeg_write_scanlines() is called, and will emit all +the requested scans during jpeg_finish_compress(). This implies that +multiple-scan output cannot be created with a suspending data destination +manager, since jpeg_finish_compress() does not support suspension. We +should also note that the compressor currently forces Huffman optimization +mode when creating a progressive JPEG file, because the default Huffman +tables are unsuitable for progressive files. + +Progressive decompression: + +When buffered-image mode is not used, the decoder library will read all of +a multi-scan file during jpeg_start_decompress(), so that it can provide a +final decoded image. (Here "multi-scan" means either progressive or +multi-scan sequential.) This makes multi-scan files transparent to the +decoding application. However, existing applications that used suspending +input with version 5 of the IJG library will need to be modified to check +for a suspension return from jpeg_start_decompress(). + +To perform incremental display, an application must use the library's +buffered-image mode. This is described in the next section. + + +Buffered-image mode +------------------- + +In buffered-image mode, the library stores the partially decoded image in a +coefficient buffer, from which it can be read out as many times as desired. +This mode is typically used for incremental display of progressive JPEG files, +but it can be used with any JPEG file. Each scan of a progressive JPEG file +adds more data (more detail) to the buffered image. The application can +display in lockstep with the source file (one display pass per input scan), +or it can allow input processing to outrun display processing. By making +input and display processing run independently, it is possible for the +application to adapt progressive display to a wide range of data transmission +rates. + +The basic control flow for buffered-image decoding is + + jpeg_create_decompress() + set data source + jpeg_read_header() + set overall decompression parameters + cinfo.buffered_image = TRUE; /* select buffered-image mode */ + jpeg_start_decompress() + for (each output pass) { + adjust output decompression parameters if required + jpeg_start_output() /* start a new output pass */ + for (all scanlines in image) { + jpeg_read_scanlines() + display scanlines + } + jpeg_finish_output() /* terminate output pass */ + } + jpeg_finish_decompress() + jpeg_destroy_decompress() + +This differs from ordinary unbuffered decoding in that there is an additional +level of looping. The application can choose how many output passes to make +and how to display each pass. + +The simplest approach to displaying progressive images is to do one display +pass for each scan appearing in the input file. In this case the outer loop +condition is typically + while (! jpeg_input_complete(&cinfo)) +and the start-output call should read + jpeg_start_output(&cinfo, cinfo.input_scan_number); +The second parameter to jpeg_start_output() indicates which scan of the input +file is to be displayed; the scans are numbered starting at 1 for this +purpose. (You can use a loop counter starting at 1 if you like, but using +the library's input scan counter is easier.) The library automatically reads +data as necessary to complete each requested scan, and jpeg_finish_output() +advances to the next scan or end-of-image marker (hence input_scan_number +will be incremented by the time control arrives back at jpeg_start_output()). +With this technique, data is read from the input file only as needed, and +input and output processing run in lockstep. + +After reading the final scan and reaching the end of the input file, the +buffered image remains available; it can be read additional times by +repeating the jpeg_start_output()/jpeg_read_scanlines()/jpeg_finish_output() +sequence. For example, a useful technique is to use fast one-pass color +quantization for display passes made while the image is arriving, followed by +a final display pass using two-pass quantization for highest quality. This +is done by changing the library parameters before the final output pass. +Changing parameters between passes is discussed in detail below. + +In general the last scan of a progressive file cannot be recognized as such +until after it is read, so a post-input display pass is the best approach if +you want special processing in the final pass. + +When done with the image, be sure to call jpeg_finish_decompress() to release +the buffered image (or just use jpeg_destroy_decompress()). + +If input data arrives faster than it can be displayed, the application can +cause the library to decode input data in advance of what's needed to produce +output. This is done by calling the routine jpeg_consume_input(). +The return value is one of the following: + JPEG_REACHED_SOS: reached an SOS marker (the start of a new scan) + JPEG_REACHED_EOI: reached the EOI marker (end of image) + JPEG_ROW_COMPLETED: completed reading one MCU row of compressed data + JPEG_SCAN_COMPLETED: completed reading last MCU row of current scan + JPEG_SUSPENDED: suspended before completing any of the above +(JPEG_SUSPENDED can occur only if a suspending data source is used.) This +routine can be called at any time after initializing the JPEG object. It +reads some additional data and returns when one of the indicated significant +events occurs. (If called after the EOI marker is reached, it will +immediately return JPEG_REACHED_EOI without attempting to read more data.) + +The library's output processing will automatically call jpeg_consume_input() +whenever the output processing overtakes the input; thus, simple lockstep +display requires no direct calls to jpeg_consume_input(). But by adding +calls to jpeg_consume_input(), you can absorb data in advance of what is +being displayed. This has two benefits: + * You can limit buildup of unprocessed data in your input buffer. + * You can eliminate extra display passes by paying attention to the + state of the library's input processing. + +The first of these benefits only requires interspersing calls to +jpeg_consume_input() with your display operations and any other processing +you may be doing. To avoid wasting cycles due to backtracking, it's best to +call jpeg_consume_input() only after a hundred or so new bytes have arrived. +This is discussed further under "I/O suspension", above. (Note: the JPEG +library currently is not thread-safe. You must not call jpeg_consume_input() +from one thread of control if a different library routine is working on the +same JPEG object in another thread.) + +When input arrives fast enough that more than one new scan is available +before you start a new output pass, you may as well skip the output pass +corresponding to the completed scan. This occurs for free if you pass +cinfo.input_scan_number as the target scan number to jpeg_start_output(). +The input_scan_number field is simply the index of the scan currently being +consumed by the input processor. You can ensure that this is up-to-date by +emptying the input buffer just before calling jpeg_start_output(): call +jpeg_consume_input() repeatedly until it returns JPEG_SUSPENDED or +JPEG_REACHED_EOI. + +The target scan number passed to jpeg_start_output() is saved in the +cinfo.output_scan_number field. The library's output processing calls +jpeg_consume_input() whenever the current input scan number and row within +that scan is less than or equal to the current output scan number and row. +Thus, input processing can "get ahead" of the output processing but is not +allowed to "fall behind". You can achieve several different effects by +manipulating this interlock rule. For example, if you pass a target scan +number greater than the current input scan number, the output processor will +wait until that scan starts to arrive before producing any output. (To avoid +an infinite loop, the target scan number is automatically reset to the last +scan number when the end of image is reached. Thus, if you specify a large +target scan number, the library will just absorb the entire input file and +then perform an output pass. This is effectively the same as what +jpeg_start_decompress() does when you don't select buffered-image mode.) +When you pass a target scan number equal to the current input scan number, +the image is displayed no faster than the current input scan arrives. The +final possibility is to pass a target scan number less than the current input +scan number; this disables the input/output interlock and causes the output +processor to simply display whatever it finds in the image buffer, without +waiting for input. (However, the library will not accept a target scan +number less than one, so you can't avoid waiting for the first scan.) + +When data is arriving faster than the output display processing can advance +through the image, jpeg_consume_input() will store data into the buffered +image beyond the point at which the output processing is reading data out +again. If the input arrives fast enough, it may "wrap around" the buffer to +the point where the input is more than one whole scan ahead of the output. +If the output processing simply proceeds through its display pass without +paying attention to the input, the effect seen on-screen is that the lower +part of the image is one or more scans better in quality than the upper part. +Then, when the next output scan is started, you have a choice of what target +scan number to use. The recommended choice is to use the current input scan +number at that time, which implies that you've skipped the output scans +corresponding to the input scans that were completed while you processed the +previous output scan. In this way, the decoder automatically adapts its +speed to the arriving data, by skipping output scans as necessary to keep up +with the arriving data. + +When using this strategy, you'll want to be sure that you perform a final +output pass after receiving all the data; otherwise your last display may not +be full quality across the whole screen. So the right outer loop logic is +something like this: + do { + absorb any waiting input by calling jpeg_consume_input() + final_pass = jpeg_input_complete(&cinfo); + adjust output decompression parameters if required + jpeg_start_output(&cinfo, cinfo.input_scan_number); + ... + jpeg_finish_output() + } while (! final_pass); +rather than quitting as soon as jpeg_input_complete() returns TRUE. This +arrangement makes it simple to use higher-quality decoding parameters +for the final pass. But if you don't want to use special parameters for +the final pass, the right loop logic is like this: + for (;;) { + absorb any waiting input by calling jpeg_consume_input() + jpeg_start_output(&cinfo, cinfo.input_scan_number); + ... + jpeg_finish_output() + if (jpeg_input_complete(&cinfo) && + cinfo.input_scan_number == cinfo.output_scan_number) + break; + } +In this case you don't need to know in advance whether an output pass is to +be the last one, so it's not necessary to have reached EOF before starting +the final output pass; rather, what you want to test is whether the output +pass was performed in sync with the final input scan. This form of the loop +will avoid an extra output pass whenever the decoder is able (or nearly able) +to keep up with the incoming data. + +When the data transmission speed is high, you might begin a display pass, +then find that much or all of the file has arrived before you can complete +the pass. (You can detect this by noting the JPEG_REACHED_EOI return code +from jpeg_consume_input(), or equivalently by testing jpeg_input_complete().) +In this situation you may wish to abort the current display pass and start a +new one using the newly arrived information. To do so, just call +jpeg_finish_output() and then start a new pass with jpeg_start_output(). + +A variant strategy is to abort and restart display if more than one complete +scan arrives during an output pass; this can be detected by noting +JPEG_REACHED_SOS returns and/or examining cinfo.input_scan_number. This +idea should be employed with caution, however, since the display process +might never get to the bottom of the image before being aborted, resulting +in the lower part of the screen being several passes worse than the upper. +In most cases it's probably best to abort an output pass only if the whole +file has arrived and you want to begin the final output pass immediately. + +When receiving data across a communication link, we recommend always using +the current input scan number for the output target scan number; if a +higher-quality final pass is to be done, it should be started (aborting any +incomplete output pass) as soon as the end of file is received. However, +many other strategies are possible. For example, the application can examine +the parameters of the current input scan and decide whether to display it or +not. If the scan contains only chroma data, one might choose not to use it +as the target scan, expecting that the scan will be small and will arrive +quickly. To skip to the next scan, call jpeg_consume_input() until it +returns JPEG_REACHED_SOS or JPEG_REACHED_EOI. Or just use the next higher +number as the target scan for jpeg_start_output(); but that method doesn't +let you inspect the next scan's parameters before deciding to display it. + + +In buffered-image mode, jpeg_start_decompress() never performs input and +thus never suspends. An application that uses input suspension with +buffered-image mode must be prepared for suspension returns from these +routines: +* jpeg_start_output() performs input only if you request 2-pass quantization + and the target scan isn't fully read yet. (This is discussed below.) +* jpeg_read_scanlines(), as always, returns the number of scanlines that it + was able to produce before suspending. +* jpeg_finish_output() will read any markers following the target scan, + up to the end of the file or the SOS marker that begins another scan. + (But it reads no input if jpeg_consume_input() has already reached the + end of the file or a SOS marker beyond the target output scan.) +* jpeg_finish_decompress() will read until the end of file, and thus can + suspend if the end hasn't already been reached (as can be tested by + calling jpeg_input_complete()). +jpeg_start_output(), jpeg_finish_output(), and jpeg_finish_decompress() +all return TRUE if they completed their tasks, FALSE if they had to suspend. +In the event of a FALSE return, the application must load more input data +and repeat the call. Applications that use non-suspending data sources need +not check the return values of these three routines. + + +It is possible to change decoding parameters between output passes in the +buffered-image mode. The decoder library currently supports only very +limited changes of parameters. ONLY THE FOLLOWING parameter changes are +allowed after jpeg_start_decompress() is called: +* dct_method can be changed before each call to jpeg_start_output(). + For example, one could use a fast DCT method for early scans, changing + to a higher quality method for the final scan. +* dither_mode can be changed before each call to jpeg_start_output(); + of course this has no impact if not using color quantization. Typically + one would use ordered dither for initial passes, then switch to + Floyd-Steinberg dither for the final pass. Caution: changing dither mode + can cause more memory to be allocated by the library. Although the amount + of memory involved is not large (a scanline or so), it may cause the + initial max_memory_to_use specification to be exceeded, which in the worst + case would result in an out-of-memory failure. +* do_block_smoothing can be changed before each call to jpeg_start_output(). + This setting is relevant only when decoding a progressive JPEG image. + During the first DC-only scan, block smoothing provides a very "fuzzy" look + instead of the very "blocky" look seen without it; which is better seems a + matter of personal taste. But block smoothing is nearly always a win + during later stages, especially when decoding a successive-approximation + image: smoothing helps to hide the slight blockiness that otherwise shows + up on smooth gradients until the lowest coefficient bits are sent. +* Color quantization mode can be changed under the rules described below. + You *cannot* change between full-color and quantized output (because that + would alter the required I/O buffer sizes), but you can change which + quantization method is used. + +When generating color-quantized output, changing quantization method is a +very useful way of switching between high-speed and high-quality display. +The library allows you to change among its three quantization methods: +1. Single-pass quantization to a fixed color cube. + Selected by cinfo.two_pass_quantize = FALSE and cinfo.colormap = NULL. +2. Single-pass quantization to an application-supplied colormap. + Selected by setting cinfo.colormap to point to the colormap (the value of + two_pass_quantize is ignored); also set cinfo.actual_number_of_colors. +3. Two-pass quantization to a colormap chosen specifically for the image. + Selected by cinfo.two_pass_quantize = TRUE and cinfo.colormap = NULL. + (This is the default setting selected by jpeg_read_header, but it is + probably NOT what you want for the first pass of progressive display!) +These methods offer successively better quality and lesser speed. However, +only the first method is available for quantizing in non-RGB color spaces. + +IMPORTANT: because the different quantizer methods have very different +working-storage requirements, the library requires you to indicate which +one(s) you intend to use before you call jpeg_start_decompress(). (If we did +not require this, the max_memory_to_use setting would be a complete fiction.) +You do this by setting one or more of these three cinfo fields to TRUE: + enable_1pass_quant Fixed color cube colormap + enable_external_quant Externally-supplied colormap + enable_2pass_quant Two-pass custom colormap +All three are initialized FALSE by jpeg_read_header(). But +jpeg_start_decompress() automatically sets TRUE the one selected by the +current two_pass_quantize and colormap settings, so you only need to set the +enable flags for any other quantization methods you plan to change to later. + +After setting the enable flags correctly at jpeg_start_decompress() time, you +can change to any enabled quantization method by setting two_pass_quantize +and colormap properly just before calling jpeg_start_output(). The following +special rules apply: +1. You must explicitly set cinfo.colormap to NULL when switching to 1-pass + or 2-pass mode from a different mode, or when you want the 2-pass + quantizer to be re-run to generate a new colormap. +2. To switch to an external colormap, or to change to a different external + colormap than was used on the prior pass, you must call + jpeg_new_colormap() after setting cinfo.colormap. +NOTE: if you want to use the same colormap as was used in the prior pass, +you should not do either of these things. This will save some nontrivial +switchover costs. +(These requirements exist because cinfo.colormap will always be non-NULL +after completing a prior output pass, since both the 1-pass and 2-pass +quantizers set it to point to their output colormaps. Thus you have to +do one of these two things to notify the library that something has changed. +Yup, it's a bit klugy, but it's necessary to do it this way for backwards +compatibility.) + +Note that in buffered-image mode, the library generates any requested colormap +during jpeg_start_output(), not during jpeg_start_decompress(). + +When using two-pass quantization, jpeg_start_output() makes a pass over the +buffered image to determine the optimum color map; it therefore may take a +significant amount of time, whereas ordinarily it does little work. The +progress monitor hook is called during this pass, if defined. It is also +important to realize that if the specified target scan number is greater than +or equal to the current input scan number, jpeg_start_output() will attempt +to consume input as it makes this pass. If you use a suspending data source, +you need to check for a FALSE return from jpeg_start_output() under these +conditions. The combination of 2-pass quantization and a not-yet-fully-read +target scan is the only case in which jpeg_start_output() will consume input. + + +Application authors who support buffered-image mode may be tempted to use it +for all JPEG images, even single-scan ones. This will work, but it is +inefficient: there is no need to create an image-sized coefficient buffer for +single-scan images. Requesting buffered-image mode for such an image wastes +memory. Worse, it can cost time on large images, since the buffered data has +to be swapped out or written to a temporary file. If you are concerned about +maximum performance on baseline JPEG files, you should use buffered-image +mode only when the incoming file actually has multiple scans. This can be +tested by calling jpeg_has_multiple_scans(), which will return a correct +result at any time after jpeg_read_header() completes. + +It is also worth noting that when you use jpeg_consume_input() to let input +processing get ahead of output processing, the resulting pattern of access to +the coefficient buffer is quite nonsequential. It's best to use the memory +manager jmemnobs.c if you can (ie, if you have enough real or virtual main +memory). If not, at least make sure that max_memory_to_use is set as high as +possible. If the JPEG memory manager has to use a temporary file, you will +probably see a lot of disk traffic and poor performance. (This could be +improved with additional work on the memory manager, but we haven't gotten +around to it yet.) + +In some applications it may be convenient to use jpeg_consume_input() for all +input processing, including reading the initial markers; that is, you may +wish to call jpeg_consume_input() instead of jpeg_read_header() during +startup. This works, but note that you must check for JPEG_REACHED_SOS and +JPEG_REACHED_EOI return codes as the equivalent of jpeg_read_header's codes. +Once the first SOS marker has been reached, you must call +jpeg_start_decompress() before jpeg_consume_input() will consume more input; +it'll just keep returning JPEG_REACHED_SOS until you do. If you read a +tables-only file this way, jpeg_consume_input() will return JPEG_REACHED_EOI +without ever returning JPEG_REACHED_SOS; be sure to check for this case. +If this happens, the decompressor will not read any more input until you call +jpeg_abort() to reset it. It is OK to call jpeg_consume_input() even when not +using buffered-image mode, but in that case it's basically a no-op after the +initial markers have been read: it will just return JPEG_SUSPENDED. + + +Abbreviated datastreams and multiple images +------------------------------------------- + +A JPEG compression or decompression object can be reused to process multiple +images. This saves a small amount of time per image by eliminating the +"create" and "destroy" operations, but that isn't the real purpose of the +feature. Rather, reuse of an object provides support for abbreviated JPEG +datastreams. Object reuse can also simplify processing a series of images in +a single input or output file. This section explains these features. + +A JPEG file normally contains several hundred bytes worth of quantization +and Huffman tables. In a situation where many images will be stored or +transmitted with identical tables, this may represent an annoying overhead. +The JPEG standard therefore permits tables to be omitted. The standard +defines three classes of JPEG datastreams: + * "Interchange" datastreams contain an image and all tables needed to decode + the image. These are the usual kind of JPEG file. + * "Abbreviated image" datastreams contain an image, but are missing some or + all of the tables needed to decode that image. + * "Abbreviated table specification" (henceforth "tables-only") datastreams + contain only table specifications. +To decode an abbreviated image, it is necessary to load the missing table(s) +into the decoder beforehand. This can be accomplished by reading a separate +tables-only file. A variant scheme uses a series of images in which the first +image is an interchange (complete) datastream, while subsequent ones are +abbreviated and rely on the tables loaded by the first image. It is assumed +that once the decoder has read a table, it will remember that table until a +new definition for the same table number is encountered. + +It is the application designer's responsibility to figure out how to associate +the correct tables with an abbreviated image. While abbreviated datastreams +can be useful in a closed environment, their use is strongly discouraged in +any situation where data exchange with other applications might be needed. +Caveat designer. + +The JPEG library provides support for reading and writing any combination of +tables-only datastreams and abbreviated images. In both compression and +decompression objects, a quantization or Huffman table will be retained for +the lifetime of the object, unless it is overwritten by a new table definition. + + +To create abbreviated image datastreams, it is only necessary to tell the +compressor not to emit some or all of the tables it is using. Each +quantization and Huffman table struct contains a boolean field "sent_table", +which normally is initialized to FALSE. For each table used by the image, the +header-writing process emits the table and sets sent_table = TRUE unless it is +already TRUE. (In normal usage, this prevents outputting the same table +definition multiple times, as would otherwise occur because the chroma +components typically share tables.) Thus, setting this field to TRUE before +calling jpeg_start_compress() will prevent the table from being written at +all. + +If you want to create a "pure" abbreviated image file containing no tables, +just call "jpeg_suppress_tables(&cinfo, TRUE)" after constructing all the +tables. If you want to emit some but not all tables, you'll need to set the +individual sent_table fields directly. + +To create an abbreviated image, you must also call jpeg_start_compress() +with a second parameter of FALSE, not TRUE. Otherwise jpeg_start_compress() +will force all the sent_table fields to FALSE. (This is a safety feature to +prevent abbreviated images from being created accidentally.) + +To create a tables-only file, perform the same parameter setup that you +normally would, but instead of calling jpeg_start_compress() and so on, call +jpeg_write_tables(&cinfo). This will write an abbreviated datastream +containing only SOI, DQT and/or DHT markers, and EOI. All the quantization +and Huffman tables that are currently defined in the compression object will +be emitted unless their sent_tables flag is already TRUE, and then all the +sent_tables flags will be set TRUE. + +A sure-fire way to create matching tables-only and abbreviated image files +is to proceed as follows: + + create JPEG compression object + set JPEG parameters + set destination to tables-only file + jpeg_write_tables(&cinfo); + set destination to image file + jpeg_start_compress(&cinfo, FALSE); + write data... + jpeg_finish_compress(&cinfo); + +Since the JPEG parameters are not altered between writing the table file and +the abbreviated image file, the same tables are sure to be used. Of course, +you can repeat the jpeg_start_compress() ... jpeg_finish_compress() sequence +many times to produce many abbreviated image files matching the table file. + +You cannot suppress output of the computed Huffman tables when Huffman +optimization is selected. (If you could, there'd be no way to decode the +image...) Generally, you don't want to set optimize_coding = TRUE when +you are trying to produce abbreviated files. + +In some cases you might want to compress an image using tables which are +not stored in the application, but are defined in an interchange or +tables-only file readable by the application. This can be done by setting up +a JPEG decompression object to read the specification file, then copying the +tables into your compression object. See jpeg_copy_critical_parameters() +for an example of copying quantization tables. + + +To read abbreviated image files, you simply need to load the proper tables +into the decompression object before trying to read the abbreviated image. +If the proper tables are stored in the application program, you can just +allocate the table structs and fill in their contents directly. For example, +to load a fixed quantization table into table slot "n": + + if (cinfo.quant_tbl_ptrs[n] == NULL) + cinfo.quant_tbl_ptrs[n] = jpeg_alloc_quant_table((j_common_ptr) &cinfo); + quant_ptr = cinfo.quant_tbl_ptrs[n]; /* quant_ptr is JQUANT_TBL* */ + for (i = 0; i < 64; i++) { + /* Qtable[] is desired quantization table, in natural array order */ + quant_ptr->quantval[i] = Qtable[i]; + } + +Code to load a fixed Huffman table is typically (for AC table "n"): + + if (cinfo.ac_huff_tbl_ptrs[n] == NULL) + cinfo.ac_huff_tbl_ptrs[n] = jpeg_alloc_huff_table((j_common_ptr) &cinfo); + huff_ptr = cinfo.ac_huff_tbl_ptrs[n]; /* huff_ptr is JHUFF_TBL* */ + for (i = 1; i <= 16; i++) { + /* counts[i] is number of Huffman codes of length i bits, i=1..16 */ + huff_ptr->bits[i] = counts[i]; + } + for (i = 0; i < 256; i++) { + /* symbols[] is the list of Huffman symbols, in code-length order */ + huff_ptr->huffval[i] = symbols[i]; + } + +(Note that trying to set cinfo.quant_tbl_ptrs[n] to point directly at a +constant JQUANT_TBL object is not safe. If the incoming file happened to +contain a quantization table definition, your master table would get +overwritten! Instead allocate a working table copy and copy the master table +into it, as illustrated above. Ditto for Huffman tables, of course.) + +You might want to read the tables from a tables-only file, rather than +hard-wiring them into your application. The jpeg_read_header() call is +sufficient to read a tables-only file. You must pass a second parameter of +FALSE to indicate that you do not require an image to be present. Thus, the +typical scenario is + + create JPEG decompression object + set source to tables-only file + jpeg_read_header(&cinfo, FALSE); + set source to abbreviated image file + jpeg_read_header(&cinfo, TRUE); + set decompression parameters + jpeg_start_decompress(&cinfo); + read data... + jpeg_finish_decompress(&cinfo); + +In some cases, you may want to read a file without knowing whether it contains +an image or just tables. In that case, pass FALSE and check the return value +from jpeg_read_header(): it will be JPEG_HEADER_OK if an image was found, +JPEG_HEADER_TABLES_ONLY if only tables were found. (A third return value, +JPEG_SUSPENDED, is possible when using a suspending data source manager.) +Note that jpeg_read_header() will not complain if you read an abbreviated +image for which you haven't loaded the missing tables; the missing-table check +occurs later, in jpeg_start_decompress(). + + +It is possible to read a series of images from a single source file by +repeating the jpeg_read_header() ... jpeg_finish_decompress() sequence, +without releasing/recreating the JPEG object or the data source module. +(If you did reinitialize, any partial bufferload left in the data source +buffer at the end of one image would be discarded, causing you to lose the +start of the next image.) When you use this method, stored tables are +automatically carried forward, so some of the images can be abbreviated images +that depend on tables from earlier images. + +If you intend to write a series of images into a single destination file, +you might want to make a specialized data destination module that doesn't +flush the output buffer at term_destination() time. This would speed things +up by some trifling amount. Of course, you'd need to remember to flush the +buffer after the last image. You can make the later images be abbreviated +ones by passing FALSE to jpeg_start_compress(). + + +Special markers +--------------- + +Some applications may need to insert or extract special data in the JPEG +datastream. The JPEG standard provides marker types "COM" (comment) and +"APP0" through "APP15" (application) to hold application-specific data. +Unfortunately, the use of these markers is not specified by the standard. +COM markers are fairly widely used to hold user-supplied text. The JFIF file +format spec uses APP0 markers with specified initial strings to hold certain +data. Adobe applications use APP14 markers beginning with the string "Adobe" +for miscellaneous data. Other APPn markers are rarely seen, but might +contain almost anything. + +If you wish to store user-supplied text, we recommend you use COM markers +and place readable 7-bit ASCII text in them. Newline conventions are not +standardized --- expect to find LF (Unix style), CR/LF (DOS style), or CR +(Mac style). A robust COM reader should be able to cope with random binary +garbage, including nulls, since some applications generate COM markers +containing non-ASCII junk. (But yours should not be one of them.) + +For program-supplied data, use an APPn marker, and be sure to begin it with an +identifying string so that you can tell whether the marker is actually yours. +It's probably best to avoid using APP0 or APP14 for any private markers. +(NOTE: the upcoming SPIFF standard will use APP8 markers; we recommend you +not use APP8 markers for any private purposes, either.) + +Keep in mind that at most 65533 bytes can be put into one marker, but you +can have as many markers as you like. + +By default, the IJG compression library will write a JFIF APP0 marker if the +selected JPEG colorspace is grayscale or YCbCr, or an Adobe APP14 marker if +the selected colorspace is RGB, CMYK, or YCCK. You can disable this, but +we don't recommend it. The decompression library will recognize JFIF and +Adobe markers and will set the JPEG colorspace properly when one is found. + + +You can write special markers immediately following the datastream header by +calling jpeg_write_marker() after jpeg_start_compress() and before the first +call to jpeg_write_scanlines(). When you do this, the markers appear after +the SOI and the JFIF APP0 and Adobe APP14 markers (if written), but before +all else. Specify the marker type parameter as "JPEG_COM" for COM or +"JPEG_APP0 + n" for APPn. (Actually, jpeg_write_marker will let you write +any marker type, but we don't recommend writing any other kinds of marker.) +For example, to write a user comment string pointed to by comment_text: + jpeg_write_marker(cinfo, JPEG_COM, comment_text, strlen(comment_text)); + +If it's not convenient to store all the marker data in memory at once, +you can instead call jpeg_write_m_header() followed by multiple calls to +jpeg_write_m_byte(). If you do it this way, it's your responsibility to +call jpeg_write_m_byte() exactly the number of times given in the length +parameter to jpeg_write_m_header(). (This method lets you empty the +output buffer partway through a marker, which might be important when +using a suspending data destination module. In any case, if you are using +a suspending destination, you should flush its buffer after inserting +any special markers. See "I/O suspension".) + +Or, if you prefer to synthesize the marker byte sequence yourself, +you can just cram it straight into the data destination module. + +If you are writing JFIF 1.02 extension markers (thumbnail images), don't +forget to set cinfo.JFIF_minor_version = 2 so that the encoder will write the +correct JFIF version number in the JFIF header marker. The library's default +is to write version 1.01, but that's wrong if you insert any 1.02 extension +markers. (We could probably get away with just defaulting to 1.02, but there +used to be broken decoders that would complain about unknown minor version +numbers. To reduce compatibility risks it's safest not to write 1.02 unless +you are actually using 1.02 extensions.) + + +When reading, two methods of handling special markers are available: +1. You can ask the library to save the contents of COM and/or APPn markers +into memory, and then examine them at your leisure afterwards. +2. You can supply your own routine to process COM and/or APPn markers +on-the-fly as they are read. +The first method is simpler to use, especially if you are using a suspending +data source; writing a marker processor that copes with input suspension is +not easy (consider what happens if the marker is longer than your available +input buffer). However, the second method conserves memory since the marker +data need not be kept around after it's been processed. + +For either method, you'd normally set up marker handling after creating a +decompression object and before calling jpeg_read_header(), because the +markers of interest will typically be near the head of the file and so will +be scanned by jpeg_read_header. Once you've established a marker handling +method, it will be used for the life of that decompression object +(potentially many datastreams), unless you change it. Marker handling is +determined separately for COM markers and for each APPn marker code. + + +To save the contents of special markers in memory, call + jpeg_save_markers(cinfo, marker_code, length_limit) +where marker_code is the marker type to save, JPEG_COM or JPEG_APP0+n. +(To arrange to save all the special marker types, you need to call this +routine 17 times, for COM and APP0-APP15.) If the incoming marker is longer +than length_limit data bytes, only length_limit bytes will be saved; this +parameter allows you to avoid chewing up memory when you only need to see the +first few bytes of a potentially large marker. If you want to save all the +data, set length_limit to 0xFFFF; that is enough since marker lengths are only +16 bits. As a special case, setting length_limit to 0 prevents that marker +type from being saved at all. (That is the default behavior, in fact.) + +After jpeg_read_header() completes, you can examine the special markers by +following the cinfo->marker_list pointer chain. All the special markers in +the file appear in this list, in order of their occurrence in the file (but +omitting any markers of types you didn't ask for). Both the original data +length and the saved data length are recorded for each list entry; the latter +will not exceed length_limit for the particular marker type. Note that these +lengths exclude the marker length word, whereas the stored representation +within the JPEG file includes it. (Hence the maximum data length is really +only 65533.) + +It is possible that additional special markers appear in the file beyond the +SOS marker at which jpeg_read_header stops; if so, the marker list will be +extended during reading of the rest of the file. This is not expected to be +common, however. If you are short on memory you may want to reset the length +limit to zero for all marker types after finishing jpeg_read_header, to +ensure that the max_memory_to_use setting cannot be exceeded due to addition +of later markers. + +The marker list remains stored until you call jpeg_finish_decompress or +jpeg_abort, at which point the memory is freed and the list is set to empty. +(jpeg_destroy also releases the storage, of course.) + +Note that the library is internally interested in APP0 and APP14 markers; +if you try to set a small nonzero length limit on these types, the library +will silently force the length up to the minimum it wants. (But you can set +a zero length limit to prevent them from being saved at all.) Also, in a +16-bit environment, the maximum length limit may be constrained to less than +65533 by malloc() limitations. It is therefore best not to assume that the +effective length limit is exactly what you set it to be. + + +If you want to supply your own marker-reading routine, you do it by calling +jpeg_set_marker_processor(). A marker processor routine must have the +signature + boolean jpeg_marker_parser_method (j_decompress_ptr cinfo) +Although the marker code is not explicitly passed, the routine can find it +in cinfo->unread_marker. At the time of call, the marker proper has been +read from the data source module. The processor routine is responsible for +reading the marker length word and the remaining parameter bytes, if any. +Return TRUE to indicate success. (FALSE should be returned only if you are +using a suspending data source and it tells you to suspend. See the standard +marker processors in jdmarker.c for appropriate coding methods if you need to +use a suspending data source.) + +If you override the default APP0 or APP14 processors, it is up to you to +recognize JFIF and Adobe markers if you want colorspace recognition to occur +properly. We recommend copying and extending the default processors if you +want to do that. (A better idea is to save these marker types for later +examination by calling jpeg_save_markers(); that method doesn't interfere +with the library's own processing of these markers.) + +jpeg_set_marker_processor() and jpeg_save_markers() are mutually exclusive +--- if you call one it overrides any previous call to the other, for the +particular marker type specified. + +A simple example of an external COM processor can be found in djpeg.c. +Also, see jpegtran.c for an example of using jpeg_save_markers. + + +Raw (downsampled) image data +---------------------------- + +Some applications need to supply already-downsampled image data to the JPEG +compressor, or to receive raw downsampled data from the decompressor. The +library supports this requirement by allowing the application to write or +read raw data, bypassing the normal preprocessing or postprocessing steps. +The interface is different from the standard one and is somewhat harder to +use. If your interest is merely in bypassing color conversion, we recommend +that you use the standard interface and simply set jpeg_color_space = +in_color_space (or jpeg_color_space = out_color_space for decompression). +The mechanism described in this section is necessary only to supply or +receive downsampled image data, in which not all components have the same +dimensions. + + +To compress raw data, you must supply the data in the colorspace to be used +in the JPEG file (please read the earlier section on Special color spaces) +and downsampled to the sampling factors specified in the JPEG parameters. +You must supply the data in the format used internally by the JPEG library, +namely a JSAMPIMAGE array. This is an array of pointers to two-dimensional +arrays, each of type JSAMPARRAY. Each 2-D array holds the values for one +color component. This structure is necessary since the components are of +different sizes. If the image dimensions are not a multiple of the MCU size, +you must also pad the data correctly (usually, this is done by replicating +the last column and/or row). The data must be padded to a multiple of a DCT +block in each component: that is, each downsampled row must contain a +multiple of 8 valid samples, and there must be a multiple of 8 sample rows +for each component. (For applications such as conversion of digital TV +images, the standard image size is usually a multiple of the DCT block size, +so that no padding need actually be done.) + +The procedure for compression of raw data is basically the same as normal +compression, except that you call jpeg_write_raw_data() in place of +jpeg_write_scanlines(). Before calling jpeg_start_compress(), you must do +the following: + * Set cinfo->raw_data_in to TRUE. (It is set FALSE by jpeg_set_defaults().) + This notifies the library that you will be supplying raw data. + * Ensure jpeg_color_space is correct --- an explicit jpeg_set_colorspace() + call is a good idea. Note that since color conversion is bypassed, + in_color_space is ignored, except that jpeg_set_defaults() uses it to + choose the default jpeg_color_space setting. + * Ensure the sampling factors, cinfo->comp_info[i].h_samp_factor and + cinfo->comp_info[i].v_samp_factor, are correct. Since these indicate the + dimensions of the data you are supplying, it's wise to set them + explicitly, rather than assuming the library's defaults are what you want. + +To pass raw data to the library, call jpeg_write_raw_data() in place of +jpeg_write_scanlines(). The two routines work similarly except that +jpeg_write_raw_data takes a JSAMPIMAGE data array rather than JSAMPARRAY. +The scanlines count passed to and returned from jpeg_write_raw_data is +measured in terms of the component with the largest v_samp_factor. + +jpeg_write_raw_data() processes one MCU row per call, which is to say +v_samp_factor*DCTSIZE sample rows of each component. The passed num_lines +value must be at least max_v_samp_factor*DCTSIZE, and the return value will +be exactly that amount (or possibly some multiple of that amount, in future +library versions). This is true even on the last call at the bottom of the +image; don't forget to pad your data as necessary. + +The required dimensions of the supplied data can be computed for each +component as + cinfo->comp_info[i].width_in_blocks*DCTSIZE samples per row + cinfo->comp_info[i].height_in_blocks*DCTSIZE rows in image +after jpeg_start_compress() has initialized those fields. If the valid data +is smaller than this, it must be padded appropriately. For some sampling +factors and image sizes, additional dummy DCT blocks are inserted to make +the image a multiple of the MCU dimensions. The library creates such dummy +blocks itself; it does not read them from your supplied data. Therefore you +need never pad by more than DCTSIZE samples. An example may help here. +Assume 2h2v downsampling of YCbCr data, that is + cinfo->comp_info[0].h_samp_factor = 2 for Y + cinfo->comp_info[0].v_samp_factor = 2 + cinfo->comp_info[1].h_samp_factor = 1 for Cb + cinfo->comp_info[1].v_samp_factor = 1 + cinfo->comp_info[2].h_samp_factor = 1 for Cr + cinfo->comp_info[2].v_samp_factor = 1 +and suppose that the nominal image dimensions (cinfo->image_width and +cinfo->image_height) are 101x101 pixels. Then jpeg_start_compress() will +compute downsampled_width = 101 and width_in_blocks = 13 for Y, +downsampled_width = 51 and width_in_blocks = 7 for Cb and Cr (and the same +for the height fields). You must pad the Y data to at least 13*8 = 104 +columns and rows, the Cb/Cr data to at least 7*8 = 56 columns and rows. The +MCU height is max_v_samp_factor = 2 DCT rows so you must pass at least 16 +scanlines on each call to jpeg_write_raw_data(), which is to say 16 actual +sample rows of Y and 8 each of Cb and Cr. A total of 7 MCU rows are needed, +so you must pass a total of 7*16 = 112 "scanlines". The last DCT block row +of Y data is dummy, so it doesn't matter what you pass for it in the data +arrays, but the scanlines count must total up to 112 so that all of the Cb +and Cr data gets passed. + +Output suspension is supported with raw-data compression: if the data +destination module suspends, jpeg_write_raw_data() will return 0. +In this case the same data rows must be passed again on the next call. + + +Decompression with raw data output implies bypassing all postprocessing: +you cannot ask for rescaling or color quantization, for instance. More +seriously, you must deal with the color space and sampling factors present in +the incoming file. If your application only handles, say, 2h1v YCbCr data, +you must check for and fail on other color spaces or other sampling factors. +The library will not convert to a different color space for you. + +To obtain raw data output, set cinfo->raw_data_out = TRUE before +jpeg_start_decompress() (it is set FALSE by jpeg_read_header()). Be sure to +verify that the color space and sampling factors are ones you can handle. +Then call jpeg_read_raw_data() in place of jpeg_read_scanlines(). The +decompression process is otherwise the same as usual. + +jpeg_read_raw_data() returns one MCU row per call, and thus you must pass a +buffer of at least max_v_samp_factor*DCTSIZE scanlines (scanline counting is +the same as for raw-data compression). The buffer you pass must be large +enough to hold the actual data plus padding to DCT-block boundaries. As with +compression, any entirely dummy DCT blocks are not processed so you need not +allocate space for them, but the total scanline count includes them. The +above example of computing buffer dimensions for raw-data compression is +equally valid for decompression. + +Input suspension is supported with raw-data decompression: if the data source +module suspends, jpeg_read_raw_data() will return 0. You can also use +buffered-image mode to read raw data in multiple passes. + + +Really raw data: DCT coefficients +--------------------------------- + +It is possible to read or write the contents of a JPEG file as raw DCT +coefficients. This facility is mainly intended for use in lossless +transcoding between different JPEG file formats. Other possible applications +include lossless cropping of a JPEG image, lossless reassembly of a +multi-strip or multi-tile TIFF/JPEG file into a single JPEG datastream, etc. + +To read the contents of a JPEG file as DCT coefficients, open the file and do +jpeg_read_header() as usual. But instead of calling jpeg_start_decompress() +and jpeg_read_scanlines(), call jpeg_read_coefficients(). This will read the +entire image into a set of virtual coefficient-block arrays, one array per +component. The return value is a pointer to an array of virtual-array +descriptors. Each virtual array can be accessed directly using the JPEG +memory manager's access_virt_barray method (see Memory management, below, +and also read structure.doc's discussion of virtual array handling). Or, +for simple transcoding to a different JPEG file format, the array list can +just be handed directly to jpeg_write_coefficients(). + +Each block in the block arrays contains quantized coefficient values in +normal array order (not JPEG zigzag order). The block arrays contain only +DCT blocks containing real data; any entirely-dummy blocks added to fill out +interleaved MCUs at the right or bottom edges of the image are discarded +during reading and are not stored in the block arrays. (The size of each +block array can be determined from the width_in_blocks and height_in_blocks +fields of the component's comp_info entry.) This is also the data format +expected by jpeg_write_coefficients(). + +When you are done using the virtual arrays, call jpeg_finish_decompress() +to release the array storage and return the decompression object to an idle +state; or just call jpeg_destroy() if you don't need to reuse the object. + +If you use a suspending data source, jpeg_read_coefficients() will return +NULL if it is forced to suspend; a non-NULL return value indicates successful +completion. You need not test for a NULL return value when using a +non-suspending data source. + +It is also possible to call jpeg_read_coefficients() to obtain access to the +decoder's coefficient arrays during a normal decode cycle in buffered-image +mode. This frammish might be useful for progressively displaying an incoming +image and then re-encoding it without loss. To do this, decode in buffered- +image mode as discussed previously, then call jpeg_read_coefficients() after +the last jpeg_finish_output() call. The arrays will be available for your use +until you call jpeg_finish_decompress(). + + +To write the contents of a JPEG file as DCT coefficients, you must provide +the DCT coefficients stored in virtual block arrays. You can either pass +block arrays read from an input JPEG file by jpeg_read_coefficients(), or +allocate virtual arrays from the JPEG compression object and fill them +yourself. In either case, jpeg_write_coefficients() is substituted for +jpeg_start_compress() and jpeg_write_scanlines(). Thus the sequence is + * Create compression object + * Set all compression parameters as necessary + * Request virtual arrays if needed + * jpeg_write_coefficients() + * jpeg_finish_compress() + * Destroy or re-use compression object +jpeg_write_coefficients() is passed a pointer to an array of virtual block +array descriptors; the number of arrays is equal to cinfo.num_components. + +The virtual arrays need only have been requested, not realized, before +jpeg_write_coefficients() is called. A side-effect of +jpeg_write_coefficients() is to realize any virtual arrays that have been +requested from the compression object's memory manager. Thus, when obtaining +the virtual arrays from the compression object, you should fill the arrays +after calling jpeg_write_coefficients(). The data is actually written out +when you call jpeg_finish_compress(); jpeg_write_coefficients() only writes +the file header. + +When writing raw DCT coefficients, it is crucial that the JPEG quantization +tables and sampling factors match the way the data was encoded, or the +resulting file will be invalid. For transcoding from an existing JPEG file, +we recommend using jpeg_copy_critical_parameters(). This routine initializes +all the compression parameters to default values (like jpeg_set_defaults()), +then copies the critical information from a source decompression object. +The decompression object should have just been used to read the entire +JPEG input file --- that is, it should be awaiting jpeg_finish_decompress(). + +jpeg_write_coefficients() marks all tables stored in the compression object +as needing to be written to the output file (thus, it acts like +jpeg_start_compress(cinfo, TRUE)). This is for safety's sake, to avoid +emitting abbreviated JPEG files by accident. If you really want to emit an +abbreviated JPEG file, call jpeg_suppress_tables(), or set the tables' +individual sent_table flags, between calling jpeg_write_coefficients() and +jpeg_finish_compress(). + + +Progress monitoring +------------------- + +Some applications may need to regain control from the JPEG library every so +often. The typical use of this feature is to produce a percent-done bar or +other progress display. (For a simple example, see cjpeg.c or djpeg.c.) +Although you do get control back frequently during the data-transferring pass +(the jpeg_read_scanlines or jpeg_write_scanlines loop), any additional passes +will occur inside jpeg_finish_compress or jpeg_start_decompress; those +routines may take a long time to execute, and you don't get control back +until they are done. + +You can define a progress-monitor routine which will be called periodically +by the library. No guarantees are made about how often this call will occur, +so we don't recommend you use it for mouse tracking or anything like that. +At present, a call will occur once per MCU row, scanline, or sample row +group, whichever unit is convenient for the current processing mode; so the +wider the image, the longer the time between calls. During the data +transferring pass, only one call occurs per call of jpeg_read_scanlines or +jpeg_write_scanlines, so don't pass a large number of scanlines at once if +you want fine resolution in the progress count. (If you really need to use +the callback mechanism for time-critical tasks like mouse tracking, you could +insert additional calls inside some of the library's inner loops.) + +To establish a progress-monitor callback, create a struct jpeg_progress_mgr, +fill in its progress_monitor field with a pointer to your callback routine, +and set cinfo->progress to point to the struct. The callback will be called +whenever cinfo->progress is non-NULL. (This pointer is set to NULL by +jpeg_create_compress or jpeg_create_decompress; the library will not change +it thereafter. So if you allocate dynamic storage for the progress struct, +make sure it will live as long as the JPEG object does. Allocating from the +JPEG memory manager with lifetime JPOOL_PERMANENT will work nicely.) You +can use the same callback routine for both compression and decompression. + +The jpeg_progress_mgr struct contains four fields which are set by the library: + long pass_counter; /* work units completed in this pass */ + long pass_limit; /* total number of work units in this pass */ + int completed_passes; /* passes completed so far */ + int total_passes; /* total number of passes expected */ +During any one pass, pass_counter increases from 0 up to (not including) +pass_limit; the step size is usually but not necessarily 1. The pass_limit +value may change from one pass to another. The expected total number of +passes is in total_passes, and the number of passes already completed is in +completed_passes. Thus the fraction of work completed may be estimated as + completed_passes + (pass_counter/pass_limit) + -------------------------------------------- + total_passes +ignoring the fact that the passes may not be equal amounts of work. + +When decompressing, pass_limit can even change within a pass, because it +depends on the number of scans in the JPEG file, which isn't always known in +advance. The computed fraction-of-work-done may jump suddenly (if the library +discovers it has overestimated the number of scans) or even decrease (in the +opposite case). It is not wise to put great faith in the work estimate. + +When using the decompressor's buffered-image mode, the progress monitor work +estimate is likely to be completely unhelpful, because the library has no way +to know how many output passes will be demanded of it. Currently, the library +sets total_passes based on the assumption that there will be one more output +pass if the input file end hasn't yet been read (jpeg_input_complete() isn't +TRUE), but no more output passes if the file end has been reached when the +output pass is started. This means that total_passes will rise as additional +output passes are requested. If you have a way of determining the input file +size, estimating progress based on the fraction of the file that's been read +will probably be more useful than using the library's value. + + +Memory management +----------------- + +This section covers some key facts about the JPEG library's built-in memory +manager. For more info, please read structure.doc's section about the memory +manager, and consult the source code if necessary. + +All memory and temporary file allocation within the library is done via the +memory manager. If necessary, you can replace the "back end" of the memory +manager to control allocation yourself (for example, if you don't want the +library to use malloc() and free() for some reason). + +Some data is allocated "permanently" and will not be freed until the JPEG +object is destroyed. Most data is allocated "per image" and is freed by +jpeg_finish_compress, jpeg_finish_decompress, or jpeg_abort. You can call the +memory manager yourself to allocate structures that will automatically be +freed at these times. Typical code for this is + ptr = (*cinfo->mem->alloc_small) ((j_common_ptr) cinfo, JPOOL_IMAGE, size); +Use JPOOL_PERMANENT to get storage that lasts as long as the JPEG object. +Use alloc_large instead of alloc_small for anything bigger than a few Kbytes. +There are also alloc_sarray and alloc_barray routines that automatically +build 2-D sample or block arrays. + +The library's minimum space requirements to process an image depend on the +image's width, but not on its height, because the library ordinarily works +with "strip" buffers that are as wide as the image but just a few rows high. +Some operating modes (eg, two-pass color quantization) require full-image +buffers. Such buffers are treated as "virtual arrays": only the current strip +need be in memory, and the rest can be swapped out to a temporary file. + +If you use the simplest memory manager back end (jmemnobs.c), then no +temporary files are used; virtual arrays are simply malloc()'d. Images bigger +than memory can be processed only if your system supports virtual memory. +The other memory manager back ends support temporary files of various flavors +and thus work in machines without virtual memory. They may also be useful on +Unix machines if you need to process images that exceed available swap space. + +When using temporary files, the library will make the in-memory buffers for +its virtual arrays just big enough to stay within a "maximum memory" setting. +Your application can set this limit by setting cinfo->mem->max_memory_to_use +after creating the JPEG object. (Of course, there is still a minimum size for +the buffers, so the max-memory setting is effective only if it is bigger than +the minimum space needed.) If you allocate any large structures yourself, you +must allocate them before jpeg_start_compress() or jpeg_start_decompress() in +order to have them counted against the max memory limit. Also keep in mind +that space allocated with alloc_small() is ignored, on the assumption that +it's too small to be worth worrying about; so a reasonable safety margin +should be left when setting max_memory_to_use. + +If you use the jmemname.c or jmemdos.c memory manager back end, it is +important to clean up the JPEG object properly to ensure that the temporary +files get deleted. (This is especially crucial with jmemdos.c, where the +"temporary files" may be extended-memory segments; if they are not freed, +DOS will require a reboot to recover the memory.) Thus, with these memory +managers, it's a good idea to provide a signal handler that will trap any +early exit from your program. The handler should call either jpeg_abort() +or jpeg_destroy() for any active JPEG objects. A handler is not needed with +jmemnobs.c, and shouldn't be necessary with jmemansi.c or jmemmac.c either, +since the C library is supposed to take care of deleting files made with +tmpfile(). + + +Memory usage +------------ + +Working memory requirements while performing compression or decompression +depend on image dimensions, image characteristics (such as colorspace and +JPEG process), and operating mode (application-selected options). + +As of v6b, the decompressor requires: + 1. About 24K in more-or-less-fixed-size data. This varies a bit depending + on operating mode and image characteristics (particularly color vs. + grayscale), but it doesn't depend on image dimensions. + 2. Strip buffers (of size proportional to the image width) for IDCT and + upsampling results. The worst case for commonly used sampling factors + is about 34 bytes * width in pixels for a color image. A grayscale image + only needs about 8 bytes per pixel column. + 3. A full-image DCT coefficient buffer is needed to decode a multi-scan JPEG + file (including progressive JPEGs), or whenever you select buffered-image + mode. This takes 2 bytes/coefficient. At typical 2x2 sampling, that's + 3 bytes per pixel for a color image. Worst case (1x1 sampling) requires + 6 bytes/pixel. For grayscale, figure 2 bytes/pixel. + 4. To perform 2-pass color quantization, the decompressor also needs a + 128K color lookup table and a full-image pixel buffer (3 bytes/pixel). +This does not count any memory allocated by the application, such as a +buffer to hold the final output image. + +The above figures are valid for 8-bit JPEG data precision and a machine with +32-bit ints. For 12-bit JPEG data, double the size of the strip buffers and +quantization pixel buffer. The "fixed-size" data will be somewhat smaller +with 16-bit ints, larger with 64-bit ints. Also, CMYK or other unusual +color spaces will require different amounts of space. + +The full-image coefficient and pixel buffers, if needed at all, do not +have to be fully RAM resident; you can have the library use temporary +files instead when the total memory usage would exceed a limit you set. +(But if your OS supports virtual memory, it's probably better to just use +jmemnobs and let the OS do the swapping.) + +The compressor's memory requirements are similar, except that it has no need +for color quantization. Also, it needs a full-image DCT coefficient buffer +if Huffman-table optimization is asked for, even if progressive mode is not +requested. + +If you need more detailed information about memory usage in a particular +situation, you can enable the MEM_STATS code in jmemmgr.c. + + +Library compile-time options +---------------------------- + +A number of compile-time options are available by modifying jmorecfg.h. + +The JPEG standard provides for both the baseline 8-bit DCT process and +a 12-bit DCT process. The IJG code supports 12-bit lossy JPEG if you define +BITS_IN_JSAMPLE as 12 rather than 8. Note that this causes JSAMPLE to be +larger than a char, so it affects the surrounding application's image data. +The sample applications cjpeg and djpeg can support 12-bit mode only for PPM +and GIF file formats; you must disable the other file formats to compile a +12-bit cjpeg or djpeg. (install.doc has more information about that.) +At present, a 12-bit library can handle *only* 12-bit images, not both +precisions. (If you need to include both 8- and 12-bit libraries in a single +application, you could probably do it by defining NEED_SHORT_EXTERNAL_NAMES +for just one of the copies. You'd have to access the 8-bit and 12-bit copies +from separate application source files. This is untested ... if you try it, +we'd like to hear whether it works!) + +Note that a 12-bit library always compresses in Huffman optimization mode, +in order to generate valid Huffman tables. This is necessary because our +default Huffman tables only cover 8-bit data. If you need to output 12-bit +files in one pass, you'll have to supply suitable default Huffman tables. +You may also want to supply your own DCT quantization tables; the existing +quality-scaling code has been developed for 8-bit use, and probably doesn't +generate especially good tables for 12-bit. + +The maximum number of components (color channels) in the image is determined +by MAX_COMPONENTS. The JPEG standard allows up to 255 components, but we +expect that few applications will need more than four or so. + +On machines with unusual data type sizes, you may be able to improve +performance or reduce memory space by tweaking the various typedefs in +jmorecfg.h. In particular, on some RISC CPUs, access to arrays of "short"s +is quite slow; consider trading memory for speed by making JCOEF, INT16, and +UINT16 be "int" or "unsigned int". UINT8 is also a candidate to become int. +You probably don't want to make JSAMPLE be int unless you have lots of memory +to burn. + +You can reduce the size of the library by compiling out various optional +functions. To do this, undefine xxx_SUPPORTED symbols as necessary. + +You can also save a few K by not having text error messages in the library; +the standard error message table occupies about 5Kb. This is particularly +reasonable for embedded applications where there's no good way to display +a message anyway. To do this, remove the creation of the message table +(jpeg_std_message_table[]) from jerror.c, and alter format_message to do +something reasonable without it. You could output the numeric value of the +message code number, for example. If you do this, you can also save a couple +more K by modifying the TRACEMSn() macros in jerror.h to expand to nothing; +you don't need trace capability anyway, right? + + +Portability considerations +-------------------------- + +The JPEG library has been written to be extremely portable; the sample +applications cjpeg and djpeg are slightly less so. This section summarizes +the design goals in this area. (If you encounter any bugs that cause the +library to be less portable than is claimed here, we'd appreciate hearing +about them.) + +The code works fine on ANSI C, C++, and pre-ANSI C compilers, using any of +the popular system include file setups, and some not-so-popular ones too. +See install.doc for configuration procedures. + +The code is not dependent on the exact sizes of the C data types. As +distributed, we make the assumptions that + char is at least 8 bits wide + short is at least 16 bits wide + int is at least 16 bits wide + long is at least 32 bits wide +(These are the minimum requirements of the ANSI C standard.) Wider types will +work fine, although memory may be used inefficiently if char is much larger +than 8 bits or short is much bigger than 16 bits. The code should work +equally well with 16- or 32-bit ints. + +In a system where these assumptions are not met, you may be able to make the +code work by modifying the typedefs in jmorecfg.h. However, you will probably +have difficulty if int is less than 16 bits wide, since references to plain +int abound in the code. + +char can be either signed or unsigned, although the code runs faster if an +unsigned char type is available. If char is wider than 8 bits, you will need +to redefine JOCTET and/or provide custom data source/destination managers so +that JOCTET represents exactly 8 bits of data on external storage. + +The JPEG library proper does not assume ASCII representation of characters. +But some of the image file I/O modules in cjpeg/djpeg do have ASCII +dependencies in file-header manipulation; so does cjpeg's select_file_type() +routine. + +The JPEG library does not rely heavily on the C library. In particular, C +stdio is used only by the data source/destination modules and the error +handler, all of which are application-replaceable. (cjpeg/djpeg are more +heavily dependent on stdio.) malloc and free are called only from the memory +manager "back end" module, so you can use a different memory allocator by +replacing that one file. + +The code generally assumes that C names must be unique in the first 15 +characters. However, global function names can be made unique in the +first 6 characters by defining NEED_SHORT_EXTERNAL_NAMES. + +More info about porting the code may be gleaned by reading jconfig.doc, +jmorecfg.h, and jinclude.h. + + +Notes for MS-DOS implementors +----------------------------- + +The IJG code is designed to work efficiently in 80x86 "small" or "medium" +memory models (i.e., data pointers are 16 bits unless explicitly declared +"far"; code pointers can be either size). You may be able to use small +model to compile cjpeg or djpeg by itself, but you will probably have to use +medium model for any larger application. This won't make much difference in +performance. You *will* take a noticeable performance hit if you use a +large-data memory model (perhaps 10%-25%), and you should avoid "huge" model +if at all possible. + +The JPEG library typically needs 2Kb-3Kb of stack space. It will also +malloc about 20K-30K of near heap space while executing (and lots of far +heap, but that doesn't count in this calculation). This figure will vary +depending on selected operating mode, and to a lesser extent on image size. +There is also about 5Kb-6Kb of constant data which will be allocated in the +near data segment (about 4Kb of this is the error message table). +Thus you have perhaps 20K available for other modules' static data and near +heap space before you need to go to a larger memory model. The C library's +static data will account for several K of this, but that still leaves a good +deal for your needs. (If you are tight on space, you could reduce the sizes +of the I/O buffers allocated by jdatasrc.c and jdatadst.c, say from 4K to +1K. Another possibility is to move the error message table to far memory; +this should be doable with only localized hacking on jerror.c.) + +About 2K of the near heap space is "permanent" memory that will not be +released until you destroy the JPEG object. This is only an issue if you +save a JPEG object between compression or decompression operations. + +Far data space may also be a tight resource when you are dealing with large +images. The most memory-intensive case is decompression with two-pass color +quantization, or single-pass quantization to an externally supplied color +map. This requires a 128Kb color lookup table plus strip buffers amounting +to about 40 bytes per column for typical sampling ratios (eg, about 25600 +bytes for a 640-pixel-wide image). You may not be able to process wide +images if you have large data structures of your own. + +Of course, all of these concerns vanish if you use a 32-bit flat-memory-model +compiler, such as DJGPP or Watcom C. We highly recommend flat model if you +can use it; the JPEG library is significantly faster in flat model. diff --git a/makefile.cfg b/makefile.cfg deleted file mode 100644 index 7bb3b9df..00000000 --- a/makefile.cfg +++ /dev/null @@ -1,319 +0,0 @@ -# Makefile for Independent JPEG Group's software - -# makefile.cfg is edited by configure to produce a custom Makefile. - -# Read installation instructions before saying "make" !! - -# For compiling with source and object files in different directories. -srcdir = @srcdir@ -VPATH = @srcdir@ - -# Where to install the programs and man pages. -prefix = @prefix@ -exec_prefix = @exec_prefix@ -bindir = $(exec_prefix)/bin -libdir = $(exec_prefix)/lib -includedir = $(prefix)/include -binprefix = -manprefix = -manext = 1 -mandir = $(prefix)/man/man$(manext) - -# The name of your C compiler: -CC= @CC@ - -# You may need to adjust these cc options: -CFLAGS= @CFLAGS@ @CPPFLAGS@ @INCLUDEFLAGS@ -# Generally, we recommend defining any configuration symbols in jconfig.h, -# NOT via -D switches here. -# However, any special defines for ansi2knr.c may be included here: -ANSI2KNRFLAGS= @ANSI2KNRFLAGS@ - -# Link-time cc options: -LDFLAGS= @LDFLAGS@ - -# To link any special libraries, add the necessary -l commands here. -LDLIBS= @LIBS@ - -# If using GNU libtool, LIBTOOL references it; if not, LIBTOOL is empty. -LIBTOOL = @LIBTOOL@ -# $(O) expands to "lo" if using libtool, plain "o" if not. -# Similarly, $(A) expands to "la" or "a". -O = @O@ -A = @A@ - -# Library version ID; libtool uses this for the shared library version number. -# Note: we suggest this match the macro of the same name in jpeglib.h. -JPEG_LIB_VERSION = @JPEG_LIB_VERSION@ - -# Put here the object file name for the correct system-dependent memory -# manager file. For Unix this is usually jmemnobs.o, but you may want -# to use jmemansi.o or jmemname.o if you have limited swap space. -SYSDEPMEM= @MEMORYMGR@ - -# miscellaneous OS-dependent stuff -SHELL= /bin/sh -# linker -LN= @LN@ -# file deletion command -RM= rm -f -# directory creation command -MKDIR= mkdir -# library (.a) file creation command -AR= ar rc -# second step in .a creation (use "touch" if not needed) -AR2= @RANLIB@ -# installation program -INSTALL= @INSTALL@ -INSTALL_PROGRAM= @INSTALL_PROGRAM@ -INSTALL_LIB= @INSTALL_LIB@ -INSTALL_DATA= @INSTALL_DATA@ - -# End of configurable options. - - -# source files: JPEG library proper -LIBSOURCES= jcapimin.c jcapistd.c jccoefct.c jccolor.c jcdctmgr.c jchuff.c \ - jcinit.c jcmainct.c jcmarker.c jcmaster.c jcomapi.c jcparam.c \ - jcphuff.c jcprepct.c jcsample.c jctrans.c jdapimin.c jdapistd.c \ - jdatadst.c jdatasrc.c jdcoefct.c jdcolor.c jddctmgr.c jdhuff.c \ - jdinput.c jdmainct.c jdmarker.c jdmaster.c jdmerge.c jdphuff.c \ - jdpostct.c jdsample.c jdtrans.c jerror.c jfdctflt.c jfdctfst.c \ - jfdctint.c jidctflt.c jidctfst.c jidctint.c jidctred.c jquant1.c \ - jquant2.c jutils.c jmemmgr.c -# memmgr back ends: compile only one of these into a working library -SYSDEPSOURCES= jmemansi.c jmemname.c jmemnobs.c jmemdos.c jmemmac.c -# source files: cjpeg/djpeg/jpegtran applications, also rdjpgcom/wrjpgcom -APPSOURCES= cjpeg.c djpeg.c jpegtran.c rdjpgcom.c wrjpgcom.c cdjpeg.c \ - rdcolmap.c rdswitch.c transupp.c rdppm.c wrppm.c rdgif.c wrgif.c \ - rdtarga.c wrtarga.c rdbmp.c wrbmp.c rdrle.c wrrle.c -SOURCES= $(LIBSOURCES) $(SYSDEPSOURCES) $(APPSOURCES) -# files included by source files -INCLUDES= jchuff.h jdhuff.h jdct.h jerror.h jinclude.h jmemsys.h jmorecfg.h \ - jpegint.h jpeglib.h jversion.h cdjpeg.h cderror.h transupp.h -# documentation, test, and support files -DOCS= README install.doc usage.doc cjpeg.1 djpeg.1 jpegtran.1 rdjpgcom.1 \ - wrjpgcom.1 wizard.doc example.c libjpeg.doc structure.doc \ - coderules.doc filelist.doc change.log -MKFILES= configure makefile.cfg makefile.ansi makefile.unix makefile.bcc \ - makefile.mc6 makefile.dj makefile.wat makefile.vc makelib.ds \ - makeapps.ds makeproj.mac makcjpeg.st makdjpeg.st makljpeg.st \ - maktjpeg.st makefile.manx makefile.sas makefile.mms makefile.vms \ - makvms.opt -CONFIGFILES= jconfig.cfg jconfig.bcc jconfig.mc6 jconfig.dj jconfig.wat \ - jconfig.vc jconfig.mac jconfig.st jconfig.manx jconfig.sas \ - jconfig.vms -CONFIGUREFILES= config.guess config.sub install-sh ltconfig ltmain.sh -OTHERFILES= jconfig.doc ckconfig.c ansi2knr.c ansi2knr.1 jmemdosa.asm -TESTFILES= testorig.jpg testimg.ppm testimg.bmp testimg.jpg testprog.jpg \ - testimgp.jpg -DISTFILES= $(DOCS) $(MKFILES) $(CONFIGFILES) $(SOURCES) $(INCLUDES) \ - $(CONFIGUREFILES) $(OTHERFILES) $(TESTFILES) -# library object files common to compression and decompression -COMOBJECTS= jcomapi.$(O) jutils.$(O) jerror.$(O) jmemmgr.$(O) $(SYSDEPMEM) -# compression library object files -CLIBOBJECTS= jcapimin.$(O) jcapistd.$(O) jctrans.$(O) jcparam.$(O) \ - jdatadst.$(O) jcinit.$(O) jcmaster.$(O) jcmarker.$(O) jcmainct.$(O) \ - jcprepct.$(O) jccoefct.$(O) jccolor.$(O) jcsample.$(O) jchuff.$(O) \ - jcphuff.$(O) jcdctmgr.$(O) jfdctfst.$(O) jfdctflt.$(O) \ - jfdctint.$(O) -# decompression library object files -DLIBOBJECTS= jdapimin.$(O) jdapistd.$(O) jdtrans.$(O) jdatasrc.$(O) \ - jdmaster.$(O) jdinput.$(O) jdmarker.$(O) jdhuff.$(O) jdphuff.$(O) \ - jdmainct.$(O) jdcoefct.$(O) jdpostct.$(O) jddctmgr.$(O) \ - jidctfst.$(O) jidctflt.$(O) jidctint.$(O) jidctred.$(O) \ - jdsample.$(O) jdcolor.$(O) jquant1.$(O) jquant2.$(O) jdmerge.$(O) -# These objectfiles are included in libjpeg.a -LIBOBJECTS= $(CLIBOBJECTS) $(DLIBOBJECTS) $(COMOBJECTS) -# object files for sample applications (excluding library files) -COBJECTS= cjpeg.$(O) rdppm.$(O) rdgif.$(O) rdtarga.$(O) rdrle.$(O) \ - rdbmp.$(O) rdswitch.$(O) cdjpeg.$(O) -DOBJECTS= djpeg.$(O) wrppm.$(O) wrgif.$(O) wrtarga.$(O) wrrle.$(O) \ - wrbmp.$(O) rdcolmap.$(O) cdjpeg.$(O) -TROBJECTS= jpegtran.$(O) rdswitch.$(O) cdjpeg.$(O) transupp.$(O) - - -all: @A2K_DEPS@ libjpeg.$(A) - -# Special compilation rules to support ansi2knr and libtool. -.SUFFIXES: .lo .la - -# How to compile with libtool. -@COM_LT@.c.lo: -@COM_LT@ $(LIBTOOL) --mode=compile $(CC) $(CFLAGS) -c $(srcdir)/$*.c - -# How to use ansi2knr, when not using libtool. -@COM_A2K@.c.o: -@COM_A2K@ ./ansi2knr $(srcdir)/$*.c knr/$*.c -@COM_A2K@ $(CC) $(CFLAGS) -c knr/$*.c -@COM_A2K@ $(RM) knr/$*.c - -# How to use ansi2knr AND libtool. -@COM_A2K@.c.lo: -@COM_A2K@ ./ansi2knr $(srcdir)/$*.c knr/$*.c -@COM_A2K@ $(LIBTOOL) --mode=compile $(CC) $(CFLAGS) -c knr/$*.c -@COM_A2K@ $(RM) knr/$*.c - -ansi2knr: ansi2knr.c - $(CC) $(CFLAGS) $(ANSI2KNRFLAGS) -o ansi2knr $(srcdir)/ansi2knr.c - $(MKDIR) knr - -# the library: - -# without libtool: -libjpeg.a: @A2K_DEPS@ $(LIBOBJECTS) - $(RM) libjpeg.a - $(AR) libjpeg.a $(LIBOBJECTS) - $(AR2) libjpeg.a - -# with libtool: -libjpeg.la: @A2K_DEPS@ $(LIBOBJECTS) - $(LIBTOOL) --mode=link $(CC) -o libjpeg.la $(LIBOBJECTS) \ - -rpath $(libdir) -version-info $(JPEG_LIB_VERSION) - -# sample programs: - -cjpeg: $(COBJECTS) libjpeg.$(A) - $(LN) $(LDFLAGS) -o cjpeg $(COBJECTS) libjpeg.$(A) $(LDLIBS) - -djpeg: $(DOBJECTS) libjpeg.$(A) - $(LN) $(LDFLAGS) -o djpeg $(DOBJECTS) libjpeg.$(A) $(LDLIBS) - -jpegtran: $(TROBJECTS) libjpeg.$(A) - $(LN) $(LDFLAGS) -o jpegtran $(TROBJECTS) libjpeg.$(A) $(LDLIBS) - -rdjpgcom: rdjpgcom.$(O) - $(LN) $(LDFLAGS) -o rdjpgcom rdjpgcom.$(O) $(LDLIBS) - -wrjpgcom: wrjpgcom.$(O) - $(LN) $(LDFLAGS) -o wrjpgcom wrjpgcom.$(O) $(LDLIBS) - -# Installation rules: - -install: cjpeg djpeg jpegtran rdjpgcom wrjpgcom @FORCE_INSTALL_LIB@ - $(INSTALL_PROGRAM) cjpeg $(bindir)/$(binprefix)cjpeg - $(INSTALL_PROGRAM) djpeg $(bindir)/$(binprefix)djpeg - $(INSTALL_PROGRAM) jpegtran $(bindir)/$(binprefix)jpegtran - $(INSTALL_PROGRAM) rdjpgcom $(bindir)/$(binprefix)rdjpgcom - $(INSTALL_PROGRAM) wrjpgcom $(bindir)/$(binprefix)wrjpgcom - $(INSTALL_DATA) $(srcdir)/cjpeg.1 $(mandir)/$(manprefix)cjpeg.$(manext) - $(INSTALL_DATA) $(srcdir)/djpeg.1 $(mandir)/$(manprefix)djpeg.$(manext) - $(INSTALL_DATA) $(srcdir)/jpegtran.1 $(mandir)/$(manprefix)jpegtran.$(manext) - $(INSTALL_DATA) $(srcdir)/rdjpgcom.1 $(mandir)/$(manprefix)rdjpgcom.$(manext) - $(INSTALL_DATA) $(srcdir)/wrjpgcom.1 $(mandir)/$(manprefix)wrjpgcom.$(manext) - -install-lib: libjpeg.$(A) install-headers - $(INSTALL_LIB) libjpeg.$(A) $(libdir)/$(binprefix)libjpeg.$(A) - -install-headers: jconfig.h - $(INSTALL_DATA) jconfig.h $(includedir)/jconfig.h - $(INSTALL_DATA) $(srcdir)/jpeglib.h $(includedir)/jpeglib.h - $(INSTALL_DATA) $(srcdir)/jmorecfg.h $(includedir)/jmorecfg.h - $(INSTALL_DATA) $(srcdir)/jerror.h $(includedir)/jerror.h - -clean: - $(RM) *.o *.lo libjpeg.a libjpeg.la - $(RM) cjpeg djpeg jpegtran rdjpgcom wrjpgcom - $(RM) ansi2knr core testout* config.log config.status - $(RM) -r knr .libs _libs - -distclean: clean - $(RM) Makefile jconfig.h libtool config.cache - -test: cjpeg djpeg jpegtran - $(RM) testout* - ./djpeg -dct int -ppm -outfile testout.ppm $(srcdir)/testorig.jpg - ./djpeg -dct int -bmp -colors 256 -outfile testout.bmp $(srcdir)/testorig.jpg - ./cjpeg -dct int -outfile testout.jpg $(srcdir)/testimg.ppm - ./djpeg -dct int -ppm -outfile testoutp.ppm $(srcdir)/testprog.jpg - ./cjpeg -dct int -progressive -opt -outfile testoutp.jpg $(srcdir)/testimg.ppm - ./jpegtran -outfile testoutt.jpg $(srcdir)/testprog.jpg - cmp $(srcdir)/testimg.ppm testout.ppm - cmp $(srcdir)/testimg.bmp testout.bmp - cmp $(srcdir)/testimg.jpg testout.jpg - cmp $(srcdir)/testimg.ppm testoutp.ppm - cmp $(srcdir)/testimgp.jpg testoutp.jpg - cmp $(srcdir)/testorig.jpg testoutt.jpg - -check: test - -# Mistake catcher: - -jconfig.h: jconfig.doc - echo You must prepare a system-dependent jconfig.h file. - echo Please read the installation directions in install.doc. - exit 1 - -# GNU Make likes to know which target names are not really files to be made: -.PHONY: all install install-lib install-headers clean distclean test check - - -jcapimin.$(O): jcapimin.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jcapistd.$(O): jcapistd.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jccoefct.$(O): jccoefct.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jccolor.$(O): jccolor.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jcdctmgr.$(O): jcdctmgr.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h jdct.h -jchuff.$(O): jchuff.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h jchuff.h -jcinit.$(O): jcinit.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jcmainct.$(O): jcmainct.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jcmarker.$(O): jcmarker.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jcmaster.$(O): jcmaster.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jcomapi.$(O): jcomapi.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jcparam.$(O): jcparam.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jcphuff.$(O): jcphuff.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h jchuff.h -jcprepct.$(O): jcprepct.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jcsample.$(O): jcsample.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jctrans.$(O): jctrans.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jdapimin.$(O): jdapimin.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jdapistd.$(O): jdapistd.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jdatadst.$(O): jdatadst.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jerror.h -jdatasrc.$(O): jdatasrc.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jerror.h -jdcoefct.$(O): jdcoefct.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jdcolor.$(O): jdcolor.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jddctmgr.$(O): jddctmgr.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h jdct.h -jdhuff.$(O): jdhuff.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h jdhuff.h -jdinput.$(O): jdinput.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jdmainct.$(O): jdmainct.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jdmarker.$(O): jdmarker.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jdmaster.$(O): jdmaster.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jdmerge.$(O): jdmerge.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jdphuff.$(O): jdphuff.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h jdhuff.h -jdpostct.$(O): jdpostct.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jdsample.$(O): jdsample.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jdtrans.$(O): jdtrans.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jerror.$(O): jerror.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jversion.h jerror.h -jfdctflt.$(O): jfdctflt.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h jdct.h -jfdctfst.$(O): jfdctfst.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h jdct.h -jfdctint.$(O): jfdctint.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h jdct.h -jidctflt.$(O): jidctflt.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h jdct.h -jidctfst.$(O): jidctfst.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h jdct.h -jidctint.$(O): jidctint.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h jdct.h -jidctred.$(O): jidctred.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h jdct.h -jquant1.$(O): jquant1.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jquant2.$(O): jquant2.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jutils.$(O): jutils.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h -jmemmgr.$(O): jmemmgr.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h jmemsys.h -jmemansi.$(O): jmemansi.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h jmemsys.h -jmemname.$(O): jmemname.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h jmemsys.h -jmemnobs.$(O): jmemnobs.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h jmemsys.h -jmemdos.$(O): jmemdos.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h jmemsys.h -jmemmac.$(O): jmemmac.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h jmemsys.h -cjpeg.$(O): cjpeg.c cdjpeg.h jinclude.h jconfig.h jpeglib.h jmorecfg.h jerror.h cderror.h jversion.h -djpeg.$(O): djpeg.c cdjpeg.h jinclude.h jconfig.h jpeglib.h jmorecfg.h jerror.h cderror.h jversion.h -jpegtran.$(O): jpegtran.c cdjpeg.h jinclude.h jconfig.h jpeglib.h jmorecfg.h jerror.h cderror.h transupp.h jversion.h -rdjpgcom.$(O): rdjpgcom.c jinclude.h jconfig.h -wrjpgcom.$(O): wrjpgcom.c jinclude.h jconfig.h -cdjpeg.$(O): cdjpeg.c cdjpeg.h jinclude.h jconfig.h jpeglib.h jmorecfg.h jerror.h cderror.h -rdcolmap.$(O): rdcolmap.c cdjpeg.h jinclude.h jconfig.h jpeglib.h jmorecfg.h jerror.h cderror.h -rdswitch.$(O): rdswitch.c cdjpeg.h jinclude.h jconfig.h jpeglib.h jmorecfg.h jerror.h cderror.h -transupp.$(O): transupp.c jinclude.h jconfig.h jpeglib.h jmorecfg.h jpegint.h jerror.h transupp.h -rdppm.$(O): rdppm.c cdjpeg.h jinclude.h jconfig.h jpeglib.h jmorecfg.h jerror.h cderror.h -wrppm.$(O): wrppm.c cdjpeg.h jinclude.h jconfig.h jpeglib.h jmorecfg.h jerror.h cderror.h -rdgif.$(O): rdgif.c cdjpeg.h jinclude.h jconfig.h jpeglib.h jmorecfg.h jerror.h cderror.h -wrgif.$(O): wrgif.c cdjpeg.h jinclude.h jconfig.h jpeglib.h jmorecfg.h jerror.h cderror.h -rdtarga.$(O): rdtarga.c cdjpeg.h jinclude.h jconfig.h jpeglib.h jmorecfg.h jerror.h cderror.h -wrtarga.$(O): wrtarga.c cdjpeg.h jinclude.h jconfig.h jpeglib.h jmorecfg.h jerror.h cderror.h -rdbmp.$(O): rdbmp.c cdjpeg.h jinclude.h jconfig.h jpeglib.h jmorecfg.h jerror.h cderror.h -wrbmp.$(O): wrbmp.c cdjpeg.h jinclude.h jconfig.h jpeglib.h jmorecfg.h jerror.h cderror.h -rdrle.$(O): rdrle.c cdjpeg.h jinclude.h jconfig.h jpeglib.h jmorecfg.h jerror.h cderror.h -wrrle.$(O): wrrle.c cdjpeg.h jinclude.h jconfig.h jpeglib.h jmorecfg.h jerror.h cderror.h diff --git a/rdjpgcom.1 b/rdjpgcom.1 new file mode 100644 index 00000000..2bba04e1 --- /dev/null +++ b/rdjpgcom.1 @@ -0,0 +1,54 @@ +.TH RDJPGCOM 1 "11 October 1997" +.SH NAME +rdjpgcom \- display text comments from a JPEG file +.SH SYNOPSIS +.B rdjpgcom +[ +.B \-verbose +] +[ +.I filename +] +.LP +.SH DESCRIPTION +.LP +.B rdjpgcom +reads the named JPEG/JFIF file, or the standard input if no file is named, +and prints any text comments found in the file on the standard output. +.PP +The JPEG standard allows "comment" (COM) blocks to occur within a JPEG file. +Although the standard doesn't actually define what COM blocks are for, they +are widely used to hold user-supplied text strings. This lets you add +annotations, titles, index terms, etc to your JPEG files, and later retrieve +them as text. COM blocks do not interfere with the image stored in the JPEG +file. The maximum size of a COM block is 64K, but you can have as many of +them as you like in one JPEG file. +.SH OPTIONS +.TP +.B \-verbose +Causes +.B rdjpgcom +to also display the JPEG image dimensions. +.PP +Switch names may be abbreviated, and are not case sensitive. +.SH HINTS +.B rdjpgcom +does not depend on the IJG JPEG library. Its source code is intended as an +illustration of the minimum amount of code required to parse a JPEG file +header correctly. +.PP +In +.B \-verbose +mode, +.B rdjpgcom +will also attempt to print the contents of any "APP12" markers as text. +Some digital cameras produce APP12 markers containing useful textual +information. If you like, you can modify the source code to print +other APPn marker types as well. +.SH SEE ALSO +.BR cjpeg (1), +.BR djpeg (1), +.BR jpegtran (1), +.BR wrjpgcom (1) +.SH AUTHOR +Independent JPEG Group diff --git a/rdjpgcom.c b/rdjpgcom.c new file mode 100644 index 00000000..ffe6fc62 --- /dev/null +++ b/rdjpgcom.c @@ -0,0 +1,496 @@ +/* + * rdjpgcom.c + * + * Copyright (C) 1994-1997, Thomas G. Lane. + * This file is part of the Independent JPEG Group's software. + * For conditions of distribution and use, see the accompanying README file. + * + * This file contains a very simple stand-alone application that displays + * the text in COM (comment) markers in a JFIF file. + * This may be useful as an example of the minimum logic needed to parse + * JPEG markers. + */ + +#define JPEG_CJPEG_DJPEG /* to get the command-line config symbols */ +#include "jinclude.h" /* get auto-config symbols, */ + +#include /* to declare isupper(), tolower() */ +#ifdef USE_SETMODE +#include /* to declare setmode()'s parameter macros */ +/* If you have setmode() but not , just delete this line: */ +#include /* to declare setmode() */ +#endif + +#ifdef USE_CCOMMAND /* command-line reader for Macintosh */ +#ifdef __MWERKS__ +#include /* Metrowerks needs this */ +#include /* ... and this */ +#endif +#ifdef THINK_C +#include /* Think declares it here */ +#endif +#endif + +#ifdef DONT_USE_B_MODE /* define mode parameters for fopen() */ +#define READ_BINARY "r" +#else +#ifdef VMS /* VMS is very nonstandard */ +#define READ_BINARY "rb", "ctx=stm" +#else /* standard ANSI-compliant case */ +#define READ_BINARY "rb" +#endif +#endif + +#ifndef EXIT_FAILURE /* define exit() codes if not provided */ +#define EXIT_FAILURE 1 +#endif +#ifndef EXIT_SUCCESS +#ifdef VMS +#define EXIT_SUCCESS 1 /* VMS is very nonstandard */ +#else +#define EXIT_SUCCESS 0 +#endif +#endif + + +/* + * These macros are used to read the input file. + * To reuse this code in another application, you might need to change these. + */ + +static FILE * infile; /* input JPEG file */ + +/* Return next input byte, or EOF if no more */ +#define NEXTBYTE() getc(infile) + + +/* Error exit handler */ +#define ERREXIT(msg) (fprintf(stderr, "%s\n", msg), exit(EXIT_FAILURE)) + + +/* Read one byte, testing for EOF */ +static int +read_1_byte (void) +{ + int c; + + c = NEXTBYTE(); + if (c == EOF) + ERREXIT("Premature EOF in JPEG file"); + return c; +} + +/* Read 2 bytes, convert to unsigned int */ +/* All 2-byte quantities in JPEG markers are MSB first */ +static unsigned int +read_2_bytes (void) +{ + int c1, c2; + + c1 = NEXTBYTE(); + if (c1 == EOF) + ERREXIT("Premature EOF in JPEG file"); + c2 = NEXTBYTE(); + if (c2 == EOF) + ERREXIT("Premature EOF in JPEG file"); + return (((unsigned int) c1) << 8) + ((unsigned int) c2); +} + + +/* + * JPEG markers consist of one or more 0xFF bytes, followed by a marker + * code byte (which is not an FF). Here are the marker codes of interest + * in this program. (See jdmarker.c for a more complete list.) + */ + +#define M_SOF0 0xC0 /* Start Of Frame N */ +#define M_SOF1 0xC1 /* N indicates which compression process */ +#define M_SOF2 0xC2 /* Only SOF0-SOF2 are now in common use */ +#define M_SOF3 0xC3 +#define M_SOF5 0xC5 /* NB: codes C4 and CC are NOT SOF markers */ +#define M_SOF6 0xC6 +#define M_SOF7 0xC7 +#define M_SOF9 0xC9 +#define M_SOF10 0xCA +#define M_SOF11 0xCB +#define M_SOF13 0xCD +#define M_SOF14 0xCE +#define M_SOF15 0xCF +#define M_SOI 0xD8 /* Start Of Image (beginning of datastream) */ +#define M_EOI 0xD9 /* End Of Image (end of datastream) */ +#define M_SOS 0xDA /* Start Of Scan (begins compressed data) */ +#define M_APP0 0xE0 /* Application-specific marker, type N */ +#define M_APP12 0xEC /* (we don't bother to list all 16 APPn's) */ +#define M_COM 0xFE /* COMment */ + + +/* + * Find the next JPEG marker and return its marker code. + * We expect at least one FF byte, possibly more if the compressor used FFs + * to pad the file. + * There could also be non-FF garbage between markers. The treatment of such + * garbage is unspecified; we choose to skip over it but emit a warning msg. + * NB: this routine must not be used after seeing SOS marker, since it will + * not deal correctly with FF/00 sequences in the compressed image data... + */ + +static int +next_marker (void) +{ + int c; + int discarded_bytes = 0; + + /* Find 0xFF byte; count and skip any non-FFs. */ + c = read_1_byte(); + while (c != 0xFF) { + discarded_bytes++; + c = read_1_byte(); + } + /* Get marker code byte, swallowing any duplicate FF bytes. Extra FFs + * are legal as pad bytes, so don't count them in discarded_bytes. + */ + do { + c = read_1_byte(); + } while (c == 0xFF); + + if (discarded_bytes != 0) { + fprintf(stderr, "Warning: garbage data found in JPEG file\n"); + } + + return c; +} + + +/* + * Read the initial marker, which should be SOI. + * For a JFIF file, the first two bytes of the file should be literally + * 0xFF M_SOI. To be more general, we could use next_marker, but if the + * input file weren't actually JPEG at all, next_marker might read the whole + * file and then return a misleading error message... + */ + +static int +first_marker (void) +{ + int c1, c2; + + c1 = NEXTBYTE(); + c2 = NEXTBYTE(); + if (c1 != 0xFF || c2 != M_SOI) + ERREXIT("Not a JPEG file"); + return c2; +} + + +/* + * Most types of marker are followed by a variable-length parameter segment. + * This routine skips over the parameters for any marker we don't otherwise + * want to process. + * Note that we MUST skip the parameter segment explicitly in order not to + * be fooled by 0xFF bytes that might appear within the parameter segment; + * such bytes do NOT introduce new markers. + */ + +static void +skip_variable (void) +/* Skip over an unknown or uninteresting variable-length marker */ +{ + unsigned int length; + + /* Get the marker parameter length count */ + length = read_2_bytes(); + /* Length includes itself, so must be at least 2 */ + if (length < 2) + ERREXIT("Erroneous JPEG marker length"); + length -= 2; + /* Skip over the remaining bytes */ + while (length > 0) { + (void) read_1_byte(); + length--; + } +} + + +/* + * Process a COM marker. + * We want to print out the marker contents as legible text; + * we must guard against non-text junk and varying newline representations. + */ + +static void +process_COM (void) +{ + unsigned int length; + int ch; + int lastch = 0; + + /* Get the marker parameter length count */ + length = read_2_bytes(); + /* Length includes itself, so must be at least 2 */ + if (length < 2) + ERREXIT("Erroneous JPEG marker length"); + length -= 2; + + while (length > 0) { + ch = read_1_byte(); + /* Emit the character in a readable form. + * Nonprintables are converted to \nnn form, + * while \ is converted to \\. + * Newlines in CR, CR/LF, or LF form will be printed as one newline. + */ + if (ch == '\r') { + printf("\n"); + } else if (ch == '\n') { + if (lastch != '\r') + printf("\n"); + } else if (ch == '\\') { + printf("\\\\"); + } else if (isprint(ch)) { + putc(ch, stdout); + } else { + printf("\\%03o", ch); + } + lastch = ch; + length--; + } + printf("\n"); +} + + +/* + * Process a SOFn marker. + * This code is only needed if you want to know the image dimensions... + */ + +static void +process_SOFn (int marker) +{ + unsigned int length; + unsigned int image_height, image_width; + int data_precision, num_components; + const char * process; + int ci; + + length = read_2_bytes(); /* usual parameter length count */ + + data_precision = read_1_byte(); + image_height = read_2_bytes(); + image_width = read_2_bytes(); + num_components = read_1_byte(); + + switch (marker) { + case M_SOF0: process = "Baseline"; break; + case M_SOF1: process = "Extended sequential"; break; + case M_SOF2: process = "Progressive"; break; + case M_SOF3: process = "Lossless"; break; + case M_SOF5: process = "Differential sequential"; break; + case M_SOF6: process = "Differential progressive"; break; + case M_SOF7: process = "Differential lossless"; break; + case M_SOF9: process = "Extended sequential, arithmetic coding"; break; + case M_SOF10: process = "Progressive, arithmetic coding"; break; + case M_SOF11: process = "Lossless, arithmetic coding"; break; + case M_SOF13: process = "Differential sequential, arithmetic coding"; break; + case M_SOF14: process = "Differential progressive, arithmetic coding"; break; + case M_SOF15: process = "Differential lossless, arithmetic coding"; break; + default: process = "Unknown"; break; + } + + printf("JPEG image is %uw * %uh, %d color components, %d bits per sample\n", + image_width, image_height, num_components, data_precision); + printf("JPEG process: %s\n", process); + + if (length != (unsigned int) (8 + num_components * 3)) + ERREXIT("Bogus SOF marker length"); + + for (ci = 0; ci < num_components; ci++) { + (void) read_1_byte(); /* Component ID code */ + (void) read_1_byte(); /* H, V sampling factors */ + (void) read_1_byte(); /* Quantization table number */ + } +} + + +/* + * Parse the marker stream until SOS or EOI is seen; + * display any COM markers. + * While the companion program wrjpgcom will always insert COM markers before + * SOFn, other implementations might not, so we scan to SOS before stopping. + * If we were only interested in the image dimensions, we would stop at SOFn. + * (Conversely, if we only cared about COM markers, there would be no need + * for special code to handle SOFn; we could treat it like other markers.) + */ + +static int +scan_JPEG_header (int verbose) +{ + int marker; + + /* Expect SOI at start of file */ + if (first_marker() != M_SOI) + ERREXIT("Expected SOI marker first"); + + /* Scan miscellaneous markers until we reach SOS. */ + for (;;) { + marker = next_marker(); + switch (marker) { + /* Note that marker codes 0xC4, 0xC8, 0xCC are not, and must not be, + * treated as SOFn. C4 in particular is actually DHT. + */ + case M_SOF0: /* Baseline */ + case M_SOF1: /* Extended sequential, Huffman */ + case M_SOF2: /* Progressive, Huffman */ + case M_SOF3: /* Lossless, Huffman */ + case M_SOF5: /* Differential sequential, Huffman */ + case M_SOF6: /* Differential progressive, Huffman */ + case M_SOF7: /* Differential lossless, Huffman */ + case M_SOF9: /* Extended sequential, arithmetic */ + case M_SOF10: /* Progressive, arithmetic */ + case M_SOF11: /* Lossless, arithmetic */ + case M_SOF13: /* Differential sequential, arithmetic */ + case M_SOF14: /* Differential progressive, arithmetic */ + case M_SOF15: /* Differential lossless, arithmetic */ + if (verbose) + process_SOFn(marker); + else + skip_variable(); + break; + + case M_SOS: /* stop before hitting compressed data */ + return marker; + + case M_EOI: /* in case it's a tables-only JPEG stream */ + return marker; + + case M_COM: + process_COM(); + break; + + case M_APP12: + /* Some digital camera makers put useful textual information into + * APP12 markers, so we print those out too when in -verbose mode. + */ + if (verbose) { + printf("APP12 contains:\n"); + process_COM(); + } else + skip_variable(); + break; + + default: /* Anything else just gets skipped */ + skip_variable(); /* we assume it has a parameter count... */ + break; + } + } /* end loop */ +} + + +/* Command line parsing code */ + +static const char * progname; /* program name for error messages */ + + +static void +usage (void) +/* complain about bad command line */ +{ + fprintf(stderr, "rdjpgcom displays any textual comments in a JPEG file.\n"); + + fprintf(stderr, "Usage: %s [switches] [inputfile]\n", progname); + + fprintf(stderr, "Switches (names may be abbreviated):\n"); + fprintf(stderr, " -verbose Also display dimensions of JPEG image\n"); + + exit(EXIT_FAILURE); +} + + +static int +keymatch (char * arg, const char * keyword, int minchars) +/* Case-insensitive matching of (possibly abbreviated) keyword switches. */ +/* keyword is the constant keyword (must be lower case already), */ +/* minchars is length of minimum legal abbreviation. */ +{ + register int ca, ck; + register int nmatched = 0; + + while ((ca = *arg++) != '\0') { + if ((ck = *keyword++) == '\0') + return 0; /* arg longer than keyword, no good */ + if (isupper(ca)) /* force arg to lcase (assume ck is already) */ + ca = tolower(ca); + if (ca != ck) + return 0; /* no good */ + nmatched++; /* count matched characters */ + } + /* reached end of argument; fail if it's too short for unique abbrev */ + if (nmatched < minchars) + return 0; + return 1; /* A-OK */ +} + + +/* + * The main program. + */ + +int +main (int argc, char **argv) +{ + int argn; + char * arg; + int verbose = 0; + + /* On Mac, fetch a command line. */ +#ifdef USE_CCOMMAND + argc = ccommand(&argv); +#endif + + progname = argv[0]; + if (progname == NULL || progname[0] == 0) + progname = "rdjpgcom"; /* in case C library doesn't provide it */ + + /* Parse switches, if any */ + for (argn = 1; argn < argc; argn++) { + arg = argv[argn]; + if (arg[0] != '-') + break; /* not switch, must be file name */ + arg++; /* advance over '-' */ + if (keymatch(arg, "verbose", 1)) { + verbose++; + } else + usage(); + } + + /* Open the input file. */ + /* Unix style: expect zero or one file name */ + if (argn < argc-1) { + fprintf(stderr, "%s: only one input file\n", progname); + usage(); + } + if (argn < argc) { + if ((infile = fopen(argv[argn], READ_BINARY)) == NULL) { + fprintf(stderr, "%s: can't open %s\n", progname, argv[argn]); + exit(EXIT_FAILURE); + } + } else { + /* default input file is stdin */ +#ifdef USE_SETMODE /* need to hack file mode? */ + setmode(fileno(stdin), O_BINARY); +#endif +#ifdef USE_FDOPEN /* need to re-open in binary mode? */ + if ((infile = fdopen(fileno(stdin), READ_BINARY)) == NULL) { + fprintf(stderr, "%s: can't open stdin\n", progname); + exit(EXIT_FAILURE); + } +#else + infile = stdin; +#endif + } + + /* Scan the JPEG headers. */ + (void) scan_JPEG_header(verbose); + + /* All done. */ + exit(EXIT_SUCCESS); + return 0; /* suppress no-return-value warnings */ +} diff --git a/rdrle.c b/rdrle.c new file mode 100644 index 00000000..542bc374 --- /dev/null +++ b/rdrle.c @@ -0,0 +1,387 @@ +/* + * rdrle.c + * + * Copyright (C) 1991-1996, Thomas G. Lane. + * This file is part of the Independent JPEG Group's software. + * For conditions of distribution and use, see the accompanying README file. + * + * This file contains routines to read input images in Utah RLE format. + * The Utah Raster Toolkit library is required (version 3.1 or later). + * + * These routines may need modification for non-Unix environments or + * specialized applications. As they stand, they assume input from + * an ordinary stdio stream. They further assume that reading begins + * at the start of the file; start_input may need work if the + * user interface has already read some data (e.g., to determine that + * the file is indeed RLE format). + * + * Based on code contributed by Mike Lijewski, + * with updates from Robert Hutchinson. + */ + +#include "cdjpeg.h" /* Common decls for cjpeg/djpeg applications */ + +#ifdef RLE_SUPPORTED + +/* rle.h is provided by the Utah Raster Toolkit. */ + +#include + +/* + * We assume that JSAMPLE has the same representation as rle_pixel, + * to wit, "unsigned char". Hence we can't cope with 12- or 16-bit samples. + */ + +#if BITS_IN_JSAMPLE != 8 + Sorry, this code only copes with 8-bit JSAMPLEs. /* deliberate syntax err */ +#endif + +/* + * We support the following types of RLE files: + * + * GRAYSCALE - 8 bits, no colormap + * MAPPEDGRAY - 8 bits, 1 channel colomap + * PSEUDOCOLOR - 8 bits, 3 channel colormap + * TRUECOLOR - 24 bits, 3 channel colormap + * DIRECTCOLOR - 24 bits, no colormap + * + * For now, we ignore any alpha channel in the image. + */ + +typedef enum + { GRAYSCALE, MAPPEDGRAY, PSEUDOCOLOR, TRUECOLOR, DIRECTCOLOR } rle_kind; + + +/* + * Since RLE stores scanlines bottom-to-top, we have to invert the image + * to conform to JPEG's top-to-bottom order. To do this, we read the + * incoming image into a virtual array on the first get_pixel_rows call, + * then fetch the required row from the virtual array on subsequent calls. + */ + +typedef struct _rle_source_struct * rle_source_ptr; + +typedef struct _rle_source_struct { + struct cjpeg_source_struct pub; /* public fields */ + + rle_kind visual; /* actual type of input file */ + jvirt_sarray_ptr image; /* virtual array to hold the image */ + JDIMENSION row; /* current row # in the virtual array */ + rle_hdr header; /* Input file information */ + rle_pixel** rle_row; /* holds a row returned by rle_getrow() */ + +} rle_source_struct; + + +/* + * Read the file header; return image size and component count. + */ + +METHODDEF(void) +start_input_rle (j_compress_ptr cinfo, cjpeg_source_ptr sinfo) +{ + rle_source_ptr source = (rle_source_ptr) sinfo; + JDIMENSION width, height; +#ifdef PROGRESS_REPORT + cd_progress_ptr progress = (cd_progress_ptr) cinfo->progress; +#endif + + /* Use RLE library routine to get the header info */ + source->header = *rle_hdr_init(NULL); + source->header.rle_file = source->pub.input_file; + switch (rle_get_setup(&(source->header))) { + case RLE_SUCCESS: + /* A-OK */ + break; + case RLE_NOT_RLE: + ERREXIT(cinfo, JERR_RLE_NOT); + break; + case RLE_NO_SPACE: + ERREXIT(cinfo, JERR_RLE_MEM); + break; + case RLE_EMPTY: + ERREXIT(cinfo, JERR_RLE_EMPTY); + break; + case RLE_EOF: + ERREXIT(cinfo, JERR_RLE_EOF); + break; + default: + ERREXIT(cinfo, JERR_RLE_BADERROR); + break; + } + + /* Figure out what we have, set private vars and return values accordingly */ + + width = source->header.xmax - source->header.xmin + 1; + height = source->header.ymax - source->header.ymin + 1; + source->header.xmin = 0; /* realign horizontally */ + source->header.xmax = width-1; + + cinfo->image_width = width; + cinfo->image_height = height; + cinfo->data_precision = 8; /* we can only handle 8 bit data */ + + if (source->header.ncolors == 1 && source->header.ncmap == 0) { + source->visual = GRAYSCALE; + TRACEMS2(cinfo, 1, JTRC_RLE_GRAY, width, height); + } else if (source->header.ncolors == 1 && source->header.ncmap == 1) { + source->visual = MAPPEDGRAY; + TRACEMS3(cinfo, 1, JTRC_RLE_MAPGRAY, width, height, + 1 << source->header.cmaplen); + } else if (source->header.ncolors == 1 && source->header.ncmap == 3) { + source->visual = PSEUDOCOLOR; + TRACEMS3(cinfo, 1, JTRC_RLE_MAPPED, width, height, + 1 << source->header.cmaplen); + } else if (source->header.ncolors == 3 && source->header.ncmap == 3) { + source->visual = TRUECOLOR; + TRACEMS3(cinfo, 1, JTRC_RLE_FULLMAP, width, height, + 1 << source->header.cmaplen); + } else if (source->header.ncolors == 3 && source->header.ncmap == 0) { + source->visual = DIRECTCOLOR; + TRACEMS2(cinfo, 1, JTRC_RLE, width, height); + } else + ERREXIT(cinfo, JERR_RLE_UNSUPPORTED); + + if (source->visual == GRAYSCALE || source->visual == MAPPEDGRAY) { + cinfo->in_color_space = JCS_GRAYSCALE; + cinfo->input_components = 1; + } else { + cinfo->in_color_space = JCS_RGB; + cinfo->input_components = 3; + } + + /* + * A place to hold each scanline while it's converted. + * (GRAYSCALE scanlines don't need converting) + */ + if (source->visual != GRAYSCALE) { + source->rle_row = (rle_pixel**) (*cinfo->mem->alloc_sarray) + ((j_common_ptr) cinfo, JPOOL_IMAGE, + (JDIMENSION) width, (JDIMENSION) cinfo->input_components); + } + + /* request a virtual array to hold the image */ + source->image = (*cinfo->mem->request_virt_sarray) + ((j_common_ptr) cinfo, JPOOL_IMAGE, FALSE, + (JDIMENSION) (width * source->header.ncolors), + (JDIMENSION) height, (JDIMENSION) 1); + +#ifdef PROGRESS_REPORT + if (progress != NULL) { + /* count file input as separate pass */ + progress->total_extra_passes++; + } +#endif + + source->pub.buffer_height = 1; +} + + +/* + * Read one row of pixels. + * Called only after load_image has read the image into the virtual array. + * Used for GRAYSCALE, MAPPEDGRAY, TRUECOLOR, and DIRECTCOLOR images. + */ + +METHODDEF(JDIMENSION) +get_rle_row (j_compress_ptr cinfo, cjpeg_source_ptr sinfo) +{ + rle_source_ptr source = (rle_source_ptr) sinfo; + + source->row--; + source->pub.buffer = (*cinfo->mem->access_virt_sarray) + ((j_common_ptr) cinfo, source->image, source->row, (JDIMENSION) 1, FALSE); + + return 1; +} + +/* + * Read one row of pixels. + * Called only after load_image has read the image into the virtual array. + * Used for PSEUDOCOLOR images. + */ + +METHODDEF(JDIMENSION) +get_pseudocolor_row (j_compress_ptr cinfo, cjpeg_source_ptr sinfo) +{ + rle_source_ptr source = (rle_source_ptr) sinfo; + JSAMPROW src_row, dest_row; + JDIMENSION col; + rle_map *colormap; + int val; + + colormap = source->header.cmap; + dest_row = source->pub.buffer[0]; + source->row--; + src_row = * (*cinfo->mem->access_virt_sarray) + ((j_common_ptr) cinfo, source->image, source->row, (JDIMENSION) 1, FALSE); + + for (col = cinfo->image_width; col > 0; col--) { + val = GETJSAMPLE(*src_row++); + *dest_row++ = (JSAMPLE) (colormap[val ] >> 8); + *dest_row++ = (JSAMPLE) (colormap[val + 256] >> 8); + *dest_row++ = (JSAMPLE) (colormap[val + 512] >> 8); + } + + return 1; +} + + +/* + * Load the image into a virtual array. We have to do this because RLE + * files start at the lower left while the JPEG standard has them starting + * in the upper left. This is called the first time we want to get a row + * of input. What we do is load the RLE data into the array and then call + * the appropriate routine to read one row from the array. Before returning, + * we set source->pub.get_pixel_rows so that subsequent calls go straight to + * the appropriate row-reading routine. + */ + +METHODDEF(JDIMENSION) +load_image (j_compress_ptr cinfo, cjpeg_source_ptr sinfo) +{ + rle_source_ptr source = (rle_source_ptr) sinfo; + JDIMENSION row, col; + JSAMPROW scanline, red_ptr, green_ptr, blue_ptr; + rle_pixel **rle_row; + rle_map *colormap; + char channel; +#ifdef PROGRESS_REPORT + cd_progress_ptr progress = (cd_progress_ptr) cinfo->progress; +#endif + + colormap = source->header.cmap; + rle_row = source->rle_row; + + /* Read the RLE data into our virtual array. + * We assume here that (a) rle_pixel is represented the same as JSAMPLE, + * and (b) we are not on a machine where FAR pointers differ from regular. + */ + RLE_CLR_BIT(source->header, RLE_ALPHA); /* don't read the alpha channel */ + +#ifdef PROGRESS_REPORT + if (progress != NULL) { + progress->pub.pass_limit = cinfo->image_height; + progress->pub.pass_counter = 0; + (*progress->pub.progress_monitor) ((j_common_ptr) cinfo); + } +#endif + + switch (source->visual) { + + case GRAYSCALE: + case PSEUDOCOLOR: + for (row = 0; row < cinfo->image_height; row++) { + rle_row = (rle_pixel **) (*cinfo->mem->access_virt_sarray) + ((j_common_ptr) cinfo, source->image, row, (JDIMENSION) 1, TRUE); + rle_getrow(&source->header, rle_row); +#ifdef PROGRESS_REPORT + if (progress != NULL) { + progress->pub.pass_counter++; + (*progress->pub.progress_monitor) ((j_common_ptr) cinfo); + } +#endif + } + break; + + case MAPPEDGRAY: + case TRUECOLOR: + for (row = 0; row < cinfo->image_height; row++) { + scanline = * (*cinfo->mem->access_virt_sarray) + ((j_common_ptr) cinfo, source->image, row, (JDIMENSION) 1, TRUE); + rle_row = source->rle_row; + rle_getrow(&source->header, rle_row); + + for (col = 0; col < cinfo->image_width; col++) { + for (channel = 0; channel < source->header.ncolors; channel++) { + *scanline++ = (JSAMPLE) + (colormap[GETJSAMPLE(rle_row[channel][col]) + 256 * channel] >> 8); + } + } + +#ifdef PROGRESS_REPORT + if (progress != NULL) { + progress->pub.pass_counter++; + (*progress->pub.progress_monitor) ((j_common_ptr) cinfo); + } +#endif + } + break; + + case DIRECTCOLOR: + for (row = 0; row < cinfo->image_height; row++) { + scanline = * (*cinfo->mem->access_virt_sarray) + ((j_common_ptr) cinfo, source->image, row, (JDIMENSION) 1, TRUE); + rle_getrow(&source->header, rle_row); + + red_ptr = rle_row[0]; + green_ptr = rle_row[1]; + blue_ptr = rle_row[2]; + + for (col = cinfo->image_width; col > 0; col--) { + *scanline++ = *red_ptr++; + *scanline++ = *green_ptr++; + *scanline++ = *blue_ptr++; + } + +#ifdef PROGRESS_REPORT + if (progress != NULL) { + progress->pub.pass_counter++; + (*progress->pub.progress_monitor) ((j_common_ptr) cinfo); + } +#endif + } + } + +#ifdef PROGRESS_REPORT + if (progress != NULL) + progress->completed_extra_passes++; +#endif + + /* Set up to call proper row-extraction routine in future */ + if (source->visual == PSEUDOCOLOR) { + source->pub.buffer = source->rle_row; + source->pub.get_pixel_rows = get_pseudocolor_row; + } else { + source->pub.get_pixel_rows = get_rle_row; + } + source->row = cinfo->image_height; + + /* And fetch the topmost (bottommost) row */ + return (*source->pub.get_pixel_rows) (cinfo, sinfo); +} + + +/* + * Finish up at the end of the file. + */ + +METHODDEF(void) +finish_input_rle (j_compress_ptr cinfo, cjpeg_source_ptr sinfo) +{ + /* no work */ +} + + +/* + * The module selection routine for RLE format input. + */ + +GLOBAL(cjpeg_source_ptr) +jinit_read_rle (j_compress_ptr cinfo) +{ + rle_source_ptr source; + + /* Create module interface object */ + source = (rle_source_ptr) + (*cinfo->mem->alloc_small) ((j_common_ptr) cinfo, JPOOL_IMAGE, + SIZEOF(rle_source_struct)); + /* Fill in method ptrs */ + source->pub.start_input = start_input_rle; + source->pub.finish_input = finish_input_rle; + source->pub.get_pixel_rows = load_image; + + return (cjpeg_source_ptr) source; +} + +#endif /* RLE_SUPPORTED */ diff --git a/structure.doc b/structure.doc new file mode 100644 index 00000000..51c9def7 --- /dev/null +++ b/structure.doc @@ -0,0 +1,948 @@ +IJG JPEG LIBRARY: SYSTEM ARCHITECTURE + +Copyright (C) 1991-1995, Thomas G. Lane. +This file is part of the Independent JPEG Group's software. +For conditions of distribution and use, see the accompanying README file. + + +This file provides an overview of the architecture of the IJG JPEG software; +that is, the functions of the various modules in the system and the interfaces +between modules. For more precise details about any data structure or calling +convention, see the include files and comments in the source code. + +We assume that the reader is already somewhat familiar with the JPEG standard. +The README file includes references for learning about JPEG. The file +libjpeg.doc describes the library from the viewpoint of an application +programmer using the library; it's best to read that file before this one. +Also, the file coderules.doc describes the coding style conventions we use. + +In this document, JPEG-specific terminology follows the JPEG standard: + A "component" means a color channel, e.g., Red or Luminance. + A "sample" is a single component value (i.e., one number in the image data). + A "coefficient" is a frequency coefficient (a DCT transform output number). + A "block" is an 8x8 group of samples or coefficients. + An "MCU" (minimum coded unit) is an interleaved set of blocks of size + determined by the sampling factors, or a single block in a + noninterleaved scan. +We do not use the terms "pixel" and "sample" interchangeably. When we say +pixel, we mean an element of the full-size image, while a sample is an element +of the downsampled image. Thus the number of samples may vary across +components while the number of pixels does not. (This terminology is not used +rigorously throughout the code, but it is used in places where confusion would +otherwise result.) + + +*** System features *** + +The IJG distribution contains two parts: + * A subroutine library for JPEG compression and decompression. + * cjpeg/djpeg, two sample applications that use the library to transform + JFIF JPEG files to and from several other image formats. +cjpeg/djpeg are of no great intellectual complexity: they merely add a simple +command-line user interface and I/O routines for several uncompressed image +formats. This document concentrates on the library itself. + +We desire the library to be capable of supporting all JPEG baseline, extended +sequential, and progressive DCT processes. Hierarchical processes are not +supported. + +The library does not support the lossless (spatial) JPEG process. Lossless +JPEG shares little or no code with lossy JPEG, and would normally be used +without the extensive pre- and post-processing provided by this library. +We feel that lossless JPEG is better handled by a separate library. + +Within these limits, any set of compression parameters allowed by the JPEG +spec should be readable for decompression. (We can be more restrictive about +what formats we can generate.) Although the system design allows for all +parameter values, some uncommon settings are not yet implemented and may +never be; nonintegral sampling ratios are the prime example. Furthermore, +we treat 8-bit vs. 12-bit data precision as a compile-time switch, not a +run-time option, because most machines can store 8-bit pixels much more +compactly than 12-bit. + +For legal reasons, JPEG arithmetic coding is not currently supported, but +extending the library to include it would be straightforward. + +By itself, the library handles only interchange JPEG datastreams --- in +particular the widely used JFIF file format. The library can be used by +surrounding code to process interchange or abbreviated JPEG datastreams that +are embedded in more complex file formats. (For example, libtiff uses this +library to implement JPEG compression within the TIFF file format.) + +The library includes a substantial amount of code that is not covered by the +JPEG standard but is necessary for typical applications of JPEG. These +functions preprocess the image before JPEG compression or postprocess it after +decompression. They include colorspace conversion, downsampling/upsampling, +and color quantization. This code can be omitted if not needed. + +A wide range of quality vs. speed tradeoffs are possible in JPEG processing, +and even more so in decompression postprocessing. The decompression library +provides multiple implementations that cover most of the useful tradeoffs, +ranging from very-high-quality down to fast-preview operation. On the +compression side we have generally not provided low-quality choices, since +compression is normally less time-critical. It should be understood that the +low-quality modes may not meet the JPEG standard's accuracy requirements; +nonetheless, they are useful for viewers. + + +*** Portability issues *** + +Portability is an essential requirement for the library. The key portability +issues that show up at the level of system architecture are: + +1. Memory usage. We want the code to be able to run on PC-class machines +with limited memory. Images should therefore be processed sequentially (in +strips), to avoid holding the whole image in memory at once. Where a +full-image buffer is necessary, we should be able to use either virtual memory +or temporary files. + +2. Near/far pointer distinction. To run efficiently on 80x86 machines, the +code should distinguish "small" objects (kept in near data space) from +"large" ones (kept in far data space). This is an annoying restriction, but +fortunately it does not impact code quality for less brain-damaged machines, +and the source code clutter turns out to be minimal with sufficient use of +pointer typedefs. + +3. Data precision. We assume that "char" is at least 8 bits, "short" and +"int" at least 16, "long" at least 32. The code will work fine with larger +data sizes, although memory may be used inefficiently in some cases. However, +the JPEG compressed datastream must ultimately appear on external storage as a +sequence of 8-bit bytes if it is to conform to the standard. This may pose a +problem on machines where char is wider than 8 bits. The library represents +compressed data as an array of values of typedef JOCTET. If no data type +exactly 8 bits wide is available, custom data source and data destination +modules must be written to unpack and pack the chosen JOCTET datatype into +8-bit external representation. + + +*** System overview *** + +The compressor and decompressor are each divided into two main sections: +the JPEG compressor or decompressor proper, and the preprocessing or +postprocessing functions. The interface between these two sections is the +image data that the official JPEG spec regards as its input or output: this +data is in the colorspace to be used for compression, and it is downsampled +to the sampling factors to be used. The preprocessing and postprocessing +steps are responsible for converting a normal image representation to or from +this form. (Those few applications that want to deal with YCbCr downsampled +data can skip the preprocessing or postprocessing step.) + +Looking more closely, the compressor library contains the following main +elements: + + Preprocessing: + * Color space conversion (e.g., RGB to YCbCr). + * Edge expansion and downsampling. Optionally, this step can do simple + smoothing --- this is often helpful for low-quality source data. + JPEG proper: + * MCU assembly, DCT, quantization. + * Entropy coding (sequential or progressive, Huffman or arithmetic). + +In addition to these modules we need overall control, marker generation, +and support code (memory management & error handling). There is also a +module responsible for physically writing the output data --- typically +this is just an interface to fwrite(), but some applications may need to +do something else with the data. + +The decompressor library contains the following main elements: + + JPEG proper: + * Entropy decoding (sequential or progressive, Huffman or arithmetic). + * Dequantization, inverse DCT, MCU disassembly. + Postprocessing: + * Upsampling. Optionally, this step may be able to do more general + rescaling of the image. + * Color space conversion (e.g., YCbCr to RGB). This step may also + provide gamma adjustment [ currently it does not ]. + * Optional color quantization (e.g., reduction to 256 colors). + * Optional color precision reduction (e.g., 24-bit to 15-bit color). + [This feature is not currently implemented.] + +We also need overall control, marker parsing, and a data source module. +The support code (memory management & error handling) can be shared with +the compression half of the library. + +There may be several implementations of each of these elements, particularly +in the decompressor, where a wide range of speed/quality tradeoffs is very +useful. It must be understood that some of the best speedups involve +merging adjacent steps in the pipeline. For example, upsampling, color space +conversion, and color quantization might all be done at once when using a +low-quality ordered-dither technique. The system architecture is designed to +allow such merging where appropriate. + + +Note: it is convenient to regard edge expansion (padding to block boundaries) +as a preprocessing/postprocessing function, even though the JPEG spec includes +it in compression/decompression. We do this because downsampling/upsampling +can be simplified a little if they work on padded data: it's not necessary to +have special cases at the right and bottom edges. Therefore the interface +buffer is always an integral number of blocks wide and high, and we expect +compression preprocessing to pad the source data properly. Padding will occur +only to the next block (8-sample) boundary. In an interleaved-scan situation, +additional dummy blocks may be used to fill out MCUs, but the MCU assembly and +disassembly logic will create or discard these blocks internally. (This is +advantageous for speed reasons, since we avoid DCTing the dummy blocks. +It also permits a small reduction in file size, because the compressor can +choose dummy block contents so as to minimize their size in compressed form. +Finally, it makes the interface buffer specification independent of whether +the file is actually interleaved or not.) Applications that wish to deal +directly with the downsampled data must provide similar buffering and padding +for odd-sized images. + + +*** Poor man's object-oriented programming *** + +It should be clear by now that we have a lot of quasi-independent processing +steps, many of which have several possible behaviors. To avoid cluttering the +code with lots of switch statements, we use a simple form of object-style +programming to separate out the different possibilities. + +For example, two different color quantization algorithms could be implemented +as two separate modules that present the same external interface; at runtime, +the calling code will access the proper module indirectly through an "object". + +We can get the limited features we need while staying within portable C. +The basic tool is a function pointer. An "object" is just a struct +containing one or more function pointer fields, each of which corresponds to +a method name in real object-oriented languages. During initialization we +fill in the function pointers with references to whichever module we have +determined we need to use in this run. Then invocation of the module is done +by indirecting through a function pointer; on most machines this is no more +expensive than a switch statement, which would be the only other way of +making the required run-time choice. The really significant benefit, of +course, is keeping the source code clean and well structured. + +We can also arrange to have private storage that varies between different +implementations of the same kind of object. We do this by making all the +module-specific object structs be separately allocated entities, which will +be accessed via pointers in the master compression or decompression struct. +The "public" fields or methods for a given kind of object are specified by +a commonly known struct. But a module's initialization code can allocate +a larger struct that contains the common struct as its first member, plus +additional private fields. With appropriate pointer casting, the module's +internal functions can access these private fields. (For a simple example, +see jdatadst.c, which implements the external interface specified by struct +jpeg_destination_mgr, but adds extra fields.) + +(Of course this would all be a lot easier if we were using C++, but we are +not yet prepared to assume that everyone has a C++ compiler.) + +An important benefit of this scheme is that it is easy to provide multiple +versions of any method, each tuned to a particular case. While a lot of +precalculation might be done to select an optimal implementation of a method, +the cost per invocation is constant. For example, the upsampling step might +have a "generic" method, plus one or more "hardwired" methods for the most +popular sampling factors; the hardwired methods would be faster because they'd +use straight-line code instead of for-loops. The cost to determine which +method to use is paid only once, at startup, and the selection criteria are +hidden from the callers of the method. + +This plan differs a little bit from usual object-oriented structures, in that +only one instance of each object class will exist during execution. The +reason for having the class structure is that on different runs we may create +different instances (choose to execute different modules). You can think of +the term "method" as denoting the common interface presented by a particular +set of interchangeable functions, and "object" as denoting a group of related +methods, or the total shared interface behavior of a group of modules. + + +*** Overall control structure *** + +We previously mentioned the need for overall control logic in the compression +and decompression libraries. In IJG implementations prior to v5, overall +control was mostly provided by "pipeline control" modules, which proved to be +large, unwieldy, and hard to understand. To improve the situation, the +control logic has been subdivided into multiple modules. The control modules +consist of: + +1. Master control for module selection and initialization. This has two +responsibilities: + + 1A. Startup initialization at the beginning of image processing. + The individual processing modules to be used in this run are selected + and given initialization calls. + + 1B. Per-pass control. This determines how many passes will be performed + and calls each active processing module to configure itself + appropriately at the beginning of each pass. End-of-pass processing, + where necessary, is also invoked from the master control module. + + Method selection is partially distributed, in that a particular processing + module may contain several possible implementations of a particular method, + which it will select among when given its initialization call. The master + control code need only be concerned with decisions that affect more than + one module. + +2. Data buffering control. A separate control module exists for each + inter-processing-step data buffer. This module is responsible for + invoking the processing steps that write or read that data buffer. + +Each buffer controller sees the world as follows: + +input data => processing step A => buffer => processing step B => output data + | | | + ------------------ controller ------------------ + +The controller knows the dataflow requirements of steps A and B: how much data +they want to accept in one chunk and how much they output in one chunk. Its +function is to manage its buffer and call A and B at the proper times. + +A data buffer control module may itself be viewed as a processing step by a +higher-level control module; thus the control modules form a binary tree with +elementary processing steps at the leaves of the tree. + +The control modules are objects. A considerable amount of flexibility can +be had by replacing implementations of a control module. For example: +* Merging of adjacent steps in the pipeline is done by replacing a control + module and its pair of processing-step modules with a single processing- + step module. (Hence the possible merges are determined by the tree of + control modules.) +* In some processing modes, a given interstep buffer need only be a "strip" + buffer large enough to accommodate the desired data chunk sizes. In other + modes, a full-image buffer is needed and several passes are required. + The control module determines which kind of buffer is used and manipulates + virtual array buffers as needed. One or both processing steps may be + unaware of the multi-pass behavior. + +In theory, we might be able to make all of the data buffer controllers +interchangeable and provide just one set of implementations for all. In +practice, each one contains considerable special-case processing for its +particular job. The buffer controller concept should be regarded as an +overall system structuring principle, not as a complete description of the +task performed by any one controller. + + +*** Compression object structure *** + +Here is a sketch of the logical structure of the JPEG compression library: + + |-- Colorspace conversion + |-- Preprocessing controller --| + | |-- Downsampling +Main controller --| + | |-- Forward DCT, quantize + |-- Coefficient controller --| + |-- Entropy encoding + +This sketch also describes the flow of control (subroutine calls) during +typical image data processing. Each of the components shown in the diagram is +an "object" which may have several different implementations available. One +or more source code files contain the actual implementation(s) of each object. + +The objects shown above are: + +* Main controller: buffer controller for the subsampled-data buffer, which + holds the preprocessed input data. This controller invokes preprocessing to + fill the subsampled-data buffer, and JPEG compression to empty it. There is + usually no need for a full-image buffer here; a strip buffer is adequate. + +* Preprocessing controller: buffer controller for the downsampling input data + buffer, which lies between colorspace conversion and downsampling. Note + that a unified conversion/downsampling module would probably replace this + controller entirely. + +* Colorspace conversion: converts application image data into the desired + JPEG color space; also changes the data from pixel-interleaved layout to + separate component planes. Processes one pixel row at a time. + +* Downsampling: performs reduction of chroma components as required. + Optionally may perform pixel-level smoothing as well. Processes a "row + group" at a time, where a row group is defined as Vmax pixel rows of each + component before downsampling, and Vk sample rows afterwards (remember Vk + differs across components). Some downsampling or smoothing algorithms may + require context rows above and below the current row group; the + preprocessing controller is responsible for supplying these rows via proper + buffering. The downsampler is responsible for edge expansion at the right + edge (i.e., extending each sample row to a multiple of 8 samples); but the + preprocessing controller is responsible for vertical edge expansion (i.e., + duplicating the bottom sample row as needed to make a multiple of 8 rows). + +* Coefficient controller: buffer controller for the DCT-coefficient data. + This controller handles MCU assembly, including insertion of dummy DCT + blocks when needed at the right or bottom edge. When performing + Huffman-code optimization or emitting a multiscan JPEG file, this + controller is responsible for buffering the full image. The equivalent of + one fully interleaved MCU row of subsampled data is processed per call, + even when the JPEG file is noninterleaved. + +* Forward DCT and quantization: Perform DCT, quantize, and emit coefficients. + Works on one or more DCT blocks at a time. (Note: the coefficients are now + emitted in normal array order, which the entropy encoder is expected to + convert to zigzag order as necessary. Prior versions of the IJG code did + the conversion to zigzag order within the quantization step.) + +* Entropy encoding: Perform Huffman or arithmetic entropy coding and emit the + coded data to the data destination module. Works on one MCU per call. + For progressive JPEG, the same DCT blocks are fed to the entropy coder + during each pass, and the coder must emit the appropriate subset of + coefficients. + +In addition to the above objects, the compression library includes these +objects: + +* Master control: determines the number of passes required, controls overall + and per-pass initialization of the other modules. + +* Marker writing: generates JPEG markers (except for RSTn, which is emitted + by the entropy encoder when needed). + +* Data destination manager: writes the output JPEG datastream to its final + destination (e.g., a file). The destination manager supplied with the + library knows how to write to a stdio stream; for other behaviors, the + surrounding application may provide its own destination manager. + +* Memory manager: allocates and releases memory, controls virtual arrays + (with backing store management, where required). + +* Error handler: performs formatting and output of error and trace messages; + determines handling of nonfatal errors. The surrounding application may + override some or all of this object's methods to change error handling. + +* Progress monitor: supports output of "percent-done" progress reports. + This object represents an optional callback to the surrounding application: + if wanted, it must be supplied by the application. + +The error handler, destination manager, and progress monitor objects are +defined as separate objects in order to simplify application-specific +customization of the JPEG library. A surrounding application may override +individual methods or supply its own all-new implementation of one of these +objects. The object interfaces for these objects are therefore treated as +part of the application interface of the library, whereas the other objects +are internal to the library. + +The error handler and memory manager are shared by JPEG compression and +decompression; the progress monitor, if used, may be shared as well. + + +*** Decompression object structure *** + +Here is a sketch of the logical structure of the JPEG decompression library: + + |-- Entropy decoding + |-- Coefficient controller --| + | |-- Dequantize, Inverse DCT +Main controller --| + | |-- Upsampling + |-- Postprocessing controller --| |-- Colorspace conversion + |-- Color quantization + |-- Color precision reduction + +As before, this diagram also represents typical control flow. The objects +shown are: + +* Main controller: buffer controller for the subsampled-data buffer, which + holds the output of JPEG decompression proper. This controller's primary + task is to feed the postprocessing procedure. Some upsampling algorithms + may require context rows above and below the current row group; when this + is true, the main controller is responsible for managing its buffer so as + to make context rows available. In the current design, the main buffer is + always a strip buffer; a full-image buffer is never required. + +* Coefficient controller: buffer controller for the DCT-coefficient data. + This controller handles MCU disassembly, including deletion of any dummy + DCT blocks at the right or bottom edge. When reading a multiscan JPEG + file, this controller is responsible for buffering the full image. + (Buffering DCT coefficients, rather than samples, is necessary to support + progressive JPEG.) The equivalent of one fully interleaved MCU row of + subsampled data is processed per call, even when the source JPEG file is + noninterleaved. + +* Entropy decoding: Read coded data from the data source module and perform + Huffman or arithmetic entropy decoding. Works on one MCU per call. + For progressive JPEG decoding, the coefficient controller supplies the prior + coefficients of each MCU (initially all zeroes), which the entropy decoder + modifies in each scan. + +* Dequantization and inverse DCT: like it says. Note that the coefficients + buffered by the coefficient controller have NOT been dequantized; we + merge dequantization and inverse DCT into a single step for speed reasons. + When scaled-down output is asked for, simplified DCT algorithms may be used + that emit only 1x1, 2x2, or 4x4 samples per DCT block, not the full 8x8. + Works on one DCT block at a time. + +* Postprocessing controller: buffer controller for the color quantization + input buffer, when quantization is in use. (Without quantization, this + controller just calls the upsampler.) For two-pass quantization, this + controller is responsible for buffering the full-image data. + +* Upsampling: restores chroma components to full size. (May support more + general output rescaling, too. Note that if undersized DCT outputs have + been emitted by the DCT module, this module must adjust so that properly + sized outputs are created.) Works on one row group at a time. This module + also calls the color conversion module, so its top level is effectively a + buffer controller for the upsampling->color conversion buffer. However, in + all but the highest-quality operating modes, upsampling and color + conversion are likely to be merged into a single step. + +* Colorspace conversion: convert from JPEG color space to output color space, + and change data layout from separate component planes to pixel-interleaved. + Works on one pixel row at a time. + +* Color quantization: reduce the data to colormapped form, using either an + externally specified colormap or an internally generated one. This module + is not used for full-color output. Works on one pixel row at a time; may + require two passes to generate a color map. Note that the output will + always be a single component representing colormap indexes. In the current + design, the output values are JSAMPLEs, so an 8-bit compilation cannot + quantize to more than 256 colors. This is unlikely to be a problem in + practice. + +* Color reduction: this module handles color precision reduction, e.g., + generating 15-bit color (5 bits/primary) from JPEG's 24-bit output. + Not quite clear yet how this should be handled... should we merge it with + colorspace conversion??? + +Note that some high-speed operating modes might condense the entire +postprocessing sequence to a single module (upsample, color convert, and +quantize in one step). + +In addition to the above objects, the decompression library includes these +objects: + +* Master control: determines the number of passes required, controls overall + and per-pass initialization of the other modules. This is subdivided into + input and output control: jdinput.c controls only input-side processing, + while jdmaster.c handles overall initialization and output-side control. + +* Marker reading: decodes JPEG markers (except for RSTn). + +* Data source manager: supplies the input JPEG datastream. The source + manager supplied with the library knows how to read from a stdio stream; + for other behaviors, the surrounding application may provide its own source + manager. + +* Memory manager: same as for compression library. + +* Error handler: same as for compression library. + +* Progress monitor: same as for compression library. + +As with compression, the data source manager, error handler, and progress +monitor are candidates for replacement by a surrounding application. + + +*** Decompression input and output separation *** + +To support efficient incremental display of progressive JPEG files, the +decompressor is divided into two sections that can run independently: + +1. Data input includes marker parsing, entropy decoding, and input into the + coefficient controller's DCT coefficient buffer. Note that this + processing is relatively cheap and fast. + +2. Data output reads from the DCT coefficient buffer and performs the IDCT + and all postprocessing steps. + +For a progressive JPEG file, the data input processing is allowed to get +arbitrarily far ahead of the data output processing. (This occurs only +if the application calls jpeg_consume_input(); otherwise input and output +run in lockstep, since the input section is called only when the output +section needs more data.) In this way the application can avoid making +extra display passes when data is arriving faster than the display pass +can run. Furthermore, it is possible to abort an output pass without +losing anything, since the coefficient buffer is read-only as far as the +output section is concerned. See libjpeg.doc for more detail. + +A full-image coefficient array is only created if the JPEG file has multiple +scans (or if the application specifies buffered-image mode anyway). When +reading a single-scan file, the coefficient controller normally creates only +a one-MCU buffer, so input and output processing must run in lockstep in this +case. jpeg_consume_input() is effectively a no-op in this situation. + +The main impact of dividing the decompressor in this fashion is that we must +be very careful with shared variables in the cinfo data structure. Each +variable that can change during the course of decompression must be +classified as belonging to data input or data output, and each section must +look only at its own variables. For example, the data output section may not +depend on any of the variables that describe the current scan in the JPEG +file, because these may change as the data input section advances into a new +scan. + +The progress monitor is (somewhat arbitrarily) defined to treat input of the +file as one pass when buffered-image mode is not used, and to ignore data +input work completely when buffered-image mode is used. Note that the +library has no reliable way to predict the number of passes when dealing +with a progressive JPEG file, nor can it predict the number of output passes +in buffered-image mode. So the work estimate is inherently bogus anyway. + +No comparable division is currently made in the compression library, because +there isn't any real need for it. + + +*** Data formats *** + +Arrays of pixel sample values use the following data structure: + + typedef something JSAMPLE; a pixel component value, 0..MAXJSAMPLE + typedef JSAMPLE *JSAMPROW; ptr to a row of samples + typedef JSAMPROW *JSAMPARRAY; ptr to a list of rows + typedef JSAMPARRAY *JSAMPIMAGE; ptr to a list of color-component arrays + +The basic element type JSAMPLE will typically be one of unsigned char, +(signed) char, or short. Short will be used if samples wider than 8 bits are +to be supported (this is a compile-time option). Otherwise, unsigned char is +used if possible. If the compiler only supports signed chars, then it is +necessary to mask off the value when reading. Thus, all reads of JSAMPLE +values must be coded as "GETJSAMPLE(value)", where the macro will be defined +as "((value) & 0xFF)" on signed-char machines and "((int) (value))" elsewhere. + +With these conventions, JSAMPLE values can be assumed to be >= 0. This helps +simplify correct rounding during downsampling, etc. The JPEG standard's +specification that sample values run from -128..127 is accommodated by +subtracting 128 just as the sample value is copied into the source array for +the DCT step (this will be an array of signed ints). Similarly, during +decompression the output of the IDCT step will be immediately shifted back to +0..255. (NB: different values are required when 12-bit samples are in use. +The code is written in terms of MAXJSAMPLE and CENTERJSAMPLE, which will be +defined as 255 and 128 respectively in an 8-bit implementation, and as 4095 +and 2048 in a 12-bit implementation.) + +We use a pointer per row, rather than a two-dimensional JSAMPLE array. This +choice costs only a small amount of memory and has several benefits: +* Code using the data structure doesn't need to know the allocated width of + the rows. This simplifies edge expansion/compression, since we can work + in an array that's wider than the logical picture width. +* Indexing doesn't require multiplication; this is a performance win on many + machines. +* Arrays with more than 64K total elements can be supported even on machines + where malloc() cannot allocate chunks larger than 64K. +* The rows forming a component array may be allocated at different times + without extra copying. This trick allows some speedups in smoothing steps + that need access to the previous and next rows. + +Note that each color component is stored in a separate array; we don't use the +traditional layout in which the components of a pixel are stored together. +This simplifies coding of modules that work on each component independently, +because they don't need to know how many components there are. Furthermore, +we can read or write each component to a temporary file independently, which +is helpful when dealing with noninterleaved JPEG files. + +In general, a specific sample value is accessed by code such as + GETJSAMPLE(image[colorcomponent][row][col]) +where col is measured from the image left edge, but row is measured from the +first sample row currently in memory. Either of the first two indexings can +be precomputed by copying the relevant pointer. + + +Since most image-processing applications prefer to work on images in which +the components of a pixel are stored together, the data passed to or from the +surrounding application uses the traditional convention: a single pixel is +represented by N consecutive JSAMPLE values, and an image row is an array of +(# of color components)*(image width) JSAMPLEs. One or more rows of data can +be represented by a pointer of type JSAMPARRAY in this scheme. This scheme is +converted to component-wise storage inside the JPEG library. (Applications +that want to skip JPEG preprocessing or postprocessing will have to contend +with component-wise storage.) + + +Arrays of DCT-coefficient values use the following data structure: + + typedef short JCOEF; a 16-bit signed integer + typedef JCOEF JBLOCK[DCTSIZE2]; an 8x8 block of coefficients + typedef JBLOCK *JBLOCKROW; ptr to one horizontal row of 8x8 blocks + typedef JBLOCKROW *JBLOCKARRAY; ptr to a list of such rows + typedef JBLOCKARRAY *JBLOCKIMAGE; ptr to a list of color component arrays + +The underlying type is at least a 16-bit signed integer; while "short" is big +enough on all machines of interest, on some machines it is preferable to use +"int" for speed reasons, despite the storage cost. Coefficients are grouped +into 8x8 blocks (but we always use #defines DCTSIZE and DCTSIZE2 rather than +"8" and "64"). + +The contents of a coefficient block may be in either "natural" or zigzagged +order, and may be true values or divided by the quantization coefficients, +depending on where the block is in the processing pipeline. In the current +library, coefficient blocks are kept in natural order everywhere; the entropy +codecs zigzag or dezigzag the data as it is written or read. The blocks +contain quantized coefficients everywhere outside the DCT/IDCT subsystems. +(This latter decision may need to be revisited to support variable +quantization a la JPEG Part 3.) + +Notice that the allocation unit is now a row of 8x8 blocks, corresponding to +eight rows of samples. Otherwise the structure is much the same as for +samples, and for the same reasons. + +On machines where malloc() can't handle a request bigger than 64Kb, this data +structure limits us to rows of less than 512 JBLOCKs, or a picture width of +4000+ pixels. This seems an acceptable restriction. + + +On 80x86 machines, the bottom-level pointer types (JSAMPROW and JBLOCKROW) +must be declared as "far" pointers, but the upper levels can be "near" +(implying that the pointer lists are allocated in the DS segment). +We use a #define symbol FAR, which expands to the "far" keyword when +compiling on 80x86 machines and to nothing elsewhere. + + +*** Suspendable processing *** + +In some applications it is desirable to use the JPEG library as an +incremental, memory-to-memory filter. In this situation the data source or +destination may be a limited-size buffer, and we can't rely on being able to +empty or refill the buffer at arbitrary times. Instead the application would +like to have control return from the library at buffer overflow/underrun, and +then resume compression or decompression at a later time. + +This scenario is supported for simple cases. (For anything more complex, we +recommend that the application "bite the bullet" and develop real multitasking +capability.) The libjpeg.doc file goes into more detail about the usage and +limitations of this capability; here we address the implications for library +structure. + +The essence of the problem is that the entropy codec (coder or decoder) must +be prepared to stop at arbitrary times. In turn, the controllers that call +the entropy codec must be able to stop before having produced or consumed all +the data that they normally would handle in one call. That part is reasonably +straightforward: we make the controller call interfaces include "progress +counters" which indicate the number of data chunks successfully processed, and +we require callers to test the counter rather than just assume all of the data +was processed. + +Rather than trying to restart at an arbitrary point, the current Huffman +codecs are designed to restart at the beginning of the current MCU after a +suspension due to buffer overflow/underrun. At the start of each call, the +codec's internal state is loaded from permanent storage (in the JPEG object +structures) into local variables. On successful completion of the MCU, the +permanent state is updated. (This copying is not very expensive, and may even +lead to *improved* performance if the local variables can be registerized.) +If a suspension occurs, the codec simply returns without updating the state, +thus effectively reverting to the start of the MCU. Note that this implies +leaving some data unprocessed in the source/destination buffer (ie, the +compressed partial MCU). The data source/destination module interfaces are +specified so as to make this possible. This also implies that the data buffer +must be large enough to hold a worst-case compressed MCU; a couple thousand +bytes should be enough. + +In a successive-approximation AC refinement scan, the progressive Huffman +decoder has to be able to undo assignments of newly nonzero coefficients if it +suspends before the MCU is complete, since decoding requires distinguishing +previously-zero and previously-nonzero coefficients. This is a bit tedious +but probably won't have much effect on performance. Other variants of Huffman +decoding need not worry about this, since they will just store the same values +again if forced to repeat the MCU. + +This approach would probably not work for an arithmetic codec, since its +modifiable state is quite large and couldn't be copied cheaply. Instead it +would have to suspend and resume exactly at the point of the buffer end. + +The JPEG marker reader is designed to cope with suspension at an arbitrary +point. It does so by backing up to the start of the marker parameter segment, +so the data buffer must be big enough to hold the largest marker of interest. +Again, a couple KB should be adequate. (A special "skip" convention is used +to bypass COM and APPn markers, so these can be larger than the buffer size +without causing problems; otherwise a 64K buffer would be needed in the worst +case.) + +The JPEG marker writer currently does *not* cope with suspension. I feel that +this is not necessary; it is much easier simply to require the application to +ensure there is enough buffer space before starting. (An empty 2K buffer is +more than sufficient for the header markers; and ensuring there are a dozen or +two bytes available before calling jpeg_finish_compress() will suffice for the +trailer.) This would not work for writing multi-scan JPEG files, but +we simply do not intend to support that capability with suspension. + + +*** Memory manager services *** + +The JPEG library's memory manager controls allocation and deallocation of +memory, and it manages large "virtual" data arrays on machines where the +operating system does not provide virtual memory. Note that the same +memory manager serves both compression and decompression operations. + +In all cases, allocated objects are tied to a particular compression or +decompression master record, and they will be released when that master +record is destroyed. + +The memory manager does not provide explicit deallocation of objects. +Instead, objects are created in "pools" of free storage, and a whole pool +can be freed at once. This approach helps prevent storage-leak bugs, and +it speeds up operations whenever malloc/free are slow (as they often are). +The pools can be regarded as lifetime identifiers for objects. Two +pools/lifetimes are defined: + * JPOOL_PERMANENT lasts until master record is destroyed + * JPOOL_IMAGE lasts until done with image (JPEG datastream) +Permanent lifetime is used for parameters and tables that should be carried +across from one datastream to another; this includes all application-visible +parameters. Image lifetime is used for everything else. (A third lifetime, +JPOOL_PASS = one processing pass, was originally planned. However it was +dropped as not being worthwhile. The actual usage patterns are such that the +peak memory usage would be about the same anyway; and having per-pass storage +substantially complicates the virtual memory allocation rules --- see below.) + +The memory manager deals with three kinds of object: +1. "Small" objects. Typically these require no more than 10K-20K total. +2. "Large" objects. These may require tens to hundreds of K depending on + image size. Semantically they behave the same as small objects, but we + distinguish them for two reasons: + * On MS-DOS machines, large objects are referenced by FAR pointers, + small objects by NEAR pointers. + * Pool allocation heuristics may differ for large and small objects. + Note that individual "large" objects cannot exceed the size allowed by + type size_t, which may be 64K or less on some machines. +3. "Virtual" objects. These are large 2-D arrays of JSAMPLEs or JBLOCKs + (typically large enough for the entire image being processed). The + memory manager provides stripwise access to these arrays. On machines + without virtual memory, the rest of the array may be swapped out to a + temporary file. + +(Note: JSAMPARRAY and JBLOCKARRAY data structures are a combination of large +objects for the data proper and small objects for the row pointers. For +convenience and speed, the memory manager provides single routines to create +these structures. Similarly, virtual arrays include a small control block +and a JSAMPARRAY or JBLOCKARRAY working buffer, all created with one call.) + +In the present implementation, virtual arrays are only permitted to have image +lifespan. (Permanent lifespan would not be reasonable, and pass lifespan is +not very useful since a virtual array's raison d'etre is to store data for +multiple passes through the image.) We also expect that only "small" objects +will be given permanent lifespan, though this restriction is not required by +the memory manager. + +In a non-virtual-memory machine, some performance benefit can be gained by +making the in-memory buffers for virtual arrays be as large as possible. +(For small images, the buffers might fit entirely in memory, so blind +swapping would be very wasteful.) The memory manager will adjust the height +of the buffers to fit within a prespecified maximum memory usage. In order +to do this in a reasonably optimal fashion, the manager needs to allocate all +of the virtual arrays at once. Therefore, there isn't a one-step allocation +routine for virtual arrays; instead, there is a "request" routine that simply +allocates the control block, and a "realize" routine (called just once) that +determines space allocation and creates all of the actual buffers. The +realize routine must allow for space occupied by non-virtual large objects. +(We don't bother to factor in the space needed for small objects, on the +grounds that it isn't worth the trouble.) + +To support all this, we establish the following protocol for doing business +with the memory manager: + 1. Modules must request virtual arrays (which may have only image lifespan) + during the initial setup phase, i.e., in their jinit_xxx routines. + 2. All "large" objects (including JSAMPARRAYs and JBLOCKARRAYs) must also be + allocated during initial setup. + 3. realize_virt_arrays will be called at the completion of initial setup. + The above conventions ensure that sufficient information is available + for it to choose a good size for virtual array buffers. +Small objects of any lifespan may be allocated at any time. We expect that +the total space used for small objects will be small enough to be negligible +in the realize_virt_arrays computation. + +In a virtual-memory machine, we simply pretend that the available space is +infinite, thus causing realize_virt_arrays to decide that it can allocate all +the virtual arrays as full-size in-memory buffers. The overhead of the +virtual-array access protocol is very small when no swapping occurs. + +A virtual array can be specified to be "pre-zeroed"; when this flag is set, +never-yet-written sections of the array are set to zero before being made +available to the caller. If this flag is not set, never-written sections +of the array contain garbage. (This feature exists primarily because the +equivalent logic would otherwise be needed in jdcoefct.c for progressive +JPEG mode; we may as well make it available for possible other uses.) + +The first write pass on a virtual array is required to occur in top-to-bottom +order; read passes, as well as any write passes after the first one, may +access the array in any order. This restriction exists partly to simplify +the virtual array control logic, and partly because some file systems may not +support seeking beyond the current end-of-file in a temporary file. The main +implication of this restriction is that rearrangement of rows (such as +converting top-to-bottom data order to bottom-to-top) must be handled while +reading data out of the virtual array, not while putting it in. + + +*** Memory manager internal structure *** + +To isolate system dependencies as much as possible, we have broken the +memory manager into two parts. There is a reasonably system-independent +"front end" (jmemmgr.c) and a "back end" that contains only the code +likely to change across systems. All of the memory management methods +outlined above are implemented by the front end. The back end provides +the following routines for use by the front end (none of these routines +are known to the rest of the JPEG code): + +jpeg_mem_init, jpeg_mem_term system-dependent initialization/shutdown + +jpeg_get_small, jpeg_free_small interface to malloc and free library routines + (or their equivalents) + +jpeg_get_large, jpeg_free_large interface to FAR malloc/free in MSDOS machines; + else usually the same as + jpeg_get_small/jpeg_free_small + +jpeg_mem_available estimate available memory + +jpeg_open_backing_store create a backing-store object + +read_backing_store, manipulate a backing-store object +write_backing_store, +close_backing_store + +On some systems there will be more than one type of backing-store object +(specifically, in MS-DOS a backing store file might be an area of extended +memory as well as a disk file). jpeg_open_backing_store is responsible for +choosing how to implement a given object. The read/write/close routines +are method pointers in the structure that describes a given object; this +lets them be different for different object types. + +It may be necessary to ensure that backing store objects are explicitly +released upon abnormal program termination. For example, MS-DOS won't free +extended memory by itself. To support this, we will expect the main program +or surrounding application to arrange to call self_destruct (typically via +jpeg_destroy) upon abnormal termination. This may require a SIGINT signal +handler or equivalent. We don't want to have the back end module install its +own signal handler, because that would pre-empt the surrounding application's +ability to control signal handling. + +The IJG distribution includes several memory manager back end implementations. +Usually the same back end should be suitable for all applications on a given +system, but it is possible for an application to supply its own back end at +need. + + +*** Implications of DNL marker *** + +Some JPEG files may use a DNL marker to postpone definition of the image +height (this would be useful for a fax-like scanner's output, for instance). +In these files the SOF marker claims the image height is 0, and you only +find out the true image height at the end of the first scan. + +We could read these files as follows: +1. Upon seeing zero image height, replace it by 65535 (the maximum allowed). +2. When the DNL is found, update the image height in the global image + descriptor. +This implies that control modules must avoid making copies of the image +height, and must re-test for termination after each MCU row. This would +be easy enough to do. + +In cases where image-size data structures are allocated, this approach will +result in very inefficient use of virtual memory or much-larger-than-necessary +temporary files. This seems acceptable for something that probably won't be a +mainstream usage. People might have to forgo use of memory-hogging options +(such as two-pass color quantization or noninterleaved JPEG files) if they +want efficient conversion of such files. (One could improve efficiency by +demanding a user-supplied upper bound for the height, less than 65536; in most +cases it could be much less.) + +The standard also permits the SOF marker to overestimate the image height, +with a DNL to give the true, smaller height at the end of the first scan. +This would solve the space problems if the overestimate wasn't too great. +However, it implies that you don't even know whether DNL will be used. + +This leads to a couple of very serious objections: +1. Testing for a DNL marker must occur in the inner loop of the decompressor's + Huffman decoder; this implies a speed penalty whether the feature is used + or not. +2. There is no way to hide the last-minute change in image height from an + application using the decoder. Thus *every* application using the IJG + library would suffer a complexity penalty whether it cared about DNL or + not. +We currently do not support DNL because of these problems. + +A different approach is to insist that DNL-using files be preprocessed by a +separate program that reads ahead to the DNL, then goes back and fixes the SOF +marker. This is a much simpler solution and is probably far more efficient. +Even if one wants piped input, buffering the first scan of the JPEG file needs +a lot smaller temp file than is implied by the maximum-height method. For +this approach we'd simply treat DNL as a no-op in the decompressor (at most, +check that it matches the SOF image height). + +We will not worry about making the compressor capable of outputting DNL. +Something similar to the first scheme above could be applied if anyone ever +wants to make that work. diff --git a/testimg.bmp b/testimg.bmp new file mode 100644 index 00000000..d67e025d Binary files /dev/null and b/testimg.bmp differ diff --git a/testimg.jpg b/testimg.jpg new file mode 100644 index 00000000..76d223fa Binary files /dev/null and b/testimg.jpg differ diff --git a/testimg.ppm b/testimg.ppm new file mode 100644 index 00000000..b3916846 --- /dev/null +++ b/testimg.ppm @@ -0,0 +1,4 @@ +P6 +227 149 +255 +0/-0/-10.21/51.51.62/62/83/83/:3-:3-:3-:3-:3-:3-:2/91.91.80-80-91.91.:2/80-80-80-80-80-80-80-80-6.+6.+6.+5-*5-*4,)4,)4,)4,)4,)4,)4,)4,)4,)4,)4,).+$/,%/,%0-&1.'2/(30)30)63,63,74-85.85.96/:70;7.?;0B<0D>2F@4IA4JB5KC6KC6MD5MD5OC3NB2OC3OC3PD4RE5R?1Y?2b@4nB5}E6‹H8™G9£F7¯G:¸F;¾F8ÅG;ÇG>ÊG?ËH@ÒDBæGKíCLëDKíDKíDGïBFñ>Aô=Aø;A÷:@ô:?ð×?<Í@9¹>.µ@.µ@.´?-´?-´?-°?-¯@-­@,ªA,¦A-¢B,Ÿ@*›A)˜@*—@,’?-’?/’?/‘>.‘>,=+’<+’<+”?+”?+”=*”=*”=*•>+–?,—?1”@5•>5—=2Ÿ?1©B3³D3¼D4¿D4¹?0µA2¬F8žH;‡H9oA2T8*C2(=6095495473271160050-50-72/72/72/61.61-50,50,40-/0+.0-//-//-0/-0/-2.-3--3--4+,4*+4(*5)+=.1E69P::/A;/C=1E?3H@5IA6JB5JB5LC4LC4MA3MA3MA1NB2OC3PD4JA0OB2WD3cF6qH6}H6ŠI7”G5žG6¦E5¬E6´F9¸H<»I>¾I?ÆG@ÚHIãDIäFGèEHëEEïBDó@C÷>Cù:?ø9>ô:?ïÑB<ÆA8¸?.´A.³@-³@-±@.°?-¯@-®A-«@.§@-¦A-¡A+A,›@+—A*—@,’?-’?/‘>.‘>.‘>,=+=+=+’?-‘>,“=,“=,“=,”>-•@,–@/”@5–>4š>3£=1®@3ºA6¾C4ÁC7¼@4µC8©G<™I>I63;55:4493383072/61.61.62/62/62/51.52-41,21,12-.0+,1-.0-.0-//-//-0/-2.-2.-3--3*+2)*4*+9/0A57M9:_@;rG@‚ME‹PJ”WRŸdh¡o{˜tŽŽ}¡„°„»{„¿nu¬Z[‘PH{NCnPDjPEePGdTLd[Xiomzƒ†‹”˜™™žššŸ˜™œ“Ž‘†}qik][\NVSLXSWYQ\YQ\/.,/.,0/-10.40-40-51.51.72.72.72.72.92,92,92,91.91.80.7/-7/-7/-7/-80.91/80.80.80.80.80.80.80.80.6.,5-+5-+5-+4,*4,*4,*4,*5-+5-+5-+5-+5-+5-+5-+5-+1.'1.'2/(30)30)41*41*52+63,63,63,74-85.96/96/;7.=9.@:.B<0D>2G?4H@5H@3H@3I@1I@1K?1K?1K?/L@0MA1NB2KB1OB2VC2aD4nE3yD2…D2B0•>-<,¤=.­?2²B6·E:¼G=ÄE>ÖDEàAFâDEæCFêDDðCEôADø?Dú;@ù:?õ;@ð=@æ@@ÜA=ÐA;Å@7·>-³@-³@-²?,°?-°?-®?,­@,ª?-§@-¥@,¡A+A,š?*—A*–?+’?-‘>.‘>.‘>.=+=+=+=+‘>,‘>,’<+’<+“=,“=,”?+•?.•A6—?5š>3¤>2¯A4»B7¿D5ÁC7ÀD8¸F;¬J?™I>€H;gA4P:-B5,?74=77<66:4494183072/72/62/62/62/51.52-41,21,12-.0+,1-.0-.0-//-//-0/-2.-40/4..5,-3*+4*+8./>24I56Y:5k@9{F>…JDPK—\`šht’nˆŠy~­}‚¹u~¹fm¤TU‹MExLAlMAgPEeQHeOG_NK\\Zgqty…‰Š‡ŒˆŠˆ‡†‰~xzlfhZZ[MVSLZUY[S^[S^---.../.,0/-10.21/40-40-51.51.61-61-61-61-81+80-50,50-4/,4/,4/,4/,50-50-61.61.61.61.61.61.61.61.3.+3.+3.+2-*2-*2-*1,)1,)4/,4/,4/,4/,4/,4/,4/,4/,30+30+30+41,41,52-52-52-52-52-63.74/850850961:5/<8/?8.@9/B;1E=2E=2F>3F>3G=1G=1H<0I=1I=/J>0L@2JA2GF4JG6NG4WH5aG6jG4tE3|C0>-‰=-‘>,™@0¢E4ªI9®M=¹J?ÈIBÑFCÖGCÜFEãEBëCCñAA÷?Aú<>ù;=ó<>ì@>áD?ÔF<ÄD7»C3¯@-®A-®A-®A-­?.­?.«@.ª?-§@/¥@.¡@-A,›@-˜@,•@+”?+?,?.?.>->->-Ž=,Ž=,>->-Ž=,Ž=,>-?.‘@/‘@/”B4–@1ž>0©?2¶@4ÀA8Å@7ÄA9ÁF>·JC¦NDMDuI>[C7F<2=90@93A75?74>63<41;3083/83/43/43/34/23.23.12-02-02-,2.,2.-2.-2./1./1.00.00.32032040/2.-2,,3--711?42N:1\>3iE7sI=xNB€WU„cl„l„€tœ|y®w}»ovº`e©QP”JD‚J?yL?mRClQEkLBdGA[NK`\^jjmttzzw}yy€yt{sioc]cWVYNSTL]XT_WU_WU------.-+/.,0/-10.3/,40-3/,3/,4/+4/+4/+4/+6/)6.+4/+4/,3.+3.+3.+3.+4/,4/,50-50-50-50-50-50-50-50-3.+3.+2-*2-*2-*1,)1,)1,)4/,4/,4/,4/,4/,4/,4/,4/,41,41,41,41,41,52-52-52-52-52-63.63.74/850961:5/:6-=6,?8.@9/B:/C;0C;0C;0D:.D:.F:.G;/H<.I=/J>0I@1IH6KH7OH5WH5`F5hE2rC1y@-<+‡;+<*—>. C2©H8®M=¹J?ÈIBÑFCÕFBÛEDáC@éAAî>>ô<>ù;=ø:<ó<>ì@>àC>ÒD:ÂB5¸@0¯@-­@,­@,­@,¬>-¬>-ª?-ª?-¦?.¤?- ?,œ@+š?,—?+”?*“>*?,?.>->->-Ž=,Ž=,Ž=,Ž=,Ž=,Ž=,Ž=,Ž=,>-?.?.”B4—A2Ÿ?1ª@3·A5ÁB9ÆA8ÄA9¾C;µHA¥MCŽKBrF;W?3C9/:6-@93A75?74>63=52<4194083/43/43/34/23.23.12-02-02-,2.,2.-2.-2./1./1.00.00.3203205103/.2,,2,,5//;0.K7.W9.c?1kA5oE9vMK}\e€h€}q™zw¬u{¹kr¶_d¨TS—MG…LA{NAoPAjMAgJ@bGA[HEZIKWMPW]cc`fbbib_f^Z`TU[OUXMWXP^YU`XV`XV,,,,,,------/.,0/-10.10.2.+2.+2.+2.+3.*3.*3.*3.+3.+3--2,,1++1++2,,3--3--3--3--3--3--3--3--3--3--2,,2,,2,,2,,1++1++1++0**3--3--3--3--3--3--3--3--41,41,41,41,41,41,41,41,41,52-52-63.74/85085094095,<5-=6.>7/@70A81A8/A8/C9/C9/E8/F90G;/H<0J>2I?3IG8IG8MG7SG7YF7`E4hC3oA1v>/|=,…=.@0–C3ŸG9¥L<®L?¼L@ÃJAÉJAÏHB×G?àB?è@=ì<<ó=<ð<;ì>=äB=ÕG=ÆG8µD2«@,¨A.¨A.§@-§@-§@/¦?.¦?.¦?.£?/ ?.@/˜?-–?,”?+?*?,?+>->->-Œ=.Œ=.Œ=.‹<-‹>.Š=-Š0‹?1@0‘D2—A0 @0­A5»B9ÂC<ÃB=¾C>³C?ªKG™SK„RKfK@LB8:=239/>93A83?82>71:5/94.74/74/43.43.24/13./4..3-.3-.3--3/-3/-3/-3/.3/.3/02/02/11/22022011/0/-/.,10.50-A62H70O;2W?5[B;dJKq]h|nˆ}v¢{{·w{ÂntÂbh¶Y[¨OM–ICƒLBvL?jH=eF?aGC^ECY?CO;?H?IKCMLGRNGRLGQHHRILVKSYM^ZNaYLaYL++++++,,,---/.,/.,0/-0/-1-*1-*1-*1-*2-)2-)2-)2-*2-*2,,1++1++1++1++2,,2,,1++1++1++1++1++1++1++1++2,,2,,2,,1++1++1++0**0**3--3--3--3--3--3--3--3--41,41,41,30+30+30+30+30+41,41,52-63.74/74/85094084+;4,<5-=6.?6/?6/?6-?6-B8.B8.E8/E8/G;/H<0J>2I?3GE6GE6KE5PD4VC4^C2e@0l>.u=.z;*‚:+‰<,‘>.šB4 G7©G:¸H<ÀG>ÆG>ÍF@ÖF>áC@éA>î>>ñ;:ï;:ë=<ãA<ÓE;ÄE6²A/¨=)§@-§@-§@-¦?,¦?.¦?.¥>-¥>-¢>. ?.œ?.˜?-–?,“>*?*>+?+>->-Œ=,Œ=.Œ=.‹<-‹<-Š=-Š=-‰;.‰;.‰=/Š>0Š>0Œ?/‘D2˜B1¡A1®B6¼C:ÂC<ÄC>¿D?·GC°QM ZRŒZSoTITJ@AD9:@6>93@72>71=60:5/94.74/63.43.43.24/13./4..3-.3-.3--3/-3/-3/-3/.3/.3/02/02/00.11/22011/0/-/.,0/-4/,<1-B1*H4+Q9/V=6aGHs_j‚tŽˆ­„„À~‚ÉtzÈkq¿ce²USœJD„I?sI`FB]DBX>BN;?H9CE>HGCNJFQKGQHHRILVKSYM^ZNaYLaYL*+-*+-+,.+,.---...0/-0/-/.,/.,1-*1-*1-*1-*1-*1-*1-,0,+0,+/+*/+*0,+0,+1-,/+*/+*/+*/+*/+*/+*/+*/+*1-,1-,1-,0,+0,+/+*/+*/+*1-,1-,1-,1-,1-,1-,1-,1-,3/,3/,3/,3/,3/,3/,3/,3/,40-40-51.62/62/73084194172.:2/;4.<5/>50>50>5.>5.B71B71E80E80G:2I<4J=4K>5I@7J@7M@7Q@8V@5\?7`>4g<3n<3t:/{9-‚8-Š;.”=3›B4¡C7­I:±I<¹K>ÀKAÊL@ÔKCÝHAäGBã?=ã?=ÝB=ÖF=ÊH;ºG5¨C/Ÿ@*¢C/¢C/¢A0¢A0¢A0¡@/¡@0¡@0@/@/™@0—@/”>-‘>,?+?+>->-Œ?/‹>.‹>.Š=-‰=/‰=/‡=0†2…?3ˆ@2D4–C3ŸC6«C:¶E=¼FB¹HB±JE«VO¤aX–l`„m_kcVTXJDNC@J?::0=9.<8/;7.85,74+44,44,34.34.25.14-13.02-.3-.3-.3/.3/.3/.3/02/02/02/02/.0-/1.22022000.//-//-1/06,47,4=11D97J?;VLMmer}˜Œ¶‹Æ„‰Íz€ÊrxÂfmµTY›EG€AAgC@_@@Z?AX>DT=EP:HK:HHCSPHYQO_URbWR`SQ_RR`SX`Q]\Ga[Ca[C,-/,-/,-/,-/------.-+.-+/.,/.,1-*0,)0,)0,)/+(/+(/+*/+*/+*/+*/+*/+*/+*0,+/+*/+*/+*/+*/+*/+*/+*/+*/+*/+*/+*0,+0,+1-,1-,2.-1-,1-,1-,1-,1-,1-,1-,1-,0,)1-*2.+3/,3/,3/,3/,3/,3/,3/,3/,3/,40-51.62/83061-91.:3-;4.=4/>50>5.>5.?4.?4.B5-C6.D7/F91G:1H;2G>5I?6L?6P?7T>3X;3\:0a6-k90s9.{9-ƒ9.‹2¦B3ªB5³E8»F<ÇI=ÑH@ÛF?âE@åA?çCAáFA×G>ÇE8¶C1§B.¡B,¡B. A- ?. ?.Ÿ>-Ÿ>- ?/ ?/š=,š=,–=-•>-“=,=+Œ>*Œ>*‹<+‹<+Š=-‰<,‰<,‰<,‡;-‡;-‡=0†2‡?3ˆ@4‡A5ŠB4‘E5—D4¢F9±I@¹H@ºD@¸GAµNI°[T«h_žthvh{sfhl^T^SGQFLLBJF;B>5<8/85,74+44,33+34.34.14-14-02-/1,,1+,1+-2.-2.-2.-2./1./1./1./1.02/02/11/11/11/11/11/2014*2:/7?33@53G<8ZPQvn{Š†¡’‘»”–Ï•Ùƒ‰ÓtzÄho·^c¥Y[”KKqGDc??Y=?V=CSAITIWZSaaaqnm~vv†|p€ulzmguh^l_W_P]\Gb\Dc]E,-/,-/,-/,-/,-/,-/------/.,.-+.-+.-+/+(/+(/+(/+*,+),*+,*+,*+-+,-+,-+,-+,-+,-+,-+,-+,-+,-+,-+,-+,-+,-+,-+,.,-.,-.,-/-./-./-./-./-./-./-./-./-./-.0,+0,+1-,2.-3/.3/.2.-2.-2.-2.-2.-2.-3/.40/51071161.91/:2/;30=31>42>50=4/?40?40A4.B5/C60E82G:4H;5K<7K<7N<8P=9P=7S;7W:4[82d93k92t80~:1‡:2=2”=3˜>3œB7¡C9£F7¬G;²K<¼L@ÆL?ÍJ@ÑKBÔKCÒLCÊKB½I<®D6 C1›C/œD0›C/œA/›@.›@.›@.›?0›?0—>.—>.”>/‘>.>->-‹>.‹>.Š=+Š=+ˆ<,ˆ<,†=.…<-„<.„<.ƒ=1ƒ=1‚>3‚>3‚?6„A8…B:‡C:H<”F: H>ªLD±KG®KF©RK¤[Rn^–{hŽ†q†pumhveYgVNYKIP@HJa]@,-/,-/,-/,-/,-/,-/------.-+.-+.-+-,*/+(.*'.*'.*),+),*+,*+,*++)*+)*+)*+)*-+,-+,-+,-+,-+,-+,-+,-+,,*+,*+-+,-+,-+,.,-.,-.,-.,-.,-.,-/-./-./-./-./-.0,+0,+1-,2.-2.-2.-2.-1-,1-,1-,1-,1-,2.-3/.40/60061.91/:2/;30=31=31=4/=4/?40?40A4.A4.C60D71F93G:4I:5J;6M;7O<8O<6R:6U82Y60b71i70r6.|8/†91;0“<2–<1š@5ž@6ŸB3¦A5¬E6¶F:ÁG:ÉF<ÏI@ÓJBÑKBÉJA»G:­C5ŸB0šB.›C/šB.›@.š?-š?-š?-š>/›?0–=-–=-“=.‘>.>-Œ=,Š=-Š=-‰<*‰<*ˆ<,‡;+…<-…<-ƒ;-ƒ;-‚<0‚<0=2‚>3‚?6„A8†C;ˆD;“K?–H< H>ªLD±KG°MH­VOªaX¦wgŸ„q—zŒ‘{‹wr€ocq`XcULSCLN@GI;CE7?A49;.46+/1&01)01)/0*/0*./*./*0/-0/-//-//-//-//-//-//-//-//-00.00.00.00.00.00.00.1/26+;7*;6/6:65FF>^_Yw{zŠŽ™•«’˜º–„½}Š´{Š±z«|Ž¤zŠ—v…Œn€‚l~~k€{nƒzxƒ‚šŒŠ£©–¦’ˆŠ—‚{Žzj{i\hTVY>]Y<_[>+/2+/2+/2+/2-.0-.0......-------,*-,*,+),+),+),+),*++)*+)*+)*+)**()*()*(),*+,*+,*+,*+,*+,*+,*+,*+,*+,*+,*+,*+,*+-+,-+,-+,-+,.,-.,-.,-.,-/-./-./-./+*0,+1-,1-,1-,1-,0,+0,+0,+0,+0,+0,+1-,2.-3/.5//711:12;31<42=32=32=31=31>31>31@2/@2/A30C52D71E82D95E:6E<7F=8G<8I;8L:6O73W:6^93h91q;1|<2ƒ=1‹?2@3•A7—@7•A6˜A7›E6£G:ªJ:²J=¹M@¾NBÀND¼LA°H=¦D7A4˜@2—B.—B.–@/•?.–?.–?.—>0—>0”<.”<.‘>0=/Œ=.Š=-‰=-ˆ<,‡;+‡;+‡;+‡;+„;,„:-<-€:.€<1€<3}=3?6€A:‚C<„E>†F=‘MD“I@˜IB MG¤QM¡VPŸcY™rc—ˆq‘—}Œ¡‚„¡ƒ™~wxm|ibm\P\HLXBHQ>BK8>E58>048*13(01)00(1.)0,)1,)1++2,,3--2,,2,,2,,2,,1-,1-,1-,1-,2.-2.-2.-2.-0/-0/-0/-3-18,87)63.+77+GL5`iNx…k‰•Œ˜Ž›™Œš›ƒ•—€—‘„ ’Š«–°˜¯—‰ª•…§£‹{Ÿƒxœ€|¡€„§‡³’•´”‘°Š¥†„€}”xj~eXfMRV;XW;\[?+/2+/2+/2+/2-.0-.0......------.-+-,*-,*,+),+),+),*+,*+,*++)*+)**()*()*(),*+,*+,*+,*+,*+,*+,*+,*+,*+,*+,*+,*+,*++)*+)*+)*,*+-+,-+,.,-.,-/-./-./-./+*0,+0,+0,+0,+0,+/+*.*)/+*/+*/+*/+*0,+1-,3/.5//711:12;31<42=32=32<20<20=20=20?1.?1.@2/A30B5/C60B73C84C:5D;6E:6G96J84M51U84]82g80o9/{;1ƒ=1‹?2Ž?2•A7–?6”@5–?5˜B3 D7¦F6®F9´H;¹I=»I?¸H=­E:¤B5›?2—?1–A-–A-•?.”>-”=,”=,–=/–=/”<.“;-=/Ž<.‹<-‰<,ˆ<,ˆ<,‡;+†:*†:*†:*ƒ:+ƒ9,€;,€:.;0€<3~>4?6B;ƒD=†G@ˆH?LC’H?—HA MG¥RN¤YS¤h^ yjŽw–œ‚‘¦‡ˆ¥‡„žƒ|’}tƒpjudZfRT`JMVCDM:?F6:@27;-68-01)00(0-(/+(0+(0**2,,3--2,,2,,2,,2,,1-,1-,1-,1-,2.-2.-2.-2.-0/-0/-0/-3-18,86(51,)66*GL5`iNx…kˆ”€™›™›œ†˜š‡ž˜¬žš»¦ŸÂª—¹¡—¸£˜º¢—¹¡³—ˆ¬ˆ­Œ²’‘´“•´”®Žˆ£„ƒœ{’vg{bTbIPT9VU9XW;,03,03,03,03./1./1./1./1.........---.-+.-+-,*-,*-+,-+,-+,,*++)**()*()*()+)*+)*+)*+)*+)*+)*+)*+)*,*+,*++)*+)*+)**()*()*(),*+,*+,*+-+,.,-.,-/-./-./+*/+*0,+0,+/+*/+*.*)-)(0,+0,+/+*0,+1-,2.-3/.5//822:12;23<34=32<21<21;10=20<1/>0/>0/?1.@2/A30?40<71<92;:5<;6<;6>;6?:4B71H92Q81Z:/e;/p9@5A5D4“F6˜G6žF8¢F7©G:­H>¬G=¦D;ž@6˜>5•?2“@0‘@-‘>,‘>,’<+’<+“=.“=.’0/=/.>0->0-?1.>3/;60:70983:94;:5=:5=82A60D5.M4-V6+a7+m9,v;-|=.„<0<4‘<7Ž>3Ž@4ŽB2C3”C2˜@2œ@1£A4¨C9¨C9£A8?5—=4•?2’?/‘@-‘>,=+‘;*‘;*’<-’<-‘;.‘;.;-;-‰;.ˆ:-„;,„;,…9)…9)ƒ:)‚9(9*9+~9*~8.=1€=4@7B9‚F>…IA‡LFŠMHŒIAŽGA–KFŸTO§]Z¦jb¦|n¡y•žŽ©ˆ†®‰ªˆ~£‚™~~‹wxnjxacr[ZhQP]IIUACL;=E60/?10@1.E1*E2+?7,99-5=03>07:1<71C1/L0/V/0\31`94c>6bE7fE4uF2}D0„C1ŠA2‘?3•=3–<1–<1”>1”B4–G6–I7”G5’C2B.”>/™;3˜93“:2Œ<1…@1ƒA1€C1‚C2ƒA1…@1‡=0ˆ2v>1t?1s@/s>.u=.w<.~>2?3ƒ?4…C7ƒG<„L?‚QC‰PGGEIH‚WN|iXw{du‰mz™zƒ¤…‰¦ˆ©Œ“§ŽŽ¢‰ƒ „zk˜wb‘mY†]W€VRvPNlJI`CFT=AI4?@2=6,=2.9.,7(+5&)5&+6'.4)/+,.)-.)-.,,.-+.0*.2(03(05(15(14(24(21)41)40*40+20+/0,+/.*44,@C2X[Fpy\ƒŽlŠ™p s£rˆ£p‹¨r–´~ŸÂŠ¦Ç’¦Ç’§Å“¤Ä’Ÿ¿‘¶ƒ‡«{ˆ®}´ˆ†©Œ¬‡Š¨†š}wŽtok[lYKXFEL5.>5.>5.=4-<3.;2-=2.<1-<1/;0.=/.>0/>0/@1.C/(C0)<4)77+2:-/:,47.83-?-+F*)N'(S*(W0+\7/]@2dC2sD0{B.„C1‹B3‘?3”<2”:/’8-’0‘B1‘D2‘D2A0Ž@,‘;,˜:2˜93“:2Œ<1…@1‚@0~A/@/„B2…@1ˆ>1‰=0‰;/ˆ:.†:-ƒ;/y9-{A5u=0n9+s@/t?/t<-{@2{;/‚@4ˆD9‹I=ˆLA†NA‚QC‡NE‘KI—SRd[‡tcƒl{s}œ}¢ƒ‰¦ˆ¦‰‘¥Œ‘¥Œ‡¤ˆ} ‚oœ{j™ucg^‡]X|VWuSXoRWeNPXCJK=E>4B73;0.8),5&)5&+5&-1&,*+-'+,'+,))+*(+.(,1'/2'/4'04'03'13'10(30(3/)3/*1.)-0,+.-)//'B3/0*01+01+01+12,12,21,32-43.43.74/74/63.52-50,50,7/,7/,6.+6.+3.+2-*1++1++0,-1-./-0.,/--/++-*).*(-/(/1'//)-/)-/)-/)-.*+.*+/+*/+*.-).-)/.)/.)/.)/.*..,.../-./-./.,1-,1-*3.+5.(5.(7.'8/(:0';1(<2)=3*>5,>5,>5,>5,>5.=4-<3,<3,=2.<1-;0.;0.;0.;0.<1/?1.@1,D/*L,-R)-U(/U&.P'/J*/A,+=.+;1(B1)M2+[4/j51q73p@4sB4|B7„A9ŠA;>:Œ=8Œ=8ˆ;3†=4…?5†B7‡C6ˆB6ˆB6‹A4Œ@2@0‰@/ˆ?.‡>-‰=-ˆ<,Š;,Œ=.;-Š=-ˆ<,‚>+>*{>){>+x8,{;1v8-r6+u=.v<.r8*w9,|>3A7ˆE<‹H?‰JAˆLBˆNC‰ME‘JF—SP•e[‘td‰„n„‘uŸ}ƒ§ƒ‚ª‡†«‰‹ª‹Ž¨‹Ž¢‡‰›…•{z“ue’iZŽ`R…ZQXP}VMuSEhH?]C5Q82I5-?/)7*%2(%1'%/')+&2()5%(4%*4%*1&*1(+0*./*.,,.,,.)-0)-0&.0&.0%/1(-00.13--0,)/,%8:-SWFox]~Œk†–r„™p„žq†£s„¤sƒ¥s‡­z‘¶ƒ–»‡•·„µ‚Š¯|„¬z¨y¨y‚©}‚§|‚¤~{x’up‰lh|cXkUMZHGK4+?5,?6-?6-@7.@7.?6/>5.=4-=4-=2.<1-;0.;0.;0.;0.<1/?1.A2-E0+L,-R)-U(/U&.P'/I).B-,>/,;1(A0(K0)X1,f1-l2.j:.m<.v<1€=5†=7‹<8Š;6Š;6‰<4†=4„>4„@5…A4‡A5‰C7C6Œ@2Œ?/‰@/ˆ?.‡>-ˆ<,ˆ<,Š;,Š;,Œ:,ˆ;+†:*=*~=){>)z=*}=1{;1x:/v:/x@1y?1v<.x:-~@5‚B8‰F=‹H?‰JA‡KAˆNCŠNF‘JF˜TQ–f\’ue‰„nƒt{¥‚ª‡†«‰Œ«Œ©Œ¤‰‹ƒ‡—}}–xi–m_“eYŒaY‡`X…^W]QtTLjP@\C>299-23-23-34.34.34.45/54/54/650761961:72:72961940940:2/91.91.80-50-4/,4/,4/,3/.3/.3/.3/.0.//-..,-/+,0*,2),2),2),0**0**0**0**1-*1-*2.+2.+10+10+10+10,21-21/10.10.3/,2.+3.*3.*92,92,;2)<3*>4+@6-B5,C6-B8/B8/C90B8/B8/A7.?4.?4.=2.=2.<1-;0,;0.<1/=20=20>50B30K.2R*2V'1U&0P'/G*.?1.74+37)67)>5&J4)W2*]2,e:3j;5r=9z=<=<†<=†<=…;<…?=‚A=‚C<€D<‚C<ƒB<…B<…B:D2E1B0„A0‡>/‰;.‰:-‹9-Š8,ˆ9,†:,€;+|=+w>*t@*x=+†M@‚LB„ND†PF€VHnbHnmOxtW€{^…eˆ‡kŠ‘r‰šx‰¤…©ƒ®…°†~¬…z§€w¡{z™w~mˆix…gvƒet„gp€cgz^csXVfLP\FIN:@A1<6*9/%7*!5&5&%2'%0(%-)&+,'+-(*/)'-)(-)(,++++,*+/)+/)+1()2('4*(0,#., 89)PU?hrYu„eyjwiz—k|p{Ÿoxžmy¡o~¦t~©t|§rz¤rz¤r{¥u|¦x|¦x}£z{¡x}Ÿzz™wuomˆie|_UlPN\EEE9B;3=6.45/45/45/560560560761761872872;83<94<94<94<73<73<41<41;30;3083072/61.61.5106216215102011/00./1-.2,.4+.4+.4+.2,,2,,2,,2,,3/,3/,3/,3/,21,21,32-32.32.32032032051.51.61-61-;4.<5/=4+?6-A7.B8/E8/E8/D:1D:1E;2D:1C90B8/@5/@5/>3/>3/=2.=2.=20=20>31>31?61C41M04T,4X)3W(2R)1J-1A3096-59+78*?6'J4)V1)[0*e:3j;5r=9z=<=<†<=†<=…;<;9>:€A:C;‚C<ƒB<„A;ƒ@8D2E1B0ƒ@/†=.‰;.‰:-‹9-‰7+‡8+…9+€;+|=+w>*t@*x=+‚8+~.%…6/‡=4x4+t4*}A6}C7|F:~H<K>€L?‚LB„ND‡QG‚XJrfLpoQxtW}x[‚|b†…i‹’s‹œz†¡~‚¦€¬ƒ®„}«„z§€w¡{z™wn‚‹l}Šl|‰kzŠmw‡jpƒgn~cbrX\hRUZFJK;E?3?5+;.%8)"7(%5'&3(&0(%-)&*+&*,').(&,(',('+****+)*.(*.(*0'(-#"3)'51(86*BC3UZDfpWn}^tˆeqŠct‘ew˜kw›ks™hs›iwŸmx£nv¡luŸmv ny£s{¥w{¥w|¢yxžuzœww–tsŽml‡hd{^UlPN\ECC7@91;4,560560671671782782872872983:94=:5>;6>;6>;6>95>95?74?74>63=52;62:51940940940940:5294183072/61.7/-6.,7-,6.,6.,6.,6.,4/+4/+50,50,41,52-52-52-63.63.43/43/73073085094094.<5/>5,?6-A7-B8.E9-F:.G;/H<0H;2H;2H;2H;2E;2C90B8/A7.?6/?6/>50=4/=4/>50?61?61=84=84=:5>;6>;4>93@91A60C6-F5-F6)G5)D7'E8(C;(K8)]3'j1*p4,z5063†65‡63…626182€<3‚<4„>6ˆ=7‹>6‰?6„@5ƒA5ƒA5ƒ?4ƒ=3‚<2€>2}=1y>0x>0x>0y>0{=0~<0€:0‰6.”.*™,)®FC´RO”=6ƒ60‚F;|L>qLmT@nUAoV@tXC|[HxdKdsLhwNtT›nY²h_Çhf×opÛwwÎ{w„y´|¨˜~œ~‘œzˆ™u†–r‰Žp‰Œo„n€n|’nv’lpkjŒgaƒ`\{YUnNM`BES9>F.9;%94!8.$9,$6+%3,$/,#--#,-%--%--%2+%6(';%'@#'D!'H'E!#9'=4#F@*JH1QT9]cGesPizVk„Zi†ZjŠYp’`p–co•bo—bršft mqlq›mtqx¡uz£{{¡zzžzv™xy˜xu”toŒmj…db}\TmMM]CCD6A81<3,671782782782893893983:94:94;:5>;6?<7?<7?<7@;7@;7B:7B:7A96@85=84=84<73<73<73<73<74<74;63:52941:2080.9/.80.80.80.80.61-61-61-61-52-52-63.63.74/74/540540841952:72=84=82@93@7.A8/C9/D:0G;/H<0I=1I=1J=4J=4J=4I<3F<3D:1B8/A7.A81@70@72?61?61@72@72A83=84>95>;6?<7@=6A<6C<4E:4E8/H7/H8+I7+G:*G:*E=*L9*Z0$g.'o3+{61„96Š:9Œ;8Œ=9ŒA<‰@:‚>5;3€:2…:4Š=5Š@7„@5ƒA5‚@4ƒ?4ƒ=3‚<2=1}=1y>0x>0x>0z?1|>1=1;1Š7/•/+§:7ÑifÞ|y°YRB<ˆLA~N@qL4*?2*;0*70(30'00&./'//'00(5.(9+*>(*C&*G$*K"*H$&G5+LC2WQ;[YB`cHgmQiwTj{WjƒYfƒWf†UlŽ\n”an”an–aršfržko›jo™kr›ow ty¢zxžwvšvs–uw–vs’rn‹li„ca|[TmMM]CGH:E<5@707827828938938939:4:94:94;:5<;6?<7@=8@=8@=8A<8A<8A<8A<8A<6@;5?:4>93@93?82@93@93@93@93?82>71<5-;4,:1*:1*:1,:1,:1,:1,92,92,61+61+72,72,63,74-74/74/74/85096/;81=82?:4B;1B;1A9.C9/C9-G;/H<.I=/K=0K=2L>3L>5J=4J=4H;2G:1C90B8/B90B90@91?80?80@91A:4A:4@70B71G81M83S81X51\5.`3._.'b-'c.&f-&f-$h-%i-#l,"u0!1$‰7+”<2ŸA7¥D;¨G>§I?ªNA¢I;—A27)4$3$—5(š8/˜67•6:’6978‰98<7y>6sA6nD6oC6rB6z>6‡76’26›-6¦(3¨ "Ä57ûutÿÏc`D>ŠJ>uJ9gQ:^W;[Z<\]>b]?k`DxdI‰cL£^N½[RØXYïO[ÿB\ÿ7Yÿ2Xÿ3YÿOqÿXtÿexÿmzûr|ñryèotÞpsÍroÆuqÃxs¿zs»|sµ|q­}q«}p£wl¡rhšh_“\UŒOLƒB@y33s+.o$)k")e#'_#%Y"%Q##K%$F'$D+&C,&A,'A,'C+'D+'D+'D,"SE+[R1e_?ifEimJnvQm|Sl~Tm„XhƒVi†VnŽ]s“at”bv—bzšivšns•pq“nt–u{šz~›{˜|y“zx’yx’yvrp‰ljƒeb{]TnKM]BMN39:49:49:49:49:4:;5=<7=<7=<7=<7@=8@=8A>9B?:D?;D?;E@8E>8D=7B;5B;5B;5B;5B;5B;5A:2A:2A81A81A83@72@72?61>71>71<71<71;60:5/85.85.74/74/96196196/:70<71=82A:0B;1C;0E;1F<0J>2K?1L@2N@3N@5N@5N@7L?6K>5I<3H;2E;2E;2B90A8/@91?80?80?80@93@93=4-NC=N?8M83Y>7W40U.'f94b1*g2,f1)e,%e,#m2*u9/y9/H9“E8šH<¢J@£E;ž=4<3¡C9©M@¨OA«UF¯WI§N>@1›9,Ÿ=4™78•6:47‰34‡76„?:{@8p>3nD6mA4n>2v:2…54‘15˜*3¡#.ÍEGî_aÉCBÑUUäxu®UO†F:‚WFjT=d]AedFfgHgbDk`DyeJiR [KÆd[åefïO[ó1Kü"Dÿ!Gÿ%Kÿ5Wÿ>ZûPcûcpùpzót{ñx}í‚ÒwtËzvÈ}xÄxÀx»‚wµ…y³…x¦zo¦wm¤riŸha™\YOMˆBBƒ;>€5:r)0n,0i-/Y"%O!!S-,R30K2-H1+E0+F1,F.*E,(H/+O7-XJ0`W6f`@gdCkoLu}Xu„[oWlƒWl‡Zp]r’at”bv–dx™dy™hr–jt–qt–qr”su”tz—{{˜|{•|z”{stn‡jk„gi‚daz\TnKO_DNO=SK@PH=9:49:49:49:4:;5;<6>=8?>9>=8>=8A>9A>9B?:C@;D?;D?;FA;E@:E@:E@:D?9D?9E>6E>6F=6F=6F=4E<3E;2E;2E;1D:0C9/C9/C90C90A8/A8/A81A81>7/>7/;60;60:5/94.83-83-96/96/:6-;7.>7-@9/B:/C;0D:.E;/I=/J>0M@0M@0NA0NA1P@3P?5M?4K=2I<3H;2E;1E;1C:1B90@9/@9/>:1>:1?;2C90J70X0.g"%|'š1¨!2©%2®2:ž84˜?7“D7•A6¦?8º@?Í/©?1©;.¤4(¤4&¨:+ªA.£<)¢=)¨A.®C/±B/¹D3ÂI@ÂFH¾AI¶9A¬08¤/5¡47•75‰606-ŠA8“F>“85•$(¦ +È/AåCRéFIéJGÔ:8Ë;:Ù\X½TNŠ>1†SB{_Gf[?a\-;C.;H4DN6WR4dY9gaAifGnrQz`zˆgt…cs†fr‡fs‰eu‹gzŽi|k~k~mzq‘yƒ’{‚‘~†“‚‹—‹Œ˜ŒŠ–Œ‡•ˆ€Žu†tp‚li€fax\SnMMaEPU?SR@RQ?8938938939:4;<6<=7?>9@?:@?:@?:C@;C@;C@;C@;D?;D?;FA;FA;FA;E@:E@:E@:G@8F?7JA:I@9H?6G>5G=4F<3F<2E;1D:0D:0D:1D:1D;2D;2D;4D;4?80?80<71;60:5/:5/94.94.96/96/:6-;7.>7-@9/B:/C;0E;/F<0I=/K?1M@0M@0NA0M@0P@3O>4L>3K=2I<3H;2E;1D:0C:1C:1A:0A:0?;2@<3@<3E;2VC:žE=šK> LAµNGÊPOÚIPÒFIª>2 A/¤>/¨>0¨:-¦6*§7)ª<-®E2£<)›6"Ÿ8%¨=)¯@-¶A0»B9«/1µ8@¿BJÄHP¿JP´GJœ><ˆ5/6-|3*}0(‰.+¢15À:EÜCUíKZçDGÓ41Ó97Á10ÊMIÊa[–J=Ž[J~bJj_ChcCuoO€pO„fJ’fM¸eWñ\`ÿJXÿ>Oý4Gÿ0Hÿ2Lÿ1Kÿ,Fÿ2Mÿ/Iû/Hÿ0Jþ/Kþ,Iÿ+Jÿ/Oÿ6Xÿ9[ÿ<]ÿ?_ÿCcÿFeþIhþKkúHhùGiøDiùCiúDlÿFoÿItÿLvÿ_ƒÿYzôStäNkÙSkÕ^q²M[{(0d$%^.*X:2P@3?<+4<'8E1GQ9UP2aV6e_?heFquT†e~Œkwˆfx‹kuŠitŠftŠfw‹fzŽi}Žj}Žl”x‡™œ…ŸŒ•¢‘š¦š›§›™¥›“¡”‰—ˆ{Œzqƒmg~d_vZSnMOcGSXBWVDXWE7827828939:4;<6=>8@?:A@;BA2I=1H<0G;/D:.D:.E;/E;/E;1F<2E<3E<3@9/?8.?80>7/;60:5/:5/:5/:6-:6-;7,;7,?9-@:.C;.D.L?/M@/M@/O?/O?0O?2O>4N=3M<2J<1H:/E;1D:0D<1D<1@<1@<1?=1@>2A>5K:2a2,m!!œ17ÓKYîK^ûK_õMZÜCF«/' 6&˜<%Ÿ@*³E4ÉI>ÚBAÑ==µ@6«C6¬@3¯?3²=3³=3µA4µD6µE7®@1¦;)§9(­9*°8*²4(³0&½7.Å60Ì20Ò./Û14è;?ëBEæFFÁ-)¯$¨¸+$Ø@=íIJð=Cå14â92Ð.#Ø7/Î5/ÌC=ÐYQ±SGšRC‚R<„^GiO”fOœ[G¬VIÊ_UïheøOVüDNìAGäDFâLKáRNÛMK×EEéMQêCKí;Gô8Gù4Hü1Gÿ3Jÿ7Qü6Qû6Rü7Uü6Wû8Xý9]ý;^þ;cþ@fü=hú=gú9@?:BA2I=1H<0G;/E;/E;/E;/E;/E;1E;1D;2D;2@9/@9/@91?80<71;60;60:5/;7.;7.;7,<8-?9-A;/C;.D/I=/K?/M@0M@/NA0O?/O?0O?2N=3N=3L;1I;0H:/D:0D:0D<1D<1@<1@<1@>2A?3B?6M<4b3-|00´IOâZhíJ]ì=Ï;;³>4©A4«?2®>2´?5¹C9¼H;»J<­=/¬>/¨=+¨:)¬8)²:,¹;/¾;1ÌF=ÒC=Ö<:Ø45Þ47ê=AïFIëKKÑ=9ÑF?ØOGÝPIàHEá=>æ39å14Ü3,Ú8-Ò1)Ò93Á82¶?7¸ZNšRC}M7†`IŒhN‹]F™XD·aT×lbðifíDKò:Dæ;Aà@BÝGFÜMIÜNLÞLLëOSìEMí;Gó7Fø3Gû0Fÿ3Jÿ8Rÿ:Uÿ:Vÿ:Xÿ9Zþ;[ÿ<`ÿ?bÿ?gÿCiÿBmÿCmÿAoüCoüBqúCsÿAoÿEpÿ>fÿEkÿJnùEhòKiíWpâ_qÄVc•=8@?:@?:C@;DAGB>GD=GD=HC=ID>IE/G>/F=.F=.E;/E;/D<1C;0B90B90@91@91?82>71;60;60;7,;7,;7,<8-?9-A;/D0L?.M@/P@0P@0O@-O?/P>0O=1M=0L2A?3@@4R92x20¤@BÇY\Ö[^ÐKLÌB@Å<6´2%«3"¤7 ›9—:šA!£H)¥J-¥E-Ÿ;,¢:1¥81§60¯95¸A=ºE>·D=­>3«?3§;/¤5*ª5+·<4ÃD=ËF=¾:%Ñ@+éA4ü<7ÿ46ÿ,3ÿ$,ÿ%ý(*ÿ:7ÿHAúE<ê8.ã.%é.'í6.Ø2"Ý=-Ë.Ñ7-Á3)µ5,ÏdZÀh\—S@“TB“N>œI;ÀQJç__ûZ_ùISóDIëADÛ@>ÒA<ÊE<ÎI@ÚQKìVUôKPø@Jú5Fý2Eø1Dô1Bò6Eö;Lú:Qý8Sý8Tÿ7Wÿ:Zÿeÿ?kÿ7eÿ8iÿ;lÿ=8A>9C@;DAHC?HC?GD=HE>ID>ID>JF=JF=MF2@@4Q81u/-¬HJÁSVº?B¸34½31¼3-¶4'©1 ¥8!ž<™<—>›@!›@#›;#œ8) 8/¢5.¥4.­73·@<¸C<²?8±B7­A5¨<0¦7,¯:0½B:ÃD=Å@7Ã?*Ï>)Ü4'ç'"ô!ÿ 'ÿ%-ÿ)0ù$&ñ*'ê/(æ1(ä2(æ1(ë0)è1)Ù3#Ö6&Ð3$Ð6,Å7-¾>5Ê_UÕ}q¨dQ“TBJ:¨UGÑb[ç__ïNSï?IõFKëADÜA?ÒA<ÆA8Å@7ÐGAãMLòIN÷?Iü7Hÿ5Hü5H÷4Eô8G÷7yRK|c^Œ}z£•”­£¤²®¯¶µº²µ¼ª®¹°·Á¸¼È½ÁÍÂÁÏÄÀÎÌÄÓÕÍÚàÔÞãÙÚèÜÜëÝÝèÙÞçØßæÖááÔÞÚÎÚËÄË»¹¼¤¦£Š‘‰t‚qexb\sW[oSZkK\iK[hJ645645653653653764873984<;6=<7>>6@@8BB8DD:EE9FFMD5KA5J@4H>4G=3E<3D;4C:3C:5A96A96@86?75<66>64?53@53>63?67=98>:;===>>>BA=DA2M:4O56N38I57C79;:66=52@33A08A,=A*B@)X8#‘:)Ì[MÊ\M¨=-Ÿ6#¡:'›8#ž9%¢>'«B-°C.¯?+±9(³8(³4%­2#¦7&¥;+£<+¡:)¦A/®I7°I6¬C0©>*«<)­:(²:*¿D4ÊK<ÇE7¿7+Å3&Ï8-Ò@3Ñ=1Ï;-Ö:.Û7-â1+í0,ô.-õ/,ò1,é3(à6'Ö9&Ô9%Ý='Ó0Û@*Í8$È9(Ç>.Ã;/êaWâWPÏ>9Õ:8õOQÿX[ÿELû9Aú?Fæ@DØ?AÐ>>ÈA=¼@6¯;.©>.¯D4ÆWFÉQCÑKBÝHDéCCñIüDLùDM÷AM÷>Lø=Nù>Sü>Xþ?^ÿCeÿBhýClûBnøAo÷AqôBröBqøAoÿLvûWzêOoÛHdðZwÿh‡ÿa„ÿQ{ÿPzÿW~÷b‚Õh{ªdnb_p_W–€r®˜Š¾²¦Ä½µÃÃÁÈÇÍÉÆÑʾÒÙÃÚÝÀÜãÁÜèÆßèÏâëÙåëàèëåçëçäîëæðëèìææìãäëâåèßäãÚßÑËÍľÀ¬«©””’€ƒ|qvoiqffnafl^el\dk[201312431653875986984984;:5<;6==5??7AA7CC9EE9EE;HH>HH>HHLMF@LC4J@4KA5MC9LB8F=4B92E<5C:5@85?74@86?75<66<42C97C86A96@78>:9>:;<<<===@?;C@;EA8IA6L@0O@-O@+L@*FA.E?1H<0K82N45N38K79F:<@?;3:20>17E49B-6:#?=&cC.ÀiX»J<¦8)¢7'£:'Ÿ8%ž;&¤?+Ÿ;$¥<'¬?*¯?+²:)±6&³4%¯4%¥6%¡7' 9(¤=,§B0©D2ªC0«B/©>*¬=*¯<*µ=-¾C3ÅF7À>0º2&Ê8+Î7,Ì:-Ï;/Ð<.×;/Ý9/æ5/í0,ô.-õ/,ò1,ë5*â8)Ù<)×<(Û;%Õ2Ï4Î9%Æ7&¿6&È@4ØOEÓHAÝLGðUSüVXûKNõ:Aø6>ù>EèBFÝDFÓAAÆ?;¹=3°Sü>XÿCbÿGiÿBh÷=fô;gô=kùCsûIyÿKzÿM{ÿMwõQtìQqâOkåOlúYxÿeˆÿ[…ÿBlÿQxð[{È[n¿yƒ‚c`‹zr§‘ƒ½§™ÑŹÝÖÎÜÜÚÜÛáßÜçåÙíëÕìñÔðøÖñüÚóùàóøæòöëóôîðøôñøõð÷òïôîîòéêíäçèßäæÝâÖÐÒÎÈÊ»º¸¤¤¢‰|zt|qrzm~„vy€pv}m0/-10.320542651762872872::2;;3==5??7AA7CC9DD:EE;JG>JH:1>:1=9.;7.96-96/:7.;8/=:1>;2@<1C<2E?1H>2I@/M@0O?/P?/Q>-L?,?A+=B,?A,A>/@<1A:4=82=84C;8E74N43\23j)-u"*Ž*4¦9?ºKB«;-ž3!¡6$¡:'ž7$Ÿ9#¦=(£:%©<(±>+¶>-¹;,º8*º4(¹5)¯7)«7*¨7)ª9+­<,°?/²>/²<.²=,±7(·9*ÅC5ËE9Æ<1À6+Æ3)Ñ4+Ö3*Õ7,Ø7-Ú:.Þ7.ä6-ê3-ñ0+ô.+ô/)ð1)é4)ß8(×;%Ö:$à;'Þ4#Ù6%Ú:,Ð8*Æ2&Ç9-ÒE<ÓF=ÙJDãRMêUQèMKâBBæBAìJHÞFC×FAÎE=Ã@6·;/¯9+®:+¯;,¹C5ÉK?ÔNEÛGCßA@êADóBJøCLõDJ÷CLùENýGTüCSø>Sû?XÿCaÿFhÿCiú@gù@jùBnüFvþJyÿJ{ÿGzÿCtÿEpþKsÿVxÿZ{ÿVuüNoöHiñJhâLgÏRd¾dm¬rpkMC“}o·“‡Ô®£ëÐÇóàÚîæãíèìêçîëãòòå÷÷äúýæúÿêüÿîýÿóýþøüþúùÿú÷þùõþöôüôòùïðõëìòçëðåéæÝàÞÕØÊÆõ±®Ÿ š‘’Œ‰ƒ‰ƒŽ–‰ˆƒ…€/.,0/-10.21/43/540761761::2::2<<4>>6@@6BB8CC9DD:IF=IG;KG;LI8MJ7NL7NL7OL9KIME=JC;F@9@A;??99<74<73=90>:1>:/=9074+85.:7.<90=:1>;2@<1B;1E?1H>2I@/M@0O?/P?/Q>-L?,:<&9>(<>)?<->:/?82;60940?74F85O54W-.f%)z'/—3=­@F¨90¢2$2 ¤9'£<)ž7$ž8"¤;&¤;&ª=)³@-¸@/»=.½;-¿9-¿;/´<.¯;.ª9+ª9+¬;+®=-°<-°:,³>-±7(»=.ÍK=ÌF:¿5*»1&Ë8.Ò5,×4+Õ7,Ù8.Ú:.Þ7.ä6-é2,ñ0+ô.+ô/)ð1)ç2'Ý6&Ô8"Ó7!Ý8$Þ4#Û8'Ý=/Ô<.É5)Æ8,Í@7É<3Í>8×FAâMIçLJåEEæBAçECÜDAÕD?ÌC;Á>4¶:.®8*­9*®:+­7)ÂD8ÔNEÝIEßA@ç>AôCKþIRòAGô@IøDMýGTþEUú@Uû?XþA_ÿDfÿCiþDkÿFpÿIuÿK{ÿL{ÿIzÿExÿFwÿItÿLtÿXzÿ_€þUtñCdøJkýVt×A\ÉL^Ö|…·}{aC9‘{m±Ø²§õÚÑþëåúòïûöú÷ôûôìûùìþþëÿÿíÿÿïÿÿóÿÿ÷ÿÿüÿÿýüÿþûÿýùÿúøÿøöÿõöýóôûðôúïóðçêçÞáÓÏÌÀ¼¹­®¨£¤ž£—£—£«žž¦™›£–/.*/.*0/+10,21,32-54/650880991;;3==5??5AA7BB8EB9KE9ME:NG7PI9QJ8RK9RK;QK?MHDQOT^\jkk…wyŸ~€°|¸|~¹us²mi¦`\—TQˆNJ|GDoC?d>;XA=T=;I:7@869:63;81<9099/783794:;5<<2?=.B=*A<(C;&G?(J?)K@,LA/L@0L@4J@6K>6I81I73G83C84>;6:;54>63=55=2?<3J70U.)j**‡14 8?®=?¦7,¥7&¥:(ª?-¨?,£8&¢7#¨9&©9%±9(·<,¿=/Ã;-Ç;.Ê:/Ë;2Ä;1¿90º5,¸3*¹5)º6*»5*½4*¿7+Ã6,Ë>4ÒB9Î;1Å.%Æ/&Ô6-Ý2*á0(ã2*å2+æ4*ê2*í0*ñ.*ö/*õ.)ò/)ì1(ã3$Ú5"Ñ6 Ð5×2Ú0!Ú4$Þ:.Û;/Ô7.Ó;0ÖA:Å5,Ä7.Ç<5ÑH@×RI×RIÏJAÈD8ÉE8ÈD5ÃA1¼=,·9*²7'³8)·9+°2&À=3ÑHBØIEØDDÞDFéJOöQWëBGîAGóDKûIUûIUùDUøAWúB\üCbýDfÿGkÿIrÿNwÿOzÿLyÿJwÿHtÿR~ÿT}ÿKrûKoÿTuÿUq÷MhìH`êNcÏAQãdoÿš¡æ†ˆ~-,‡=:µrlÛ šÿÏÊÿäáÿñîÿûûÿüÿ÷ôûøòüúòÿüôÿÿöÿÿ÷ÿÿùüÿüûÿüùÿýùÿûøÿùøÿø÷ÿõ÷ÿôöÿôøÿó÷÷ëíîâäÜÔÑÌÄÁ¼¹°¶³ª³³§³µª¶½µ®¸°ª´¬10,10,0/+0/+10+21,43.54/77/880991;;3==3??5AA7DA8KE9ME:OH8QJ:RK9SL:SL<-A<)B=)D<'G?(J?)K@,LA/L@0L@4J@6K>6O>7N<8I:5C84<949:43=54>66>3=:1G4-Y2-w77•?B¦>E©8:ª;0ª<+«@.¬A/©@-¦;)¦;'¬=*¨8$°8'¶;+¾<.Ã;-Ç;.Ë;0Ì<3Ç>4Â<3½8/º5,º6*»7+¼6+¾5+¾6*Ì?5ÏB8Ç7.Ã0&É2)Í6-Ò4+Þ3+â1)ä3+æ3,æ4*ë3+í0*ñ.*ö/*ö/*ò/)ë0'â2#Ù4!Ð5Ï4Ö1Ù/ Ø2"Ù5)Ù9-Ö90×?4ÙD=ÖF=Í@7Ç<5ÊA9ÒMDÕPGÌG>Á=1Â>1Á=.¿=-º;*·9*µ:*·<-¼>0·9-¿<2É@:ÒC?ØDDàFHêKPõPVé@Eì?EòCJûIUýKWüGXúCYûC]ù@_ûBdþFjÿJsÿOxÿOzÿLyþIvÿKwÿUÿT}þJqùImÿStÿVrøNiéE]ãG\èZjÿ–¡ÿ³ºúšœ–EDt*'¬icЕ÷ÆÁÿáÞÿñîÿûûÿýÿú÷þý÷ÿÿ÷ÿÿøÿÿúÿÿúÿÿüÿÿþýÿýúÿüøÿûøÿùøÿø÷ÿöøÿõ÷ÿôøÿôøýñóôèêäÜÙØÐÍÍÊÁËÈ¿ÊʾËÍÂÉÐȾÈÀ·Á¹85.63,52+30)30)41*52+63,85.96/:70<92>;2@=4B?6C?4KC8ND8RF8UI;VJ:WK=TJ>SJCSJM\Vdki~}¥‰Á‘™×•å–ë’™ç’㇊ׅÏ{~Ãtuµik¤cc—XY…SSyJIiB?Z<:O:7J86D63D43C52C64?:5;<85?;2C=-E@-E@*DB-DC/BD6AD9?D>6ïXOäQJÕH?ÌC;ÉF<ÉK?ÃG=º@3·=(·=&¹<&¹:'¸9&»9)À5C?4JB7MC7RF8UI;WK;WK=UK?SJCSJM]Wenl„‚©•Ç˜ Þž¦î¡¨öž¥ó› ñ˜›è”˜â’•ÚЇ‰Â‚‚¶xy¥qq—dcƒXUpOMbIFYECQC@Q?>N>;L;9D=8><85?;2C=-E@-E@*DB-DC/BD6AD9?D>=M@>S@ASBET@HS@IP=HJ>GDCHAA=1L:,fG5€Q?‰L9ŠA.‘:'£@-©>,«>*¬?+®?,°?-²?,³;*²7'¹7)¾9*Æ8,Ê7-Ï6.Ó91Õ:5Ò93Ð83Î61Î61Ï81Ð92Ï60Î5/Õ;3×=5Õ8/Î1(Ñ3*Ù;2Ü;3Ù2*æ1(ì0'í1(ñ0)ò/)õ.)ö,(÷,(÷-)ô/)ð1)é3(á5'Ù6%Ò7!Î8 Ò:%Ò:%Ò7%Ð4%Ñ5&Ó7+Ò8,Ð7/åNEêWPçZQÚQIËH>ÃE9½A7¸>1·=(·=&¹<&¹:'¸9&¼:*Á=0Ä@4ÊD9Æ?9É@:ÐFCÔJHÓIGÔJJÛKKåGHçCDëEIóLSûQZúP]ùM]ùL`õE\öEaùFdýIlÿNsÿPwÿOxýQwòYxìYvðWuùZxÿ^{ÿ[uúRkòI`ýXiùTeíL\ü[kêGXóN_óN_ãR_ÇceÉ‚~窧ÿÓÏÿêèÿóðÿø÷ÿþÿùýþøýÿùýþûüþûûûýùúüøõü÷ôÿú÷ÿûøÿüûÿûúÿøøÿóóýîñúëîðââëÝÜäÙÕãØÒæàÔíçÛñîßññåìòîÛåäÎØ×A=4>:1;7.84+62)62)62)73*84+84+:6-<8/>93@;5A<6D=5JA8MC7RF8VJ:XK:YLc@9X=8L<9D=;>>=9?@:@A9>C±K=«@.£9#¦9$®?+¯@-°?-²?-³@-·?.¶;+´5&º5&Â6)Æ6+Í6-Ñ4+Ö5-Ø7/Ü94×50Ö41×4/Ø50Ú72Ú72Ú5/Ø3-ã>8Ú5/Õ1(Ú6-à<3à<3Û9.Ý5*å3)ë0'ð/(õ.)ø-)û+)û)(ú*(÷-+ò/+ë3+æ5+à6)Ú7(Ö6&Ð7%È:&È;'Ç:&Ê9&Î8)Ò9+Ñ7+Ð3*Í3)æMGùb[ñ]YÛLFÉ>9Á74»6-º=)º>&¹<&»:%»8&À8*Ã;-Ç=2ÍC9Ë@9ÌF=ÒMFÑMHÊICÆICÐKFÝLIàFDâHHëQSòVYòU\òR\ôRaîK\ñI`òJaøKgýPlÿStÿSuÿUwòUtòYwü]yÿ]zûTnöLfùPgÿXnÿ[lÿbsôL[ýRbûK_ÿQfþH^êO_¾^_¸wsÖœ˜úÉÅÿãáÿìéÿôóÿþýüÿýùÿÿøÿÿøÿþúÿûüüúþùöÿ÷õþùõÿúöÿûøÿúøÿ÷öüððøêêôææëÝÚèÚ×äÚÑèÞÔðèÛúóãÿûçÿþïõúôâëêÔÝÜB>5A=4@<3>:1<8/:6-84+73*62)62)73*84+;60>93A<6E>6I@7MC7RF8UI9WJ9XK;ZL?[NHTIMXQagd|}©Œ’Ì—Ÿçž©ø¥°ÿ¨³ÿª³ÿ¬´ÿ«³þª±ùª®õ§¬ð§«ëŸ à™™×ŒÆ~¸tq¨gd›]XŽXQ…XPYP}VNsMFeC>R=:E=;>@?;=>8@A9@E>?D>:C@:BD=GI>LY>XqMgˆ\s“fs“uu‘„v‹k‚‰Zl•UcžQY«QQ³PK¯I;§<*¡7!¥8#ª;'¬=*¯>,³@.³@-¶>-·<,º;,»6'Á5(Å5*Í6-Ó6-Ø7/Ú91Û83Ù72Ú85Ü94Û83Ù61Ù61Ü71Þ93çB<á<6Û7.ä@7ÿ[Rÿlcÿ^Sç?4å3)í2)ò1*õ.)õ*&÷'%ù'&ú*(÷-+ó0,ë3+â1'Ú0#Ô1"Ô4$Ó:(Ê<(É<(Ê=)Î=*Ñ;,Ò9+Ò8,Ó6-Ú@6Ð71ÞG@öb^æWQÌA<È>;¸3*·:&¸<$¹<&¼;&½:(Á9+Ä<.Ç=2È>4ÍB;×QHÞYRÓOJÁ@:½@:ÎIDÛJGáGEåKKìRTïSVìOVìLVïM\öSd÷OfôLc÷JfûNjÿRsÿRtýRtôWvðWuöWsýZwÿ\vÿYsÿWnÿUkÿctþVgÿ\kÿZjôDXöCXÿOeðUeÆfgªieɋ網ùÑÏÿêçýïîüø÷ùþúùÿÿøÿÿøÿþúÿûþþüÿûøþöôþùõÿû÷ÿùöÿöôÿ÷öÿõõöèèæØØãÕÒÞÐÍá×ÎñçÝüôçÿøèÿüèÿÿñúÿùèñðØáàC?3B>2A=1?;/=9.;7,:6+95*73*73*73*84+:5/=82@;5D=7G@6KC8OE9TH8VI8YI9[K<[MDVJJXP[fb{y{¢ŠÆ”à›§ñ£®ý«µý­µý®¶þ¯·ÿ°·ÿ¯¶þ¯³ü®²û§©ó ¢ì—–⊉Õ|Éro¼fc°b[¨_Uœ`S˜[SŽUN‚JGrCBd??W@?O=:EG=EMAEQÄ70º5&µ8"³;#«6"­5$®6%²7'´6'¸6(º5&½3&À0%Æ2(Î6+Ö90Ü;3à;5à<3â;3â=7à;5à;5â=7èA;êC=êA:é@9ç@8èA9ä@6Ü8.Ó3'×7+èK<þ\OêD6ç9.å-%ë*%÷-+ý//ý,/õ)*÷12ò53ë83ä70Ü3,Ø1)Õ1(Ô3)Î8)Ì9)Í:(Ð9(Ð9(Ð7'Ñ5(Ð4(Õ9-Ñ4-Ö;6éNLêROáHJÔ>?¾-*Á7*¿:'Á9)Á9)À8(À8(Â:,Ã;/Å?3ÉC8ÓPFÛXNÑSGÃE9¾D9ÉJA×NFÚMFÞPLäVTæXVäSVâQTçQZðZcóXfóVgöTiøTlýUnþVpÿQqÿEkÿJtÿUxÿY{ÿZuÿVmúSg÷TeøWfñUbõ_jñajÜY_ÜadÝilÀbb£jaŠd[¬†}Ò­§ìÉÅþàÞüèçÿõõûûùûÿÿùÿÿ÷ÿÿúþýÿþÿÿûýÿö÷üùôûûóýúõü÷óþùõÿöôõëéèÝÛâ×ÑÛÑÈßÕËïæ×üõãÿùæÿþåÿÿíüÿôëðêÜáÛEA5EA5C?3A=1?;0=9.<8-;7,84+84+73*84+:5/=82?:4C<6F?5JB7ND8RF6TG6WG7YI:YKBWKKXP[b^wsuœ…ŠÁ™Ü˜¤î «úª´ü­µý¯·ÿ±¹ÿ³ºÿ´»ÿµ¹ÿµ¹ÿ¯±ûª¬ö£¢î˜—㎋؂ÌwtÁsl¹j`§i\¡bZ•]VŠTQ|LKmCC[@?O85@D:BL@DR=BU<@aBHxSZ‹_p¦l”µs£½x§Át Æo™ÎjÐ\ÏLlÏAYÝFYÛCOÎ8:À3,¼7(¸;%³;#°;'²:)²:)µ:*¹;,½;-Á<-Å;.Å5*Ì8.Ô<1Û>5á@8â=7à<3á:2Ü71Ù4.Ø3-Þ93èA;ìE?êA:å<5ã<4Û4,Ø4*Û7-Ó3'Ì, Ô7(éG:òL>ïA6í5-ï.)ö,*ú,,ü+.÷+,ð*+ì/-æ3.â5.Ü3,Ø1)Õ1(Ó2(Í7(Ì9)Í:(Ñ:)Ò;*Ó:*Ô8+Ô8,Ñ5)Ø;4Õ:5Ö;9çOLðWYÚDEÃ2/Ã9,À;(Â:*Á9)Á9)À8(À8*À8,Ä>2ÇA6ÎKAØUKÑSGÆH<¿E:ÆG>ÕLD×JCÛMIâTRãUSáPSßNQäNWïYbõZhú]ný[púVnúRkúRlÿPpÿEkÿLvÿX{ÿY{ÿVqýTkþWkÿ\múYh÷[høbmòbkäagæknàlo¿aa™`WwQH•of¿š”ݺ¶ñÓÑôàßÿôôùù÷ùÿýùÿÿ÷ÿÿúþýÿþÿÿýÿÿøùüùôúúòüùôýøôÿúöÿøöøîìïäâåÚÔÛÑÈÜÒÈîåÖýöäÿûèÿþåÿÿíúýòëðêÞãÝKE7JD6HB4F@2D>2B<0A:0@9/<5-;4,;4,;4,<5/>71@93B;5B?8FB9KE9OF7QF4SF3WH5WJ:ZMEYNR_[jqp‚†³–Ï•£â©ñ©¯ù¬¯ü¯²ÿ²µÿ³¶ÿ´·ÿ´·ÿ´·ÿ®±þª­ú¤§ôœŸì”—䉌ـ‚Ï{zÆqo¸kh­ab£Z\—UXNQ~GEjD;XF0GV1Ci3@|3>5>§>EÀKSÛSaõUoÿWwþ[vöXoìSgæN]ÛCPÓ7BÑ08â?DäDFÕ:8Æ7/Ä>3ºA0±9(®5$±3$±3$¶4&º5&À6)Ç9-Ì9/Ö?4Ù?5Ü?6ß>6ß<3Þ:1Ý6.Ù5,Ò/(Ð/'Ò/&Ø4+ß;2ã<4à90Ü5,Ú6,Ï-"Ë+Ö9*ÝD4Ù@0Ì7#Æ1áJ9êM>öKAö?9ð..ï$'ó(,ø03í/1ç10á32Ü30Ù1.Ø/,×--Ú,+á/+ã0+â4-ã6/â:/à<0ß?1Ü@3Ð7)åMBáMCË60ÝGFñ[]ßIKÖ@AÍ82Ë7-Ç7,Æ8,Å9,Ã9,¿:+¾9*À>0Á?1ÆG8ÏPAÎPAÆH9ÁC4ÂB5ÊJ=ÌI?ÐMEÖSKØTOÔPLÔNKÖNPæ[^î^g÷dnüds÷ZkòPeòNfýNkÿPqÿSwÿYuùYqí\kícpôkuûozüjwõdqîdqähpÑopÁtn¯vk˜tdviXVO=rdW ŒƒÉ­©äÈÇñÙÙÿñóþõöýûüûÿÿúþÿýþÿÿýÿÿûÿÿùþûüöùüóùüõüûöÿþùÿüøûöðöïééà×ÝÕÊÜÔÇíæÔþùãÿÿæÿÿäÿÿéùúìíïääæÛNH:MG9LF8JD6HB6F@4D=3C<2?80>7/=6.=6.=60>71@93A:4B?8EA8JD8NE6PE3RE2VG4VI9ZMEWLP[WflkŠ~‚¯Š“Ì’ ßš¦î§­÷«®û­°ý¯²ÿ°³ÿ°³ÿ°³ÿ¯²ÿ«®û¨«ø¤§ôŸ¢ï™œé’•âŠŒÙ†…Ñ‚€Éyv»kl­ce ^a–X[ˆRPuPGdZD[e@Rt>KŠAL¢HQ¹PWÊU]ÛSaëKeõJjðMhèJaÞEY×?NÎ6CÉ-8Ø7?æCHçGIÙ><Í>6ÌF;ÂI8¶>-·>-º<-º<-¿=/Ä?0ËA4ÑC7×D:ÛD9ÛA7Û>5Û:2Ù6-Ù5,Ú3+×3*Ô1*Ö5-Ú7.Ý90Ý90Þ7/Ý6-Ü5,Ô0&Ø6+×7)Ï2#Ë2"Ò9)Ô?+Ò=)Õ>-ãF7öKAüE?ø66õ*-õ*.÷/2õ79ì65á32Ú1.×/,Ø/,Ù//Ü.-ç51é61æ81æ92ã;0à<0Þ>0Ú>1Ñ8*ïWLöbXÑ<6Ñ;:æPRÜFHæPQÐ;5Í9/Ç7,Æ8,Æ:-Å;.Á<-À;,½;-¾<.ÁB3ÇH9ÇI:ÂD5¾@1½=0ÇG:ÉF<ÍJBÔQIÖRMÓOKÒLIÕMOæ[^ï_húgqÿixû^oòPeñMeýNkÿWxÿTxÿTpõUmñ`oõkxömwógrùgtñ`mê`mèltØvw»nh¡h]•qaviXRK9gYL‘}t¼ œÞÂÁîÖÖÿíïýôõüúûûÿÿúþÿýþÿÿýÿÿûÿÿúÿþÿùûþõúýöÿþùÿÿúÿþúÿûõÿøòñèßäÜÑáÙÌðé×ÿúäÿÿæÿÿãÿÿèøùëîðåèêßQK;PJ:OI;MG9KE7IC5GA5GA5B;1A:0@91?80?82?82A96@;7@?:CC;HF9LF6NF1RF0SG/WH5YM?VKIZT^ki}¦‹“Ä“ ×›¤é¨«ú¬©ÿ®¬ÿ°®ÿ¯°ÿ¯°ÿ®°ý®°ý©­÷§«õ¤¨ï¢¦í¤è˜Ÿã“›Ü—ØŒ•ØƒŒÍw‚Àoy´kw«lp igŽn]‚[xQj GYºEU×FSìFPùAI÷=>î@5èE2áK3×M1ËN0ÂK-¼E'¼>'ÚQ>áMAáB<Ù54Ù35Ý8>Ü9>Ï57ÊA7ÇC6ÈD7ÌD8ÏE8ÔF:ÙG:ÝF;×=3Ø:1Ö8-Ö3*Ö3*Ø4+Û4,Ú6-Ú9/Û=2ß>4ß<3Ü:/Ú6,Ú6,Û7-Ð0"Ú=.Ù=.Ê3"Ä/Ë8$Í?)Ê<(Ç<'Î;+Ý<2î?:ÿAAÿÖ;7Ï60É4-Ç9/Æ<1Â>1À>0¸;)º=+½@.¿B0ÀA.À?,¾=*½;+ÂD6ÁE9ÄJ=ÌRGÏUJÍPJÍPJÒPPå`aëbiújsÿnzþfuôWhòSgúXoý`uõ`tãdoÛjpÜzyá‚€ÜtsÒ^aëcoñ`oïaqóp~쇋ˀ£wl~nhpYES4D=3B;3A:2@93A:4A96@;7A@;CC;HF9MG7OG2RF0SG/WH5WK=SHFXR\jh€}¦‹“Ä’ŸÖ™¢ç¤§ö¨¥ü«©ý­«ÿ¬­ÿ­®ÿ¬®û¬®û¨¬ö¦ªô¤¨ï£§î¡¨ì §ë¥æ›£ä–Ÿâ‘šÛ‰”Ò…Ê‚ŽÂ„ˆ¸ƒ¨‰xš’kˆŸaz®UgÂM]ÙHUêDNô*È:$À2Æ;&È5%Ó2(å61ú<<ÿ=@ÿ8=÷37è.1à..Ù--×/.Ü44ã9:é;=ñ8=û06þ-3÷/1ñ//ç0*ß1(Õ1%Ð2&È2#Ð>1új_ãTLÇ95ÏA@Ê<;äRSäJHÝB>Ò93Ê5.Æ8.Å;0Á=0¿=/¹<*¼?-½@.¼?-º;(¼;(½<)¾<,¼>0º>2¿E8ÇMBËQFÊMGÊMGÐNNçbcêahøhqÿo{ÿix÷ZkõVjý[rú]rõ`tåfqßntã€ê‹‰âzyÕadðhtþm|óeuíjxö‘•ì¢¡Á•ŠŸŽ~dlUESTKAÝCAÜCEá@Eâ>EÛBEÖDEÎDAÉ?<Ê:9Ï68îKNè=Cå4<ë:BíCFåABØ:9Ì73ÐA=ÌA<ÉC:ÆA8À@5»=1¶;,¶8*º8+À7-Æ8.Î70Õ62Ù42Þ20Þ2.è@3â;+ß5&á4&ä7'ä7'Þ5"Õ3Ö:$Ê3Æ4Ì;(Ì9'É3$Î4(Ü>5Ð2)Ó4.Ò8,Ó;.Ñ>,×A0ßF4éI9ûQDûHAù@;÷99÷69ó19ì/5ë)1ó,1ô,/ð..ì0.å3)ß5(Ø6'Ó8&Æ0Á.ôeTì]OÐ@7ÕD?Î:6ßMMäTTÙKJÍ=<Æ71Ç7/È8-È9+Æ7'Å:'Æ=*Æ?,¾;'·8%·:(·>+º@1²8+²8-¹=1ÂF:ÈJ<ÈH;ÉJ;ÍK=æbVå`Wíh_øsnöqlécbå_^îchóboõcpñakôdmÿsxÿ‚†ÿ|ðnlötrÿ{ÿ\mñOfÿ€‘ÿ³¸º¹¥†§ˆUoJDS2PW8geN˜‹{×úïÚÕöáàÿôõÿùýÿþÿýýÿüýÿüÿÿþÿÿõþûðÿøéÿðèÿîðÿòóÿò÷ÿðüÿñÿÿóÿÿñüôçùðßÿ÷æÿüçÿúåÿûãÿÿíÿÿúüüüûûûXO@XO@WN?VM>TKæ=@ÜB@ÛBDß>Cß;BÝDGÊ89ÌB?ÍC@¾.-àGIëHKìAGíÚ<;Ò=9ÐA=É>9ÊD;ÑLCËK@¼>2³8)¹;-»9,À7-Å7-Ê3,Ï0,Ô/-Ý1/à40è@3à9)Û1"ß2$æ9)è;+á8%Õ3Ï3Ë4È6Æ5"Ç4"Ê4%Î4(Ò4+Í/&Ð1+Ï5)Ï7*Ë8&Í7&Ð7%×7'Þ4'æ3,í4/ï11î-0ì*2ê-3ï-5õ.3ô,/î,,ë/-è6,ã9,Ù7(Ð5#Ã-Å2"çXGéZLË;2ßNIÇ3/ÚHHàPPÚLKÓCBË<6È80Ç7,È9+Ê;+Ç<)Ã:'À9&½:&»<)º=+·>+¶<-³9,µ;0¹=1»?3½?1¿?2ÀA2ÄB4ïk_õpgéd[óniøsnécbðjiýrwþmzûivócmï_hòaf÷hlônkñomûywÿ}ƒþYjÿ`wä_pû¬±¯®št•vZtOJY8LS4qoX£–†Ë·®ëÖÑÿïîÿö÷ÿ÷ûýùúüüþþÿÿüÿÿþÿÿøÿþìÿôâÿéâþèìÿîõÿôûÿôýÿòÿþñÿýïÿûîÿùèÿøçÿøãÿøãÿùáþùæÿþùÿÿÿÿÿÿ[OAZN@ZN@XL>WK=VJ?â=Aã=Aã5Þ;2Ú8-Ú6,Ý7+Û7+Ó7(Ì6%É<*Ã<)¼>(¼?-¿@/Â@3Á=1Ç7/Ö3.Û2-×4+Ð6*É6$Ä6"Å7!È7"Î7$Ó7(Ø6)Ù5,Ú3+Ú2/Ù40Ü43Û4.Ü5/Ü8.Ú:.Õ9*Ñ:)Î;'Í<'ÒA.¼)×C5Ô;3ÞD<òSPá?=ß??íSSæPOßJF×B<Ð;4Ì8.Ê8+Ç8*È;*Ä;)¾;)»<+º?-¹@/¶A0´>0¯;,±=0´>0µ?1¸@0º@1½C4ÂD6èj^ïofæc[ïkgõolèbcñklüszÿr~ÿo~õirë^fêY`òaføppÿyxýuwÿv~üQdÿYpæ[nú£©¬¥’m‹iZtMLa:P[9ruZ§ŸŠÓƶôãÙÿöïÿýöÿüøûþ÷ùþø÷ÿùøÿúùÿùôÿõêÿðàÿåàþâèÿçòÿí÷ÿîúÿîÿÿïÿþíÿýíÿûéÿöåýñáüðàþóáþõæþúñÿü÷ÿÿú\PB[OA[OAYM?XL>WK=VJ?â=Aã=AãBæÇG:»=.·8)º6'À6)Ç7,Ï6.×6.Þ71æ95é=9×3*×4+Ù7,Ú6,Ü6*Û7+×;,Õ?.Â5#¼5"µ7!µ8&¹:)»9,¹5)¾.&ã@;æ=8ß<3Õ;/Ì9'Æ8$Æ8"É8#Ï8%Ñ5&Ó1$Ô0'×0(Ø0-Ö1-Ø0/Ö/)Ú3-Û7-Ø8,Ñ5&Í6%Í:&Ð?*ÓB/Ã0 çSEÓ:2ÛA9áB?ëIGóSSîTTèRQäOKÞIC×B;Ð<2Ê8+Å6(Ä7&À7%»8&¹:)·<*·>-³>-²<.¯;,°.¹?0½C4ÃE7Û]Qèh_äaYðlhöpmçabìfgójqàR^ï^môhqòemñ`gõdiùqqþxwûsuÿmuõJ]ùQhåZmò›¡£œ‰b€^UoHOd=Va?ux]­¥ßÒÂÿîäÿøñÿýöÿþúýÿùûÿúùÿûùÿûùÿùóÿôçÿíÜÿáÚøÜàúßèüãïýæõþéüÿìýúéÿúêÿøæúñàôèØòæÖöëÙùðáþúñÿü÷ÿÿú\PB\PB[OAZN@YM?YM?XL>XL>UI;TH:SG9RF8RF8RF8RF8PF:ME:MG;PH;SJ9TL7WL6XK8XK;VL@VLJ]V]lhy|y–……«Œ¹’”Ä”–Æ•—Ê•˜Ï˜š×™œß›žãž¡æŸ¢åŸ¥ã›¡Û˜ŸÖ•œÒ‘šÑ™Ò–Ñ‘’È‘ƒ¦¥~›Át–Úf‹ñU|úEhö8Tì1Bè=CÞC?×G?ÖGAÜDCä?Fî9Hî9Hã?FÒ<=ÏA?ÎGCÂC<·81Ã@8ç\WÙCBàBCâ?@Ý==Õ;9Í<7É@6ÉC8ÎF8Ã9,¹4%Á<-ÇF3ÆE2¿>+»8&¿8%Å8'Ì8*Õ9-Ú8-á90é;4î<8ß-+á-.å.0ç/1è00è21ã41à72Ñ2,Î5/Ê7/Ç61Ç63Ê57Í79×49õ>B÷;<ë<7Þ:1Ñ8*É8'Æ;&Ç<'Ê?*É;'È5%Ê4%Í5(Ï7*Ì5*Ç5(Å9*Ä<,Å>+Ä=*Â;'Â;'Æ=*Ê?,Ê;*Ñ;-ö\PæC>Ø0-Ù+,ï<@ÿTVÿrpÿqlÿibú]VèPE×@5È4(½. Â9)¾9*¸9(¶;+µ=-²>/¯>.­=/«=0«=0¬>/­=/­>-±@0¸D5½G9ÅOCÜaYßb\ñqpöttã`eã^cå]gÓJTæZgñhpôgpöelýjrÿsvÿuxþouÿbpõBXúHbìTið–¥’cxWQlARi=Yj@w~\¬­ŽãßÆÿøåÿüìýþìüÿï÷ÿò÷ÿóõÿóóÿñîÿìæþä×û×ÌõËÈîÇÌîÉÕðÍÝòÑåõØïùÞó÷àø÷âûöãõìÛíáÓêÜÏðßÕôæÝÿóêÿöíÿøï\PB\PB[OA[OAZN@YM?YM?YM?WK=VJ0Á7*»6'¾9*¿>+¿>+½<)¾;)Â;(È;*Ï;-×;/Û9.à8/ç92ë95é75ç34ç02é13ê22é32ß0-×.)Î/)Î5/Ë80Æ50Ã2/Æ13Ï9;à=Bî7;ñ56å61Ù5,Í4&Æ5$Ã8#Å:%É>)È:&É6&Ì6'Ñ9,Ó;.Ñ:/Ì:-Ì@1Å=-Á:'À9&Â;'Ä=)Å<)Æ;(Í>-Ï9+Ø>2äA<Ö.+ç9:ã04â46Ø42Ø;6àC<çJCêRGêSHèTHäUGÉ@0Ä?0¼=,¸=-¶>.³?0°?/®>0«=0«=0«=.¬<.¬=,¯>.¶B3ºD6ÃMAÝbZàc]ïonôrrã`eå`eç_iõlvûo|õltí`ið_fþksÿx{ÿy|ümsú\jôAWõC]ëSh熥’i~]YtI^uIgxNˆf²³”çãÊÿûèÿýíþÿíýÿðøÿó÷ÿóòÿðëüéâóà×ïÕÅéŻ亹߸½ßºÆá¾ÍâÁ×çÊâìÑëïØóòÝ÷òßóêÙìàÒèÚÍìÛÑïáØôçÞòèßóéà\O?\O?\O?[N>[N>ZM=ZM=ZM=YLRH>ìC@âH@àHCäEIéBLò=Nï>NàEIÑFCÈC>ÊKD¶=2®5*ÈI@ÓLFÔE?Ø@=Ø=9×>9ÕB;ÑG=ÈJ<ÇI:¾9(Á8&À9&À9&½8%¼7$À9%Ã:'Ç:(Î;+Ô;+Û9,Þ8,â6,æ5+ì3.ò./õ(-÷&,þ(0ÿ-4ÿ.6ÿ,2û(/ï$(ð'/î)2í%2ë!1ï 4ú&=ÿ.Bù)6÷,2í/1ã/.Ö2)Ð4(Í7(Ï9*Ì4&Ï3&Õ3(Ü5,â:1ç<4ç<4à=4ÕF6ÉA1Â:*À8(Ä;+È<-È:,È6)Ð8-Ñ4+Ñ.'êA<Þ0/ò>?å.0Ü**Ø1)Õ4*Ö8-Ö:.Ò8.Ì5*Å2(¿1%ÎD9Æ@4¼[N>[N>[N>ZM=ZM=ZM=ZM=YLWK=XL>ìC@âH@àHCäEIéBLò=Nï>NÜAEÒGDÇB=ÈIB³:/°7,ÎOFÉB<Í>8Ï74Í2.Ï61Ò?8ÏE;ÅG9ÂD5¾9(Ã:(Â;(Á:'½8%¾9&Á:&Â9&Å8&Ì9)Ó:*Ú8+Ý7+á5+ä3)ë2-í)*õ(-ü+1ÿ,4ÿ/6ÿ/7ÿ17ÿ18ÿ59ý4<ú5>ü4Aþ4Dÿ2Fÿ1Hÿ1Eø(5÷,2î02æ21Ú6-Ó7+Ð:+Ñ;,Ì4&Ó7*Ü:/â;2å=4ç<4è=5â?6ÙJ:ÏG7ÉA1Ä<,Â9)Ä8)Æ8*Ê8+Ê2'Õ8/â?8ìC>Þ0/á-.ë46è66Ú3+×6,×9.×;/Õ;1Ò;0Í:0É;/ÖLAÌF:¿?2´9*°6)®6(«7*«7*¬;-®=/®>0­=/«<+«<+­<.¯>0ÀKAÚc[Ýc^èjkîpsêhpõrzüvígp÷oyùryöjsþlvÿvÿv}úgoúbnøQcÿA[ø;YìJaÞs{¶™‡Žžz}™i{—f€–g‘u«³ŒÉͬÞáÂèìÑëøÚäô××ïÏÎçÇÄß¾»Öµ³ÍªªÈ¢˜Â–˜đ¡É—¦Ì›«ÌŸ´Ï¤¿Ó®ÌÚ¹ÙÝÄäãÎìåÕïáÖìÙÓçÒÍäÏÌáÎÇÜËÃ×ƾ[N>ZM=ZM=ZM=ZM=ZM=YL:÷><ö=;ö<=ò>?ï?Bë@HèAKçAMáDMÑCAÍJBÀD:¿I=¯;.±;/ÐVIÃ>5É91È/*Å*&È/*Í:2ÍC8ÂD5¼?-¿<*Ã<)Ã<)Á:'Ã:'Æ;(Å:'Å6%Ç4"Î5%×7'Ý5(à4(ä2(ç2)ê2*ñ6-ù:2ÿ<6ÿ84ÿ/.ÿ))ÿ()ÿ*-ÿ+.þ%-ý!-ÿ#5ÿ%;ÿ"?ÿ7ÿ/ù 1ó'2î+3è.3à-0Ü./Ù//Ý/0á//ë14ô68ú6:ù25÷/2ö.0ð22êC=âE>Ý@9Õ81Î1*Ë.'Ï2-Ô51Ñ2,×4/æC>ß74Ü5/Ì#ç;7à93Ñ3'Ï6(Î6)Í7)Ë7+É6,Å7+Ä7-ãYOÚQGËF=Â=4¼9/»8.¼9/¼9/¹4+»6-¹9,¹9,´9*²7(°8*±8-²<0ÐYQÜb]ìppówyìmtôrzõs}þ{ƒÿ‰ÿy‚òisødpÿp}ÿtÿjvú\kúMaÿ@^ú7UìF\Ünq½ˆš©‚ƒžk~›e€˜fŒpŸª€³»”ÅϪÐ߸Èݶ½Ø¯®Ï¤¢Æš›¿‘—¸‹“´…Ž³€‰´|†¶zº”Á†™ÅŠÆŽ£È’®Ë›¸Ò¥ÅÕ°ÖÜÀãáÌèÞÒè×ÐáÌÇÛÆÃÓÁ½Ì½¸Æ·²ZM=ZM=ZM=ZM=ZM=ZM=ZM=ZM=XK;XK;XK;YL]N;^O<\O<\O>YM=YMAWLFYMMZQT_U^aYfc\nkepjŒuo›xq¥{u³„}ÁŠƒÇŒ‚lj~ÀŒ~¼‹x°‡p¦Œo¥“r§Œi¡Y€™DGª@3¹@5ËE<ÛB<ä<9ð>:þEC÷><õ;<ð<=î>AìAIêCMèBNàCLÎ@>ÄA9¼@6µ?3°3´6'»>,º7%Á:'Ã<)Â;(Á8%Ä9&Å:'È9(Ì9'Ñ8(Ö6&Ù1$Ú."á/%ì7.õ=5ô90õ6.ö1+÷,(ù'&û%%ü$%ü$'ý%(ù (ü ,ÿ%7ÿ&<ÿ;ÿ4ÿ1ÿ'8ï#.æ#+ä*/ß,/×)*Õ++à23æ44í36ò46÷37ö/2ô,/ò*,ê,,ß82Õ81Õ81ïRK¾!Ç*#âE@Ë,(Í.(ß<7èE@â:7×0*Ø/*á51ä=7Ý?3Õ<.Î6)Ê4&Ê6*Í:0Ê<0Å8.ìbXâYOÈC:º5,¼9/º7-´1'·4*³.%´/&±1$²2%±6'´9*´<.µ<1°:.ºC;Ö\Wìppðtvöw~ûyôr|ÿ|„ûx€út}üs}ÿr~ÿq~ÿmxÿgsý_nõH\ÿ>\ÿ=[æ@VÔfiµ•€’¡zƒžk}šd}•c†—j”Ÿuž¦ž¨ƒš©‚¥~‰¤{ uxœpw›m|p€¡r¦s‚­uƒ³w‹¸}½‚“¿„–¿‡š¿‰¡¾Ž¤¾‘®¾™½Ã§Ï͸ÝÓÇãÒËÜÇÂÔ¿¼Ìº¶Á²­¹ª¥\L<\L<\L<\L<\L<\L<\L<\L9º>4³=/°<-ª;*®:+¿A3ÒI?ÝE@ß@=Ø42Õ30Ù>9Ó@8½7+¶2#½8'Â;(Å<*Å<*Æ:)Ç:)È9(Ë8(Ñ8*Ô4(Õ1%Ý1'å4*í6.ð80ï:1Ü6&Ù6%Ü5%ã3&è2'î2)ò2-ô20ñ//î*.î)0ø,8ý*=ü :ù4ó1ì!4ð0=ð4Bã+7Ü&2à*6â,8â&4ö6Cù3Bû1=û/:ö/6õ15ö45ò89Þ1-à85Û64èCAçCBÑ-,Ó1/Ã!Ô52ß@=äG@Ü?8Ó6-Ò5,Ö:-Ö>0Ì?.Æ=+Á9)À8*Ã;-Æ>2Æ=3Ä:0íb[åVPÍ>6Ã0)Ê5.Í6/Ê1)Ð3,Ï-(Ï,'Ì-'É/'Ä0&À0%»3'·3'¹9,¿@7ÔYRèljïqröx|ü~‚öw~ü}„ûyøv~þuÿtÿpÿjyþcsÿ^pøH_ÿ>\ÿ>\éCWÓef®Žu‹˜mz•bu’\xŽ]c‰–j˜nˆ—nƒ•knˆ[jŠ[e‹XfŽZi’Zp—`wdz gƒ¬p…±tŠ¸x»{½|‘¾}“¿€—¿ƒ—¸ƒœ¶‡©¹”ºÀ¤ÍÈ´ÕɽÕ»μºÂ¸¹´®²¬¦ª\L<\L<\L<\L<\L<\L<\L<\L>÷:@û9Aù;Eð?GæAHÖACÌB@¿;6¶:0¯9+­9*¨9(­9*½?1ÏF<ÛC>Ø96Ú64Ü:7ÝB=àMEÎH<¶2#¾9(Á:'Ä;)Æ=+É=,É<+É:)Ì9)Ð7)Ñ1%Ó/#à4*î=3õ>6ñ91é4+Ü6&Ú7&Ü5%á1$å/$ê.%í-(î,*ï--í)-í(/ö*6ú':ú8ø3õ3ñ&9ð0=ñ5Cñ9Eð:Fñ;Gê4@æ*8ñ1>ô.=÷-9ø,7õ.5ó/3ò01í34Ý0,ä<9Û64à;9ÿlkæBAÑ/-Ð.,Ù:7ß@=ßB;Ú=6Ô7.Ó6-Ó7*Ï7)Å8'À7%¿7'Á9+Ä<.Å=1Å<2Å;1ë`YâSMÊ;3Â/(Î92Ô=6Ò91Ø;4Ý;6Ý:5Ù:4Ô:2Í9/Ç7,¾6*¹5)º:-¾?6ÏTMãgeíopøz~ÿ‚†û|ƒû|ƒûyúx€ÿwÿtÿn}ÿgvû`pü[m÷G^ÿ\ìFZÎ`až~ex…Zi„Qh…OmƒRt…X{ˆ\}ˆ^v…\p‚X`zM_P`†SeYm–^uœe{¡h~¤kƒ¬p…±tˆ¶v‹¹y‹¹xºy»|“»‘²}“­~šª…¨®’ºµ¡Æº®Ë¸±È¶´·­®¨¢¦ž˜œ[K;[K;[K;[K;[K;[K;[K;[K;ZJ:ZJ:ZJ:[K;[K;\L<\L<]L<]L<^K<^K<_L=^M;_N<^O<^O<`Q>`Q>_O?^N>^N?^N?_O@`OGdOVhSdgYrj_pi’|v¢…~ª‰|§ž†ª­„¤¼}˜ÊtÝqˆìlƒéYråAYö9Oõ4Eæ8AÜ=AÒD@ÏF@ÏF>×C?äDDí@Dñ@FòAGéEFÞDBÍD>ÂB9¼@4µ=/¬;+ª;*ª9)°8*½=0ÑB:Ø;6Ù10æ89ë??æA=îQJãSHÄ8+Á9+¾6(À7'Æ:+É=.Ë<.Ì8*Ð6*Ð2'Ô0'Ü1)æ81ó=9ö=:ð50è,*ç10ç02è.1ê+0í*0î)0ì)1ë)2ç)3ã'5ä):é,Bì*Dì%Dð"Fð)Hñ:NÛ,9Ý3@ýS`ÿbrþRbî=Oï:Mâ,;ä.;æ2=å8<Ü=:Ó<5Æ8*À4'Ê7-Ð;4Ë60ÜGAÿvrîYUØ@?áIHÕ@<Ô?;Ñ<5Î:0Í9-Ì8*È7$Á6#´:#¯:&³<(¸?.¹?0º<.¾;1Å<4åXQàKGÏ4/Ï+)à93é<8ç60í62ø66ù56õ86ð95æ92Û7.Ð6*È5+À6)¿;/ÎNEâc]ìomú|ÿ„‡ýƒøy€úx€ûyÿx‚ÿt„ÿmýdvù^p÷VhóE\ý8Vþ=ZëJZÄ[X‡nPbsGZuB]xEfyKm}PtVvƒXrXm‚WlˆXlŽ\n–asžh{¤j¨o„ªm‡«n†¬q‰¯tŠ´tŠ·v‰¸t‡¹tˆºuŒºyŽ¶xŒ­x¦x˜¦ƒª­’»´¢Å¹«Ä¹µ®­µœŸ®“¢[K;[K;[K;[K;[K;[K;[K;[K;ZJ:ZJ:ZJ:[K;[K;\L<\L<]L<]L<^K<^K<_L=^M;_N<^O<^O<^O<^O<^N>^N>^N?_O@`PA`OGcNUePacUneZzleŽxržx¤ƒv¡–~¢¯†¦Çˆ£Õ˜áuŒéi€åUnä@Xû>Tÿ@QõGPåFJÒD@ÍD>ÏF>ØD@äDDîAEòAGóBHêFGÞDBÌC=À@7½A5µ=/¬;+ª;*ª9)°8*»;.Í>6ãFAä<;ïABíAAß:6æIBçWL×K>È@2À8*¼3#Ã7(È<-É:,Ë7)Ñ7+Î0%×3*â7/é;4ï95î52ë0+ç+)å/.æ/1é/2ï05ô17÷29÷4<÷5>ë-7è,:ê/@î1Gð.Hò+Jú,Pü5Tñ:Nã4AìBOÿanÿl|ÿXhôCUô?Rë5Dê4Aé5@å8<Ü=:Ó<5Æ8*¿3&Ç4*Ä/(Í82ïZTó^ZïZVÚBAáIHÙD@Ò=9Ì70Ë7-Í9-Í9+É8%Á6#´:#¯:&³<(·>-¶<-µ7)»8.Æ=5ÛNGÚEAÏ4/Ó/-ä=7ë>:ç60ë40ñ//ó/0ð31í62å81Ü8/Ò8,Ë8.¿5(»7+ÉI@Þ_Yënlû}€ÿ…ˆýƒõv}øv~ûyÿx‚ÿsƒÿk}ýdvù^pôSeôF]ý8Vþ=ZîM]¾URy`BWh?î;>é58Ý1/ã>:ñXPøe[ÚPCÉA3¾4'Â6)Ç9-Ê7-Î6+Ô7.Ò/(Ü5/ç:4ë95ë31ê.-ê-+ò)/ÿ*@ÿ&Cÿ&Dÿ&Eÿ&Eÿ&Dÿ(Fÿ(Gÿ*Hû+Kù0Rù1V÷,Wø*Zÿ/`ÿ=fá5KòR^ÿdrÿbpúYiõRcíHYâ;MêEUß?KÎ9=¿84µ<1¬C.¢H-¤F*³C/³8(ÎPBðpeÔQGÚSMÆ?;É>;ÚOJÐC<Ç80Ç9-Ì=/Ë<,É;'Á=(®>(¦='¨?*®@/¬;+­4)·;1ÉD=ÖGAÛB=×52Ü0,ì95ñ85ï/*õ.+ý')ÿ'*ü*+ù/-ð3/é6/à90Ø<0Æ4'¿2(ÆA8ØWQéifú|}ÿ‡‡ý€„õw{ùwüz„ÿw„ÿqÿi{ûbtø]oðQeöJbý:Xý?[îP_¹QNnZ9Qg8]uEc{KnTv…Z{‡_~Šbg‚—l€œl}Ÿm|¥m}¨p€©m‚ªnƒªk…©l‰«oŠ­s‰°qˆ²r„³mƒµn„¸p‡¹t‰¶u‡­r‹§v˜ª‚¯¶•ÆÄ­ÕμÙÒ̽Ãϧ²Æ—¢¶ZK8ZK8ZK8ZK8ZK8ZK8ZK8ZK8ZK8ZK8ZK8[L9[L9\M:\M:]L:^K<`J<^K<_L=^M;_N<^O<^O<^O:_P;`O;aPÉ@6¾>1¸>1®:+¨7'©:)­<*´<,Á=1Ñ>7ß=:æ89ã03ã/2à42Ý84æMEþkaòh[ÙQCÆÿ<ú<ú%Cø(Hö-Oö.Sô)Tö(Xÿ1bÿAjðDZÿamÿiwõWeìK[ïL]éDUÙ2DçBRÙ9EÄ/3³,(ª1&¤;&C(¡C'²B.·<,Ù[MÞ^SËH>ËD>¾73Ç<9áVQÔG@È91Ç9-É:,È9)È:&Â>)¯?)¥<&¥<'«=,©8(¬3(º>4ÒMFÖGAÞE@Û96Þ2.ê73í41î.)÷0-ÿ+-ÿ*-þ,-ù/-ð3/é6/á:1Ú>2Ë9,¿2(À;2ÏNHáa^÷yzÿˆˆÿƒ‡ù{ý{ƒþ|†ÿw„ÿn~þew÷^põZlëL`õIaü9Wû=YìN]²JGfR1Oe6\tDf~Nuˆ[Žc„h†’jˆ—n‰žsˆ¤t„¦t¨p}¨p¨l©mƒªk…©l†¨l‡ªp†­n…¯o°j€²k‚¶n…·r‡´s‡­rŒ¨w›­…²¹˜ÈƯÖϽÙÒ̹¿Ë¢­Á›¯\J6\J6\J6\J6\J6\J6\J6\J6\J6\J6\J6]K7]K7^L8^L8^K:]K=]K?\L=]M>[N=\O>[P>[P>]R@_RA_RAbQAbPBbOAcMBcJClMHkMOdQWcXiggqw›v}©wy©„}©„¬¶ˆ¥Ê‚–Ü}ƒëuséeXäQIÝAEéDRíGSëANê>Jí>Kë;Fä6@æ;Aã=AÞ@?ÚB?ÕE=ÍC9Å?3¼>0°C/¨=+¨9(²:,½:0Å:3Ñ>7ÜA=×82Þ93×3)Ý7)à?-Ó2Ô6óR>ÿqhùTPÛ>5Ñ9.Ë<,Ç8(È9)Ò<.Ù80à74è45ë07í-8ð-;õ0Aý3Aú)/ÿ(-ÿ)+ÿ)+þ((ü&&ö$%õ#&í!ï"'ñ(0ð+5í*8í,=÷;LÿJ\ÿdpÿ_júV]õPVöPTñNOßD?Ê:1ËG:»B1¨;'ž7$:%ž=*ž=, :,¦:0®84ÑVQ½97È<;Ã12Á//Ô@@æWQÖGAÇ:0Ä6,Å5*Ç3)Ê1)É6.»7+²4(µ0'»2*»,$½*#Í:2åNGÞG<äG>Þ;2ß2,ë40ñ//ö*-ý14ô02ò01ñ//ð,-î,*ë.*ä1*Ý5,Ô<.¿3$»9,ÅK@Ô_Xízwÿ‹‹ý‰Œôƒ…ü€ˆÿyŠÿo†ÿd~ÿYuÿRoÿNlö=]úAaî9ZàB[ÉWa“PJXL4Oa;Tq;^€Dm‘Txœ_z e|¢g~§k‚«o‡°t„­q‚ªn§k~¤g€¤g¥g‚¦i¦m€©o€¬o€­l®h€°fƒ³g‡µj‰·lˆ±mˆ°q’µ¡Â“±Í¥¹Ô³¾Ô¿²Áº «­˜š]K7]K7]K7]K7]K7]K7]K7]K7^L8^L8^L8^L8^L8^L8^L8^K:\J<]K?]M>\L=ZM<[N=\Q?^SA_TB_RA^Q@bQAcQCdQCdNCdKDkLGiKMdQWf[lll†v| ~…±†ˆ¸‹„°¡ˆ°¸Š§Ëƒ—Û|‚ëusònaøe]íQUèCQä>JëANïCOí>Kê:Eê4Á;/¸:,¥8$­B0¬=,®6(Â?5ÏD=Ï<5Ñ62Ø93Ü71Û7-Ý7)Û:(Ý<(Ù;"Ö5!Ý90õPLõXOÜD9Ç8(Í>.ÒC3Ñ;-Ô3+ðGDâ./ï4;ô4?î+9ÿ@Qñ'5ù(.ÿ*/ÿ+-ö "ú$$ÿ))û)*ð!î "ù,1ê!)ì'1ñ.<å$5ÿ[lå.@ÿ^jÿ^iþZaúU[öPTëHIÛ@;Ê:1ÅA4¾E4°C/ 9&—4—6#›:) :,¥9/­73ÁFA¿;9¾21Æ45Æ44×CCÛLFÚKEÑD:È:0Ä4)È4*Ì3+Ç4,¿;/¶8,±,#¯&¹*"É6/ÕB:ÝF?æODáD;Ú7.Ý0*ç0,ó11ü03ý14ô02ó12ó11ó/0ò0.î1-ç4-à8/Õ=/¾2#À>1¸>3Õ`Yçtqÿù…ˆùˆŠÿ„Œÿwˆÿf}ÿ]wÿYuÿSpüIgüCcò9Yñ<]àB[Óak†C=SG/L^8Yv@e‡Kt˜[zžaz e}£h¨l€©m¨l~§k~¦j}¥i}£f£f£e£f~¥l~§m«n¬k~­g¯e±e„²g‡µj‹´pŠ²s°z•¶‡£¿—ªÅ¤­Ã®¤³¬˜šz…‡\K7\K7\K7\K7\K7\K7\K7\K7]L8]L8]L8]L8]L8]L8]L8]L8]J9_L;_N<_N<[N=[N>ZQ@\RF]SI[PJZOI\NM\NM_OP_OR_OR_QQ]RZ]Vha`‚jnžv{»}…Î…†Öš“៉Ѥ~·±x¡Æ}‘܈ã|uéngô_aóOXìGNòHQùITöDPò>Gì;Cç8=â9<Ú;8Õ=8ËA6Ä@3º?/µ=-«<)­>-©8*°:.¾B8Á>6À:1Î?9Ë80Ð7/Ó6-Ö6*Ø8*Ü9*Ü9&Þ6)Þ6-é@;íLBäH<Ó=.Ì6'Í7(Ö:-á:2øIFç//ó4;ø6>ò.:ÿ@Lì(4ì'.í)-ñ-/ó/1ò./ï+,î,,ï./æ((ã),â).ô?FÒ'é7CôFPÑ*4ÿlsþejû\`ûX]óPQåBCÙ;8Ô<7Ã6-Å@7ÂD8³80£*!œ#œ!"¢+%´94ÔRPÑGGÄ44É35Ò<;ìVUÚFB×FAÐB8È8/Æ3)Ì5,Ñ7/Ó40×53Õ/1Ô,,Ö)+Ù,.Þ13ã:7æA=êG@â?8Ú6-Ü1*ä1,ï31õ33ø23ô02ô02ö01õ/0ó0.ð0-ç4-à8/Ö>0¿3$¾aP>]P?\O?YP?[QE[QG[PJZOI\NM^POaQRdTWeUXdVVcX`e^pji‹rv¦|Á‰ÒŠ‹Û—ÞŸ‰Ñ¨‚»¶}¦Ë‚–à…Œèzïtmúeg÷S\íHOðFO÷GR÷EQô@Iî=Eå6;à7:Ù:7Ô<7ËA6ÅA4»@0¶>.­>+«<+«:,¸B6ÅI?¿<4¸2)É:4Ê7/Ï6.Ô7.Ø8,Ø8*Ú7(Ü9&á9,Ý5,Ü3.âA7ëOCÞH9Ê4%È2#Û?2ä=5öGDé11ó4;ù7?ø4@ÿEQ÷3?î)0è$(é%'ö24ò./ì()é''ó23è**ó9<å,1ß*1è4=ÿR^í?Iÿ]gü_fðW\îOSðMRéFGÝ:;Õ74Ö>9Â5,Â=4¿A5¶;3¯6-ª1)¥*% % ›$ª/*ÇECÄ::¼,,É35×A@ô^]Ò>:ÓB=ÐB8Ì<3Ì9/Ô=4Ú@8Þ?;à><ß9;ã;;ê=?é<>å8:ç>;íHDã@9Þ;4Ù5,Ý2+å2-ï31ô22÷12ô02ô02ö01õ/0ó0.ð0-ç4-à8/×?1À4%º8+µ;0Ð[Tízwÿ“’û‡Šû‚‰ÿ}‰ÿr‚ÿdyÿ[tÿTqÿMmÿEgü=_ô=\ëGbÝVgžCHn<3QI2Qa=]xEh‡Nr“Zv—^tš_xžc{£g{£gy¢fy¢fy¡cx by ay a| bz cz¢f{¤h{§h{¨e{©a{©`}¬^­b‡³h‹´nŠ²s‰¬t†¦u‚žuy“no†jSeYAPK2A<^M;^M;^M;^M;^M;^M;^M;^M;^M;^M;^M;^M;^M;^M;^M;_M9^L4bN6aQ8`Q<]P?XNBXOFWOMUOQXQY[Uc^WiaWocYtf\wd^zbcxagem’ku¨u~Á}†Õ…ŠåŒêŒ†ÞšŒÛ¦ŒÉ¨…¯­€•¸„ˆÇ‹€Ý‹}ózq÷hdðZYïQRðJLòEIò?Eð;Bæ69ã68Ü86Õ<6Î@6ÅA4¼A/·?.®8*±;/±<2»F<ÈSIÁKA°:.°6+¾>3Ã=2Ì>4Õ>3Ù;0Ù5+ß5(ã7-â4-Þ1+ã<3ïMBçJ;Ö9*Ö6&æ@2â6,ó=9ë/-ó04÷48ý8?ÿOWÿNUóCFæ9=Ö)+á46ß12å78Ü00à44ç??Ç!Ü89Ô14Þ=BèINø]aìQW×>@ÛACâBDâ=Aá8=ß6;Ü6:Ù69Ï57Ê46Æ45Ë:?ÙFLäNWÝGRÏ7Õ>5ÛA9áC:é=;ù7?û/;þ0=ÿ6Cý4>ö.8÷8=ÿHJå63à40Ú3+Ü3,â5.è50ì5/ð31ô01÷/2÷/1ø-0õ/.ñ/-ê3-â7/Û?2Ã5'·5(³9.ËVOï|yÿ“’ÿ†‹ÿ~‰ÿw‡üoûdwýYrÿNmÿChÿXNBXOFXPNWQS^W_f`nmfxqgqg‚qg‚nh„lm‚lrŒowœs}°y‚Å~‡Ö„‰äŠ‹è“å›Üž„Ášw¡›nƒ¥quµynËykîulýnjþhgý_`ùSUôGKï3Û=2Ú6,Þ4'â6,á3,ã60ä=4æD9ãF7ßB3à@0ä>0Ü0&ì62ì0.ð-1ñ.2û6=ÿPXÿ]dÿ\_þQUÝ02ß24Ü./ôFGä88Ú..×//è?BØ45×47ÿchÝ>CÇ,0É.4À')Õ;=áACÛ6:Û27á8=Ý7;Ð-0Í35Ð:<×EFáPUð]cûenøbmî[cÅ?>ÉC@ç]ZùggÿonÿjjæKI×=;Ë3.Ò=7×D<×B;Õ>5Ö<4Ø:1ß31ô2:÷+7÷)6ù+8ó*4ñ)3ö7<ÿIKá2/Þ2.Ú3+Ü3,â5.è50ì5/ð31ô01÷/2÷/1ø-0õ/.ñ/-ê3-â7/Û?2Æ8*´2%²8-ÃNGï|yÿ’‘ÿ‡Œÿ~‰ÿu…ùl|øatùUnýHgÿ=bÿ8_ü5\ñBaÛPe½Yak2+[A0YW>^lIe}Ml‰St’\w•_v™_zcy¡cx buŸ`uŸ`u^vž_wž_xŸ`{Ÿaz¡bz¢c{¥e|§b|§`y§\y¨Z{ªZ}¬^€¬_…¯g‡®mˆ©p…¦q„Ÿr{–mt‰jexb[l\RcS^O<^O<^O<^O<^O<^O<^O<^O<^O<^O<^O<^O<^O<^O<^O<_N:^M3aM4_O8^N>ZNBXOJXRVWT_\Ynda~nmvtœvt£tr¤to¥po¨lr¬lv±rz¸w½}ƒ¿‚‡ÁŠ‹Á‘Àš”ºš«˜Œš‹‹ Ÿ‡oŽvT‡\<¥YA½\KÍbRÙ`Uà[TåQOãCCà7:è:<ç9;ã99Þ:8Ú=6Ô=4Ê<0Ä:/º5,¿?6¯3+¦-$»K@×h]ÒhZÄXK°@2±9+¹7*Ê<2Ö<2Ú5/ß2+æ5/á/+å61å:2ß8/à=.çD5çA1ã7)â0&ë3+ò2/ï--ì,+ñ33ÿGHÿX[ÿ`dþ_dÜ;AÜ;AÐ-2ïLQÝ:?Ó05×6;É(-Æ*-ôZ\Ù@CÑ;=Í8:º "Ë%'æ8:ð=Cç/7à(2å-7à,7Ó%/×08éGRú_gÿfpýanû]kÿ\mÿ_kÛIIÛLFïZVîTRëKKèEFÒ30Ð2/Û@;ãJDæOFâIAÚ@8Ø93Ù4.ß--ø0:þ+:û)6ø&3ö(4ù0:ÿ=AÿIJâ0,Þ3,Ü4+Ý5,â4+ç4-í4/ò21ô01ù.2ù.1ù-0ö..ò/-ë2-ã6/Ú<0Ê;-´0$²6,ºC=îxvÿÿ†ÿyŠÿm‚ùfy÷^sùRlüCcÿ7`ÿ5_õ9\åKc¿W`RMT=-MH2W[B`kKhzPn†Vt]x”ax™`|dz cw`sœZsœZsœZt[v^wž_{Ÿa| by¢^{¤`|§_{¦^z¦Yz¦Y|¨Y}©\©]„¬e…¬i‡©l‰§q‰¥t„žo|•muŠimeey]_P=_P=_P=_P=_P=_P=_P=_P=^O<^O<^O<^O<^O<^O<^O<_N:aP6cO6`P9^N>[OC[RM\VZ]Zejg|roŒ{zœ€~¦~|«zxªytªvu®rx²r|·x€¾{ƒÁ€†Â…ŠÄŽÅ–”Å›•»¡—²ªž¬»©©Ä±£Á©‘¤Œj•jJ•I1¦E4¯D4½D9ÐKDäPNëKKé@Cë=?é;=å;;à<:Ü?8Õ>5Ë=1Å;0¾90¿?6°4,©0'ºJ?ÑbWÓi[ÒfYÀPB¸@2¸6)Æ8.Ô:0Ù4.ß2+ç60â0,ã4/â7/Þ7.á>/æC4ä>.ß3%æ4*é1)ò2/ð..î.-ð22ó78öBEóNRùZ_çFLóRX×49êGLÜ9>åBGØ7<Î-2Î25ãIKÑ8;Î8:¸#%Õ;=Ý79è:<î;Aì4<ä,6à(2ä0;é;EòKSþ\gÿksÿisû_l÷YgúWhúZfõccéZTëVRÙ?=Ð00Ö34Ó41áC@äIDêQKêSJâIAÙ?7Ø93Ü71å33õ-7ÿ/>ÿ0=ü*7ü.:ÿ;EÿBFûABã1-ß4-Ý5,Ý5,â4+æ3,í4/ó32ô01ù.2ù.1ù-0ö..ò/-ë2-ã6/Ø:.Í>0µ1%²6,²;5ésqÿŠŠÿ†ÿu†ÿh}ôatô[p÷PjûBbÿ7`ÿ7aø<_èNfºR[x;6W@0LG1UY@ZeEewMl„TrŽ[w“`yša|dxžatš]p™Wp™WqšXqšXt›\uœ]y_zž`x¡]y¢^z¥]y¤\x¤Wx¤Wy¥V{§Z©]ƒ«d„«h†¨k‡¥o†¢q€škx‘iq†ej~bbvZ_O?_O?_O?_O?_O?_O?_O?_O?^N>^N>^N>^N>^N>^N>^N>^N>bQ?aQA^PEZOIXORYS_\Yl^^zqq—vw¥}€µ¼z~½ux»sv»tvÃuyÐz|Ó€‚̆‡À‹‹¯“’¢ž›–§¢Œ³­‰»³…Áº„È¿ˆÎÅŽÑÇ’ÊÀ‹Ä³‡—{V’iMŠT:ŽJ5ªSBË`VÛ`YáUTßEEä?Cå==ç:<æ::ã77Ü41Õ30Ë3.È93¾71¼<3ÄNDÈXLÇ]OÐfXÐeUÁM@·<-Â9/Ñ:1Ö4/Ü3,ä71ä52à3/Þ5.ã<4çC7èB6ä:-â1'ê5*è-$î1+í0,í4/í73â0,Þ52äDFôY]ôX\ÿquäDLèHPÞ=Eü[cÿowÞ=Eÿ|„ÿksëPV×2¹/%·4,²51ëooÿ†ˆÿ…Žÿn‚ÿ`x÷YpùUnûLkýAdÿ;cý@fèHdÓZižZYT7)LJ3AJ/RT`P@`P@_O?_O?_O?aQAbRB_O?]M=]M=aQAcSCbRB`P@dSA`P@]OD\QKZQTYS_datqqxxžz{©}€µ¼{¾vy¼ps¸ln»rvÍxzÑ€‚̌Ƙ˜¼¦¥µµ²­¿º¤ÍÇ£ÖΠÙÒœÛÒ›ÛÒ›ÜÒ×͘ÕĘɭˆ®…i˜bHÂ~iÏxg¶KAÐUNñedæLLä?Cá99æ9;å99á55Ü41Û96Î61Ã4.ÈA;¼<3¿I?ÇWK¹OAÎdVÏdTÌXKÃH9Ã:0Í6-Ø61ß6/â5/ß0-ß2.à70ä=5à<0Ý7+ß5(ç6,ä/$ê/&ì/)î1-ì3.ê40ç51à74×79åJNõY]ëOS×7?Ö6>ùX`ÿ~†ÿ~†ÿowÿgoÿhpÿflö[añX[ýZ_ÿTZÿBKÿ7Bÿ5Aù1>ï+9î0<òAX.?U.æ36â24Ý97Ò50Ñ<6Á2*¾;1ÄH<ºF9Ì[Mám^×_QÆH9½5)Á2$Ñ7-Ø7-Ö1+Þ63â:9á>9ß<7Û8/Ù5,Ý5*â6,ê8.ë6-ê3-ç2+à3,Ý5,Ù8.Ö90Ð;5Õ@<áKJòXZù_aú]dý]eÿakôR_ïMZñQ[ÿ_iÿjsÿenõZ`ôMTî3:ô+3ô+5ù-9ñ'3æ /ç'4ï7CþPZÿZbÿbhÿciÿdjÿbiÿZaùPUìC@å95á40ã41å31à1.Þ1-Þ50á>7Þ=5Ù;2Ú91Ü71à72ç85ç98ä<9á<:ã;8ç;9ç;7æ95ß6/Û4,Ù5+Û7-Þ8,â6,ç2)í0*ó0,÷10õ12õ13÷12÷/1ö0/ò0.î3.ç60à<2Ö<2Å6.¹0*¼44ÞW[ÿ“ÿq}ÿd{ÿ[xÿRqÿIkÿBfü>bóAcãIcÐZj¥UXjB8E6#9;%=A*GF1RR:XcCaqLnƒZwŽ`w’]t“Xq“Vp”Tk“Ml”Nl•Om–Ro˜TqšXsš[sšYt›XuWvžWvžWtžVsUrœTqšTo—Qn’RhŒNbHXu?Nh8F^.@W)>X)>X)?Y*YL<[N>^QA^QA^QA^QA_RB`SCaTD`SC_RB`SCaTDaTD`SC^PE`UO\PRZQVaYfidxpmŠuu™x{¨x{°y}ºw|¼nr¹cj²`f°hnºruÆ}|ÙˆƒÝ—”Ùª§Ö¼¹ÌÍÊÃÝظçá¯éæ£íé ðé¡íæ¢çá¥âÛ§ÖÏ£Éß²±“¢ž…”…n¡†s rb•UI³`X×pkðxwéaaáKMâAFëADí4ßB9Ã.(Ê51ÚDCðVXù_a÷ZaóS[ñQ[èFSêHUïOYü\fÿmvÿmvôY_ä=Dé.5õ,4û2<þ2>õ+7í'6ö6CÿKW÷ISöOWøW]ÿ^dÿciÿ`gøQXëBGá85á51ä73ê;8í;9ç85â51Þ50Ý:3Û:2×90Ù80Ü71á83è96é;:â:7à;9â:7æ:8æ:6å84Þ5.Ú3+Ú6,Û7-Þ8,â6,ç2)ì/)ó0,÷10õ12õ13÷12÷/1ö0/ò0.î3.ç60Ý9/ÝC9Ç80½4.¶..å^bÿ‚ˆùkwÿaxÿVsýNmÿJlÿBf÷9]ï=_æLfÍWg—GJf>4N?,;=';?(ED/HH0Q\U'B\-E_0Ic4WJ:ZM=\O?^QA]P@^QA_RBaTD`SC`SC`SCaTDaTD`SC_RB\OIVOWWOd\Xqfc‚nl“st¢wx®w{¸v{»qx¾jrºai²\d­`h±lr¼x|ʼnŒÓ”•Õ£¤Ú´¶ÝÄÄÜÒÑÙÜÛÖäáÐåãÊëæÉêäÊæÞÉà×ÆØÎÄɾºº²¯¡¤›–™ŠŠ€Ž„{‹wn‹i`¡pi½zt甎ã}yÚbaØRQÝIIãEFå??æ<<ä86â94åB=Ü?8Ë6/Ã6,¸2'°.!ÆF9á_RíiZÜREÈ;*É5'Ð8*Ó6-Ô63îNPø]YèMIÖ92Ó4.Ù5,Û2+Ý/(Þ-'Ü.'Ú/'Ö3*Ó9-Ò>2ÐB4¼3#À6)È>1ÕF>ÙJFÜGIßJNèNVíS]óWbôZd÷]gÿhrÿmwñZaÛ<ø?=ó;9é73ã60Ý90Û8/Ù8.Ú7.ß61ä73ë76ì87å97å97å97ç98è96æ74à5.Û2+Ú6,Û7-Ü9*á7*ä3)é1)ñ0)ô1-ñ42ñ33ó32ó11ô1/ò0.ì3.ç60Þ7.âE<Ì71Â1.¹*,ódjÿv€üetÿbyÿSqÿFkÿBjÿ:eò5[ÞD`ÏZj®devKB[H9XP=JE1G@-MF3HC-LU8Tb?btNm‚WrŠXoŒTmNjKgHhIh’Jj“Mk”Pm–To–Wp—Xv›XušWq˜Uo–Sj“OgLeŽLdŒM`‡H]€FWx?So\O?]P@]P@_RBaTD_RB`SCaTDaTD`SC_RB_RB^QKTMU_Wlkg€spvt›vw¥xy¯w{¸sx¸jq·_g¯[c¬_g°jr»v|Æ€„Í“–ÝžŸß­®ä»½äÉÉáÔÓÛÛÚÕáÞÍâàÇæáÄãÝÃÞÖÁØϾÎĺ¾³¯­¥¢—š‘‹Ž…††|‡}tŒxo—ul¡piµrlߌ†éƒíutígfíYYíOPëEEê@@å97ã:5åB=áD=Ï:3É<2Æ@5²0#¯/"ÊH;ÜXI×M@Ë>-Ì8*Ï7)Ð3*Ó52õUWÿlhø]YâE>Ú;5ß;2á81â4-ã2,à2+Ü1)Ó0'Ê0$Ä0$¿1#Ã:*¾4'¾4'Ê;3ÔEAÚEGØCGÚ@HßEOëOZñWañWaù_iÿgqñZaáBGæ<<ê67é56ì39î5;ô;CÿISÿV_ä6?Þ3;à69í@DüILÿGL÷:>í/1ê41î84ñ;8ó;9ô;9ñ97é73ã60ß;2Ý:1Û:0Ü90à72ä73é54ê65æ:8æ:8æ:8è:9é:7ç85á6/Ü3,Û7-Ü8.Ý:+á7*ä3)é1)ñ0)ô1-ñ42ñ33ó32ó11ô1/ò0.ì3.ç60Þ7.àC:Ë60Á0-À13ùjpÿpzüetû]tüOmÿAfÿ_L=aYFTO;NG4PI6ID.GP3M[8ZlFf{Pm…SmŠRlŒMiŒJfŽGgHg‘Ii’Lj“Ol•Sn•Vo–Wt™Vs˜Un•Rj‘NfKcŒHaŠH_‡HZBX{ASt;Qm:Ok:Tk=WnB[qCUo?Vq>Wr?QE5TH8WK;YM=ZN>[O?]QA_SC_SC`TD`TD`TD_SC_SCaUE`WR]Ujic…vt™zy£xy©vy°txµrw¹ir·bj²[c¬]e®hp¸v~ƈΆŽÍ˜ Ï ©Ò­µÚº¿åÂÈêÊÍðÎÑðÓÒòÓÓïÕÐîÒÌèÏÄâɾÜöԳ¤Ã£—¯‹ˆ“zx}yuvtkl{ml†qn„e`’e`³xpÌyâ…}ñ‚{ôwqóheìXTêKHïD=ì>7æ;4ä?9Ö8/Ù@8âRIÈ;1½3(À8,Å<,Ê>/ÏB1ÖD5ÓB/Ï9+Ì41çMOø`_ðXUÞE@Ö;6Ú91Ý82å:3æ93ã:3ß;2Õ;1Í;.Ä:-¾;)ª,´6ÂD.ÏK<ÍG<È=8Æ:9Ì;@Ë:?ÝJRêWaíZdñ`góbiçV[ÖDEÜE>ßE=èFAñKKûQRÿUYÿW]ÿX^á48Ý.3à-0í57ü9=ÿ7;ÿ03û-/ò21ñ85ñ85ï31í1/ë2/ç4/â4-ã<4á=4ß<3ß;2á83å63è43ë33î68ï58ï58ò59ò67î45æ3/à1,Ý7+Ü8,Ý:+ß7*à4&æ1&ì1(ï2,î52î53ð42ò21ò2/ñ1.ì3.è50à90Ú<3Ï61Ä.-Ò@CÿluÿjuüasðRiöGhÿ8cÿ0`ÿ4bû>dÝRi½bi}NF^K:WO<]VC\O>WG7RE5JC0EI0IT4Sc>`rHh~Mk†OjŠKh‹GeFfŽEfHgJi’Nk“Tl”Um“Vo–Uo“Sj‘PgŽMcŒJ`‰G_‡H_…H\‚E\}FWxAVrAUo@YpD]rI_tIYtAYt?Xs>NB2QE5UI9WK;XL\P@^RBaUEbVFbVFaUE_SCaUEfZJg^Ynf{uo‘zxzy£wx¨ux¯pt±jo±`i®^f®_g°em¶pxÀ}…͉֗֙¡Ð ©Òª²×´¹ß¹¿á¾ÁäÀÃâÅÄäÃÃßÄ¿Ý¿¹Õ¼±Ï¹®Ì´§Å¦—¶–Š¢ˆ…rputpqofgvhg„ol`[’e`—\TµhbÓvnì}vú}wÿxuþjfú[XþSLöHAè=6èC=Ù;2ÞE=ë[RÇ:0Å;0¿7+¿6&É=.ÑD3ÔB3ÓB/×A3Ñ96Ø>@ÜDCÛC@Ö=8Ó83Ø7/Ü71å:3æ93ã:3à<3Ù?5ÔB5ÏE8ËH6¬.º<%ÊL6ÐL=Ä>3»0+½10Ê9>ÔCHßLTéV`î[eï^eëZaÞMRÑ?@Í6/Ó91Þ<7çAAïEFóFJðCIí@Fâ59à16å25ð8:ø59û04ÿ-0þ02ñ10ñ85ð74ì0.è,*è/,æ3.á3,ä=5á=4à=4à<3ã:5ç85ê65í55í57î47î47ñ48ñ56í34å2.ß0+Þ8,Ý9-Ý:+ß7*à4&æ1&ì1(ï2,î52î53ð42ò21ò2/ñ1.ì3.è50â;2Ò4+Ó:5Ç10çUXÿoxùcnôYkçI`ôEfÿ7bÿ-]ÿ4bÿBhÙNe­RYf7/[H7UM:UN;\O>XH8M@0JC0AE,CN.K[6Xj@bxGfJhˆIgŠFc‹Dc‹BcEeŽHgLhQi‘Rk‘Tl“RlPhNd‹JaŠH_ˆF_‡H`†I_…H`J]~G]yH]wH`wKcxOdyN[vC[vAZu@CE:GG=LIBRKEUKBZLC^N?aP>gVBgXCeXE`VJ]VP\W[a^ifbyuq–ys£xt¦up¦rqªus²no°ee­_^ªdc³ki¼roÆ|xχ‚Ü”Žèœ—顜ߦ¢Ý­©ä²®éµ¯ëµ¯ëµ°ê¶±ëµ­æ²ªã­¤Ù¨ŸÔ§Ñ¡—Ë”Š¼…}¤{x‰dbgjdfdXXmZTb\TK—aWLA¤TI»aXÐneå}tò‡ðƒ|êysâljÜ^_ÒPNßUSÕEDÜGCëVP¾)"À1#Á3%Ç>,ÑE4Ê>-Á2"Ê6(ÜD7ßF8Ö:-Ì4&Î6(Ô<.×>0Û=1à>3ã<3â:1Û7-Ö6*Í7(Ç:(Ä=)Ã>-ÖPDÌC;Á80Á80Å<4Ä;3Á80¿6.ØOGÚQIÛULßYPã]TàZQ×QHÐF;È7"Ó8$Ú7&ä3+ì..ô+3ø(5û$6ÿ)>ÿ'@ÿ+Dÿ/Kÿ+Hÿ#Aÿ"Aÿ'Eÿ<ÿ&@ÿ)@þ%8ò&2ì-5è47á55à=8ß=8à=6á<6ä;6ç:6ê84í76ì44ë35ê43è64æ93á81Ü6*Ö2&Û9*Ü:+Ý:'Þ9&Ü7#ß6#á8#ç8'ì7.ð50ð5.ð3-ï5)ì4(è6*ä8,ä>2Ï.&Ú<9Ð16ÿ^iÿj|ÿUoûHfù;]ÿ@dÿ:cû4]ï@aÞSj°V_}MIC3$LM;OM>LI:URCNL=9E1>K1>D FH!MS-Y`>aoKhzTh‚Sg…Od†IcˆCbŠAdAhŽEiŽHjLkMl‘KkJhGeŠGd‡Ec…He„He„IbGa~Fa|Ea|Ea}Cb~De~Dd€CY|:Y~9Z:AC8DD:IF?OHBRH?WI@]M>`O=aP1Ò9+ØÌC;Å<4»2*µ,$Æ=5ÏF>×QHÞXOá[RßYPÖPGÎD9Ì;&Õ:&Ü9(å4,ë--ñ(0õ%2û$6ÿ)>ÿ'@ÿ'@ÿ&Bÿ%Bÿ$Bÿ"Aÿ!?ÿ<ÿ"<ÿ'>ÿ)<ö*6í.6è47ç;;Ü94Ü:5Þ;4à;5ã:5æ95é73ë54ë33ì46ë54è64ä71ß6/Ü6*Ù5)Û9*Û9*Ü9&Þ9&Þ9%á8%á8#å6%ë6-ï4/ð5.ñ4.ð6*í5)è6*ä8,à:.Ø7/×96Ý>CÿlwÿasþRlùFdÿHjû5Yÿ6_ÿ>gñBcÞSj§MVW'#?/ :;)GE6PM>MJ;DB39E1]P?]R@\SD]VN`\[fclml|roŠtp•vpžsq pm¢fgŸaaŸ[^¡Z]¤ce°ijºrsÃ{|Î…ƒÖŒŠÝ“㗔㙖ٚ˜×›™Úœ™Ü˜Ûœ–Üœ•Û›”Øž•Øœ“Òœ’Λ’É™‘Â’‹·ˆ€©†w˜‚ew{]emZ\e\Wb^Re\MqZJ†XKTK¹WTÅSRÎRTÝaaåmlåuqë~yùŠƒÿ‰…óxsìhdÞWQé\SÂ5+¾2%Â9'À9&½9$À9%Á:&Ç<)Ì=-Ó=/Õ9,Ö8,Ó:,Ò:,Î;+Ð:+Ð:+Ó:,Û=1Ü<0Ú:.Ö8,Ï9*Ê9(Â9&À9&¿5*Â8.Ç=3Ê@6ËA7É?5È;2Å8/Á4+Ê=4ÔG>ÛNEÝPGÚMDÏB9Å5*Í5'Ö6(à5+è2/ï.1ö*5ù)7ý(<ÿ,@ÿ+Aþ*Aý'?þ&=þ";ÿ!:ÿ9ÿ"8ÿ$9ÿ(;û+;ó/9í29è8:å;;Ü94Ü:5Þ;4à;5å95ç85é73ë54ì23í36ì44é54å61á6/Ü5,Ù5+Ú:*Ú:*Û:(Ü9(Ü9&ß8&ß8%á7&â8)â8+ã9*ã9*á:*à:*Ý:+Ú:,Û=2Ò50Ô44öR[ÿcuÿXrûDcÿEjÿ=dÿ8bö6[ëBcÜXpµWgw@CG0*88,2:+6?,?B/DA.D=*E?'GC&=DIR%Xe9bqHfxNd{OcNdƒJ`„Da†@a‰@c‹BgDiŽIkMl‘Nl‘KjIhGf‹HgŠHfˆKd†Ib„He„Kc‚Ic€Fc€FeFeFd€EaA]€>_„?b‡B69.:<1>?7DA:JC;OE[P>\SD^WOb^]hennm}sp‹so”qk™ig–c`•[\”ZZ˜Z] \_¦hjµno¿wxÈ€Ò†„׊ˆÛ‹ß‘ŽÝ“Ó“‘Г‘Ò“Ó”Ò“Ó“ŒÒ’‹Ï•ŒÏ“ŠÉ”ŠÆ”‹Â“‹¼Œ…±ƒ{¤r“€cuz\dlY[d[Va]QcZKoXHƒUH£ZQÀ^[ÌZYÓWYÞbbâjißokãvqú‹„ÿŠ†ÿ†ÿ}yõnhîaXÂ5+¿3&Â9'Á:'¾:%À9%Á:&Æ;(Ê;+Ð:,Ö:-Ó5)Î5'Ð8*Ò?/Ô>/Í7(É0"Ø:.Ù9-Ø8,Ö8,Ð:+Ë:)Â9&¾7$¾4)À6,Â8.Ä:0Ç=3Ê@6Í@7ÎA8Ç:1Ì?6ÑD;ÒE<ÔG>ÓF=Ì?6Æ6+Í5'Ö6(á6,é30ñ03ø,7û+9ÿ*>ü';ü'=ú&=ù#;ú"9ú7û6þ6ÿ 6ÿ!6þ%8û+;ö2<ñ6=é9;ä::Ü94Ü:5Þ;4à;5å95ç85é73ë54í34î47í55ê65å61á6/Ü5,Ø4*Ù9)Ù9)Ú9'Û8'Û8%Þ7%Þ7$à6%à6'à6)á7(á7(ß8(Þ8(Û8)Ù9+Û=2Ï2-Ø88ÿktÿ\nÿOió<[ÿGlÿ6]ÿ=gö6[êAbÞZr¡CS\%(H1+88,/7(09&9<)@=*B;(C=%EA$?FXa4rS~dvˆ^hSa}La€G_ƒC`…?a‰@c‹BhŽEjJkMl‘Nn“MkJhGgŒIh‹IhŠMfˆKd†Je„KdƒJc€FdGf‚Gf‚GeFb€Bc†DeŠEhH06*58/:=4?>9D@=JB?NGASJAUMBVNCVRI[WVa^eifwmm…poon–ig–^^WVSUWX›[_¦`c°kn½qtÅz|σֆ‡×ˆ‰Ù‹ŠØŒŒÖŽÒŽÏŽÓ‹Ö‰ÖŒ‡×…ØŒ…Õ…ÒŒ…ËŽ†Âˆ¼ˆ±‰ƒ¥€z”‚oƒ‹[k‡T]pWSc]QYbMWaHa]DvWC›WNÁZ[ÕW[áT]ë`gíhmçlnévsì}vízsû…{ÿ‡~ÿƒyôl`Æ>0Á9)À<'¾<&¾<&¾:%Á:&Å:'È9)Î8*Ú9/×4+Î4(Î8*Î?/Í@/Ç:)Á2"Ì8*Ï7*Î6)Ð6*Ð:,Î:,Ì:+È9+Ç9+Ç9-Ç9-Ç9-É9.Ê:/Ë;0Ì<1ÖC9ÖC9Ó@6Î;1Ï;1Ó?5Ó?5Ó91Ô1(ß2.æ21î17ó.7÷+7ø)9ù*:õ(9ó)9ò)9ô*:ô*8÷(8ú'6û'6ù&5÷'5ò*5ò09ñ8>î;?ä::Þ97Ü94Ý:5Þ;6â:7å95ç85ê65ì44ð37ð37ï56ì65æ72á6/Ú6,×5*Ö9*Ö9*Ö9(Ö9(Ø9&Ø9&Ù8&Ø9&Ò:%Ò;&Ò='Ó>(Ð@(Ð?*Ð=+Ò<.Ô;3Ñ11íFNÿkÿRlÿ@bÿ8aÿ=iÿ2^ÿ;bçFeÏYo¦^id=B6&'954-2+.6+2=,;C,?B%B=K=MDR_*lI‹¢l“«y€šji…T\}H]~E_„Aa†@bŠAfŽEk‘Hl‘Lm‘Qm‘Qo”Nl‘KiŽHhJiŒJi‹NhŠMg‰Mf…JdƒHc‚GdƒHf„Fg…GeƒCcƒBf‹FgIj’L-3'36-7:1<;6A=:G?RJ?SK@SOFYUTa^eifwkkƒlk‹ihb`VVˆPOˆPRXYœ_cªfi¶orÁuxÉ|~Ñ‚„׆‡×‡ˆØŠ‰×‹‹Õ‹ŒÏŠ‹ÌŠ‰Ï‰‡Ò‰…ÒˆƒÓŠ‚Õ‰‚ÒŒ„Ñ‹„Ê…Á†º†¯‡£~x’€mˆXh„QZoVRc]QYbMWaHa]DuVB‘MDºSTÑSWÞQZè]dêejåjlçtqäunâohõuÿ‚yÿˆ~ôl`È@2À8(À<'¿='¿='À<'Â;'Å:'Ç8(Í7)Ú9/Ú7.Ò8,Ï9+Ê;+È;*Ç:)Ç8(Í9+Ð8+Ñ9,Ñ7+Î8*Ì8*Í;,Ì=/Ê<.Ê<0Ê<0É;/É9.Ç7,Æ6+Å5*Ò?5Ò?5Ï<2Ë8.Ì8.Ï;1Î:0Î4,Ñ.%Ü/+å10î17ô/8ù-9ú+;û,<û.?ù/?ù0@ú0@û1?þ/?ÿ.=ÿ/>ý*9ú*8ô,7ó1:ð7=ì9=á77Ú53Ü94Ý:5Þ;6â:7å95ç85ê65ì44ñ48ñ48ï56í76æ72á6/Ú6,×5*Ö9*Ö9*Ö9(Ö9(Ø9&Ø9&Ù8&Ø9&Ò:%Ò;&Ò='Ó>(Ð@(Ð?*Ñ>,Ó=/Ð7/Ú::ÿ]eÿ_sÿOiù:\ÿ@iÿ3_ÿ4`ú2YîMlÓ]s‹CNQ*/<,-732+0)08-5@/:B+:= A<VH%cZ1y†Q¤l¨¿‰§¿Œ¦vo‹Z_€K^F`…BcˆBeDj’Io•Lp•Po“So“So”Nl‘KiŽHgŒIiŒJi‹Ni‹NhŠNf…Je„IdƒHe„Ig…Gh†Hg…Ee…DiŽIi‘Kl”N*2%-5*270794;;9?>2Ù=1Ó5*Î)#Ö('á*.ë.5ó1:ö0=ù1>ú1Aø2Aó3@ò4@ï6<ï4;ð37ò16ó04ò/5ó49ï5:í49ê69ç9:â88Þ65Ù42Ü86Þ97ß:6ã:7æ87é77ê67ì46ó49ó49ð69í68å84ß61Ù6-Ô6+Ò9+Ñ9+Ð:+Ð:+Ð:)Ð:)Ñ:)Ð:)Ê<$É?%È@&ÈB)ÇC*ÉB.Í@/Ð<2Ô44ðENÿcvÿJgÿEiÿ4_ÿ?oú1_ú=cÜ?ZÇ^m cjR?;21->:;:16<02?42:;+3</;IHDQQS[[eabtac|``‚_^ŠZXŠSTŒTT’Z]¢gi¶prÅvwÑ{Ú~Þƒ„à„…ß„„Úƒ„Ö…„Ô†…у†Ë‚…ʃƒË‚̓Ó…Õ†€Öˆ€Õ…҃ȋƒ¼‹„°‰‚¡|wq}vek}VYzQOmWLf_M]eMZdIaaEo]E…VF«^VÃ]YÒWZá\aè]dì_eòjløysîrjúwmáXNçZPÓC8Ä5%È9)Å:%Æ;&Ç<'É<(Ì;*Ï9*Ó7*Ö6*Ó0'Ô3)Ò8,Í;,Å<*À;(¿<(Á<)Ç;*ÓD4ßK=ÞH:Ó=/Ê4&É5'Î:,È9)È9)È9)È9)Ê8)Ë7)Ë7)Í7)Î6)Ó;.Ø>2Ù?3Ü@4ÝA5Ø:/Ô/)Ý/.ç04ð3:÷5>ù3@ù1>ù0@ö0?ï/<î0<ê17ë07ì/3î-2ï,0î+1ò38ð6;ï6;ê69ä67ß55Þ65Ü75Ü86Þ97ß:6ã:7æ87é77ê67ì46ô5:ô5:ñ7:î79å84à72Ù6-Ô6+Ñ8*Ð8*Ï9*Ï9*Ï9(Ï9(Ð9(Ï9(È:"Æ<"Æ>$Æ@'ÅA(Ç@,Ë>-Ï;1Ø88ÿT]ÿ^qÿFcÿ>bÿ8cÿ7gý4b÷:`æId¼SbDKI62:95?;<<38@46@5389)4= 8DP\*„N ¨m®Æˆ®ÌŽ¯Ì’¦Ã‘¯{{™egˆQ_E^ƒ>c‰@iDo•Js™Ps˜Sq•Uo“Sn“NkJgŒGeŠGgŠHh‹Ki‹Ni‹NfˆKd†Id‡GeˆHgŠHh‹IgŠFeŠEj’Kl–No™Q&.(0#-2+/402415769:5;<7DE=CD>EHANPOX[`_an^`u\]|`_‡\ZŒYY][œgg¯sqÄz{Õ߃ƒç„ƒé……焄䃃Ý׃ԃ‚΄‡Ìƒ†É„„Ê„‚Í…ƒÎ‰‚ЊƒÐŽ„͆ǎƒ»Œƒ®Œƒ¢ˆ€y€vnlne\h_Pf[IeZHi^LjbKh`Ii_Dn`FoW=ŠdM¢eS³\RÎ[VãWZõT\ÿ\cÿliüibÿleÚ?:Ü>5Î-#Ï1%Û?0Î5#Î7$Ï8'Ò9)×7)Ú6*ß4,Ý4-Î-#Ê2'Ê8+É=.ÄA/À?,½<)»8&¾5%ÐB4âPCâNBÖB6Ë7+È9+Î?1Ê;*É:)Ç8'È7&È7&Ì6'Î8)Ñ8*Ô;-Ø:.Ø8,Ö4)Ù5+Þ:0á:1á6/ë7:ò7>÷9Cû9Dø5Có0>í/;é/:ä39â59á78â88æ87ê86í74î87é75é99è<:å97Þ63Ü41Ý86à;9ß76á77â88æ89ç79é69ê69ë48ó6:ó6:ð8:ë99å97Ü94Õ8/Ï8-Ê;-É;-Æ=-Æ=-Æ=+Æ=+Æ=+Æ=+Á:$¿;$À>(À?*Á@+Ä?0Ë;2Ñ64ä9BÿXjÿNiÿGhÿ8_ÿ?jò2[îDhÉL\Âmrˆ[VI8.;>3?D=?75G14N.1M0,D7$?E#BY%Yx<€¤^ Ä~­ÍŽªÉŽ¥ÃœºˆŽ¬z{™gh†R\{B^?b†@hŽCo•Jp˜Op˜Rn•Rn“Pn“NkIgŠFeˆFf‰Gh‹KhŒNhŒNe‰KdˆJcˆEd‰Ff‹EgŒFgDc‹Bj”Jl˜Mo›P(0!'/"(-&).*.0-2437839:5<=5?@:CF?JLKORWVXeZ\q]^}YX€[Y‹^^”fd¥nn¶ywÊ€Ú„„䌌ðŒ‹ñŠŠì††æ‚‚Ü€€Ö‚€Óƒ‚΀ƒÈ„ǃƒÉ…ƒÎ†„ÏŠƒÑ‹„ÑŽ„͊‹€¸‰€«‡~x‰wpwmecf]Tg^Oi^Lh]Kh]Kf^Gg_Hj`En`FkS9~XAžaOºcYÎ[VÝQTòQYþY`þfcêWPÙB;Ð50Ô6-Ú9/Ù;/Ö:+Ñ8&Ð9&Ð9(Ò9)×7)Ú6*ß4,Ý4-Ð/%Ì4)Ë9,Ê>/ÄA/Á@-¾=*¼9'Â9)¾0"éWJßK?Ã/#Ñ=1Ì=/Ç8*Ê;*É:)È9(É8'È7&Ë5&Ë5&Í4&Ð7)Ø:.Þ>2Ý;0Ú6,Û7-ä=4îC<öBEó8?ð2<ö4?õ2@ð-;ì.:ì2=é8>ä7;á78â88è:9í;9ï96î87ï=;ì<<è<:å97à85ß74Ü75Ü75à87â88ã99ç9:é9;ì9<í9<ï8<ô7;ó6:ð8:ì::ç;9ß<7Ö90Î7,È9+Ç9+Ä;+Ä;+Ä;)Ä;)Å<*Å<*À9#Â>'½;%µ4»:%ÉD5Ï?6Ë0.ÿ]fÿUgÿHcÿ;\ø1Xõ0[ø8aïEiÜ_o¡LQe83G6,>A6>C<@86B,/N.1N1-D7$DJ(Xo;|›_˜¼v¤È‚«ËŒŸ¾ƒ˜¶€”²€‚ nf„RXvB[zA]€>c‡AiDn”Im•Ll”Nk’Ol‘NiŽIfŠDc†Bc†Df‰Gh‹KfŠLdˆJg‹MhŒNgŒIf‹HeŠDf‹EjGk“Jq›QržSt U,0!+/!+.%+-(./*220560780;=0>@2BD7IJBOQLUVZZZb]\l^\qa^{ecˆnkšvu±}ljˆØŽ‹äŽëŒêŒˆæ‡„݃€Ñ~Ë‚ƄĆ†Æ‡‡Å‰ˆÄŠ‰Å‰ÄˆÂˆ¼‡¶‹ƒªŒ¡‡~‘…y…~tuvkgocWd^N^cL]bKb`Ki\KmZIqZJr\Gr\Eu_G|\CŒ\E¨]JÆWLàRPúPSÿTYùQPìGCã:5ß2.à3,ã6/á7*Ü6(Ö7$Ô7$Ó8&Õ8'Ù5)Ý5*á3,Ý4-Ç3%Â9)Ã;+Ã>-ÃB/Â?-À;*Á8(Æ7)Î:.åQEÜH<Å6(È<-Â=,¼7&Ç>,É=,É<+Ê;+É:*Ì8*Î8*Ï5)Ó7+Ø7-Ù6-Ù2*×0(Û0)á6/é:7øDEñ8=ê17ì18ì3;é19ä5<ã:?Ü9<Õ78Ð72Ø=9éGBñLHóGCîB>å<7ã<6â;5á:4á85á85â96â96ã77å78æ8:è8;ë8<ì9=ì9=ì7<ñ7:ð69ë78ç98á<8Ù<5Ï;1Ç9-À;,¾<,¼=,»>,¹>,º?-º?-º?-¸;'»A,µ<)¯6%µ;,¿<4É98Ú:Bÿ]kÿPfûC]ðYãE^ÝKbÇWeŠPLeN@KD2>?-:?+<=-F?/R@2J4&P;(TN.cj@wYŠ±p—Å}ȃ˜¹€œ¶†›µˆŽ§}u‹d\sIUo@^yD`~Be„AiEm“Hl”Kj”Lg’Kh‘MgŒGeˆDc†Dc†DgŠJiŒLhŒLg‹KgŽMgŽMgIeGdŽDeEi“Gk—JnœQnžRq¡U-1"-1#,/&,.)/0+11/34.45-9;.<>0@B5FG?KMHQRVUU]XWg\Zo`]zfd‰qnzyµ†‚̌ܒèíŽëŒˆæ‡„Ý‚Ð|É€}Ä~Á††ÆˆˆÆ‹ŠÆŒ‹ÇŽŠÅˆÂŒ…¹Œƒ²‰¨‡|œ€wŠ|p|uklod`k_Sc]M]bK]bKa_Jh[JmZIqZJr\Gr\EwaIxX?„T=¢WDÇXMãUSùORÿLQå=<à;7à72â51â5.â5.à6)Ü6(Ö7$Ô7$Ó8&Õ8'Ù5)Ý5*á3,Ý4-È4&Á8(Á9)Á<+Á@-Â?-Á<+Á8(Ä5'ÝI=ÚF:ÕA5Ì=/Ã7(Á<+¼7&Ä;)Æ:)Ç:)É:*È9)Ë7)Ì6(Í3'Õ9-×6,Ö3*Ù2*Ú3+á6/å:3ê;8ð<=í49ê17ì18í4<ì4<è9@ç>CÛ8;àBCéPKõZVüZU÷RNîB>ä84à72ß82ß82ß82á85â96ä;8ä;8ã77å78æ8:è8;ë8<ë8<ë8<ì7<ï58î47ê67æ87à;7Ø;4Í9/Æ8,¿:+½;+»<+º=+¸=+¸=+¸=+¸=+·:&»A,²9&°7&µ;,´1)Ã32îNVÿ[iÿJ`ó;Uí9VìB]éKdßMdÃSaw=9[D6KD2AB09>*67'>7'K9+D. R=*e_?ˆ^’«t•¼{”Âz•À{’³z·‡š´‡€™o^tMJa7Nh9\wB_}Adƒ@hŒDl’Gj’Ih’Jf‘JfKd‰Dd‡Cc†DeˆFh‹KkŽNkOjŽNiOiOi‘KhJfFh’Hk•InšMs¡Vs£Wu¥Y34$23%11%11)12*23-35*46)9<);>)?C,DG2JK;OOCSRMUTOYYQ^]Yediqn{zš‡„³ŒÆ“Õ•“Ü”‘ތ֊‡Ì…€À~·‚~±ƒ²†ƒºˆ…¼Œˆ»ŠºŽ‰±†¨ˆ‚œˆ’ˆ~‰„w~{pnvgbpbWn^Ql[KgZId]Kc^Ke\Kh[KmZKqZJvYI}XFR?ˆK9™J9¸RD×WLéRKïGDï@=Þ1-à3/â5.ä6/ã5,á5+Þ7'Ú9'Ó8$Ð9$Í:&Ð;'Ò9)Ø8*Ú6,Ö8-¿:)¶;)·:(º;*¿=-Å=/Æ:-É5+Ê1)ïRKÔ;3Ì8.ÏC6º6'º?-º?-½:(Â9)Ã:*Ç9+Ç9+Ê8+Ì5*Í3)Ò5,Ô3+Ö1+Ü3.ã:5ê=9ì?;ì=:ç53é77ë99ê7:ä68à69Þ:;Û?@ìXVõfbþqjükfíXRàB?Ú83Ú51Þ7/Þ7/ß61à72ã73å84æ87è88è58é69ê7;ë8<ë8>ë8>é8>ë8<í6:í68ç79ã99Ü=9Ô=6É;1À:.º;,¶=,±>,¯>,®?,®?,¬?+¬?+©>,®C1£<+¥;-­=1§,'¾68ùamûVfóJ_åBUÜEVÑS^Æ]a±`]—bZ^SAKN;HF1JD.HD+?@!2>,=*@>R!bs?‡•b˜«s˜°v•³w˜µ¡¸Œ¤µ“”£„pbN]@ET5Oa;\oBazAe‚BiŠCk‘Fi’Ff’GbGdHb‡Be…Bd‡EgŠHjMlOm‘Qn’Rj‘Nj‘Ni“Kh’Jf’Eh”Gl™HpœMu¦Uv§Xx©Z78(78*66*66.56.56068-68+;>+=@+@D-DG2JK;NNBQPKSRMVVNZYUa`eli|ut”~­ˆ‡ÁŠÏ•“Ü”‘ޑ׋ˆÍ†Á~·€|¯€|¯~µ„¸ˆ„·‹…µŠ…­‡€¢{•x‹u€{nurgen_Zj\Qk[NkZJgZIe^Ld_Lf]Li\Ln[Lr[Kx[K~YGTAŒO=ŸP?ºTFÑQFÝF?á96ã41Þ1-à3/â5.ã5.á3*ß3)Ý6&Û:(Ó8$Ð9$Í:&Ð;'Ò9)Ø8*Ú6,Ö8-Á<+¶;)´7%·8'½;+Ä<.Ç;.Ê6,Ñ80ø[TÖ=5É5+ÎB5·3$µ:(º?-¾;)Ã:*Ä;+È:,É;-Ì:-Ï8-Ñ7-Ð3*Ò1)Ö1+ß61å<7ë>:è;7æ74é75î<<ï==é69á35á7:çCDêNOÿywÿrnïb[ÛJEÎ93Ð2/Ú83å@<à91à91à72à72â62ä73å76æ66è58é69ê7;ë8<ë8>ë8>è7=ê7;î7;î79è8:ä::Ý>:Õ>7Ê<2Á;/¸9*´;*°=+­<*¬=*«<)ª=)ª=)§<*©>,¡:)¤:,©9-«0+ÉACÿhtóN^ñH]éFYáJ[ÑS^ÁX\«ZW’]U\Q?KN;JH3KE/HD+AB#:F :KDZ+Wk:s„P‹™f‘¤l¨n’°tš·Ÿ¶Š”¥ƒv…fSbE@O2CR3Oa;Xk>b{Be‚BiŠCjEi’Fe‘FbGcŽGb‡Bf†CgŠHiŒJkŽNmPn’Ro“Sj‘Nk’Oj”Li“Kh”Gj–In›JržOu¦Uv§Xw¨Y@=,@=.?=0?<3==3<<2<<0<=-@B*AD)DG(GJ-MM5PO;TQBUR?ZY;]\>_aLhgbqq{}z•ƒƒ©‰‡¹‘ŽÅ‘Ȍˆ¼„®€{¤|x™{wœ{x§}y¬‚|¨„~¤ƒšyŽ}v~}stwlfug\naQm\Ll[ImZIoZIpYKsYLsXMm[Ml\Mj_Mp_Oy^M†XKžZO«NFºE>ÊA;Ð<2Ó5*Ö2(Û3*ß7.á6/â5.á4-Þ4'Ü4'Ø9&Õ=(Í;"É="È>$É>'Ë='Ï<*Ó:,Î<-»A,°=(¬7#°5#¹:)Ä<.Ì9/Ï5-Ü=7ûYTæGAÐ90Ê@3¶7&¨5 ²=)¹:)¿7)¿7)Ã7*Ä8+Ç7,Ì8.Ð7/Ù<5Û94Þ95å<9ê><ê<;ç77ã33ç:4ê=7é<8æ:8è@?ôRPÿecÿrn÷ießVPÅ>8½2-Æ50Õ;9Ý>;à;9à;5á:2â94ã73ã73å63å55è66ê69ê69ë6;ì7<é8>è7=è7=é6<ì9<ë8;æ::á<:Ú?:Ò?7Æ>2½>/³9*¯<*ª=)§<(¤=*£<)¢;(¡<*ž?+™<*™>,›;-8,±@<×WX÷gqéN\éL]àO\ÐSY¶[X `T‰fPvjPFN7FN9PH5N=)A3684U=p-W—MeŸUy¢`…c‘šešnŸ§v¢ª‡’pq{bT^F?H3;D/DN6P^=XhAeyDgDkŠDlFh’Fc‘F`FaGcˆCi‰FjKlMlOlOm‘Qn’Rm”Qm”Qm—Ol–Lk—Jm™JpŸNs¢Ry­[y¬]x«\DA0EB3DB5EB9CC9CC9BB6BC3DF.EH-GJ+JM0OO7RQ=URCVS@\[=]\>\^Iba\iistqŒ{{¡±†ƒºˆ„¿ˆ…¼…€¶|©yttp‘qm’pmœrn¡vpœxr˜wsŽvnƒsltsijmb\m_Tj]Ml[Km\Jo\Kq\Kr[MtZMtYNn\Nn^OlaOraQz_NˆZM¢^SªME´?8Á82É5+Ï1&Ö2(Ý5,à8/á6/á4-à3,ß5(Ý5(×8%Ò:%Í;"É="È>$É>'Ë='Ï<*Ó:,Î<-¼B-°=(ª5!®3!¸9(Ä<.Ì9/Ï5-Ø93ðNIòSMÙB9ÌB5¾?.¥2±<(¼=,Á9+À8*Â6)Ä8+É9.Ï;1Ô;3áD=ãA<ä?;ç>;é=;é;:è88ç77æ93æ93å84è<:óKJÿ][ÿec÷c_Ë=9Á82»4.Ã83ÓB=ÞDBÝ>;Ù42à;5â;3â94ä84ä84æ74ç77é77ê69ë7:ë6;ì7<é8>è7=è7=é6<ê7:é69å99à;9Ù>9Ñ>6Å=1¼=.²8)®;)©<(¦;'¢;(¡:'¡:'Ÿ:(ž?+”7%™>,™9+˜3'ÂQMìlmí]gëP^èK\ÛJWÊMS±VSž^RŠgQymSGO8DL7JB/I8$D6FH!Qr9c–Sw·m}·m¨f{“Y„X‘”e•d‰`ZeCIS:;E-8A,:C.?I1JX7Wg@g{Fh‚El‹ElFi“Gc‘Fa‘GaGf‹FlŒImNn‘OlOkŽNkOm‘Qp—Tq˜UpšRpšPo›NqNt£Rw¦Vz®\z­^y¬]KB3LC4MD5MD5NE6NE6MD5MD5NE6OF7QH9SJ;VM>XO@ZQB[RC_VG_UI`VJcYPk`\vjj€tx†y‚Š}†Œ‰Ž€‹}Š…x‚|oyvirrgmmiflkfpmfpmfplaoh^keWjbUg^Mh\Lg\Hi\Im^Go`IoaGkaHddLhaNu[J„VI“PGžNE§MB«N?¯P>©F3¤>(°=+Á;/Ï81Ü43á32ß6/Ü5,Ú6,Ú6,Ü8.Û7-Ø6+Õ3(Ö6*Ö6*Ô6*Õ7+Ô8+Õ9,Õ9,Ï;-Á?1³9*¨3"©4#²:)ºA0¿@1Â<0Ä6*ÙE;õ]RáI>×@5ÔB5¸,Å9,ÒB9Ò?8Î>5Ï<4Ð=5Ø?9áB>êBAê<;ì89ê67ç34ä44ã75ß<5ÚA9ÒH>ÊG=ÄF8ÉK=ÒXIÖ[LÃH8®/ µ/#Â4*Ò;2Ý;6ä86è45ï56ò8;è5;å6=å79å79å97æ:8å<7æ=8ä;4ä;4ç;7ç;7ç;9æ:8æ89æ89æ8:ä79Þ:;Ú<;Ð?:È?7»?5²>1§<,£>,ž?-›>,™>+˜=*˜=*“>*D3‚9*–>4›50++ÑY[ò{Ð_aÉgf·b]¤^Vš\Q˜^SšaV›`XŽhSWW%@288,8:-@B7=C59B/CP6TeAe{JgƒHl‹HoIl’GjGeEeGfNkRl“Rl“Pi‘JgDg’Ci”DqžIrŸJp Lp Lo Nr£Qv§V{©`w¤cx¡gvŸeSJ;SJ;SJ;SJ;SJ;SJ;SJ;SJ;VM>WN?XO@YPAZQB\SD]TE]TEcZKbXLbXLcYPg\Xmaasgkwjs|ox~q{s€s€~q{wjtobkh]cea^a`[a^W_\U_[P`YOa[MbZMe\Kg[Kh]Ii\Ik\El]Fl^Di_FeeMngTsYH{M@•RI§WN®TI´WH«L:¨E2¤>(­:(¿9-Ð92Ü43Þ0/ß6/Þ7.Ü8.Ü8.Ü8.Û7-Ø6+Ø6+×7+×7+Õ7+Õ7+Ô8+Ô8+Ô8+Î:,½;-·=.®9(§2!ª2!´;*½>/À:.Å7+Ë7-Ó;0ÛC8àI>ØF9Ç;,¼0#ßOFÛHAÕE<ÖC;ÚG?ßF@áB>ã;:ã54ê67í9:í9:ç77â64Ý:3Ø?7ÓI?ÈE;¼>0µ7)¯5&³8)¹>.ÀA2Á;/Ê<2Õ>5ß=8ç;9ì89ð67ñ7:é6<æ7>æ8:æ8:å97å97ã:5ã:5Þ5.ß6/ã73ä84å97æ:8ç9:ç9:ê<>æ9;Þ:;Û=<ÓB=ÌC;¾B8´@3¦;+¢=+>,™<*–;(•:'”9&:&ŒC2‡>/‡/%“-(½KKåmoämqÉXZ³QP©TOWO˜ZO•[P–]R™^VŽhSZZ(:N3JOf"x’I˜²i¡¼u »v™±s…šbk~P]kGWdHS\GHN@?B7:<.AA5=?2;=2.­:(£2 ¢5 ¬=)´A.¸?.¿=-Á7*Å7+Ï<2ÚF:âNBàQCãLCåA?ä:;Ü66Û55Þ88á99â66ã03ì59ï5:ð6;î5:é69æ89â=;ÛB<ÈB7¼A2µ;,°6'¬7&±9)¶>-¾@1ÄB2ËA4ÕA7Ý>8â;5é75í76ð8:ì57ê69é77é77ç85ç85å:3å:3â92ã:3â;5ã;8á<8á<:à::ß;:Ý==Ú?=ÖA=ÒC=ÉD=¾B8±@2¨=-¡=->,™>,•<*“<)‘:'9&‹:'}:'}:)„8*–?5·VPÏieÆda­RO£SLWO—[Q–]R”`U•_U–`VŒfS`^5Te1^p<{Y™­z§»Š›¯~Špl~VbrNTcFLV>FO>@F:;>567/:7¾;3½9-»7+¼8)À;,Ã>/Ì=/Ö:.Û7-Ú8-Û9.Ú8-Ù7,Ø8,×7+Õ7+Õ7+Ô8+Ô8+Ô8+Ô8+Ò9+Í;,À>0¶>.­:(£2 ¡4©:&²?,¸?.Â@0Â8+Â4(Ç4*Ð<0ÙE9ÜM?äMDÜ86Ü23Ö00Ø22Ý77ä<<è<<ì9<ï8<ï5:ì27ê16è58æ89á<:Ù@:¾8-µ:+°6'®4%«6%°8(´<+»=.ÇE5ÍC6ÖB8Ü=7á:4è64ì65ï79ì57ê69é77é77ç85ç85å:3å:3ã:3ä;4ã<6ã;8á<8à;9ß99Ý98Ú::Ù><×B>ÒC=Å@9·;1ª9+£8( <,œ=+˜=+”;)’;(9&8%Š9&y6#y6%†:,žG=¶UO¾XT´RO¦KHŸOHšTL–ZP—^S–bW—aW–`V‹eRsqH{ŒX“¥q¥·ƒ«¿Œž²|_[nA?Q)BR.AP3AK3:C26<069067/9;.@@4=?2:<1;A39B/@M3Qb>`vEi…Js’Ot•No•Jo•Ll–Ll”Nn•Rq•Uo—Qn–Ol”Kl•Il—Gn™IpLpLpŸNu¤Tx©Xyª[u¥Yr X]‰JVEOx>aXIaXIaXIaXIaXIaXIaXIaXI_VG`WH`WHaXIbYJcZKd[Ld[Je]Ff_Ef^Gg_Jg_Jf^Kf]Lf]Lh_Nh_Nh`Mh`Mg_Je]Hd\Ed\G_ZG\VFXRBTN>PMSP?TSAVUCXWEZYG[\J^_M`aOabRdbSldWs]R…]U¥d^¶[Z¸DDÂ7:Ñ59×26Ô20Ì3-À7'·=(°F,¹G-Î=,Ø8*×:+×:+×:+Ö9*Õ9*Ô8)Ô8)Ô8)Ò9)Ò9)Ò9)Ò9)Ò9)Í;,Á?1¶>0©:'Ÿ4 ˜5:#¤B)­D.µB/¸=-¾9*Ã7*Ê7-Î:0Ñ:/Ù72æ16ê,6ä,4ã06å4:è9>ëè5;ã28â38Þ8:Ü9:Ó97È93±7(ª9'¨9&¨9&¨9&«:(­=)³;*¾C3ÇC6ÑC7ØA8Þ<7â:7ç:6ë97î66ï56î64í74ë83è:3ç:3ä<3á:2Þ;4Ý<4Û>9Ø=9Ö<:Ò<;Ï>;ËB<ÉF>ÅIA¿F=°@4¥;-9*—:)•>+“>*>+Ž=*Š<(ˆ:&‡8'…9)>*t5#|7(’H;¡TJ SIœRI›WL“UJ‘YLŽ]O`R“aV•aV—aWfUŠ„dœ¦¯»—©´”‘ž‚uiO\H0=,/:*6>11:<1:@29B/?L2Pa=awFj†Kt“Pu–Oq—Lq—Nn˜Nm—Op˜Oq™Pp™Mo˜Ll—Hl—Hn™Jp›LqNržQt£Uy§^|ªax¦^n›Vg‘Q[„HT{DOv?cZKcZKcZKcZKcZKcZKcZKcZKcZKcZKd[Ld[Le\Mf]Nf]Nf]Lf^Gg`Fh`IiaLiaLiaNh_Ng^MjaPi`OiaNh`Mh`Kh`Kh`IiaLd_L`ZJ[UEVP@PMSR@UTBVWEYZH[\J\]Mb`Qf^QmWL„\Tªic¾cbÁMMË@CÕ9=Ú59Ø64Ï60Â9)¸>)¯E+·E+Í<+×7)Ö9*×:+×:+Ö9*Õ9*Ô8)Ô8)Ô8)Ò9)Ò9)Ò9)Ò9)Ò9)Í;,Á?1¶>0ª;(¡6"˜5š7 ¡?&¬C-°=*·<,À;,Æ:-Ë8.Î:0Ò;0Û94ì7<ð2<é19å28ã28â38â38â17ç6<è5;å4:æ7<à:<Ú78Í31¿0*±7(«:(ª;(ª;(ª;(«:(ª:&¯7&¶;+À9Ù>:Ø><Ô>=Ñ@=ËB<ÇD<ÀD<·>5©9- 6(œ8)˜;*“<)’=)Ž=*Œ;(ˆ:&‡9%†7&ƒ7'‚A-s4"y4%‘G: SIPFšPGYN•WL‘YL\NŒ\N]R”`U—aWhWŽˆh™£~©…‚m]jNEQ92?+$1 .9)2:-5=2;>56;;1::09:,>>2;=09;09?18A.>K1Pa=bxGk‡Lu”Qv—Pr˜Ms™PpšPo™QršQršQr›Op™Mm˜Im˜Ip›LsžOt Qv¢Ux§Y{©`z¨_qŸWd‘L[…E]†JW~GRyBe\Me\Me\Me\Me\Me\Me\Me\Me\Mf]Nf]Nf]Ng^Og^Oh_Ph_Pg^Mh_Ni`OjaPjaPjaPjbOjbOjbMiaLh`Ih`IhaGhaGibFjcIf`Jc\I_XEYR?SN;OJ7JI7IH6IJ8JK9JN=LP?LSCNUEOXGPWGYYM[WK\TGo]O‘pa¦mbµ^UÊWTÓCCÞ;>à67Û32Î7,Ã;+µA*¸@(É<*Ñ8(Ò9)Ó:*Ó:*Ó:*Ó:*Ò9)Ñ:)Ñ:)Ñ:)Ñ:)Ñ:)Ñ:)Ñ:)Í;,Â>1¶Þ>@Ú@@Ö@?Ô@>Ð<<Ð>>ÑA@ÐEBÉE@ÀA:±;1§7+§=-¥@.¤A,¤A,£@+£>*£='¥:&©8&²:*¾?0ÉA5Ð@7×@9Ú?:á>9è;7ì95ë:4ë:4è;4ç<4ä=4á>5ÝA5ÚA9×D<ÓD>ÏF@ÌEBÈD@ÃFBµF;®F9§C4Ÿ>.–:+‘:)<*Ž@,‹>,‰>+…>,ƒ<*‚;)€9'8&~6'~9)v1"}:*”QAž\N•VGRE’XL“[NZNŽZOYO‘ZS—\V›^Y”fY€wZ{‚`r{\V^F;D/19*0:11;35;75:66;4=>6@B5@A1>=+98&89)>>2:07@-=J0O`GP?HO?PPDVRFXPCeSE}\M‘XM¬ULÏ\YÚJJâ?Bâ89Ý54Ñ:/Å=-µA*´<$È;)Ñ8(Ò9)Ó:*Ó:*Ó:*Ó:*Ó:*Ñ:)Ñ:)Ñ:)Ñ:)Ñ:)Ñ:)Ñ:)Í;,Á=0¶/À6+Â/%È/'Ð6.Þ:8è59ì7>ë9¹:3®8.§7+§=-¤?-£@+¤A,£@+£>*£='¦;'¨7%°8(¹:+Â:.É90Ò;4Ù>9ã@;è;7ì95ë:4ë:4è;4ç<4ä=4á>5ßC7ÜC;×D<ÒC=ÌC=Ç@=Ã?;¼?;­>3¤F.6?*4<-4>55?76<89>:=B;DE=EG:CD4@?-;:(78(==1:06?,=J0N_;awFk‡Lu”Qw˜Qs™NtšQq›QpšPqœMrMqœLp›KošKrNu¡Ty¥Z«`~©az¥^qœWf‘L_‰G]‡G^ˆIb‰PY€ISzCh_Ph_Ph_Ph_Ph_Ph_Ph_Ph_Pg^Oh_Ph_Ph_Ph_Ph_Pi`Qi_Smb\la]j_Yi^Xh^Ug]Tg]Qh^Ri`Qi`Qi`Oi`Oh_Nh_Nh`Mh`Mh`Kg_Jf^Ic[F\WCWR>ON:ML:DG4DG6DH9DH9AI:BJ;@K;BJ;FL>OSDKTAMR>Û78Ú85Õ83É5+Ã1$Ë9*Ì9)Í:*Ï<,Ï<,Ï<,Ï<,Ï<,Ð:+Ð:+Ð:+Ð:+Ð:+Ð:+Ð:+Í;.Ã:0¹90²9.«;-œ7#’2–6¢>'¦7$³9*Á=0É;1Î70Ó61Ú;7â@>âBBáEFÛJGÒKEÅIA¸C9«?3¦3ÈE;ÓI?ÙB9Ý@7Ý@7Ý@7ÛA7ÚB7ÙB7ÖC9ÔH;ÐG=ÈH=ÁE=ºC;²?8­>7¥>5–=/<,‹:)‰:)Š=-Š>.„=+:(‚?.>->,~=+|:*z8(y7'{6'z0#ƒ7*E:—QE’PD‹K?ŽRGš^S”UL–WN™XR›ZTš[Vš[V–YVŠ^QaX7EM$6@8B >H---8(19,8>0@G7HK8GK4BE*??#;;!78&==19;.79.8>06?,F7?G8=H8>F7EK=HL=>G4GL6XT;\H0|N7¹m]Öj`ÞWSáGGåABâ@=Ù<7Î:0Ì:-Æ4%É6&Ê7'Ë8(Ë8(Ì9)Ï<,Ñ>.Ò<-Ò<-Ò<-Ò<-Ñ;,Ñ;,Ñ;,Î-‹@-Œ?-”?+–=+–?,—@-™A-œA.B/ A/ =*¤:*§9*­7+²8+º:/À=3È>4Ö?6Ü?6ÞA8ßB9ÝC9ÛC8ØA6ÔA7ÖJ=ÏF<ÃC8¸<4®7/§4-¢3,›4+”;-<,<+Š;*ˆ;+‡;+„=+„=+}:)|9({:({:({9)z8(x6&x3$w- A4˜NC“MAŽL@‘QE‘UJŽRGš[Rš[R”SM“RL™ZU—XS”WT“gZ]T3IQ(AK&BL*>H-7A)2=,4?/4>2;=0;=29?14=*;H.Pa=cyHlˆMu”Qu–Oq—Lr˜Oq›Qq›QpJqžKrŸLrŸNsŸPv¢U{§\ªc‚­fx£^j“Q`‰G^†Ga‰JfŽPhTd‰S[€LTyEi`Qi`Qi`Qi`Qi`Qi`Qi`Qi`Qi`Qi`Qi`Qi`Qi`Qi`Qi`Qi_Uj_]j^`j^^j_]j_[j_Yj`Vj`Vj`Tj`Tj`Tj`Tj`Vj`Vj`Wj`Vj_Mj_Kg_Lg_Ld]J_XEUR?PMD6=I5=F1>F/KK3OH.W?'~Q:¸ubÃgZÖc\à[VàJKßABä>Bà:<×53Í9/Ë=/Í>0Í>0Ì=/Ë<.Ì:-Ì:-Í;.Í;.Î:.Î:.Î:.Î:.Î:.Í:0Í<7Ê?:Ã>7·8/§1% , ,¥-°0#»2(È80Ö>9áD?çHDéJFçLHÖGCÑJFÃH@±A5¡@0›D1—F3E2F3F4‰D4‡D3‚C2~C1|E1~C1ˆ?0Œ=0Œ?/@0ŽA1ŽA1A0’A0•D3—A2˜?/›>/Ÿ=0¤>2§A3®?4¹C7¿C9ÄF:ÆH<ÈJ<ÈJ<ÆK<ÄJ;¿G9¹E8®B5¦>3žQF“SI“PH–QLœUQšSQ™URš]ZYT†WO…fT[Y3Xc8^k?Zf>GV/6D!3B!;J+MZ>YcH^hMW]CIO3AE*=@#:<$9:(==1:+;H.Pa=dzIlˆMu”Qv—Pq—Ls™Pq›Qq›Qq Op LnLožNr¡Sv¤[|§_ªe|¥ap™Wc‹L]…Fb‰JfNfLdŠMd‰S[€MTyFi`Qi`Qi`Qi`Qi`Qi`Qi`Qi`Qi`Qi`Qi`Qi`Qi`Qi`Qi`Qi_Uj_]j^`j^^j_]j_[j_Yj`Vj`Vj`Tj`Tj`Tj`Tj`Vj`Vj`Wj`VlaOk`LiaNiaNf_Lb[HYVCTQ@ML:JH9DF8BD6AE6AE6>D6=C5;G37@+@H1KK3F?%W?'‡ZC¶s`³WJÖc\ìgbêTUåGHìFJèBDÛ97Ë7-È:,É:,É:,É:,È9+È6)È6)Ê8+Ê8+Ë7+Ë7+Ë7+Ì8,Ì8,Ë8.Ã2-¿4/¹4-°1(¤."¡- £/ ª2$¿?2ÊA7×G?ãKFéLGéJFåFBßD@ÔEAÌEA½B:­=1 ?/›D1˜G4“H5F3F4‰D4†C2B1}B0zC/|A/„;,‰:-ˆ;+‰<,Š=-Š=-Œ=,Ž=,’A0”>/–=-˜;,œ:-¡;/£=/ª;0²<0¸<2¼>2¿A5ÀB4ÁC5¾C4½C4´<.¯;.¦:- 8-š8+–8.•9.’;1ŠPJ:JG8HE6FD5EC4DB3?B/,b1#‰@7°WO¼UP¬;5ËQNâeaèbaãWXáORáHMÚDFÉ:4Ä:0Ä7.Ä7.Æ90È;2Ê;3Ê;3Ï?7Ï?7Ñ>7Ñ>7Ò?8Ò?8Ó>8Õ=:Ö>=×>@Ò@@ÏA?ÌA<ÎC>ÔG@ÜHDåMJèJIëIGêFEçECäB@ßA>ÛA?ÕFBÉD?º?8«<1ž>0™C2”G5’I8‹G4ŠE5ˆC4†A2‚@2~?0}?2}=1;0‚90‚90ƒ:1;/‚<0=0=0‚=.‚=.„<-†=.ˆ?0A3B5”B6˜B5œ@5A4¡A5¡A3¤?3£?0£=/<,›;+–:+’:,<+Š=-‰=/ˆ?0…=/„<.ƒ;-9+9-~8,}9,~:-z:.z:.y;.w9,r8,p6*p8+r6+†G8K=ŠOA„J‰QD‘UK•UL—PL›TP–ROUO`X†dX„n`‹ƒn–tƒ’krƒYXi?AT'>Q$Oa7btLdvN[kGKZ9BL1NK;ÖYUðjiòfgæTWäKPåOQØICÑG=Í@7Ë>5Í@7ÑD;ÕF>ÖG?ÚJBÚJBÝJCÝJCÞKDÞKDàKEâJGëSRëRTäRRßQOÜQLÜQLàSLæRNãKHåGFæDBåA@äB@äB@ãEBàFDÙJFÊE@¹>7¬=2 @2˜B1’E3G6ŠF3ˆC3‡B3„?0?1~?0|>1}=1;0‚90‚90‚90;/;/€1˜<1˜M,:D);E-ÏD?ÒGBÕGCÕGCØIEÙJFÚIFÛJGÞJHÞJHßKIâJIãGJäEIáEHßEGÝEDÞDDáCDå@Dç>Aë>Bí>Cí@DêBBåA@ÝB>ÚB?ÞHIÏA@¾:6²;5¥?3›?2•?2“A5Ž?2=2Ž;3Œ93‰92ˆ73†93„93:4€;4€;4€;4}=3}=3|>3|>3|>1|>1|>1{=0{=.z<-z<-z;,?3ƒ=3†>2‹>4Ž?2“?4”A1—A2’<+<*Ž=,Š=+†=,‚>+€=,<,€;,9-7+~6*}5)}5){5+{5+x5,z7.w9.u7,o5*o5*p:.s=1‡O@ƒN>~M<~O=SCˆWHYM”XN’OI˜TQ”WR^W‰i\rcPZ\FXbIAP1>M.>O+J\6]rGiQbzJUl>K`5@Q-5F&7C-;F6BÊJIÞb`ísrìppâdgÞ\^ÙRNÕLFÏD?ÍB=ÏD?ÐE@ÐB>Í?;ÒC?ÒC?ÔC@ÕDA×CAØDBÙECÜDCÝADß@DßCFàFHáIHãIIæHIéDHé@Cí@Dï@EîAEéAAã?>Ù>:Õ=:ÛEFË=<»73±:4¦@4š>1“=0‘?3‹3{=2{=0{=0{=0z.”>/:)Ž;)Œ;*‰<*…<+=*<+~;+~9*€8,~6*}5)|4(|4(z4*z4*u2)x5,v8-t6+n4)o5*q;/v@4‰QB„O?N=R@„VF‰XIŒVJSI’OI—SP‘TO]V‡gZl]JKM7BL3@O0KZ;VgC`rLezOdzLUm=F]/AV+7H$0A!6B,;F67³US´HH¶?C¹;>ÉDIÞXYêbdáWWÐFFÔHKÒCGÏA@ÑA@ÖEBÕF@ÎD:Æ@5ÊH:ÈH;ÉI<ÍHAÒGBÙDFÝBFáBGß>Cà@BàBCâDEäFEãEDàBAÞ@?ãEBâDAáB?àA>â@=ãA>åA?âDAÓD>Á<7²7/­<4¥@6—?5Œ>2‡A5~@3}?2}?4<3ƒ:3†93‰92Š:1…9,ƒ:+ƒ:+ƒ:+‚:,‚:,‚:,‚:,|6*}7+~8,~8,~:/~:/}9.}9.~:1~:1}90}90}90}90}:1}:1<3<3~>4~>4~>4}=3{=2z<1y:1x90u9/s7-s7-r6,q7,r8-n4)q7,r9.p7,m4)n5*t;0xB8†VLPI‚MEŠOI‘RM–PN“MK‘KI’VNYNXIy^KtjO^_@CN,;L(E\2UnDd{QbxQYnGUfDQ`?PZ?>H-6;%16 9<+AB2@A3><0;;18>27?44:.9<1?C4;>-CâAFâBDáCDâDEâDCãEDãEDãEDâDAáC@áB?àA>â@=â@=ã?=àB?ÒC=Ä?:µ:2©80Ÿ:0–>4?3„>2A4~@3}?4<3ƒ:3†93ˆ81‰90‡;.…<-…<-„;,ƒ;-‚:,‚:,‚:,9-9-9-9-~:/~:/~:/~:/}90}90}90}90}90}90|90|90|90|90z:0y9/y9/x8.w9.w9.w8/w8/t8.t8.s7-r6,p6+p6+l2'q7,m4)l3(o6+m4)q8-I?„TJ„SL†QI‹PJŽOJ”NL•OM–PN‘UMŠVK„]NdQkaFVW8LW5N_;i€V`yOYpFTjCRg@O`>IX7FP59C(7<&49#7:)=>.AB4B@4==339-2:/4:.7:/9=.A,>D*T^ÖEBØDBØDDÛBDÞDDßCDßCDàDEßEEàFFßGDßGDÞFCÝEBÚE?ÙD>ÛD=ÛD=ÛD=ÚE?ÕE=ÌA<½=4¯80£8.—9/;-…;.‚@0@1~>2=1ƒ:1†91‡9/ˆ:0‡;-…<-„;,„;,ƒ;-‚:,€:.€:.9-9-~:/~:/~:/~:/~:/~:/}90}90}90}90|90|90|90|90z:0z:0y;0x:/x:/x:/w9.w9.u9/u9/t8.s7-r6,r6,p6+p6+j1&p7,m4)l3(m7+j4(n8,~H>‰PG‹PJ‹PJŒOJQL‘RMTNVOƒSI~VJz]MwfRpjRgkPfqShwX_sPYmJSdDN_?N]@L[>HU;CP6@2=?1:>04:03:25;18;29=/<>0>A.>C,Q[9^mFkPp‹Tp“Qq™RsStžVw ^|¢exžak‘T`†I]ƒF]ƒF\‚E`†Ia‡Jc‰Le‹NdŠMbˆK`†I^„I]LRtBIk9i`Qi`Qi`QjaRjaRkbSkbSkbSjaRjaRjaRjaRjaRjaRjaRjaRkbSkbSkbSkbSkbSkbSkbSkbSlcTlcTlcTlcTlcTlcTlcTnbTqdTo_Pk]Pm_ToeYpf\kdZhaWfbWpla{xi~{lyiztdpiVcaLQU>BG0=A*GE0LD1M<,S<,bB5b>2i>5qA7{F>„PEWM—^S `V°c[±VQ°JE¶EAÅEDÐFDÓCBÒ><Ó?;Ô@<ÓD>ÕF@×FCÚFDÚFFÝDFÞDDßCDßCDßCDßEEßEEÞFCÞFCÝEBÝEBÚE?ÙD>ÛD=ÛD=ÛD=ÙD>ÖF>ÏD?ÃC:´=5¤9/•7-Š8*„:-‚@0@1~>2=1ƒ:1†91‡9/ˆ:0‡;-„;,„;,„;,‚:,‚:,€:.€:.9-9-~:/~:/~:/~:/~:/~:/}90}90}90}90|90{8/{8/{8/{;1{;1y;0y;0x:/x:/x:/x:/t8.t8.s7-s7-r6,q5+o5*o5*j1&o6+m4)k2'l6*i3'm7+}G=‰PGŠOI‹PJŽQL‘RM’SN‘VPWP‰YO„\P|_OsbNoiQnrWlwYgvWQeBK_0;=/8<.6<25<46<28;29=/<>0=@-=B+MW5ZiBf|Kl‡Pn‘Oq™RuŸUuŸWy¢`w`n”Wc‰L\‚E\‚E\‚EZ€C_…Ha‡JbˆKdŠMc‰La‡J_…H]ƒH[}JPr@Gi7haQhaQhaQibRibRjcSjcSjcSibRibRibRibRibRibRibRibRkbSkbSkbSkbSkbSkbSkbSkbSlcTlcTlcTlcTlcTlcTlcTlcTqeYnbVj`Vi_VibXkd^if_ifaifawto‡„}†“†Œƒˆw}yncaRQRBCG6BF5>G4:C08E1@M97D26C17B1:C2jZM~`U’aZžYT©NM¹FIÉFK×FKÕ>CÙ>BÚ@@ÜBBÜDAÝEBÝE@ÝEBÞDDÞDFÞDFÞDFÝEDÝEDÛEDÜFEØGB×FAÕF>ÕF>ÑG=ÑG=ÒH>ÕF>ÖC;×D=ÎD:¿?6«9.œ6*7)ˆ:-†>/‚?/€>.€=-<-„:-„:-‡;.ƒ;-ƒ;-ƒ;-‚:,‚:,‚:,9-9-~:/~:/~:/~:/}:1}:1}:1}:1z:1z:1z:1y90y90y90x90w8/z;2y:1w;1w;1v:0v:0u;0u;0r7/r7/r7/q6.p5-o4,n5,m4+h2(m7-j4*h2(j6+g3(k7,~E<ŽMG‘NHOISKŽUN‹YP‡[Rƒ_S~bVyfWpcSb]J_`NaiT\ePO[EGS?CO;?K7=I5@L8DPIR?BK8>G49B/6?,6?.6?.5>-4bxIj…Nn‘Os›Tw¡Wx¢Z{¢ct—]gŠP^G\E^G^G\Ea„Jb…Kc†Ld‡Mc†Lb…K`ƒI_‚JW|ILp@Cg7haQhaQhaQibRibRjcSjcSjcSibRibRibRibRibRibRibRibRkbSkbSkbSkbSkbSkbSkbSkbSlcTlcTlcTlcTlcTlcTlcTlcTrfZth\qg]mcZibXle_rohzwr~yˆ –¨¥ž«§ž¨¤›£œ’™•Š|zkdeUNRAFJ9AJ7>G4;H4>K7CP>@M;=H7:C26>/6<.7;-;9,J:-eG<„SL˜SN§LK»HKÉFKÓBGÖ?DÚ?CÛAAÜBBÜDAÜDAÜD?ÜDAÞDDÞDFÞDFÞDFÝEDÝEDÛEDÚDCØGB×FAÕF>ÔE=ÑG=ÑG=ÑG=ÕF>ÔA9ÕB;ÏE;ÂB9¯=2Ÿ9-’:,Š/‚?/€>.€=-<-„:-„:-‡;.ƒ;-ƒ;-‚:,‚:,‚:,9+9-9-~:/~:/~:/~:/}:1}:1}:1}:1z:1z:1z:1y90y90x8/w8/v7.y:1y:1v:0v:0v:0u9/t:/t:/r7/q6.q6.p5-o4,n3+m4+m4+h2(m7-j4*h2(i5*f2'j6+}D;ŽMG‘NH‘PJTLVO‹YP‡[R]Qw[Oq^Oh[K[VCWXFW_JOXC?K5;G38D05A-5A-8D0=I5CL9EN;BK8?H5-;@*GP1Ra:`vGi„Mo’PuVy£Yy£[xŸ`n‘W`ƒIZ}C[~D^G^G]€F`ƒIa„Jb…Kb…Ka„J`ƒI_‚H^IW|ILp@Bf6haQhaQhaQibRibRjcSjcSjcSibRibRibRibRibRibRibRibRkbSkbSkbSkbSkbSkbSkbSkbSlcTlcTlcTlcTlcTlcTlcTlbVjbWmd[lh_id^he^qmj‚}Ž¤¤¤²²²ÂÀÁÇÅÆÈÄÁÅÀ½¾¹¶½¯¬¯–—{ps]P\L=NE4EB/?B/=E0;D19D3:C2;A5>A8BAlMJŽXX©adµ[]µLPÁOOÈLLÐJIÖHFÛEDáCBãA?ä@AßCDÞDFÞDFÞDFÝCEÝCEÝCCÝCCÚDCÙECÖE@ÔE?ÐF<ÐF<ÐG=ÔE=×>6Ù>9ÒB9ÈB9º@5ª;0›;-‘;.‰=-…=.>-€=,<,<,ƒ<*„<-‚:+‚:,‚:,‚:,9-9-~:/}9.~:/~:/}:1}:1}:1}:1}:1}:1y:1y:1x90x90u9/t8.s9.s9.t:/t:/s:/r9.r9.r9.q8-q8-p7.p7.o6-n5,m4+m4+j4*j4*g3(k7,h4)f2'f4)c1&g5*{B9MG“LHQJŽUNˆYO€\Px^QqaRi`Ob_PX[JQUFLTEIQB@H;7=34:058136/36/39/6<29A45;:5;748739?5=>6G:2Z;8KK¨`c¾dfÃZ^ÆTTÍQQÔNMÚLJÞHGãEDåCAåABßCDÞDFÞDFÝCEÝCEÜBDÜBBÜBBÚDCØDBÕD?ÔE?ÐF<ÐF<ÐG=ÔE=Ù@8Ú?:ÒB9ÉC:½C8®?4›;-Ž8+‰=-…=.>-€=,<,<,ƒ<*„<-‚:+‚:,‚:,9+9-9-}9.}9.~:/~:/}:1}:1}:1}:1}:1}:1y:1y:1x90x90u9/t8.r8-r8-s9.s9.q8-q8-q8-p7,p7,p7,o6-o6-n5,n5,m4+l3*i3)i3)f2'k7,h4)e1&f4)b0%f4)zA8MG“LHQJŽUN‡XN[Ov\On^Oh_N[XIORAJN?BJ;9A22:-17-17-36/25.14-/5+17-2:-4-.800641624616929;0:<.:?+?H+KY5[qChƒNq“Vwž[w¡YsœVgP^IUx@WzB[~F[~F[~F]€H_‚J_‚J_‚J_‚J^I^I]€H]LUvIJjA@`7gaQgaQgaQhbRhbRicSicSicShbRhbRhbRhbRhbRhbRhbRibRjcSkbSkbSkbSkbSkbSkbSkbSlcTlcTlcTlcTlcTlcTlcTkcXmi`khcihdrqoƒ…‚Ÿ¡ ¹½¾ÌÐÑÌÐÓßàäñòôùùûùøö÷óòðìéîãÝçÑÃÜﬕ£‘yuZa\?NM/GG+EH+GG/GE0IB2K=4L95K63H66=96>><>96>31R>=x\Y—tp¨{v¡jc«f_¸aZÃZVÑQPÜJMãDHåBGÝDGÚEGÛEGÜCFÜCEÜBDÝADÝADÞBCÝABÚBA×A@ÖB>ÔC>ÓD>×D=ÝB=Û@;ÔA9ÌC;ÀD:±A6ž9-3(‹<-†=.‚=-€=,€=,€=,=*‚=-€;,€:.€:.9-~:/}9.}9.}9.}:1}:1}:1}:1{;2{;2{;2z;2w;3v;3u:2t91r90r90q8/p7.o9/o9/m9.m9.m9.l8-l8-l8-m6/m6/l5.k4-i4,i4,h3+h3+d2)i7.e5+b2(d4*a1'd4*wB:ŠOIŒQK‰TNƒXO|\Qs]Ph_Na_PSWFDM<9F5;F87B408-06,8;446166466455324/24/07/1806A3:E7=J9>K:;J77F30B,0>-,6-.4005/35058/8:/:-><@;8D97]IHŠnk»˜”Þ±¬Ç‰½xq¸aZ¿VRÑQPÝKNæGKéFKÞEHÞIKÚDFÔ;>×>@áGIàDGÖ:=Û?@Û?@ÙA@×A@ÖB>ÒA<ÐA;Ó@9ÞC>Û@;Ó@8ÊA9¾B8°@5Ÿ:.‘7,Œ=.‡>/ƒ>.>-€=,<+=*<,:+9-9-~8,}9.|8-|8-|8-|90|90|90|90z:1z:1z:1y:1y=5w<4v;3u:2s:1q8/p7.p7.m7-m7-l8-l8-l8-l8-l8-l8-i2+m6/p92o81j5-g2*g2*h3+c1(i7.c3)]-#`0&_/%b2(s>6‹PJŒQK‡RL~SJzZOu_RcZIQO@BF5=F57D35@22=/3;04:0692683775664553350350/6..5-.9+2=/6C2:G6:I68G42D.1?.*4+,2.-2,02-36-79.:-6>&DQ3WlCh‚Ss”]w`r›Yk“T[~DXyDTu@Tu@WxCZ{F[|GZ{F^JbƒNbƒN^J\}H_€K`L^~MVrLHcB0D>2G>7B87H>?PFE\RQrmi˜“½º±ÕÎÄìâØÔ¾³´Žƒ¨me²a^Â[\ÊQVÉHLÈKIÊJGÍNHÓOKÓIGÎ@?Ð>>ØBCÖ@AØ?AÙA@ÙA@ÖB@ÕA?ÒA<Ó?;ÛB<ÙA<ÑA9ÉB<¿C;±@8 ;1’8/Ž<0‰=0ƒ>/>.=-~<,€=-€=-9-9-~:/}9.}9.|8-{8/{8/|90|90z:1z:1z:1{;2z;4x<4v=4s=3r<2q;1o;0m9.l8-l8-j8-j8-j8-j8-i9-i9-i9-j8-i7.m80n91n91j8/g5,e3*e3*b2(d4*^/%].$a2(].$_0&l@7wNH|WQ{]Ut\RjYO]UHMK><@19A26A15@23>04<15;15;17:379468568357227016//7,/7,.9+1<.4A08E49G68F56E25B1.8-.5-.4*/2)14)46+8:,9=,7?*DQ7WkHhYt”ewœhp—`gŽWZ{FYwEVtBVtBXvD[yG[yG[yG]{IaMaM^|J]{I`~L`~L_zOUlPI\H?×>@Ø@?Ø@?ÖB@ÕA?ÓB=Ô@<Ù@:Ø@;ÒB:ËD>ÀD<²A9¡<2“90Ž<0‰=0ƒ>/>.=-~<,€=-€=-9-9-~:/}9.}9.|8-{8/{8/}:1}:1{;2{;2{;2{;2z;4x<4t;2q;1p:0o9/m9.l8-k7,k7,j8-j8-j8-j8-i9-i9-i9-j8-l:1m80m80m80k90i7.f4+c1(c3)a1'\-#_0&c4*\-#_0&qE33:2/5+.1(.1&13(57)6:)6>)DQ7YmJk„\w—hwœhl“\_†OWxCWuCTr@Tr@VtBXvDYwEYwEZxF]{I_}K]{I]{I_}K^|J[vKPgKCVB5H4gdSgdSgdSgdSgdSgdSgdSgdSgdSgdSgdSgdSgdSgdSgdSicSjcSkbSkbSlcTlcTmdUmdUmdUmdUmdUmdUneVneVneVneVmf\ikj‚‡‹ ¨«·¿ÂÍ×ÙäîðòüþôþÿùÿÿûÿÿûÿýüÿøüÿöýÿôÿÿòþÿñóÿéðþåêùÜæñÓÝèÈÑØ·¸À›¤ªˆ‚†ehkNLR6DI2DL7EL<>I9=C7LIBib\‹¤š˜¸®­ÍÅÃßÚ×éåâóôìÿÿöÿþô÷æÜÞúŞ—¤umŽOFª\O¶]M¸XJ´NBºNBÈSJËPIÆE@ÉB>ÍB?ÎC@ÑCAÑC?ÑC?ÏD?ÑC?Ñ@;ÒA>ÎE?ÊFB½F@¯B= >5”;3Ž<1‰<2ƒ=3=2=1~<0=/=/~:/~:/~:/}9.|90{8/{8/{8/|<3|<3|<3{;2z;4z;4z;4x<4p92n91n91m80j8/i7.h6-h6-h8.h8.g8.g8.g8.g8.g8.h8.l;4j81h6/i70i81i81e4-a0)d5-a2*[/&_3*`4+W+"_3*uPHuaZj]W\SLNG?C?6;;19;08;017+28,4:.5;/8;07:/79.79.5;14:04:04:02:/2:/19,19,.9+/:,1<.3>06A19D4I9>D8b_X…~x«¡ŸÁ·µÌÂÁ×ÏÍæáÞñíê÷øðùöíúóéÿõëÿøïÿéâÝ®¦¬mdžPC­TD¼\NÃ]QÀTH»F=¾C<ÇFAÈA=ÌA>ÍB?ÐB@ÑC?ÑC?ÏD?ÑC?Ñ@;ÒA>ÏF@ÉEA»D>­@; >5•<4Ž<1‰<2ƒ=3=2=1~<0=/=/~:/~:/~:/}9.|90{8/{8/{8/|<3|<3|<3{;2z;4y:3y:3w;3n70m80l7/l7/i7.h6-h6-h6-h8.h8.g8.g8.g8.g8.g8.h8.j92h6/f4-g5.h70h70e4-b1*b3+b3+]1(]1(]1(V*!b6-zUMo[T]PJJA:?80;7.99/9;09<139-4:.5;/6<08;07:/68-57,4:04:039/39/2:/2:/19,19,.9+.9+/:,0;-3>.7B2:E5Qn>Qn>Qn>Qn>Qn>Sp@Sp@WtD[xH]zJ]zJ_|L_|LZwGSlECTA7C9)5+gdSgdSgdSgdSgdSgdSgdSgdSgdSgdSgdSgdSgdSgdSgdSicSjcSkbSkbSlcTlcTmdUmdUmdUmdUmdUneVneVofWpgXpgXng_jnoz‰’›¢«´»ÃÎÒÛæêì÷ùóÿÿôþýöÿúøÿùûÿõùÿðøûêô÷âôòãûùíþ÷ïþõìþòæÿïà÷äÕãѽҽª¼ª–™ˆvnbRTL?II=HKBGNFJQIw}qœœÃ¿¶ÙÎÊäÒÒíÙÛúçëÿóöõìíüûùüÿúûÿú÷ÿôôÿñìõäìäÑÆœ„¬lS•Q:§ZF²\K«K=­E8ÁOE¾H>ÃG?ÆE?ÉE@ÉF>ÉF>ÉF>ÉD=ÎC>ÏDAËFAÄDAµB=©=:<6•<6Œ<5‡=4…<5‚<4<3~;2=1=1~:/~:/~:/}9.|90{8/{8/{8/|<3{;2z;4y:3y:3x92w81u91m80j8/j8/j8/h8.h8.g7-g7-f7-f7-f7-f7-d8-d8-d8-f7-g80g6/f5.f5.g6/h70f7/e6.a2*e6.^2)\0'`4+a5,h=4rTJQJBNk=Pm?Pm?Nk=Nk=Ol>Qn@VsEZwI]zL^{M_|N_|NVsENfD=I;286&,*gdSgdSgdSgdSgdSgdSgdSgdSgdSgdSgdSgdSgdSgdSgdSicSjcSkbSkbSlcTlcTmdUmdUmdUmdUmdUneVneVofWpgXqhYoh`fjkmt|„”£¬³¾ÉÍÓÞâåðòðüüòüûõþùöÿ÷úÿôúÿñúýì÷úåøöçøöêüõíýôëÿôèÿòãüéÚé×ÃÙı°œ¢‘xl\]UHPPDSVM[bZeld“™²²¦ÓÏÆèÝÙõããýéëÿðôÿöùÿüýþýûöûôôûóõÿòùÿöûÿóÿÿìÿéÑí­”¶r[¥XDªTC²RD¶NA½KA¿I?ÃG?ÇF@ÉE@ÉF>ÈE=ÇD<ÈC<ÏD?ÐEBËFAÂB?±>9¦:7œ;5•<6Œ<5‡=4…<5‚<4<3~;2=1=1~:/~:/~:/}9.|90{8/{8/{8/{;2{;2y:3x92w81v70v70s7/m80j8/j8/j8/i9/h8.h8.h8.f7-f7-f7-f7-d8-d8-d8-f7-f7/h70i81i81h70i81j;3l=5g80k<4b6-a5,oC:xLCtI@lNDA:227016/5:36<228.14+25,68-68-57,46+46+46+46)37)/7(.9).9).9).9).9)08)08)19*08)08+/7*08+19,3;.4<-9B/:C.;B0<@/9=.68*24&/3$29'IUAcu[m„hf„bWyVInE?d9Hg;Li;Nk=Nk=Li;Li;Mj
    UrDYvH[xJ]zL^{M\yKQn@G_=6B4-31#)'gdUgdUgdUgdUgdUgdUgdUgdUgdUgdUgdUgdUgdUgdUgdUgdUgdUgcWicWjcYkb[lcZldYleUkfSkfRihTjhYhiahhhhingjshpsmuxƒ‹©­°ÇËÌÜÜÞìììûùúûúøüûùýü÷þýøüÿöüÿöùÿõûþõ÷úóúûóúüïûþíüþèõøÝãæÇÑÕ´´º˜˜}r{\ZdIR^HYfTkyh|†{¦«¥¾¾¼ÖÖÔççåòòðøøöùù÷÷÷õûûùúúøüüúÿÿýüüúøøöúúøûÿÿòÿÿôÿÿÖÚÙ›‹‹\X•ZV§XQ©G>¼LAÄH>ÇG:ÊF:ÉD;ÈC:ÄD;ÃE9ÆK9ÂM9¼M9°I6 E2“@.ŠA0‡D4B3€@4?3=2ƒ:1…80ˆ8/‡8181~92}:2|91|91{80y90y90z:1z:1x90w8/v7.u6-s7-q6.k90j92i81i81i81i81i81h70h6/h6/h6/h6/h6/h6/h6/j5/i4.m61o:2n91j:.i;.k@0lE4eD3fI9XC0UD4i^Ltm[f`PTRC9<139/4:07=34:0/5+06,7=317-06,/5+.4*.4*06,17-270/4-/4.05/05/05/05/05/05/27116016005/05/05/1600705?76A99E;9E;7C72>2,9()6%/<*IVDdr[lzcdrYYgNQ_EK[>Jb@LfAOiBOiBLg>Kf=Mh?OjAUpGXrK[uN\vS^xU[tTOhJEXD2=7*/3!&*heVheVheVheVheVheVheVheVheVheVheVheVheVheVheVheVheVhdXjdXkdZlc\md[meZmfVfaNjeQmlXnl]ef^eeeqrw‚‹ˆ“–ž¡«³µÄÈËÙÝÞííï÷÷÷ûùúþýûÿþüÿÿúþýøúýôùüóøþôûþõøûôùúòøúíùüëûýçöùÞäçÈÒÖµ¶¼š•šzmvW\fK`lVq~lƒ‘€‘›´¹³ËËÉââàïïíôôòøøöúúøùù÷þþüþþüþþüþþüþþüþþüþþüúÿÿîÿÿôÿÿüÿÿþîîΫ§b^•F?²PG¾NCÂF<ÄD7ÊF:ÎI@ÏJAÉI@ÆH<ÃH6¿J6ºK7°I6¢G4—D2D3ˆE5ƒD5‚B6€@4‚>3„;2†91ˆ8/‡8181~92|91{80z7/z7/w7.v6-w7.w7.w8/w8/v7.u6-q5+n3+j8/i81i81h70h70g6/g6/g6/g5.h6/i70j81i70h6/f4-g2,h3-k4/m80m80j:.i;.i>.iB1dC2gJ:`K8raQyn\ƒ|j‡qNL=69.4:04:039/39/39/28.28.17-17-17-06,06,/5+/5+/4-/4-/4./4./4./4./4./4./4.05//4./4..3-.3-/4./4./6/1;32=55A77C98D86B64A02?.3@.DQ?WeN\jSSaHHV=DR8EU8Jb@Ke@Ke>Ke>JeOjAUpGYsL\vO]wT]wTWpPHaC;N:&1+&+/$)-heVheVheVheVheVheVheVheVheVheVheVheVheVheVheVheVheVhdXjdXkdZlc\md[meZmfVidQlgSlkWlj[fg_lll|„“œ¨°³¹ÁÄÏ×Ùãçêðôõüüþÿÿÿÿþÿþýùÿþúÿÿúÿþùúýôøûòöüð÷ýñ÷ûí÷ûíøûêøùçùûåôôÚááÅÎÏ°¶¶š””zlpW\_JbiYx~r—Œ ¥Ÿ¿Á¼ÓÓÑççåóóñ÷÷õûûùüüúûûùþþüþþüþþüþþüþþüþþüþþüþþþüÿÿþÿÿÿþÿÿýûÿóëÞȽ©‰|ƒXH“ZGœXEªWG³SE³L=³A6¸B6ÁE;ÇE8ÉF<ÃI<ºE;­B8¡?6˜?7’B;Š?9…@9@:~?8{?7z>6z>6z>6w<4w<4v;3v;3t;2s:1r90r90o9/p:0p:0p:0o;0m9.k7,j5-l7/l71l71k60k60k60h6/h6/e3,e3,f5.g6/i81i81i81j92e90f:1g;0h<1e>/fA1fC0eF2dI6hQ?cT?rgU}xd‰†sƒ„rJM<69.39/39/39/28.28.28.17-17-17-17-06,06,/5+/5+/4-/4-/4./4./4./4./4./4./4.05//4..3-.3-.3-.3-/4./6/.80/:21=34@66B66B66B45A36C1CP>P]IR_KIW@AO8BP7EU;LaBKcCLdBLdBJb>Ia=Jc›WD¢O?¢B4±J;ÌZOÌVJ¼@6ÆD7ÉF<ÄJ=¼G=¬A7 >5˜?7”D=Š?9…@9@:~?8{?7z>6z>6z>6w<4w<4v;3v;3t;2s:1s:1s:1p:0p:0p:0p:0n:/m9.k7,j5-l7/l71l71l71k60k60i70h6/g5.g5.f5.g6/h70i81k:3k:3i=4h<3g;0h<1hA2iD4hE2eF2eJ7lUCiZEujX…€l‘Ž{~mDG658-28.28.28.17-17-17-06,17-17-17-06,06,/5+/5+/4-/4-/4./4./4./4./4./4./4./4./4..3--2,-2,.3-/4..5.+5-+6.-9//;12>24@46B47C58E3?L:ER>CP<;I28F/>L3DT:J_@JbBLdBKcAIa=G_;F_8G`9RjFXpN]uS^uXZqTPgK=T:/@.&1-',0%*.heVheVheVheVheVheVheVheVheVheVheVheVheVheVheVheVheVhdXjdXkdZlc\md[meZmfVliVljUjlWlm]ori€‚¢¦¹½ÆÃÍÏÜäçóûþüÿÿúþÿýýÿýýýüúûÿþúÿÿûÿÿ÷üüôô÷ìîñæéïáçîÞíòÞðõßñõÞòôÞðòÚëéÒÙ×¾Êů´¯™¤ŸŒ–‚–…Ÿœ•®ª§º¹µÄÃÁÜÜÚééçööôûûùýýûÿÿýÿÿýýýûþþüþþüþþüþþüþþüþþüþþüÿýüÿøùÿûýÿþýóóñïùñøÿúõÿøôÿðÍнš}x]H‰ZH£bN¦UB¨K:·K>¾B8ÈD?ÈGAÁD@³=;¨87¡98=>’<;Œ>>ƒ?<|A=vA=rC=nC5p>5o=4n>4m=3k<2k<2k<2j;1g;0f:/f:/h8.n72q62o51o51m61l50i70i70k:3j92e90d8/c8/c8/c;1b<1cC6_B4]B1^C2`G3bI5_K3\J2]M6dXBe_GomX‚„n‹zlt_6?,28,28.17-17-17-06,06,06,17-17-17-06,06,/5+/5+/4-.3,.3-.3-.3-.3-.3-.3-.3-.3-.3--2,-2,-2,-2,.3-.3-*4,*4,+5,,6-/902<35@26A37B2;F6=H79D33?+3?+9E1?L8GW=HZ@L^DM_EL_AJ]?I\>I\>TgI[nRatXas[[mUO`M:K8+9,%.+%*-$),heVheVheVheVheVheVheVheVheVheVheVheVheVheVheVheVheVhdXjdXkdZlc\md[meZmfVjgTkiTlnYop`svm…‡†£¨¬¿ÃÌÍ×ÙçïòùÿÿüÿÿùýþþþÿÿÿÿþüýÿÿûÿÿûþþöøøðîñæçêßàæØÞåÕçìØêïÙíñÚíïÙìîÖéçÐÚØ¿Îɳ½§¹´¡³­Ÿ¹²¨Á¾·ËÇÄÓÒÎÚÙ×èèæòòðúúøüüúýýûÿÿýÿÿýüüúþþüþþüþþüþþüþþüþþüþþüÿýüÿüýÿûýÿûúûûùøÿúøÿúõÿøöÿòÿÿïîãÑ» ‹•fTN: O<¯RA¹M@½A7ÆB=ÆE?ÀC?³=;©98¡98œ<=’<;Œ>>„@=|A=wB>rC=oD=oD=p@6q?6q?6p>5p>5p>5o?5n>4m>4l=3k<2j;1h<1g;0g;0j:0n72q62p62o51m61m61i70i70l;4k:3f:1e90d90d90c;1c=2cC6`C5`E4aF5bI5cJ6_K3\J2]M6cWAicKpnY‚„nƒˆrYaL2;(28,28.17-17-17-06,06,06,17-17-17-06,06,/5+/5+/4-.3,.3-.3-.3-.3-.3-.3-.3--2,-2,,1+,1+,1+,1+-2,-2,,6.+5-*4+*4++5,.8/0;-2=/2=-5@06A05@/1=)1=)5A-8E1?O5AS9FX>I[AJ]?J]?K^@L_ATgI\oScvZbt\YkSK\I6G4&4'$-*$),"'*heVheVheVheVheVheVheVheVheVheVheVheVheVheVheVheVjdVjdXjdXkdZlc\md[lfZlfVjgTkjUlnYnraqwm€†„œ¦¨·ÀÇÖßäîõûùÿÿüÿÿùýþÿÿÿÿÿýþýûÿÿúÿÿúüüòôôêêîßãçØÝäÒÜäÏäêÐèìÑéíÒììÒëëÓêåÑßÚÆÔͽÕË¿ÎÄ»ÌÁ»ÒÇÅÛÏÏäØÜîãçõìñóòðùù÷ýýûýýûýýûÿÿýþþüüüúþþüþþüþþüþþüþþüþþüþþüÿýüÿûùÿø÷ÿþûüÿÿ÷ÿÿïÿþëÿüðÿÿæúñøÿøõóæ½­t_ŽdN•aI›T>¨M;²K<µK>´I?¯D:§>8¢;6œ:7—<7‘>:ˆ?8€@7xB8sC7oE9oE9p?8q?8q?8q?8q?8p>7o>7o>7o@8n?7m>6k<4h<3h<3h<3l;4o83q62p62p62l71l71i81h91e90b:0a;0a=1_?2aA4`C5_E6WF4XK8\P:]Q;\P8ZN6VO3WP4XT9\ZAjjPpt]}…ms}eCQ:2>*2:-28.28.28.17-17-17-06,17-17-17-06,06,/5+/5+/4--2+-2,-2,-2,-2,-2,-2,-2,-2,,1++0*+0*+0*+0*,1+-2,,6.,6.*4,*4,*4++5,-7,.8--7,0:/4?15@24?/3>.3>.4?/8E3HV?KYBN\CP^EVdM_mVer^cp^YfTJVH5A3&0'$-*$**"((heVheVheVheVheVheVheVheVheVheVheVheVheVheVheVheVjdVjdXjdXkdZlc\md[lfZlfVliVlkVkmXjn]lrhy}”ž ®·¾ÒÛàëòøùÿÿúýÿ÷ûüÿÿÿÿÿýúù÷ÿÿúþýøùùïòòèèìÝãçØßæÔàèÓäêÐèìÑèìÑééÏèèÐéäÐàÛÇ×ÐÀÛÑÅÚÐÇÞÓÍçÜÚïããôèìûðôÿøýúù÷þþüÿÿýýýûýýûÿÿýÿÿýüüúþþüþþüþþüþþüþþüþþüþþüÿýüÿù÷ÿúùÿþûüÿÿöÿþìÿûðÿÿðÿÿòÿýïûïÿþñÿüìíѼ¤zdˆT<¥^H¬Q?³L=µK>µJ@³H>­D>¥>9œ:7—<7‘>:ˆ?8A8xB8tD8pF:pF:p?8q?8q?8q?8q?8q?8p?8p?8qB:pA9n?7l=5i=4j>5j>5n=6o83r73p62p62m82l71i81h91d8/b:0b<1c?3aA4bB5`C5^D5WF4\OK7AO8ES0$.%&/,&,,$**heVheVheVheVheVheVheVheVheVheVheVheVheVheVheVheVjdVjdXjdXkdZlc\md[lfZlfVnmYkmWilWelZembr{x˜š§²¸ÊÓØäëñöþÿøûÿøüýÿÿÿÿÿýúùõÿÿúýýõøøìññåèìÛåéØãëÖçìÖæíÎéîÎêíÐèèÎèæÑéâÒáÙÌÙÏÆÚÌÉßÑÑìÞÞúëîÿôøÿõùÿôûÿøþþýûÿÿýÿÿýþþüþþüÿÿýÿÿýýýûþþüþþüþþüþþüþþüþþüþþüþþüþÿúþÿûûýúûüþþÿÿþÿÿþýÿùöýüúÿÿýÿÿþúÿöíÿ÷èõêÖ¶ž’z`cH–]B–Z@šZAŸXBžS>—J8A0B2A3ˆ@1„A1}B2zB1wD3wC5s>6t=8t=8t=8s>8s>8s>8s>8tB;sA:p?8n=6m<5m<5n=6o>7l:3l:3k:3j92g;2e:1c;1a=1`>2^A3^B4\E5[F5WD3UD2QD1MK4TV>aaGbbH\[?VU9VU7YX:UX;UX=ioSrw`t~eWaI%38D03;.4:04:039/39/39/28.28.17-17-17-06,06,/5+/5+/4--2+-2,-2,-2,-2,-2,-2,-2,,1++0*+0**/)*/)+0*+0*,1++2++2+,3,-4--4-.5./6./6..5-07/4;38?7;C8;C89A68@50;+3>.6A0:E4=I5AM9GS=KWAS_K\gVbm\]hZR]OCMB0:1",$+2+(.*&,(heVheVheVheVheVheVheVheVifWifWifWifWifWifWifWifWkeWkeYkeYle[md]ne\mg[mgWpo[kmWknYkr`jrgpyv†‘“Ÿª°»ÄÉÑØÞèðó÷úÿúþÿÿÿÿÿÿýþýùÿÿúþþöúúî÷÷ëó÷æðôãêòÝéîØð÷ØíòÒëîÑììÒèæÑâÛËÝÕÈÞÔËáÓÐèÚÚòääúëîþòöÿ÷ûÿùÿÿûÿÿþüþþüþþüþþüþþüþþüþþüþþüþþüþþüþþüþþüþþüþþüþþüþþüýÿùýÿúýÿüýþÿýþÿýþÿþýÿÿüÿÿþÿÿýÿÿû÷ÿûòÿþïÿýéÿöÞÿíÓ²†kŸfKS9˜X?£\FŸT?™L:N=‹>.Š>0†>/€=-x=-v>-uB1wC5r=5s<7t=8t=8u@:u@:t?9s>8sA:r@9q@9q@9p?8o>7o>7o>7k92k92k:3l;4i=4g<3e=3b>2a?3\?1cG9`I9S>-L9(J9'>1TR;MO7JJ0LL2[Z>gfJcbDVU7VY<]`EntXzhcmT?I1,:#2>*47B25@03>-1<+2>*9E1BN8IU?O[GVaP]hWYdVLWI-sA6q?6r@7sA8qA7n>4n?5qB8o@6o@6mA6l@5l@5k?4k?4j@4e?4eA5dB6dB6aD6`D6^D5[F5]J9TE2WJ7WL8GA+@:$@;%:8!HN4DM2BH,AE*JO1Y\?abC`aBYY=ffLsw\txaZ_H=B,1:%9B/7=16<26<26<25;15;15;15;15;15;15;14:04:039/39/38127027127116016016005/05/.3-.3--2,-2,,1+,1++0*+0*+0*+0**/)*/)*/)+0*,1+-2,/4..3-/4.1605:4:?9@E?BIA;F89F56C13@.2?+5B.;I2?M6KXDR_MXeSVbTKWI)s@+tD0vE4q?4n<3o=4tB9rB8o?5pA7wH>m>4m>4k?4k?4j>3j>3j>3i?3f@5fB6dB6eC7bE7`D6^D5[F5_L;SD1WJ7_T@OI3B<&C>(DB+@F,@I.@F*<@%>C%LO2_`AijKaaEppVvz_hlUJO86;%4=(=F38>28>48>48>47=37=37=36<28>48>47=37=37=36<26<26;45:349349349338238238227105/05//4..3--2,,1++0*+0*).().().().().(*/)+0*,1+160/4.,1+,1+/4.6;5=BK:4.8/+5--4-,3,gdUgdUheVheVheVheVifWifWifWifWifWifWifWifWifWkeWkeWldYldYmd[md]ne\kg[jiWkmXhmVhpYht`guhm|w†˜˜¥´¹¿ÊÐÔÛãéðö÷úÿúþÿþþþÿÿýÿþùþþöýýñúûíøùçóøâîóÜåîÓâèÌÜßÂÙÙ½×Õ¾ÙÖÅÝ×ËÞ×ÑåÛÜëàæöíòúðøý÷ûÿúþþýûþýûýþøþÿúþÿúþþüþþüþþüþþüþþüþþüþþüþþüþþüþþüþþüþþüþþüþþüýÿþûÿÿûþÿûÿÿþþÿþþüÿýüÿþùÿýùÿþøÿý÷ÿýøÿþûÿÿûÿÿýýÿþüüüÿÿýÿýüøóïúóíüóêã×Ë¢–†iYIcQ=eNdE3\;*tP@lH8hG6jI8hG6`?.\=+`A/bC1bC1`C1`C1_B0_B0^C0]C2XF2XG5XG5XG5UH5TG4QI4PH3QL6HF/WW?ikS]aHIM4DJ0GM3;E*>H->G*39?59?58>48>47=37=37=39?58>48>48>48>48>48>48=67<57<67<66;56;56;55:45:438238216005//4.-2,,1+,1++0,+0,*/+*/++0,,1--2.-2.051.3/+/.+/.-102658<;;B;?K=?N;?N9';J3AP;GVAHVECQ@:H91?2.:.,6-.5--4,gdUgdUgdUheVheVifWifWifWifWifWifWifWifWifWifWkeWkeWldYldYmd[md]ne\kg[jiWkmXinWiqZgs_drejytƒ••£²·½ÈÎÓÚâèïõõøýùýÿþþþÿÿýÿÿúÿÿøÿÿóþÿñüýëöûåðõÞæïÔâèÌÙÜ¿ÕÕ¹ÒйÔÑÀÚÔÈàÙÓêàáôéïýôùÿöþÿüÿÿýÿÿÿýÿþüþÿùþÿúþÿúþþüþþüþþüþþüþþüþþüþþüþþüþþüþþüþþüþþüþþüþþüýÿþûÿÿûþÿûÿÿþþÿþþüÿýüÿþùÿýùÿüöÿûõÿü÷ÿüùÿÿûÿÿýýÿþýýýöõóÿþýÿþúÿþøÿüóÿøìôèØäÔÄÉ·£²›‰ŽxcsXEfK8iJ8nO=rQ@kG7gC3dC2gF5kJ9lK:lM;lM;bC1bC1`C1`C1`C1`C1_D1^D3ZH4YH6YH6YH6VI6UH5QI4PH3NI3KI2eeM|~fosZUY@HN4GM3;E*-;>39?59?58>48>47=37=37=38>48>48>48>48>48>48>48=69>79>89>88=78=78=77<67<66;55:449338227105//4./4.-2.-2.,1-+0,+0,,1--2.-2.,1-,1-,0/,0/.210433764;4;G9=L9@O:@O:&R@(TB*R@(YI0YI0XJ0XJ0YK1YK1YK1WK3VN7VP:UP:TO9RP9QO8LN6LN6JN5NR9enSy‚gisXPZ?AN2;H,<-48>48>48>47=37=38>48>48>48>49?59>7:?8:?9:?9:?99>89>89>88=78=78=77<66;55:4493382382/40.3/-2.,1-+0,+0,+/.+/.+/.,0/-10.21/34/34/34-3/2@15F3;M7>P:=O5:L27I/6H.3E-6H0:L6MJ9DB3=@5;A7;A7;A7:@6:@6:@69?58>48>48>49?59?5:@6:@6:?8;@9;@:;@::?9:?99>89>89>8:?9:?99>89>88=78=77<67<6495273162/40-2.,1-+/.+/.,0/,0/-10.21.23.23-12+1-+9*/@-6H2;M7=O5E#EK'DH%HL)KL*NO/PQ2LM.LL2YY?jjRfdM`^G\ZA][B^]AXW;QP2NJ/FB)G@-FA-E?/C@/C?3??3??5;>5;>58@59A67B48C57D38C58C5:B7:B79A69A68@58@58@5:B7:B7:B7:B79A69A69A69@85A74@62<10;-09(.6'.4(.3,-4--4-)5+)6%%7%9%<#= > #C,K5O,8P6:M9:M:;L98J49K1;N2XW;UT6UQ6JF-JC0FA-D>.A>-A=1??3??5;>5;>58@59A67B48C57D38C58C59A69A68@58@59A69A6:B7:B7:B79A6:B7;C8E=7C97C97A66A36?.4<-39-270.5./6/,8.-:)+=#.B3J 5O8Y$8X&8W+;U2:R8=P<=P=>O<:L6@R8EXVV>XV?YW@XV=XV=YU:XT;QK3OH5LG3IC3DA0C?3??3??5;>5;>58@59A67B48C57D38C58C59A69A68@58@59A69A6:B7:B7:B7:B7:B7;C8E=76=62>41>-1C)9M*BY/Ga1Op;Mm;Ji=Ga>AY?>Q=:M::K8=O9DV5;>59A69A67B47B47D38C58C5:B79A69A69A69A6:B7:B7:B7:B7:B7:B7;C8F;>E=>J@>J@?I>>I;?H7>F7>D8=B;>E>;B;5A75B17I/BV3Pg=XrB^J\|JVuINhEBZ@;N:5H54E2ZS@ZT>XQ>TO;QK;KH7HD8CC7AA7F;?F>>H=>I;?H7>F7>D8=B;=D=;B;5A75B17I/DX5Ri?[uEZ{FXxFRqEJdA+6H2@R8L_CReGSgKOcH@W;7H5/;-07/-4,YgMZhN\hP^jRblTemVgoZkn[lo\lm[mk\mj[liZnhZoi]oi]liXkhYjfZieZie\ie\igZigXfiVchTajUerao|s|ŠŠŽŸ¦¢°»ÁËÔÔÝäéðöòúüôúøñöðëñçéëÞáãÕÜÚËÒѽÌɶÉıþ«¿¸¦¼³¢Ê¾®ÓŸÜÐÄæÙÑíâà÷ëíþõúÿøÿþùÿÿúÿÿüÿÿüÿüýÿûüþüþýþÿÿþþþþþþþþþþþþþþþþþþÿþüÿþüþýûþýûÿýúÿýúÿýúÿûøÿúöþùöÿýúÿûúýùúþúûþüýÿýþÿþÿÿýþÿüûÿüüÿýùÿøó÷ìæòåÝøêáÿôîÿûýÿüÿÿýþÿÿýþÿûýÿüýÿüüýÿüýÿþýÿÿÿÿÿþýÿþõÿüìÿüãÿùßÿýæÿÿëçâÌŒ‡qRL2TN4TM0UN1TN.UO/VQ3VQ3UQ4SO2ON2NM1PL1PL1MM3MM3KO6LP7IQ9JR:LU:IR7JS4OX9SZ8T[9]c?doG“a§sž²š«~‘¢xˆ”pq|Z\bFKQ5KM5JL6KI4LJ5PK7TM:VOF;?F>=G<=H:>G6=E6=C7=B;:A:9@94@65B17I/BV3Ne;Uo?Tu@SsANmAF`=8P6/B.*=*+<)1C-image_width / (dstinfo->max_h_samp_factor * DCTSIZE); + + for (ci = 0; ci < dstinfo->num_components; ci++) { + compptr = dstinfo->comp_info + ci; + comp_width = MCU_cols * compptr->h_samp_factor; + for (blk_y = 0; blk_y < compptr->height_in_blocks; + blk_y += compptr->v_samp_factor) { + buffer = (*srcinfo->mem->access_virt_barray) + ((j_common_ptr) srcinfo, src_coef_arrays[ci], blk_y, + (JDIMENSION) compptr->v_samp_factor, TRUE); + for (offset_y = 0; offset_y < compptr->v_samp_factor; offset_y++) { + for (blk_x = 0; blk_x * 2 < comp_width; blk_x++) { + ptr1 = buffer[offset_y][blk_x]; + ptr2 = buffer[offset_y][comp_width - blk_x - 1]; + /* this unrolled loop doesn't need to know which row it's on... */ + for (k = 0; k < DCTSIZE2; k += 2) { + temp1 = *ptr1; /* swap even column */ + temp2 = *ptr2; + *ptr1++ = temp2; + *ptr2++ = temp1; + temp1 = *ptr1; /* swap odd column with sign change */ + temp2 = *ptr2; + *ptr1++ = -temp2; + *ptr2++ = -temp1; + } + } + } + } + } +} + + +LOCAL(void) +do_flip_v (j_decompress_ptr srcinfo, j_compress_ptr dstinfo, + jvirt_barray_ptr *src_coef_arrays, + jvirt_barray_ptr *dst_coef_arrays) +/* Vertical flip */ +{ + JDIMENSION MCU_rows, comp_height, dst_blk_x, dst_blk_y; + int ci, i, j, offset_y; + JBLOCKARRAY src_buffer, dst_buffer; + JBLOCKROW src_row_ptr, dst_row_ptr; + JCOEFPTR src_ptr, dst_ptr; + jpeg_component_info *compptr; + + /* We output into a separate array because we can't touch different + * rows of the source virtual array simultaneously. Otherwise, this + * is a pretty straightforward analog of horizontal flip. + * Within a DCT block, vertical mirroring is done by changing the signs + * of odd-numbered rows. + * Partial iMCUs at the bottom edge are copied verbatim. + */ + MCU_rows = dstinfo->image_height / (dstinfo->max_v_samp_factor * DCTSIZE); + + for (ci = 0; ci < dstinfo->num_components; ci++) { + compptr = dstinfo->comp_info + ci; + comp_height = MCU_rows * compptr->v_samp_factor; + for (dst_blk_y = 0; dst_blk_y < compptr->height_in_blocks; + dst_blk_y += compptr->v_samp_factor) { + dst_buffer = (*srcinfo->mem->access_virt_barray) + ((j_common_ptr) srcinfo, dst_coef_arrays[ci], dst_blk_y, + (JDIMENSION) compptr->v_samp_factor, TRUE); + if (dst_blk_y < comp_height) { + /* Row is within the mirrorable area. */ + src_buffer = (*srcinfo->mem->access_virt_barray) + ((j_common_ptr) srcinfo, src_coef_arrays[ci], + comp_height - dst_blk_y - (JDIMENSION) compptr->v_samp_factor, + (JDIMENSION) compptr->v_samp_factor, FALSE); + } else { + /* Bottom-edge blocks will be copied verbatim. */ + src_buffer = (*srcinfo->mem->access_virt_barray) + ((j_common_ptr) srcinfo, src_coef_arrays[ci], dst_blk_y, + (JDIMENSION) compptr->v_samp_factor, FALSE); + } + for (offset_y = 0; offset_y < compptr->v_samp_factor; offset_y++) { + if (dst_blk_y < comp_height) { + /* Row is within the mirrorable area. */ + dst_row_ptr = dst_buffer[offset_y]; + src_row_ptr = src_buffer[compptr->v_samp_factor - offset_y - 1]; + for (dst_blk_x = 0; dst_blk_x < compptr->width_in_blocks; + dst_blk_x++) { + dst_ptr = dst_row_ptr[dst_blk_x]; + src_ptr = src_row_ptr[dst_blk_x]; + for (i = 0; i < DCTSIZE; i += 2) { + /* copy even row */ + for (j = 0; j < DCTSIZE; j++) + *dst_ptr++ = *src_ptr++; + /* copy odd row with sign change */ + for (j = 0; j < DCTSIZE; j++) + *dst_ptr++ = - *src_ptr++; + } + } + } else { + /* Just copy row verbatim. */ + jcopy_block_row(src_buffer[offset_y], dst_buffer[offset_y], + compptr->width_in_blocks); + } + } + } + } +} + + +LOCAL(void) +do_transpose (j_decompress_ptr srcinfo, j_compress_ptr dstinfo, + jvirt_barray_ptr *src_coef_arrays, + jvirt_barray_ptr *dst_coef_arrays) +/* Transpose source into destination */ +{ + JDIMENSION dst_blk_x, dst_blk_y; + int ci, i, j, offset_x, offset_y; + JBLOCKARRAY src_buffer, dst_buffer; + JCOEFPTR src_ptr, dst_ptr; + jpeg_component_info *compptr; + + /* Transposing pixels within a block just requires transposing the + * DCT coefficients. + * Partial iMCUs at the edges require no special treatment; we simply + * process all the available DCT blocks for every component. + */ + for (ci = 0; ci < dstinfo->num_components; ci++) { + compptr = dstinfo->comp_info + ci; + for (dst_blk_y = 0; dst_blk_y < compptr->height_in_blocks; + dst_blk_y += compptr->v_samp_factor) { + dst_buffer = (*srcinfo->mem->access_virt_barray) + ((j_common_ptr) srcinfo, dst_coef_arrays[ci], dst_blk_y, + (JDIMENSION) compptr->v_samp_factor, TRUE); + for (offset_y = 0; offset_y < compptr->v_samp_factor; offset_y++) { + for (dst_blk_x = 0; dst_blk_x < compptr->width_in_blocks; + dst_blk_x += compptr->h_samp_factor) { + src_buffer = (*srcinfo->mem->access_virt_barray) + ((j_common_ptr) srcinfo, src_coef_arrays[ci], dst_blk_x, + (JDIMENSION) compptr->h_samp_factor, FALSE); + for (offset_x = 0; offset_x < compptr->h_samp_factor; offset_x++) { + src_ptr = src_buffer[offset_x][dst_blk_y + offset_y]; + dst_ptr = dst_buffer[offset_y][dst_blk_x + offset_x]; + for (i = 0; i < DCTSIZE; i++) + for (j = 0; j < DCTSIZE; j++) + dst_ptr[j*DCTSIZE+i] = src_ptr[i*DCTSIZE+j]; + } + } + } + } + } +} + + +LOCAL(void) +do_rot_90 (j_decompress_ptr srcinfo, j_compress_ptr dstinfo, + jvirt_barray_ptr *src_coef_arrays, + jvirt_barray_ptr *dst_coef_arrays) +/* 90 degree rotation is equivalent to + * 1. Transposing the image; + * 2. Horizontal mirroring. + * These two steps are merged into a single processing routine. + */ +{ + JDIMENSION MCU_cols, comp_width, dst_blk_x, dst_blk_y; + int ci, i, j, offset_x, offset_y; + JBLOCKARRAY src_buffer, dst_buffer; + JCOEFPTR src_ptr, dst_ptr; + jpeg_component_info *compptr; + + /* Because of the horizontal mirror step, we can't process partial iMCUs + * at the (output) right edge properly. They just get transposed and + * not mirrored. + */ + MCU_cols = dstinfo->image_width / (dstinfo->max_h_samp_factor * DCTSIZE); + + for (ci = 0; ci < dstinfo->num_components; ci++) { + compptr = dstinfo->comp_info + ci; + comp_width = MCU_cols * compptr->h_samp_factor; + for (dst_blk_y = 0; dst_blk_y < compptr->height_in_blocks; + dst_blk_y += compptr->v_samp_factor) { + dst_buffer = (*srcinfo->mem->access_virt_barray) + ((j_common_ptr) srcinfo, dst_coef_arrays[ci], dst_blk_y, + (JDIMENSION) compptr->v_samp_factor, TRUE); + for (offset_y = 0; offset_y < compptr->v_samp_factor; offset_y++) { + for (dst_blk_x = 0; dst_blk_x < compptr->width_in_blocks; + dst_blk_x += compptr->h_samp_factor) { + src_buffer = (*srcinfo->mem->access_virt_barray) + ((j_common_ptr) srcinfo, src_coef_arrays[ci], dst_blk_x, + (JDIMENSION) compptr->h_samp_factor, FALSE); + for (offset_x = 0; offset_x < compptr->h_samp_factor; offset_x++) { + src_ptr = src_buffer[offset_x][dst_blk_y + offset_y]; + if (dst_blk_x < comp_width) { + /* Block is within the mirrorable area. */ + dst_ptr = dst_buffer[offset_y] + [comp_width - dst_blk_x - offset_x - 1]; + for (i = 0; i < DCTSIZE; i++) { + for (j = 0; j < DCTSIZE; j++) + dst_ptr[j*DCTSIZE+i] = src_ptr[i*DCTSIZE+j]; + i++; + for (j = 0; j < DCTSIZE; j++) + dst_ptr[j*DCTSIZE+i] = -src_ptr[i*DCTSIZE+j]; + } + } else { + /* Edge blocks are transposed but not mirrored. */ + dst_ptr = dst_buffer[offset_y][dst_blk_x + offset_x]; + for (i = 0; i < DCTSIZE; i++) + for (j = 0; j < DCTSIZE; j++) + dst_ptr[j*DCTSIZE+i] = src_ptr[i*DCTSIZE+j]; + } + } + } + } + } + } +} + + +LOCAL(void) +do_rot_270 (j_decompress_ptr srcinfo, j_compress_ptr dstinfo, + jvirt_barray_ptr *src_coef_arrays, + jvirt_barray_ptr *dst_coef_arrays) +/* 270 degree rotation is equivalent to + * 1. Horizontal mirroring; + * 2. Transposing the image. + * These two steps are merged into a single processing routine. + */ +{ + JDIMENSION MCU_rows, comp_height, dst_blk_x, dst_blk_y; + int ci, i, j, offset_x, offset_y; + JBLOCKARRAY src_buffer, dst_buffer; + JCOEFPTR src_ptr, dst_ptr; + jpeg_component_info *compptr; + + /* Because of the horizontal mirror step, we can't process partial iMCUs + * at the (output) bottom edge properly. They just get transposed and + * not mirrored. + */ + MCU_rows = dstinfo->image_height / (dstinfo->max_v_samp_factor * DCTSIZE); + + for (ci = 0; ci < dstinfo->num_components; ci++) { + compptr = dstinfo->comp_info + ci; + comp_height = MCU_rows * compptr->v_samp_factor; + for (dst_blk_y = 0; dst_blk_y < compptr->height_in_blocks; + dst_blk_y += compptr->v_samp_factor) { + dst_buffer = (*srcinfo->mem->access_virt_barray) + ((j_common_ptr) srcinfo, dst_coef_arrays[ci], dst_blk_y, + (JDIMENSION) compptr->v_samp_factor, TRUE); + for (offset_y = 0; offset_y < compptr->v_samp_factor; offset_y++) { + for (dst_blk_x = 0; dst_blk_x < compptr->width_in_blocks; + dst_blk_x += compptr->h_samp_factor) { + src_buffer = (*srcinfo->mem->access_virt_barray) + ((j_common_ptr) srcinfo, src_coef_arrays[ci], dst_blk_x, + (JDIMENSION) compptr->h_samp_factor, FALSE); + for (offset_x = 0; offset_x < compptr->h_samp_factor; offset_x++) { + dst_ptr = dst_buffer[offset_y][dst_blk_x + offset_x]; + if (dst_blk_y < comp_height) { + /* Block is within the mirrorable area. */ + src_ptr = src_buffer[offset_x] + [comp_height - dst_blk_y - offset_y - 1]; + for (i = 0; i < DCTSIZE; i++) { + for (j = 0; j < DCTSIZE; j++) { + dst_ptr[j*DCTSIZE+i] = src_ptr[i*DCTSIZE+j]; + j++; + dst_ptr[j*DCTSIZE+i] = -src_ptr[i*DCTSIZE+j]; + } + } + } else { + /* Edge blocks are transposed but not mirrored. */ + src_ptr = src_buffer[offset_x][dst_blk_y + offset_y]; + for (i = 0; i < DCTSIZE; i++) + for (j = 0; j < DCTSIZE; j++) + dst_ptr[j*DCTSIZE+i] = src_ptr[i*DCTSIZE+j]; + } + } + } + } + } + } +} + + +LOCAL(void) +do_rot_180 (j_decompress_ptr srcinfo, j_compress_ptr dstinfo, + jvirt_barray_ptr *src_coef_arrays, + jvirt_barray_ptr *dst_coef_arrays) +/* 180 degree rotation is equivalent to + * 1. Vertical mirroring; + * 2. Horizontal mirroring. + * These two steps are merged into a single processing routine. + */ +{ + JDIMENSION MCU_cols, MCU_rows, comp_width, comp_height, dst_blk_x, dst_blk_y; + int ci, i, j, offset_y; + JBLOCKARRAY src_buffer, dst_buffer; + JBLOCKROW src_row_ptr, dst_row_ptr; + JCOEFPTR src_ptr, dst_ptr; + jpeg_component_info *compptr; + + MCU_cols = dstinfo->image_width / (dstinfo->max_h_samp_factor * DCTSIZE); + MCU_rows = dstinfo->image_height / (dstinfo->max_v_samp_factor * DCTSIZE); + + for (ci = 0; ci < dstinfo->num_components; ci++) { + compptr = dstinfo->comp_info + ci; + comp_width = MCU_cols * compptr->h_samp_factor; + comp_height = MCU_rows * compptr->v_samp_factor; + for (dst_blk_y = 0; dst_blk_y < compptr->height_in_blocks; + dst_blk_y += compptr->v_samp_factor) { + dst_buffer = (*srcinfo->mem->access_virt_barray) + ((j_common_ptr) srcinfo, dst_coef_arrays[ci], dst_blk_y, + (JDIMENSION) compptr->v_samp_factor, TRUE); + if (dst_blk_y < comp_height) { + /* Row is within the vertically mirrorable area. */ + src_buffer = (*srcinfo->mem->access_virt_barray) + ((j_common_ptr) srcinfo, src_coef_arrays[ci], + comp_height - dst_blk_y - (JDIMENSION) compptr->v_samp_factor, + (JDIMENSION) compptr->v_samp_factor, FALSE); + } else { + /* Bottom-edge rows are only mirrored horizontally. */ + src_buffer = (*srcinfo->mem->access_virt_barray) + ((j_common_ptr) srcinfo, src_coef_arrays[ci], dst_blk_y, + (JDIMENSION) compptr->v_samp_factor, FALSE); + } + for (offset_y = 0; offset_y < compptr->v_samp_factor; offset_y++) { + if (dst_blk_y < comp_height) { + /* Row is within the mirrorable area. */ + dst_row_ptr = dst_buffer[offset_y]; + src_row_ptr = src_buffer[compptr->v_samp_factor - offset_y - 1]; + /* Process the blocks that can be mirrored both ways. */ + for (dst_blk_x = 0; dst_blk_x < comp_width; dst_blk_x++) { + dst_ptr = dst_row_ptr[dst_blk_x]; + src_ptr = src_row_ptr[comp_width - dst_blk_x - 1]; + for (i = 0; i < DCTSIZE; i += 2) { + /* For even row, negate every odd column. */ + for (j = 0; j < DCTSIZE; j += 2) { + *dst_ptr++ = *src_ptr++; + *dst_ptr++ = - *src_ptr++; + } + /* For odd row, negate every even column. */ + for (j = 0; j < DCTSIZE; j += 2) { + *dst_ptr++ = - *src_ptr++; + *dst_ptr++ = *src_ptr++; + } + } + } + /* Any remaining right-edge blocks are only mirrored vertically. */ + for (; dst_blk_x < compptr->width_in_blocks; dst_blk_x++) { + dst_ptr = dst_row_ptr[dst_blk_x]; + src_ptr = src_row_ptr[dst_blk_x]; + for (i = 0; i < DCTSIZE; i += 2) { + for (j = 0; j < DCTSIZE; j++) + *dst_ptr++ = *src_ptr++; + for (j = 0; j < DCTSIZE; j++) + *dst_ptr++ = - *src_ptr++; + } + } + } else { + /* Remaining rows are just mirrored horizontally. */ + dst_row_ptr = dst_buffer[offset_y]; + src_row_ptr = src_buffer[offset_y]; + /* Process the blocks that can be mirrored. */ + for (dst_blk_x = 0; dst_blk_x < comp_width; dst_blk_x++) { + dst_ptr = dst_row_ptr[dst_blk_x]; + src_ptr = src_row_ptr[comp_width - dst_blk_x - 1]; + for (i = 0; i < DCTSIZE2; i += 2) { + *dst_ptr++ = *src_ptr++; + *dst_ptr++ = - *src_ptr++; + } + } + /* Any remaining right-edge blocks are only copied. */ + for (; dst_blk_x < compptr->width_in_blocks; dst_blk_x++) { + dst_ptr = dst_row_ptr[dst_blk_x]; + src_ptr = src_row_ptr[dst_blk_x]; + for (i = 0; i < DCTSIZE2; i++) + *dst_ptr++ = *src_ptr++; + } + } + } + } + } +} + + +LOCAL(void) +do_transverse (j_decompress_ptr srcinfo, j_compress_ptr dstinfo, + jvirt_barray_ptr *src_coef_arrays, + jvirt_barray_ptr *dst_coef_arrays) +/* Transverse transpose is equivalent to + * 1. 180 degree rotation; + * 2. Transposition; + * or + * 1. Horizontal mirroring; + * 2. Transposition; + * 3. Horizontal mirroring. + * These steps are merged into a single processing routine. + */ +{ + JDIMENSION MCU_cols, MCU_rows, comp_width, comp_height, dst_blk_x, dst_blk_y; + int ci, i, j, offset_x, offset_y; + JBLOCKARRAY src_buffer, dst_buffer; + JCOEFPTR src_ptr, dst_ptr; + jpeg_component_info *compptr; + + MCU_cols = dstinfo->image_width / (dstinfo->max_h_samp_factor * DCTSIZE); + MCU_rows = dstinfo->image_height / (dstinfo->max_v_samp_factor * DCTSIZE); + + for (ci = 0; ci < dstinfo->num_components; ci++) { + compptr = dstinfo->comp_info + ci; + comp_width = MCU_cols * compptr->h_samp_factor; + comp_height = MCU_rows * compptr->v_samp_factor; + for (dst_blk_y = 0; dst_blk_y < compptr->height_in_blocks; + dst_blk_y += compptr->v_samp_factor) { + dst_buffer = (*srcinfo->mem->access_virt_barray) + ((j_common_ptr) srcinfo, dst_coef_arrays[ci], dst_blk_y, + (JDIMENSION) compptr->v_samp_factor, TRUE); + for (offset_y = 0; offset_y < compptr->v_samp_factor; offset_y++) { + for (dst_blk_x = 0; dst_blk_x < compptr->width_in_blocks; + dst_blk_x += compptr->h_samp_factor) { + src_buffer = (*srcinfo->mem->access_virt_barray) + ((j_common_ptr) srcinfo, src_coef_arrays[ci], dst_blk_x, + (JDIMENSION) compptr->h_samp_factor, FALSE); + for (offset_x = 0; offset_x < compptr->h_samp_factor; offset_x++) { + if (dst_blk_y < comp_height) { + src_ptr = src_buffer[offset_x] + [comp_height - dst_blk_y - offset_y - 1]; + if (dst_blk_x < comp_width) { + /* Block is within the mirrorable area. */ + dst_ptr = dst_buffer[offset_y] + [comp_width - dst_blk_x - offset_x - 1]; + for (i = 0; i < DCTSIZE; i++) { + for (j = 0; j < DCTSIZE; j++) { + dst_ptr[j*DCTSIZE+i] = src_ptr[i*DCTSIZE+j]; + j++; + dst_ptr[j*DCTSIZE+i] = -src_ptr[i*DCTSIZE+j]; + } + i++; + for (j = 0; j < DCTSIZE; j++) { + dst_ptr[j*DCTSIZE+i] = -src_ptr[i*DCTSIZE+j]; + j++; + dst_ptr[j*DCTSIZE+i] = src_ptr[i*DCTSIZE+j]; + } + } + } else { + /* Right-edge blocks are mirrored in y only */ + dst_ptr = dst_buffer[offset_y][dst_blk_x + offset_x]; + for (i = 0; i < DCTSIZE; i++) { + for (j = 0; j < DCTSIZE; j++) { + dst_ptr[j*DCTSIZE+i] = src_ptr[i*DCTSIZE+j]; + j++; + dst_ptr[j*DCTSIZE+i] = -src_ptr[i*DCTSIZE+j]; + } + } + } + } else { + src_ptr = src_buffer[offset_x][dst_blk_y + offset_y]; + if (dst_blk_x < comp_width) { + /* Bottom-edge blocks are mirrored in x only */ + dst_ptr = dst_buffer[offset_y] + [comp_width - dst_blk_x - offset_x - 1]; + for (i = 0; i < DCTSIZE; i++) { + for (j = 0; j < DCTSIZE; j++) + dst_ptr[j*DCTSIZE+i] = src_ptr[i*DCTSIZE+j]; + i++; + for (j = 0; j < DCTSIZE; j++) + dst_ptr[j*DCTSIZE+i] = -src_ptr[i*DCTSIZE+j]; + } + } else { + /* At lower right corner, just transpose, no mirroring */ + dst_ptr = dst_buffer[offset_y][dst_blk_x + offset_x]; + for (i = 0; i < DCTSIZE; i++) + for (j = 0; j < DCTSIZE; j++) + dst_ptr[j*DCTSIZE+i] = src_ptr[i*DCTSIZE+j]; + } + } + } + } + } + } + } +} + + +/* Request any required workspace. + * + * We allocate the workspace virtual arrays from the source decompression + * object, so that all the arrays (both the original data and the workspace) + * will be taken into account while making memory management decisions. + * Hence, this routine must be called after jpeg_read_header (which reads + * the image dimensions) and before jpeg_read_coefficients (which realizes + * the source's virtual arrays). + */ + +GLOBAL(void) +jtransform_request_workspace (j_decompress_ptr srcinfo, + jpeg_transform_info *info) +{ + jvirt_barray_ptr *coef_arrays = NULL; + jpeg_component_info *compptr; + int ci; + + if (info->force_grayscale && + srcinfo->jpeg_color_space == JCS_YCbCr && + srcinfo->num_components == 3) { + /* We'll only process the first component */ + info->num_components = 1; + } else { + /* Process all the components */ + info->num_components = srcinfo->num_components; + } + + switch (info->transform) { + case JXFORM_NONE: + case JXFORM_FLIP_H: + /* Don't need a workspace array */ + break; + case JXFORM_FLIP_V: + case JXFORM_ROT_180: + /* Need workspace arrays having same dimensions as source image. + * Note that we allocate arrays padded out to the next iMCU boundary, + * so that transform routines need not worry about missing edge blocks. + */ + coef_arrays = (jvirt_barray_ptr *) + (*srcinfo->mem->alloc_small) ((j_common_ptr) srcinfo, JPOOL_IMAGE, + SIZEOF(jvirt_barray_ptr) * info->num_components); + for (ci = 0; ci < info->num_components; ci++) { + compptr = srcinfo->comp_info + ci; + coef_arrays[ci] = (*srcinfo->mem->request_virt_barray) + ((j_common_ptr) srcinfo, JPOOL_IMAGE, FALSE, + (JDIMENSION) jround_up((long) compptr->width_in_blocks, + (long) compptr->h_samp_factor), + (JDIMENSION) jround_up((long) compptr->height_in_blocks, + (long) compptr->v_samp_factor), + (JDIMENSION) compptr->v_samp_factor); + } + break; + case JXFORM_TRANSPOSE: + case JXFORM_TRANSVERSE: + case JXFORM_ROT_90: + case JXFORM_ROT_270: + /* Need workspace arrays having transposed dimensions. + * Note that we allocate arrays padded out to the next iMCU boundary, + * so that transform routines need not worry about missing edge blocks. + */ + coef_arrays = (jvirt_barray_ptr *) + (*srcinfo->mem->alloc_small) ((j_common_ptr) srcinfo, JPOOL_IMAGE, + SIZEOF(jvirt_barray_ptr) * info->num_components); + for (ci = 0; ci < info->num_components; ci++) { + compptr = srcinfo->comp_info + ci; + coef_arrays[ci] = (*srcinfo->mem->request_virt_barray) + ((j_common_ptr) srcinfo, JPOOL_IMAGE, FALSE, + (JDIMENSION) jround_up((long) compptr->height_in_blocks, + (long) compptr->v_samp_factor), + (JDIMENSION) jround_up((long) compptr->width_in_blocks, + (long) compptr->h_samp_factor), + (JDIMENSION) compptr->h_samp_factor); + } + break; + } + info->workspace_coef_arrays = coef_arrays; +} + + +/* Transpose destination image parameters */ + +LOCAL(void) +transpose_critical_parameters (j_compress_ptr dstinfo) +{ + int tblno, i, j, ci, itemp; + jpeg_component_info *compptr; + JQUANT_TBL *qtblptr; + JDIMENSION dtemp; + UINT16 qtemp; + + /* Transpose basic image dimensions */ + dtemp = dstinfo->image_width; + dstinfo->image_width = dstinfo->image_height; + dstinfo->image_height = dtemp; + + /* Transpose sampling factors */ + for (ci = 0; ci < dstinfo->num_components; ci++) { + compptr = dstinfo->comp_info + ci; + itemp = compptr->h_samp_factor; + compptr->h_samp_factor = compptr->v_samp_factor; + compptr->v_samp_factor = itemp; + } + + /* Transpose quantization tables */ + for (tblno = 0; tblno < NUM_QUANT_TBLS; tblno++) { + qtblptr = dstinfo->quant_tbl_ptrs[tblno]; + if (qtblptr != NULL) { + for (i = 0; i < DCTSIZE; i++) { + for (j = 0; j < i; j++) { + qtemp = qtblptr->quantval[i*DCTSIZE+j]; + qtblptr->quantval[i*DCTSIZE+j] = qtblptr->quantval[j*DCTSIZE+i]; + qtblptr->quantval[j*DCTSIZE+i] = qtemp; + } + } + } + } +} + + +/* Trim off any partial iMCUs on the indicated destination edge */ + +LOCAL(void) +trim_right_edge (j_compress_ptr dstinfo) +{ + int ci, max_h_samp_factor; + JDIMENSION MCU_cols; + + /* We have to compute max_h_samp_factor ourselves, + * because it hasn't been set yet in the destination + * (and we don't want to use the source's value). + */ + max_h_samp_factor = 1; + for (ci = 0; ci < dstinfo->num_components; ci++) { + int h_samp_factor = dstinfo->comp_info[ci].h_samp_factor; + max_h_samp_factor = MAX(max_h_samp_factor, h_samp_factor); + } + MCU_cols = dstinfo->image_width / (max_h_samp_factor * DCTSIZE); + if (MCU_cols > 0) /* can't trim to 0 pixels */ + dstinfo->image_width = MCU_cols * (max_h_samp_factor * DCTSIZE); +} + +LOCAL(void) +trim_bottom_edge (j_compress_ptr dstinfo) +{ + int ci, max_v_samp_factor; + JDIMENSION MCU_rows; + + /* We have to compute max_v_samp_factor ourselves, + * because it hasn't been set yet in the destination + * (and we don't want to use the source's value). + */ + max_v_samp_factor = 1; + for (ci = 0; ci < dstinfo->num_components; ci++) { + int v_samp_factor = dstinfo->comp_info[ci].v_samp_factor; + max_v_samp_factor = MAX(max_v_samp_factor, v_samp_factor); + } + MCU_rows = dstinfo->image_height / (max_v_samp_factor * DCTSIZE); + if (MCU_rows > 0) /* can't trim to 0 pixels */ + dstinfo->image_height = MCU_rows * (max_v_samp_factor * DCTSIZE); +} + + +/* Adjust output image parameters as needed. + * + * This must be called after jpeg_copy_critical_parameters() + * and before jpeg_write_coefficients(). + * + * The return value is the set of virtual coefficient arrays to be written + * (either the ones allocated by jtransform_request_workspace, or the + * original source data arrays). The caller will need to pass this value + * to jpeg_write_coefficients(). + */ + +GLOBAL(jvirt_barray_ptr *) +jtransform_adjust_parameters (j_decompress_ptr srcinfo, + j_compress_ptr dstinfo, + jvirt_barray_ptr *src_coef_arrays, + jpeg_transform_info *info) +{ + /* If force-to-grayscale is requested, adjust destination parameters */ + if (info->force_grayscale) { + /* We use jpeg_set_colorspace to make sure subsidiary settings get fixed + * properly. Among other things, the target h_samp_factor & v_samp_factor + * will get set to 1, which typically won't match the source. + * In fact we do this even if the source is already grayscale; that + * provides an easy way of coercing a grayscale JPEG with funny sampling + * factors to the customary 1,1. (Some decoders fail on other factors.) + */ + if ((dstinfo->jpeg_color_space == JCS_YCbCr && + dstinfo->num_components == 3) || + (dstinfo->jpeg_color_space == JCS_GRAYSCALE && + dstinfo->num_components == 1)) { + /* We have to preserve the source's quantization table number. */ + int sv_quant_tbl_no = dstinfo->comp_info[0].quant_tbl_no; + jpeg_set_colorspace(dstinfo, JCS_GRAYSCALE); + dstinfo->comp_info[0].quant_tbl_no = sv_quant_tbl_no; + } else { + /* Sorry, can't do it */ + ERREXIT(dstinfo, JERR_CONVERSION_NOTIMPL); + } + } + + /* Correct the destination's image dimensions etc if necessary */ + switch (info->transform) { + case JXFORM_NONE: + /* Nothing to do */ + break; + case JXFORM_FLIP_H: + if (info->trim) + trim_right_edge(dstinfo); + break; + case JXFORM_FLIP_V: + if (info->trim) + trim_bottom_edge(dstinfo); + break; + case JXFORM_TRANSPOSE: + transpose_critical_parameters(dstinfo); + /* transpose does NOT have to trim anything */ + break; + case JXFORM_TRANSVERSE: + transpose_critical_parameters(dstinfo); + if (info->trim) { + trim_right_edge(dstinfo); + trim_bottom_edge(dstinfo); + } + break; + case JXFORM_ROT_90: + transpose_critical_parameters(dstinfo); + if (info->trim) + trim_right_edge(dstinfo); + break; + case JXFORM_ROT_180: + if (info->trim) { + trim_right_edge(dstinfo); + trim_bottom_edge(dstinfo); + } + break; + case JXFORM_ROT_270: + transpose_critical_parameters(dstinfo); + if (info->trim) + trim_bottom_edge(dstinfo); + break; + } + + /* Return the appropriate output data set */ + if (info->workspace_coef_arrays != NULL) + return info->workspace_coef_arrays; + return src_coef_arrays; +} + + +/* Execute the actual transformation, if any. + * + * This must be called *after* jpeg_write_coefficients, because it depends + * on jpeg_write_coefficients to have computed subsidiary values such as + * the per-component width and height fields in the destination object. + * + * Note that some transformations will modify the source data arrays! + */ + +GLOBAL(void) +jtransform_execute_transformation (j_decompress_ptr srcinfo, + j_compress_ptr dstinfo, + jvirt_barray_ptr *src_coef_arrays, + jpeg_transform_info *info) +{ + jvirt_barray_ptr *dst_coef_arrays = info->workspace_coef_arrays; + + switch (info->transform) { + case JXFORM_NONE: + break; + case JXFORM_FLIP_H: + do_flip_h(srcinfo, dstinfo, src_coef_arrays); + break; + case JXFORM_FLIP_V: + do_flip_v(srcinfo, dstinfo, src_coef_arrays, dst_coef_arrays); + break; + case JXFORM_TRANSPOSE: + do_transpose(srcinfo, dstinfo, src_coef_arrays, dst_coef_arrays); + break; + case JXFORM_TRANSVERSE: + do_transverse(srcinfo, dstinfo, src_coef_arrays, dst_coef_arrays); + break; + case JXFORM_ROT_90: + do_rot_90(srcinfo, dstinfo, src_coef_arrays, dst_coef_arrays); + break; + case JXFORM_ROT_180: + do_rot_180(srcinfo, dstinfo, src_coef_arrays, dst_coef_arrays); + break; + case JXFORM_ROT_270: + do_rot_270(srcinfo, dstinfo, src_coef_arrays, dst_coef_arrays); + break; + } +} + +#endif /* TRANSFORMS_SUPPORTED */ + + +/* Setup decompression object to save desired markers in memory. + * This must be called before jpeg_read_header() to have the desired effect. + */ + +GLOBAL(void) +jcopy_markers_setup (j_decompress_ptr srcinfo, JCOPY_OPTION option) +{ +#ifdef SAVE_MARKERS_SUPPORTED + int m; + + /* Save comments except under NONE option */ + if (option != JCOPYOPT_NONE) { + jpeg_save_markers(srcinfo, JPEG_COM, 0xFFFF); + } + /* Save all types of APPn markers iff ALL option */ + if (option == JCOPYOPT_ALL) { + for (m = 0; m < 16; m++) + jpeg_save_markers(srcinfo, JPEG_APP0 + m, 0xFFFF); + } +#endif /* SAVE_MARKERS_SUPPORTED */ +} + +/* Copy markers saved in the given source object to the destination object. + * This should be called just after jpeg_start_compress() or + * jpeg_write_coefficients(). + * Note that those routines will have written the SOI, and also the + * JFIF APP0 or Adobe APP14 markers if selected. + */ + +GLOBAL(void) +jcopy_markers_execute (j_decompress_ptr srcinfo, j_compress_ptr dstinfo, + JCOPY_OPTION option) +{ + jpeg_saved_marker_ptr marker; + + /* In the current implementation, we don't actually need to examine the + * option flag here; we just copy everything that got saved. + * But to avoid confusion, we do not output JFIF and Adobe APP14 markers + * if the encoder library already wrote one. + */ + for (marker = srcinfo->marker_list; marker != NULL; marker = marker->next) { + if (dstinfo->write_JFIF_header && + marker->marker == JPEG_APP0 && + marker->data_length >= 5 && + GETJOCTET(marker->data[0]) == 0x4A && + GETJOCTET(marker->data[1]) == 0x46 && + GETJOCTET(marker->data[2]) == 0x49 && + GETJOCTET(marker->data[3]) == 0x46 && + GETJOCTET(marker->data[4]) == 0) + continue; /* reject duplicate JFIF */ + if (dstinfo->write_Adobe_marker && + marker->marker == JPEG_APP0+14 && + marker->data_length >= 5 && + GETJOCTET(marker->data[0]) == 0x41 && + GETJOCTET(marker->data[1]) == 0x64 && + GETJOCTET(marker->data[2]) == 0x6F && + GETJOCTET(marker->data[3]) == 0x62 && + GETJOCTET(marker->data[4]) == 0x65) + continue; /* reject duplicate Adobe */ +#ifdef NEED_FAR_POINTERS + /* We could use jpeg_write_marker if the data weren't FAR... */ + { + unsigned int i; + jpeg_write_m_header(dstinfo, marker->marker, marker->data_length); + for (i = 0; i < marker->data_length; i++) + jpeg_write_m_byte(dstinfo, marker->data[i]); + } +#else + jpeg_write_marker(dstinfo, marker->marker, + marker->data, marker->data_length); +#endif + } +} diff --git a/transupp.h b/transupp.h new file mode 100644 index 00000000..5c2d32af --- /dev/null +++ b/transupp.h @@ -0,0 +1,135 @@ +/* + * transupp.h + * + * Copyright (C) 1997, Thomas G. Lane. + * This file is part of the Independent JPEG Group's software. + * For conditions of distribution and use, see the accompanying README file. + * + * This file contains declarations for image transformation routines and + * other utility code used by the jpegtran sample application. These are + * NOT part of the core JPEG library. But we keep these routines separate + * from jpegtran.c to ease the task of maintaining jpegtran-like programs + * that have other user interfaces. + * + * NOTE: all the routines declared here have very specific requirements + * about when they are to be executed during the reading and writing of the + * source and destination files. See the comments in transupp.c, or see + * jpegtran.c for an example of correct usage. + */ + +/* If you happen not to want the image transform support, disable it here */ +#ifndef TRANSFORMS_SUPPORTED +#define TRANSFORMS_SUPPORTED 1 /* 0 disables transform code */ +#endif + +/* Short forms of external names for systems with brain-damaged linkers. */ + +#ifdef NEED_SHORT_EXTERNAL_NAMES +#define jtransform_request_workspace jTrRequest +#define jtransform_adjust_parameters jTrAdjust +#define jtransform_execute_transformation jTrExec +#define jcopy_markers_setup jCMrkSetup +#define jcopy_markers_execute jCMrkExec +#endif /* NEED_SHORT_EXTERNAL_NAMES */ + + +/* + * Codes for supported types of image transformations. + */ + +typedef enum { + JXFORM_NONE, /* no transformation */ + JXFORM_FLIP_H, /* horizontal flip */ + JXFORM_FLIP_V, /* vertical flip */ + JXFORM_TRANSPOSE, /* transpose across UL-to-LR axis */ + JXFORM_TRANSVERSE, /* transpose across UR-to-LL axis */ + JXFORM_ROT_90, /* 90-degree clockwise rotation */ + JXFORM_ROT_180, /* 180-degree rotation */ + JXFORM_ROT_270 /* 270-degree clockwise (or 90 ccw) */ +} JXFORM_CODE; + +/* + * Although rotating and flipping data expressed as DCT coefficients is not + * hard, there is an asymmetry in the JPEG format specification for images + * whose dimensions aren't multiples of the iMCU size. The right and bottom + * image edges are padded out to the next iMCU boundary with junk data; but + * no padding is possible at the top and left edges. If we were to flip + * the whole image including the pad data, then pad garbage would become + * visible at the top and/or left, and real pixels would disappear into the + * pad margins --- perhaps permanently, since encoders & decoders may not + * bother to preserve DCT blocks that appear to be completely outside the + * nominal image area. So, we have to exclude any partial iMCUs from the + * basic transformation. + * + * Transpose is the only transformation that can handle partial iMCUs at the + * right and bottom edges completely cleanly. flip_h can flip partial iMCUs + * at the bottom, but leaves any partial iMCUs at the right edge untouched. + * Similarly flip_v leaves any partial iMCUs at the bottom edge untouched. + * The other transforms are defined as combinations of these basic transforms + * and process edge blocks in a way that preserves the equivalence. + * + * The "trim" option causes untransformable partial iMCUs to be dropped; + * this is not strictly lossless, but it usually gives the best-looking + * result for odd-size images. Note that when this option is active, + * the expected mathematical equivalences between the transforms may not hold. + * (For example, -rot 270 -trim trims only the bottom edge, but -rot 90 -trim + * followed by -rot 180 -trim trims both edges.) + * + * We also offer a "force to grayscale" option, which simply discards the + * chrominance channels of a YCbCr image. This is lossless in the sense that + * the luminance channel is preserved exactly. It's not the same kind of + * thing as the rotate/flip transformations, but it's convenient to handle it + * as part of this package, mainly because the transformation routines have to + * be aware of the option to know how many components to work on. + */ + +typedef struct { + /* Options: set by caller */ + JXFORM_CODE transform; /* image transform operator */ + boolean trim; /* if TRUE, trim partial MCUs as needed */ + boolean force_grayscale; /* if TRUE, convert color image to grayscale */ + + /* Internal workspace: caller should not touch these */ + int num_components; /* # of components in workspace */ + jvirt_barray_ptr * workspace_coef_arrays; /* workspace for transformations */ +} jpeg_transform_info; + + +#if TRANSFORMS_SUPPORTED + +/* Request any required workspace */ +EXTERN(void) jtransform_request_workspace + JPP((j_decompress_ptr srcinfo, jpeg_transform_info *info)); +/* Adjust output image parameters */ +EXTERN(jvirt_barray_ptr *) jtransform_adjust_parameters + JPP((j_decompress_ptr srcinfo, j_compress_ptr dstinfo, + jvirt_barray_ptr *src_coef_arrays, + jpeg_transform_info *info)); +/* Execute the actual transformation, if any */ +EXTERN(void) jtransform_execute_transformation + JPP((j_decompress_ptr srcinfo, j_compress_ptr dstinfo, + jvirt_barray_ptr *src_coef_arrays, + jpeg_transform_info *info)); + +#endif /* TRANSFORMS_SUPPORTED */ + + +/* + * Support for copying optional markers from source to destination file. + */ + +typedef enum { + JCOPYOPT_NONE, /* copy no optional markers */ + JCOPYOPT_COMMENTS, /* copy only comment (COM) markers */ + JCOPYOPT_ALL /* copy all optional markers */ +} JCOPY_OPTION; + +#define JCOPYOPT_DEFAULT JCOPYOPT_COMMENTS /* recommended default */ + +/* Setup decompression object to save desired markers in memory */ +EXTERN(void) jcopy_markers_setup + JPP((j_decompress_ptr srcinfo, JCOPY_OPTION option)); +/* Copy markers saved in the given source object to the destination object */ +EXTERN(void) jcopy_markers_execute + JPP((j_decompress_ptr srcinfo, j_compress_ptr dstinfo, + JCOPY_OPTION option)); diff --git a/usage.doc b/usage.doc new file mode 100644 index 00000000..8c4970af --- /dev/null +++ b/usage.doc @@ -0,0 +1,562 @@ +USAGE instructions for the Independent JPEG Group's JPEG software +================================================================= + +This file describes usage of the JPEG conversion programs cjpeg and djpeg, +as well as the utility programs jpegtran, rdjpgcom and wrjpgcom. (See +the other documentation files if you wish to use the JPEG library within +your own programs.) + +If you are on a Unix machine you may prefer to read the Unix-style manual +pages in files cjpeg.1, djpeg.1, jpegtran.1, rdjpgcom.1, wrjpgcom.1. + + +INTRODUCTION + +These programs implement JPEG image compression and decompression. JPEG +(pronounced "jay-peg") is a standardized compression method for full-color +and gray-scale images. JPEG is designed to handle "real-world" scenes, +for example scanned photographs. Cartoons, line drawings, and other +non-realistic images are not JPEG's strong suit; on that sort of material +you may get poor image quality and/or little compression. + +JPEG is lossy, meaning that the output image is not necessarily identical to +the input image. Hence you should not use JPEG if you have to have identical +output bits. However, on typical real-world images, very good compression +levels can be obtained with no visible change, and amazingly high compression +is possible if you can tolerate a low-quality image. You can trade off image +quality against file size by adjusting the compressor's "quality" setting. + + +GENERAL USAGE + +We provide two programs, cjpeg to compress an image file into JPEG format, +and djpeg to decompress a JPEG file back into a conventional image format. + +On Unix-like systems, you say: + cjpeg [switches] [imagefile] >jpegfile +or + djpeg [switches] [jpegfile] >imagefile +The programs read the specified input file, or standard input if none is +named. They always write to standard output (with trace/error messages to +standard error). These conventions are handy for piping images between +programs. + +On most non-Unix systems, you say: + cjpeg [switches] imagefile jpegfile +or + djpeg [switches] jpegfile imagefile +i.e., both the input and output files are named on the command line. This +style is a little more foolproof, and it loses no functionality if you don't +have pipes. (You can get this style on Unix too, if you prefer, by defining +TWO_FILE_COMMANDLINE when you compile the programs; see install.doc.) + +You can also say: + cjpeg [switches] -outfile jpegfile imagefile +or + djpeg [switches] -outfile imagefile jpegfile +This syntax works on all systems, so it is useful for scripts. + +The currently supported image file formats are: PPM (PBMPLUS color format), +PGM (PBMPLUS gray-scale format), BMP, Targa, and RLE (Utah Raster Toolkit +format). (RLE is supported only if the URT library is available.) +cjpeg recognizes the input image format automatically, with the exception +of some Targa-format files. You have to tell djpeg which format to generate. + +JPEG files are in the defacto standard JFIF file format. There are other, +less widely used JPEG-based file formats, but we don't support them. + +All switch names may be abbreviated; for example, -grayscale may be written +-gray or -gr. Most of the "basic" switches can be abbreviated to as little as +one letter. Upper and lower case are equivalent (-BMP is the same as -bmp). +British spellings are also accepted (e.g., -greyscale), though for brevity +these are not mentioned below. + + +CJPEG DETAILS + +The basic command line switches for cjpeg are: + + -quality N Scale quantization tables to adjust image quality. + Quality is 0 (worst) to 100 (best); default is 75. + (See below for more info.) + + -grayscale Create monochrome JPEG file from color input. + Be sure to use this switch when compressing a grayscale + BMP file, because cjpeg isn't bright enough to notice + whether a BMP file uses only shades of gray. By + saying -grayscale, you'll get a smaller JPEG file that + takes less time to process. + + -optimize Perform optimization of entropy encoding parameters. + Without this, default encoding parameters are used. + -optimize usually makes the JPEG file a little smaller, + but cjpeg runs somewhat slower and needs much more + memory. Image quality and speed of decompression are + unaffected by -optimize. + + -progressive Create progressive JPEG file (see below). + + -targa Input file is Targa format. Targa files that contain + an "identification" field will not be automatically + recognized by cjpeg; for such files you must specify + -targa to make cjpeg treat the input as Targa format. + For most Targa files, you won't need this switch. + +The -quality switch lets you trade off compressed file size against quality of +the reconstructed image: the higher the quality setting, the larger the JPEG +file, and the closer the output image will be to the original input. Normally +you want to use the lowest quality setting (smallest file) that decompresses +into something visually indistinguishable from the original image. For this +purpose the quality setting should be between 50 and 95; the default of 75 is +often about right. If you see defects at -quality 75, then go up 5 or 10 +counts at a time until you are happy with the output image. (The optimal +setting will vary from one image to another.) + +-quality 100 will generate a quantization table of all 1's, minimizing loss +in the quantization step (but there is still information loss in subsampling, +as well as roundoff error). This setting is mainly of interest for +experimental purposes. Quality values above about 95 are NOT recommended for +normal use; the compressed file size goes up dramatically for hardly any gain +in output image quality. + +In the other direction, quality values below 50 will produce very small files +of low image quality. Settings around 5 to 10 might be useful in preparing an +index of a large image library, for example. Try -quality 2 (or so) for some +amusing Cubist effects. (Note: quality values below about 25 generate 2-byte +quantization tables, which are considered optional in the JPEG standard. +cjpeg emits a warning message when you give such a quality value, because some +other JPEG programs may be unable to decode the resulting file. Use -baseline +if you need to ensure compatibility at low quality values.) + +The -progressive switch creates a "progressive JPEG" file. In this type of +JPEG file, the data is stored in multiple scans of increasing quality. If the +file is being transmitted over a slow communications link, the decoder can use +the first scan to display a low-quality image very quickly, and can then +improve the display with each subsequent scan. The final image is exactly +equivalent to a standard JPEG file of the same quality setting, and the total +file size is about the same --- often a little smaller. CAUTION: progressive +JPEG is not yet widely implemented, so many decoders will be unable to view a +progressive JPEG file at all. + +Switches for advanced users: + + -dct int Use integer DCT method (default). + -dct fast Use fast integer DCT (less accurate). + -dct float Use floating-point DCT method. + The float method is very slightly more accurate than + the int method, but is much slower unless your machine + has very fast floating-point hardware. Also note that + results of the floating-point method may vary slightly + across machines, while the integer methods should give + the same results everywhere. The fast integer method + is much less accurate than the other two. + + -restart N Emit a JPEG restart marker every N MCU rows, or every + N MCU blocks if "B" is attached to the number. + -restart 0 (the default) means no restart markers. + + -smooth N Smooth the input image to eliminate dithering noise. + N, ranging from 1 to 100, indicates the strength of + smoothing. 0 (the default) means no smoothing. + + -maxmemory N Set limit for amount of memory to use in processing + large images. Value is in thousands of bytes, or + millions of bytes if "M" is attached to the number. + For example, -max 4m selects 4000000 bytes. If more + space is needed, temporary files will be used. + + -verbose Enable debug printout. More -v's give more printout. + or -debug Also, version information is printed at startup. + +The -restart option inserts extra markers that allow a JPEG decoder to +resynchronize after a transmission error. Without restart markers, any damage +to a compressed file will usually ruin the image from the point of the error +to the end of the image; with restart markers, the damage is usually confined +to the portion of the image up to the next restart marker. Of course, the +restart markers occupy extra space. We recommend -restart 1 for images that +will be transmitted across unreliable networks such as Usenet. + +The -smooth option filters the input to eliminate fine-scale noise. This is +often useful when converting dithered images to JPEG: a moderate smoothing +factor of 10 to 50 gets rid of dithering patterns in the input file, resulting +in a smaller JPEG file and a better-looking image. Too large a smoothing +factor will visibly blur the image, however. + +Switches for wizards: + + -baseline Force baseline-compatible quantization tables to be + generated. This clamps quantization values to 8 bits + even at low quality settings. (This switch is poorly + named, since it does not ensure that the output is + actually baseline JPEG. For example, you can use + -baseline and -progressive together.) + + -qtables file Use the quantization tables given in the specified + text file. + + -qslots N[,...] Select which quantization table to use for each color + component. + + -sample HxV[,...] Set JPEG sampling factors for each color component. + + -scans file Use the scan script given in the specified text file. + +The "wizard" switches are intended for experimentation with JPEG. If you +don't know what you are doing, DON'T USE THEM. These switches are documented +further in the file wizard.doc. + + +DJPEG DETAILS + +The basic command line switches for djpeg are: + + -colors N Reduce image to at most N colors. This reduces the + or -quantize N number of colors used in the output image, so that it + can be displayed on a colormapped display or stored in + a colormapped file format. For example, if you have + an 8-bit display, you'd need to reduce to 256 or fewer + colors. (-colors is the recommended name, -quantize + is provided only for backwards compatibility.) + + -fast Select recommended processing options for fast, low + quality output. (The default options are chosen for + highest quality output.) Currently, this is equivalent + to "-dct fast -nosmooth -onepass -dither ordered". + + -grayscale Force gray-scale output even if JPEG file is color. + Useful for viewing on monochrome displays; also, + djpeg runs noticeably faster in this mode. + + -scale M/N Scale the output image by a factor M/N. Currently + the scale factor must be 1/1, 1/2, 1/4, or 1/8. + Scaling is handy if the image is larger than your + screen; also, djpeg runs much faster when scaling + down the output. + + -bmp Select BMP output format (Windows flavor). 8-bit + colormapped format is emitted if -colors or -grayscale + is specified, or if the JPEG file is gray-scale; + otherwise, 24-bit full-color format is emitted. + + -gif Select GIF output format. Since GIF does not support + more than 256 colors, -colors 256 is assumed (unless + you specify a smaller number of colors). If you + specify -fast, the default number of colors is 216. + + -os2 Select BMP output format (OS/2 1.x flavor). 8-bit + colormapped format is emitted if -colors or -grayscale + is specified, or if the JPEG file is gray-scale; + otherwise, 24-bit full-color format is emitted. + + -pnm Select PBMPLUS (PPM/PGM) output format (this is the + default format). PGM is emitted if the JPEG file is + gray-scale or if -grayscale is specified; otherwise + PPM is emitted. + + -rle Select RLE output format. (Requires URT library.) + + -targa Select Targa output format. Gray-scale format is + emitted if the JPEG file is gray-scale or if + -grayscale is specified; otherwise, colormapped format + is emitted if -colors is specified; otherwise, 24-bit + full-color format is emitted. + +Switches for advanced users: + + -dct int Use integer DCT method (default). + -dct fast Use fast integer DCT (less accurate). + -dct float Use floating-point DCT method. + The float method is very slightly more accurate than + the int method, but is much slower unless your machine + has very fast floating-point hardware. Also note that + results of the floating-point method may vary slightly + across machines, while the integer methods should give + the same results everywhere. The fast integer method + is much less accurate than the other two. + + -dither fs Use Floyd-Steinberg dithering in color quantization. + -dither ordered Use ordered dithering in color quantization. + -dither none Do not use dithering in color quantization. + By default, Floyd-Steinberg dithering is applied when + quantizing colors; this is slow but usually produces + the best results. Ordered dither is a compromise + between speed and quality; no dithering is fast but + usually looks awful. Note that these switches have + no effect unless color quantization is being done. + Ordered dither is only available in -onepass mode. + + -map FILE Quantize to the colors used in the specified image + file. This is useful for producing multiple files + with identical color maps, or for forcing a predefined + set of colors to be used. The FILE must be a GIF + or PPM file. This option overrides -colors and + -onepass. + + -nosmooth Use a faster, lower-quality upsampling routine. + + -onepass Use one-pass instead of two-pass color quantization. + The one-pass method is faster and needs less memory, + but it produces a lower-quality image. -onepass is + ignored unless you also say -colors N. Also, + the one-pass method is always used for gray-scale + output (the two-pass method is no improvement then). + + -maxmemory N Set limit for amount of memory to use in processing + large images. Value is in thousands of bytes, or + millions of bytes if "M" is attached to the number. + For example, -max 4m selects 4000000 bytes. If more + space is needed, temporary files will be used. + + -verbose Enable debug printout. More -v's give more printout. + or -debug Also, version information is printed at startup. + + +HINTS FOR CJPEG + +Color GIF files are not the ideal input for JPEG; JPEG is really intended for +compressing full-color (24-bit) images. In particular, don't try to convert +cartoons, line drawings, and other images that have only a few distinct +colors. GIF works great on these, JPEG does not. If you want to convert a +GIF to JPEG, you should experiment with cjpeg's -quality and -smooth options +to get a satisfactory conversion. -smooth 10 or so is often helpful. + +Avoid running an image through a series of JPEG compression/decompression +cycles. Image quality loss will accumulate; after ten or so cycles the image +may be noticeably worse than it was after one cycle. It's best to use a +lossless format while manipulating an image, then convert to JPEG format when +you are ready to file the image away. + +The -optimize option to cjpeg is worth using when you are making a "final" +version for posting or archiving. It's also a win when you are using low +quality settings to make very small JPEG files; the percentage improvement +is often a lot more than it is on larger files. (At present, -optimize +mode is always selected when generating progressive JPEG files.) + +GIF input files are no longer supported, to avoid the Unisys LZW patent. +Use a Unisys-licensed program if you need to read a GIF file. (Conversion +of GIF files to JPEG is usually a bad idea anyway.) + + +HINTS FOR DJPEG + +To get a quick preview of an image, use the -grayscale and/or -scale switches. +"-grayscale -scale 1/8" is the fastest case. + +Several options are available that trade off image quality to gain speed. +"-fast" turns on the recommended settings. + +"-dct fast" and/or "-nosmooth" gain speed at a small sacrifice in quality. +When producing a color-quantized image, "-onepass -dither ordered" is fast but +much lower quality than the default behavior. "-dither none" may give +acceptable results in two-pass mode, but is seldom tolerable in one-pass mode. + +If you are fortunate enough to have very fast floating point hardware, +"-dct float" may be even faster than "-dct fast". But on most machines +"-dct float" is slower than "-dct int"; in this case it is not worth using, +because its theoretical accuracy advantage is too small to be significant +in practice. + +Two-pass color quantization requires a good deal of memory; on MS-DOS machines +it may run out of memory even with -maxmemory 0. In that case you can still +decompress, with some loss of image quality, by specifying -onepass for +one-pass quantization. + +To avoid the Unisys LZW patent, djpeg produces uncompressed GIF files. These +are larger than they should be, but are readable by standard GIF decoders. + + +HINTS FOR BOTH PROGRAMS + +If more space is needed than will fit in the available main memory (as +determined by -maxmemory), temporary files will be used. (MS-DOS versions +will try to get extended or expanded memory first.) The temporary files are +often rather large: in typical cases they occupy three bytes per pixel, for +example 3*800*600 = 1.44Mb for an 800x600 image. If you don't have enough +free disk space, leave out -progressive and -optimize (for cjpeg) or specify +-onepass (for djpeg). + +On MS-DOS, the temporary files are created in the directory named by the TMP +or TEMP environment variable, or in the current directory if neither of those +exist. Amiga implementations put the temp files in the directory named by +JPEGTMP:, so be sure to assign JPEGTMP: to a disk partition with adequate free +space. + +The default memory usage limit (-maxmemory) is set when the software is +compiled. If you get an "insufficient memory" error, try specifying a smaller +-maxmemory value, even -maxmemory 0 to use the absolute minimum space. You +may want to recompile with a smaller default value if this happens often. + +On machines that have "environment" variables, you can define the environment +variable JPEGMEM to set the default memory limit. The value is specified as +described for the -maxmemory switch. JPEGMEM overrides the default value +specified when the program was compiled, and itself is overridden by an +explicit -maxmemory switch. + +On MS-DOS machines, -maxmemory is the amount of main (conventional) memory to +use. (Extended or expanded memory is also used if available.) Most +DOS-specific versions of this software do their own memory space estimation +and do not need you to specify -maxmemory. + + +JPEGTRAN + +jpegtran performs various useful transformations of JPEG files. +It can translate the coded representation from one variant of JPEG to another, +for example from baseline JPEG to progressive JPEG or vice versa. It can also +perform some rearrangements of the image data, for example turning an image +from landscape to portrait format by rotation. + +jpegtran works by rearranging the compressed data (DCT coefficients), without +ever fully decoding the image. Therefore, its transformations are lossless: +there is no image degradation at all, which would not be true if you used +djpeg followed by cjpeg to accomplish the same conversion. But by the same +token, jpegtran cannot perform lossy operations such as changing the image +quality. + +jpegtran uses a command line syntax similar to cjpeg or djpeg. +On Unix-like systems, you say: + jpegtran [switches] [inputfile] >outputfile +On most non-Unix systems, you say: + jpegtran [switches] inputfile outputfile +where both the input and output files are JPEG files. + +To specify the coded JPEG representation used in the output file, +jpegtran accepts a subset of the switches recognized by cjpeg: + -optimize Perform optimization of entropy encoding parameters. + -progressive Create progressive JPEG file. + -restart N Emit a JPEG restart marker every N MCU rows, or every + N MCU blocks if "B" is attached to the number. + -scans file Use the scan script given in the specified text file. +See the previous discussion of cjpeg for more details about these switches. +If you specify none of these switches, you get a plain baseline-JPEG output +file. The quality setting and so forth are determined by the input file. + +The image can be losslessly transformed by giving one of these switches: + -flip horizontal Mirror image horizontally (left-right). + -flip vertical Mirror image vertically (top-bottom). + -rotate 90 Rotate image 90 degrees clockwise. + -rotate 180 Rotate image 180 degrees. + -rotate 270 Rotate image 270 degrees clockwise (or 90 ccw). + -transpose Transpose image (across UL-to-LR axis). + -transverse Transverse transpose (across UR-to-LL axis). + +The transpose transformation has no restrictions regarding image dimensions. +The other transformations operate rather oddly if the image dimensions are not +a multiple of the iMCU size (usually 8 or 16 pixels), because they can only +transform complete blocks of DCT coefficient data in the desired way. + +jpegtran's default behavior when transforming an odd-size image is designed +to preserve exact reversibility and mathematical consistency of the +transformation set. As stated, transpose is able to flip the entire image +area. Horizontal mirroring leaves any partial iMCU column at the right edge +untouched, but is able to flip all rows of the image. Similarly, vertical +mirroring leaves any partial iMCU row at the bottom edge untouched, but is +able to flip all columns. The other transforms can be built up as sequences +of transpose and flip operations; for consistency, their actions on edge +pixels are defined to be the same as the end result of the corresponding +transpose-and-flip sequence. + +For practical use, you may prefer to discard any untransformable edge pixels +rather than having a strange-looking strip along the right and/or bottom edges +of a transformed image. To do this, add the -trim switch: + -trim Drop non-transformable edge blocks. +Obviously, a transformation with -trim is not reversible, so strictly speaking +jpegtran with this switch is not lossless. Also, the expected mathematical +equivalences between the transformations no longer hold. For example, +"-rot 270 -trim" trims only the bottom edge, but "-rot 90 -trim" followed by +"-rot 180 -trim" trims both edges. + +Another not-strictly-lossless transformation switch is: + -grayscale Force grayscale output. +This option discards the chrominance channels if the input image is YCbCr +(ie, a standard color JPEG), resulting in a grayscale JPEG file. The +luminance channel is preserved exactly, so this is a better method of reducing +to grayscale than decompression, conversion, and recompression. This switch +is particularly handy for fixing a monochrome picture that was mistakenly +encoded as a color JPEG. (In such a case, the space savings from getting rid +of the near-empty chroma channels won't be large; but the decoding time for +a grayscale JPEG is substantially less than that for a color JPEG.) + +jpegtran also recognizes these switches that control what to do with "extra" +markers, such as comment blocks: + -copy none Copy no extra markers from source file. This setting + suppresses all comments and other excess baggage + present in the source file. + -copy comments Copy only comment markers. This setting copies + comments from the source file, but discards + any other inessential data. + -copy all Copy all extra markers. This setting preserves + miscellaneous markers found in the source file, such + as JFIF thumbnails and Photoshop settings. In some + files these extra markers can be sizable. +The default behavior is -copy comments. (Note: in IJG releases v6 and v6a, +jpegtran always did the equivalent of -copy none.) + +Additional switches recognized by jpegtran are: + -outfile filename + -maxmemory N + -verbose + -debug +These work the same as in cjpeg or djpeg. + + +THE COMMENT UTILITIES + +The JPEG standard allows "comment" (COM) blocks to occur within a JPEG file. +Although the standard doesn't actually define what COM blocks are for, they +are widely used to hold user-supplied text strings. This lets you add +annotations, titles, index terms, etc to your JPEG files, and later retrieve +them as text. COM blocks do not interfere with the image stored in the JPEG +file. The maximum size of a COM block is 64K, but you can have as many of +them as you like in one JPEG file. + +We provide two utility programs to display COM block contents and add COM +blocks to a JPEG file. + +rdjpgcom searches a JPEG file and prints the contents of any COM blocks on +standard output. The command line syntax is + rdjpgcom [-verbose] [inputfilename] +The switch "-verbose" (or just "-v") causes rdjpgcom to also display the JPEG +image dimensions. If you omit the input file name from the command line, +the JPEG file is read from standard input. (This may not work on some +operating systems, if binary data can't be read from stdin.) + +wrjpgcom adds a COM block, containing text you provide, to a JPEG file. +Ordinarily, the COM block is added after any existing COM blocks, but you +can delete the old COM blocks if you wish. wrjpgcom produces a new JPEG +file; it does not modify the input file. DO NOT try to overwrite the input +file by directing wrjpgcom's output back into it; on most systems this will +just destroy your file. + +The command line syntax for wrjpgcom is similar to cjpeg's. On Unix-like +systems, it is + wrjpgcom [switches] [inputfilename] +The output file is written to standard output. The input file comes from +the named file, or from standard input if no input file is named. + +On most non-Unix systems, the syntax is + wrjpgcom [switches] inputfilename outputfilename +where both input and output file names must be given explicitly. + +wrjpgcom understands three switches: + -replace Delete any existing COM blocks from the file. + -comment "Comment text" Supply new COM text on command line. + -cfile name Read text for new COM block from named file. +(Switch names can be abbreviated.) If you have only one line of comment text +to add, you can provide it on the command line with -comment. The comment +text must be surrounded with quotes so that it is treated as a single +argument. Longer comments can be read from a text file. + +If you give neither -comment nor -cfile, then wrjpgcom will read the comment +text from standard input. (In this case an input image file name MUST be +supplied, so that the source JPEG file comes from somewhere else.) You can +enter multiple lines, up to 64KB worth. Type an end-of-file indicator +(usually control-D or control-Z) to terminate the comment text entry. + +wrjpgcom will not add a COM block if the provided comment string is empty. +Therefore -replace -comment "" can be used to delete all COM blocks from a +file. + +These utility programs do not depend on the IJG JPEG library. In +particular, the source code for rdjpgcom is intended as an illustration of +the minimum amount of code required to parse a JPEG file header correctly. diff --git a/wizard.doc b/wizard.doc new file mode 100644 index 00000000..54170b22 --- /dev/null +++ b/wizard.doc @@ -0,0 +1,211 @@ +Advanced usage instructions for the Independent JPEG Group's JPEG software +========================================================================== + +This file describes cjpeg's "switches for wizards". + +The "wizard" switches are intended for experimentation with JPEG by persons +who are reasonably knowledgeable about the JPEG standard. If you don't know +what you are doing, DON'T USE THESE SWITCHES. You'll likely produce files +with worse image quality and/or poorer compression than you'd get from the +default settings. Furthermore, these switches must be used with caution +when making files intended for general use, because not all JPEG decoders +will support unusual JPEG parameter settings. + + +Quantization Table Adjustment +----------------------------- + +Ordinarily, cjpeg starts with a default set of tables (the same ones given +as examples in the JPEG standard) and scales them up or down according to +the -quality setting. The details of the scaling algorithm can be found in +jcparam.c. At very low quality settings, some quantization table entries +can get scaled up to values exceeding 255. Although 2-byte quantization +values are supported by the IJG software, this feature is not in baseline +JPEG and is not supported by all implementations. If you need to ensure +wide compatibility of low-quality files, you can constrain the scaled +quantization values to no more than 255 by giving the -baseline switch. +Note that use of -baseline will result in poorer quality for the same file +size, since more bits than necessary are expended on higher AC coefficients. + +You can substitute a different set of quantization values by using the +-qtables switch: + + -qtables file Use the quantization tables given in the named file. + +The specified file should be a text file containing decimal quantization +values. The file should contain one to four tables, each of 64 elements. +The tables are implicitly numbered 0,1,etc. in order of appearance. Table +entries appear in normal array order (NOT in the zigzag order in which they +will be stored in the JPEG file). + +Quantization table files are free format, in that arbitrary whitespace can +appear between numbers. Also, comments can be included: a comment starts +with '#' and extends to the end of the line. Here is an example file that +duplicates the default quantization tables: + + # Quantization tables given in JPEG spec, section K.1 + + # This is table 0 (the luminance table): + 16 11 10 16 24 40 51 61 + 12 12 14 19 26 58 60 55 + 14 13 16 24 40 57 69 56 + 14 17 22 29 51 87 80 62 + 18 22 37 56 68 109 103 77 + 24 35 55 64 81 104 113 92 + 49 64 78 87 103 121 120 101 + 72 92 95 98 112 100 103 99 + + # This is table 1 (the chrominance table): + 17 18 24 47 99 99 99 99 + 18 21 26 66 99 99 99 99 + 24 26 56 99 99 99 99 99 + 47 66 99 99 99 99 99 99 + 99 99 99 99 99 99 99 99 + 99 99 99 99 99 99 99 99 + 99 99 99 99 99 99 99 99 + 99 99 99 99 99 99 99 99 + +If the -qtables switch is used without -quality, then the specified tables +are used exactly as-is. If both -qtables and -quality are used, then the +tables taken from the file are scaled in the same fashion that the default +tables would be scaled for that quality setting. If -baseline appears, then +the quantization values are constrained to the range 1-255. + +By default, cjpeg will use quantization table 0 for luminance components and +table 1 for chrominance components. To override this choice, use the -qslots +switch: + + -qslots N[,...] Select which quantization table to use for + each color component. + +The -qslots switch specifies a quantization table number for each color +component, in the order in which the components appear in the JPEG SOF marker. +For example, to create a separate table for each of Y,Cb,Cr, you could +provide a -qtables file that defines three quantization tables and say +"-qslots 0,1,2". If -qslots gives fewer table numbers than there are color +components, then the last table number is repeated as necessary. + + +Sampling Factor Adjustment +-------------------------- + +By default, cjpeg uses 2:1 horizontal and vertical downsampling when +compressing YCbCr data, and no downsampling for all other color spaces. +You can override this default with the -sample switch: + + -sample HxV[,...] Set JPEG sampling factors for each color + component. + +The -sample switch specifies the JPEG sampling factors for each color +component, in the order in which they appear in the JPEG SOF marker. +If you specify fewer HxV pairs than there are components, the remaining +components are set to 1x1 sampling. For example, the default YCbCr setting +is equivalent to "-sample 2x2,1x1,1x1", which can be abbreviated to +"-sample 2x2". + +There are still some JPEG decoders in existence that support only 2x1 +sampling (also called 4:2:2 sampling). Compatibility with such decoders can +be achieved by specifying "-sample 2x1". This is not recommended unless +really necessary, since it increases file size and encoding/decoding time +with very little quality gain. + + +Multiple Scan / Progression Control +----------------------------------- + +By default, cjpeg emits a single-scan sequential JPEG file. The +-progressive switch generates a progressive JPEG file using a default series +of progression parameters. You can create multiple-scan sequential JPEG +files or progressive JPEG files with custom progression parameters by using +the -scans switch: + + -scans file Use the scan sequence given in the named file. + +The specified file should be a text file containing a "scan script". +The script specifies the contents and ordering of the scans to be emitted. +Each entry in the script defines one scan. A scan definition specifies +the components to be included in the scan, and for progressive JPEG it also +specifies the progression parameters Ss,Se,Ah,Al for the scan. Scan +definitions are separated by semicolons (';'). A semicolon after the last +scan definition is optional. + +Each scan definition contains one to four component indexes, optionally +followed by a colon (':') and the four progressive-JPEG parameters. The +component indexes denote which color component(s) are to be transmitted in +the scan. Components are numbered in the order in which they appear in the +JPEG SOF marker, with the first component being numbered 0. (Note that these +indexes are not the "component ID" codes assigned to the components, just +positional indexes.) + +The progression parameters for each scan are: + Ss Zigzag index of first coefficient included in scan + Se Zigzag index of last coefficient included in scan + Ah Zero for first scan of a coefficient, else Al of prior scan + Al Successive approximation low bit position for scan +If the progression parameters are omitted, the values 0,63,0,0 are used, +producing a sequential JPEG file. cjpeg automatically determines whether +the script represents a progressive or sequential file, by observing whether +Ss and Se values other than 0 and 63 appear. (The -progressive switch is +not needed to specify this; in fact, it is ignored when -scans appears.) +The scan script must meet the JPEG restrictions on progression sequences. +(cjpeg checks that the spec's requirements are obeyed.) + +Scan script files are free format, in that arbitrary whitespace can appear +between numbers and around punctuation. Also, comments can be included: a +comment starts with '#' and extends to the end of the line. For additional +legibility, commas or dashes can be placed between values. (Actually, any +single punctuation character other than ':' or ';' can be inserted.) For +example, the following two scan definitions are equivalent: + 0 1 2: 0 63 0 0; + 0,1,2 : 0-63, 0,0 ; + +Here is an example of a scan script that generates a partially interleaved +sequential JPEG file: + + 0; # Y only in first scan + 1 2; # Cb and Cr in second scan + +Here is an example of a progressive scan script using only spectral selection +(no successive approximation): + + # Interleaved DC scan for Y,Cb,Cr: + 0,1,2: 0-0, 0, 0 ; + # AC scans: + 0: 1-2, 0, 0 ; # First two Y AC coefficients + 0: 3-5, 0, 0 ; # Three more + 1: 1-63, 0, 0 ; # All AC coefficients for Cb + 2: 1-63, 0, 0 ; # All AC coefficients for Cr + 0: 6-9, 0, 0 ; # More Y coefficients + 0: 10-63, 0, 0 ; # Remaining Y coefficients + +Here is an example of a successive-approximation script. This is equivalent +to the default script used by "cjpeg -progressive" for YCbCr images: + + # Initial DC scan for Y,Cb,Cr (lowest bit not sent) + 0,1,2: 0-0, 0, 1 ; + # First AC scan: send first 5 Y AC coefficients, minus 2 lowest bits: + 0: 1-5, 0, 2 ; + # Send all Cr,Cb AC coefficients, minus lowest bit: + # (chroma data is usually too small to be worth subdividing further; + # but note we send Cr first since eye is least sensitive to Cb) + 2: 1-63, 0, 1 ; + 1: 1-63, 0, 1 ; + # Send remaining Y AC coefficients, minus 2 lowest bits: + 0: 6-63, 0, 2 ; + # Send next-to-lowest bit of all Y AC coefficients: + 0: 1-63, 2, 1 ; + # At this point we've sent all but the lowest bit of all coefficients. + # Send lowest bit of DC coefficients + 0,1,2: 0-0, 1, 0 ; + # Send lowest bit of AC coefficients + 2: 1-63, 1, 0 ; + 1: 1-63, 1, 0 ; + # Y AC lowest bit scan is last; it's usually the largest scan + 0: 1-63, 1, 0 ; + +It may be worth pointing out that this script is tuned for quality settings +of around 50 to 75. For lower quality settings, you'd probably want to use +a script with fewer stages of successive approximation (otherwise the +initial scans will be really bad). For higher quality settings, you might +want to use more stages of successive approximation (so that the initial +scans are not too large). diff --git a/wrjpgcom.1 b/wrjpgcom.1 new file mode 100644 index 00000000..d419a999 --- /dev/null +++ b/wrjpgcom.1 @@ -0,0 +1,103 @@ +.TH WRJPGCOM 1 "15 June 1995" +.SH NAME +wrjpgcom \- insert text comments into a JPEG file +.SH SYNOPSIS +.B wrjpgcom +[ +.B \-replace +] +[ +.BI \-comment " text" +] +[ +.BI \-cfile " name" +] +[ +.I filename +] +.LP +.SH DESCRIPTION +.LP +.B wrjpgcom +reads the named JPEG/JFIF file, or the standard input if no file is named, +and generates a new JPEG/JFIF file on standard output. A comment block is +added to the file. +.PP +The JPEG standard allows "comment" (COM) blocks to occur within a JPEG file. +Although the standard doesn't actually define what COM blocks are for, they +are widely used to hold user-supplied text strings. This lets you add +annotations, titles, index terms, etc to your JPEG files, and later retrieve +them as text. COM blocks do not interfere with the image stored in the JPEG +file. The maximum size of a COM block is 64K, but you can have as many of +them as you like in one JPEG file. +.PP +.B wrjpgcom +adds a COM block, containing text you provide, to a JPEG file. +Ordinarily, the COM block is added after any existing COM blocks; but you +can delete the old COM blocks if you wish. +.SH OPTIONS +Switch names may be abbreviated, and are not case sensitive. +.TP +.B \-replace +Delete any existing COM blocks from the file. +.TP +.BI \-comment " text" +Supply text for new COM block on command line. +.TP +.BI \-cfile " name" +Read text for new COM block from named file. +.PP +If you have only one line of comment text to add, you can provide it on the +command line with +.BR \-comment . +The comment text must be surrounded with quotes so that it is treated as a +single argument. Longer comments can be read from a text file. +.PP +If you give neither +.B \-comment +nor +.BR \-cfile , +then +.B wrjpgcom +will read the comment text from standard input. (In this case an input image +file name MUST be supplied, so that the source JPEG file comes from somewhere +else.) You can enter multiple lines, up to 64KB worth. Type an end-of-file +indicator (usually control-D) to terminate the comment text entry. +.PP +.B wrjpgcom +will not add a COM block if the provided comment string is empty. Therefore +\fB\-replace \-comment ""\fR can be used to delete all COM blocks from a file. +.SH EXAMPLES +.LP +Add a short comment to in.jpg, producing out.jpg: +.IP +.B wrjpgcom \-c +\fI"View of my back yard" in.jpg +.B > +.I out.jpg +.PP +Attach a long comment previously stored in comment.txt: +.IP +.B wrjpgcom +.I in.jpg +.B < +.I comment.txt +.B > +.I out.jpg +.PP +or equivalently +.IP +.B wrjpgcom +.B -cfile +.I comment.txt +.B < +.I in.jpg +.B > +.I out.jpg +.SH SEE ALSO +.BR cjpeg (1), +.BR djpeg (1), +.BR jpegtran (1), +.BR rdjpgcom (1) +.SH AUTHOR +Independent JPEG Group diff --git a/wrjpgcom.c b/wrjpgcom.c new file mode 100644 index 00000000..8c04b055 --- /dev/null +++ b/wrjpgcom.c @@ -0,0 +1,583 @@ +/* + * wrjpgcom.c + * + * Copyright (C) 1994-1997, Thomas G. Lane. + * This file is part of the Independent JPEG Group's software. + * For conditions of distribution and use, see the accompanying README file. + * + * This file contains a very simple stand-alone application that inserts + * user-supplied text as a COM (comment) marker in a JFIF file. + * This may be useful as an example of the minimum logic needed to parse + * JPEG markers. + */ + +#define JPEG_CJPEG_DJPEG /* to get the command-line config symbols */ +#include "jinclude.h" /* get auto-config symbols, */ + +#ifndef HAVE_STDLIB_H /* should declare malloc() */ +extern void * malloc (); +#endif +#include /* to declare isupper(), tolower() */ +#ifdef USE_SETMODE +#include /* to declare setmode()'s parameter macros */ +/* If you have setmode() but not , just delete this line: */ +#include /* to declare setmode() */ +#endif + +#ifdef USE_CCOMMAND /* command-line reader for Macintosh */ +#ifdef __MWERKS__ +#include /* Metrowerks needs this */ +#include /* ... and this */ +#endif +#ifdef THINK_C +#include /* Think declares it here */ +#endif +#endif + +#ifdef DONT_USE_B_MODE /* define mode parameters for fopen() */ +#define READ_BINARY "r" +#define WRITE_BINARY "w" +#else +#ifdef VMS /* VMS is very nonstandard */ +#define READ_BINARY "rb", "ctx=stm" +#define WRITE_BINARY "wb", "ctx=stm" +#else /* standard ANSI-compliant case */ +#define READ_BINARY "rb" +#define WRITE_BINARY "wb" +#endif +#endif + +#ifndef EXIT_FAILURE /* define exit() codes if not provided */ +#define EXIT_FAILURE 1 +#endif +#ifndef EXIT_SUCCESS +#ifdef VMS +#define EXIT_SUCCESS 1 /* VMS is very nonstandard */ +#else +#define EXIT_SUCCESS 0 +#endif +#endif + +/* Reduce this value if your malloc() can't allocate blocks up to 64K. + * On DOS, compiling in large model is usually a better solution. + */ + +#ifndef MAX_COM_LENGTH +#define MAX_COM_LENGTH 65000L /* must be <= 65533 in any case */ +#endif + + +/* + * These macros are used to read the input file and write the output file. + * To reuse this code in another application, you might need to change these. + */ + +static FILE * infile; /* input JPEG file */ + +/* Return next input byte, or EOF if no more */ +#define NEXTBYTE() getc(infile) + +static FILE * outfile; /* output JPEG file */ + +/* Emit an output byte */ +#define PUTBYTE(x) putc((x), outfile) + + +/* Error exit handler */ +#define ERREXIT(msg) (fprintf(stderr, "%s\n", msg), exit(EXIT_FAILURE)) + + +/* Read one byte, testing for EOF */ +static int +read_1_byte (void) +{ + int c; + + c = NEXTBYTE(); + if (c == EOF) + ERREXIT("Premature EOF in JPEG file"); + return c; +} + +/* Read 2 bytes, convert to unsigned int */ +/* All 2-byte quantities in JPEG markers are MSB first */ +static unsigned int +read_2_bytes (void) +{ + int c1, c2; + + c1 = NEXTBYTE(); + if (c1 == EOF) + ERREXIT("Premature EOF in JPEG file"); + c2 = NEXTBYTE(); + if (c2 == EOF) + ERREXIT("Premature EOF in JPEG file"); + return (((unsigned int) c1) << 8) + ((unsigned int) c2); +} + + +/* Routines to write data to output file */ + +static void +write_1_byte (int c) +{ + PUTBYTE(c); +} + +static void +write_2_bytes (unsigned int val) +{ + PUTBYTE((val >> 8) & 0xFF); + PUTBYTE(val & 0xFF); +} + +static void +write_marker (int marker) +{ + PUTBYTE(0xFF); + PUTBYTE(marker); +} + +static void +copy_rest_of_file (void) +{ + int c; + + while ((c = NEXTBYTE()) != EOF) + PUTBYTE(c); +} + + +/* + * JPEG markers consist of one or more 0xFF bytes, followed by a marker + * code byte (which is not an FF). Here are the marker codes of interest + * in this program. (See jdmarker.c for a more complete list.) + */ + +#define M_SOF0 0xC0 /* Start Of Frame N */ +#define M_SOF1 0xC1 /* N indicates which compression process */ +#define M_SOF2 0xC2 /* Only SOF0-SOF2 are now in common use */ +#define M_SOF3 0xC3 +#define M_SOF5 0xC5 /* NB: codes C4 and CC are NOT SOF markers */ +#define M_SOF6 0xC6 +#define M_SOF7 0xC7 +#define M_SOF9 0xC9 +#define M_SOF10 0xCA +#define M_SOF11 0xCB +#define M_SOF13 0xCD +#define M_SOF14 0xCE +#define M_SOF15 0xCF +#define M_SOI 0xD8 /* Start Of Image (beginning of datastream) */ +#define M_EOI 0xD9 /* End Of Image (end of datastream) */ +#define M_SOS 0xDA /* Start Of Scan (begins compressed data) */ +#define M_COM 0xFE /* COMment */ + + +/* + * Find the next JPEG marker and return its marker code. + * We expect at least one FF byte, possibly more if the compressor used FFs + * to pad the file. (Padding FFs will NOT be replicated in the output file.) + * There could also be non-FF garbage between markers. The treatment of such + * garbage is unspecified; we choose to skip over it but emit a warning msg. + * NB: this routine must not be used after seeing SOS marker, since it will + * not deal correctly with FF/00 sequences in the compressed image data... + */ + +static int +next_marker (void) +{ + int c; + int discarded_bytes = 0; + + /* Find 0xFF byte; count and skip any non-FFs. */ + c = read_1_byte(); + while (c != 0xFF) { + discarded_bytes++; + c = read_1_byte(); + } + /* Get marker code byte, swallowing any duplicate FF bytes. Extra FFs + * are legal as pad bytes, so don't count them in discarded_bytes. + */ + do { + c = read_1_byte(); + } while (c == 0xFF); + + if (discarded_bytes != 0) { + fprintf(stderr, "Warning: garbage data found in JPEG file\n"); + } + + return c; +} + + +/* + * Read the initial marker, which should be SOI. + * For a JFIF file, the first two bytes of the file should be literally + * 0xFF M_SOI. To be more general, we could use next_marker, but if the + * input file weren't actually JPEG at all, next_marker might read the whole + * file and then return a misleading error message... + */ + +static int +first_marker (void) +{ + int c1, c2; + + c1 = NEXTBYTE(); + c2 = NEXTBYTE(); + if (c1 != 0xFF || c2 != M_SOI) + ERREXIT("Not a JPEG file"); + return c2; +} + + +/* + * Most types of marker are followed by a variable-length parameter segment. + * This routine skips over the parameters for any marker we don't otherwise + * want to process. + * Note that we MUST skip the parameter segment explicitly in order not to + * be fooled by 0xFF bytes that might appear within the parameter segment; + * such bytes do NOT introduce new markers. + */ + +static void +copy_variable (void) +/* Copy an unknown or uninteresting variable-length marker */ +{ + unsigned int length; + + /* Get the marker parameter length count */ + length = read_2_bytes(); + write_2_bytes(length); + /* Length includes itself, so must be at least 2 */ + if (length < 2) + ERREXIT("Erroneous JPEG marker length"); + length -= 2; + /* Skip over the remaining bytes */ + while (length > 0) { + write_1_byte(read_1_byte()); + length--; + } +} + +static void +skip_variable (void) +/* Skip over an unknown or uninteresting variable-length marker */ +{ + unsigned int length; + + /* Get the marker parameter length count */ + length = read_2_bytes(); + /* Length includes itself, so must be at least 2 */ + if (length < 2) + ERREXIT("Erroneous JPEG marker length"); + length -= 2; + /* Skip over the remaining bytes */ + while (length > 0) { + (void) read_1_byte(); + length--; + } +} + + +/* + * Parse the marker stream until SOFn or EOI is seen; + * copy data to output, but discard COM markers unless keep_COM is true. + */ + +static int +scan_JPEG_header (int keep_COM) +{ + int marker; + + /* Expect SOI at start of file */ + if (first_marker() != M_SOI) + ERREXIT("Expected SOI marker first"); + write_marker(M_SOI); + + /* Scan miscellaneous markers until we reach SOFn. */ + for (;;) { + marker = next_marker(); + switch (marker) { + /* Note that marker codes 0xC4, 0xC8, 0xCC are not, and must not be, + * treated as SOFn. C4 in particular is actually DHT. + */ + case M_SOF0: /* Baseline */ + case M_SOF1: /* Extended sequential, Huffman */ + case M_SOF2: /* Progressive, Huffman */ + case M_SOF3: /* Lossless, Huffman */ + case M_SOF5: /* Differential sequential, Huffman */ + case M_SOF6: /* Differential progressive, Huffman */ + case M_SOF7: /* Differential lossless, Huffman */ + case M_SOF9: /* Extended sequential, arithmetic */ + case M_SOF10: /* Progressive, arithmetic */ + case M_SOF11: /* Lossless, arithmetic */ + case M_SOF13: /* Differential sequential, arithmetic */ + case M_SOF14: /* Differential progressive, arithmetic */ + case M_SOF15: /* Differential lossless, arithmetic */ + return marker; + + case M_SOS: /* should not see compressed data before SOF */ + ERREXIT("SOS without prior SOFn"); + break; + + case M_EOI: /* in case it's a tables-only JPEG stream */ + return marker; + + case M_COM: /* Existing COM: conditionally discard */ + if (keep_COM) { + write_marker(marker); + copy_variable(); + } else { + skip_variable(); + } + break; + + default: /* Anything else just gets copied */ + write_marker(marker); + copy_variable(); /* we assume it has a parameter count... */ + break; + } + } /* end loop */ +} + + +/* Command line parsing code */ + +static const char * progname; /* program name for error messages */ + + +static void +usage (void) +/* complain about bad command line */ +{ + fprintf(stderr, "wrjpgcom inserts a textual comment in a JPEG file.\n"); + fprintf(stderr, "You can add to or replace any existing comment(s).\n"); + + fprintf(stderr, "Usage: %s [switches] ", progname); +#ifdef TWO_FILE_COMMANDLINE + fprintf(stderr, "inputfile outputfile\n"); +#else + fprintf(stderr, "[inputfile]\n"); +#endif + + fprintf(stderr, "Switches (names may be abbreviated):\n"); + fprintf(stderr, " -replace Delete any existing comments\n"); + fprintf(stderr, " -comment \"text\" Insert comment with given text\n"); + fprintf(stderr, " -cfile name Read comment from named file\n"); + fprintf(stderr, "Notice that you must put quotes around the comment text\n"); + fprintf(stderr, "when you use -comment.\n"); + fprintf(stderr, "If you do not give either -comment or -cfile on the command line,\n"); + fprintf(stderr, "then the comment text is read from standard input.\n"); + fprintf(stderr, "It can be multiple lines, up to %u characters total.\n", + (unsigned int) MAX_COM_LENGTH); +#ifndef TWO_FILE_COMMANDLINE + fprintf(stderr, "You must specify an input JPEG file name when supplying\n"); + fprintf(stderr, "comment text from standard input.\n"); +#endif + + exit(EXIT_FAILURE); +} + + +static int +keymatch (char * arg, const char * keyword, int minchars) +/* Case-insensitive matching of (possibly abbreviated) keyword switches. */ +/* keyword is the constant keyword (must be lower case already), */ +/* minchars is length of minimum legal abbreviation. */ +{ + register int ca, ck; + register int nmatched = 0; + + while ((ca = *arg++) != '\0') { + if ((ck = *keyword++) == '\0') + return 0; /* arg longer than keyword, no good */ + if (isupper(ca)) /* force arg to lcase (assume ck is already) */ + ca = tolower(ca); + if (ca != ck) + return 0; /* no good */ + nmatched++; /* count matched characters */ + } + /* reached end of argument; fail if it's too short for unique abbrev */ + if (nmatched < minchars) + return 0; + return 1; /* A-OK */ +} + + +/* + * The main program. + */ + +int +main (int argc, char **argv) +{ + int argn; + char * arg; + int keep_COM = 1; + char * comment_arg = NULL; + FILE * comment_file = NULL; + unsigned int comment_length = 0; + int marker; + + /* On Mac, fetch a command line. */ +#ifdef USE_CCOMMAND + argc = ccommand(&argv); +#endif + + progname = argv[0]; + if (progname == NULL || progname[0] == 0) + progname = "wrjpgcom"; /* in case C library doesn't provide it */ + + /* Parse switches, if any */ + for (argn = 1; argn < argc; argn++) { + arg = argv[argn]; + if (arg[0] != '-') + break; /* not switch, must be file name */ + arg++; /* advance over '-' */ + if (keymatch(arg, "replace", 1)) { + keep_COM = 0; + } else if (keymatch(arg, "cfile", 2)) { + if (++argn >= argc) usage(); + if ((comment_file = fopen(argv[argn], "r")) == NULL) { + fprintf(stderr, "%s: can't open %s\n", progname, argv[argn]); + exit(EXIT_FAILURE); + } + } else if (keymatch(arg, "comment", 1)) { + if (++argn >= argc) usage(); + comment_arg = argv[argn]; + /* If the comment text starts with '"', then we are probably running + * under MS-DOG and must parse out the quoted string ourselves. Sigh. + */ + if (comment_arg[0] == '"') { + comment_arg = (char *) malloc((size_t) MAX_COM_LENGTH); + if (comment_arg == NULL) + ERREXIT("Insufficient memory"); + strcpy(comment_arg, argv[argn]+1); + for (;;) { + comment_length = (unsigned int) strlen(comment_arg); + if (comment_length > 0 && comment_arg[comment_length-1] == '"') { + comment_arg[comment_length-1] = '\0'; /* zap terminating quote */ + break; + } + if (++argn >= argc) + ERREXIT("Missing ending quote mark"); + strcat(comment_arg, " "); + strcat(comment_arg, argv[argn]); + } + } + comment_length = (unsigned int) strlen(comment_arg); + } else + usage(); + } + + /* Cannot use both -comment and -cfile. */ + if (comment_arg != NULL && comment_file != NULL) + usage(); + /* If there is neither -comment nor -cfile, we will read the comment text + * from stdin; in this case there MUST be an input JPEG file name. + */ + if (comment_arg == NULL && comment_file == NULL && argn >= argc) + usage(); + + /* Open the input file. */ + if (argn < argc) { + if ((infile = fopen(argv[argn], READ_BINARY)) == NULL) { + fprintf(stderr, "%s: can't open %s\n", progname, argv[argn]); + exit(EXIT_FAILURE); + } + } else { + /* default input file is stdin */ +#ifdef USE_SETMODE /* need to hack file mode? */ + setmode(fileno(stdin), O_BINARY); +#endif +#ifdef USE_FDOPEN /* need to re-open in binary mode? */ + if ((infile = fdopen(fileno(stdin), READ_BINARY)) == NULL) { + fprintf(stderr, "%s: can't open stdin\n", progname); + exit(EXIT_FAILURE); + } +#else + infile = stdin; +#endif + } + + /* Open the output file. */ +#ifdef TWO_FILE_COMMANDLINE + /* Must have explicit output file name */ + if (argn != argc-2) { + fprintf(stderr, "%s: must name one input and one output file\n", + progname); + usage(); + } + if ((outfile = fopen(argv[argn+1], WRITE_BINARY)) == NULL) { + fprintf(stderr, "%s: can't open %s\n", progname, argv[argn+1]); + exit(EXIT_FAILURE); + } +#else + /* Unix style: expect zero or one file name */ + if (argn < argc-1) { + fprintf(stderr, "%s: only one input file\n", progname); + usage(); + } + /* default output file is stdout */ +#ifdef USE_SETMODE /* need to hack file mode? */ + setmode(fileno(stdout), O_BINARY); +#endif +#ifdef USE_FDOPEN /* need to re-open in binary mode? */ + if ((outfile = fdopen(fileno(stdout), WRITE_BINARY)) == NULL) { + fprintf(stderr, "%s: can't open stdout\n", progname); + exit(EXIT_FAILURE); + } +#else + outfile = stdout; +#endif +#endif /* TWO_FILE_COMMANDLINE */ + + /* Collect comment text from comment_file or stdin, if necessary */ + if (comment_arg == NULL) { + FILE * src_file; + int c; + + comment_arg = (char *) malloc((size_t) MAX_COM_LENGTH); + if (comment_arg == NULL) + ERREXIT("Insufficient memory"); + comment_length = 0; + src_file = (comment_file != NULL ? comment_file : stdin); + while ((c = getc(src_file)) != EOF) { + if (comment_length >= (unsigned int) MAX_COM_LENGTH) { + fprintf(stderr, "Comment text may not exceed %u bytes\n", + (unsigned int) MAX_COM_LENGTH); + exit(EXIT_FAILURE); + } + comment_arg[comment_length++] = (char) c; + } + if (comment_file != NULL) + fclose(comment_file); + } + + /* Copy JPEG headers until SOFn marker; + * we will insert the new comment marker just before SOFn. + * This (a) causes the new comment to appear after, rather than before, + * existing comments; and (b) ensures that comments come after any JFIF + * or JFXX markers, as required by the JFIF specification. + */ + marker = scan_JPEG_header(keep_COM); + /* Insert the new COM marker, but only if nonempty text has been supplied */ + if (comment_length > 0) { + write_marker(M_COM); + write_2_bytes(comment_length + 2); + while (comment_length > 0) { + write_1_byte(*comment_arg++); + comment_length--; + } + } + /* Duplicate the remainder of the source file. + * Note that any COM markers occuring after SOF will not be touched. + */ + write_marker(marker); + copy_rest_of_file(); + + /* All done. */ + exit(EXIT_SUCCESS); + return 0; /* suppress no-return-value warnings */ +} diff --git a/wrrle.c b/wrrle.c new file mode 100644 index 00000000..a4e73372 --- /dev/null +++ b/wrrle.c @@ -0,0 +1,305 @@ +/* + * wrrle.c + * + * Copyright (C) 1991-1996, Thomas G. Lane. + * This file is part of the Independent JPEG Group's software. + * For conditions of distribution and use, see the accompanying README file. + * + * This file contains routines to write output images in RLE format. + * The Utah Raster Toolkit library is required (version 3.1 or later). + * + * These routines may need modification for non-Unix environments or + * specialized applications. As they stand, they assume output to + * an ordinary stdio stream. + * + * Based on code contributed by Mike Lijewski, + * with updates from Robert Hutchinson. + */ + +#include "cdjpeg.h" /* Common decls for cjpeg/djpeg applications */ + +#ifdef RLE_SUPPORTED + +/* rle.h is provided by the Utah Raster Toolkit. */ + +#include + +/* + * We assume that JSAMPLE has the same representation as rle_pixel, + * to wit, "unsigned char". Hence we can't cope with 12- or 16-bit samples. + */ + +#if BITS_IN_JSAMPLE != 8 + Sorry, this code only copes with 8-bit JSAMPLEs. /* deliberate syntax err */ +#endif + + +/* + * Since RLE stores scanlines bottom-to-top, we have to invert the image + * from JPEG's top-to-bottom order. To do this, we save the outgoing data + * in a virtual array during put_pixel_row calls, then actually emit the + * RLE file during finish_output. + */ + + +/* + * For now, if we emit an RLE color map then it is always 256 entries long, + * though not all of the entries need be used. + */ + +#define CMAPBITS 8 +#define CMAPLENGTH (1<<(CMAPBITS)) + +typedef struct { + struct djpeg_dest_struct pub; /* public fields */ + + jvirt_sarray_ptr image; /* virtual array to store the output image */ + rle_map *colormap; /* RLE-style color map, or NULL if none */ + rle_pixel **rle_row; /* To pass rows to rle_putrow() */ + +} rle_dest_struct; + +typedef rle_dest_struct * rle_dest_ptr; + +/* Forward declarations */ +METHODDEF(void) rle_put_pixel_rows + JPP((j_decompress_ptr cinfo, djpeg_dest_ptr dinfo, + JDIMENSION rows_supplied)); + + +/* + * Write the file header. + * + * In this module it's easier to wait till finish_output to write anything. + */ + +METHODDEF(void) +start_output_rle (j_decompress_ptr cinfo, djpeg_dest_ptr dinfo) +{ + rle_dest_ptr dest = (rle_dest_ptr) dinfo; + size_t cmapsize; + int i, ci; +#ifdef PROGRESS_REPORT + cd_progress_ptr progress = (cd_progress_ptr) cinfo->progress; +#endif + + /* + * Make sure the image can be stored in RLE format. + * + * - RLE stores image dimensions as *signed* 16 bit integers. JPEG + * uses unsigned, so we have to check the width. + * + * - Colorspace is expected to be grayscale or RGB. + * + * - The number of channels (components) is expected to be 1 (grayscale/ + * pseudocolor) or 3 (truecolor/directcolor). + * (could be 2 or 4 if using an alpha channel, but we aren't) + */ + + if (cinfo->output_width > 32767 || cinfo->output_height > 32767) + ERREXIT2(cinfo, JERR_RLE_DIMENSIONS, cinfo->output_width, + cinfo->output_height); + + if (cinfo->out_color_space != JCS_GRAYSCALE && + cinfo->out_color_space != JCS_RGB) + ERREXIT(cinfo, JERR_RLE_COLORSPACE); + + if (cinfo->output_components != 1 && cinfo->output_components != 3) + ERREXIT1(cinfo, JERR_RLE_TOOMANYCHANNELS, cinfo->num_components); + + /* Convert colormap, if any, to RLE format. */ + + dest->colormap = NULL; + + if (cinfo->quantize_colors) { + /* Allocate storage for RLE-style cmap, zero any extra entries */ + cmapsize = cinfo->out_color_components * CMAPLENGTH * SIZEOF(rle_map); + dest->colormap = (rle_map *) (*cinfo->mem->alloc_small) + ((j_common_ptr) cinfo, JPOOL_IMAGE, cmapsize); + MEMZERO(dest->colormap, cmapsize); + + /* Save away data in RLE format --- note 8-bit left shift! */ + /* Shifting would need adjustment for JSAMPLEs wider than 8 bits. */ + for (ci = 0; ci < cinfo->out_color_components; ci++) { + for (i = 0; i < cinfo->actual_number_of_colors; i++) { + dest->colormap[ci * CMAPLENGTH + i] = + GETJSAMPLE(cinfo->colormap[ci][i]) << 8; + } + } + } + + /* Set the output buffer to the first row */ + dest->pub.buffer = (*cinfo->mem->access_virt_sarray) + ((j_common_ptr) cinfo, dest->image, (JDIMENSION) 0, (JDIMENSION) 1, TRUE); + dest->pub.buffer_height = 1; + + dest->pub.put_pixel_rows = rle_put_pixel_rows; + +#ifdef PROGRESS_REPORT + if (progress != NULL) { + progress->total_extra_passes++; /* count file writing as separate pass */ + } +#endif +} + + +/* + * Write some pixel data. + * + * This routine just saves the data away in a virtual array. + */ + +METHODDEF(void) +rle_put_pixel_rows (j_decompress_ptr cinfo, djpeg_dest_ptr dinfo, + JDIMENSION rows_supplied) +{ + rle_dest_ptr dest = (rle_dest_ptr) dinfo; + + if (cinfo->output_scanline < cinfo->output_height) { + dest->pub.buffer = (*cinfo->mem->access_virt_sarray) + ((j_common_ptr) cinfo, dest->image, + cinfo->output_scanline, (JDIMENSION) 1, TRUE); + } +} + +/* + * Finish up at the end of the file. + * + * Here is where we really output the RLE file. + */ + +METHODDEF(void) +finish_output_rle (j_decompress_ptr cinfo, djpeg_dest_ptr dinfo) +{ + rle_dest_ptr dest = (rle_dest_ptr) dinfo; + rle_hdr header; /* Output file information */ + rle_pixel **rle_row, *red, *green, *blue; + JSAMPROW output_row; + char cmapcomment[80]; + int row, col; + int ci; +#ifdef PROGRESS_REPORT + cd_progress_ptr progress = (cd_progress_ptr) cinfo->progress; +#endif + + /* Initialize the header info */ + header = *rle_hdr_init(NULL); + header.rle_file = dest->pub.output_file; + header.xmin = 0; + header.xmax = cinfo->output_width - 1; + header.ymin = 0; + header.ymax = cinfo->output_height - 1; + header.alpha = 0; + header.ncolors = cinfo->output_components; + for (ci = 0; ci < cinfo->output_components; ci++) { + RLE_SET_BIT(header, ci); + } + if (cinfo->quantize_colors) { + header.ncmap = cinfo->out_color_components; + header.cmaplen = CMAPBITS; + header.cmap = dest->colormap; + /* Add a comment to the output image with the true colormap length. */ + sprintf(cmapcomment, "color_map_length=%d", cinfo->actual_number_of_colors); + rle_putcom(cmapcomment, &header); + } + + /* Emit the RLE header and color map (if any) */ + rle_put_setup(&header); + + /* Now output the RLE data from our virtual array. + * We assume here that (a) rle_pixel is represented the same as JSAMPLE, + * and (b) we are not on a machine where FAR pointers differ from regular. + */ + +#ifdef PROGRESS_REPORT + if (progress != NULL) { + progress->pub.pass_limit = cinfo->output_height; + progress->pub.pass_counter = 0; + (*progress->pub.progress_monitor) ((j_common_ptr) cinfo); + } +#endif + + if (cinfo->output_components == 1) { + for (row = cinfo->output_height-1; row >= 0; row--) { + rle_row = (rle_pixel **) (*cinfo->mem->access_virt_sarray) + ((j_common_ptr) cinfo, dest->image, + (JDIMENSION) row, (JDIMENSION) 1, FALSE); + rle_putrow(rle_row, (int) cinfo->output_width, &header); +#ifdef PROGRESS_REPORT + if (progress != NULL) { + progress->pub.pass_counter++; + (*progress->pub.progress_monitor) ((j_common_ptr) cinfo); + } +#endif + } + } else { + for (row = cinfo->output_height-1; row >= 0; row--) { + rle_row = (rle_pixel **) dest->rle_row; + output_row = * (*cinfo->mem->access_virt_sarray) + ((j_common_ptr) cinfo, dest->image, + (JDIMENSION) row, (JDIMENSION) 1, FALSE); + red = rle_row[0]; + green = rle_row[1]; + blue = rle_row[2]; + for (col = cinfo->output_width; col > 0; col--) { + *red++ = GETJSAMPLE(*output_row++); + *green++ = GETJSAMPLE(*output_row++); + *blue++ = GETJSAMPLE(*output_row++); + } + rle_putrow(rle_row, (int) cinfo->output_width, &header); +#ifdef PROGRESS_REPORT + if (progress != NULL) { + progress->pub.pass_counter++; + (*progress->pub.progress_monitor) ((j_common_ptr) cinfo); + } +#endif + } + } + +#ifdef PROGRESS_REPORT + if (progress != NULL) + progress->completed_extra_passes++; +#endif + + /* Emit file trailer */ + rle_puteof(&header); + fflush(dest->pub.output_file); + if (ferror(dest->pub.output_file)) + ERREXIT(cinfo, JERR_FILE_WRITE); +} + + +/* + * The module selection routine for RLE format output. + */ + +GLOBAL(djpeg_dest_ptr) +jinit_write_rle (j_decompress_ptr cinfo) +{ + rle_dest_ptr dest; + + /* Create module interface object, fill in method pointers */ + dest = (rle_dest_ptr) + (*cinfo->mem->alloc_small) ((j_common_ptr) cinfo, JPOOL_IMAGE, + SIZEOF(rle_dest_struct)); + dest->pub.start_output = start_output_rle; + dest->pub.finish_output = finish_output_rle; + + /* Calculate output image dimensions so we can allocate space */ + jpeg_calc_output_dimensions(cinfo); + + /* Allocate a work array for output to the RLE library. */ + dest->rle_row = (*cinfo->mem->alloc_sarray) + ((j_common_ptr) cinfo, JPOOL_IMAGE, + cinfo->output_width, (JDIMENSION) cinfo->output_components); + + /* Allocate a virtual array to hold the image. */ + dest->image = (*cinfo->mem->request_virt_sarray) + ((j_common_ptr) cinfo, JPOOL_IMAGE, FALSE, + (JDIMENSION) (cinfo->output_width * cinfo->output_components), + cinfo->output_height, (JDIMENSION) 1); + + return (djpeg_dest_ptr) dest; +} + +#endif /* RLE_SUPPORTED */