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