uzairkhan - Final 350 project

Users » shoaib_ahmed » Code » uzairkhan

Shoaib Ahmed / Mbed 2 deprecated uzairkhan

Final 350 project

Dependencies: uzair Camera_LS_Y201 F7_Ethernet LCD_DISCO_F746NG NetworkAPI SDFileSystem mbed

includes/libjpeg.txt@0:791a779d6220, 2017-07-31 (annotated)

Committer:: shoaib_ahmed
Date:: Mon Jul 31 09:16:35 2017 +0000
Revision:: 0:791a779d6220

final project;

Who changed what in which revision?

User	Revision	Line number	New contents of line
shoaib_ahmed	0:791a779d6220	1	USING THE IJG JPEG LIBRARY
shoaib_ahmed	0:791a779d6220	2
shoaib_ahmed	0:791a779d6220	3	Copyright (C) 1994-2013, Thomas G. Lane, Guido Vollbeding.
shoaib_ahmed	0:791a779d6220	4	This file is part of the Independent JPEG Group's software.
shoaib_ahmed	0:791a779d6220	5	For conditions of distribution and use, see the accompanying README file.
shoaib_ahmed	0:791a779d6220	6
shoaib_ahmed	0:791a779d6220	7
shoaib_ahmed	0:791a779d6220	8	This file describes how to use the IJG JPEG library within an application
shoaib_ahmed	0:791a779d6220	9	program. Read it if you want to write a program that uses the library.
shoaib_ahmed	0:791a779d6220	10
shoaib_ahmed	0:791a779d6220	11	The file example.c provides heavily commented skeleton code for calling the
shoaib_ahmed	0:791a779d6220	12	JPEG library. Also see jpeglib.h (the include file to be used by application
shoaib_ahmed	0:791a779d6220	13	programs) for full details about data structures and function parameter lists.
shoaib_ahmed	0:791a779d6220	14	The library source code, of course, is the ultimate reference.
shoaib_ahmed	0:791a779d6220	15
shoaib_ahmed	0:791a779d6220	16	Note that there have been major changes from the application interface
shoaib_ahmed	0:791a779d6220	17	presented by IJG version 4 and earlier versions. The old design had several
shoaib_ahmed	0:791a779d6220	18	inherent limitations, and it had accumulated a lot of cruft as we added
shoaib_ahmed	0:791a779d6220	19	features while trying to minimize application-interface changes. We have
shoaib_ahmed	0:791a779d6220	20	sacrificed backward compatibility in the version 5 rewrite, but we think the
shoaib_ahmed	0:791a779d6220	21	improvements justify this.
shoaib_ahmed	0:791a779d6220	22
shoaib_ahmed	0:791a779d6220	23
shoaib_ahmed	0:791a779d6220	24	TABLE OF CONTENTS
shoaib_ahmed	0:791a779d6220	25	-----------------
shoaib_ahmed	0:791a779d6220	26
shoaib_ahmed	0:791a779d6220	27	Overview:
shoaib_ahmed	0:791a779d6220	28	Functions provided by the library
shoaib_ahmed	0:791a779d6220	29	Outline of typical usage
shoaib_ahmed	0:791a779d6220	30	Basic library usage:
shoaib_ahmed	0:791a779d6220	31	Data formats
shoaib_ahmed	0:791a779d6220	32	Compression details
shoaib_ahmed	0:791a779d6220	33	Decompression details
shoaib_ahmed	0:791a779d6220	34	Mechanics of usage: include files, linking, etc
shoaib_ahmed	0:791a779d6220	35	Advanced features:
shoaib_ahmed	0:791a779d6220	36	Compression parameter selection
shoaib_ahmed	0:791a779d6220	37	Decompression parameter selection
shoaib_ahmed	0:791a779d6220	38	Special color spaces
shoaib_ahmed	0:791a779d6220	39	Error handling
shoaib_ahmed	0:791a779d6220	40	Compressed data handling (source and destination managers)
shoaib_ahmed	0:791a779d6220	41	I/O suspension
shoaib_ahmed	0:791a779d6220	42	Progressive JPEG support
shoaib_ahmed	0:791a779d6220	43	Buffered-image mode
shoaib_ahmed	0:791a779d6220	44	Abbreviated datastreams and multiple images
shoaib_ahmed	0:791a779d6220	45	Special markers
shoaib_ahmed	0:791a779d6220	46	Raw (downsampled) image data
shoaib_ahmed	0:791a779d6220	47	Really raw data: DCT coefficients
shoaib_ahmed	0:791a779d6220	48	Progress monitoring
shoaib_ahmed	0:791a779d6220	49	Memory management
shoaib_ahmed	0:791a779d6220	50	Memory usage
shoaib_ahmed	0:791a779d6220	51	Library compile-time options
shoaib_ahmed	0:791a779d6220	52	Portability considerations
shoaib_ahmed	0:791a779d6220	53	Notes for MS-DOS implementors
shoaib_ahmed	0:791a779d6220	54
shoaib_ahmed	0:791a779d6220	55	You should read at least the overview and basic usage sections before trying
shoaib_ahmed	0:791a779d6220	56	to program with the library. The sections on advanced features can be read
shoaib_ahmed	0:791a779d6220	57	if and when you need them.
shoaib_ahmed	0:791a779d6220	58
shoaib_ahmed	0:791a779d6220	59
shoaib_ahmed	0:791a779d6220	60	OVERVIEW
shoaib_ahmed	0:791a779d6220	61	========
shoaib_ahmed	0:791a779d6220	62
shoaib_ahmed	0:791a779d6220	63	Functions provided by the library
shoaib_ahmed	0:791a779d6220	64	---------------------------------
shoaib_ahmed	0:791a779d6220	65
shoaib_ahmed	0:791a779d6220	66	The IJG JPEG library provides C code to read and write JPEG-compressed image
shoaib_ahmed	0:791a779d6220	67	files. The surrounding application program receives or supplies image data a
shoaib_ahmed	0:791a779d6220	68	scanline at a time, using a straightforward uncompressed image format. All
shoaib_ahmed	0:791a779d6220	69	details of color conversion and other preprocessing/postprocessing can be
shoaib_ahmed	0:791a779d6220	70	handled by the library.
shoaib_ahmed	0:791a779d6220	71
shoaib_ahmed	0:791a779d6220	72	The library includes a substantial amount of code that is not covered by the
shoaib_ahmed	0:791a779d6220	73	JPEG standard but is necessary for typical applications of JPEG. These
shoaib_ahmed	0:791a779d6220	74	functions preprocess the image before JPEG compression or postprocess it after
shoaib_ahmed	0:791a779d6220	75	decompression. They include colorspace conversion, downsampling/upsampling,
shoaib_ahmed	0:791a779d6220	76	and color quantization. The application indirectly selects use of this code
shoaib_ahmed	0:791a779d6220	77	by specifying the format in which it wishes to supply or receive image data.
shoaib_ahmed	0:791a779d6220	78	For example, if colormapped output is requested, then the decompression
shoaib_ahmed	0:791a779d6220	79	library automatically invokes color quantization.
shoaib_ahmed	0:791a779d6220	80
shoaib_ahmed	0:791a779d6220	81	A wide range of quality vs. speed tradeoffs are possible in JPEG processing,
shoaib_ahmed	0:791a779d6220	82	and even more so in decompression postprocessing. The decompression library
shoaib_ahmed	0:791a779d6220	83	provides multiple implementations that cover most of the useful tradeoffs,
shoaib_ahmed	0:791a779d6220	84	ranging from very-high-quality down to fast-preview operation. On the
shoaib_ahmed	0:791a779d6220	85	compression side we have generally not provided low-quality choices, since
shoaib_ahmed	0:791a779d6220	86	compression is normally less time-critical. It should be understood that the
shoaib_ahmed	0:791a779d6220	87	low-quality modes may not meet the JPEG standard's accuracy requirements;
shoaib_ahmed	0:791a779d6220	88	nonetheless, they are useful for viewers.
shoaib_ahmed	0:791a779d6220	89
shoaib_ahmed	0:791a779d6220	90	A word about functions not provided by the library. We handle a subset of
shoaib_ahmed	0:791a779d6220	91	the ISO JPEG standard; most baseline, extended-sequential, and progressive
shoaib_ahmed	0:791a779d6220	92	JPEG processes are supported. (Our subset includes all features now in common
shoaib_ahmed	0:791a779d6220	93	use.) Unsupported ISO options include:
shoaib_ahmed	0:791a779d6220	94	* Hierarchical storage
shoaib_ahmed	0:791a779d6220	95	* Lossless JPEG
shoaib_ahmed	0:791a779d6220	96	* DNL marker
shoaib_ahmed	0:791a779d6220	97	* Nonintegral subsampling ratios
shoaib_ahmed	0:791a779d6220	98	We support 8-bit to 12-bit data precision, but this is a compile-time choice
shoaib_ahmed	0:791a779d6220	99	rather than a run-time choice; hence it is difficult to use different
shoaib_ahmed	0:791a779d6220	100	precisions in a single application.
shoaib_ahmed	0:791a779d6220	101
shoaib_ahmed	0:791a779d6220	102	By itself, the library handles only interchange JPEG datastreams --- in
shoaib_ahmed	0:791a779d6220	103	particular the widely used JFIF file format. The library can be used by
shoaib_ahmed	0:791a779d6220	104	surrounding code to process interchange or abbreviated JPEG datastreams that
shoaib_ahmed	0:791a779d6220	105	are embedded in more complex file formats. (For example, this library is
shoaib_ahmed	0:791a779d6220	106	used by the free LIBTIFF library to support JPEG compression in TIFF.)
shoaib_ahmed	0:791a779d6220	107
shoaib_ahmed	0:791a779d6220	108
shoaib_ahmed	0:791a779d6220	109	Outline of typical usage
shoaib_ahmed	0:791a779d6220	110	------------------------
shoaib_ahmed	0:791a779d6220	111
shoaib_ahmed	0:791a779d6220	112	The rough outline of a JPEG compression operation is:
shoaib_ahmed	0:791a779d6220	113
shoaib_ahmed	0:791a779d6220	114	Allocate and initialize a JPEG compression object
shoaib_ahmed	0:791a779d6220	115	Specify the destination for the compressed data (eg, a file)
shoaib_ahmed	0:791a779d6220	116	Set parameters for compression, including image size & colorspace
shoaib_ahmed	0:791a779d6220	117	jpeg_start_compress(...);
shoaib_ahmed	0:791a779d6220	118	while (scan lines remain to be written)
shoaib_ahmed	0:791a779d6220	119	jpeg_write_scanlines(...);
shoaib_ahmed	0:791a779d6220	120	jpeg_finish_compress(...);
shoaib_ahmed	0:791a779d6220	121	Release the JPEG compression object
shoaib_ahmed	0:791a779d6220	122
shoaib_ahmed	0:791a779d6220	123	A JPEG compression object holds parameters and working state for the JPEG
shoaib_ahmed	0:791a779d6220	124	library. We make creation/destruction of the object separate from starting
shoaib_ahmed	0:791a779d6220	125	or finishing compression of an image; the same object can be re-used for a
shoaib_ahmed	0:791a779d6220	126	series of image compression operations. This makes it easy to re-use the
shoaib_ahmed	0:791a779d6220	127	same parameter settings for a sequence of images. Re-use of a JPEG object
shoaib_ahmed	0:791a779d6220	128	also has important implications for processing abbreviated JPEG datastreams,
shoaib_ahmed	0:791a779d6220	129	as discussed later.
shoaib_ahmed	0:791a779d6220	130
shoaib_ahmed	0:791a779d6220	131	The image data to be compressed is supplied to jpeg_write_scanlines() from
shoaib_ahmed	0:791a779d6220	132	in-memory buffers. If the application is doing file-to-file compression,
shoaib_ahmed	0:791a779d6220	133	reading image data from the source file is the application's responsibility.
shoaib_ahmed	0:791a779d6220	134	The library emits compressed data by calling a "data destination manager",
shoaib_ahmed	0:791a779d6220	135	which typically will write the data into a file; but the application can
shoaib_ahmed	0:791a779d6220	136	provide its own destination manager to do something else.
shoaib_ahmed	0:791a779d6220	137
shoaib_ahmed	0:791a779d6220	138	Similarly, the rough outline of a JPEG decompression operation is:
shoaib_ahmed	0:791a779d6220	139
shoaib_ahmed	0:791a779d6220	140	Allocate and initialize a JPEG decompression object
shoaib_ahmed	0:791a779d6220	141	Specify the source of the compressed data (eg, a file)
shoaib_ahmed	0:791a779d6220	142	Call jpeg_read_header() to obtain image info
shoaib_ahmed	0:791a779d6220	143	Set parameters for decompression
shoaib_ahmed	0:791a779d6220	144	jpeg_start_decompress(...);
shoaib_ahmed	0:791a779d6220	145	while (scan lines remain to be read)
shoaib_ahmed	0:791a779d6220	146	jpeg_read_scanlines(...);
shoaib_ahmed	0:791a779d6220	147	jpeg_finish_decompress(...);
shoaib_ahmed	0:791a779d6220	148	Release the JPEG decompression object
shoaib_ahmed	0:791a779d6220	149
shoaib_ahmed	0:791a779d6220	150	This is comparable to the compression outline except that reading the
shoaib_ahmed	0:791a779d6220	151	datastream header is a separate step. This is helpful because information
shoaib_ahmed	0:791a779d6220	152	about the image's size, colorspace, etc is available when the application
shoaib_ahmed	0:791a779d6220	153	selects decompression parameters. For example, the application can choose an
shoaib_ahmed	0:791a779d6220	154	output scaling ratio that will fit the image into the available screen size.
shoaib_ahmed	0:791a779d6220	155
shoaib_ahmed	0:791a779d6220	156	The decompression library obtains compressed data by calling a data source
shoaib_ahmed	0:791a779d6220	157	manager, which typically will read the data from a file; but other behaviors
shoaib_ahmed	0:791a779d6220	158	can be obtained with a custom source manager. Decompressed data is delivered
shoaib_ahmed	0:791a779d6220	159	into in-memory buffers passed to jpeg_read_scanlines().
shoaib_ahmed	0:791a779d6220	160
shoaib_ahmed	0:791a779d6220	161	It is possible to abort an incomplete compression or decompression operation
shoaib_ahmed	0:791a779d6220	162	by calling jpeg_abort(); or, if you do not need to retain the JPEG object,
shoaib_ahmed	0:791a779d6220	163	simply release it by calling jpeg_destroy().
shoaib_ahmed	0:791a779d6220	164
shoaib_ahmed	0:791a779d6220	165	JPEG compression and decompression objects are two separate struct types.
shoaib_ahmed	0:791a779d6220	166	However, they share some common fields, and certain routines such as
shoaib_ahmed	0:791a779d6220	167	jpeg_destroy() can work on either type of object.
shoaib_ahmed	0:791a779d6220	168
shoaib_ahmed	0:791a779d6220	169	The JPEG library has no static variables: all state is in the compression
shoaib_ahmed	0:791a779d6220	170	or decompression object. Therefore it is possible to process multiple
shoaib_ahmed	0:791a779d6220	171	compression and decompression operations concurrently, using multiple JPEG
shoaib_ahmed	0:791a779d6220	172	objects.
shoaib_ahmed	0:791a779d6220	173
shoaib_ahmed	0:791a779d6220	174	Both compression and decompression can be done in an incremental memory-to-
shoaib_ahmed	0:791a779d6220	175	memory fashion, if suitable source/destination managers are used. See the
shoaib_ahmed	0:791a779d6220	176	section on "I/O suspension" for more details.
shoaib_ahmed	0:791a779d6220	177
shoaib_ahmed	0:791a779d6220	178
shoaib_ahmed	0:791a779d6220	179	BASIC LIBRARY USAGE
shoaib_ahmed	0:791a779d6220	180	===================
shoaib_ahmed	0:791a779d6220	181
shoaib_ahmed	0:791a779d6220	182	Data formats
shoaib_ahmed	0:791a779d6220	183	------------
shoaib_ahmed	0:791a779d6220	184
shoaib_ahmed	0:791a779d6220	185	Before diving into procedural details, it is helpful to understand the
shoaib_ahmed	0:791a779d6220	186	image data format that the JPEG library expects or returns.
shoaib_ahmed	0:791a779d6220	187
shoaib_ahmed	0:791a779d6220	188	The standard input image format is a rectangular array of pixels, with each
shoaib_ahmed	0:791a779d6220	189	pixel having the same number of "component" or "sample" values (color
shoaib_ahmed	0:791a779d6220	190	channels). You must specify how many components there are and the colorspace
shoaib_ahmed	0:791a779d6220	191	interpretation of the components. Most applications will use RGB data
shoaib_ahmed	0:791a779d6220	192	(three components per pixel) or grayscale data (one component per pixel).
shoaib_ahmed	0:791a779d6220	193	PLEASE NOTE THAT RGB DATA IS THREE SAMPLES PER PIXEL, GRAYSCALE ONLY ONE.
shoaib_ahmed	0:791a779d6220	194	A remarkable number of people manage to miss this, only to find that their
shoaib_ahmed	0:791a779d6220	195	programs don't work with grayscale JPEG files.
shoaib_ahmed	0:791a779d6220	196
shoaib_ahmed	0:791a779d6220	197	There is no provision for colormapped input. JPEG files are always full-color
shoaib_ahmed	0:791a779d6220	198	or full grayscale (or sometimes another colorspace such as CMYK). You can
shoaib_ahmed	0:791a779d6220	199	feed in a colormapped image by expanding it to full-color format. However
shoaib_ahmed	0:791a779d6220	200	JPEG often doesn't work very well with source data that has been colormapped,
shoaib_ahmed	0:791a779d6220	201	because of dithering noise. This is discussed in more detail in the JPEG FAQ
shoaib_ahmed	0:791a779d6220	202	and the other references mentioned in the README file.
shoaib_ahmed	0:791a779d6220	203
shoaib_ahmed	0:791a779d6220	204	Pixels are stored by scanlines, with each scanline running from left to
shoaib_ahmed	0:791a779d6220	205	right. The component values for each pixel are adjacent in the row; for
shoaib_ahmed	0:791a779d6220	206	example, R,G,B,R,G,B,R,G,B,... for 24-bit RGB color. Each scanline is an
shoaib_ahmed	0:791a779d6220	207	array of data type JSAMPLE --- which is typically "unsigned char", unless
shoaib_ahmed	0:791a779d6220	208	you've changed jmorecfg.h. (You can also change the RGB pixel layout, say
shoaib_ahmed	0:791a779d6220	209	to B,G,R order, by modifying jmorecfg.h. But see the restrictions listed in
shoaib_ahmed	0:791a779d6220	210	that file before doing so.)
shoaib_ahmed	0:791a779d6220	211
shoaib_ahmed	0:791a779d6220	212	A 2-D array of pixels is formed by making a list of pointers to the starts of
shoaib_ahmed	0:791a779d6220	213	scanlines; so the scanlines need not be physically adjacent in memory. Even
shoaib_ahmed	0:791a779d6220	214	if you process just one scanline at a time, you must make a one-element
shoaib_ahmed	0:791a779d6220	215	pointer array to conform to this structure. Pointers to JSAMPLE rows are of
shoaib_ahmed	0:791a779d6220	216	type JSAMPROW, and the pointer to the pointer array is of type JSAMPARRAY.
shoaib_ahmed	0:791a779d6220	217
shoaib_ahmed	0:791a779d6220	218	The library accepts or supplies one or more complete scanlines per call.
shoaib_ahmed	0:791a779d6220	219	It is not possible to process part of a row at a time. Scanlines are always
shoaib_ahmed	0:791a779d6220	220	processed top-to-bottom. You can process an entire image in one call if you
shoaib_ahmed	0:791a779d6220	221	have it all in memory, but usually it's simplest to process one scanline at
shoaib_ahmed	0:791a779d6220	222	a time.
shoaib_ahmed	0:791a779d6220	223
shoaib_ahmed	0:791a779d6220	224	For best results, source data values should have the precision specified by
shoaib_ahmed	0:791a779d6220	225	BITS_IN_JSAMPLE (normally 8 bits). For instance, if you choose to compress
shoaib_ahmed	0:791a779d6220	226	data that's only 6 bits/channel, you should left-justify each value in a
shoaib_ahmed	0:791a779d6220	227	byte before passing it to the compressor. If you need to compress data
shoaib_ahmed	0:791a779d6220	228	that has more than 8 bits/channel, compile with BITS_IN_JSAMPLE = 9 to 12.
shoaib_ahmed	0:791a779d6220	229	(See "Library compile-time options", later.)
shoaib_ahmed	0:791a779d6220	230
shoaib_ahmed	0:791a779d6220	231
shoaib_ahmed	0:791a779d6220	232	The data format returned by the decompressor is the same in all details,
shoaib_ahmed	0:791a779d6220	233	except that colormapped output is supported. (Again, a JPEG file is never
shoaib_ahmed	0:791a779d6220	234	colormapped. But you can ask the decompressor to perform on-the-fly color
shoaib_ahmed	0:791a779d6220	235	quantization to deliver colormapped output.) If you request colormapped
shoaib_ahmed	0:791a779d6220	236	output then the returned data array contains a single JSAMPLE per pixel;
shoaib_ahmed	0:791a779d6220	237	its value is an index into a color map. The color map is represented as
shoaib_ahmed	0:791a779d6220	238	a 2-D JSAMPARRAY in which each row holds the values of one color component,
shoaib_ahmed	0:791a779d6220	239	that is, colormap[i][j] is the value of the i'th color component for pixel
shoaib_ahmed	0:791a779d6220	240	value (map index) j. Note that since the colormap indexes are stored in
shoaib_ahmed	0:791a779d6220	241	JSAMPLEs, the maximum number of colors is limited by the size of JSAMPLE
shoaib_ahmed	0:791a779d6220	242	(ie, at most 256 colors for an 8-bit JPEG library).
shoaib_ahmed	0:791a779d6220	243
shoaib_ahmed	0:791a779d6220	244
shoaib_ahmed	0:791a779d6220	245	Compression details
shoaib_ahmed	0:791a779d6220	246	-------------------
shoaib_ahmed	0:791a779d6220	247
shoaib_ahmed	0:791a779d6220	248	Here we revisit the JPEG compression outline given in the overview.
shoaib_ahmed	0:791a779d6220	249
shoaib_ahmed	0:791a779d6220	250	1. Allocate and initialize a JPEG compression object.
shoaib_ahmed	0:791a779d6220	251
shoaib_ahmed	0:791a779d6220	252	A JPEG compression object is a "struct jpeg_compress_struct". (It also has
shoaib_ahmed	0:791a779d6220	253	a bunch of subsidiary structures which are allocated via malloc(), but the
shoaib_ahmed	0:791a779d6220	254	application doesn't control those directly.) This struct can be just a local
shoaib_ahmed	0:791a779d6220	255	variable in the calling routine, if a single routine is going to execute the
shoaib_ahmed	0:791a779d6220	256	whole JPEG compression sequence. Otherwise it can be static or allocated
shoaib_ahmed	0:791a779d6220	257	from malloc().
shoaib_ahmed	0:791a779d6220	258
shoaib_ahmed	0:791a779d6220	259	You will also need a structure representing a JPEG error handler. The part
shoaib_ahmed	0:791a779d6220	260	of this that the library cares about is a "struct jpeg_error_mgr". If you
shoaib_ahmed	0:791a779d6220	261	are providing your own error handler, you'll typically want to embed the
shoaib_ahmed	0:791a779d6220	262	jpeg_error_mgr struct in a larger structure; this is discussed later under
shoaib_ahmed	0:791a779d6220	263	"Error handling". For now we'll assume you are just using the default error
shoaib_ahmed	0:791a779d6220	264	handler. The default error handler will print JPEG error/warning messages
shoaib_ahmed	0:791a779d6220	265	on stderr, and it will call exit() if a fatal error occurs.
shoaib_ahmed	0:791a779d6220	266
shoaib_ahmed	0:791a779d6220	267	You must initialize the error handler structure, store a pointer to it into
shoaib_ahmed	0:791a779d6220	268	the JPEG object's "err" field, and then call jpeg_create_compress() to
shoaib_ahmed	0:791a779d6220	269	initialize the rest of the JPEG object.
shoaib_ahmed	0:791a779d6220	270
shoaib_ahmed	0:791a779d6220	271	Typical code for this step, if you are using the default error handler, is
shoaib_ahmed	0:791a779d6220	272
shoaib_ahmed	0:791a779d6220	273	struct jpeg_compress_struct cinfo;
shoaib_ahmed	0:791a779d6220	274	struct jpeg_error_mgr jerr;
shoaib_ahmed	0:791a779d6220	275	...
shoaib_ahmed	0:791a779d6220	276	cinfo.err = jpeg_std_error(&jerr);
shoaib_ahmed	0:791a779d6220	277	jpeg_create_compress(&cinfo);
shoaib_ahmed	0:791a779d6220	278
shoaib_ahmed	0:791a779d6220	279	jpeg_create_compress allocates a small amount of memory, so it could fail
shoaib_ahmed	0:791a779d6220	280	if you are out of memory. In that case it will exit via the error handler;
shoaib_ahmed	0:791a779d6220	281	that's why the error handler must be initialized first.
shoaib_ahmed	0:791a779d6220	282
shoaib_ahmed	0:791a779d6220	283
shoaib_ahmed	0:791a779d6220	284	2. Specify the destination for the compressed data (eg, a file).
shoaib_ahmed	0:791a779d6220	285
shoaib_ahmed	0:791a779d6220	286	As previously mentioned, the JPEG library delivers compressed data to a
shoaib_ahmed	0:791a779d6220	287	"data destination" module. The library includes one data destination
shoaib_ahmed	0:791a779d6220	288	module which knows how to write to a stdio stream. You can use your own
shoaib_ahmed	0:791a779d6220	289	destination module if you want to do something else, as discussed later.
shoaib_ahmed	0:791a779d6220	290
shoaib_ahmed	0:791a779d6220	291	If you use the standard destination module, you must open the target stdio
shoaib_ahmed	0:791a779d6220	292	stream beforehand. Typical code for this step looks like:
shoaib_ahmed	0:791a779d6220	293
shoaib_ahmed	0:791a779d6220	294	FILE * outfile;
shoaib_ahmed	0:791a779d6220	295	...
shoaib_ahmed	0:791a779d6220	296	if ((outfile = fopen(filename, "wb")) == NULL) {
shoaib_ahmed	0:791a779d6220	297	fprintf(stderr, "can't open %s\n", filename);
shoaib_ahmed	0:791a779d6220	298	exit(1);
shoaib_ahmed	0:791a779d6220	299	}
shoaib_ahmed	0:791a779d6220	300	jpeg_stdio_dest(&cinfo, outfile);
shoaib_ahmed	0:791a779d6220	301
shoaib_ahmed	0:791a779d6220	302	where the last line invokes the standard destination module.
shoaib_ahmed	0:791a779d6220	303
shoaib_ahmed	0:791a779d6220	304	WARNING: it is critical that the binary compressed data be delivered to the
shoaib_ahmed	0:791a779d6220	305	output file unchanged. On non-Unix systems the stdio library may perform
shoaib_ahmed	0:791a779d6220	306	newline translation or otherwise corrupt binary data. To suppress this
shoaib_ahmed	0:791a779d6220	307	behavior, you may need to use a "b" option to fopen (as shown above), or use
shoaib_ahmed	0:791a779d6220	308	setmode() or another routine to put the stdio stream in binary mode. See
shoaib_ahmed	0:791a779d6220	309	cjpeg.c and djpeg.c for code that has been found to work on many systems.
shoaib_ahmed	0:791a779d6220	310
shoaib_ahmed	0:791a779d6220	311	You can select the data destination after setting other parameters (step 3),
shoaib_ahmed	0:791a779d6220	312	if that's more convenient. You may not change the destination between
shoaib_ahmed	0:791a779d6220	313	calling jpeg_start_compress() and jpeg_finish_compress().
shoaib_ahmed	0:791a779d6220	314
shoaib_ahmed	0:791a779d6220	315
shoaib_ahmed	0:791a779d6220	316	3. Set parameters for compression, including image size & colorspace.
shoaib_ahmed	0:791a779d6220	317
shoaib_ahmed	0:791a779d6220	318	You must supply information about the source image by setting the following
shoaib_ahmed	0:791a779d6220	319	fields in the JPEG object (cinfo structure):
shoaib_ahmed	0:791a779d6220	320
shoaib_ahmed	0:791a779d6220	321	image_width Width of image, in pixels
shoaib_ahmed	0:791a779d6220	322	image_height Height of image, in pixels
shoaib_ahmed	0:791a779d6220	323	input_components Number of color channels (samples per pixel)
shoaib_ahmed	0:791a779d6220	324	in_color_space Color space of source image
shoaib_ahmed	0:791a779d6220	325
shoaib_ahmed	0:791a779d6220	326	The image dimensions are, hopefully, obvious. JPEG supports image dimensions
shoaib_ahmed	0:791a779d6220	327	of 1 to 64K pixels in either direction. The input color space is typically
shoaib_ahmed	0:791a779d6220	328	RGB or grayscale, and input_components is 3 or 1 accordingly. (See "Special
shoaib_ahmed	0:791a779d6220	329	color spaces", later, for more info.) The in_color_space field must be
shoaib_ahmed	0:791a779d6220	330	assigned one of the J_COLOR_SPACE enum constants, typically JCS_RGB or
shoaib_ahmed	0:791a779d6220	331	JCS_GRAYSCALE.
shoaib_ahmed	0:791a779d6220	332
shoaib_ahmed	0:791a779d6220	333	JPEG has a large number of compression parameters that determine how the
shoaib_ahmed	0:791a779d6220	334	image is encoded. Most applications don't need or want to know about all
shoaib_ahmed	0:791a779d6220	335	these parameters. You can set all the parameters to reasonable defaults by
shoaib_ahmed	0:791a779d6220	336	calling jpeg_set_defaults(); then, if there are particular values you want
shoaib_ahmed	0:791a779d6220	337	to change, you can do so after that. The "Compression parameter selection"
shoaib_ahmed	0:791a779d6220	338	section tells about all the parameters.
shoaib_ahmed	0:791a779d6220	339
shoaib_ahmed	0:791a779d6220	340	You must set in_color_space correctly before calling jpeg_set_defaults(),
shoaib_ahmed	0:791a779d6220	341	because the defaults depend on the source image colorspace. However the
shoaib_ahmed	0:791a779d6220	342	other three source image parameters need not be valid until you call
shoaib_ahmed	0:791a779d6220	343	jpeg_start_compress(). There's no harm in calling jpeg_set_defaults() more
shoaib_ahmed	0:791a779d6220	344	than once, if that happens to be convenient.
shoaib_ahmed	0:791a779d6220	345
shoaib_ahmed	0:791a779d6220	346	Typical code for a 24-bit RGB source image is
shoaib_ahmed	0:791a779d6220	347
shoaib_ahmed	0:791a779d6220	348	cinfo.image_width = Width; /* image width and height, in pixels */
shoaib_ahmed	0:791a779d6220	349	cinfo.image_height = Height;
shoaib_ahmed	0:791a779d6220	350	cinfo.input_components = 3; /* # of color components per pixel */
shoaib_ahmed	0:791a779d6220	351	cinfo.in_color_space = JCS_RGB; /* colorspace of input image */
shoaib_ahmed	0:791a779d6220	352
shoaib_ahmed	0:791a779d6220	353	jpeg_set_defaults(&cinfo);
shoaib_ahmed	0:791a779d6220	354	/* Make optional parameter settings here */
shoaib_ahmed	0:791a779d6220	355
shoaib_ahmed	0:791a779d6220	356
shoaib_ahmed	0:791a779d6220	357	4. jpeg_start_compress(...);
shoaib_ahmed	0:791a779d6220	358
shoaib_ahmed	0:791a779d6220	359	After you have established the data destination and set all the necessary
shoaib_ahmed	0:791a779d6220	360	source image info and other parameters, call jpeg_start_compress() to begin
shoaib_ahmed	0:791a779d6220	361	a compression cycle. This will initialize internal state, allocate working
shoaib_ahmed	0:791a779d6220	362	storage, and emit the first few bytes of the JPEG datastream header.
shoaib_ahmed	0:791a779d6220	363
shoaib_ahmed	0:791a779d6220	364	Typical code:
shoaib_ahmed	0:791a779d6220	365
shoaib_ahmed	0:791a779d6220	366	jpeg_start_compress(&cinfo, TRUE);
shoaib_ahmed	0:791a779d6220	367
shoaib_ahmed	0:791a779d6220	368	The "TRUE" parameter ensures that a complete JPEG interchange datastream
shoaib_ahmed	0:791a779d6220	369	will be written. This is appropriate in most cases. If you think you might
shoaib_ahmed	0:791a779d6220	370	want to use an abbreviated datastream, read the section on abbreviated
shoaib_ahmed	0:791a779d6220	371	datastreams, below.
shoaib_ahmed	0:791a779d6220	372
shoaib_ahmed	0:791a779d6220	373	Once you have called jpeg_start_compress(), you may not alter any JPEG
shoaib_ahmed	0:791a779d6220	374	parameters or other fields of the JPEG object until you have completed
shoaib_ahmed	0:791a779d6220	375	the compression cycle.
shoaib_ahmed	0:791a779d6220	376
shoaib_ahmed	0:791a779d6220	377
shoaib_ahmed	0:791a779d6220	378	5. while (scan lines remain to be written)
shoaib_ahmed	0:791a779d6220	379	jpeg_write_scanlines(...);
shoaib_ahmed	0:791a779d6220	380
shoaib_ahmed	0:791a779d6220	381	Now write all the required image data by calling jpeg_write_scanlines()
shoaib_ahmed	0:791a779d6220	382	one or more times. You can pass one or more scanlines in each call, up
shoaib_ahmed	0:791a779d6220	383	to the total image height. In most applications it is convenient to pass
shoaib_ahmed	0:791a779d6220	384	just one or a few scanlines at a time. The expected format for the passed
shoaib_ahmed	0:791a779d6220	385	data is discussed under "Data formats", above.
shoaib_ahmed	0:791a779d6220	386
shoaib_ahmed	0:791a779d6220	387	Image data should be written in top-to-bottom scanline order. The JPEG spec
shoaib_ahmed	0:791a779d6220	388	contains some weasel wording about how top and bottom are application-defined
shoaib_ahmed	0:791a779d6220	389	terms (a curious interpretation of the English language...) but if you want
shoaib_ahmed	0:791a779d6220	390	your files to be compatible with everyone else's, you WILL use top-to-bottom
shoaib_ahmed	0:791a779d6220	391	order. If the source data must be read in bottom-to-top order, you can use
shoaib_ahmed	0:791a779d6220	392	the JPEG library's virtual array mechanism to invert the data efficiently.
shoaib_ahmed	0:791a779d6220	393	Examples of this can be found in the sample application cjpeg.
shoaib_ahmed	0:791a779d6220	394
shoaib_ahmed	0:791a779d6220	395	The library maintains a count of the number of scanlines written so far
shoaib_ahmed	0:791a779d6220	396	in the next_scanline field of the JPEG object. Usually you can just use
shoaib_ahmed	0:791a779d6220	397	this variable as the loop counter, so that the loop test looks like
shoaib_ahmed	0:791a779d6220	398	"while (cinfo.next_scanline < cinfo.image_height)".
shoaib_ahmed	0:791a779d6220	399
shoaib_ahmed	0:791a779d6220	400	Code for this step depends heavily on the way that you store the source data.
shoaib_ahmed	0:791a779d6220	401	example.c shows the following code for the case of a full-size 2-D source
shoaib_ahmed	0:791a779d6220	402	array containing 3-byte RGB pixels:
shoaib_ahmed	0:791a779d6220	403
shoaib_ahmed	0:791a779d6220	404	JSAMPROW row_pointer[1]; /* pointer to a single row */
shoaib_ahmed	0:791a779d6220	405	int row_stride; /* physical row width in buffer */
shoaib_ahmed	0:791a779d6220	406
shoaib_ahmed	0:791a779d6220	407	row_stride = image_width * 3; /* JSAMPLEs per row in image_buffer */
shoaib_ahmed	0:791a779d6220	408
shoaib_ahmed	0:791a779d6220	409	while (cinfo.next_scanline < cinfo.image_height) {
shoaib_ahmed	0:791a779d6220	410	row_pointer[0] = & image_buffer[cinfo.next_scanline * row_stride];
shoaib_ahmed	0:791a779d6220	411	jpeg_write_scanlines(&cinfo, row_pointer, 1);
shoaib_ahmed	0:791a779d6220	412	}
shoaib_ahmed	0:791a779d6220	413
shoaib_ahmed	0:791a779d6220	414	jpeg_write_scanlines() returns the number of scanlines actually written.
shoaib_ahmed	0:791a779d6220	415	This will normally be equal to the number passed in, so you can usually
shoaib_ahmed	0:791a779d6220	416	ignore the return value. It is different in just two cases:
shoaib_ahmed	0:791a779d6220	417	* If you try to write more scanlines than the declared image height,
shoaib_ahmed	0:791a779d6220	418	the additional scanlines are ignored.
shoaib_ahmed	0:791a779d6220	419	* If you use a suspending data destination manager, output buffer overrun
shoaib_ahmed	0:791a779d6220	420	will cause the compressor to return before accepting all the passed lines.
shoaib_ahmed	0:791a779d6220	421	This feature is discussed under "I/O suspension", below. The normal
shoaib_ahmed	0:791a779d6220	422	stdio destination manager will NOT cause this to happen.
shoaib_ahmed	0:791a779d6220	423	In any case, the return value is the same as the change in the value of
shoaib_ahmed	0:791a779d6220	424	next_scanline.
shoaib_ahmed	0:791a779d6220	425
shoaib_ahmed	0:791a779d6220	426
shoaib_ahmed	0:791a779d6220	427	6. jpeg_finish_compress(...);
shoaib_ahmed	0:791a779d6220	428
shoaib_ahmed	0:791a779d6220	429	After all the image data has been written, call jpeg_finish_compress() to
shoaib_ahmed	0:791a779d6220	430	complete the compression cycle. This step is ESSENTIAL to ensure that the
shoaib_ahmed	0:791a779d6220	431	last bufferload of data is written to the data destination.
shoaib_ahmed	0:791a779d6220	432	jpeg_finish_compress() also releases working memory associated with the JPEG
shoaib_ahmed	0:791a779d6220	433	object.
shoaib_ahmed	0:791a779d6220	434
shoaib_ahmed	0:791a779d6220	435	Typical code:
shoaib_ahmed	0:791a779d6220	436
shoaib_ahmed	0:791a779d6220	437	jpeg_finish_compress(&cinfo);
shoaib_ahmed	0:791a779d6220	438
shoaib_ahmed	0:791a779d6220	439	If using the stdio destination manager, don't forget to close the output
shoaib_ahmed	0:791a779d6220	440	stdio stream (if necessary) afterwards.
shoaib_ahmed	0:791a779d6220	441
shoaib_ahmed	0:791a779d6220	442	If you have requested a multi-pass operating mode, such as Huffman code
shoaib_ahmed	0:791a779d6220	443	optimization, jpeg_finish_compress() will perform the additional passes using
shoaib_ahmed	0:791a779d6220	444	data buffered by the first pass. In this case jpeg_finish_compress() may take
shoaib_ahmed	0:791a779d6220	445	quite a while to complete. With the default compression parameters, this will
shoaib_ahmed	0:791a779d6220	446	not happen.
shoaib_ahmed	0:791a779d6220	447
shoaib_ahmed	0:791a779d6220	448	It is an error to call jpeg_finish_compress() before writing the necessary
shoaib_ahmed	0:791a779d6220	449	total number of scanlines. If you wish to abort compression, call
shoaib_ahmed	0:791a779d6220	450	jpeg_abort() as discussed below.
shoaib_ahmed	0:791a779d6220	451
shoaib_ahmed	0:791a779d6220	452	After completing a compression cycle, you may dispose of the JPEG object
shoaib_ahmed	0:791a779d6220	453	as discussed next, or you may use it to compress another image. In that case
shoaib_ahmed	0:791a779d6220	454	return to step 2, 3, or 4 as appropriate. If you do not change the
shoaib_ahmed	0:791a779d6220	455	destination manager, the new datastream will be written to the same target.
shoaib_ahmed	0:791a779d6220	456	If you do not change any JPEG parameters, the new datastream will be written
shoaib_ahmed	0:791a779d6220	457	with the same parameters as before. Note that you can change the input image
shoaib_ahmed	0:791a779d6220	458	dimensions freely between cycles, but if you change the input colorspace, you
shoaib_ahmed	0:791a779d6220	459	should call jpeg_set_defaults() to adjust for the new colorspace; and then
shoaib_ahmed	0:791a779d6220	460	you'll need to repeat all of step 3.
shoaib_ahmed	0:791a779d6220	461
shoaib_ahmed	0:791a779d6220	462
shoaib_ahmed	0:791a779d6220	463	7. Release the JPEG compression object.
shoaib_ahmed	0:791a779d6220	464
shoaib_ahmed	0:791a779d6220	465	When you are done with a JPEG compression object, destroy it by calling
shoaib_ahmed	0:791a779d6220	466	jpeg_destroy_compress(). This will free all subsidiary memory (regardless of
shoaib_ahmed	0:791a779d6220	467	the previous state of the object). Or you can call jpeg_destroy(), which
shoaib_ahmed	0:791a779d6220	468	works for either compression or decompression objects --- this may be more
shoaib_ahmed	0:791a779d6220	469	convenient if you are sharing code between compression and decompression
shoaib_ahmed	0:791a779d6220	470	cases. (Actually, these routines are equivalent except for the declared type
shoaib_ahmed	0:791a779d6220	471	of the passed pointer. To avoid gripes from ANSI C compilers, jpeg_destroy()
shoaib_ahmed	0:791a779d6220	472	should be passed a j_common_ptr.)
shoaib_ahmed	0:791a779d6220	473
shoaib_ahmed	0:791a779d6220	474	If you allocated the jpeg_compress_struct structure from malloc(), freeing
shoaib_ahmed	0:791a779d6220	475	it is your responsibility --- jpeg_destroy() won't. Ditto for the error
shoaib_ahmed	0:791a779d6220	476	handler structure.
shoaib_ahmed	0:791a779d6220	477
shoaib_ahmed	0:791a779d6220	478	Typical code:
shoaib_ahmed	0:791a779d6220	479
shoaib_ahmed	0:791a779d6220	480	jpeg_destroy_compress(&cinfo);
shoaib_ahmed	0:791a779d6220	481
shoaib_ahmed	0:791a779d6220	482
shoaib_ahmed	0:791a779d6220	483	8. Aborting.
shoaib_ahmed	0:791a779d6220	484
shoaib_ahmed	0:791a779d6220	485	If you decide to abort a compression cycle before finishing, you can clean up
shoaib_ahmed	0:791a779d6220	486	in either of two ways:
shoaib_ahmed	0:791a779d6220	487
shoaib_ahmed	0:791a779d6220	488	* If you don't need the JPEG object any more, just call
shoaib_ahmed	0:791a779d6220	489	jpeg_destroy_compress() or jpeg_destroy() to release memory. This is
shoaib_ahmed	0:791a779d6220	490	legitimate at any point after calling jpeg_create_compress() --- in fact,
shoaib_ahmed	0:791a779d6220	491	it's safe even if jpeg_create_compress() fails.
shoaib_ahmed	0:791a779d6220	492
shoaib_ahmed	0:791a779d6220	493	* If you want to re-use the JPEG object, call jpeg_abort_compress(), or call
shoaib_ahmed	0:791a779d6220	494	jpeg_abort() which works on both compression and decompression objects.
shoaib_ahmed	0:791a779d6220	495	This will return the object to an idle state, releasing any working memory.
shoaib_ahmed	0:791a779d6220	496	jpeg_abort() is allowed at any time after successful object creation.
shoaib_ahmed	0:791a779d6220	497
shoaib_ahmed	0:791a779d6220	498	Note that cleaning up the data destination, if required, is your
shoaib_ahmed	0:791a779d6220	499	responsibility; neither of these routines will call term_destination().
shoaib_ahmed	0:791a779d6220	500	(See "Compressed data handling", below, for more about that.)
shoaib_ahmed	0:791a779d6220	501
shoaib_ahmed	0:791a779d6220	502	jpeg_destroy() and jpeg_abort() are the only safe calls to make on a JPEG
shoaib_ahmed	0:791a779d6220	503	object that has reported an error by calling error_exit (see "Error handling"
shoaib_ahmed	0:791a779d6220	504	for more info). The internal state of such an object is likely to be out of
shoaib_ahmed	0:791a779d6220	505	whack. Either of these two routines will return the object to a known state.
shoaib_ahmed	0:791a779d6220	506
shoaib_ahmed	0:791a779d6220	507
shoaib_ahmed	0:791a779d6220	508	Decompression details
shoaib_ahmed	0:791a779d6220	509	---------------------
shoaib_ahmed	0:791a779d6220	510
shoaib_ahmed	0:791a779d6220	511	Here we revisit the JPEG decompression outline given in the overview.
shoaib_ahmed	0:791a779d6220	512
shoaib_ahmed	0:791a779d6220	513	1. Allocate and initialize a JPEG decompression object.
shoaib_ahmed	0:791a779d6220	514
shoaib_ahmed	0:791a779d6220	515	This is just like initialization for compression, as discussed above,
shoaib_ahmed	0:791a779d6220	516	except that the object is a "struct jpeg_decompress_struct" and you
shoaib_ahmed	0:791a779d6220	517	call jpeg_create_decompress(). Error handling is exactly the same.
shoaib_ahmed	0:791a779d6220	518
shoaib_ahmed	0:791a779d6220	519	Typical code:
shoaib_ahmed	0:791a779d6220	520
shoaib_ahmed	0:791a779d6220	521	struct jpeg_decompress_struct cinfo;
shoaib_ahmed	0:791a779d6220	522	struct jpeg_error_mgr jerr;
shoaib_ahmed	0:791a779d6220	523	...
shoaib_ahmed	0:791a779d6220	524	cinfo.err = jpeg_std_error(&jerr);
shoaib_ahmed	0:791a779d6220	525	jpeg_create_decompress(&cinfo);
shoaib_ahmed	0:791a779d6220	526
shoaib_ahmed	0:791a779d6220	527	(Both here and in the IJG code, we usually use variable name "cinfo" for
shoaib_ahmed	0:791a779d6220	528	both compression and decompression objects.)
shoaib_ahmed	0:791a779d6220	529
shoaib_ahmed	0:791a779d6220	530
shoaib_ahmed	0:791a779d6220	531	2. Specify the source of the compressed data (eg, a file).
shoaib_ahmed	0:791a779d6220	532
shoaib_ahmed	0:791a779d6220	533	As previously mentioned, the JPEG library reads compressed data from a "data
shoaib_ahmed	0:791a779d6220	534	source" module. The library includes one data source module which knows how
shoaib_ahmed	0:791a779d6220	535	to read from a stdio stream. You can use your own source module if you want
shoaib_ahmed	0:791a779d6220	536	to do something else, as discussed later.
shoaib_ahmed	0:791a779d6220	537
shoaib_ahmed	0:791a779d6220	538	If you use the standard source module, you must open the source stdio stream
shoaib_ahmed	0:791a779d6220	539	beforehand. Typical code for this step looks like:
shoaib_ahmed	0:791a779d6220	540
shoaib_ahmed	0:791a779d6220	541	FILE * infile;
shoaib_ahmed	0:791a779d6220	542	...
shoaib_ahmed	0:791a779d6220	543	if ((infile = fopen(filename, "rb")) == NULL) {
shoaib_ahmed	0:791a779d6220	544	fprintf(stderr, "can't open %s\n", filename);
shoaib_ahmed	0:791a779d6220	545	exit(1);
shoaib_ahmed	0:791a779d6220	546	}
shoaib_ahmed	0:791a779d6220	547	jpeg_stdio_src(&cinfo, infile);
shoaib_ahmed	0:791a779d6220	548
shoaib_ahmed	0:791a779d6220	549	where the last line invokes the standard source module.
shoaib_ahmed	0:791a779d6220	550
shoaib_ahmed	0:791a779d6220	551	WARNING: it is critical that the binary compressed data be read unchanged.
shoaib_ahmed	0:791a779d6220	552	On non-Unix systems the stdio library may perform newline translation or
shoaib_ahmed	0:791a779d6220	553	otherwise corrupt binary data. To suppress this behavior, you may need to use
shoaib_ahmed	0:791a779d6220	554	a "b" option to fopen (as shown above), or use setmode() or another routine to
shoaib_ahmed	0:791a779d6220	555	put the stdio stream in binary mode. See cjpeg.c and djpeg.c for code that
shoaib_ahmed	0:791a779d6220	556	has been found to work on many systems.
shoaib_ahmed	0:791a779d6220	557
shoaib_ahmed	0:791a779d6220	558	You may not change the data source between calling jpeg_read_header() and
shoaib_ahmed	0:791a779d6220	559	jpeg_finish_decompress(). If you wish to read a series of JPEG images from
shoaib_ahmed	0:791a779d6220	560	a single source file, you should repeat the jpeg_read_header() to
shoaib_ahmed	0:791a779d6220	561	jpeg_finish_decompress() sequence without reinitializing either the JPEG
shoaib_ahmed	0:791a779d6220	562	object or the data source module; this prevents buffered input data from
shoaib_ahmed	0:791a779d6220	563	being discarded.
shoaib_ahmed	0:791a779d6220	564
shoaib_ahmed	0:791a779d6220	565
shoaib_ahmed	0:791a779d6220	566	3. Call jpeg_read_header() to obtain image info.
shoaib_ahmed	0:791a779d6220	567
shoaib_ahmed	0:791a779d6220	568	Typical code for this step is just
shoaib_ahmed	0:791a779d6220	569
shoaib_ahmed	0:791a779d6220	570	jpeg_read_header(&cinfo, TRUE);
shoaib_ahmed	0:791a779d6220	571
shoaib_ahmed	0:791a779d6220	572	This will read the source datastream header markers, up to the beginning
shoaib_ahmed	0:791a779d6220	573	of the compressed data proper. On return, the image dimensions and other
shoaib_ahmed	0:791a779d6220	574	info have been stored in the JPEG object. The application may wish to
shoaib_ahmed	0:791a779d6220	575	consult this information before selecting decompression parameters.
shoaib_ahmed	0:791a779d6220	576
shoaib_ahmed	0:791a779d6220	577	More complex code is necessary if
shoaib_ahmed	0:791a779d6220	578	* A suspending data source is used --- in that case jpeg_read_header()
shoaib_ahmed	0:791a779d6220	579	may return before it has read all the header data. See "I/O suspension",
shoaib_ahmed	0:791a779d6220	580	below. The normal stdio source manager will NOT cause this to happen.
shoaib_ahmed	0:791a779d6220	581	* Abbreviated JPEG files are to be processed --- see the section on
shoaib_ahmed	0:791a779d6220	582	abbreviated datastreams. Standard applications that deal only in
shoaib_ahmed	0:791a779d6220	583	interchange JPEG files need not be concerned with this case either.
shoaib_ahmed	0:791a779d6220	584
shoaib_ahmed	0:791a779d6220	585	It is permissible to stop at this point if you just wanted to find out the
shoaib_ahmed	0:791a779d6220	586	image dimensions and other header info for a JPEG file. In that case,
shoaib_ahmed	0:791a779d6220	587	call jpeg_destroy() when you are done with the JPEG object, or call
shoaib_ahmed	0:791a779d6220	588	jpeg_abort() to return it to an idle state before selecting a new data
shoaib_ahmed	0:791a779d6220	589	source and reading another header.
shoaib_ahmed	0:791a779d6220	590
shoaib_ahmed	0:791a779d6220	591
shoaib_ahmed	0:791a779d6220	592	4. Set parameters for decompression.
shoaib_ahmed	0:791a779d6220	593
shoaib_ahmed	0:791a779d6220	594	jpeg_read_header() sets appropriate default decompression parameters based on
shoaib_ahmed	0:791a779d6220	595	the properties of the image (in particular, its colorspace). However, you
shoaib_ahmed	0:791a779d6220	596	may well want to alter these defaults before beginning the decompression.
shoaib_ahmed	0:791a779d6220	597	For example, the default is to produce full color output from a color file.
shoaib_ahmed	0:791a779d6220	598	If you want colormapped output you must ask for it. Other options allow the
shoaib_ahmed	0:791a779d6220	599	returned image to be scaled and allow various speed/quality tradeoffs to be
shoaib_ahmed	0:791a779d6220	600	selected. "Decompression parameter selection", below, gives details.
shoaib_ahmed	0:791a779d6220	601
shoaib_ahmed	0:791a779d6220	602	If the defaults are appropriate, nothing need be done at this step.
shoaib_ahmed	0:791a779d6220	603
shoaib_ahmed	0:791a779d6220	604	Note that all default values are set by each call to jpeg_read_header().
shoaib_ahmed	0:791a779d6220	605	If you reuse a decompression object, you cannot expect your parameter
shoaib_ahmed	0:791a779d6220	606	settings to be preserved across cycles, as you can for compression.
shoaib_ahmed	0:791a779d6220	607	You must set desired parameter values each time.
shoaib_ahmed	0:791a779d6220	608
shoaib_ahmed	0:791a779d6220	609
shoaib_ahmed	0:791a779d6220	610	5. jpeg_start_decompress(...);
shoaib_ahmed	0:791a779d6220	611
shoaib_ahmed	0:791a779d6220	612	Once the parameter values are satisfactory, call jpeg_start_decompress() to
shoaib_ahmed	0:791a779d6220	613	begin decompression. This will initialize internal state, allocate working
shoaib_ahmed	0:791a779d6220	614	memory, and prepare for returning data.
shoaib_ahmed	0:791a779d6220	615
shoaib_ahmed	0:791a779d6220	616	Typical code is just
shoaib_ahmed	0:791a779d6220	617
shoaib_ahmed	0:791a779d6220	618	jpeg_start_decompress(&cinfo);
shoaib_ahmed	0:791a779d6220	619
shoaib_ahmed	0:791a779d6220	620	If you have requested a multi-pass operating mode, such as 2-pass color
shoaib_ahmed	0:791a779d6220	621	quantization, jpeg_start_decompress() will do everything needed before data
shoaib_ahmed	0:791a779d6220	622	output can begin. In this case jpeg_start_decompress() may take quite a while
shoaib_ahmed	0:791a779d6220	623	to complete. With a single-scan (non progressive) JPEG file and default
shoaib_ahmed	0:791a779d6220	624	decompression parameters, this will not happen; jpeg_start_decompress() will
shoaib_ahmed	0:791a779d6220	625	return quickly.
shoaib_ahmed	0:791a779d6220	626
shoaib_ahmed	0:791a779d6220	627	After this call, the final output image dimensions, including any requested
shoaib_ahmed	0:791a779d6220	628	scaling, are available in the JPEG object; so is the selected colormap, if
shoaib_ahmed	0:791a779d6220	629	colormapped output has been requested. Useful fields include
shoaib_ahmed	0:791a779d6220	630
shoaib_ahmed	0:791a779d6220	631	output_width image width and height, as scaled
shoaib_ahmed	0:791a779d6220	632	output_height
shoaib_ahmed	0:791a779d6220	633	out_color_components # of color components in out_color_space
shoaib_ahmed	0:791a779d6220	634	output_components # of color components returned per pixel
shoaib_ahmed	0:791a779d6220	635	colormap the selected colormap, if any
shoaib_ahmed	0:791a779d6220	636	actual_number_of_colors number of entries in colormap
shoaib_ahmed	0:791a779d6220	637
shoaib_ahmed	0:791a779d6220	638	output_components is 1 (a colormap index) when quantizing colors; otherwise it
shoaib_ahmed	0:791a779d6220	639	equals out_color_components. It is the number of JSAMPLE values that will be
shoaib_ahmed	0:791a779d6220	640	emitted per pixel in the output arrays.
shoaib_ahmed	0:791a779d6220	641
shoaib_ahmed	0:791a779d6220	642	Typically you will need to allocate data buffers to hold the incoming image.
shoaib_ahmed	0:791a779d6220	643	You will need output_width * output_components JSAMPLEs per scanline in your
shoaib_ahmed	0:791a779d6220	644	output buffer, and a total of output_height scanlines will be returned.
shoaib_ahmed	0:791a779d6220	645
shoaib_ahmed	0:791a779d6220	646	Note: if you are using the JPEG library's internal memory manager to allocate
shoaib_ahmed	0:791a779d6220	647	data buffers (as djpeg does), then the manager's protocol requires that you
shoaib_ahmed	0:791a779d6220	648	request large buffers before calling jpeg_start_decompress(). This is a
shoaib_ahmed	0:791a779d6220	649	little tricky since the output_XXX fields are not normally valid then. You
shoaib_ahmed	0:791a779d6220	650	can make them valid by calling jpeg_calc_output_dimensions() after setting the
shoaib_ahmed	0:791a779d6220	651	relevant parameters (scaling, output color space, and quantization flag).
shoaib_ahmed	0:791a779d6220	652
shoaib_ahmed	0:791a779d6220	653
shoaib_ahmed	0:791a779d6220	654	6. while (scan lines remain to be read)
shoaib_ahmed	0:791a779d6220	655	jpeg_read_scanlines(...);
shoaib_ahmed	0:791a779d6220	656
shoaib_ahmed	0:791a779d6220	657	Now you can read the decompressed image data by calling jpeg_read_scanlines()
shoaib_ahmed	0:791a779d6220	658	one or more times. At each call, you pass in the maximum number of scanlines
shoaib_ahmed	0:791a779d6220	659	to be read (ie, the height of your working buffer); jpeg_read_scanlines()
shoaib_ahmed	0:791a779d6220	660	will return up to that many lines. The return value is the number of lines
shoaib_ahmed	0:791a779d6220	661	actually read. The format of the returned data is discussed under "Data
shoaib_ahmed	0:791a779d6220	662	formats", above. Don't forget that grayscale and color JPEGs will return
shoaib_ahmed	0:791a779d6220	663	different data formats!
shoaib_ahmed	0:791a779d6220	664
shoaib_ahmed	0:791a779d6220	665	Image data is returned in top-to-bottom scanline order. If you must write
shoaib_ahmed	0:791a779d6220	666	out the image in bottom-to-top order, you can use the JPEG library's virtual
shoaib_ahmed	0:791a779d6220	667	array mechanism to invert the data efficiently. Examples of this can be
shoaib_ahmed	0:791a779d6220	668	found in the sample application djpeg.
shoaib_ahmed	0:791a779d6220	669
shoaib_ahmed	0:791a779d6220	670	The library maintains a count of the number of scanlines returned so far
shoaib_ahmed	0:791a779d6220	671	in the output_scanline field of the JPEG object. Usually you can just use
shoaib_ahmed	0:791a779d6220	672	this variable as the loop counter, so that the loop test looks like
shoaib_ahmed	0:791a779d6220	673	"while (cinfo.output_scanline < cinfo.output_height)". (Note that the test
shoaib_ahmed	0:791a779d6220	674	should NOT be against image_height, unless you never use scaling. The
shoaib_ahmed	0:791a779d6220	675	image_height field is the height of the original unscaled image.)
shoaib_ahmed	0:791a779d6220	676	The return value always equals the change in the value of output_scanline.
shoaib_ahmed	0:791a779d6220	677
shoaib_ahmed	0:791a779d6220	678	If you don't use a suspending data source, it is safe to assume that
shoaib_ahmed	0:791a779d6220	679	jpeg_read_scanlines() reads at least one scanline per call, until the
shoaib_ahmed	0:791a779d6220	680	bottom of the image has been reached.
shoaib_ahmed	0:791a779d6220	681
shoaib_ahmed	0:791a779d6220	682	If you use a buffer larger than one scanline, it is NOT safe to assume that
shoaib_ahmed	0:791a779d6220	683	jpeg_read_scanlines() fills it. (The current implementation returns only a
shoaib_ahmed	0:791a779d6220	684	few scanlines per call, no matter how large a buffer you pass.) So you must
shoaib_ahmed	0:791a779d6220	685	always provide a loop that calls jpeg_read_scanlines() repeatedly until the
shoaib_ahmed	0:791a779d6220	686	whole image has been read.
shoaib_ahmed	0:791a779d6220	687
shoaib_ahmed	0:791a779d6220	688
shoaib_ahmed	0:791a779d6220	689	7. jpeg_finish_decompress(...);
shoaib_ahmed	0:791a779d6220	690
shoaib_ahmed	0:791a779d6220	691	After all the image data has been read, call jpeg_finish_decompress() to
shoaib_ahmed	0:791a779d6220	692	complete the decompression cycle. This causes working memory associated
shoaib_ahmed	0:791a779d6220	693	with the JPEG object to be released.
shoaib_ahmed	0:791a779d6220	694
shoaib_ahmed	0:791a779d6220	695	Typical code:
shoaib_ahmed	0:791a779d6220	696
shoaib_ahmed	0:791a779d6220	697	jpeg_finish_decompress(&cinfo);
shoaib_ahmed	0:791a779d6220	698
shoaib_ahmed	0:791a779d6220	699	If using the stdio source manager, don't forget to close the source stdio
shoaib_ahmed	0:791a779d6220	700	stream if necessary.
shoaib_ahmed	0:791a779d6220	701
shoaib_ahmed	0:791a779d6220	702	It is an error to call jpeg_finish_decompress() before reading the correct
shoaib_ahmed	0:791a779d6220	703	total number of scanlines. If you wish to abort decompression, call
shoaib_ahmed	0:791a779d6220	704	jpeg_abort() as discussed below.
shoaib_ahmed	0:791a779d6220	705
shoaib_ahmed	0:791a779d6220	706	After completing a decompression cycle, you may dispose of the JPEG object as
shoaib_ahmed	0:791a779d6220	707	discussed next, or you may use it to decompress another image. In that case
shoaib_ahmed	0:791a779d6220	708	return to step 2 or 3 as appropriate. If you do not change the source
shoaib_ahmed	0:791a779d6220	709	manager, the next image will be read from the same source.
shoaib_ahmed	0:791a779d6220	710
shoaib_ahmed	0:791a779d6220	711
shoaib_ahmed	0:791a779d6220	712	8. Release the JPEG decompression object.
shoaib_ahmed	0:791a779d6220	713
shoaib_ahmed	0:791a779d6220	714	When you are done with a JPEG decompression object, destroy it by calling
shoaib_ahmed	0:791a779d6220	715	jpeg_destroy_decompress() or jpeg_destroy(). The previous discussion of
shoaib_ahmed	0:791a779d6220	716	destroying compression objects applies here too.
shoaib_ahmed	0:791a779d6220	717
shoaib_ahmed	0:791a779d6220	718	Typical code:
shoaib_ahmed	0:791a779d6220	719
shoaib_ahmed	0:791a779d6220	720	jpeg_destroy_decompress(&cinfo);
shoaib_ahmed	0:791a779d6220	721
shoaib_ahmed	0:791a779d6220	722
shoaib_ahmed	0:791a779d6220	723	9. Aborting.
shoaib_ahmed	0:791a779d6220	724
shoaib_ahmed	0:791a779d6220	725	You can abort a decompression cycle by calling jpeg_destroy_decompress() or
shoaib_ahmed	0:791a779d6220	726	jpeg_destroy() if you don't need the JPEG object any more, or
shoaib_ahmed	0:791a779d6220	727	jpeg_abort_decompress() or jpeg_abort() if you want to reuse the object.
shoaib_ahmed	0:791a779d6220	728	The previous discussion of aborting compression cycles applies here too.
shoaib_ahmed	0:791a779d6220	729
shoaib_ahmed	0:791a779d6220	730
shoaib_ahmed	0:791a779d6220	731	Mechanics of usage: include files, linking, etc
shoaib_ahmed	0:791a779d6220	732	-----------------------------------------------
shoaib_ahmed	0:791a779d6220	733
shoaib_ahmed	0:791a779d6220	734	Applications using the JPEG library should include the header file jpeglib.h
shoaib_ahmed	0:791a779d6220	735	to obtain declarations of data types and routines. Before including
shoaib_ahmed	0:791a779d6220	736	jpeglib.h, include system headers that define at least the typedefs FILE and
shoaib_ahmed	0:791a779d6220	737	size_t. On ANSI-conforming systems, including <stdio.h> is sufficient; on
shoaib_ahmed	0:791a779d6220	738	older Unix systems, you may need <sys/types.h> to define size_t.
shoaib_ahmed	0:791a779d6220	739
shoaib_ahmed	0:791a779d6220	740	If the application needs to refer to individual JPEG library error codes, also
shoaib_ahmed	0:791a779d6220	741	include jerror.h to define those symbols.
shoaib_ahmed	0:791a779d6220	742
shoaib_ahmed	0:791a779d6220	743	jpeglib.h indirectly includes the files jconfig.h and jmorecfg.h. If you are
shoaib_ahmed	0:791a779d6220	744	installing the JPEG header files in a system directory, you will want to
shoaib_ahmed	0:791a779d6220	745	install all four files: jpeglib.h, jerror.h, jconfig.h, jmorecfg.h.
shoaib_ahmed	0:791a779d6220	746
shoaib_ahmed	0:791a779d6220	747	The most convenient way to include the JPEG code into your executable program
shoaib_ahmed	0:791a779d6220	748	is to prepare a library file ("libjpeg.a", or a corresponding name on non-Unix
shoaib_ahmed	0:791a779d6220	749	machines) and reference it at your link step. If you use only half of the
shoaib_ahmed	0:791a779d6220	750	library (only compression or only decompression), only that much code will be
shoaib_ahmed	0:791a779d6220	751	included from the library, unless your linker is hopelessly brain-damaged.
shoaib_ahmed	0:791a779d6220	752	The supplied makefiles build libjpeg.a automatically (see install.txt).
shoaib_ahmed	0:791a779d6220	753
shoaib_ahmed	0:791a779d6220	754	While you can build the JPEG library as a shared library if the whim strikes
shoaib_ahmed	0:791a779d6220	755	you, we don't really recommend it. The trouble with shared libraries is that
shoaib_ahmed	0:791a779d6220	756	at some point you'll probably try to substitute a new version of the library
shoaib_ahmed	0:791a779d6220	757	without recompiling the calling applications. That generally doesn't work
shoaib_ahmed	0:791a779d6220	758	because the parameter struct declarations usually change with each new
shoaib_ahmed	0:791a779d6220	759	version. In other words, the library's API is not guaranteed binary
shoaib_ahmed	0:791a779d6220	760	compatible across versions; we only try to ensure source-code compatibility.
shoaib_ahmed	0:791a779d6220	761	(In hindsight, it might have been smarter to hide the parameter structs from
shoaib_ahmed	0:791a779d6220	762	applications and introduce a ton of access functions instead. Too late now,
shoaib_ahmed	0:791a779d6220	763	however.)
shoaib_ahmed	0:791a779d6220	764
shoaib_ahmed	0:791a779d6220	765	On some systems your application may need to set up a signal handler to ensure
shoaib_ahmed	0:791a779d6220	766	that temporary files are deleted if the program is interrupted. This is most
shoaib_ahmed	0:791a779d6220	767	critical if you are on MS-DOS and use the jmemdos.c memory manager back end;
shoaib_ahmed	0:791a779d6220	768	it will try to grab extended memory for temp files, and that space will NOT be
shoaib_ahmed	0:791a779d6220	769	freed automatically. See cjpeg.c or djpeg.c for an example signal handler.
shoaib_ahmed	0:791a779d6220	770
shoaib_ahmed	0:791a779d6220	771	It may be worth pointing out that the core JPEG library does not actually
shoaib_ahmed	0:791a779d6220	772	require the stdio library: only the default source/destination managers and
shoaib_ahmed	0:791a779d6220	773	error handler need it. You can use the library in a stdio-less environment
shoaib_ahmed	0:791a779d6220	774	if you replace those modules and use jmemnobs.c (or another memory manager of
shoaib_ahmed	0:791a779d6220	775	your own devising). More info about the minimum system library requirements
shoaib_ahmed	0:791a779d6220	776	may be found in jinclude.h.
shoaib_ahmed	0:791a779d6220	777
shoaib_ahmed	0:791a779d6220	778
shoaib_ahmed	0:791a779d6220	779	ADVANCED FEATURES
shoaib_ahmed	0:791a779d6220	780	=================
shoaib_ahmed	0:791a779d6220	781
shoaib_ahmed	0:791a779d6220	782	Compression parameter selection
shoaib_ahmed	0:791a779d6220	783	-------------------------------
shoaib_ahmed	0:791a779d6220	784
shoaib_ahmed	0:791a779d6220	785	This section describes all the optional parameters you can set for JPEG
shoaib_ahmed	0:791a779d6220	786	compression, as well as the "helper" routines provided to assist in this
shoaib_ahmed	0:791a779d6220	787	task. Proper setting of some parameters requires detailed understanding
shoaib_ahmed	0:791a779d6220	788	of the JPEG standard; if you don't know what a parameter is for, it's best
shoaib_ahmed	0:791a779d6220	789	not to mess with it! See REFERENCES in the README file for pointers to
shoaib_ahmed	0:791a779d6220	790	more info about JPEG.
shoaib_ahmed	0:791a779d6220	791
shoaib_ahmed	0:791a779d6220	792	It's a good idea to call jpeg_set_defaults() first, even if you plan to set
shoaib_ahmed	0:791a779d6220	793	all the parameters; that way your code is more likely to work with future JPEG
shoaib_ahmed	0:791a779d6220	794	libraries that have additional parameters. For the same reason, we recommend
shoaib_ahmed	0:791a779d6220	795	you use a helper routine where one is provided, in preference to twiddling
shoaib_ahmed	0:791a779d6220	796	cinfo fields directly.
shoaib_ahmed	0:791a779d6220	797
shoaib_ahmed	0:791a779d6220	798	The helper routines are:
shoaib_ahmed	0:791a779d6220	799
shoaib_ahmed	0:791a779d6220	800	jpeg_set_defaults (j_compress_ptr cinfo)
shoaib_ahmed	0:791a779d6220	801	This routine sets all JPEG parameters to reasonable defaults, using
shoaib_ahmed	0:791a779d6220	802	only the input image's color space (field in_color_space, which must
shoaib_ahmed	0:791a779d6220	803	already be set in cinfo). Many applications will only need to use
shoaib_ahmed	0:791a779d6220	804	this routine and perhaps jpeg_set_quality().
shoaib_ahmed	0:791a779d6220	805
shoaib_ahmed	0:791a779d6220	806	jpeg_set_colorspace (j_compress_ptr cinfo, J_COLOR_SPACE colorspace)
shoaib_ahmed	0:791a779d6220	807	Sets the JPEG file's colorspace (field jpeg_color_space) as specified,
shoaib_ahmed	0:791a779d6220	808	and sets other color-space-dependent parameters appropriately. See
shoaib_ahmed	0:791a779d6220	809	"Special color spaces", below, before using this. A large number of
shoaib_ahmed	0:791a779d6220	810	parameters, including all per-component parameters, are set by this
shoaib_ahmed	0:791a779d6220	811	routine; if you want to twiddle individual parameters you should call
shoaib_ahmed	0:791a779d6220	812	jpeg_set_colorspace() before rather than after.
shoaib_ahmed	0:791a779d6220	813
shoaib_ahmed	0:791a779d6220	814	jpeg_default_colorspace (j_compress_ptr cinfo)
shoaib_ahmed	0:791a779d6220	815	Selects an appropriate JPEG colorspace based on cinfo->in_color_space,
shoaib_ahmed	0:791a779d6220	816	and calls jpeg_set_colorspace(). This is actually a subroutine of
shoaib_ahmed	0:791a779d6220	817	jpeg_set_defaults(). It's broken out in case you want to change
shoaib_ahmed	0:791a779d6220	818	just the colorspace-dependent JPEG parameters.
shoaib_ahmed	0:791a779d6220	819
shoaib_ahmed	0:791a779d6220	820	jpeg_set_quality (j_compress_ptr cinfo, int quality, boolean force_baseline)
shoaib_ahmed	0:791a779d6220	821	Constructs JPEG quantization tables appropriate for the indicated
shoaib_ahmed	0:791a779d6220	822	quality setting. The quality value is expressed on the 0..100 scale
shoaib_ahmed	0:791a779d6220	823	recommended by IJG (cjpeg's "-quality" switch uses this routine).
shoaib_ahmed	0:791a779d6220	824	Note that the exact mapping from quality values to tables may change
shoaib_ahmed	0:791a779d6220	825	in future IJG releases as more is learned about DCT quantization.
shoaib_ahmed	0:791a779d6220	826	If the force_baseline parameter is TRUE, then the quantization table
shoaib_ahmed	0:791a779d6220	827	entries are constrained to the range 1..255 for full JPEG baseline
shoaib_ahmed	0:791a779d6220	828	compatibility. In the current implementation, this only makes a
shoaib_ahmed	0:791a779d6220	829	difference for quality settings below 25, and it effectively prevents
shoaib_ahmed	0:791a779d6220	830	very small/low quality files from being generated. The IJG decoder
shoaib_ahmed	0:791a779d6220	831	is capable of reading the non-baseline files generated at low quality
shoaib_ahmed	0:791a779d6220	832	settings when force_baseline is FALSE, but other decoders may not be.
shoaib_ahmed	0:791a779d6220	833
shoaib_ahmed	0:791a779d6220	834	jpeg_set_linear_quality (j_compress_ptr cinfo, int scale_factor,
shoaib_ahmed	0:791a779d6220	835	boolean force_baseline)
shoaib_ahmed	0:791a779d6220	836	Same as jpeg_set_quality() except that the generated tables are the
shoaib_ahmed	0:791a779d6220	837	sample tables given in the JPEC spec section K.1, multiplied by the
shoaib_ahmed	0:791a779d6220	838	specified scale factor (which is expressed as a percentage; thus
shoaib_ahmed	0:791a779d6220	839	scale_factor = 100 reproduces the spec's tables). Note that larger
shoaib_ahmed	0:791a779d6220	840	scale factors give lower quality. This entry point is useful for
shoaib_ahmed	0:791a779d6220	841	conforming to the Adobe PostScript DCT conventions, but we do not
shoaib_ahmed	0:791a779d6220	842	recommend linear scaling as a user-visible quality scale otherwise.
shoaib_ahmed	0:791a779d6220	843	force_baseline again constrains the computed table entries to 1..255.
shoaib_ahmed	0:791a779d6220	844
shoaib_ahmed	0:791a779d6220	845	int jpeg_quality_scaling (int quality)
shoaib_ahmed	0:791a779d6220	846	Converts a value on the IJG-recommended quality scale to a linear
shoaib_ahmed	0:791a779d6220	847	scaling percentage. Note that this routine may change or go away
shoaib_ahmed	0:791a779d6220	848	in future releases --- IJG may choose to adopt a scaling method that
shoaib_ahmed	0:791a779d6220	849	can't be expressed as a simple scalar multiplier, in which case the
shoaib_ahmed	0:791a779d6220	850	premise of this routine collapses. Caveat user.
shoaib_ahmed	0:791a779d6220	851
shoaib_ahmed	0:791a779d6220	852	jpeg_default_qtables (j_compress_ptr cinfo, boolean force_baseline)
shoaib_ahmed	0:791a779d6220	853	Set default quantization tables with linear q_scale_factor[] values
shoaib_ahmed	0:791a779d6220	854	(see below).
shoaib_ahmed	0:791a779d6220	855
shoaib_ahmed	0:791a779d6220	856	jpeg_add_quant_table (j_compress_ptr cinfo, int which_tbl,
shoaib_ahmed	0:791a779d6220	857	const unsigned int *basic_table,
shoaib_ahmed	0:791a779d6220	858	int scale_factor, boolean force_baseline)
shoaib_ahmed	0:791a779d6220	859	Allows an arbitrary quantization table to be created. which_tbl
shoaib_ahmed	0:791a779d6220	860	indicates which table slot to fill. basic_table points to an array
shoaib_ahmed	0:791a779d6220	861	of 64 unsigned ints given in normal array order. These values are
shoaib_ahmed	0:791a779d6220	862	multiplied by scale_factor/100 and then clamped to the range 1..65535
shoaib_ahmed	0:791a779d6220	863	(or to 1..255 if force_baseline is TRUE).
shoaib_ahmed	0:791a779d6220	864	CAUTION: prior to library version 6a, jpeg_add_quant_table expected
shoaib_ahmed	0:791a779d6220	865	the basic table to be given in JPEG zigzag order. If you need to
shoaib_ahmed	0:791a779d6220	866	write code that works with either older or newer versions of this
shoaib_ahmed	0:791a779d6220	867	routine, you must check the library version number. Something like
shoaib_ahmed	0:791a779d6220	868	"#if JPEG_LIB_VERSION >= 61" is the right test.
shoaib_ahmed	0:791a779d6220	869
shoaib_ahmed	0:791a779d6220	870	jpeg_simple_progression (j_compress_ptr cinfo)
shoaib_ahmed	0:791a779d6220	871	Generates a default scan script for writing a progressive-JPEG file.
shoaib_ahmed	0:791a779d6220	872	This is the recommended method of creating a progressive file,
shoaib_ahmed	0:791a779d6220	873	unless you want to make a custom scan sequence. You must ensure that
shoaib_ahmed	0:791a779d6220	874	the JPEG color space is set correctly before calling this routine.
shoaib_ahmed	0:791a779d6220	875
shoaib_ahmed	0:791a779d6220	876
shoaib_ahmed	0:791a779d6220	877	Compression parameters (cinfo fields) include:
shoaib_ahmed	0:791a779d6220	878
shoaib_ahmed	0:791a779d6220	879	boolean arith_code
shoaib_ahmed	0:791a779d6220	880	If TRUE, use arithmetic coding.
shoaib_ahmed	0:791a779d6220	881	If FALSE, use Huffman coding.
shoaib_ahmed	0:791a779d6220	882
shoaib_ahmed	0:791a779d6220	883	int block_size
shoaib_ahmed	0:791a779d6220	884	Set DCT block size. All N from 1 to 16 are possible.
shoaib_ahmed	0:791a779d6220	885	Default is 8 (baseline format).
shoaib_ahmed	0:791a779d6220	886	Larger values produce higher compression,
shoaib_ahmed	0:791a779d6220	887	smaller values produce higher quality.
shoaib_ahmed	0:791a779d6220	888	An exact DCT stage is possible with 1 or 2.
shoaib_ahmed	0:791a779d6220	889	With the default quality of 75 and default Luminance qtable
shoaib_ahmed	0:791a779d6220	890	the DCT+Quantization stage is lossless for value 1.
shoaib_ahmed	0:791a779d6220	891	Note that values other than 8 require a SmartScale capable decoder,
shoaib_ahmed	0:791a779d6220	892	introduced with IJG JPEG 8. Setting the block_size parameter for
shoaib_ahmed	0:791a779d6220	893	compression works with version 8c and later.
shoaib_ahmed	0:791a779d6220	894
shoaib_ahmed	0:791a779d6220	895	J_DCT_METHOD dct_method
shoaib_ahmed	0:791a779d6220	896	Selects the algorithm used for the DCT step. Choices are:
shoaib_ahmed	0:791a779d6220	897	JDCT_ISLOW: slow but accurate integer algorithm
shoaib_ahmed	0:791a779d6220	898	JDCT_IFAST: faster, less accurate integer method
shoaib_ahmed	0:791a779d6220	899	JDCT_FLOAT: floating-point method
shoaib_ahmed	0:791a779d6220	900	JDCT_DEFAULT: default method (normally JDCT_ISLOW)
shoaib_ahmed	0:791a779d6220	901	JDCT_FASTEST: fastest method (normally JDCT_IFAST)
shoaib_ahmed	0:791a779d6220	902	The FLOAT method is very slightly more accurate than the ISLOW method,
shoaib_ahmed	0:791a779d6220	903	but may give different results on different machines due to varying
shoaib_ahmed	0:791a779d6220	904	roundoff behavior. The integer methods should give the same results
shoaib_ahmed	0:791a779d6220	905	on all machines. On machines with sufficiently fast FP hardware, the
shoaib_ahmed	0:791a779d6220	906	floating-point method may also be the fastest. The IFAST method is
shoaib_ahmed	0:791a779d6220	907	considerably less accurate than the other two; its use is not
shoaib_ahmed	0:791a779d6220	908	recommended if high quality is a concern. JDCT_DEFAULT and
shoaib_ahmed	0:791a779d6220	909	JDCT_FASTEST are macros configurable by each installation.
shoaib_ahmed	0:791a779d6220	910
shoaib_ahmed	0:791a779d6220	911	unsigned int scale_num, scale_denom
shoaib_ahmed	0:791a779d6220	912	Scale the image by the fraction scale_num/scale_denom. Default is
shoaib_ahmed	0:791a779d6220	913	1/1, or no scaling. Currently, the supported scaling ratios are
shoaib_ahmed	0:791a779d6220	914	M/N with all N from 1 to 16, where M is the destination DCT size,
shoaib_ahmed	0:791a779d6220	915	which is 8 by default (see block_size parameter above).
shoaib_ahmed	0:791a779d6220	916	(The library design allows for arbitrary scaling ratios but this
shoaib_ahmed	0:791a779d6220	917	is not likely to be implemented any time soon.)
shoaib_ahmed	0:791a779d6220	918
shoaib_ahmed	0:791a779d6220	919	J_COLOR_SPACE jpeg_color_space
shoaib_ahmed	0:791a779d6220	920	int num_components
shoaib_ahmed	0:791a779d6220	921	The JPEG color space and corresponding number of components; see
shoaib_ahmed	0:791a779d6220	922	"Special color spaces", below, for more info. We recommend using
shoaib_ahmed	0:791a779d6220	923	jpeg_set_colorspace() if you want to change these.
shoaib_ahmed	0:791a779d6220	924
shoaib_ahmed	0:791a779d6220	925	J_COLOR_TRANSFORM color_transform
shoaib_ahmed	0:791a779d6220	926	Internal color transform identifier, writes LSE marker if nonzero
shoaib_ahmed	0:791a779d6220	927	(requires decoder with inverse color transform support, introduced
shoaib_ahmed	0:791a779d6220	928	with IJG JPEG 9).
shoaib_ahmed	0:791a779d6220	929	Two values are currently possible: JCT_NONE and JCT_SUBTRACT_GREEN.
shoaib_ahmed	0:791a779d6220	930	Set this value for lossless RGB application before calling
shoaib_ahmed	0:791a779d6220	931	jpeg_set_colorspace(), because entropy table assignment in
shoaib_ahmed	0:791a779d6220	932	jpeg_set_colorspace() depends on color_transform.
shoaib_ahmed	0:791a779d6220	933
shoaib_ahmed	0:791a779d6220	934	boolean optimize_coding
shoaib_ahmed	0:791a779d6220	935	TRUE causes the compressor to compute optimal Huffman coding tables
shoaib_ahmed	0:791a779d6220	936	for the image. This requires an extra pass over the data and
shoaib_ahmed	0:791a779d6220	937	therefore costs a good deal of space and time. The default is
shoaib_ahmed	0:791a779d6220	938	FALSE, which tells the compressor to use the supplied or default
shoaib_ahmed	0:791a779d6220	939	Huffman tables. In most cases optimal tables save only a few percent
shoaib_ahmed	0:791a779d6220	940	of file size compared to the default tables. Note that when this is
shoaib_ahmed	0:791a779d6220	941	TRUE, you need not supply Huffman tables at all, and any you do
shoaib_ahmed	0:791a779d6220	942	supply will be overwritten.
shoaib_ahmed	0:791a779d6220	943
shoaib_ahmed	0:791a779d6220	944	unsigned int restart_interval
shoaib_ahmed	0:791a779d6220	945	int restart_in_rows
shoaib_ahmed	0:791a779d6220	946	To emit restart markers in the JPEG file, set one of these nonzero.
shoaib_ahmed	0:791a779d6220	947	Set restart_interval to specify the exact interval in MCU blocks.
shoaib_ahmed	0:791a779d6220	948	Set restart_in_rows to specify the interval in MCU rows. (If
shoaib_ahmed	0:791a779d6220	949	restart_in_rows is not 0, then restart_interval is set after the
shoaib_ahmed	0:791a779d6220	950	image width in MCUs is computed.) Defaults are zero (no restarts).
shoaib_ahmed	0:791a779d6220	951	One restart marker per MCU row is often a good choice.
shoaib_ahmed	0:791a779d6220	952	NOTE: the overhead of restart markers is higher in grayscale JPEG
shoaib_ahmed	0:791a779d6220	953	files than in color files, and MUCH higher in progressive JPEGs.
shoaib_ahmed	0:791a779d6220	954	If you use restarts, you may want to use larger intervals in those
shoaib_ahmed	0:791a779d6220	955	cases.
shoaib_ahmed	0:791a779d6220	956
shoaib_ahmed	0:791a779d6220	957	const jpeg_scan_info * scan_info
shoaib_ahmed	0:791a779d6220	958	int num_scans
shoaib_ahmed	0:791a779d6220	959	By default, scan_info is NULL; this causes the compressor to write a
shoaib_ahmed	0:791a779d6220	960	single-scan sequential JPEG file. If not NULL, scan_info points to
shoaib_ahmed	0:791a779d6220	961	an array of scan definition records of length num_scans. The
shoaib_ahmed	0:791a779d6220	962	compressor will then write a JPEG file having one scan for each scan
shoaib_ahmed	0:791a779d6220	963	definition record. This is used to generate noninterleaved or
shoaib_ahmed	0:791a779d6220	964	progressive JPEG files. The library checks that the scan array
shoaib_ahmed	0:791a779d6220	965	defines a valid JPEG scan sequence. (jpeg_simple_progression creates
shoaib_ahmed	0:791a779d6220	966	a suitable scan definition array for progressive JPEG.) This is
shoaib_ahmed	0:791a779d6220	967	discussed further under "Progressive JPEG support".
shoaib_ahmed	0:791a779d6220	968
shoaib_ahmed	0:791a779d6220	969	boolean do_fancy_downsampling
shoaib_ahmed	0:791a779d6220	970	If TRUE, use direct DCT scaling with DCT size > 8 for downsampling
shoaib_ahmed	0:791a779d6220	971	of chroma components.
shoaib_ahmed	0:791a779d6220	972	If FALSE, use only DCT size <= 8 and simple separate downsampling.
shoaib_ahmed	0:791a779d6220	973	Default is TRUE.
shoaib_ahmed	0:791a779d6220	974	For better image stability in multiple generation compression cycles
shoaib_ahmed	0:791a779d6220	975	it is preferable that this value matches the corresponding
shoaib_ahmed	0:791a779d6220	976	do_fancy_upsampling value in decompression.
shoaib_ahmed	0:791a779d6220	977
shoaib_ahmed	0:791a779d6220	978	int smoothing_factor
shoaib_ahmed	0:791a779d6220	979	If non-zero, the input image is smoothed; the value should be 1 for
shoaib_ahmed	0:791a779d6220	980	minimal smoothing to 100 for maximum smoothing. Consult jcsample.c
shoaib_ahmed	0:791a779d6220	981	for details of the smoothing algorithm. The default is zero.
shoaib_ahmed	0:791a779d6220	982
shoaib_ahmed	0:791a779d6220	983	boolean write_JFIF_header
shoaib_ahmed	0:791a779d6220	984	If TRUE, a JFIF APP0 marker is emitted. jpeg_set_defaults() and
shoaib_ahmed	0:791a779d6220	985	jpeg_set_colorspace() set this TRUE if a JFIF-legal JPEG color space
shoaib_ahmed	0:791a779d6220	986	(ie, YCbCr or grayscale) is selected, otherwise FALSE.
shoaib_ahmed	0:791a779d6220	987
shoaib_ahmed	0:791a779d6220	988	UINT8 JFIF_major_version
shoaib_ahmed	0:791a779d6220	989	UINT8 JFIF_minor_version
shoaib_ahmed	0:791a779d6220	990	The version number to be written into the JFIF marker.
shoaib_ahmed	0:791a779d6220	991	jpeg_set_defaults() initializes the version to 1.01 (major=minor=1).
shoaib_ahmed	0:791a779d6220	992	You should set it to 1.02 (major=1, minor=2) if you plan to write
shoaib_ahmed	0:791a779d6220	993	any JFIF 1.02 extension markers.
shoaib_ahmed	0:791a779d6220	994
shoaib_ahmed	0:791a779d6220	995	UINT8 density_unit
shoaib_ahmed	0:791a779d6220	996	UINT16 X_density
shoaib_ahmed	0:791a779d6220	997	UINT16 Y_density
shoaib_ahmed	0:791a779d6220	998	The resolution information to be written into the JFIF marker;
shoaib_ahmed	0:791a779d6220	999	not used otherwise. density_unit may be 0 for unknown,
shoaib_ahmed	0:791a779d6220	1000	1 for dots/inch, or 2 for dots/cm. The default values are 0,1,1
shoaib_ahmed	0:791a779d6220	1001	indicating square pixels of unknown size.
shoaib_ahmed	0:791a779d6220	1002
shoaib_ahmed	0:791a779d6220	1003	boolean write_Adobe_marker
shoaib_ahmed	0:791a779d6220	1004	If TRUE, an Adobe APP14 marker is emitted. jpeg_set_defaults() and
shoaib_ahmed	0:791a779d6220	1005	jpeg_set_colorspace() set this TRUE if JPEG color space RGB, CMYK,
shoaib_ahmed	0:791a779d6220	1006	or YCCK is selected, otherwise FALSE. It is generally a bad idea
shoaib_ahmed	0:791a779d6220	1007	to set both write_JFIF_header and write_Adobe_marker. In fact,
shoaib_ahmed	0:791a779d6220	1008	you probably shouldn't change the default settings at all --- the
shoaib_ahmed	0:791a779d6220	1009	default behavior ensures that the JPEG file's color space can be
shoaib_ahmed	0:791a779d6220	1010	recognized by the decoder.
shoaib_ahmed	0:791a779d6220	1011
shoaib_ahmed	0:791a779d6220	1012	JQUANT_TBL * quant_tbl_ptrs[NUM_QUANT_TBLS]
shoaib_ahmed	0:791a779d6220	1013	Pointers to coefficient quantization tables, one per table slot,
shoaib_ahmed	0:791a779d6220	1014	or NULL if no table is defined for a slot. Usually these should
shoaib_ahmed	0:791a779d6220	1015	be set via one of the above helper routines; jpeg_add_quant_table()
shoaib_ahmed	0:791a779d6220	1016	is general enough to define any quantization table. The other
shoaib_ahmed	0:791a779d6220	1017	routines will set up table slot 0 for luminance quality and table
shoaib_ahmed	0:791a779d6220	1018	slot 1 for chrominance.
shoaib_ahmed	0:791a779d6220	1019
shoaib_ahmed	0:791a779d6220	1020	int q_scale_factor[NUM_QUANT_TBLS]
shoaib_ahmed	0:791a779d6220	1021	Linear quantization scaling factors (percentage, initialized 100)
shoaib_ahmed	0:791a779d6220	1022	for use with jpeg_default_qtables().
shoaib_ahmed	0:791a779d6220	1023	See rdswitch.c and cjpeg.c for an example of usage.
shoaib_ahmed	0:791a779d6220	1024	Note that the q_scale_factor[] fields are the "linear" scales, so you
shoaib_ahmed	0:791a779d6220	1025	have to convert from user-defined ratings via jpeg_quality_scaling().
shoaib_ahmed	0:791a779d6220	1026	Here is an example code which corresponds to cjpeg -quality 90,70:
shoaib_ahmed	0:791a779d6220	1027
shoaib_ahmed	0:791a779d6220	1028	jpeg_set_defaults(cinfo);
shoaib_ahmed	0:791a779d6220	1029
shoaib_ahmed	0:791a779d6220	1030	/* Set luminance quality 90. */
shoaib_ahmed	0:791a779d6220	1031	cinfo->q_scale_factor[0] = jpeg_quality_scaling(90);
shoaib_ahmed	0:791a779d6220	1032	/* Set chrominance quality 70. */
shoaib_ahmed	0:791a779d6220	1033	cinfo->q_scale_factor[1] = jpeg_quality_scaling(70);
shoaib_ahmed	0:791a779d6220	1034
shoaib_ahmed	0:791a779d6220	1035	jpeg_default_qtables(cinfo, force_baseline);
shoaib_ahmed	0:791a779d6220	1036
shoaib_ahmed	0:791a779d6220	1037	CAUTION: You must also set 1x1 subsampling for efficient separate
shoaib_ahmed	0:791a779d6220	1038	color quality selection, since the default value used by library
shoaib_ahmed	0:791a779d6220	1039	is 2x2:
shoaib_ahmed	0:791a779d6220	1040
shoaib_ahmed	0:791a779d6220	1041	cinfo->comp_info[0].v_samp_factor = 1;
shoaib_ahmed	0:791a779d6220	1042	cinfo->comp_info[0].h_samp_factor = 1;
shoaib_ahmed	0:791a779d6220	1043
shoaib_ahmed	0:791a779d6220	1044	JHUFF_TBL * dc_huff_tbl_ptrs[NUM_HUFF_TBLS]
shoaib_ahmed	0:791a779d6220	1045	JHUFF_TBL * ac_huff_tbl_ptrs[NUM_HUFF_TBLS]
shoaib_ahmed	0:791a779d6220	1046	Pointers to Huffman coding tables, one per table slot, or NULL if
shoaib_ahmed	0:791a779d6220	1047	no table is defined for a slot. Slots 0 and 1 are filled with the
shoaib_ahmed	0:791a779d6220	1048	JPEG sample tables by jpeg_set_defaults(). If you need to allocate
shoaib_ahmed	0:791a779d6220	1049	more table structures, jpeg_alloc_huff_table() may be used.
shoaib_ahmed	0:791a779d6220	1050	Note that optimal Huffman tables can be computed for an image
shoaib_ahmed	0:791a779d6220	1051	by setting optimize_coding, as discussed above; there's seldom
shoaib_ahmed	0:791a779d6220	1052	any need to mess with providing your own Huffman tables.
shoaib_ahmed	0:791a779d6220	1053
shoaib_ahmed	0:791a779d6220	1054
shoaib_ahmed	0:791a779d6220	1055	The actual dimensions of the JPEG image that will be written to the file are
shoaib_ahmed	0:791a779d6220	1056	given by the following fields. These are computed from the input image
shoaib_ahmed	0:791a779d6220	1057	dimensions and the compression parameters by jpeg_start_compress(). You can
shoaib_ahmed	0:791a779d6220	1058	also call jpeg_calc_jpeg_dimensions() to obtain the values that will result
shoaib_ahmed	0:791a779d6220	1059	from the current parameter settings. This can be useful if you are trying
shoaib_ahmed	0:791a779d6220	1060	to pick a scaling ratio that will get close to a desired target size.
shoaib_ahmed	0:791a779d6220	1061
shoaib_ahmed	0:791a779d6220	1062	JDIMENSION jpeg_width Actual dimensions of output image.
shoaib_ahmed	0:791a779d6220	1063	JDIMENSION jpeg_height
shoaib_ahmed	0:791a779d6220	1064
shoaib_ahmed	0:791a779d6220	1065
shoaib_ahmed	0:791a779d6220	1066	Per-component parameters are stored in the struct cinfo.comp_info[i] for
shoaib_ahmed	0:791a779d6220	1067	component number i. Note that components here refer to components of the
shoaib_ahmed	0:791a779d6220	1068	JPEG color space, not the source image color space. A suitably large
shoaib_ahmed	0:791a779d6220	1069	comp_info[] array is allocated by jpeg_set_defaults(); if you choose not
shoaib_ahmed	0:791a779d6220	1070	to use that routine, it's up to you to allocate the array.
shoaib_ahmed	0:791a779d6220	1071
shoaib_ahmed	0:791a779d6220	1072	int component_id
shoaib_ahmed	0:791a779d6220	1073	The one-byte identifier code to be recorded in the JPEG file for
shoaib_ahmed	0:791a779d6220	1074	this component. For the standard color spaces, we recommend you
shoaib_ahmed	0:791a779d6220	1075	leave the default values alone.
shoaib_ahmed	0:791a779d6220	1076
shoaib_ahmed	0:791a779d6220	1077	int h_samp_factor
shoaib_ahmed	0:791a779d6220	1078	int v_samp_factor
shoaib_ahmed	0:791a779d6220	1079	Horizontal and vertical sampling factors for the component; must
shoaib_ahmed	0:791a779d6220	1080	be 1..4 according to the JPEG standard. Note that larger sampling
shoaib_ahmed	0:791a779d6220	1081	factors indicate a higher-resolution component; many people find
shoaib_ahmed	0:791a779d6220	1082	this behavior quite unintuitive. The default values are 2,2 for
shoaib_ahmed	0:791a779d6220	1083	luminance components and 1,1 for chrominance components, except
shoaib_ahmed	0:791a779d6220	1084	for grayscale where 1,1 is used.
shoaib_ahmed	0:791a779d6220	1085
shoaib_ahmed	0:791a779d6220	1086	int quant_tbl_no
shoaib_ahmed	0:791a779d6220	1087	Quantization table number for component. The default value is
shoaib_ahmed	0:791a779d6220	1088	0 for luminance components and 1 for chrominance components.
shoaib_ahmed	0:791a779d6220	1089
shoaib_ahmed	0:791a779d6220	1090	int dc_tbl_no
shoaib_ahmed	0:791a779d6220	1091	int ac_tbl_no
shoaib_ahmed	0:791a779d6220	1092	DC and AC entropy coding table numbers. The default values are
shoaib_ahmed	0:791a779d6220	1093	0 for luminance components and 1 for chrominance components.
shoaib_ahmed	0:791a779d6220	1094
shoaib_ahmed	0:791a779d6220	1095	int component_index
shoaib_ahmed	0:791a779d6220	1096	Must equal the component's index in comp_info[]. (Beginning in
shoaib_ahmed	0:791a779d6220	1097	release v6, the compressor library will fill this in automatically;
shoaib_ahmed	0:791a779d6220	1098	you don't have to.)
shoaib_ahmed	0:791a779d6220	1099
shoaib_ahmed	0:791a779d6220	1100
shoaib_ahmed	0:791a779d6220	1101	Decompression parameter selection
shoaib_ahmed	0:791a779d6220	1102	---------------------------------
shoaib_ahmed	0:791a779d6220	1103
shoaib_ahmed	0:791a779d6220	1104	Decompression parameter selection is somewhat simpler than compression
shoaib_ahmed	0:791a779d6220	1105	parameter selection, since all of the JPEG internal parameters are
shoaib_ahmed	0:791a779d6220	1106	recorded in the source file and need not be supplied by the application.
shoaib_ahmed	0:791a779d6220	1107	(Unless you are working with abbreviated files, in which case see
shoaib_ahmed	0:791a779d6220	1108	"Abbreviated datastreams", below.) Decompression parameters control
shoaib_ahmed	0:791a779d6220	1109	the postprocessing done on the image to deliver it in a format suitable
shoaib_ahmed	0:791a779d6220	1110	for the application's use. Many of the parameters control speed/quality
shoaib_ahmed	0:791a779d6220	1111	tradeoffs, in which faster decompression may be obtained at the price of
shoaib_ahmed	0:791a779d6220	1112	a poorer-quality image. The defaults select the highest quality (slowest)
shoaib_ahmed	0:791a779d6220	1113	processing.
shoaib_ahmed	0:791a779d6220	1114
shoaib_ahmed	0:791a779d6220	1115	The following fields in the JPEG object are set by jpeg_read_header() and
shoaib_ahmed	0:791a779d6220	1116	may be useful to the application in choosing decompression parameters:
shoaib_ahmed	0:791a779d6220	1117
shoaib_ahmed	0:791a779d6220	1118	JDIMENSION image_width Width and height of image
shoaib_ahmed	0:791a779d6220	1119	JDIMENSION image_height
shoaib_ahmed	0:791a779d6220	1120	int num_components Number of color components
shoaib_ahmed	0:791a779d6220	1121	J_COLOR_SPACE jpeg_color_space Colorspace of image
shoaib_ahmed	0:791a779d6220	1122	boolean saw_JFIF_marker TRUE if a JFIF APP0 marker was seen
shoaib_ahmed	0:791a779d6220	1123	UINT8 JFIF_major_version Version information from JFIF marker
shoaib_ahmed	0:791a779d6220	1124	UINT8 JFIF_minor_version
shoaib_ahmed	0:791a779d6220	1125	UINT8 density_unit Resolution data from JFIF marker
shoaib_ahmed	0:791a779d6220	1126	UINT16 X_density
shoaib_ahmed	0:791a779d6220	1127	UINT16 Y_density
shoaib_ahmed	0:791a779d6220	1128	boolean saw_Adobe_marker TRUE if an Adobe APP14 marker was seen
shoaib_ahmed	0:791a779d6220	1129	UINT8 Adobe_transform Color transform code from Adobe marker
shoaib_ahmed	0:791a779d6220	1130
shoaib_ahmed	0:791a779d6220	1131	The JPEG color space, unfortunately, is something of a guess since the JPEG
shoaib_ahmed	0:791a779d6220	1132	standard proper does not provide a way to record it. In practice most files
shoaib_ahmed	0:791a779d6220	1133	adhere to the JFIF or Adobe conventions, and the decoder will recognize these
shoaib_ahmed	0:791a779d6220	1134	correctly. See "Special color spaces", below, for more info.
shoaib_ahmed	0:791a779d6220	1135
shoaib_ahmed	0:791a779d6220	1136
shoaib_ahmed	0:791a779d6220	1137	The decompression parameters that determine the basic properties of the
shoaib_ahmed	0:791a779d6220	1138	returned image are:
shoaib_ahmed	0:791a779d6220	1139
shoaib_ahmed	0:791a779d6220	1140	J_COLOR_SPACE out_color_space
shoaib_ahmed	0:791a779d6220	1141	Output color space. jpeg_read_header() sets an appropriate default
shoaib_ahmed	0:791a779d6220	1142	based on jpeg_color_space; typically it will be RGB or grayscale.
shoaib_ahmed	0:791a779d6220	1143	The application can change this field to request output in a different
shoaib_ahmed	0:791a779d6220	1144	colorspace. For example, set it to JCS_GRAYSCALE to get grayscale
shoaib_ahmed	0:791a779d6220	1145	output from a color file. (This is useful for previewing: grayscale
shoaib_ahmed	0:791a779d6220	1146	output is faster than full color since the color components need not
shoaib_ahmed	0:791a779d6220	1147	be processed.) Note that not all possible color space transforms are
shoaib_ahmed	0:791a779d6220	1148	currently implemented; you may need to extend jdcolor.c if you want an
shoaib_ahmed	0:791a779d6220	1149	unusual conversion.
shoaib_ahmed	0:791a779d6220	1150
shoaib_ahmed	0:791a779d6220	1151	unsigned int scale_num, scale_denom
shoaib_ahmed	0:791a779d6220	1152	Scale the image by the fraction scale_num/scale_denom. Currently,
shoaib_ahmed	0:791a779d6220	1153	the supported scaling ratios are M/N with all M from 1 to 16, where
shoaib_ahmed	0:791a779d6220	1154	N is the source DCT size, which is 8 for baseline JPEG. (The library
shoaib_ahmed	0:791a779d6220	1155	design allows for arbitrary scaling ratios but this is not likely
shoaib_ahmed	0:791a779d6220	1156	to be implemented any time soon.) The values are initialized by
shoaib_ahmed	0:791a779d6220	1157	jpeg_read_header() with the source DCT size. For baseline JPEG
shoaib_ahmed	0:791a779d6220	1158	this is 8/8. If you change only the scale_num value while leaving
shoaib_ahmed	0:791a779d6220	1159	the other unchanged, then this specifies the DCT scaled size to be
shoaib_ahmed	0:791a779d6220	1160	applied on the given input. For baseline JPEG this is equivalent
shoaib_ahmed	0:791a779d6220	1161	to M/8 scaling, since the source DCT size for baseline JPEG is 8.
shoaib_ahmed	0:791a779d6220	1162	Smaller scaling ratios permit significantly faster decoding since
shoaib_ahmed	0:791a779d6220	1163	fewer pixels need be processed and a simpler IDCT method can be used.
shoaib_ahmed	0:791a779d6220	1164
shoaib_ahmed	0:791a779d6220	1165	boolean quantize_colors
shoaib_ahmed	0:791a779d6220	1166	If set TRUE, colormapped output will be delivered. Default is FALSE,
shoaib_ahmed	0:791a779d6220	1167	meaning that full-color output will be delivered.
shoaib_ahmed	0:791a779d6220	1168
shoaib_ahmed	0:791a779d6220	1169	The next three parameters are relevant only if quantize_colors is TRUE.
shoaib_ahmed	0:791a779d6220	1170
shoaib_ahmed	0:791a779d6220	1171	int desired_number_of_colors
shoaib_ahmed	0:791a779d6220	1172	Maximum number of colors to use in generating a library-supplied color
shoaib_ahmed	0:791a779d6220	1173	map (the actual number of colors is returned in a different field).
shoaib_ahmed	0:791a779d6220	1174	Default 256. Ignored when the application supplies its own color map.
shoaib_ahmed	0:791a779d6220	1175
shoaib_ahmed	0:791a779d6220	1176	boolean two_pass_quantize
shoaib_ahmed	0:791a779d6220	1177	If TRUE, an extra pass over the image is made to select a custom color
shoaib_ahmed	0:791a779d6220	1178	map for the image. This usually looks a lot better than the one-size-
shoaib_ahmed	0:791a779d6220	1179	fits-all colormap that is used otherwise. Default is TRUE. Ignored
shoaib_ahmed	0:791a779d6220	1180	when the application supplies its own color map.
shoaib_ahmed	0:791a779d6220	1181
shoaib_ahmed	0:791a779d6220	1182	J_DITHER_MODE dither_mode
shoaib_ahmed	0:791a779d6220	1183	Selects color dithering method. Supported values are:
shoaib_ahmed	0:791a779d6220	1184	JDITHER_NONE no dithering: fast, very low quality
shoaib_ahmed	0:791a779d6220	1185	JDITHER_ORDERED ordered dither: moderate speed and quality
shoaib_ahmed	0:791a779d6220	1186	JDITHER_FS Floyd-Steinberg dither: slow, high quality
shoaib_ahmed	0:791a779d6220	1187	Default is JDITHER_FS. (At present, ordered dither is implemented
shoaib_ahmed	0:791a779d6220	1188	only in the single-pass, standard-colormap case. If you ask for
shoaib_ahmed	0:791a779d6220	1189	ordered dither when two_pass_quantize is TRUE or when you supply
shoaib_ahmed	0:791a779d6220	1190	an external color map, you'll get F-S dithering.)
shoaib_ahmed	0:791a779d6220	1191
shoaib_ahmed	0:791a779d6220	1192	When quantize_colors is TRUE, the target color map is described by the next
shoaib_ahmed	0:791a779d6220	1193	two fields. colormap is set to NULL by jpeg_read_header(). The application
shoaib_ahmed	0:791a779d6220	1194	can supply a color map by setting colormap non-NULL and setting
shoaib_ahmed	0:791a779d6220	1195	actual_number_of_colors to the map size. Otherwise, jpeg_start_decompress()
shoaib_ahmed	0:791a779d6220	1196	selects a suitable color map and sets these two fields itself.
shoaib_ahmed	0:791a779d6220	1197	[Implementation restriction: at present, an externally supplied colormap is
shoaib_ahmed	0:791a779d6220	1198	only accepted for 3-component output color spaces.]
shoaib_ahmed	0:791a779d6220	1199
shoaib_ahmed	0:791a779d6220	1200	JSAMPARRAY colormap
shoaib_ahmed	0:791a779d6220	1201	The color map, represented as a 2-D pixel array of out_color_components
shoaib_ahmed	0:791a779d6220	1202	rows and actual_number_of_colors columns. Ignored if not quantizing.
shoaib_ahmed	0:791a779d6220	1203	CAUTION: if the JPEG library creates its own colormap, the storage
shoaib_ahmed	0:791a779d6220	1204	pointed to by this field is released by jpeg_finish_decompress().
shoaib_ahmed	0:791a779d6220	1205	Copy the colormap somewhere else first, if you want to save it.
shoaib_ahmed	0:791a779d6220	1206
shoaib_ahmed	0:791a779d6220	1207	int actual_number_of_colors
shoaib_ahmed	0:791a779d6220	1208	The number of colors in the color map.
shoaib_ahmed	0:791a779d6220	1209
shoaib_ahmed	0:791a779d6220	1210	Additional decompression parameters that the application may set include:
shoaib_ahmed	0:791a779d6220	1211
shoaib_ahmed	0:791a779d6220	1212	J_DCT_METHOD dct_method
shoaib_ahmed	0:791a779d6220	1213	Selects the algorithm used for the DCT step. Choices are the same
shoaib_ahmed	0:791a779d6220	1214	as described above for compression.
shoaib_ahmed	0:791a779d6220	1215
shoaib_ahmed	0:791a779d6220	1216	boolean do_fancy_upsampling
shoaib_ahmed	0:791a779d6220	1217	If TRUE, use direct DCT scaling with DCT size > 8 for upsampling
shoaib_ahmed	0:791a779d6220	1218	of chroma components.
shoaib_ahmed	0:791a779d6220	1219	If FALSE, use only DCT size <= 8 and simple separate upsampling.
shoaib_ahmed	0:791a779d6220	1220	Default is TRUE.
shoaib_ahmed	0:791a779d6220	1221	For better image stability in multiple generation compression cycles
shoaib_ahmed	0:791a779d6220	1222	it is preferable that this value matches the corresponding
shoaib_ahmed	0:791a779d6220	1223	do_fancy_downsampling value in compression.
shoaib_ahmed	0:791a779d6220	1224
shoaib_ahmed	0:791a779d6220	1225	boolean do_block_smoothing
shoaib_ahmed	0:791a779d6220	1226	If TRUE, interblock smoothing is applied in early stages of decoding
shoaib_ahmed	0:791a779d6220	1227	progressive JPEG files; if FALSE, not. Default is TRUE. Early
shoaib_ahmed	0:791a779d6220	1228	progression stages look "fuzzy" with smoothing, "blocky" without.
shoaib_ahmed	0:791a779d6220	1229	In any case, block smoothing ceases to be applied after the first few
shoaib_ahmed	0:791a779d6220	1230	AC coefficients are known to full accuracy, so it is relevant only
shoaib_ahmed	0:791a779d6220	1231	when using buffered-image mode for progressive images.
shoaib_ahmed	0:791a779d6220	1232
shoaib_ahmed	0:791a779d6220	1233	boolean enable_1pass_quant
shoaib_ahmed	0:791a779d6220	1234	boolean enable_external_quant
shoaib_ahmed	0:791a779d6220	1235	boolean enable_2pass_quant
shoaib_ahmed	0:791a779d6220	1236	These are significant only in buffered-image mode, which is
shoaib_ahmed	0:791a779d6220	1237	described in its own section below.
shoaib_ahmed	0:791a779d6220	1238
shoaib_ahmed	0:791a779d6220	1239
shoaib_ahmed	0:791a779d6220	1240	The output image dimensions are given by the following fields. These are
shoaib_ahmed	0:791a779d6220	1241	computed from the source image dimensions and the decompression parameters
shoaib_ahmed	0:791a779d6220	1242	by jpeg_start_decompress(). You can also call jpeg_calc_output_dimensions()
shoaib_ahmed	0:791a779d6220	1243	to obtain the values that will result from the current parameter settings.
shoaib_ahmed	0:791a779d6220	1244	This can be useful if you are trying to pick a scaling ratio that will get
shoaib_ahmed	0:791a779d6220	1245	close to a desired target size. It's also important if you are using the
shoaib_ahmed	0:791a779d6220	1246	JPEG library's memory manager to allocate output buffer space, because you
shoaib_ahmed	0:791a779d6220	1247	are supposed to request such buffers before jpeg_start_decompress().
shoaib_ahmed	0:791a779d6220	1248
shoaib_ahmed	0:791a779d6220	1249	JDIMENSION output_width Actual dimensions of output image.
shoaib_ahmed	0:791a779d6220	1250	JDIMENSION output_height
shoaib_ahmed	0:791a779d6220	1251	int out_color_components Number of color components in out_color_space.
shoaib_ahmed	0:791a779d6220	1252	int output_components Number of color components returned.
shoaib_ahmed	0:791a779d6220	1253	int rec_outbuf_height Recommended height of scanline buffer.
shoaib_ahmed	0:791a779d6220	1254
shoaib_ahmed	0:791a779d6220	1255	When quantizing colors, output_components is 1, indicating a single color map
shoaib_ahmed	0:791a779d6220	1256	index per pixel. Otherwise it equals out_color_components. The output arrays
shoaib_ahmed	0:791a779d6220	1257	are required to be output_width * output_components JSAMPLEs wide.
shoaib_ahmed	0:791a779d6220	1258
shoaib_ahmed	0:791a779d6220	1259	rec_outbuf_height is the recommended minimum height (in scanlines) of the
shoaib_ahmed	0:791a779d6220	1260	buffer passed to jpeg_read_scanlines(). If the buffer is smaller, the
shoaib_ahmed	0:791a779d6220	1261	library will still work, but time will be wasted due to unnecessary data
shoaib_ahmed	0:791a779d6220	1262	copying. In high-quality modes, rec_outbuf_height is always 1, but some
shoaib_ahmed	0:791a779d6220	1263	faster, lower-quality modes set it to larger values (typically 2 to 4).
shoaib_ahmed	0:791a779d6220	1264	If you are going to ask for a high-speed processing mode, you may as well
shoaib_ahmed	0:791a779d6220	1265	go to the trouble of honoring rec_outbuf_height so as to avoid data copying.
shoaib_ahmed	0:791a779d6220	1266	(An output buffer larger than rec_outbuf_height lines is OK, but won't
shoaib_ahmed	0:791a779d6220	1267	provide any material speed improvement over that height.)
shoaib_ahmed	0:791a779d6220	1268
shoaib_ahmed	0:791a779d6220	1269
shoaib_ahmed	0:791a779d6220	1270	Special color spaces
shoaib_ahmed	0:791a779d6220	1271	--------------------
shoaib_ahmed	0:791a779d6220	1272
shoaib_ahmed	0:791a779d6220	1273	The JPEG standard itself is "color blind" and doesn't specify any particular
shoaib_ahmed	0:791a779d6220	1274	color space. It is customary to convert color data to a luminance/chrominance
shoaib_ahmed	0:791a779d6220	1275	color space before compressing, since this permits greater compression. The
shoaib_ahmed	0:791a779d6220	1276	existing JPEG file interchange format standards specify YCbCr or GRAYSCALE
shoaib_ahmed	0:791a779d6220	1277	data (JFIF version 1), GRAYSCALE, RGB, YCbCr, CMYK, or YCCK (Adobe), or BG_RGB
shoaib_ahmed	0:791a779d6220	1278	or BG_YCC (big gamut color spaces, JFIF version 2). For special applications
shoaib_ahmed	0:791a779d6220	1279	such as multispectral images, other color spaces can be used,
shoaib_ahmed	0:791a779d6220	1280	but it must be understood that such files will be unportable.
shoaib_ahmed	0:791a779d6220	1281
shoaib_ahmed	0:791a779d6220	1282	The JPEG library can handle the most common colorspace conversions (namely
shoaib_ahmed	0:791a779d6220	1283	RGB <=> YCbCr and CMYK <=> YCCK). It can also deal with data of an unknown
shoaib_ahmed	0:791a779d6220	1284	color space, passing it through without conversion. If you deal extensively
shoaib_ahmed	0:791a779d6220	1285	with an unusual color space, you can easily extend the library to understand
shoaib_ahmed	0:791a779d6220	1286	additional color spaces and perform appropriate conversions.
shoaib_ahmed	0:791a779d6220	1287
shoaib_ahmed	0:791a779d6220	1288	For compression, the source data's color space is specified by field
shoaib_ahmed	0:791a779d6220	1289	in_color_space. This is transformed to the JPEG file's color space given
shoaib_ahmed	0:791a779d6220	1290	by jpeg_color_space. jpeg_set_defaults() chooses a reasonable JPEG color
shoaib_ahmed	0:791a779d6220	1291	space depending on in_color_space, but you can override this by calling
shoaib_ahmed	0:791a779d6220	1292	jpeg_set_colorspace(). Of course you must select a supported transformation.
shoaib_ahmed	0:791a779d6220	1293	jccolor.c currently supports the following transformations:
shoaib_ahmed	0:791a779d6220	1294	RGB => YCbCr
shoaib_ahmed	0:791a779d6220	1295	RGB => GRAYSCALE
shoaib_ahmed	0:791a779d6220	1296	RGB => BG_YCC
shoaib_ahmed	0:791a779d6220	1297	YCbCr => GRAYSCALE
shoaib_ahmed	0:791a779d6220	1298	YCbCr => BG_YCC
shoaib_ahmed	0:791a779d6220	1299	CMYK => YCCK
shoaib_ahmed	0:791a779d6220	1300	plus the null transforms: GRAYSCALE => GRAYSCALE, RGB => RGB,
shoaib_ahmed	0:791a779d6220	1301	BG_RGB => BG_RGB, YCbCr => YCbCr, BG_YCC => BG_YCC, CMYK => CMYK,
shoaib_ahmed	0:791a779d6220	1302	YCCK => YCCK, and UNKNOWN => UNKNOWN.
shoaib_ahmed	0:791a779d6220	1303
shoaib_ahmed	0:791a779d6220	1304	The file interchange format standards (JFIF and Adobe) specify APPn markers
shoaib_ahmed	0:791a779d6220	1305	that indicate the color space of the JPEG file. It is important to ensure
shoaib_ahmed	0:791a779d6220	1306	that these are written correctly, or omitted if the JPEG file's color space
shoaib_ahmed	0:791a779d6220	1307	is not one of the ones supported by the interchange standards.
shoaib_ahmed	0:791a779d6220	1308	jpeg_set_colorspace() will set the compression parameters to include or omit
shoaib_ahmed	0:791a779d6220	1309	the APPn markers properly, so long as it is told the truth about the JPEG
shoaib_ahmed	0:791a779d6220	1310	color space. For example, if you are writing some random 3-component color
shoaib_ahmed	0:791a779d6220	1311	space without conversion, don't try to fake out the library by setting
shoaib_ahmed	0:791a779d6220	1312	in_color_space and jpeg_color_space to JCS_YCbCr; use JCS_UNKNOWN.
shoaib_ahmed	0:791a779d6220	1313	You may want to write an APPn marker of your own devising to identify
shoaib_ahmed	0:791a779d6220	1314	the colorspace --- see "Special markers", below.
shoaib_ahmed	0:791a779d6220	1315
shoaib_ahmed	0:791a779d6220	1316	When told that the color space is UNKNOWN, the library will default to using
shoaib_ahmed	0:791a779d6220	1317	luminance-quality compression parameters for all color components. You may
shoaib_ahmed	0:791a779d6220	1318	well want to change these parameters. See the source code for
shoaib_ahmed	0:791a779d6220	1319	jpeg_set_colorspace(), in jcparam.c, for details.
shoaib_ahmed	0:791a779d6220	1320
shoaib_ahmed	0:791a779d6220	1321	For decompression, the JPEG file's color space is given in jpeg_color_space,
shoaib_ahmed	0:791a779d6220	1322	and this is transformed to the output color space out_color_space.
shoaib_ahmed	0:791a779d6220	1323	jpeg_read_header's setting of jpeg_color_space can be relied on if the file
shoaib_ahmed	0:791a779d6220	1324	conforms to JFIF or Adobe conventions, but otherwise it is no better than a
shoaib_ahmed	0:791a779d6220	1325	guess. If you know the JPEG file's color space for certain, you can override
shoaib_ahmed	0:791a779d6220	1326	jpeg_read_header's guess by setting jpeg_color_space. jpeg_read_header also
shoaib_ahmed	0:791a779d6220	1327	selects a default output color space based on (its guess of) jpeg_color_space;
shoaib_ahmed	0:791a779d6220	1328	set out_color_space to override this. Again, you must select a supported
shoaib_ahmed	0:791a779d6220	1329	transformation. jdcolor.c currently supports
shoaib_ahmed	0:791a779d6220	1330	YCbCr => RGB
shoaib_ahmed	0:791a779d6220	1331	YCbCr => GRAYSCALE
shoaib_ahmed	0:791a779d6220	1332	BG_YCC => RGB
shoaib_ahmed	0:791a779d6220	1333	BG_YCC => GRAYSCALE
shoaib_ahmed	0:791a779d6220	1334	RGB => GRAYSCALE
shoaib_ahmed	0:791a779d6220	1335	GRAYSCALE => RGB
shoaib_ahmed	0:791a779d6220	1336	YCCK => CMYK
shoaib_ahmed	0:791a779d6220	1337	as well as the null transforms. (Since GRAYSCALE=>RGB is provided, an
shoaib_ahmed	0:791a779d6220	1338	application can force grayscale JPEGs to look like color JPEGs if it only
shoaib_ahmed	0:791a779d6220	1339	wants to handle one case.)
shoaib_ahmed	0:791a779d6220	1340
shoaib_ahmed	0:791a779d6220	1341	The two-pass color quantizer, jquant2.c, is specialized to handle RGB data
shoaib_ahmed	0:791a779d6220	1342	(it weights distances appropriately for RGB colors). You'll need to modify
shoaib_ahmed	0:791a779d6220	1343	the code if you want to use it for non-RGB output color spaces. Note that
shoaib_ahmed	0:791a779d6220	1344	jquant2.c is used to map to an application-supplied colormap as well as for
shoaib_ahmed	0:791a779d6220	1345	the normal two-pass colormap selection process.
shoaib_ahmed	0:791a779d6220	1346
shoaib_ahmed	0:791a779d6220	1347	CAUTION: it appears that Adobe Photoshop writes inverted data in CMYK JPEG
shoaib_ahmed	0:791a779d6220	1348	files: 0 represents 100% ink coverage, rather than 0% ink as you'd expect.
shoaib_ahmed	0:791a779d6220	1349	This is arguably a bug in Photoshop, but if you need to work with Photoshop
shoaib_ahmed	0:791a779d6220	1350	CMYK files, you will have to deal with it in your application. We cannot
shoaib_ahmed	0:791a779d6220	1351	"fix" this in the library by inverting the data during the CMYK<=>YCCK
shoaib_ahmed	0:791a779d6220	1352	transform, because that would break other applications, notably Ghostscript.
shoaib_ahmed	0:791a779d6220	1353	Photoshop versions prior to 3.0 write EPS files containing JPEG-encoded CMYK
shoaib_ahmed	0:791a779d6220	1354	data in the same inverted-YCCK representation used in bare JPEG files, but
shoaib_ahmed	0:791a779d6220	1355	the surrounding PostScript code performs an inversion using the PS image
shoaib_ahmed	0:791a779d6220	1356	operator. I am told that Photoshop 3.0 will write uninverted YCCK in
shoaib_ahmed	0:791a779d6220	1357	EPS/JPEG files, and will omit the PS-level inversion. (But the data
shoaib_ahmed	0:791a779d6220	1358	polarity used in bare JPEG files will not change in 3.0.) In either case,
shoaib_ahmed	0:791a779d6220	1359	the JPEG library must not invert the data itself, or else Ghostscript would
shoaib_ahmed	0:791a779d6220	1360	read these EPS files incorrectly.
shoaib_ahmed	0:791a779d6220	1361
shoaib_ahmed	0:791a779d6220	1362
shoaib_ahmed	0:791a779d6220	1363	Error handling
shoaib_ahmed	0:791a779d6220	1364	--------------
shoaib_ahmed	0:791a779d6220	1365
shoaib_ahmed	0:791a779d6220	1366	When the default error handler is used, any error detected inside the JPEG
shoaib_ahmed	0:791a779d6220	1367	routines will cause a message to be printed on stderr, followed by exit().
shoaib_ahmed	0:791a779d6220	1368	You can supply your own error handling routines to override this behavior
shoaib_ahmed	0:791a779d6220	1369	and to control the treatment of nonfatal warnings and trace/debug messages.
shoaib_ahmed	0:791a779d6220	1370	The file example.c illustrates the most common case, which is to have the
shoaib_ahmed	0:791a779d6220	1371	application regain control after an error rather than exiting.
shoaib_ahmed	0:791a779d6220	1372
shoaib_ahmed	0:791a779d6220	1373	The JPEG library never writes any message directly; it always goes through
shoaib_ahmed	0:791a779d6220	1374	the error handling routines. Three classes of messages are recognized:
shoaib_ahmed	0:791a779d6220	1375	* Fatal errors: the library cannot continue.
shoaib_ahmed	0:791a779d6220	1376	* Warnings: the library can continue, but the data is corrupt, and a
shoaib_ahmed	0:791a779d6220	1377	damaged output image is likely to result.
shoaib_ahmed	0:791a779d6220	1378	* Trace/informational messages. These come with a trace level indicating
shoaib_ahmed	0:791a779d6220	1379	the importance of the message; you can control the verbosity of the
shoaib_ahmed	0:791a779d6220	1380	program by adjusting the maximum trace level that will be displayed.
shoaib_ahmed	0:791a779d6220	1381
shoaib_ahmed	0:791a779d6220	1382	You may, if you wish, simply replace the entire JPEG error handling module
shoaib_ahmed	0:791a779d6220	1383	(jerror.c) with your own code. However, you can avoid code duplication by
shoaib_ahmed	0:791a779d6220	1384	only replacing some of the routines depending on the behavior you need.
shoaib_ahmed	0:791a779d6220	1385	This is accomplished by calling jpeg_std_error() as usual, but then overriding
shoaib_ahmed	0:791a779d6220	1386	some of the method pointers in the jpeg_error_mgr struct, as illustrated by
shoaib_ahmed	0:791a779d6220	1387	example.c.
shoaib_ahmed	0:791a779d6220	1388
shoaib_ahmed	0:791a779d6220	1389	All of the error handling routines will receive a pointer to the JPEG object
shoaib_ahmed	0:791a779d6220	1390	(a j_common_ptr which points to either a jpeg_compress_struct or a
shoaib_ahmed	0:791a779d6220	1391	jpeg_decompress_struct; if you need to tell which, test the is_decompressor
shoaib_ahmed	0:791a779d6220	1392	field). This struct includes a pointer to the error manager struct in its
shoaib_ahmed	0:791a779d6220	1393	"err" field. Frequently, custom error handler routines will need to access
shoaib_ahmed	0:791a779d6220	1394	additional data which is not known to the JPEG library or the standard error
shoaib_ahmed	0:791a779d6220	1395	handler. The most convenient way to do this is to embed either the JPEG
shoaib_ahmed	0:791a779d6220	1396	object or the jpeg_error_mgr struct in a larger structure that contains
shoaib_ahmed	0:791a779d6220	1397	additional fields; then casting the passed pointer provides access to the
shoaib_ahmed	0:791a779d6220	1398	additional fields. Again, see example.c for one way to do it. (Beginning
shoaib_ahmed	0:791a779d6220	1399	with IJG version 6b, there is also a void pointer "client_data" in each
shoaib_ahmed	0:791a779d6220	1400	JPEG object, which the application can also use to find related data.
shoaib_ahmed	0:791a779d6220	1401	The library does not touch client_data at all.)
shoaib_ahmed	0:791a779d6220	1402
shoaib_ahmed	0:791a779d6220	1403	The individual methods that you might wish to override are:
shoaib_ahmed	0:791a779d6220	1404
shoaib_ahmed	0:791a779d6220	1405	error_exit (j_common_ptr cinfo)
shoaib_ahmed	0:791a779d6220	1406	Receives control for a fatal error. Information sufficient to
shoaib_ahmed	0:791a779d6220	1407	generate the error message has been stored in cinfo->err; call
shoaib_ahmed	0:791a779d6220	1408	output_message to display it. Control must NOT return to the caller;
shoaib_ahmed	0:791a779d6220	1409	generally this routine will exit() or longjmp() somewhere.
shoaib_ahmed	0:791a779d6220	1410	Typically you would override this routine to get rid of the exit()
shoaib_ahmed	0:791a779d6220	1411	default behavior. Note that if you continue processing, you should
shoaib_ahmed	0:791a779d6220	1412	clean up the JPEG object with jpeg_abort() or jpeg_destroy().
shoaib_ahmed	0:791a779d6220	1413
shoaib_ahmed	0:791a779d6220	1414	output_message (j_common_ptr cinfo)
shoaib_ahmed	0:791a779d6220	1415	Actual output of any JPEG message. Override this to send messages
shoaib_ahmed	0:791a779d6220	1416	somewhere other than stderr. Note that this method does not know
shoaib_ahmed	0:791a779d6220	1417	how to generate a message, only where to send it.
shoaib_ahmed	0:791a779d6220	1418
shoaib_ahmed	0:791a779d6220	1419	format_message (j_common_ptr cinfo, char * buffer)
shoaib_ahmed	0:791a779d6220	1420	Constructs a readable error message string based on the error info
shoaib_ahmed	0:791a779d6220	1421	stored in cinfo->err. This method is called by output_message. Few
shoaib_ahmed	0:791a779d6220	1422	applications should need to override this method. One possible
shoaib_ahmed	0:791a779d6220	1423	reason for doing so is to implement dynamic switching of error message
shoaib_ahmed	0:791a779d6220	1424	language.
shoaib_ahmed	0:791a779d6220	1425
shoaib_ahmed	0:791a779d6220	1426	emit_message (j_common_ptr cinfo, int msg_level)
shoaib_ahmed	0:791a779d6220	1427	Decide whether or not to emit a warning or trace message; if so,
shoaib_ahmed	0:791a779d6220	1428	calls output_message. The main reason for overriding this method
shoaib_ahmed	0:791a779d6220	1429	would be to abort on warnings. msg_level is -1 for warnings,
shoaib_ahmed	0:791a779d6220	1430	0 and up for trace messages.
shoaib_ahmed	0:791a779d6220	1431
shoaib_ahmed	0:791a779d6220	1432	Only error_exit() and emit_message() are called from the rest of the JPEG
shoaib_ahmed	0:791a779d6220	1433	library; the other two are internal to the error handler.
shoaib_ahmed	0:791a779d6220	1434
shoaib_ahmed	0:791a779d6220	1435	The actual message texts are stored in an array of strings which is pointed to
shoaib_ahmed	0:791a779d6220	1436	by the field err->jpeg_message_table. The messages are numbered from 0 to
shoaib_ahmed	0:791a779d6220	1437	err->last_jpeg_message, and it is these code numbers that are used in the
shoaib_ahmed	0:791a779d6220	1438	JPEG library code. You could replace the message texts (for instance, with
shoaib_ahmed	0:791a779d6220	1439	messages in French or German) by changing the message table pointer. See
shoaib_ahmed	0:791a779d6220	1440	jerror.h for the default texts. CAUTION: this table will almost certainly
shoaib_ahmed	0:791a779d6220	1441	change or grow from one library version to the next.
shoaib_ahmed	0:791a779d6220	1442
shoaib_ahmed	0:791a779d6220	1443	It may be useful for an application to add its own message texts that are
shoaib_ahmed	0:791a779d6220	1444	handled by the same mechanism. The error handler supports a second "add-on"
shoaib_ahmed	0:791a779d6220	1445	message table for this purpose. To define an addon table, set the pointer
shoaib_ahmed	0:791a779d6220	1446	err->addon_message_table and the message numbers err->first_addon_message and
shoaib_ahmed	0:791a779d6220	1447	err->last_addon_message. If you number the addon messages beginning at 1000
shoaib_ahmed	0:791a779d6220	1448	or so, you won't have to worry about conflicts with the library's built-in
shoaib_ahmed	0:791a779d6220	1449	messages. See the sample applications cjpeg/djpeg for an example of using
shoaib_ahmed	0:791a779d6220	1450	addon messages (the addon messages are defined in cderror.h).
shoaib_ahmed	0:791a779d6220	1451
shoaib_ahmed	0:791a779d6220	1452	Actual invocation of the error handler is done via macros defined in jerror.h:
shoaib_ahmed	0:791a779d6220	1453	ERREXITn(...) for fatal errors
shoaib_ahmed	0:791a779d6220	1454	WARNMSn(...) for corrupt-data warnings
shoaib_ahmed	0:791a779d6220	1455	TRACEMSn(...) for trace and informational messages.
shoaib_ahmed	0:791a779d6220	1456	These macros store the message code and any additional parameters into the
shoaib_ahmed	0:791a779d6220	1457	error handler struct, then invoke the error_exit() or emit_message() method.
shoaib_ahmed	0:791a779d6220	1458	The variants of each macro are for varying numbers of additional parameters.
shoaib_ahmed	0:791a779d6220	1459	The additional parameters are inserted into the generated message using
shoaib_ahmed	0:791a779d6220	1460	standard printf() format codes.
shoaib_ahmed	0:791a779d6220	1461
shoaib_ahmed	0:791a779d6220	1462	See jerror.h and jerror.c for further details.
shoaib_ahmed	0:791a779d6220	1463
shoaib_ahmed	0:791a779d6220	1464
shoaib_ahmed	0:791a779d6220	1465	Compressed data handling (source and destination managers)
shoaib_ahmed	0:791a779d6220	1466	----------------------------------------------------------
shoaib_ahmed	0:791a779d6220	1467
shoaib_ahmed	0:791a779d6220	1468	The JPEG compression library sends its compressed data to a "destination
shoaib_ahmed	0:791a779d6220	1469	manager" module. The default destination manager just writes the data to a
shoaib_ahmed	0:791a779d6220	1470	memory buffer or to a stdio stream, but you can provide your own manager to
shoaib_ahmed	0:791a779d6220	1471	do something else. Similarly, the decompression library calls a "source
shoaib_ahmed	0:791a779d6220	1472	manager" to obtain the compressed data; you can provide your own source
shoaib_ahmed	0:791a779d6220	1473	manager if you want the data to come from somewhere other than a memory
shoaib_ahmed	0:791a779d6220	1474	buffer or a stdio stream.
shoaib_ahmed	0:791a779d6220	1475
shoaib_ahmed	0:791a779d6220	1476	In both cases, compressed data is processed a bufferload at a time: the
shoaib_ahmed	0:791a779d6220	1477	destination or source manager provides a work buffer, and the library invokes
shoaib_ahmed	0:791a779d6220	1478	the manager only when the buffer is filled or emptied. (You could define a
shoaib_ahmed	0:791a779d6220	1479	one-character buffer to force the manager to be invoked for each byte, but
shoaib_ahmed	0:791a779d6220	1480	that would be rather inefficient.) The buffer's size and location are
shoaib_ahmed	0:791a779d6220	1481	controlled by the manager, not by the library. For example, the memory
shoaib_ahmed	0:791a779d6220	1482	source manager just makes the buffer pointer and length point to the original
shoaib_ahmed	0:791a779d6220	1483	data in memory. In this case the buffer-reload procedure will be invoked
shoaib_ahmed	0:791a779d6220	1484	only if the decompressor ran off the end of the datastream, which would
shoaib_ahmed	0:791a779d6220	1485	indicate an erroneous datastream.
shoaib_ahmed	0:791a779d6220	1486
shoaib_ahmed	0:791a779d6220	1487	The work buffer is defined as an array of datatype JOCTET, which is generally
shoaib_ahmed	0:791a779d6220	1488	"char" or "unsigned char". On a machine where char is not exactly 8 bits
shoaib_ahmed	0:791a779d6220	1489	wide, you must define JOCTET as a wider data type and then modify the data
shoaib_ahmed	0:791a779d6220	1490	source and destination modules to transcribe the work arrays into 8-bit units
shoaib_ahmed	0:791a779d6220	1491	on external storage.
shoaib_ahmed	0:791a779d6220	1492
shoaib_ahmed	0:791a779d6220	1493	A data destination manager struct contains a pointer and count defining the
shoaib_ahmed	0:791a779d6220	1494	next byte to write in the work buffer and the remaining free space:
shoaib_ahmed	0:791a779d6220	1495
shoaib_ahmed	0:791a779d6220	1496	JOCTET * next_output_byte; /* => next byte to write in buffer */
shoaib_ahmed	0:791a779d6220	1497	size_t free_in_buffer; /* # of byte spaces remaining in buffer */
shoaib_ahmed	0:791a779d6220	1498
shoaib_ahmed	0:791a779d6220	1499	The library increments the pointer and decrements the count until the buffer
shoaib_ahmed	0:791a779d6220	1500	is filled. The manager's empty_output_buffer method must reset the pointer
shoaib_ahmed	0:791a779d6220	1501	and count. The manager is expected to remember the buffer's starting address
shoaib_ahmed	0:791a779d6220	1502	and total size in private fields not visible to the library.
shoaib_ahmed	0:791a779d6220	1503
shoaib_ahmed	0:791a779d6220	1504	A data destination manager provides three methods:
shoaib_ahmed	0:791a779d6220	1505
shoaib_ahmed	0:791a779d6220	1506	init_destination (j_compress_ptr cinfo)
shoaib_ahmed	0:791a779d6220	1507	Initialize destination. This is called by jpeg_start_compress()
shoaib_ahmed	0:791a779d6220	1508	before any data is actually written. It must initialize
shoaib_ahmed	0:791a779d6220	1509	next_output_byte and free_in_buffer. free_in_buffer must be
shoaib_ahmed	0:791a779d6220	1510	initialized to a positive value.
shoaib_ahmed	0:791a779d6220	1511
shoaib_ahmed	0:791a779d6220	1512	empty_output_buffer (j_compress_ptr cinfo)
shoaib_ahmed	0:791a779d6220	1513	This is called whenever the buffer has filled (free_in_buffer
shoaib_ahmed	0:791a779d6220	1514	reaches zero). In typical applications, it should write out the
shoaib_ahmed	0:791a779d6220	1515	entire buffer (use the saved start address and buffer length;
shoaib_ahmed	0:791a779d6220	1516	ignore the current state of next_output_byte and free_in_buffer).
shoaib_ahmed	0:791a779d6220	1517	Then reset the pointer & count to the start of the buffer, and
shoaib_ahmed	0:791a779d6220	1518	return TRUE indicating that the buffer has been dumped.
shoaib_ahmed	0:791a779d6220	1519	free_in_buffer must be set to a positive value when TRUE is
shoaib_ahmed	0:791a779d6220	1520	returned. A FALSE return should only be used when I/O suspension is
shoaib_ahmed	0:791a779d6220	1521	desired (this operating mode is discussed in the next section).
shoaib_ahmed	0:791a779d6220	1522
shoaib_ahmed	0:791a779d6220	1523	term_destination (j_compress_ptr cinfo)
shoaib_ahmed	0:791a779d6220	1524	Terminate destination --- called by jpeg_finish_compress() after all
shoaib_ahmed	0:791a779d6220	1525	data has been written. In most applications, this must flush any
shoaib_ahmed	0:791a779d6220	1526	data remaining in the buffer. Use either next_output_byte or
shoaib_ahmed	0:791a779d6220	1527	free_in_buffer to determine how much data is in the buffer.
shoaib_ahmed	0:791a779d6220	1528
shoaib_ahmed	0:791a779d6220	1529	term_destination() is NOT called by jpeg_abort() or jpeg_destroy(). If you
shoaib_ahmed	0:791a779d6220	1530	want the destination manager to be cleaned up during an abort, you must do it
shoaib_ahmed	0:791a779d6220	1531	yourself.
shoaib_ahmed	0:791a779d6220	1532
shoaib_ahmed	0:791a779d6220	1533	You will also need code to create a jpeg_destination_mgr struct, fill in its
shoaib_ahmed	0:791a779d6220	1534	method pointers, and insert a pointer to the struct into the "dest" field of
shoaib_ahmed	0:791a779d6220	1535	the JPEG compression object. This can be done in-line in your setup code if
shoaib_ahmed	0:791a779d6220	1536	you like, but it's probably cleaner to provide a separate routine similar to
shoaib_ahmed	0:791a779d6220	1537	the jpeg_stdio_dest() or jpeg_mem_dest() routines of the supplied destination
shoaib_ahmed	0:791a779d6220	1538	managers.
shoaib_ahmed	0:791a779d6220	1539
shoaib_ahmed	0:791a779d6220	1540	Decompression source managers follow a parallel design, but with some
shoaib_ahmed	0:791a779d6220	1541	additional frammishes. The source manager struct contains a pointer and count
shoaib_ahmed	0:791a779d6220	1542	defining the next byte to read from the work buffer and the number of bytes
shoaib_ahmed	0:791a779d6220	1543	remaining:
shoaib_ahmed	0:791a779d6220	1544
shoaib_ahmed	0:791a779d6220	1545	const JOCTET * next_input_byte; /* => next byte to read from buffer */
shoaib_ahmed	0:791a779d6220	1546	size_t bytes_in_buffer; /* # of bytes remaining in buffer */
shoaib_ahmed	0:791a779d6220	1547
shoaib_ahmed	0:791a779d6220	1548	The library increments the pointer and decrements the count until the buffer
shoaib_ahmed	0:791a779d6220	1549	is emptied. The manager's fill_input_buffer method must reset the pointer and
shoaib_ahmed	0:791a779d6220	1550	count. In most applications, the manager must remember the buffer's starting
shoaib_ahmed	0:791a779d6220	1551	address and total size in private fields not visible to the library.
shoaib_ahmed	0:791a779d6220	1552
shoaib_ahmed	0:791a779d6220	1553	A data source manager provides five methods:
shoaib_ahmed	0:791a779d6220	1554
shoaib_ahmed	0:791a779d6220	1555	init_source (j_decompress_ptr cinfo)
shoaib_ahmed	0:791a779d6220	1556	Initialize source. This is called by jpeg_read_header() before any
shoaib_ahmed	0:791a779d6220	1557	data is actually read. Unlike init_destination(), it may leave
shoaib_ahmed	0:791a779d6220	1558	bytes_in_buffer set to 0 (in which case a fill_input_buffer() call
shoaib_ahmed	0:791a779d6220	1559	will occur immediately).
shoaib_ahmed	0:791a779d6220	1560
shoaib_ahmed	0:791a779d6220	1561	fill_input_buffer (j_decompress_ptr cinfo)
shoaib_ahmed	0:791a779d6220	1562	This is called whenever bytes_in_buffer has reached zero and more
shoaib_ahmed	0:791a779d6220	1563	data is wanted. In typical applications, it should read fresh data
shoaib_ahmed	0:791a779d6220	1564	into the buffer (ignoring the current state of next_input_byte and
shoaib_ahmed	0:791a779d6220	1565	bytes_in_buffer), reset the pointer & count to the start of the
shoaib_ahmed	0:791a779d6220	1566	buffer, and return TRUE indicating that the buffer has been reloaded.
shoaib_ahmed	0:791a779d6220	1567	It is not necessary to fill the buffer entirely, only to obtain at
shoaib_ahmed	0:791a779d6220	1568	least one more byte. bytes_in_buffer MUST be set to a positive value
shoaib_ahmed	0:791a779d6220	1569	if TRUE is returned. A FALSE return should only be used when I/O
shoaib_ahmed	0:791a779d6220	1570	suspension is desired (this mode is discussed in the next section).
shoaib_ahmed	0:791a779d6220	1571
shoaib_ahmed	0:791a779d6220	1572	skip_input_data (j_decompress_ptr cinfo, long num_bytes)
shoaib_ahmed	0:791a779d6220	1573	Skip num_bytes worth of data. The buffer pointer and count should
shoaib_ahmed	0:791a779d6220	1574	be advanced over num_bytes input bytes, refilling the buffer as
shoaib_ahmed	0:791a779d6220	1575	needed. This is used to skip over a potentially large amount of
shoaib_ahmed	0:791a779d6220	1576	uninteresting data (such as an APPn marker). In some applications
shoaib_ahmed	0:791a779d6220	1577	it may be possible to optimize away the reading of the skipped data,
shoaib_ahmed	0:791a779d6220	1578	but it's not clear that being smart is worth much trouble; large
shoaib_ahmed	0:791a779d6220	1579	skips are uncommon. bytes_in_buffer may be zero on return.
shoaib_ahmed	0:791a779d6220	1580	A zero or negative skip count should be treated as a no-op.
shoaib_ahmed	0:791a779d6220	1581
shoaib_ahmed	0:791a779d6220	1582	resync_to_restart (j_decompress_ptr cinfo, int desired)
shoaib_ahmed	0:791a779d6220	1583	This routine is called only when the decompressor has failed to find
shoaib_ahmed	0:791a779d6220	1584	a restart (RSTn) marker where one is expected. Its mission is to
shoaib_ahmed	0:791a779d6220	1585	find a suitable point for resuming decompression. For most
shoaib_ahmed	0:791a779d6220	1586	applications, we recommend that you just use the default resync
shoaib_ahmed	0:791a779d6220	1587	procedure, jpeg_resync_to_restart(). However, if you are able to back
shoaib_ahmed	0:791a779d6220	1588	up in the input data stream, or if you have a-priori knowledge about
shoaib_ahmed	0:791a779d6220	1589	the likely location of restart markers, you may be able to do better.
shoaib_ahmed	0:791a779d6220	1590	Read the read_restart_marker() and jpeg_resync_to_restart() routines
shoaib_ahmed	0:791a779d6220	1591	in jdmarker.c if you think you'd like to implement your own resync
shoaib_ahmed	0:791a779d6220	1592	procedure.
shoaib_ahmed	0:791a779d6220	1593
shoaib_ahmed	0:791a779d6220	1594	term_source (j_decompress_ptr cinfo)
shoaib_ahmed	0:791a779d6220	1595	Terminate source --- called by jpeg_finish_decompress() after all
shoaib_ahmed	0:791a779d6220	1596	data has been read. Often a no-op.
shoaib_ahmed	0:791a779d6220	1597
shoaib_ahmed	0:791a779d6220	1598	For both fill_input_buffer() and skip_input_data(), there is no such thing
shoaib_ahmed	0:791a779d6220	1599	as an EOF return. If the end of the file has been reached, the routine has
shoaib_ahmed	0:791a779d6220	1600	a choice of exiting via ERREXIT() or inserting fake data into the buffer.
shoaib_ahmed	0:791a779d6220	1601	In most cases, generating a warning message and inserting a fake EOI marker
shoaib_ahmed	0:791a779d6220	1602	is the best course of action --- this will allow the decompressor to output
shoaib_ahmed	0:791a779d6220	1603	however much of the image is there. In pathological cases, the decompressor
shoaib_ahmed	0:791a779d6220	1604	may swallow the EOI and again demand data ... just keep feeding it fake EOIs.
shoaib_ahmed	0:791a779d6220	1605	jdatasrc.c illustrates the recommended error recovery behavior.
shoaib_ahmed	0:791a779d6220	1606
shoaib_ahmed	0:791a779d6220	1607	term_source() is NOT called by jpeg_abort() or jpeg_destroy(). If you want
shoaib_ahmed	0:791a779d6220	1608	the source manager to be cleaned up during an abort, you must do it yourself.
shoaib_ahmed	0:791a779d6220	1609
shoaib_ahmed	0:791a779d6220	1610	You will also need code to create a jpeg_source_mgr struct, fill in its method
shoaib_ahmed	0:791a779d6220	1611	pointers, and insert a pointer to the struct into the "src" field of the JPEG
shoaib_ahmed	0:791a779d6220	1612	decompression object. This can be done in-line in your setup code if you
shoaib_ahmed	0:791a779d6220	1613	like, but it's probably cleaner to provide a separate routine similar to the
shoaib_ahmed	0:791a779d6220	1614	jpeg_stdio_src() or jpeg_mem_src() routines of the supplied source managers.
shoaib_ahmed	0:791a779d6220	1615
shoaib_ahmed	0:791a779d6220	1616	For more information, consult the memory and stdio source and destination
shoaib_ahmed	0:791a779d6220	1617	managers in jdatasrc.c and jdatadst.c.
shoaib_ahmed	0:791a779d6220	1618
shoaib_ahmed	0:791a779d6220	1619
shoaib_ahmed	0:791a779d6220	1620	I/O suspension
shoaib_ahmed	0:791a779d6220	1621	--------------
shoaib_ahmed	0:791a779d6220	1622
shoaib_ahmed	0:791a779d6220	1623	Some applications need to use the JPEG library as an incremental memory-to-
shoaib_ahmed	0:791a779d6220	1624	memory filter: when the compressed data buffer is filled or emptied, they want
shoaib_ahmed	0:791a779d6220	1625	control to return to the outer loop, rather than expecting that the buffer can
shoaib_ahmed	0:791a779d6220	1626	be emptied or reloaded within the data source/destination manager subroutine.
shoaib_ahmed	0:791a779d6220	1627	The library supports this need by providing an "I/O suspension" mode, which we
shoaib_ahmed	0:791a779d6220	1628	describe in this section.
shoaib_ahmed	0:791a779d6220	1629
shoaib_ahmed	0:791a779d6220	1630	The I/O suspension mode is not a panacea: nothing is guaranteed about the
shoaib_ahmed	0:791a779d6220	1631	maximum amount of time spent in any one call to the library, so it will not
shoaib_ahmed	0:791a779d6220	1632	eliminate response-time problems in single-threaded applications. If you
shoaib_ahmed	0:791a779d6220	1633	need guaranteed response time, we suggest you "bite the bullet" and implement
shoaib_ahmed	0:791a779d6220	1634	a real multi-tasking capability.
shoaib_ahmed	0:791a779d6220	1635
shoaib_ahmed	0:791a779d6220	1636	To use I/O suspension, cooperation is needed between the calling application
shoaib_ahmed	0:791a779d6220	1637	and the data source or destination manager; you will always need a custom
shoaib_ahmed	0:791a779d6220	1638	source/destination manager. (Please read the previous section if you haven't
shoaib_ahmed	0:791a779d6220	1639	already.) The basic idea is that the empty_output_buffer() or
shoaib_ahmed	0:791a779d6220	1640	fill_input_buffer() routine is a no-op, merely returning FALSE to indicate
shoaib_ahmed	0:791a779d6220	1641	that it has done nothing. Upon seeing this, the JPEG library suspends
shoaib_ahmed	0:791a779d6220	1642	operation and returns to its caller. The surrounding application is
shoaib_ahmed	0:791a779d6220	1643	responsible for emptying or refilling the work buffer before calling the
shoaib_ahmed	0:791a779d6220	1644	JPEG library again.
shoaib_ahmed	0:791a779d6220	1645
shoaib_ahmed	0:791a779d6220	1646	Compression suspension:
shoaib_ahmed	0:791a779d6220	1647
shoaib_ahmed	0:791a779d6220	1648	For compression suspension, use an empty_output_buffer() routine that returns
shoaib_ahmed	0:791a779d6220	1649	FALSE; typically it will not do anything else. This will cause the
shoaib_ahmed	0:791a779d6220	1650	compressor to return to the caller of jpeg_write_scanlines(), with the return
shoaib_ahmed	0:791a779d6220	1651	value indicating that not all the supplied scanlines have been accepted.
shoaib_ahmed	0:791a779d6220	1652	The application must make more room in the output buffer, adjust the output
shoaib_ahmed	0:791a779d6220	1653	buffer pointer/count appropriately, and then call jpeg_write_scanlines()
shoaib_ahmed	0:791a779d6220	1654	again, pointing to the first unconsumed scanline.
shoaib_ahmed	0:791a779d6220	1655
shoaib_ahmed	0:791a779d6220	1656	When forced to suspend, the compressor will backtrack to a convenient stopping
shoaib_ahmed	0:791a779d6220	1657	point (usually the start of the current MCU); it will regenerate some output
shoaib_ahmed	0:791a779d6220	1658	data when restarted. Therefore, although empty_output_buffer() is only
shoaib_ahmed	0:791a779d6220	1659	called when the buffer is filled, you should NOT write out the entire buffer
shoaib_ahmed	0:791a779d6220	1660	after a suspension. Write only the data up to the current position of
shoaib_ahmed	0:791a779d6220	1661	next_output_byte/free_in_buffer. The data beyond that point will be
shoaib_ahmed	0:791a779d6220	1662	regenerated after resumption.
shoaib_ahmed	0:791a779d6220	1663
shoaib_ahmed	0:791a779d6220	1664	Because of the backtracking behavior, a good-size output buffer is essential
shoaib_ahmed	0:791a779d6220	1665	for efficiency; you don't want the compressor to suspend often. (In fact, an
shoaib_ahmed	0:791a779d6220	1666	overly small buffer could lead to infinite looping, if a single MCU required
shoaib_ahmed	0:791a779d6220	1667	more data than would fit in the buffer.) We recommend a buffer of at least
shoaib_ahmed	0:791a779d6220	1668	several Kbytes. You may want to insert explicit code to ensure that you don't
shoaib_ahmed	0:791a779d6220	1669	call jpeg_write_scanlines() unless there is a reasonable amount of space in
shoaib_ahmed	0:791a779d6220	1670	the output buffer; in other words, flush the buffer before trying to compress
shoaib_ahmed	0:791a779d6220	1671	more data.
shoaib_ahmed	0:791a779d6220	1672
shoaib_ahmed	0:791a779d6220	1673	The compressor does not allow suspension while it is trying to write JPEG
shoaib_ahmed	0:791a779d6220	1674	markers at the beginning and end of the file. This means that:
shoaib_ahmed	0:791a779d6220	1675	* At the beginning of a compression operation, there must be enough free
shoaib_ahmed	0:791a779d6220	1676	space in the output buffer to hold the header markers (typically 600 or
shoaib_ahmed	0:791a779d6220	1677	so bytes). The recommended buffer size is bigger than this anyway, so
shoaib_ahmed	0:791a779d6220	1678	this is not a problem as long as you start with an empty buffer. However,
shoaib_ahmed	0:791a779d6220	1679	this restriction might catch you if you insert large special markers, such
shoaib_ahmed	0:791a779d6220	1680	as a JFIF thumbnail image, without flushing the buffer afterwards.
shoaib_ahmed	0:791a779d6220	1681	* When you call jpeg_finish_compress(), there must be enough space in the
shoaib_ahmed	0:791a779d6220	1682	output buffer to emit any buffered data and the final EOI marker. In the
shoaib_ahmed	0:791a779d6220	1683	current implementation, half a dozen bytes should suffice for this, but
shoaib_ahmed	0:791a779d6220	1684	for safety's sake we recommend ensuring that at least 100 bytes are free
shoaib_ahmed	0:791a779d6220	1685	before calling jpeg_finish_compress().
shoaib_ahmed	0:791a779d6220	1686
shoaib_ahmed	0:791a779d6220	1687	A more significant restriction is that jpeg_finish_compress() cannot suspend.
shoaib_ahmed	0:791a779d6220	1688	This means you cannot use suspension with multi-pass operating modes, namely
shoaib_ahmed	0:791a779d6220	1689	Huffman code optimization and multiple-scan output. Those modes write the
shoaib_ahmed	0:791a779d6220	1690	whole file during jpeg_finish_compress(), which will certainly result in
shoaib_ahmed	0:791a779d6220	1691	buffer overrun. (Note that this restriction applies only to compression,
shoaib_ahmed	0:791a779d6220	1692	not decompression. The decompressor supports input suspension in all of its
shoaib_ahmed	0:791a779d6220	1693	operating modes.)
shoaib_ahmed	0:791a779d6220	1694
shoaib_ahmed	0:791a779d6220	1695	Decompression suspension:
shoaib_ahmed	0:791a779d6220	1696
shoaib_ahmed	0:791a779d6220	1697	For decompression suspension, use a fill_input_buffer() routine that simply
shoaib_ahmed	0:791a779d6220	1698	returns FALSE (except perhaps during error recovery, as discussed below).
shoaib_ahmed	0:791a779d6220	1699	This will cause the decompressor to return to its caller with an indication
shoaib_ahmed	0:791a779d6220	1700	that suspension has occurred. This can happen at four places:
shoaib_ahmed	0:791a779d6220	1701	* jpeg_read_header(): will return JPEG_SUSPENDED.
shoaib_ahmed	0:791a779d6220	1702	* jpeg_start_decompress(): will return FALSE, rather than its usual TRUE.
shoaib_ahmed	0:791a779d6220	1703	* jpeg_read_scanlines(): will return the number of scanlines already
shoaib_ahmed	0:791a779d6220	1704	completed (possibly 0).
shoaib_ahmed	0:791a779d6220	1705	* jpeg_finish_decompress(): will return FALSE, rather than its usual TRUE.
shoaib_ahmed	0:791a779d6220	1706	The surrounding application must recognize these cases, load more data into
shoaib_ahmed	0:791a779d6220	1707	the input buffer, and repeat the call. In the case of jpeg_read_scanlines(),
shoaib_ahmed	0:791a779d6220	1708	increment the passed pointers past any scanlines successfully read.
shoaib_ahmed	0:791a779d6220	1709
shoaib_ahmed	0:791a779d6220	1710	Just as with compression, the decompressor will typically backtrack to a
shoaib_ahmed	0:791a779d6220	1711	convenient restart point before suspending. When fill_input_buffer() is
shoaib_ahmed	0:791a779d6220	1712	called, next_input_byte/bytes_in_buffer point to the current restart point,
shoaib_ahmed	0:791a779d6220	1713	which is where the decompressor will backtrack to if FALSE is returned.
shoaib_ahmed	0:791a779d6220	1714	The data beyond that position must NOT be discarded if you suspend; it needs
shoaib_ahmed	0:791a779d6220	1715	to be re-read upon resumption. In most implementations, you'll need to shift
shoaib_ahmed	0:791a779d6220	1716	this data down to the start of your work buffer and then load more data after
shoaib_ahmed	0:791a779d6220	1717	it. Again, this behavior means that a several-Kbyte work buffer is essential
shoaib_ahmed	0:791a779d6220	1718	for decent performance; furthermore, you should load a reasonable amount of
shoaib_ahmed	0:791a779d6220	1719	new data before resuming decompression. (If you loaded, say, only one new
shoaib_ahmed	0:791a779d6220	1720	byte each time around, you could waste a LOT of cycles.)
shoaib_ahmed	0:791a779d6220	1721
shoaib_ahmed	0:791a779d6220	1722	The skip_input_data() source manager routine requires special care in a
shoaib_ahmed	0:791a779d6220	1723	suspension scenario. This routine is NOT granted the ability to suspend the
shoaib_ahmed	0:791a779d6220	1724	decompressor; it can decrement bytes_in_buffer to zero, but no more. If the
shoaib_ahmed	0:791a779d6220	1725	requested skip distance exceeds the amount of data currently in the input
shoaib_ahmed	0:791a779d6220	1726	buffer, then skip_input_data() must set bytes_in_buffer to zero and record the
shoaib_ahmed	0:791a779d6220	1727	additional skip distance somewhere else. The decompressor will immediately
shoaib_ahmed	0:791a779d6220	1728	call fill_input_buffer(), which should return FALSE, which will cause a
shoaib_ahmed	0:791a779d6220	1729	suspension return. The surrounding application must then arrange to discard
shoaib_ahmed	0:791a779d6220	1730	the recorded number of bytes before it resumes loading the input buffer.
shoaib_ahmed	0:791a779d6220	1731	(Yes, this design is rather baroque, but it avoids complexity in the far more
shoaib_ahmed	0:791a779d6220	1732	common case where a non-suspending source manager is used.)
shoaib_ahmed	0:791a779d6220	1733
shoaib_ahmed	0:791a779d6220	1734	If the input data has been exhausted, we recommend that you emit a warning
shoaib_ahmed	0:791a779d6220	1735	and insert dummy EOI markers just as a non-suspending data source manager
shoaib_ahmed	0:791a779d6220	1736	would do. This can be handled either in the surrounding application logic or
shoaib_ahmed	0:791a779d6220	1737	within fill_input_buffer(); the latter is probably more efficient. If
shoaib_ahmed	0:791a779d6220	1738	fill_input_buffer() knows that no more data is available, it can set the
shoaib_ahmed	0:791a779d6220	1739	pointer/count to point to a dummy EOI marker and then return TRUE just as
shoaib_ahmed	0:791a779d6220	1740	though it had read more data in a non-suspending situation.
shoaib_ahmed	0:791a779d6220	1741
shoaib_ahmed	0:791a779d6220	1742	The decompressor does not attempt to suspend within standard JPEG markers;
shoaib_ahmed	0:791a779d6220	1743	instead it will backtrack to the start of the marker and reprocess the whole
shoaib_ahmed	0:791a779d6220	1744	marker next time. Hence the input buffer must be large enough to hold the
shoaib_ahmed	0:791a779d6220	1745	longest standard marker in the file. Standard JPEG markers should normally
shoaib_ahmed	0:791a779d6220	1746	not exceed a few hundred bytes each (DHT tables are typically the longest).
shoaib_ahmed	0:791a779d6220	1747	We recommend at least a 2K buffer for performance reasons, which is much
shoaib_ahmed	0:791a779d6220	1748	larger than any correct marker is likely to be. For robustness against
shoaib_ahmed	0:791a779d6220	1749	damaged marker length counts, you may wish to insert a test in your
shoaib_ahmed	0:791a779d6220	1750	application for the case that the input buffer is completely full and yet
shoaib_ahmed	0:791a779d6220	1751	the decoder has suspended without consuming any data --- otherwise, if this
shoaib_ahmed	0:791a779d6220	1752	situation did occur, it would lead to an endless loop. (The library can't
shoaib_ahmed	0:791a779d6220	1753	provide this test since it has no idea whether "the buffer is full", or
shoaib_ahmed	0:791a779d6220	1754	even whether there is a fixed-size input buffer.)
shoaib_ahmed	0:791a779d6220	1755
shoaib_ahmed	0:791a779d6220	1756	The input buffer would need to be 64K to allow for arbitrary COM or APPn
shoaib_ahmed	0:791a779d6220	1757	markers, but these are handled specially: they are either saved into allocated
shoaib_ahmed	0:791a779d6220	1758	memory, or skipped over by calling skip_input_data(). In the former case,
shoaib_ahmed	0:791a779d6220	1759	suspension is handled correctly, and in the latter case, the problem of
shoaib_ahmed	0:791a779d6220	1760	buffer overrun is placed on skip_input_data's shoulders, as explained above.
shoaib_ahmed	0:791a779d6220	1761	Note that if you provide your own marker handling routine for large markers,
shoaib_ahmed	0:791a779d6220	1762	you should consider how to deal with buffer overflow.
shoaib_ahmed	0:791a779d6220	1763
shoaib_ahmed	0:791a779d6220	1764	Multiple-buffer management:
shoaib_ahmed	0:791a779d6220	1765
shoaib_ahmed	0:791a779d6220	1766	In some applications it is desirable to store the compressed data in a linked
shoaib_ahmed	0:791a779d6220	1767	list of buffer areas, so as to avoid data copying. This can be handled by
shoaib_ahmed	0:791a779d6220	1768	having empty_output_buffer() or fill_input_buffer() set the pointer and count
shoaib_ahmed	0:791a779d6220	1769	to reference the next available buffer; FALSE is returned only if no more
shoaib_ahmed	0:791a779d6220	1770	buffers are available. Although seemingly straightforward, there is a
shoaib_ahmed	0:791a779d6220	1771	pitfall in this approach: the backtrack that occurs when FALSE is returned
shoaib_ahmed	0:791a779d6220	1772	could back up into an earlier buffer. For example, when fill_input_buffer()
shoaib_ahmed	0:791a779d6220	1773	is called, the current pointer & count indicate the backtrack restart point.
shoaib_ahmed	0:791a779d6220	1774	Since fill_input_buffer() will set the pointer and count to refer to a new
shoaib_ahmed	0:791a779d6220	1775	buffer, the restart position must be saved somewhere else. Suppose a second
shoaib_ahmed	0:791a779d6220	1776	call to fill_input_buffer() occurs in the same library call, and no
shoaib_ahmed	0:791a779d6220	1777	additional input data is available, so fill_input_buffer must return FALSE.
shoaib_ahmed	0:791a779d6220	1778	If the JPEG library has not moved the pointer/count forward in the current
shoaib_ahmed	0:791a779d6220	1779	buffer, then *the correct restart point is the saved position in the prior
shoaib_ahmed	0:791a779d6220	1780	buffer*. Prior buffers may be discarded only after the library establishes
shoaib_ahmed	0:791a779d6220	1781	a restart point within a later buffer. Similar remarks apply for output into
shoaib_ahmed	0:791a779d6220	1782	a chain of buffers.
shoaib_ahmed	0:791a779d6220	1783
shoaib_ahmed	0:791a779d6220	1784	The library will never attempt to backtrack over a skip_input_data() call,
shoaib_ahmed	0:791a779d6220	1785	so any skipped data can be permanently discarded. You still have to deal
shoaib_ahmed	0:791a779d6220	1786	with the case of skipping not-yet-received data, however.
shoaib_ahmed	0:791a779d6220	1787
shoaib_ahmed	0:791a779d6220	1788	It's much simpler to use only a single buffer; when fill_input_buffer() is
shoaib_ahmed	0:791a779d6220	1789	called, move any unconsumed data (beyond the current pointer/count) down to
shoaib_ahmed	0:791a779d6220	1790	the beginning of this buffer and then load new data into the remaining buffer
shoaib_ahmed	0:791a779d6220	1791	space. This approach requires a little more data copying but is far easier
shoaib_ahmed	0:791a779d6220	1792	to get right.
shoaib_ahmed	0:791a779d6220	1793
shoaib_ahmed	0:791a779d6220	1794
shoaib_ahmed	0:791a779d6220	1795	Progressive JPEG support
shoaib_ahmed	0:791a779d6220	1796	------------------------
shoaib_ahmed	0:791a779d6220	1797
shoaib_ahmed	0:791a779d6220	1798	Progressive JPEG rearranges the stored data into a series of scans of
shoaib_ahmed	0:791a779d6220	1799	increasing quality. In situations where a JPEG file is transmitted across a
shoaib_ahmed	0:791a779d6220	1800	slow communications link, a decoder can generate a low-quality image very
shoaib_ahmed	0:791a779d6220	1801	quickly from the first scan, then gradually improve the displayed quality as
shoaib_ahmed	0:791a779d6220	1802	more scans are received. The final image after all scans are complete is
shoaib_ahmed	0:791a779d6220	1803	identical to that of a regular (sequential) JPEG file of the same quality
shoaib_ahmed	0:791a779d6220	1804	setting. Progressive JPEG files are often slightly smaller than equivalent
shoaib_ahmed	0:791a779d6220	1805	sequential JPEG files, but the possibility of incremental display is the main
shoaib_ahmed	0:791a779d6220	1806	reason for using progressive JPEG.
shoaib_ahmed	0:791a779d6220	1807
shoaib_ahmed	0:791a779d6220	1808	The IJG encoder library generates progressive JPEG files when given a
shoaib_ahmed	0:791a779d6220	1809	suitable "scan script" defining how to divide the data into scans.
shoaib_ahmed	0:791a779d6220	1810	Creation of progressive JPEG files is otherwise transparent to the encoder.
shoaib_ahmed	0:791a779d6220	1811	Progressive JPEG files can also be read transparently by the decoder library.
shoaib_ahmed	0:791a779d6220	1812	If the decoding application simply uses the library as defined above, it
shoaib_ahmed	0:791a779d6220	1813	will receive a final decoded image without any indication that the file was
shoaib_ahmed	0:791a779d6220	1814	progressive. Of course, this approach does not allow incremental display.
shoaib_ahmed	0:791a779d6220	1815	To perform incremental display, an application needs to use the decoder
shoaib_ahmed	0:791a779d6220	1816	library's "buffered-image" mode, in which it receives a decoded image
shoaib_ahmed	0:791a779d6220	1817	multiple times.
shoaib_ahmed	0:791a779d6220	1818
shoaib_ahmed	0:791a779d6220	1819	Each displayed scan requires about as much work to decode as a full JPEG
shoaib_ahmed	0:791a779d6220	1820	image of the same size, so the decoder must be fairly fast in relation to the
shoaib_ahmed	0:791a779d6220	1821	data transmission rate in order to make incremental display useful. However,
shoaib_ahmed	0:791a779d6220	1822	it is possible to skip displaying the image and simply add the incoming bits
shoaib_ahmed	0:791a779d6220	1823	to the decoder's coefficient buffer. This is fast because only Huffman
shoaib_ahmed	0:791a779d6220	1824	decoding need be done, not IDCT, upsampling, colorspace conversion, etc.
shoaib_ahmed	0:791a779d6220	1825	The IJG decoder library allows the application to switch dynamically between
shoaib_ahmed	0:791a779d6220	1826	displaying the image and simply absorbing the incoming bits. A properly
shoaib_ahmed	0:791a779d6220	1827	coded application can automatically adapt the number of display passes to
shoaib_ahmed	0:791a779d6220	1828	suit the time available as the image is received. Also, a final
shoaib_ahmed	0:791a779d6220	1829	higher-quality display cycle can be performed from the buffered data after
shoaib_ahmed	0:791a779d6220	1830	the end of the file is reached.
shoaib_ahmed	0:791a779d6220	1831
shoaib_ahmed	0:791a779d6220	1832	Progressive compression:
shoaib_ahmed	0:791a779d6220	1833
shoaib_ahmed	0:791a779d6220	1834	To create a progressive JPEG file (or a multiple-scan sequential JPEG file),
shoaib_ahmed	0:791a779d6220	1835	set the scan_info cinfo field to point to an array of scan descriptors, and
shoaib_ahmed	0:791a779d6220	1836	perform compression as usual. Instead of constructing your own scan list,
shoaib_ahmed	0:791a779d6220	1837	you can call the jpeg_simple_progression() helper routine to create a
shoaib_ahmed	0:791a779d6220	1838	recommended progression sequence; this method should be used by all
shoaib_ahmed	0:791a779d6220	1839	applications that don't want to get involved in the nitty-gritty of
shoaib_ahmed	0:791a779d6220	1840	progressive scan sequence design. (If you want to provide user control of
shoaib_ahmed	0:791a779d6220	1841	scan sequences, you may wish to borrow the scan script reading code found
shoaib_ahmed	0:791a779d6220	1842	in rdswitch.c, so that you can read scan script files just like cjpeg's.)
shoaib_ahmed	0:791a779d6220	1843	When scan_info is not NULL, the compression library will store DCT'd data
shoaib_ahmed	0:791a779d6220	1844	into a buffer array as jpeg_write_scanlines() is called, and will emit all
shoaib_ahmed	0:791a779d6220	1845	the requested scans during jpeg_finish_compress(). This implies that
shoaib_ahmed	0:791a779d6220	1846	multiple-scan output cannot be created with a suspending data destination
shoaib_ahmed	0:791a779d6220	1847	manager, since jpeg_finish_compress() does not support suspension. We
shoaib_ahmed	0:791a779d6220	1848	should also note that the compressor currently forces Huffman optimization
shoaib_ahmed	0:791a779d6220	1849	mode when creating a progressive JPEG file, because the default Huffman
shoaib_ahmed	0:791a779d6220	1850	tables are unsuitable for progressive files.
shoaib_ahmed	0:791a779d6220	1851
shoaib_ahmed	0:791a779d6220	1852	Progressive decompression:
shoaib_ahmed	0:791a779d6220	1853
shoaib_ahmed	0:791a779d6220	1854	When buffered-image mode is not used, the decoder library will read all of
shoaib_ahmed	0:791a779d6220	1855	a multi-scan file during jpeg_start_decompress(), so that it can provide a
shoaib_ahmed	0:791a779d6220	1856	final decoded image. (Here "multi-scan" means either progressive or
shoaib_ahmed	0:791a779d6220	1857	multi-scan sequential.) This makes multi-scan files transparent to the
shoaib_ahmed	0:791a779d6220	1858	decoding application. However, existing applications that used suspending
shoaib_ahmed	0:791a779d6220	1859	input with version 5 of the IJG library will need to be modified to check
shoaib_ahmed	0:791a779d6220	1860	for a suspension return from jpeg_start_decompress().
shoaib_ahmed	0:791a779d6220	1861
shoaib_ahmed	0:791a779d6220	1862	To perform incremental display, an application must use the library's
shoaib_ahmed	0:791a779d6220	1863	buffered-image mode. This is described in the next section.
shoaib_ahmed	0:791a779d6220	1864
shoaib_ahmed	0:791a779d6220	1865
shoaib_ahmed	0:791a779d6220	1866	Buffered-image mode
shoaib_ahmed	0:791a779d6220	1867	-------------------
shoaib_ahmed	0:791a779d6220	1868
shoaib_ahmed	0:791a779d6220	1869	In buffered-image mode, the library stores the partially decoded image in a
shoaib_ahmed	0:791a779d6220	1870	coefficient buffer, from which it can be read out as many times as desired.
shoaib_ahmed	0:791a779d6220	1871	This mode is typically used for incremental display of progressive JPEG files,
shoaib_ahmed	0:791a779d6220	1872	but it can be used with any JPEG file. Each scan of a progressive JPEG file
shoaib_ahmed	0:791a779d6220	1873	adds more data (more detail) to the buffered image. The application can
shoaib_ahmed	0:791a779d6220	1874	display in lockstep with the source file (one display pass per input scan),
shoaib_ahmed	0:791a779d6220	1875	or it can allow input processing to outrun display processing. By making
shoaib_ahmed	0:791a779d6220	1876	input and display processing run independently, it is possible for the
shoaib_ahmed	0:791a779d6220	1877	application to adapt progressive display to a wide range of data transmission
shoaib_ahmed	0:791a779d6220	1878	rates.
shoaib_ahmed	0:791a779d6220	1879
shoaib_ahmed	0:791a779d6220	1880	The basic control flow for buffered-image decoding is
shoaib_ahmed	0:791a779d6220	1881
shoaib_ahmed	0:791a779d6220	1882	jpeg_create_decompress()
shoaib_ahmed	0:791a779d6220	1883	set data source
shoaib_ahmed	0:791a779d6220	1884	jpeg_read_header()
shoaib_ahmed	0:791a779d6220	1885	set overall decompression parameters
shoaib_ahmed	0:791a779d6220	1886	cinfo.buffered_image = TRUE; /* select buffered-image mode */
shoaib_ahmed	0:791a779d6220	1887	jpeg_start_decompress()
shoaib_ahmed	0:791a779d6220	1888	for (each output pass) {
shoaib_ahmed	0:791a779d6220	1889	adjust output decompression parameters if required
shoaib_ahmed	0:791a779d6220	1890	jpeg_start_output() /* start a new output pass */
shoaib_ahmed	0:791a779d6220	1891	for (all scanlines in image) {
shoaib_ahmed	0:791a779d6220	1892	jpeg_read_scanlines()
shoaib_ahmed	0:791a779d6220	1893	display scanlines
shoaib_ahmed	0:791a779d6220	1894	}
shoaib_ahmed	0:791a779d6220	1895	jpeg_finish_output() /* terminate output pass */
shoaib_ahmed	0:791a779d6220	1896	}
shoaib_ahmed	0:791a779d6220	1897	jpeg_finish_decompress()
shoaib_ahmed	0:791a779d6220	1898	jpeg_destroy_decompress()
shoaib_ahmed	0:791a779d6220	1899
shoaib_ahmed	0:791a779d6220	1900	This differs from ordinary unbuffered decoding in that there is an additional
shoaib_ahmed	0:791a779d6220	1901	level of looping. The application can choose how many output passes to make
shoaib_ahmed	0:791a779d6220	1902	and how to display each pass.
shoaib_ahmed	0:791a779d6220	1903
shoaib_ahmed	0:791a779d6220	1904	The simplest approach to displaying progressive images is to do one display
shoaib_ahmed	0:791a779d6220	1905	pass for each scan appearing in the input file. In this case the outer loop
shoaib_ahmed	0:791a779d6220	1906	condition is typically
shoaib_ahmed	0:791a779d6220	1907	while (! jpeg_input_complete(&cinfo))
shoaib_ahmed	0:791a779d6220	1908	and the start-output call should read
shoaib_ahmed	0:791a779d6220	1909	jpeg_start_output(&cinfo, cinfo.input_scan_number);
shoaib_ahmed	0:791a779d6220	1910	The second parameter to jpeg_start_output() indicates which scan of the input
shoaib_ahmed	0:791a779d6220	1911	file is to be displayed; the scans are numbered starting at 1 for this
shoaib_ahmed	0:791a779d6220	1912	purpose. (You can use a loop counter starting at 1 if you like, but using
shoaib_ahmed	0:791a779d6220	1913	the library's input scan counter is easier.) The library automatically reads
shoaib_ahmed	0:791a779d6220	1914	data as necessary to complete each requested scan, and jpeg_finish_output()
shoaib_ahmed	0:791a779d6220	1915	advances to the next scan or end-of-image marker (hence input_scan_number
shoaib_ahmed	0:791a779d6220	1916	will be incremented by the time control arrives back at jpeg_start_output()).
shoaib_ahmed	0:791a779d6220	1917	With this technique, data is read from the input file only as needed, and
shoaib_ahmed	0:791a779d6220	1918	input and output processing run in lockstep.
shoaib_ahmed	0:791a779d6220	1919
shoaib_ahmed	0:791a779d6220	1920	After reading the final scan and reaching the end of the input file, the
shoaib_ahmed	0:791a779d6220	1921	buffered image remains available; it can be read additional times by
shoaib_ahmed	0:791a779d6220	1922	repeating the jpeg_start_output()/jpeg_read_scanlines()/jpeg_finish_output()
shoaib_ahmed	0:791a779d6220	1923	sequence. For example, a useful technique is to use fast one-pass color
shoaib_ahmed	0:791a779d6220	1924	quantization for display passes made while the image is arriving, followed by
shoaib_ahmed	0:791a779d6220	1925	a final display pass using two-pass quantization for highest quality. This
shoaib_ahmed	0:791a779d6220	1926	is done by changing the library parameters before the final output pass.
shoaib_ahmed	0:791a779d6220	1927	Changing parameters between passes is discussed in detail below.
shoaib_ahmed	0:791a779d6220	1928
shoaib_ahmed	0:791a779d6220	1929	In general the last scan of a progressive file cannot be recognized as such
shoaib_ahmed	0:791a779d6220	1930	until after it is read, so a post-input display pass is the best approach if
shoaib_ahmed	0:791a779d6220	1931	you want special processing in the final pass.
shoaib_ahmed	0:791a779d6220	1932
shoaib_ahmed	0:791a779d6220	1933	When done with the image, be sure to call jpeg_finish_decompress() to release
shoaib_ahmed	0:791a779d6220	1934	the buffered image (or just use jpeg_destroy_decompress()).
shoaib_ahmed	0:791a779d6220	1935
shoaib_ahmed	0:791a779d6220	1936	If input data arrives faster than it can be displayed, the application can
shoaib_ahmed	0:791a779d6220	1937	cause the library to decode input data in advance of what's needed to produce
shoaib_ahmed	0:791a779d6220	1938	output. This is done by calling the routine jpeg_consume_input().
shoaib_ahmed	0:791a779d6220	1939	The return value is one of the following:
shoaib_ahmed	0:791a779d6220	1940	JPEG_REACHED_SOS: reached an SOS marker (the start of a new scan)
shoaib_ahmed	0:791a779d6220	1941	JPEG_REACHED_EOI: reached the EOI marker (end of image)
shoaib_ahmed	0:791a779d6220	1942	JPEG_ROW_COMPLETED: completed reading one MCU row of compressed data
shoaib_ahmed	0:791a779d6220	1943	JPEG_SCAN_COMPLETED: completed reading last MCU row of current scan
shoaib_ahmed	0:791a779d6220	1944	JPEG_SUSPENDED: suspended before completing any of the above
shoaib_ahmed	0:791a779d6220	1945	(JPEG_SUSPENDED can occur only if a suspending data source is used.) This
shoaib_ahmed	0:791a779d6220	1946	routine can be called at any time after initializing the JPEG object. It
shoaib_ahmed	0:791a779d6220	1947	reads some additional data and returns when one of the indicated significant
shoaib_ahmed	0:791a779d6220	1948	events occurs. (If called after the EOI marker is reached, it will
shoaib_ahmed	0:791a779d6220	1949	immediately return JPEG_REACHED_EOI without attempting to read more data.)
shoaib_ahmed	0:791a779d6220	1950
shoaib_ahmed	0:791a779d6220	1951	The library's output processing will automatically call jpeg_consume_input()
shoaib_ahmed	0:791a779d6220	1952	whenever the output processing overtakes the input; thus, simple lockstep
shoaib_ahmed	0:791a779d6220	1953	display requires no direct calls to jpeg_consume_input(). But by adding
shoaib_ahmed	0:791a779d6220	1954	calls to jpeg_consume_input(), you can absorb data in advance of what is
shoaib_ahmed	0:791a779d6220	1955	being displayed. This has two benefits:
shoaib_ahmed	0:791a779d6220	1956	* You can limit buildup of unprocessed data in your input buffer.
shoaib_ahmed	0:791a779d6220	1957	* You can eliminate extra display passes by paying attention to the
shoaib_ahmed	0:791a779d6220	1958	state of the library's input processing.
shoaib_ahmed	0:791a779d6220	1959
shoaib_ahmed	0:791a779d6220	1960	The first of these benefits only requires interspersing calls to
shoaib_ahmed	0:791a779d6220	1961	jpeg_consume_input() with your display operations and any other processing
shoaib_ahmed	0:791a779d6220	1962	you may be doing. To avoid wasting cycles due to backtracking, it's best to
shoaib_ahmed	0:791a779d6220	1963	call jpeg_consume_input() only after a hundred or so new bytes have arrived.
shoaib_ahmed	0:791a779d6220	1964	This is discussed further under "I/O suspension", above. (Note: the JPEG
shoaib_ahmed	0:791a779d6220	1965	library currently is not thread-safe. You must not call jpeg_consume_input()
shoaib_ahmed	0:791a779d6220	1966	from one thread of control if a different library routine is working on the
shoaib_ahmed	0:791a779d6220	1967	same JPEG object in another thread.)
shoaib_ahmed	0:791a779d6220	1968
shoaib_ahmed	0:791a779d6220	1969	When input arrives fast enough that more than one new scan is available
shoaib_ahmed	0:791a779d6220	1970	before you start a new output pass, you may as well skip the output pass
shoaib_ahmed	0:791a779d6220	1971	corresponding to the completed scan. This occurs for free if you pass
shoaib_ahmed	0:791a779d6220	1972	cinfo.input_scan_number as the target scan number to jpeg_start_output().
shoaib_ahmed	0:791a779d6220	1973	The input_scan_number field is simply the index of the scan currently being
shoaib_ahmed	0:791a779d6220	1974	consumed by the input processor. You can ensure that this is up-to-date by
shoaib_ahmed	0:791a779d6220	1975	emptying the input buffer just before calling jpeg_start_output(): call
shoaib_ahmed	0:791a779d6220	1976	jpeg_consume_input() repeatedly until it returns JPEG_SUSPENDED or
shoaib_ahmed	0:791a779d6220	1977	JPEG_REACHED_EOI.
shoaib_ahmed	0:791a779d6220	1978
shoaib_ahmed	0:791a779d6220	1979	The target scan number passed to jpeg_start_output() is saved in the
shoaib_ahmed	0:791a779d6220	1980	cinfo.output_scan_number field. The library's output processing calls
shoaib_ahmed	0:791a779d6220	1981	jpeg_consume_input() whenever the current input scan number and row within
shoaib_ahmed	0:791a779d6220	1982	that scan is less than or equal to the current output scan number and row.
shoaib_ahmed	0:791a779d6220	1983	Thus, input processing can "get ahead" of the output processing but is not
shoaib_ahmed	0:791a779d6220	1984	allowed to "fall behind". You can achieve several different effects by
shoaib_ahmed	0:791a779d6220	1985	manipulating this interlock rule. For example, if you pass a target scan
shoaib_ahmed	0:791a779d6220	1986	number greater than the current input scan number, the output processor will
shoaib_ahmed	0:791a779d6220	1987	wait until that scan starts to arrive before producing any output. (To avoid
shoaib_ahmed	0:791a779d6220	1988	an infinite loop, the target scan number is automatically reset to the last
shoaib_ahmed	0:791a779d6220	1989	scan number when the end of image is reached. Thus, if you specify a large
shoaib_ahmed	0:791a779d6220	1990	target scan number, the library will just absorb the entire input file and
shoaib_ahmed	0:791a779d6220	1991	then perform an output pass. This is effectively the same as what
shoaib_ahmed	0:791a779d6220	1992	jpeg_start_decompress() does when you don't select buffered-image mode.)
shoaib_ahmed	0:791a779d6220	1993	When you pass a target scan number equal to the current input scan number,
shoaib_ahmed	0:791a779d6220	1994	the image is displayed no faster than the current input scan arrives. The
shoaib_ahmed	0:791a779d6220	1995	final possibility is to pass a target scan number less than the current input
shoaib_ahmed	0:791a779d6220	1996	scan number; this disables the input/output interlock and causes the output
shoaib_ahmed	0:791a779d6220	1997	processor to simply display whatever it finds in the image buffer, without
shoaib_ahmed	0:791a779d6220	1998	waiting for input. (However, the library will not accept a target scan
shoaib_ahmed	0:791a779d6220	1999	number less than one, so you can't avoid waiting for the first scan.)
shoaib_ahmed	0:791a779d6220	2000
shoaib_ahmed	0:791a779d6220	2001	When data is arriving faster than the output display processing can advance
shoaib_ahmed	0:791a779d6220	2002	through the image, jpeg_consume_input() will store data into the buffered
shoaib_ahmed	0:791a779d6220	2003	image beyond the point at which the output processing is reading data out
shoaib_ahmed	0:791a779d6220	2004	again. If the input arrives fast enough, it may "wrap around" the buffer to
shoaib_ahmed	0:791a779d6220	2005	the point where the input is more than one whole scan ahead of the output.
shoaib_ahmed	0:791a779d6220	2006	If the output processing simply proceeds through its display pass without
shoaib_ahmed	0:791a779d6220	2007	paying attention to the input, the effect seen on-screen is that the lower
shoaib_ahmed	0:791a779d6220	2008	part of the image is one or more scans better in quality than the upper part.
shoaib_ahmed	0:791a779d6220	2009	Then, when the next output scan is started, you have a choice of what target
shoaib_ahmed	0:791a779d6220	2010	scan number to use. The recommended choice is to use the current input scan
shoaib_ahmed	0:791a779d6220	2011	number at that time, which implies that you've skipped the output scans
shoaib_ahmed	0:791a779d6220	2012	corresponding to the input scans that were completed while you processed the
shoaib_ahmed	0:791a779d6220	2013	previous output scan. In this way, the decoder automatically adapts its
shoaib_ahmed	0:791a779d6220	2014	speed to the arriving data, by skipping output scans as necessary to keep up
shoaib_ahmed	0:791a779d6220	2015	with the arriving data.
shoaib_ahmed	0:791a779d6220	2016
shoaib_ahmed	0:791a779d6220	2017	When using this strategy, you'll want to be sure that you perform a final
shoaib_ahmed	0:791a779d6220	2018	output pass after receiving all the data; otherwise your last display may not
shoaib_ahmed	0:791a779d6220	2019	be full quality across the whole screen. So the right outer loop logic is
shoaib_ahmed	0:791a779d6220	2020	something like this:
shoaib_ahmed	0:791a779d6220	2021	do {
shoaib_ahmed	0:791a779d6220	2022	absorb any waiting input by calling jpeg_consume_input()
shoaib_ahmed	0:791a779d6220	2023	final_pass = jpeg_input_complete(&cinfo);
shoaib_ahmed	0:791a779d6220	2024	adjust output decompression parameters if required
shoaib_ahmed	0:791a779d6220	2025	jpeg_start_output(&cinfo, cinfo.input_scan_number);
shoaib_ahmed	0:791a779d6220	2026	...
shoaib_ahmed	0:791a779d6220	2027	jpeg_finish_output()
shoaib_ahmed	0:791a779d6220	2028	} while (! final_pass);
shoaib_ahmed	0:791a779d6220	2029	rather than quitting as soon as jpeg_input_complete() returns TRUE. This
shoaib_ahmed	0:791a779d6220	2030	arrangement makes it simple to use higher-quality decoding parameters
shoaib_ahmed	0:791a779d6220	2031	for the final pass. But if you don't want to use special parameters for
shoaib_ahmed	0:791a779d6220	2032	the final pass, the right loop logic is like this:
shoaib_ahmed	0:791a779d6220	2033	for (;;) {
shoaib_ahmed	0:791a779d6220	2034	absorb any waiting input by calling jpeg_consume_input()
shoaib_ahmed	0:791a779d6220	2035	jpeg_start_output(&cinfo, cinfo.input_scan_number);
shoaib_ahmed	0:791a779d6220	2036	...
shoaib_ahmed	0:791a779d6220	2037	jpeg_finish_output()
shoaib_ahmed	0:791a779d6220	2038	if (jpeg_input_complete(&cinfo) &&
shoaib_ahmed	0:791a779d6220	2039	cinfo.input_scan_number == cinfo.output_scan_number)
shoaib_ahmed	0:791a779d6220	2040	break;
shoaib_ahmed	0:791a779d6220	2041	}
shoaib_ahmed	0:791a779d6220	2042	In this case you don't need to know in advance whether an output pass is to
shoaib_ahmed	0:791a779d6220	2043	be the last one, so it's not necessary to have reached EOF before starting
shoaib_ahmed	0:791a779d6220	2044	the final output pass; rather, what you want to test is whether the output
shoaib_ahmed	0:791a779d6220	2045	pass was performed in sync with the final input scan. This form of the loop
shoaib_ahmed	0:791a779d6220	2046	will avoid an extra output pass whenever the decoder is able (or nearly able)
shoaib_ahmed	0:791a779d6220	2047	to keep up with the incoming data.
shoaib_ahmed	0:791a779d6220	2048
shoaib_ahmed	0:791a779d6220	2049	When the data transmission speed is high, you might begin a display pass,
shoaib_ahmed	0:791a779d6220	2050	then find that much or all of the file has arrived before you can complete
shoaib_ahmed	0:791a779d6220	2051	the pass. (You can detect this by noting the JPEG_REACHED_EOI return code
shoaib_ahmed	0:791a779d6220	2052	from jpeg_consume_input(), or equivalently by testing jpeg_input_complete().)
shoaib_ahmed	0:791a779d6220	2053	In this situation you may wish to abort the current display pass and start a
shoaib_ahmed	0:791a779d6220	2054	new one using the newly arrived information. To do so, just call
shoaib_ahmed	0:791a779d6220	2055	jpeg_finish_output() and then start a new pass with jpeg_start_output().
shoaib_ahmed	0:791a779d6220	2056
shoaib_ahmed	0:791a779d6220	2057	A variant strategy is to abort and restart display if more than one complete
shoaib_ahmed	0:791a779d6220	2058	scan arrives during an output pass; this can be detected by noting
shoaib_ahmed	0:791a779d6220	2059	JPEG_REACHED_SOS returns and/or examining cinfo.input_scan_number. This
shoaib_ahmed	0:791a779d6220	2060	idea should be employed with caution, however, since the display process
shoaib_ahmed	0:791a779d6220	2061	might never get to the bottom of the image before being aborted, resulting
shoaib_ahmed	0:791a779d6220	2062	in the lower part of the screen being several passes worse than the upper.
shoaib_ahmed	0:791a779d6220	2063	In most cases it's probably best to abort an output pass only if the whole
shoaib_ahmed	0:791a779d6220	2064	file has arrived and you want to begin the final output pass immediately.
shoaib_ahmed	0:791a779d6220	2065
shoaib_ahmed	0:791a779d6220	2066	When receiving data across a communication link, we recommend always using
shoaib_ahmed	0:791a779d6220	2067	the current input scan number for the output target scan number; if a
shoaib_ahmed	0:791a779d6220	2068	higher-quality final pass is to be done, it should be started (aborting any
shoaib_ahmed	0:791a779d6220	2069	incomplete output pass) as soon as the end of file is received. However,
shoaib_ahmed	0:791a779d6220	2070	many other strategies are possible. For example, the application can examine
shoaib_ahmed	0:791a779d6220	2071	the parameters of the current input scan and decide whether to display it or
shoaib_ahmed	0:791a779d6220	2072	not. If the scan contains only chroma data, one might choose not to use it
shoaib_ahmed	0:791a779d6220	2073	as the target scan, expecting that the scan will be small and will arrive
shoaib_ahmed	0:791a779d6220	2074	quickly. To skip to the next scan, call jpeg_consume_input() until it
shoaib_ahmed	0:791a779d6220	2075	returns JPEG_REACHED_SOS or JPEG_REACHED_EOI. Or just use the next higher
shoaib_ahmed	0:791a779d6220	2076	number as the target scan for jpeg_start_output(); but that method doesn't
shoaib_ahmed	0:791a779d6220	2077	let you inspect the next scan's parameters before deciding to display it.
shoaib_ahmed	0:791a779d6220	2078
shoaib_ahmed	0:791a779d6220	2079
shoaib_ahmed	0:791a779d6220	2080	In buffered-image mode, jpeg_start_decompress() never performs input and
shoaib_ahmed	0:791a779d6220	2081	thus never suspends. An application that uses input suspension with
shoaib_ahmed	0:791a779d6220	2082	buffered-image mode must be prepared for suspension returns from these
shoaib_ahmed	0:791a779d6220	2083	routines:
shoaib_ahmed	0:791a779d6220	2084	* jpeg_start_output() performs input only if you request 2-pass quantization
shoaib_ahmed	0:791a779d6220	2085	and the target scan isn't fully read yet. (This is discussed below.)
shoaib_ahmed	0:791a779d6220	2086	* jpeg_read_scanlines(), as always, returns the number of scanlines that it
shoaib_ahmed	0:791a779d6220	2087	was able to produce before suspending.
shoaib_ahmed	0:791a779d6220	2088	* jpeg_finish_output() will read any markers following the target scan,
shoaib_ahmed	0:791a779d6220	2089	up to the end of the file or the SOS marker that begins another scan.
shoaib_ahmed	0:791a779d6220	2090	(But it reads no input if jpeg_consume_input() has already reached the
shoaib_ahmed	0:791a779d6220	2091	end of the file or a SOS marker beyond the target output scan.)
shoaib_ahmed	0:791a779d6220	2092	* jpeg_finish_decompress() will read until the end of file, and thus can
shoaib_ahmed	0:791a779d6220	2093	suspend if the end hasn't already been reached (as can be tested by
shoaib_ahmed	0:791a779d6220	2094	calling jpeg_input_complete()).
shoaib_ahmed	0:791a779d6220	2095	jpeg_start_output(), jpeg_finish_output(), and jpeg_finish_decompress()
shoaib_ahmed	0:791a779d6220	2096	all return TRUE if they completed their tasks, FALSE if they had to suspend.
shoaib_ahmed	0:791a779d6220	2097	In the event of a FALSE return, the application must load more input data
shoaib_ahmed	0:791a779d6220	2098	and repeat the call. Applications that use non-suspending data sources need
shoaib_ahmed	0:791a779d6220	2099	not check the return values of these three routines.
shoaib_ahmed	0:791a779d6220	2100
shoaib_ahmed	0:791a779d6220	2101
shoaib_ahmed	0:791a779d6220	2102	It is possible to change decoding parameters between output passes in the
shoaib_ahmed	0:791a779d6220	2103	buffered-image mode. The decoder library currently supports only very
shoaib_ahmed	0:791a779d6220	2104	limited changes of parameters. ONLY THE FOLLOWING parameter changes are
shoaib_ahmed	0:791a779d6220	2105	allowed after jpeg_start_decompress() is called:
shoaib_ahmed	0:791a779d6220	2106	* dct_method can be changed before each call to jpeg_start_output().
shoaib_ahmed	0:791a779d6220	2107	For example, one could use a fast DCT method for early scans, changing
shoaib_ahmed	0:791a779d6220	2108	to a higher quality method for the final scan.
shoaib_ahmed	0:791a779d6220	2109	* dither_mode can be changed before each call to jpeg_start_output();
shoaib_ahmed	0:791a779d6220	2110	of course this has no impact if not using color quantization. Typically
shoaib_ahmed	0:791a779d6220	2111	one would use ordered dither for initial passes, then switch to
shoaib_ahmed	0:791a779d6220	2112	Floyd-Steinberg dither for the final pass. Caution: changing dither mode
shoaib_ahmed	0:791a779d6220	2113	can cause more memory to be allocated by the library. Although the amount
shoaib_ahmed	0:791a779d6220	2114	of memory involved is not large (a scanline or so), it may cause the
shoaib_ahmed	0:791a779d6220	2115	initial max_memory_to_use specification to be exceeded, which in the worst
shoaib_ahmed	0:791a779d6220	2116	case would result in an out-of-memory failure.
shoaib_ahmed	0:791a779d6220	2117	* do_block_smoothing can be changed before each call to jpeg_start_output().
shoaib_ahmed	0:791a779d6220	2118	This setting is relevant only when decoding a progressive JPEG image.
shoaib_ahmed	0:791a779d6220	2119	During the first DC-only scan, block smoothing provides a very "fuzzy" look
shoaib_ahmed	0:791a779d6220	2120	instead of the very "blocky" look seen without it; which is better seems a
shoaib_ahmed	0:791a779d6220	2121	matter of personal taste. But block smoothing is nearly always a win
shoaib_ahmed	0:791a779d6220	2122	during later stages, especially when decoding a successive-approximation
shoaib_ahmed	0:791a779d6220	2123	image: smoothing helps to hide the slight blockiness that otherwise shows
shoaib_ahmed	0:791a779d6220	2124	up on smooth gradients until the lowest coefficient bits are sent.
shoaib_ahmed	0:791a779d6220	2125	* Color quantization mode can be changed under the rules described below.
shoaib_ahmed	0:791a779d6220	2126	You cannot change between full-color and quantized output (because that
shoaib_ahmed	0:791a779d6220	2127	would alter the required I/O buffer sizes), but you can change which
shoaib_ahmed	0:791a779d6220	2128	quantization method is used.
shoaib_ahmed	0:791a779d6220	2129
shoaib_ahmed	0:791a779d6220	2130	When generating color-quantized output, changing quantization method is a
shoaib_ahmed	0:791a779d6220	2131	very useful way of switching between high-speed and high-quality display.
shoaib_ahmed	0:791a779d6220	2132	The library allows you to change among its three quantization methods:
shoaib_ahmed	0:791a779d6220	2133	1. Single-pass quantization to a fixed color cube.
shoaib_ahmed	0:791a779d6220	2134	Selected by cinfo.two_pass_quantize = FALSE and cinfo.colormap = NULL.
shoaib_ahmed	0:791a779d6220	2135	2. Single-pass quantization to an application-supplied colormap.
shoaib_ahmed	0:791a779d6220	2136	Selected by setting cinfo.colormap to point to the colormap (the value of
shoaib_ahmed	0:791a779d6220	2137	two_pass_quantize is ignored); also set cinfo.actual_number_of_colors.
shoaib_ahmed	0:791a779d6220	2138	3. Two-pass quantization to a colormap chosen specifically for the image.
shoaib_ahmed	0:791a779d6220	2139	Selected by cinfo.two_pass_quantize = TRUE and cinfo.colormap = NULL.
shoaib_ahmed	0:791a779d6220	2140	(This is the default setting selected by jpeg_read_header, but it is
shoaib_ahmed	0:791a779d6220	2141	probably NOT what you want for the first pass of progressive display!)
shoaib_ahmed	0:791a779d6220	2142	These methods offer successively better quality and lesser speed. However,
shoaib_ahmed	0:791a779d6220	2143	only the first method is available for quantizing in non-RGB color spaces.
shoaib_ahmed	0:791a779d6220	2144
shoaib_ahmed	0:791a779d6220	2145	IMPORTANT: because the different quantizer methods have very different
shoaib_ahmed	0:791a779d6220	2146	working-storage requirements, the library requires you to indicate which
shoaib_ahmed	0:791a779d6220	2147	one(s) you intend to use before you call jpeg_start_decompress(). (If we did
shoaib_ahmed	0:791a779d6220	2148	not require this, the max_memory_to_use setting would be a complete fiction.)
shoaib_ahmed	0:791a779d6220	2149	You do this by setting one or more of these three cinfo fields to TRUE:
shoaib_ahmed	0:791a779d6220	2150	enable_1pass_quant Fixed color cube colormap
shoaib_ahmed	0:791a779d6220	2151	enable_external_quant Externally-supplied colormap
shoaib_ahmed	0:791a779d6220	2152	enable_2pass_quant Two-pass custom colormap
shoaib_ahmed	0:791a779d6220	2153	All three are initialized FALSE by jpeg_read_header(). But
shoaib_ahmed	0:791a779d6220	2154	jpeg_start_decompress() automatically sets TRUE the one selected by the
shoaib_ahmed	0:791a779d6220	2155	current two_pass_quantize and colormap settings, so you only need to set the
shoaib_ahmed	0:791a779d6220	2156	enable flags for any other quantization methods you plan to change to later.
shoaib_ahmed	0:791a779d6220	2157
shoaib_ahmed	0:791a779d6220	2158	After setting the enable flags correctly at jpeg_start_decompress() time, you
shoaib_ahmed	0:791a779d6220	2159	can change to any enabled quantization method by setting two_pass_quantize
shoaib_ahmed	0:791a779d6220	2160	and colormap properly just before calling jpeg_start_output(). The following
shoaib_ahmed	0:791a779d6220	2161	special rules apply:
shoaib_ahmed	0:791a779d6220	2162	1. You must explicitly set cinfo.colormap to NULL when switching to 1-pass
shoaib_ahmed	0:791a779d6220	2163	or 2-pass mode from a different mode, or when you want the 2-pass
shoaib_ahmed	0:791a779d6220	2164	quantizer to be re-run to generate a new colormap.
shoaib_ahmed	0:791a779d6220	2165	2. To switch to an external colormap, or to change to a different external
shoaib_ahmed	0:791a779d6220	2166	colormap than was used on the prior pass, you must call
shoaib_ahmed	0:791a779d6220	2167	jpeg_new_colormap() after setting cinfo.colormap.
shoaib_ahmed	0:791a779d6220	2168	NOTE: if you want to use the same colormap as was used in the prior pass,
shoaib_ahmed	0:791a779d6220	2169	you should not do either of these things. This will save some nontrivial
shoaib_ahmed	0:791a779d6220	2170	switchover costs.
shoaib_ahmed	0:791a779d6220	2171	(These requirements exist because cinfo.colormap will always be non-NULL
shoaib_ahmed	0:791a779d6220	2172	after completing a prior output pass, since both the 1-pass and 2-pass
shoaib_ahmed	0:791a779d6220	2173	quantizers set it to point to their output colormaps. Thus you have to
shoaib_ahmed	0:791a779d6220	2174	do one of these two things to notify the library that something has changed.
shoaib_ahmed	0:791a779d6220	2175	Yup, it's a bit klugy, but it's necessary to do it this way for backwards
shoaib_ahmed	0:791a779d6220	2176	compatibility.)
shoaib_ahmed	0:791a779d6220	2177
shoaib_ahmed	0:791a779d6220	2178	Note that in buffered-image mode, the library generates any requested colormap
shoaib_ahmed	0:791a779d6220	2179	during jpeg_start_output(), not during jpeg_start_decompress().
shoaib_ahmed	0:791a779d6220	2180
shoaib_ahmed	0:791a779d6220	2181	When using two-pass quantization, jpeg_start_output() makes a pass over the
shoaib_ahmed	0:791a779d6220	2182	buffered image to determine the optimum color map; it therefore may take a
shoaib_ahmed	0:791a779d6220	2183	significant amount of time, whereas ordinarily it does little work. The
shoaib_ahmed	0:791a779d6220	2184	progress monitor hook is called during this pass, if defined. It is also
shoaib_ahmed	0:791a779d6220	2185	important to realize that if the specified target scan number is greater than
shoaib_ahmed	0:791a779d6220	2186	or equal to the current input scan number, jpeg_start_output() will attempt
shoaib_ahmed	0:791a779d6220	2187	to consume input as it makes this pass. If you use a suspending data source,
shoaib_ahmed	0:791a779d6220	2188	you need to check for a FALSE return from jpeg_start_output() under these
shoaib_ahmed	0:791a779d6220	2189	conditions. The combination of 2-pass quantization and a not-yet-fully-read
shoaib_ahmed	0:791a779d6220	2190	target scan is the only case in which jpeg_start_output() will consume input.
shoaib_ahmed	0:791a779d6220	2191
shoaib_ahmed	0:791a779d6220	2192
shoaib_ahmed	0:791a779d6220	2193	Application authors who support buffered-image mode may be tempted to use it
shoaib_ahmed	0:791a779d6220	2194	for all JPEG images, even single-scan ones. This will work, but it is
shoaib_ahmed	0:791a779d6220	2195	inefficient: there is no need to create an image-sized coefficient buffer for
shoaib_ahmed	0:791a779d6220	2196	single-scan images. Requesting buffered-image mode for such an image wastes
shoaib_ahmed	0:791a779d6220	2197	memory. Worse, it can cost time on large images, since the buffered data has
shoaib_ahmed	0:791a779d6220	2198	to be swapped out or written to a temporary file. If you are concerned about
shoaib_ahmed	0:791a779d6220	2199	maximum performance on baseline JPEG files, you should use buffered-image
shoaib_ahmed	0:791a779d6220	2200	mode only when the incoming file actually has multiple scans. This can be
shoaib_ahmed	0:791a779d6220	2201	tested by calling jpeg_has_multiple_scans(), which will return a correct
shoaib_ahmed	0:791a779d6220	2202	result at any time after jpeg_read_header() completes.
shoaib_ahmed	0:791a779d6220	2203
shoaib_ahmed	0:791a779d6220	2204	It is also worth noting that when you use jpeg_consume_input() to let input
shoaib_ahmed	0:791a779d6220	2205	processing get ahead of output processing, the resulting pattern of access to
shoaib_ahmed	0:791a779d6220	2206	the coefficient buffer is quite nonsequential. It's best to use the memory
shoaib_ahmed	0:791a779d6220	2207	manager jmemnobs.c if you can (ie, if you have enough real or virtual main
shoaib_ahmed	0:791a779d6220	2208	memory). If not, at least make sure that max_memory_to_use is set as high as
shoaib_ahmed	0:791a779d6220	2209	possible. If the JPEG memory manager has to use a temporary file, you will
shoaib_ahmed	0:791a779d6220	2210	probably see a lot of disk traffic and poor performance. (This could be
shoaib_ahmed	0:791a779d6220	2211	improved with additional work on the memory manager, but we haven't gotten
shoaib_ahmed	0:791a779d6220	2212	around to it yet.)
shoaib_ahmed	0:791a779d6220	2213
shoaib_ahmed	0:791a779d6220	2214	In some applications it may be convenient to use jpeg_consume_input() for all
shoaib_ahmed	0:791a779d6220	2215	input processing, including reading the initial markers; that is, you may
shoaib_ahmed	0:791a779d6220	2216	wish to call jpeg_consume_input() instead of jpeg_read_header() during
shoaib_ahmed	0:791a779d6220	2217	startup. This works, but note that you must check for JPEG_REACHED_SOS and
shoaib_ahmed	0:791a779d6220	2218	JPEG_REACHED_EOI return codes as the equivalent of jpeg_read_header's codes.
shoaib_ahmed	0:791a779d6220	2219	Once the first SOS marker has been reached, you must call
shoaib_ahmed	0:791a779d6220	2220	jpeg_start_decompress() before jpeg_consume_input() will consume more input;
shoaib_ahmed	0:791a779d6220	2221	it'll just keep returning JPEG_REACHED_SOS until you do. If you read a
shoaib_ahmed	0:791a779d6220	2222	tables-only file this way, jpeg_consume_input() will return JPEG_REACHED_EOI
shoaib_ahmed	0:791a779d6220	2223	without ever returning JPEG_REACHED_SOS; be sure to check for this case.
shoaib_ahmed	0:791a779d6220	2224	If this happens, the decompressor will not read any more input until you call
shoaib_ahmed	0:791a779d6220	2225	jpeg_abort() to reset it. It is OK to call jpeg_consume_input() even when not
shoaib_ahmed	0:791a779d6220	2226	using buffered-image mode, but in that case it's basically a no-op after the
shoaib_ahmed	0:791a779d6220	2227	initial markers have been read: it will just return JPEG_SUSPENDED.
shoaib_ahmed	0:791a779d6220	2228
shoaib_ahmed	0:791a779d6220	2229
shoaib_ahmed	0:791a779d6220	2230	Abbreviated datastreams and multiple images
shoaib_ahmed	0:791a779d6220	2231	-------------------------------------------
shoaib_ahmed	0:791a779d6220	2232
shoaib_ahmed	0:791a779d6220	2233	A JPEG compression or decompression object can be reused to process multiple
shoaib_ahmed	0:791a779d6220	2234	images. This saves a small amount of time per image by eliminating the
shoaib_ahmed	0:791a779d6220	2235	"create" and "destroy" operations, but that isn't the real purpose of the
shoaib_ahmed	0:791a779d6220	2236	feature. Rather, reuse of an object provides support for abbreviated JPEG
shoaib_ahmed	0:791a779d6220	2237	datastreams. Object reuse can also simplify processing a series of images in
shoaib_ahmed	0:791a779d6220	2238	a single input or output file. This section explains these features.
shoaib_ahmed	0:791a779d6220	2239
shoaib_ahmed	0:791a779d6220	2240	A JPEG file normally contains several hundred bytes worth of quantization
shoaib_ahmed	0:791a779d6220	2241	and Huffman tables. In a situation where many images will be stored or
shoaib_ahmed	0:791a779d6220	2242	transmitted with identical tables, this may represent an annoying overhead.
shoaib_ahmed	0:791a779d6220	2243	The JPEG standard therefore permits tables to be omitted. The standard
shoaib_ahmed	0:791a779d6220	2244	defines three classes of JPEG datastreams:
shoaib_ahmed	0:791a779d6220	2245	* "Interchange" datastreams contain an image and all tables needed to decode
shoaib_ahmed	0:791a779d6220	2246	the image. These are the usual kind of JPEG file.
shoaib_ahmed	0:791a779d6220	2247	* "Abbreviated image" datastreams contain an image, but are missing some or
shoaib_ahmed	0:791a779d6220	2248	all of the tables needed to decode that image.
shoaib_ahmed	0:791a779d6220	2249	* "Abbreviated table specification" (henceforth "tables-only") datastreams
shoaib_ahmed	0:791a779d6220	2250	contain only table specifications.
shoaib_ahmed	0:791a779d6220	2251	To decode an abbreviated image, it is necessary to load the missing table(s)
shoaib_ahmed	0:791a779d6220	2252	into the decoder beforehand. This can be accomplished by reading a separate
shoaib_ahmed	0:791a779d6220	2253	tables-only file. A variant scheme uses a series of images in which the first
shoaib_ahmed	0:791a779d6220	2254	image is an interchange (complete) datastream, while subsequent ones are
shoaib_ahmed	0:791a779d6220	2255	abbreviated and rely on the tables loaded by the first image. It is assumed
shoaib_ahmed	0:791a779d6220	2256	that once the decoder has read a table, it will remember that table until a
shoaib_ahmed	0:791a779d6220	2257	new definition for the same table number is encountered.
shoaib_ahmed	0:791a779d6220	2258
shoaib_ahmed	0:791a779d6220	2259	It is the application designer's responsibility to figure out how to associate
shoaib_ahmed	0:791a779d6220	2260	the correct tables with an abbreviated image. While abbreviated datastreams
shoaib_ahmed	0:791a779d6220	2261	can be useful in a closed environment, their use is strongly discouraged in
shoaib_ahmed	0:791a779d6220	2262	any situation where data exchange with other applications might be needed.
shoaib_ahmed	0:791a779d6220	2263	Caveat designer.
shoaib_ahmed	0:791a779d6220	2264
shoaib_ahmed	0:791a779d6220	2265	The JPEG library provides support for reading and writing any combination of
shoaib_ahmed	0:791a779d6220	2266	tables-only datastreams and abbreviated images. In both compression and
shoaib_ahmed	0:791a779d6220	2267	decompression objects, a quantization or Huffman table will be retained for
shoaib_ahmed	0:791a779d6220	2268	the lifetime of the object, unless it is overwritten by a new table definition.
shoaib_ahmed	0:791a779d6220	2269
shoaib_ahmed	0:791a779d6220	2270
shoaib_ahmed	0:791a779d6220	2271	To create abbreviated image datastreams, it is only necessary to tell the
shoaib_ahmed	0:791a779d6220	2272	compressor not to emit some or all of the tables it is using. Each
shoaib_ahmed	0:791a779d6220	2273	quantization and Huffman table struct contains a boolean field "sent_table",
shoaib_ahmed	0:791a779d6220	2274	which normally is initialized to FALSE. For each table used by the image, the
shoaib_ahmed	0:791a779d6220	2275	header-writing process emits the table and sets sent_table = TRUE unless it is
shoaib_ahmed	0:791a779d6220	2276	already TRUE. (In normal usage, this prevents outputting the same table
shoaib_ahmed	0:791a779d6220	2277	definition multiple times, as would otherwise occur because the chroma
shoaib_ahmed	0:791a779d6220	2278	components typically share tables.) Thus, setting this field to TRUE before
shoaib_ahmed	0:791a779d6220	2279	calling jpeg_start_compress() will prevent the table from being written at
shoaib_ahmed	0:791a779d6220	2280	all.
shoaib_ahmed	0:791a779d6220	2281
shoaib_ahmed	0:791a779d6220	2282	If you want to create a "pure" abbreviated image file containing no tables,
shoaib_ahmed	0:791a779d6220	2283	just call "jpeg_suppress_tables(&cinfo, TRUE)" after constructing all the
shoaib_ahmed	0:791a779d6220	2284	tables. If you want to emit some but not all tables, you'll need to set the
shoaib_ahmed	0:791a779d6220	2285	individual sent_table fields directly.
shoaib_ahmed	0:791a779d6220	2286
shoaib_ahmed	0:791a779d6220	2287	To create an abbreviated image, you must also call jpeg_start_compress()
shoaib_ahmed	0:791a779d6220	2288	with a second parameter of FALSE, not TRUE. Otherwise jpeg_start_compress()
shoaib_ahmed	0:791a779d6220	2289	will force all the sent_table fields to FALSE. (This is a safety feature to
shoaib_ahmed	0:791a779d6220	2290	prevent abbreviated images from being created accidentally.)
shoaib_ahmed	0:791a779d6220	2291
shoaib_ahmed	0:791a779d6220	2292	To create a tables-only file, perform the same parameter setup that you
shoaib_ahmed	0:791a779d6220	2293	normally would, but instead of calling jpeg_start_compress() and so on, call
shoaib_ahmed	0:791a779d6220	2294	jpeg_write_tables(&cinfo). This will write an abbreviated datastream
shoaib_ahmed	0:791a779d6220	2295	containing only SOI, DQT and/or DHT markers, and EOI. All the quantization
shoaib_ahmed	0:791a779d6220	2296	and Huffman tables that are currently defined in the compression object will
shoaib_ahmed	0:791a779d6220	2297	be emitted unless their sent_tables flag is already TRUE, and then all the
shoaib_ahmed	0:791a779d6220	2298	sent_tables flags will be set TRUE.
shoaib_ahmed	0:791a779d6220	2299
shoaib_ahmed	0:791a779d6220	2300	A sure-fire way to create matching tables-only and abbreviated image files
shoaib_ahmed	0:791a779d6220	2301	is to proceed as follows:
shoaib_ahmed	0:791a779d6220	2302
shoaib_ahmed	0:791a779d6220	2303	create JPEG compression object
shoaib_ahmed	0:791a779d6220	2304	set JPEG parameters
shoaib_ahmed	0:791a779d6220	2305	set destination to tables-only file
shoaib_ahmed	0:791a779d6220	2306	jpeg_write_tables(&cinfo);
shoaib_ahmed	0:791a779d6220	2307	set destination to image file
shoaib_ahmed	0:791a779d6220	2308	jpeg_start_compress(&cinfo, FALSE);
shoaib_ahmed	0:791a779d6220	2309	write data...
shoaib_ahmed	0:791a779d6220	2310	jpeg_finish_compress(&cinfo);
shoaib_ahmed	0:791a779d6220	2311
shoaib_ahmed	0:791a779d6220	2312	Since the JPEG parameters are not altered between writing the table file and
shoaib_ahmed	0:791a779d6220	2313	the abbreviated image file, the same tables are sure to be used. Of course,
shoaib_ahmed	0:791a779d6220	2314	you can repeat the jpeg_start_compress() ... jpeg_finish_compress() sequence
shoaib_ahmed	0:791a779d6220	2315	many times to produce many abbreviated image files matching the table file.
shoaib_ahmed	0:791a779d6220	2316
shoaib_ahmed	0:791a779d6220	2317	You cannot suppress output of the computed Huffman tables when Huffman
shoaib_ahmed	0:791a779d6220	2318	optimization is selected. (If you could, there'd be no way to decode the
shoaib_ahmed	0:791a779d6220	2319	image...) Generally, you don't want to set optimize_coding = TRUE when
shoaib_ahmed	0:791a779d6220	2320	you are trying to produce abbreviated files.
shoaib_ahmed	0:791a779d6220	2321
shoaib_ahmed	0:791a779d6220	2322	In some cases you might want to compress an image using tables which are
shoaib_ahmed	0:791a779d6220	2323	not stored in the application, but are defined in an interchange or
shoaib_ahmed	0:791a779d6220	2324	tables-only file readable by the application. This can be done by setting up
shoaib_ahmed	0:791a779d6220	2325	a JPEG decompression object to read the specification file, then copying the
shoaib_ahmed	0:791a779d6220	2326	tables into your compression object. See jpeg_copy_critical_parameters()
shoaib_ahmed	0:791a779d6220	2327	for an example of copying quantization tables.
shoaib_ahmed	0:791a779d6220	2328
shoaib_ahmed	0:791a779d6220	2329
shoaib_ahmed	0:791a779d6220	2330	To read abbreviated image files, you simply need to load the proper tables
shoaib_ahmed	0:791a779d6220	2331	into the decompression object before trying to read the abbreviated image.
shoaib_ahmed	0:791a779d6220	2332	If the proper tables are stored in the application program, you can just
shoaib_ahmed	0:791a779d6220	2333	allocate the table structs and fill in their contents directly. For example,
shoaib_ahmed	0:791a779d6220	2334	to load a fixed quantization table into table slot "n":
shoaib_ahmed	0:791a779d6220	2335
shoaib_ahmed	0:791a779d6220	2336	if (cinfo.quant_tbl_ptrs[n] == NULL)
shoaib_ahmed	0:791a779d6220	2337	cinfo.quant_tbl_ptrs[n] = jpeg_alloc_quant_table((j_common_ptr) &cinfo);
shoaib_ahmed	0:791a779d6220	2338	quant_ptr = cinfo.quant_tbl_ptrs[n]; /* quant_ptr is JQUANT_TBL* */
shoaib_ahmed	0:791a779d6220	2339	for (i = 0; i < 64; i++) {
shoaib_ahmed	0:791a779d6220	2340	/* Qtable[] is desired quantization table, in natural array order */
shoaib_ahmed	0:791a779d6220	2341	quant_ptr->quantval[i] = Qtable[i];
shoaib_ahmed	0:791a779d6220	2342	}
shoaib_ahmed	0:791a779d6220	2343
shoaib_ahmed	0:791a779d6220	2344	Code to load a fixed Huffman table is typically (for AC table "n"):
shoaib_ahmed	0:791a779d6220	2345
shoaib_ahmed	0:791a779d6220	2346	if (cinfo.ac_huff_tbl_ptrs[n] == NULL)
shoaib_ahmed	0:791a779d6220	2347	cinfo.ac_huff_tbl_ptrs[n] = jpeg_alloc_huff_table((j_common_ptr) &cinfo);
shoaib_ahmed	0:791a779d6220	2348	huff_ptr = cinfo.ac_huff_tbl_ptrs[n]; /* huff_ptr is JHUFF_TBL* */
shoaib_ahmed	0:791a779d6220	2349	for (i = 1; i <= 16; i++) {
shoaib_ahmed	0:791a779d6220	2350	/* counts[i] is number of Huffman codes of length i bits, i=1..16 */
shoaib_ahmed	0:791a779d6220	2351	huff_ptr->bits[i] = counts[i];
shoaib_ahmed	0:791a779d6220	2352	}
shoaib_ahmed	0:791a779d6220	2353	for (i = 0; i < 256; i++) {
shoaib_ahmed	0:791a779d6220	2354	/* symbols[] is the list of Huffman symbols, in code-length order */
shoaib_ahmed	0:791a779d6220	2355	huff_ptr->huffval[i] = symbols[i];
shoaib_ahmed	0:791a779d6220	2356	}
shoaib_ahmed	0:791a779d6220	2357
shoaib_ahmed	0:791a779d6220	2358	(Note that trying to set cinfo.quant_tbl_ptrs[n] to point directly at a
shoaib_ahmed	0:791a779d6220	2359	constant JQUANT_TBL object is not safe. If the incoming file happened to
shoaib_ahmed	0:791a779d6220	2360	contain a quantization table definition, your master table would get
shoaib_ahmed	0:791a779d6220	2361	overwritten! Instead allocate a working table copy and copy the master table
shoaib_ahmed	0:791a779d6220	2362	into it, as illustrated above. Ditto for Huffman tables, of course.)
shoaib_ahmed	0:791a779d6220	2363
shoaib_ahmed	0:791a779d6220	2364	You might want to read the tables from a tables-only file, rather than
shoaib_ahmed	0:791a779d6220	2365	hard-wiring them into your application. The jpeg_read_header() call is
shoaib_ahmed	0:791a779d6220	2366	sufficient to read a tables-only file. You must pass a second parameter of
shoaib_ahmed	0:791a779d6220	2367	FALSE to indicate that you do not require an image to be present. Thus, the
shoaib_ahmed	0:791a779d6220	2368	typical scenario is
shoaib_ahmed	0:791a779d6220	2369
shoaib_ahmed	0:791a779d6220	2370	create JPEG decompression object
shoaib_ahmed	0:791a779d6220	2371	set source to tables-only file
shoaib_ahmed	0:791a779d6220	2372	jpeg_read_header(&cinfo, FALSE);
shoaib_ahmed	0:791a779d6220	2373	set source to abbreviated image file
shoaib_ahmed	0:791a779d6220	2374	jpeg_read_header(&cinfo, TRUE);
shoaib_ahmed	0:791a779d6220	2375	set decompression parameters
shoaib_ahmed	0:791a779d6220	2376	jpeg_start_decompress(&cinfo);
shoaib_ahmed	0:791a779d6220	2377	read data...
shoaib_ahmed	0:791a779d6220	2378	jpeg_finish_decompress(&cinfo);
shoaib_ahmed	0:791a779d6220	2379
shoaib_ahmed	0:791a779d6220	2380	In some cases, you may want to read a file without knowing whether it contains
shoaib_ahmed	0:791a779d6220	2381	an image or just tables. In that case, pass FALSE and check the return value
shoaib_ahmed	0:791a779d6220	2382	from jpeg_read_header(): it will be JPEG_HEADER_OK if an image was found,
shoaib_ahmed	0:791a779d6220	2383	JPEG_HEADER_TABLES_ONLY if only tables were found. (A third return value,
shoaib_ahmed	0:791a779d6220	2384	JPEG_SUSPENDED, is possible when using a suspending data source manager.)
shoaib_ahmed	0:791a779d6220	2385	Note that jpeg_read_header() will not complain if you read an abbreviated
shoaib_ahmed	0:791a779d6220	2386	image for which you haven't loaded the missing tables; the missing-table check
shoaib_ahmed	0:791a779d6220	2387	occurs later, in jpeg_start_decompress().
shoaib_ahmed	0:791a779d6220	2388
shoaib_ahmed	0:791a779d6220	2389
shoaib_ahmed	0:791a779d6220	2390	It is possible to read a series of images from a single source file by
shoaib_ahmed	0:791a779d6220	2391	repeating the jpeg_read_header() ... jpeg_finish_decompress() sequence,
shoaib_ahmed	0:791a779d6220	2392	without releasing/recreating the JPEG object or the data source module.
shoaib_ahmed	0:791a779d6220	2393	(If you did reinitialize, any partial bufferload left in the data source
shoaib_ahmed	0:791a779d6220	2394	buffer at the end of one image would be discarded, causing you to lose the
shoaib_ahmed	0:791a779d6220	2395	start of the next image.) When you use this method, stored tables are
shoaib_ahmed	0:791a779d6220	2396	automatically carried forward, so some of the images can be abbreviated images
shoaib_ahmed	0:791a779d6220	2397	that depend on tables from earlier images.
shoaib_ahmed	0:791a779d6220	2398
shoaib_ahmed	0:791a779d6220	2399	If you intend to write a series of images into a single destination file,
shoaib_ahmed	0:791a779d6220	2400	you might want to make a specialized data destination module that doesn't
shoaib_ahmed	0:791a779d6220	2401	flush the output buffer at term_destination() time. This would speed things
shoaib_ahmed	0:791a779d6220	2402	up by some trifling amount. Of course, you'd need to remember to flush the
shoaib_ahmed	0:791a779d6220	2403	buffer after the last image. You can make the later images be abbreviated
shoaib_ahmed	0:791a779d6220	2404	ones by passing FALSE to jpeg_start_compress().
shoaib_ahmed	0:791a779d6220	2405
shoaib_ahmed	0:791a779d6220	2406
shoaib_ahmed	0:791a779d6220	2407	Special markers
shoaib_ahmed	0:791a779d6220	2408	---------------
shoaib_ahmed	0:791a779d6220	2409
shoaib_ahmed	0:791a779d6220	2410	Some applications may need to insert or extract special data in the JPEG
shoaib_ahmed	0:791a779d6220	2411	datastream. The JPEG standard provides marker types "COM" (comment) and
shoaib_ahmed	0:791a779d6220	2412	"APP0" through "APP15" (application) to hold application-specific data.
shoaib_ahmed	0:791a779d6220	2413	Unfortunately, the use of these markers is not specified by the standard.
shoaib_ahmed	0:791a779d6220	2414	COM markers are fairly widely used to hold user-supplied text. The JFIF file
shoaib_ahmed	0:791a779d6220	2415	format spec uses APP0 markers with specified initial strings to hold certain
shoaib_ahmed	0:791a779d6220	2416	data. Adobe applications use APP14 markers beginning with the string "Adobe"
shoaib_ahmed	0:791a779d6220	2417	for miscellaneous data. Other APPn markers are rarely seen, but might
shoaib_ahmed	0:791a779d6220	2418	contain almost anything.
shoaib_ahmed	0:791a779d6220	2419
shoaib_ahmed	0:791a779d6220	2420	If you wish to store user-supplied text, we recommend you use COM markers
shoaib_ahmed	0:791a779d6220	2421	and place readable 7-bit ASCII text in them. Newline conventions are not
shoaib_ahmed	0:791a779d6220	2422	standardized --- expect to find LF (Unix style), CR/LF (DOS style), or CR
shoaib_ahmed	0:791a779d6220	2423	(Mac style). A robust COM reader should be able to cope with random binary
shoaib_ahmed	0:791a779d6220	2424	garbage, including nulls, since some applications generate COM markers
shoaib_ahmed	0:791a779d6220	2425	containing non-ASCII junk. (But yours should not be one of them.)
shoaib_ahmed	0:791a779d6220	2426
shoaib_ahmed	0:791a779d6220	2427	For program-supplied data, use an APPn marker, and be sure to begin it with an
shoaib_ahmed	0:791a779d6220	2428	identifying string so that you can tell whether the marker is actually yours.
shoaib_ahmed	0:791a779d6220	2429	It's probably best to avoid using APP0 or APP14 for any private markers.
shoaib_ahmed	0:791a779d6220	2430	(NOTE: the upcoming SPIFF standard will use APP8 markers; we recommend you
shoaib_ahmed	0:791a779d6220	2431	not use APP8 markers for any private purposes, either.)
shoaib_ahmed	0:791a779d6220	2432
shoaib_ahmed	0:791a779d6220	2433	Keep in mind that at most 65533 bytes can be put into one marker, but you
shoaib_ahmed	0:791a779d6220	2434	can have as many markers as you like.
shoaib_ahmed	0:791a779d6220	2435
shoaib_ahmed	0:791a779d6220	2436	By default, the IJG compression library will write a JFIF APP0 marker if the
shoaib_ahmed	0:791a779d6220	2437	selected JPEG colorspace is grayscale or YCbCr, or an Adobe APP14 marker if
shoaib_ahmed	0:791a779d6220	2438	the selected colorspace is RGB, CMYK, or YCCK. You can disable this, but
shoaib_ahmed	0:791a779d6220	2439	we don't recommend it. The decompression library will recognize JFIF and
shoaib_ahmed	0:791a779d6220	2440	Adobe markers and will set the JPEG colorspace properly when one is found.
shoaib_ahmed	0:791a779d6220	2441
shoaib_ahmed	0:791a779d6220	2442
shoaib_ahmed	0:791a779d6220	2443	You can write special markers immediately following the datastream header by
shoaib_ahmed	0:791a779d6220	2444	calling jpeg_write_marker() after jpeg_start_compress() and before the first
shoaib_ahmed	0:791a779d6220	2445	call to jpeg_write_scanlines(). When you do this, the markers appear after
shoaib_ahmed	0:791a779d6220	2446	the SOI and the JFIF APP0 and Adobe APP14 markers (if written), but before
shoaib_ahmed	0:791a779d6220	2447	all else. Specify the marker type parameter as "JPEG_COM" for COM or
shoaib_ahmed	0:791a779d6220	2448	"JPEG_APP0 + n" for APPn. (Actually, jpeg_write_marker will let you write
shoaib_ahmed	0:791a779d6220	2449	any marker type, but we don't recommend writing any other kinds of marker.)
shoaib_ahmed	0:791a779d6220	2450	For example, to write a user comment string pointed to by comment_text:
shoaib_ahmed	0:791a779d6220	2451	jpeg_write_marker(cinfo, JPEG_COM, comment_text, strlen(comment_text));
shoaib_ahmed	0:791a779d6220	2452
shoaib_ahmed	0:791a779d6220	2453	If it's not convenient to store all the marker data in memory at once,
shoaib_ahmed	0:791a779d6220	2454	you can instead call jpeg_write_m_header() followed by multiple calls to
shoaib_ahmed	0:791a779d6220	2455	jpeg_write_m_byte(). If you do it this way, it's your responsibility to
shoaib_ahmed	0:791a779d6220	2456	call jpeg_write_m_byte() exactly the number of times given in the length
shoaib_ahmed	0:791a779d6220	2457	parameter to jpeg_write_m_header(). (This method lets you empty the
shoaib_ahmed	0:791a779d6220	2458	output buffer partway through a marker, which might be important when
shoaib_ahmed	0:791a779d6220	2459	using a suspending data destination module. In any case, if you are using
shoaib_ahmed	0:791a779d6220	2460	a suspending destination, you should flush its buffer after inserting
shoaib_ahmed	0:791a779d6220	2461	any special markers. See "I/O suspension".)
shoaib_ahmed	0:791a779d6220	2462
shoaib_ahmed	0:791a779d6220	2463	Or, if you prefer to synthesize the marker byte sequence yourself,
shoaib_ahmed	0:791a779d6220	2464	you can just cram it straight into the data destination module.
shoaib_ahmed	0:791a779d6220	2465
shoaib_ahmed	0:791a779d6220	2466	If you are writing JFIF 1.02 extension markers (thumbnail images), don't
shoaib_ahmed	0:791a779d6220	2467	forget to set cinfo.JFIF_minor_version = 2 so that the encoder will write the
shoaib_ahmed	0:791a779d6220	2468	correct JFIF version number in the JFIF header marker. The library's default
shoaib_ahmed	0:791a779d6220	2469	is to write version 1.01, but that's wrong if you insert any 1.02 extension
shoaib_ahmed	0:791a779d6220	2470	markers. (We could probably get away with just defaulting to 1.02, but there
shoaib_ahmed	0:791a779d6220	2471	used to be broken decoders that would complain about unknown minor version
shoaib_ahmed	0:791a779d6220	2472	numbers. To reduce compatibility risks it's safest not to write 1.02 unless
shoaib_ahmed	0:791a779d6220	2473	you are actually using 1.02 extensions.)
shoaib_ahmed	0:791a779d6220	2474
shoaib_ahmed	0:791a779d6220	2475
shoaib_ahmed	0:791a779d6220	2476	When reading, two methods of handling special markers are available:
shoaib_ahmed	0:791a779d6220	2477	1. You can ask the library to save the contents of COM and/or APPn markers
shoaib_ahmed	0:791a779d6220	2478	into memory, and then examine them at your leisure afterwards.
shoaib_ahmed	0:791a779d6220	2479	2. You can supply your own routine to process COM and/or APPn markers
shoaib_ahmed	0:791a779d6220	2480	on-the-fly as they are read.
shoaib_ahmed	0:791a779d6220	2481	The first method is simpler to use, especially if you are using a suspending
shoaib_ahmed	0:791a779d6220	2482	data source; writing a marker processor that copes with input suspension is
shoaib_ahmed	0:791a779d6220	2483	not easy (consider what happens if the marker is longer than your available
shoaib_ahmed	0:791a779d6220	2484	input buffer). However, the second method conserves memory since the marker
shoaib_ahmed	0:791a779d6220	2485	data need not be kept around after it's been processed.
shoaib_ahmed	0:791a779d6220	2486
shoaib_ahmed	0:791a779d6220	2487	For either method, you'd normally set up marker handling after creating a
shoaib_ahmed	0:791a779d6220	2488	decompression object and before calling jpeg_read_header(), because the
shoaib_ahmed	0:791a779d6220	2489	markers of interest will typically be near the head of the file and so will
shoaib_ahmed	0:791a779d6220	2490	be scanned by jpeg_read_header. Once you've established a marker handling
shoaib_ahmed	0:791a779d6220	2491	method, it will be used for the life of that decompression object
shoaib_ahmed	0:791a779d6220	2492	(potentially many datastreams), unless you change it. Marker handling is
shoaib_ahmed	0:791a779d6220	2493	determined separately for COM markers and for each APPn marker code.
shoaib_ahmed	0:791a779d6220	2494
shoaib_ahmed	0:791a779d6220	2495
shoaib_ahmed	0:791a779d6220	2496	To save the contents of special markers in memory, call
shoaib_ahmed	0:791a779d6220	2497	jpeg_save_markers(cinfo, marker_code, length_limit)
shoaib_ahmed	0:791a779d6220	2498	where marker_code is the marker type to save, JPEG_COM or JPEG_APP0+n.
shoaib_ahmed	0:791a779d6220	2499	(To arrange to save all the special marker types, you need to call this
shoaib_ahmed	0:791a779d6220	2500	routine 17 times, for COM and APP0-APP15.) If the incoming marker is longer
shoaib_ahmed	0:791a779d6220	2501	than length_limit data bytes, only length_limit bytes will be saved; this
shoaib_ahmed	0:791a779d6220	2502	parameter allows you to avoid chewing up memory when you only need to see the
shoaib_ahmed	0:791a779d6220	2503	first few bytes of a potentially large marker. If you want to save all the
shoaib_ahmed	0:791a779d6220	2504	data, set length_limit to 0xFFFF; that is enough since marker lengths are only
shoaib_ahmed	0:791a779d6220	2505	16 bits. As a special case, setting length_limit to 0 prevents that marker
shoaib_ahmed	0:791a779d6220	2506	type from being saved at all. (That is the default behavior, in fact.)
shoaib_ahmed	0:791a779d6220	2507
shoaib_ahmed	0:791a779d6220	2508	After jpeg_read_header() completes, you can examine the special markers by
shoaib_ahmed	0:791a779d6220	2509	following the cinfo->marker_list pointer chain. All the special markers in
shoaib_ahmed	0:791a779d6220	2510	the file appear in this list, in order of their occurrence in the file (but
shoaib_ahmed	0:791a779d6220	2511	omitting any markers of types you didn't ask for). Both the original data
shoaib_ahmed	0:791a779d6220	2512	length and the saved data length are recorded for each list entry; the latter
shoaib_ahmed	0:791a779d6220	2513	will not exceed length_limit for the particular marker type. Note that these
shoaib_ahmed	0:791a779d6220	2514	lengths exclude the marker length word, whereas the stored representation
shoaib_ahmed	0:791a779d6220	2515	within the JPEG file includes it. (Hence the maximum data length is really
shoaib_ahmed	0:791a779d6220	2516	only 65533.)
shoaib_ahmed	0:791a779d6220	2517
shoaib_ahmed	0:791a779d6220	2518	It is possible that additional special markers appear in the file beyond the
shoaib_ahmed	0:791a779d6220	2519	SOS marker at which jpeg_read_header stops; if so, the marker list will be
shoaib_ahmed	0:791a779d6220	2520	extended during reading of the rest of the file. This is not expected to be
shoaib_ahmed	0:791a779d6220	2521	common, however. If you are short on memory you may want to reset the length
shoaib_ahmed	0:791a779d6220	2522	limit to zero for all marker types after finishing jpeg_read_header, to
shoaib_ahmed	0:791a779d6220	2523	ensure that the max_memory_to_use setting cannot be exceeded due to addition
shoaib_ahmed	0:791a779d6220	2524	of later markers.
shoaib_ahmed	0:791a779d6220	2525
shoaib_ahmed	0:791a779d6220	2526	The marker list remains stored until you call jpeg_finish_decompress or
shoaib_ahmed	0:791a779d6220	2527	jpeg_abort, at which point the memory is freed and the list is set to empty.
shoaib_ahmed	0:791a779d6220	2528	(jpeg_destroy also releases the storage, of course.)
shoaib_ahmed	0:791a779d6220	2529
shoaib_ahmed	0:791a779d6220	2530	Note that the library is internally interested in APP0 and APP14 markers;
shoaib_ahmed	0:791a779d6220	2531	if you try to set a small nonzero length limit on these types, the library
shoaib_ahmed	0:791a779d6220	2532	will silently force the length up to the minimum it wants. (But you can set
shoaib_ahmed	0:791a779d6220	2533	a zero length limit to prevent them from being saved at all.) Also, in a
shoaib_ahmed	0:791a779d6220	2534	16-bit environment, the maximum length limit may be constrained to less than
shoaib_ahmed	0:791a779d6220	2535	65533 by malloc() limitations. It is therefore best not to assume that the
shoaib_ahmed	0:791a779d6220	2536	effective length limit is exactly what you set it to be.
shoaib_ahmed	0:791a779d6220	2537
shoaib_ahmed	0:791a779d6220	2538
shoaib_ahmed	0:791a779d6220	2539	If you want to supply your own marker-reading routine, you do it by calling
shoaib_ahmed	0:791a779d6220	2540	jpeg_set_marker_processor(). A marker processor routine must have the
shoaib_ahmed	0:791a779d6220	2541	signature
shoaib_ahmed	0:791a779d6220	2542	boolean jpeg_marker_parser_method (j_decompress_ptr cinfo)
shoaib_ahmed	0:791a779d6220	2543	Although the marker code is not explicitly passed, the routine can find it
shoaib_ahmed	0:791a779d6220	2544	in cinfo->unread_marker. At the time of call, the marker proper has been
shoaib_ahmed	0:791a779d6220	2545	read from the data source module. The processor routine is responsible for
shoaib_ahmed	0:791a779d6220	2546	reading the marker length word and the remaining parameter bytes, if any.
shoaib_ahmed	0:791a779d6220	2547	Return TRUE to indicate success. (FALSE should be returned only if you are
shoaib_ahmed	0:791a779d6220	2548	using a suspending data source and it tells you to suspend. See the standard
shoaib_ahmed	0:791a779d6220	2549	marker processors in jdmarker.c for appropriate coding methods if you need to
shoaib_ahmed	0:791a779d6220	2550	use a suspending data source.)
shoaib_ahmed	0:791a779d6220	2551
shoaib_ahmed	0:791a779d6220	2552	If you override the default APP0 or APP14 processors, it is up to you to
shoaib_ahmed	0:791a779d6220	2553	recognize JFIF and Adobe markers if you want colorspace recognition to occur
shoaib_ahmed	0:791a779d6220	2554	properly. We recommend copying and extending the default processors if you
shoaib_ahmed	0:791a779d6220	2555	want to do that. (A better idea is to save these marker types for later
shoaib_ahmed	0:791a779d6220	2556	examination by calling jpeg_save_markers(); that method doesn't interfere
shoaib_ahmed	0:791a779d6220	2557	with the library's own processing of these markers.)
shoaib_ahmed	0:791a779d6220	2558
shoaib_ahmed	0:791a779d6220	2559	jpeg_set_marker_processor() and jpeg_save_markers() are mutually exclusive
shoaib_ahmed	0:791a779d6220	2560	--- if you call one it overrides any previous call to the other, for the
shoaib_ahmed	0:791a779d6220	2561	particular marker type specified.
shoaib_ahmed	0:791a779d6220	2562
shoaib_ahmed	0:791a779d6220	2563	A simple example of an external COM processor can be found in djpeg.c.
shoaib_ahmed	0:791a779d6220	2564	Also, see jpegtran.c for an example of using jpeg_save_markers.
shoaib_ahmed	0:791a779d6220	2565
shoaib_ahmed	0:791a779d6220	2566
shoaib_ahmed	0:791a779d6220	2567	Raw (downsampled) image data
shoaib_ahmed	0:791a779d6220	2568	----------------------------
shoaib_ahmed	0:791a779d6220	2569
shoaib_ahmed	0:791a779d6220	2570	Some applications need to supply already-downsampled image data to the JPEG
shoaib_ahmed	0:791a779d6220	2571	compressor, or to receive raw downsampled data from the decompressor. The
shoaib_ahmed	0:791a779d6220	2572	library supports this requirement by allowing the application to write or
shoaib_ahmed	0:791a779d6220	2573	read raw data, bypassing the normal preprocessing or postprocessing steps.
shoaib_ahmed	0:791a779d6220	2574	The interface is different from the standard one and is somewhat harder to
shoaib_ahmed	0:791a779d6220	2575	use. If your interest is merely in bypassing color conversion, we recommend
shoaib_ahmed	0:791a779d6220	2576	that you use the standard interface and simply set jpeg_color_space =
shoaib_ahmed	0:791a779d6220	2577	in_color_space (or jpeg_color_space = out_color_space for decompression).
shoaib_ahmed	0:791a779d6220	2578	The mechanism described in this section is necessary only to supply or
shoaib_ahmed	0:791a779d6220	2579	receive downsampled image data, in which not all components have the same
shoaib_ahmed	0:791a779d6220	2580	dimensions.
shoaib_ahmed	0:791a779d6220	2581
shoaib_ahmed	0:791a779d6220	2582
shoaib_ahmed	0:791a779d6220	2583	To compress raw data, you must supply the data in the colorspace to be used
shoaib_ahmed	0:791a779d6220	2584	in the JPEG file (please read the earlier section on Special color spaces)
shoaib_ahmed	0:791a779d6220	2585	and downsampled to the sampling factors specified in the JPEG parameters.
shoaib_ahmed	0:791a779d6220	2586	You must supply the data in the format used internally by the JPEG library,
shoaib_ahmed	0:791a779d6220	2587	namely a JSAMPIMAGE array. This is an array of pointers to two-dimensional
shoaib_ahmed	0:791a779d6220	2588	arrays, each of type JSAMPARRAY. Each 2-D array holds the values for one
shoaib_ahmed	0:791a779d6220	2589	color component. This structure is necessary since the components are of
shoaib_ahmed	0:791a779d6220	2590	different sizes. If the image dimensions are not a multiple of the MCU size,
shoaib_ahmed	0:791a779d6220	2591	you must also pad the data correctly (usually, this is done by replicating
shoaib_ahmed	0:791a779d6220	2592	the last column and/or row). The data must be padded to a multiple of a DCT
shoaib_ahmed	0:791a779d6220	2593	block in each component: that is, each downsampled row must contain a
shoaib_ahmed	0:791a779d6220	2594	multiple of block_size valid samples, and there must be a multiple of
shoaib_ahmed	0:791a779d6220	2595	block_size sample rows for each component. (For applications such as
shoaib_ahmed	0:791a779d6220	2596	conversion of digital TV images, the standard image size is usually a
shoaib_ahmed	0:791a779d6220	2597	multiple of the DCT block size, so that no padding need actually be done.)
shoaib_ahmed	0:791a779d6220	2598
shoaib_ahmed	0:791a779d6220	2599	The procedure for compression of raw data is basically the same as normal
shoaib_ahmed	0:791a779d6220	2600	compression, except that you call jpeg_write_raw_data() in place of
shoaib_ahmed	0:791a779d6220	2601	jpeg_write_scanlines(). Before calling jpeg_start_compress(), you must do
shoaib_ahmed	0:791a779d6220	2602	the following:
shoaib_ahmed	0:791a779d6220	2603	* Set cinfo->raw_data_in to TRUE. (It is set FALSE by jpeg_set_defaults().)
shoaib_ahmed	0:791a779d6220	2604	This notifies the library that you will be supplying raw data.
shoaib_ahmed	0:791a779d6220	2605	Furthermore, set cinfo->do_fancy_downsampling to FALSE if you want to use
shoaib_ahmed	0:791a779d6220	2606	real downsampled data. (It is set TRUE by jpeg_set_defaults().)
shoaib_ahmed	0:791a779d6220	2607	* Ensure jpeg_color_space is correct --- an explicit jpeg_set_colorspace()
shoaib_ahmed	0:791a779d6220	2608	call is a good idea. Note that since color conversion is bypassed,
shoaib_ahmed	0:791a779d6220	2609	in_color_space is ignored, except that jpeg_set_defaults() uses it to
shoaib_ahmed	0:791a779d6220	2610	choose the default jpeg_color_space setting.
shoaib_ahmed	0:791a779d6220	2611	* Ensure the sampling factors, cinfo->comp_info[i].h_samp_factor and
shoaib_ahmed	0:791a779d6220	2612	cinfo->comp_info[i].v_samp_factor, are correct. Since these indicate the
shoaib_ahmed	0:791a779d6220	2613	dimensions of the data you are supplying, it's wise to set them
shoaib_ahmed	0:791a779d6220	2614	explicitly, rather than assuming the library's defaults are what you want.
shoaib_ahmed	0:791a779d6220	2615
shoaib_ahmed	0:791a779d6220	2616	To pass raw data to the library, call jpeg_write_raw_data() in place of
shoaib_ahmed	0:791a779d6220	2617	jpeg_write_scanlines(). The two routines work similarly except that
shoaib_ahmed	0:791a779d6220	2618	jpeg_write_raw_data takes a JSAMPIMAGE data array rather than JSAMPARRAY.
shoaib_ahmed	0:791a779d6220	2619	The scanlines count passed to and returned from jpeg_write_raw_data is
shoaib_ahmed	0:791a779d6220	2620	measured in terms of the component with the largest v_samp_factor.
shoaib_ahmed	0:791a779d6220	2621
shoaib_ahmed	0:791a779d6220	2622	jpeg_write_raw_data() processes one MCU row per call, which is to say
shoaib_ahmed	0:791a779d6220	2623	v_samp_factor*block_size sample rows of each component. The passed num_lines
shoaib_ahmed	0:791a779d6220	2624	value must be at least max_v_samp_factor*block_size, and the return value
shoaib_ahmed	0:791a779d6220	2625	will be exactly that amount (or possibly some multiple of that amount, in
shoaib_ahmed	0:791a779d6220	2626	future library versions). This is true even on the last call at the bottom
shoaib_ahmed	0:791a779d6220	2627	of the image; don't forget to pad your data as necessary.
shoaib_ahmed	0:791a779d6220	2628
shoaib_ahmed	0:791a779d6220	2629	The required dimensions of the supplied data can be computed for each
shoaib_ahmed	0:791a779d6220	2630	component as
shoaib_ahmed	0:791a779d6220	2631	cinfo->comp_info[i].width_in_blocks*block_size samples per row
shoaib_ahmed	0:791a779d6220	2632	cinfo->comp_info[i].height_in_blocks*block_size rows in image
shoaib_ahmed	0:791a779d6220	2633	after jpeg_start_compress() has initialized those fields. If the valid data
shoaib_ahmed	0:791a779d6220	2634	is smaller than this, it must be padded appropriately. For some sampling
shoaib_ahmed	0:791a779d6220	2635	factors and image sizes, additional dummy DCT blocks are inserted to make
shoaib_ahmed	0:791a779d6220	2636	the image a multiple of the MCU dimensions. The library creates such dummy
shoaib_ahmed	0:791a779d6220	2637	blocks itself; it does not read them from your supplied data. Therefore you
shoaib_ahmed	0:791a779d6220	2638	need never pad by more than block_size samples. An example may help here.
shoaib_ahmed	0:791a779d6220	2639	Assume 2h2v downsampling of YCbCr data, that is
shoaib_ahmed	0:791a779d6220	2640	cinfo->comp_info[0].h_samp_factor = 2 for Y
shoaib_ahmed	0:791a779d6220	2641	cinfo->comp_info[0].v_samp_factor = 2
shoaib_ahmed	0:791a779d6220	2642	cinfo->comp_info[1].h_samp_factor = 1 for Cb
shoaib_ahmed	0:791a779d6220	2643	cinfo->comp_info[1].v_samp_factor = 1
shoaib_ahmed	0:791a779d6220	2644	cinfo->comp_info[2].h_samp_factor = 1 for Cr
shoaib_ahmed	0:791a779d6220	2645	cinfo->comp_info[2].v_samp_factor = 1
shoaib_ahmed	0:791a779d6220	2646	and suppose that the nominal image dimensions (cinfo->image_width and
shoaib_ahmed	0:791a779d6220	2647	cinfo->image_height) are 101x101 pixels. Then jpeg_start_compress() will
shoaib_ahmed	0:791a779d6220	2648	compute downsampled_width = 101 and width_in_blocks = 13 for Y,
shoaib_ahmed	0:791a779d6220	2649	downsampled_width = 51 and width_in_blocks = 7 for Cb and Cr (and the same
shoaib_ahmed	0:791a779d6220	2650	for the height fields). You must pad the Y data to at least 13*8 = 104
shoaib_ahmed	0:791a779d6220	2651	columns and rows, the Cb/Cr data to at least 7*8 = 56 columns and rows. The
shoaib_ahmed	0:791a779d6220	2652	MCU height is max_v_samp_factor = 2 DCT rows so you must pass at least 16
shoaib_ahmed	0:791a779d6220	2653	scanlines on each call to jpeg_write_raw_data(), which is to say 16 actual
shoaib_ahmed	0:791a779d6220	2654	sample rows of Y and 8 each of Cb and Cr. A total of 7 MCU rows are needed,
shoaib_ahmed	0:791a779d6220	2655	so you must pass a total of 7*16 = 112 "scanlines". The last DCT block row
shoaib_ahmed	0:791a779d6220	2656	of Y data is dummy, so it doesn't matter what you pass for it in the data
shoaib_ahmed	0:791a779d6220	2657	arrays, but the scanlines count must total up to 112 so that all of the Cb
shoaib_ahmed	0:791a779d6220	2658	and Cr data gets passed.
shoaib_ahmed	0:791a779d6220	2659
shoaib_ahmed	0:791a779d6220	2660	Output suspension is supported with raw-data compression: if the data
shoaib_ahmed	0:791a779d6220	2661	destination module suspends, jpeg_write_raw_data() will return 0.
shoaib_ahmed	0:791a779d6220	2662	In this case the same data rows must be passed again on the next call.
shoaib_ahmed	0:791a779d6220	2663
shoaib_ahmed	0:791a779d6220	2664
shoaib_ahmed	0:791a779d6220	2665	Decompression with raw data output implies bypassing all postprocessing.
shoaib_ahmed	0:791a779d6220	2666	You must deal with the color space and sampling factors present in the
shoaib_ahmed	0:791a779d6220	2667	incoming file. If your application only handles, say, 2h1v YCbCr data,
shoaib_ahmed	0:791a779d6220	2668	you must check for and fail on other color spaces or other sampling factors.
shoaib_ahmed	0:791a779d6220	2669	The library will not convert to a different color space for you.
shoaib_ahmed	0:791a779d6220	2670
shoaib_ahmed	0:791a779d6220	2671	To obtain raw data output, set cinfo->raw_data_out = TRUE before
shoaib_ahmed	0:791a779d6220	2672	jpeg_start_decompress() (it is set FALSE by jpeg_read_header()). Be sure to
shoaib_ahmed	0:791a779d6220	2673	verify that the color space and sampling factors are ones you can handle.
shoaib_ahmed	0:791a779d6220	2674	Furthermore, set cinfo->do_fancy_upsampling = FALSE if you want to get real
shoaib_ahmed	0:791a779d6220	2675	downsampled data (it is set TRUE by jpeg_read_header()).
shoaib_ahmed	0:791a779d6220	2676	Then call jpeg_read_raw_data() in place of jpeg_read_scanlines(). The
shoaib_ahmed	0:791a779d6220	2677	decompression process is otherwise the same as usual.
shoaib_ahmed	0:791a779d6220	2678
shoaib_ahmed	0:791a779d6220	2679	jpeg_read_raw_data() returns one MCU row per call, and thus you must pass a
shoaib_ahmed	0:791a779d6220	2680	buffer of at least max_v_samp_factor*block_size scanlines (scanline counting
shoaib_ahmed	0:791a779d6220	2681	is the same as for raw-data compression). The buffer you pass must be large
shoaib_ahmed	0:791a779d6220	2682	enough to hold the actual data plus padding to DCT-block boundaries. As with
shoaib_ahmed	0:791a779d6220	2683	compression, any entirely dummy DCT blocks are not processed so you need not
shoaib_ahmed	0:791a779d6220	2684	allocate space for them, but the total scanline count includes them. The
shoaib_ahmed	0:791a779d6220	2685	above example of computing buffer dimensions for raw-data compression is
shoaib_ahmed	0:791a779d6220	2686	equally valid for decompression.
shoaib_ahmed	0:791a779d6220	2687
shoaib_ahmed	0:791a779d6220	2688	Input suspension is supported with raw-data decompression: if the data source
shoaib_ahmed	0:791a779d6220	2689	module suspends, jpeg_read_raw_data() will return 0. You can also use
shoaib_ahmed	0:791a779d6220	2690	buffered-image mode to read raw data in multiple passes.
shoaib_ahmed	0:791a779d6220	2691
shoaib_ahmed	0:791a779d6220	2692
shoaib_ahmed	0:791a779d6220	2693	Really raw data: DCT coefficients
shoaib_ahmed	0:791a779d6220	2694	---------------------------------
shoaib_ahmed	0:791a779d6220	2695
shoaib_ahmed	0:791a779d6220	2696	It is possible to read or write the contents of a JPEG file as raw DCT
shoaib_ahmed	0:791a779d6220	2697	coefficients. This facility is mainly intended for use in lossless
shoaib_ahmed	0:791a779d6220	2698	transcoding between different JPEG file formats. Other possible applications
shoaib_ahmed	0:791a779d6220	2699	include lossless cropping of a JPEG image, lossless reassembly of a
shoaib_ahmed	0:791a779d6220	2700	multi-strip or multi-tile TIFF/JPEG file into a single JPEG datastream, etc.
shoaib_ahmed	0:791a779d6220	2701
shoaib_ahmed	0:791a779d6220	2702	To read the contents of a JPEG file as DCT coefficients, open the file and do
shoaib_ahmed	0:791a779d6220	2703	jpeg_read_header() as usual. But instead of calling jpeg_start_decompress()
shoaib_ahmed	0:791a779d6220	2704	and jpeg_read_scanlines(), call jpeg_read_coefficients(). This will read the
shoaib_ahmed	0:791a779d6220	2705	entire image into a set of virtual coefficient-block arrays, one array per
shoaib_ahmed	0:791a779d6220	2706	component. The return value is a pointer to an array of virtual-array
shoaib_ahmed	0:791a779d6220	2707	descriptors. Each virtual array can be accessed directly using the JPEG
shoaib_ahmed	0:791a779d6220	2708	memory manager's access_virt_barray method (see Memory management, below,
shoaib_ahmed	0:791a779d6220	2709	and also read structure.txt's discussion of virtual array handling). Or,
shoaib_ahmed	0:791a779d6220	2710	for simple transcoding to a different JPEG file format, the array list can
shoaib_ahmed	0:791a779d6220	2711	just be handed directly to jpeg_write_coefficients().
shoaib_ahmed	0:791a779d6220	2712
shoaib_ahmed	0:791a779d6220	2713	Each block in the block arrays contains quantized coefficient values in
shoaib_ahmed	0:791a779d6220	2714	normal array order (not JPEG zigzag order). The block arrays contain only
shoaib_ahmed	0:791a779d6220	2715	DCT blocks containing real data; any entirely-dummy blocks added to fill out
shoaib_ahmed	0:791a779d6220	2716	interleaved MCUs at the right or bottom edges of the image are discarded
shoaib_ahmed	0:791a779d6220	2717	during reading and are not stored in the block arrays. (The size of each
shoaib_ahmed	0:791a779d6220	2718	block array can be determined from the width_in_blocks and height_in_blocks
shoaib_ahmed	0:791a779d6220	2719	fields of the component's comp_info entry.) This is also the data format
shoaib_ahmed	0:791a779d6220	2720	expected by jpeg_write_coefficients().
shoaib_ahmed	0:791a779d6220	2721
shoaib_ahmed	0:791a779d6220	2722	When you are done using the virtual arrays, call jpeg_finish_decompress()
shoaib_ahmed	0:791a779d6220	2723	to release the array storage and return the decompression object to an idle
shoaib_ahmed	0:791a779d6220	2724	state; or just call jpeg_destroy() if you don't need to reuse the object.
shoaib_ahmed	0:791a779d6220	2725
shoaib_ahmed	0:791a779d6220	2726	If you use a suspending data source, jpeg_read_coefficients() will return
shoaib_ahmed	0:791a779d6220	2727	NULL if it is forced to suspend; a non-NULL return value indicates successful
shoaib_ahmed	0:791a779d6220	2728	completion. You need not test for a NULL return value when using a
shoaib_ahmed	0:791a779d6220	2729	non-suspending data source.
shoaib_ahmed	0:791a779d6220	2730
shoaib_ahmed	0:791a779d6220	2731	It is also possible to call jpeg_read_coefficients() to obtain access to the
shoaib_ahmed	0:791a779d6220	2732	decoder's coefficient arrays during a normal decode cycle in buffered-image
shoaib_ahmed	0:791a779d6220	2733	mode. This frammish might be useful for progressively displaying an incoming
shoaib_ahmed	0:791a779d6220	2734	image and then re-encoding it without loss. To do this, decode in buffered-
shoaib_ahmed	0:791a779d6220	2735	image mode as discussed previously, then call jpeg_read_coefficients() after
shoaib_ahmed	0:791a779d6220	2736	the last jpeg_finish_output() call. The arrays will be available for your use
shoaib_ahmed	0:791a779d6220	2737	until you call jpeg_finish_decompress().
shoaib_ahmed	0:791a779d6220	2738
shoaib_ahmed	0:791a779d6220	2739
shoaib_ahmed	0:791a779d6220	2740	To write the contents of a JPEG file as DCT coefficients, you must provide
shoaib_ahmed	0:791a779d6220	2741	the DCT coefficients stored in virtual block arrays. You can either pass
shoaib_ahmed	0:791a779d6220	2742	block arrays read from an input JPEG file by jpeg_read_coefficients(), or
shoaib_ahmed	0:791a779d6220	2743	allocate virtual arrays from the JPEG compression object and fill them
shoaib_ahmed	0:791a779d6220	2744	yourself. In either case, jpeg_write_coefficients() is substituted for
shoaib_ahmed	0:791a779d6220	2745	jpeg_start_compress() and jpeg_write_scanlines(). Thus the sequence is
shoaib_ahmed	0:791a779d6220	2746	* Create compression object
shoaib_ahmed	0:791a779d6220	2747	* Set all compression parameters as necessary
shoaib_ahmed	0:791a779d6220	2748	* Request virtual arrays if needed
shoaib_ahmed	0:791a779d6220	2749	* jpeg_write_coefficients()
shoaib_ahmed	0:791a779d6220	2750	* jpeg_finish_compress()
shoaib_ahmed	0:791a779d6220	2751	* Destroy or re-use compression object
shoaib_ahmed	0:791a779d6220	2752	jpeg_write_coefficients() is passed a pointer to an array of virtual block
shoaib_ahmed	0:791a779d6220	2753	array descriptors; the number of arrays is equal to cinfo.num_components.
shoaib_ahmed	0:791a779d6220	2754
shoaib_ahmed	0:791a779d6220	2755	The virtual arrays need only have been requested, not realized, before
shoaib_ahmed	0:791a779d6220	2756	jpeg_write_coefficients() is called. A side-effect of
shoaib_ahmed	0:791a779d6220	2757	jpeg_write_coefficients() is to realize any virtual arrays that have been
shoaib_ahmed	0:791a779d6220	2758	requested from the compression object's memory manager. Thus, when obtaining
shoaib_ahmed	0:791a779d6220	2759	the virtual arrays from the compression object, you should fill the arrays
shoaib_ahmed	0:791a779d6220	2760	after calling jpeg_write_coefficients(). The data is actually written out
shoaib_ahmed	0:791a779d6220	2761	when you call jpeg_finish_compress(); jpeg_write_coefficients() only writes
shoaib_ahmed	0:791a779d6220	2762	the file header.
shoaib_ahmed	0:791a779d6220	2763
shoaib_ahmed	0:791a779d6220	2764	When writing raw DCT coefficients, it is crucial that the JPEG quantization
shoaib_ahmed	0:791a779d6220	2765	tables and sampling factors match the way the data was encoded, or the
shoaib_ahmed	0:791a779d6220	2766	resulting file will be invalid. For transcoding from an existing JPEG file,
shoaib_ahmed	0:791a779d6220	2767	we recommend using jpeg_copy_critical_parameters(). This routine initializes
shoaib_ahmed	0:791a779d6220	2768	all the compression parameters to default values (like jpeg_set_defaults()),
shoaib_ahmed	0:791a779d6220	2769	then copies the critical information from a source decompression object.
shoaib_ahmed	0:791a779d6220	2770	The decompression object should have just been used to read the entire
shoaib_ahmed	0:791a779d6220	2771	JPEG input file --- that is, it should be awaiting jpeg_finish_decompress().
shoaib_ahmed	0:791a779d6220	2772
shoaib_ahmed	0:791a779d6220	2773	jpeg_write_coefficients() marks all tables stored in the compression object
shoaib_ahmed	0:791a779d6220	2774	as needing to be written to the output file (thus, it acts like
shoaib_ahmed	0:791a779d6220	2775	jpeg_start_compress(cinfo, TRUE)). This is for safety's sake, to avoid
shoaib_ahmed	0:791a779d6220	2776	emitting abbreviated JPEG files by accident. If you really want to emit an
shoaib_ahmed	0:791a779d6220	2777	abbreviated JPEG file, call jpeg_suppress_tables(), or set the tables'
shoaib_ahmed	0:791a779d6220	2778	individual sent_table flags, between calling jpeg_write_coefficients() and
shoaib_ahmed	0:791a779d6220	2779	jpeg_finish_compress().
shoaib_ahmed	0:791a779d6220	2780
shoaib_ahmed	0:791a779d6220	2781
shoaib_ahmed	0:791a779d6220	2782	Progress monitoring
shoaib_ahmed	0:791a779d6220	2783	-------------------
shoaib_ahmed	0:791a779d6220	2784
shoaib_ahmed	0:791a779d6220	2785	Some applications may need to regain control from the JPEG library every so
shoaib_ahmed	0:791a779d6220	2786	often. The typical use of this feature is to produce a percent-done bar or
shoaib_ahmed	0:791a779d6220	2787	other progress display. (For a simple example, see cjpeg.c or djpeg.c.)
shoaib_ahmed	0:791a779d6220	2788	Although you do get control back frequently during the data-transferring pass
shoaib_ahmed	0:791a779d6220	2789	(the jpeg_read_scanlines or jpeg_write_scanlines loop), any additional passes
shoaib_ahmed	0:791a779d6220	2790	will occur inside jpeg_finish_compress or jpeg_start_decompress; those
shoaib_ahmed	0:791a779d6220	2791	routines may take a long time to execute, and you don't get control back
shoaib_ahmed	0:791a779d6220	2792	until they are done.
shoaib_ahmed	0:791a779d6220	2793
shoaib_ahmed	0:791a779d6220	2794	You can define a progress-monitor routine which will be called periodically
shoaib_ahmed	0:791a779d6220	2795	by the library. No guarantees are made about how often this call will occur,
shoaib_ahmed	0:791a779d6220	2796	so we don't recommend you use it for mouse tracking or anything like that.
shoaib_ahmed	0:791a779d6220	2797	At present, a call will occur once per MCU row, scanline, or sample row
shoaib_ahmed	0:791a779d6220	2798	group, whichever unit is convenient for the current processing mode; so the
shoaib_ahmed	0:791a779d6220	2799	wider the image, the longer the time between calls. During the data
shoaib_ahmed	0:791a779d6220	2800	transferring pass, only one call occurs per call of jpeg_read_scanlines or
shoaib_ahmed	0:791a779d6220	2801	jpeg_write_scanlines, so don't pass a large number of scanlines at once if
shoaib_ahmed	0:791a779d6220	2802	you want fine resolution in the progress count. (If you really need to use
shoaib_ahmed	0:791a779d6220	2803	the callback mechanism for time-critical tasks like mouse tracking, you could
shoaib_ahmed	0:791a779d6220	2804	insert additional calls inside some of the library's inner loops.)
shoaib_ahmed	0:791a779d6220	2805
shoaib_ahmed	0:791a779d6220	2806	To establish a progress-monitor callback, create a struct jpeg_progress_mgr,
shoaib_ahmed	0:791a779d6220	2807	fill in its progress_monitor field with a pointer to your callback routine,
shoaib_ahmed	0:791a779d6220	2808	and set cinfo->progress to point to the struct. The callback will be called
shoaib_ahmed	0:791a779d6220	2809	whenever cinfo->progress is non-NULL. (This pointer is set to NULL by
shoaib_ahmed	0:791a779d6220	2810	jpeg_create_compress or jpeg_create_decompress; the library will not change
shoaib_ahmed	0:791a779d6220	2811	it thereafter. So if you allocate dynamic storage for the progress struct,
shoaib_ahmed	0:791a779d6220	2812	make sure it will live as long as the JPEG object does. Allocating from the
shoaib_ahmed	0:791a779d6220	2813	JPEG memory manager with lifetime JPOOL_PERMANENT will work nicely.) You
shoaib_ahmed	0:791a779d6220	2814	can use the same callback routine for both compression and decompression.
shoaib_ahmed	0:791a779d6220	2815
shoaib_ahmed	0:791a779d6220	2816	The jpeg_progress_mgr struct contains four fields which are set by the library:
shoaib_ahmed	0:791a779d6220	2817	long pass_counter; /* work units completed in this pass */
shoaib_ahmed	0:791a779d6220	2818	long pass_limit; /* total number of work units in this pass */
shoaib_ahmed	0:791a779d6220	2819	int completed_passes; /* passes completed so far */
shoaib_ahmed	0:791a779d6220	2820	int total_passes; /* total number of passes expected */
shoaib_ahmed	0:791a779d6220	2821	During any one pass, pass_counter increases from 0 up to (not including)
shoaib_ahmed	0:791a779d6220	2822	pass_limit; the step size is usually but not necessarily 1. The pass_limit
shoaib_ahmed	0:791a779d6220	2823	value may change from one pass to another. The expected total number of
shoaib_ahmed	0:791a779d6220	2824	passes is in total_passes, and the number of passes already completed is in
shoaib_ahmed	0:791a779d6220	2825	completed_passes. Thus the fraction of work completed may be estimated as
shoaib_ahmed	0:791a779d6220	2826	completed_passes + (pass_counter/pass_limit)
shoaib_ahmed	0:791a779d6220	2827	--------------------------------------------
shoaib_ahmed	0:791a779d6220	2828	total_passes
shoaib_ahmed	0:791a779d6220	2829	ignoring the fact that the passes may not be equal amounts of work.
shoaib_ahmed	0:791a779d6220	2830
shoaib_ahmed	0:791a779d6220	2831	When decompressing, pass_limit can even change within a pass, because it
shoaib_ahmed	0:791a779d6220	2832	depends on the number of scans in the JPEG file, which isn't always known in
shoaib_ahmed	0:791a779d6220	2833	advance. The computed fraction-of-work-done may jump suddenly (if the library
shoaib_ahmed	0:791a779d6220	2834	discovers it has overestimated the number of scans) or even decrease (in the
shoaib_ahmed	0:791a779d6220	2835	opposite case). It is not wise to put great faith in the work estimate.
shoaib_ahmed	0:791a779d6220	2836
shoaib_ahmed	0:791a779d6220	2837	When using the decompressor's buffered-image mode, the progress monitor work
shoaib_ahmed	0:791a779d6220	2838	estimate is likely to be completely unhelpful, because the library has no way
shoaib_ahmed	0:791a779d6220	2839	to know how many output passes will be demanded of it. Currently, the library
shoaib_ahmed	0:791a779d6220	2840	sets total_passes based on the assumption that there will be one more output
shoaib_ahmed	0:791a779d6220	2841	pass if the input file end hasn't yet been read (jpeg_input_complete() isn't
shoaib_ahmed	0:791a779d6220	2842	TRUE), but no more output passes if the file end has been reached when the
shoaib_ahmed	0:791a779d6220	2843	output pass is started. This means that total_passes will rise as additional
shoaib_ahmed	0:791a779d6220	2844	output passes are requested. If you have a way of determining the input file
shoaib_ahmed	0:791a779d6220	2845	size, estimating progress based on the fraction of the file that's been read
shoaib_ahmed	0:791a779d6220	2846	will probably be more useful than using the library's value.
shoaib_ahmed	0:791a779d6220	2847
shoaib_ahmed	0:791a779d6220	2848
shoaib_ahmed	0:791a779d6220	2849	Memory management
shoaib_ahmed	0:791a779d6220	2850	-----------------
shoaib_ahmed	0:791a779d6220	2851
shoaib_ahmed	0:791a779d6220	2852	This section covers some key facts about the JPEG library's built-in memory
shoaib_ahmed	0:791a779d6220	2853	manager. For more info, please read structure.txt's section about the memory
shoaib_ahmed	0:791a779d6220	2854	manager, and consult the source code if necessary.
shoaib_ahmed	0:791a779d6220	2855
shoaib_ahmed	0:791a779d6220	2856	All memory and temporary file allocation within the library is done via the
shoaib_ahmed	0:791a779d6220	2857	memory manager. If necessary, you can replace the "back end" of the memory
shoaib_ahmed	0:791a779d6220	2858	manager to control allocation yourself (for example, if you don't want the
shoaib_ahmed	0:791a779d6220	2859	library to use malloc() and free() for some reason).
shoaib_ahmed	0:791a779d6220	2860
shoaib_ahmed	0:791a779d6220	2861	Some data is allocated "permanently" and will not be freed until the JPEG
shoaib_ahmed	0:791a779d6220	2862	object is destroyed. Most data is allocated "per image" and is freed by
shoaib_ahmed	0:791a779d6220	2863	jpeg_finish_compress, jpeg_finish_decompress, or jpeg_abort. You can call the
shoaib_ahmed	0:791a779d6220	2864	memory manager yourself to allocate structures that will automatically be
shoaib_ahmed	0:791a779d6220	2865	freed at these times. Typical code for this is
shoaib_ahmed	0:791a779d6220	2866	ptr = (*cinfo->mem->alloc_small) ((j_common_ptr) cinfo, JPOOL_IMAGE, size);
shoaib_ahmed	0:791a779d6220	2867	Use JPOOL_PERMANENT to get storage that lasts as long as the JPEG object.
shoaib_ahmed	0:791a779d6220	2868	Use alloc_large instead of alloc_small for anything bigger than a few Kbytes.
shoaib_ahmed	0:791a779d6220	2869	There are also alloc_sarray and alloc_barray routines that automatically
shoaib_ahmed	0:791a779d6220	2870	build 2-D sample or block arrays.
shoaib_ahmed	0:791a779d6220	2871
shoaib_ahmed	0:791a779d6220	2872	The library's minimum space requirements to process an image depend on the
shoaib_ahmed	0:791a779d6220	2873	image's width, but not on its height, because the library ordinarily works
shoaib_ahmed	0:791a779d6220	2874	with "strip" buffers that are as wide as the image but just a few rows high.
shoaib_ahmed	0:791a779d6220	2875	Some operating modes (eg, two-pass color quantization) require full-image
shoaib_ahmed	0:791a779d6220	2876	buffers. Such buffers are treated as "virtual arrays": only the current strip
shoaib_ahmed	0:791a779d6220	2877	need be in memory, and the rest can be swapped out to a temporary file.
shoaib_ahmed	0:791a779d6220	2878
shoaib_ahmed	0:791a779d6220	2879	If you use the simplest memory manager back end (jmemnobs.c), then no
shoaib_ahmed	0:791a779d6220	2880	temporary files are used; virtual arrays are simply malloc()'d. Images bigger
shoaib_ahmed	0:791a779d6220	2881	than memory can be processed only if your system supports virtual memory.
shoaib_ahmed	0:791a779d6220	2882	The other memory manager back ends support temporary files of various flavors
shoaib_ahmed	0:791a779d6220	2883	and thus work in machines without virtual memory. They may also be useful on
shoaib_ahmed	0:791a779d6220	2884	Unix machines if you need to process images that exceed available swap space.
shoaib_ahmed	0:791a779d6220	2885
shoaib_ahmed	0:791a779d6220	2886	When using temporary files, the library will make the in-memory buffers for
shoaib_ahmed	0:791a779d6220	2887	its virtual arrays just big enough to stay within a "maximum memory" setting.
shoaib_ahmed	0:791a779d6220	2888	Your application can set this limit by setting cinfo->mem->max_memory_to_use
shoaib_ahmed	0:791a779d6220	2889	after creating the JPEG object. (Of course, there is still a minimum size for
shoaib_ahmed	0:791a779d6220	2890	the buffers, so the max-memory setting is effective only if it is bigger than
shoaib_ahmed	0:791a779d6220	2891	the minimum space needed.) If you allocate any large structures yourself, you
shoaib_ahmed	0:791a779d6220	2892	must allocate them before jpeg_start_compress() or jpeg_start_decompress() in
shoaib_ahmed	0:791a779d6220	2893	order to have them counted against the max memory limit. Also keep in mind
shoaib_ahmed	0:791a779d6220	2894	that space allocated with alloc_small() is ignored, on the assumption that
shoaib_ahmed	0:791a779d6220	2895	it's too small to be worth worrying about; so a reasonable safety margin
shoaib_ahmed	0:791a779d6220	2896	should be left when setting max_memory_to_use.
shoaib_ahmed	0:791a779d6220	2897
shoaib_ahmed	0:791a779d6220	2898	If you use the jmemname.c or jmemdos.c memory manager back end, it is
shoaib_ahmed	0:791a779d6220	2899	important to clean up the JPEG object properly to ensure that the temporary
shoaib_ahmed	0:791a779d6220	2900	files get deleted. (This is especially crucial with jmemdos.c, where the
shoaib_ahmed	0:791a779d6220	2901	"temporary files" may be extended-memory segments; if they are not freed,
shoaib_ahmed	0:791a779d6220	2902	DOS will require a reboot to recover the memory.) Thus, with these memory
shoaib_ahmed	0:791a779d6220	2903	managers, it's a good idea to provide a signal handler that will trap any
shoaib_ahmed	0:791a779d6220	2904	early exit from your program. The handler should call either jpeg_abort()
shoaib_ahmed	0:791a779d6220	2905	or jpeg_destroy() for any active JPEG objects. A handler is not needed with
shoaib_ahmed	0:791a779d6220	2906	jmemnobs.c, and shouldn't be necessary with jmemansi.c or jmemmac.c either,
shoaib_ahmed	0:791a779d6220	2907	since the C library is supposed to take care of deleting files made with
shoaib_ahmed	0:791a779d6220	2908	tmpfile().
shoaib_ahmed	0:791a779d6220	2909
shoaib_ahmed	0:791a779d6220	2910
shoaib_ahmed	0:791a779d6220	2911	Memory usage
shoaib_ahmed	0:791a779d6220	2912	------------
shoaib_ahmed	0:791a779d6220	2913
shoaib_ahmed	0:791a779d6220	2914	Working memory requirements while performing compression or decompression
shoaib_ahmed	0:791a779d6220	2915	depend on image dimensions, image characteristics (such as colorspace and
shoaib_ahmed	0:791a779d6220	2916	JPEG process), and operating mode (application-selected options).
shoaib_ahmed	0:791a779d6220	2917
shoaib_ahmed	0:791a779d6220	2918	As of v6b, the decompressor requires:
shoaib_ahmed	0:791a779d6220	2919	1. About 24K in more-or-less-fixed-size data. This varies a bit depending
shoaib_ahmed	0:791a779d6220	2920	on operating mode and image characteristics (particularly color vs.
shoaib_ahmed	0:791a779d6220	2921	grayscale), but it doesn't depend on image dimensions.
shoaib_ahmed	0:791a779d6220	2922	2. Strip buffers (of size proportional to the image width) for IDCT and
shoaib_ahmed	0:791a779d6220	2923	upsampling results. The worst case for commonly used sampling factors
shoaib_ahmed	0:791a779d6220	2924	is about 34 bytes * width in pixels for a color image. A grayscale image
shoaib_ahmed	0:791a779d6220	2925	only needs about 8 bytes per pixel column.
shoaib_ahmed	0:791a779d6220	2926	3. A full-image DCT coefficient buffer is needed to decode a multi-scan JPEG
shoaib_ahmed	0:791a779d6220	2927	file (including progressive JPEGs), or whenever you select buffered-image
shoaib_ahmed	0:791a779d6220	2928	mode. This takes 2 bytes/coefficient. At typical 2x2 sampling, that's
shoaib_ahmed	0:791a779d6220	2929	3 bytes per pixel for a color image. Worst case (1x1 sampling) requires
shoaib_ahmed	0:791a779d6220	2930	6 bytes/pixel. For grayscale, figure 2 bytes/pixel.
shoaib_ahmed	0:791a779d6220	2931	4. To perform 2-pass color quantization, the decompressor also needs a
shoaib_ahmed	0:791a779d6220	2932	128K color lookup table and a full-image pixel buffer (3 bytes/pixel).
shoaib_ahmed	0:791a779d6220	2933	This does not count any memory allocated by the application, such as a
shoaib_ahmed	0:791a779d6220	2934	buffer to hold the final output image.
shoaib_ahmed	0:791a779d6220	2935
shoaib_ahmed	0:791a779d6220	2936	The above figures are valid for 8-bit JPEG data precision and a machine with
shoaib_ahmed	0:791a779d6220	2937	32-bit ints. For 9-bit to 12-bit JPEG data, double the size of the strip
shoaib_ahmed	0:791a779d6220	2938	buffers and quantization pixel buffer. The "fixed-size" data will be
shoaib_ahmed	0:791a779d6220	2939	somewhat smaller with 16-bit ints, larger with 64-bit ints. Also, CMYK
shoaib_ahmed	0:791a779d6220	2940	or other unusual color spaces will require different amounts of space.
shoaib_ahmed	0:791a779d6220	2941
shoaib_ahmed	0:791a779d6220	2942	The full-image coefficient and pixel buffers, if needed at all, do not
shoaib_ahmed	0:791a779d6220	2943	have to be fully RAM resident; you can have the library use temporary
shoaib_ahmed	0:791a779d6220	2944	files instead when the total memory usage would exceed a limit you set.
shoaib_ahmed	0:791a779d6220	2945	(But if your OS supports virtual memory, it's probably better to just use
shoaib_ahmed	0:791a779d6220	2946	jmemnobs and let the OS do the swapping.)
shoaib_ahmed	0:791a779d6220	2947
shoaib_ahmed	0:791a779d6220	2948	The compressor's memory requirements are similar, except that it has no need
shoaib_ahmed	0:791a779d6220	2949	for color quantization. Also, it needs a full-image DCT coefficient buffer
shoaib_ahmed	0:791a779d6220	2950	if Huffman-table optimization is asked for, even if progressive mode is not
shoaib_ahmed	0:791a779d6220	2951	requested.
shoaib_ahmed	0:791a779d6220	2952
shoaib_ahmed	0:791a779d6220	2953	If you need more detailed information about memory usage in a particular
shoaib_ahmed	0:791a779d6220	2954	situation, you can enable the MEM_STATS code in jmemmgr.c.
shoaib_ahmed	0:791a779d6220	2955
shoaib_ahmed	0:791a779d6220	2956
shoaib_ahmed	0:791a779d6220	2957	Library compile-time options
shoaib_ahmed	0:791a779d6220	2958	----------------------------
shoaib_ahmed	0:791a779d6220	2959
shoaib_ahmed	0:791a779d6220	2960	A number of compile-time options are available by modifying jmorecfg.h.
shoaib_ahmed	0:791a779d6220	2961
shoaib_ahmed	0:791a779d6220	2962	The IJG code currently supports 8-bit to 12-bit sample data precision by
shoaib_ahmed	0:791a779d6220	2963	defining BITS_IN_JSAMPLE as 8, 9, 10, 11, or 12.
shoaib_ahmed	0:791a779d6220	2964	Note that a value larger than 8 causes JSAMPLE to be larger than a char,
shoaib_ahmed	0:791a779d6220	2965	so it affects the surrounding application's image data.
shoaib_ahmed	0:791a779d6220	2966	The sample applications cjpeg and djpeg can support deeper than 8-bit data
shoaib_ahmed	0:791a779d6220	2967	only for PPM and GIF file formats; you must disable the other file formats
shoaib_ahmed	0:791a779d6220	2968	to compile a 9-bit to 12-bit cjpeg or djpeg. (install.txt has more
shoaib_ahmed	0:791a779d6220	2969	information about that.)
shoaib_ahmed	0:791a779d6220	2970	Run-time selection and conversion of data precision are currently not
shoaib_ahmed	0:791a779d6220	2971	supported and may be added later.
shoaib_ahmed	0:791a779d6220	2972	Exception: The transcoding part (jpegtran) supports all settings in a
shoaib_ahmed	0:791a779d6220	2973	single instance, since it operates on the level of DCT coefficients and
shoaib_ahmed	0:791a779d6220	2974	not sample values.
shoaib_ahmed	0:791a779d6220	2975	(If you need to include an 8-bit library and a 9-bit to 12-bit library for
shoaib_ahmed	0:791a779d6220	2976	compression or decompression in a single application, you could probably do
shoaib_ahmed	0:791a779d6220	2977	it by defining NEED_SHORT_EXTERNAL_NAMES for just one of the copies. You'd
shoaib_ahmed	0:791a779d6220	2978	have to access the 8-bit and the 9-bit to 12-bit copies from separate
shoaib_ahmed	0:791a779d6220	2979	application source files. This is untested ... if you try it, we'd like to
shoaib_ahmed	0:791a779d6220	2980	hear whether it works!)
shoaib_ahmed	0:791a779d6220	2981
shoaib_ahmed	0:791a779d6220	2982	Note that the standard Huffman tables are only valid for 8-bit data precision.
shoaib_ahmed	0:791a779d6220	2983	If you selected more than 8-bit data precision, cjpeg uses arithmetic coding
shoaib_ahmed	0:791a779d6220	2984	by default. The Huffman encoder normally uses entropy optimization to
shoaib_ahmed	0:791a779d6220	2985	compute usable tables for higher precision. Otherwise, you'll have to
shoaib_ahmed	0:791a779d6220	2986	supply different default Huffman tables. You may also want to supply your
shoaib_ahmed	0:791a779d6220	2987	own DCT quantization tables; the existing quality-scaling code has been
shoaib_ahmed	0:791a779d6220	2988	developed for 8-bit use, and probably doesn't generate especially good tables
shoaib_ahmed	0:791a779d6220	2989	for 9-bit to 12-bit.
shoaib_ahmed	0:791a779d6220	2990
shoaib_ahmed	0:791a779d6220	2991	The maximum number of components (color channels) in the image is determined
shoaib_ahmed	0:791a779d6220	2992	by MAX_COMPONENTS. The JPEG standard allows up to 255 components, but we
shoaib_ahmed	0:791a779d6220	2993	expect that few applications will need more than four or so.
shoaib_ahmed	0:791a779d6220	2994
shoaib_ahmed	0:791a779d6220	2995	On machines with unusual data type sizes, you may be able to improve
shoaib_ahmed	0:791a779d6220	2996	performance or reduce memory space by tweaking the various typedefs in
shoaib_ahmed	0:791a779d6220	2997	jmorecfg.h. In particular, on some RISC CPUs, access to arrays of "short"s
shoaib_ahmed	0:791a779d6220	2998	is quite slow; consider trading memory for speed by making JCOEF, INT16, and
shoaib_ahmed	0:791a779d6220	2999	UINT16 be "int" or "unsigned int". UINT8 is also a candidate to become int.
shoaib_ahmed	0:791a779d6220	3000	You probably don't want to make JSAMPLE be int unless you have lots of memory
shoaib_ahmed	0:791a779d6220	3001	to burn.
shoaib_ahmed	0:791a779d6220	3002
shoaib_ahmed	0:791a779d6220	3003	You can reduce the size of the library by compiling out various optional
shoaib_ahmed	0:791a779d6220	3004	functions. To do this, undefine xxx_SUPPORTED symbols as necessary.
shoaib_ahmed	0:791a779d6220	3005
shoaib_ahmed	0:791a779d6220	3006	You can also save a few K by not having text error messages in the library;
shoaib_ahmed	0:791a779d6220	3007	the standard error message table occupies about 5Kb. This is particularly
shoaib_ahmed	0:791a779d6220	3008	reasonable for embedded applications where there's no good way to display
shoaib_ahmed	0:791a779d6220	3009	a message anyway. To do this, remove the creation of the message table
shoaib_ahmed	0:791a779d6220	3010	(jpeg_std_message_table[]) from jerror.c, and alter format_message to do
shoaib_ahmed	0:791a779d6220	3011	something reasonable without it. You could output the numeric value of the
shoaib_ahmed	0:791a779d6220	3012	message code number, for example. If you do this, you can also save a couple
shoaib_ahmed	0:791a779d6220	3013	more K by modifying the TRACEMSn() macros in jerror.h to expand to nothing;
shoaib_ahmed	0:791a779d6220	3014	you don't need trace capability anyway, right?
shoaib_ahmed	0:791a779d6220	3015
shoaib_ahmed	0:791a779d6220	3016
shoaib_ahmed	0:791a779d6220	3017	Portability considerations
shoaib_ahmed	0:791a779d6220	3018	--------------------------
shoaib_ahmed	0:791a779d6220	3019
shoaib_ahmed	0:791a779d6220	3020	The JPEG library has been written to be extremely portable; the sample
shoaib_ahmed	0:791a779d6220	3021	applications cjpeg and djpeg are slightly less so. This section summarizes
shoaib_ahmed	0:791a779d6220	3022	the design goals in this area. (If you encounter any bugs that cause the
shoaib_ahmed	0:791a779d6220	3023	library to be less portable than is claimed here, we'd appreciate hearing
shoaib_ahmed	0:791a779d6220	3024	about them.)
shoaib_ahmed	0:791a779d6220	3025
shoaib_ahmed	0:791a779d6220	3026	The code works fine on ANSI C, C++, and pre-ANSI C compilers, using any of
shoaib_ahmed	0:791a779d6220	3027	the popular system include file setups, and some not-so-popular ones too.
shoaib_ahmed	0:791a779d6220	3028	See install.txt for configuration procedures.
shoaib_ahmed	0:791a779d6220	3029
shoaib_ahmed	0:791a779d6220	3030	The code is not dependent on the exact sizes of the C data types. As
shoaib_ahmed	0:791a779d6220	3031	distributed, we make the assumptions that
shoaib_ahmed	0:791a779d6220	3032	char is at least 8 bits wide
shoaib_ahmed	0:791a779d6220	3033	short is at least 16 bits wide
shoaib_ahmed	0:791a779d6220	3034	int is at least 16 bits wide
shoaib_ahmed	0:791a779d6220	3035	long is at least 32 bits wide
shoaib_ahmed	0:791a779d6220	3036	(These are the minimum requirements of the ANSI C standard.) Wider types will
shoaib_ahmed	0:791a779d6220	3037	work fine, although memory may be used inefficiently if char is much larger
shoaib_ahmed	0:791a779d6220	3038	than 8 bits or short is much bigger than 16 bits. The code should work
shoaib_ahmed	0:791a779d6220	3039	equally well with 16- or 32-bit ints.
shoaib_ahmed	0:791a779d6220	3040
shoaib_ahmed	0:791a779d6220	3041	In a system where these assumptions are not met, you may be able to make the
shoaib_ahmed	0:791a779d6220	3042	code work by modifying the typedefs in jmorecfg.h. However, you will probably
shoaib_ahmed	0:791a779d6220	3043	have difficulty if int is less than 16 bits wide, since references to plain
shoaib_ahmed	0:791a779d6220	3044	int abound in the code.
shoaib_ahmed	0:791a779d6220	3045
shoaib_ahmed	0:791a779d6220	3046	char can be either signed or unsigned, although the code runs faster if an
shoaib_ahmed	0:791a779d6220	3047	unsigned char type is available. If char is wider than 8 bits, you will need
shoaib_ahmed	0:791a779d6220	3048	to redefine JOCTET and/or provide custom data source/destination managers so
shoaib_ahmed	0:791a779d6220	3049	that JOCTET represents exactly 8 bits of data on external storage.
shoaib_ahmed	0:791a779d6220	3050
shoaib_ahmed	0:791a779d6220	3051	The JPEG library proper does not assume ASCII representation of characters.
shoaib_ahmed	0:791a779d6220	3052	But some of the image file I/O modules in cjpeg/djpeg do have ASCII
shoaib_ahmed	0:791a779d6220	3053	dependencies in file-header manipulation; so does cjpeg's select_file_type()
shoaib_ahmed	0:791a779d6220	3054	routine.
shoaib_ahmed	0:791a779d6220	3055
shoaib_ahmed	0:791a779d6220	3056	The JPEG library does not rely heavily on the C library. In particular, C
shoaib_ahmed	0:791a779d6220	3057	stdio is used only by the data source/destination modules and the error
shoaib_ahmed	0:791a779d6220	3058	handler, all of which are application-replaceable. (cjpeg/djpeg are more
shoaib_ahmed	0:791a779d6220	3059	heavily dependent on stdio.) malloc and free are called only from the memory
shoaib_ahmed	0:791a779d6220	3060	manager "back end" module, so you can use a different memory allocator by
shoaib_ahmed	0:791a779d6220	3061	replacing that one file.
shoaib_ahmed	0:791a779d6220	3062
shoaib_ahmed	0:791a779d6220	3063	The code generally assumes that C names must be unique in the first 15
shoaib_ahmed	0:791a779d6220	3064	characters. However, global function names can be made unique in the
shoaib_ahmed	0:791a779d6220	3065	first 6 characters by defining NEED_SHORT_EXTERNAL_NAMES.
shoaib_ahmed	0:791a779d6220	3066
shoaib_ahmed	0:791a779d6220	3067	More info about porting the code may be gleaned by reading jconfig.txt,
shoaib_ahmed	0:791a779d6220	3068	jmorecfg.h, and jinclude.h.
shoaib_ahmed	0:791a779d6220	3069
shoaib_ahmed	0:791a779d6220	3070
shoaib_ahmed	0:791a779d6220	3071	Notes for MS-DOS implementors
shoaib_ahmed	0:791a779d6220	3072	-----------------------------
shoaib_ahmed	0:791a779d6220	3073
shoaib_ahmed	0:791a779d6220	3074	The IJG code is designed to work efficiently in 80x86 "small" or "medium"
shoaib_ahmed	0:791a779d6220	3075	memory models (i.e., data pointers are 16 bits unless explicitly declared
shoaib_ahmed	0:791a779d6220	3076	"far"; code pointers can be either size). You may be able to use small
shoaib_ahmed	0:791a779d6220	3077	model to compile cjpeg or djpeg by itself, but you will probably have to use
shoaib_ahmed	0:791a779d6220	3078	medium model for any larger application. This won't make much difference in
shoaib_ahmed	0:791a779d6220	3079	performance. You will take a noticeable performance hit if you use a
shoaib_ahmed	0:791a779d6220	3080	large-data memory model (perhaps 10%-25%), and you should avoid "huge" model
shoaib_ahmed	0:791a779d6220	3081	if at all possible.
shoaib_ahmed	0:791a779d6220	3082
shoaib_ahmed	0:791a779d6220	3083	The JPEG library typically needs 2Kb-3Kb of stack space. It will also
shoaib_ahmed	0:791a779d6220	3084	malloc about 20K-30K of near heap space while executing (and lots of far
shoaib_ahmed	0:791a779d6220	3085	heap, but that doesn't count in this calculation). This figure will vary
shoaib_ahmed	0:791a779d6220	3086	depending on selected operating mode, and to a lesser extent on image size.
shoaib_ahmed	0:791a779d6220	3087	There is also about 5Kb-6Kb of constant data which will be allocated in the
shoaib_ahmed	0:791a779d6220	3088	near data segment (about 4Kb of this is the error message table).
shoaib_ahmed	0:791a779d6220	3089	Thus you have perhaps 20K available for other modules' static data and near
shoaib_ahmed	0:791a779d6220	3090	heap space before you need to go to a larger memory model. The C library's
shoaib_ahmed	0:791a779d6220	3091	static data will account for several K of this, but that still leaves a good
shoaib_ahmed	0:791a779d6220	3092	deal for your needs. (If you are tight on space, you could reduce the sizes
shoaib_ahmed	0:791a779d6220	3093	of the I/O buffers allocated by jdatasrc.c and jdatadst.c, say from 4K to
shoaib_ahmed	0:791a779d6220	3094	1K. Another possibility is to move the error message table to far memory;
shoaib_ahmed	0:791a779d6220	3095	this should be doable with only localized hacking on jerror.c.)
shoaib_ahmed	0:791a779d6220	3096
shoaib_ahmed	0:791a779d6220	3097	About 2K of the near heap space is "permanent" memory that will not be
shoaib_ahmed	0:791a779d6220	3098	released until you destroy the JPEG object. This is only an issue if you
shoaib_ahmed	0:791a779d6220	3099	save a JPEG object between compression or decompression operations.
shoaib_ahmed	0:791a779d6220	3100
shoaib_ahmed	0:791a779d6220	3101	Far data space may also be a tight resource when you are dealing with large
shoaib_ahmed	0:791a779d6220	3102	images. The most memory-intensive case is decompression with two-pass color
shoaib_ahmed	0:791a779d6220	3103	quantization, or single-pass quantization to an externally supplied color
shoaib_ahmed	0:791a779d6220	3104	map. This requires a 128Kb color lookup table plus strip buffers amounting
shoaib_ahmed	0:791a779d6220	3105	to about 40 bytes per column for typical sampling ratios (eg, about 25600
shoaib_ahmed	0:791a779d6220	3106	bytes for a 640-pixel-wide image). You may not be able to process wide
shoaib_ahmed	0:791a779d6220	3107	images if you have large data structures of your own.
shoaib_ahmed	0:791a779d6220	3108
shoaib_ahmed	0:791a779d6220	3109	Of course, all of these concerns vanish if you use a 32-bit flat-memory-model
shoaib_ahmed	0:791a779d6220	3110	compiler, such as DJGPP or Watcom C. We highly recommend flat model if you
shoaib_ahmed	0:791a779d6220	3111	can use it; the JPEG library is significantly faster in flat model.

Repository toolbox

Export to desktop IDE

Build repository

Repository details

Type:	Program
Mbed OS support:	Mbed 2 deprecated
Created:	31 Jul 2017
Imports:	1
Forks:	0
Commits:	1
Dependents:	0
Dependencies:	7
Followers:	1

includes/libjpeg.txt@0:791a779d6220, 2017-07-31 (annotated)

Who changed what in which revision?

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning