c/libjpeg-turbo
1
0
Fork 0
mirror of https://github.com/libjpeg-turbo/libjpeg-turbo synced 2025-03-28 21:13:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into dev

Browse Source
This commit is contained in:
DRC 2024-06-24 22:16:07 -04:00
commit 55bcad88e1
25 changed files with 465 additions and 362 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
CMakeLists.txt
View File

@ -309,12 +309,12 @@ endif()
# 1: + In-memory source/destination managers (libjpeg-turbo 1.3.x)
# 2: + Partial image decompression functions (libjpeg-turbo 1.5.x)
# 3: + ICC functions (libjpeg-turbo 2.0.x)
# 4: + 12-bit-per-component and lossless functions (libjpeg-turbo 2.2.x)
# 4: + 12-bit-per-sample and lossless functions (libjpeg-turbo 2.2.x)
#
# libjpeg v8 API/ABI emulation:
# 1: + Partial image decompression functions (libjpeg-turbo 1.5.x)
# 2: + ICC functions (libjpeg-turbo 2.0.x)
# 3: + 12-bit-per-component and lossless functions (libjpeg-turbo 2.2.x)
# 3: + 12-bit-per-sample and lossless functions (libjpeg-turbo 2.2.x)
set(SO_AGE 3)
if(NOT WITH_JPEG8)
set(SO_AGE 4)

13
ChangeLog.md
View File

@ -25,12 +25,21 @@ type.
2. Hardened the default marker processor in the decompressor to guard against
an issue (exposed by 3.0 beta2[6]) whereby attempting to decompress a
specially-crafted malformed JPEG image (specifically an image with a complete
12-bit-per-component Start Of Frame segment followed by an incomplete
8-bit-per-component Start Of Frame segment) using buffered-image mode and input
12-bit-per-sample Start Of Frame segment followed by an incomplete
8-bit-per-sample Start Of Frame segment) using buffered-image mode and input
prefetching caused a segfault if the `fill_input_buffer()` method in the
calling application's custom source manager incorrectly returned `FALSE` in
response to a prematurely-terminated JPEG data stream.
3. Fixed an issue in cjpeg whereby, when generating a 12-bit-per-sample or
16-bit-per-sample lossless JPEG image, specifying a point transform value
greater than 7 resulted in an error ("Invalid progressive/lossless parameters")
unless the `-precision` option was specified before the `-lossless` option.
4. Fixed a regression introduced by 3.0.3[3] that made it impossible for
calling applications to generate 12-bit-per-sample arithmetic-coded lossy JPEG
images using the TurboJPEG API.
3.0.3
=====

6
README.ijg
View File

@ -91,9 +91,9 @@ The library is intended to be reused in other applications.
In order to support file conversion and viewing software, we have included
considerable functionality beyond the bare JPEG coding/decoding capability;
for example, the color quantization modules are not strictly part of JPEG
decoding, but they are essential for output to colormapped file formats or
colormapped displays. These extra functions can be compiled out of the
library if not required for a particular application.
decoding, but they are essential for output to colormapped file formats. These
extra functions can be compiled out of the library if not required for a
particular application.
We have also included "jpegtran", a utility for lossless transcoding between
different JPEG processes, and "rdjpgcom" and "wrjpgcom", two simple

81
doc/cjpeg.1
View File

@ -1,4 +1,4 @@
.TH CJPEG 1 "14 Dec 2023"
.TH CJPEG 1 "24 June 2024"
.SH NAME
cjpeg \- compress an image file to a JPEG file
.SH SYNOPSIS
@ -16,7 +16,8 @@ cjpeg \- compress an image file to a JPEG file
compresses the named image file, or the standard input if no file is
named, and produces a JPEG/JFIF file on the standard output.
The currently supported input file formats are: PPM (PBMPLUS color
format), PGM (PBMPLUS grayscale format), BMP, GIF, and Targa.
format), PGM (PBMPLUS grayscale format), BMP, GIF [legacy feature], and Targa
[legacy feature].
.SH OPTIONS
All switch names may be abbreviated; for example,
.B \-grayscale
@ -29,7 +30,7 @@ Upper and lower case are equivalent (thus
.B \-BMP
is the same as
.BR \-bmp ).
British spellings are also accepted (e.g.,
British spellings are also accepted (e.g.
.BR \-greyscale ),
though for brevity these are not mentioned below.
.PP
@ -40,13 +41,12 @@ Scale quantization tables to adjust image quality. Quality is 0 (worst) to
100 (best); default is 75. (See below for more info.)
.TP
.B \-grayscale
Create monochrome JPEG file from color input. By saying
Create monochrome JPEG file from color input. By specifying
.BR \-grayscale,
you'll get a smaller JPEG file that takes less time to process.
.TP
.B \-rgb
Create RGB JPEG file.
Using this switch suppresses the conversion from RGB
Create RGB JPEG file. Using this switch suppresses the conversion from RGB
colorspace input to the default YCbCr JPEG colorspace.
.TP
.B \-optimize
@ -60,18 +60,22 @@ decompression are unaffected by
.BR \-optimize .
.TP
.B \-progressive
Create progressive JPEG file (see below).
Create progressive JPEG file (see below). Implies
.B \-optimize
unless
.B \-arithmetic
is also specified.
.TP
.B \-targa
Input file is Targa format. Targa files that contain an "identification"
field will not be automatically recognized by
.BR cjpeg ;
for such files you must specify
Input file is Targa format [legacy feature]. Targa files that contain an
"identification" field will not be automatically recognized by
.BR cjpeg .
For such files, you must specify
.B \-targa
to make
.B cjpeg
treat the input as Targa format.
For most Targa files, you won't need this switch.
treat the input as Targa format. For most Targa files, you won't need this
switch.
.PP
The
.B \-quality
@ -153,10 +157,28 @@ Switches for advanced users:
Create JPEG file with N-bit data precision. N is 8, 12, or 16; default is 8.
If N is 16, then
.B -lossless
must also be specified.
must also be specified. Note that only the PBMPLUS input file format supports
data precisions other than 8. (For historical reasons,
.B cjpeg
allows GIF input files to be converted into 12-bit-per-sample JPEG files, but
this is not a useful conversion.) Note also that PBMPLUS input files are
silently scaled to the target data precision, even if it is lower than the
precision of the input file. Passing an argument of
.B \-verbose
to
.B cjpeg
will cause it to print information about the precision of the input file.
.B Caution:
12-bit and 16-bit JPEG is not yet widely implemented, so many decoders will be
unable to view a 12-bit or 16-bit JPEG file at all.
12-bit and 16-bit data precision is not yet widely implemented, so many
decoders will be unable to handle a 12-bit-per-sample or 16-bit-per-sample JPEG
file at all.
.IP
.B \-precision\ 12
implies
.B \-optimize
unless
.B \-arithmetic
is also specified.
.TP
.BI \-lossless " psv[,Pt]"
Create a lossless JPEG file using the specified predictor selection value
@ -174,11 +196,11 @@ non-zero point transform value right-shifts the input samples by the specified
number of bits, which is effectively a form of lossy color quantization.)
.B Caution:
lossless JPEG is not yet widely implemented, so many decoders will be unable to
view a lossless JPEG file at all. In most cases, compressing and decompressing
a lossless JPEG file is considerably slower than compressing and decompressing
a lossy JPEG file, and lossless JPEG files are much larger than lossy JPEG
files. Also note that the following features will be unavailable when
compressing or decompressing a lossless JPEG file:
handle a lossless JPEG file at all. In most cases, compressing and
decompressing a lossless JPEG file is considerably slower than compressing and
decompressing a lossy JPEG file, and lossless JPEG files are much larger than
lossy JPEG files. Also note that the following features will be unavailable
when compressing or decompressing a lossless JPEG file:
.IP
- Quality/quantization table selection
.IP
@ -205,8 +227,8 @@ Any switches used to enable or configure those features will be ignored.
.B \-arithmetic
Use arithmetic coding.
.B Caution:
arithmetic coded JPEG is not yet widely implemented, so many decoders will be
unable to view an arithmetic coded JPEG file at all.
arithmetic-coded JPEG is not yet widely implemented, so many decoders will be
unable to handle an arithmetic-coded JPEG file at all.
.TP
.B \-dct int
Use accurate integer DCT method (default).
@ -349,10 +371,10 @@ This example compresses the PPM file foo.ppm with a quality factor of
.I foo.jpg
.SH HINTS
Color GIF files are not the ideal input for JPEG; JPEG is really intended for
compressing full-color (24-bit) images. In particular, don't try to convert
cartoons, line drawings, and other images that have only a few distinct
colors. GIF works great on these, JPEG does not. If you want to convert a
GIF to JPEG, you should experiment with
compressing full-color (24-bit through 48-bit) images. In particular, don't
try to convert cartoons, line drawings, and other images that have only a few
distinct colors. GIF works great on these; JPEG does not. If you want to
convert a GIF to JPEG, you should experiment with
.BR cjpeg 's
.B \-quality
and
@ -407,8 +429,3 @@ relevant to libjpeg-turbo, to wordsmith certain sections, and to describe
features not present in libjpeg.
.SH ISSUES
Not all variants of BMP and Targa file formats are supported.
.PP
The
.B \-targa
switch is not a bug, it's a feature. (It would be a bug if the Targa format
designers had not been clueless.)

129
doc/djpeg.1
View File

@ -1,4 +1,4 @@
.TH DJPEG 1 "4 November 2020"
.TH DJPEG 1 "17 June 2024"
.SH NAME
djpeg \- decompress a JPEG file to an image file
.SH SYNOPSIS
@ -28,47 +28,46 @@ Upper and lower case are equivalent (thus
.B \-BMP
is the same as
.BR \-bmp ).
British spellings are also accepted (e.g.,
British spellings are also accepted (e.g.
.BR \-greyscale ),
though for brevity these are not mentioned below.
.PP
The basic switches are:
.TP
.BI \-colors " N"
Reduce image to at most N colors. This reduces the number of colors used in
the output image, so that it can be displayed on a colormapped display or
stored in a colormapped file format. For example, if you have an 8-bit
display, you'd need to reduce to 256 or fewer colors.
Reduce image to at most N colors [legacy feature]. This reduces the number of
colors used in the output image so that it can be stored in a colormapped file
format. This feature cannot be used when decompressing lossless JPEG images.
.TP
.BI \-quantize " N"
Same as
.BR \-colors .
.B \-colors
is the recommended name,
is the recommended name.
.B \-quantize
is provided only for backwards compatibility.
is provided only for backward compatibility.
.TP
.B \-fast
Select recommended processing options for fast, low quality output. (The
default options are chosen for highest quality output.) Currently, this is
equivalent to \fB\-dct fast \-nosmooth \-onepass \-dither ordered\fR.
Select recommended processing options for low-quality output [legacy feature].
(The default options are chosen for highest-quality output.) Currently, this
is equivalent to \fB\-dct fast \-nosmooth \-onepass \-dither ordered\fR. On
modern CPUs, these settings have little or no performance benefit and are
retained solely for backward compatibility.
.TP
.B \-grayscale
Force grayscale output even if JPEG file is color. Useful for viewing on
monochrome displays; also,
.B djpeg
runs noticeably faster in this mode.
Force grayscale output even if JPEG file is full-color. This feature cannot be
used when decompressing full-color lossless JPEG images.
.TP
.B \-rgb
Force RGB output even if JPEG file is grayscale.
Force RGB output even if JPEG file is grayscale. This feature cannot be used
when decompressing grayscale lossless JPEG images.
.TP
.BI \-scale " M/N"
Scale the output image by a factor M/N. Currently the scale factor must be
M/8, where M is an integer between 1 and 16 inclusive, or any reduced fraction
thereof (such as 1/2, 3/4, etc.) Scaling is handy if the image is larger than
your screen; also,
.B djpeg
runs much faster when scaling down the output.
your screen. This feature cannot be used when decompressing lossless JPEG
images.
.TP
.B \-bmp
Select BMP output format (Windows flavor). 8-bit colormapped format is
@ -77,32 +76,36 @@ emitted if
or
.B \-grayscale
is specified, or if the JPEG file is grayscale; otherwise, 24-bit full-color
format is emitted.
format is emitted. This format can only be used when decompressing
8-bit-per-sample JPEG images.
.TP
.B \-gif
Select GIF output format (LZW-compressed). Since GIF does not support more
than 256 colors,
Select GIF output format (LZW-compressed) [legacy feature]. Since GIF does not
support more than 256 colors,
.B \-colors 256
is assumed (unless you specify a smaller number of colors). If you specify
.BR \-fast,
the default number of colors is 216.
the default number of colors is 216. This format can only be used when
decompressing 8-bit-per-sample or 12-bit-per-sample lossy JPEG images.
.TP
.B \-gif0
Select GIF output format (uncompressed). Since GIF does not support more than
256 colors,
Select GIF output format (uncompressed) [legacy feature]. Since GIF does not
support more than 256 colors,
.B \-colors 256
is assumed (unless you specify a smaller number of colors). If you specify
.BR \-fast,
the default number of colors is 216.
the default number of colors is 216. This format can only be used when
decompressing 8-bit-per-sample or 12-bit-per-sample lossy JPEG images.
.TP
.B \-os2
Select BMP output format (OS/2 1.x flavor). 8-bit colormapped format is
emitted if
Select BMP output format (OS/2 1.x flavor) [legacy feature]. 8-bit colormapped
format is emitted if
.B \-colors
or
.B \-grayscale
is specified, or if the JPEG file is grayscale; otherwise, 24-bit full-color
format is emitted.
format is emitted. This format can only be used when decompressing
8-bit-per-sample JPEG images.
.TP
.B \-pnm
Select PBMPLUS (PPM/PGM) output format (this is the default format).
@ -111,12 +114,13 @@ PGM is emitted if the JPEG file is grayscale or if
is specified; otherwise PPM is emitted.
.TP
.B \-targa
Select Targa output format. Grayscale format is emitted if the JPEG file is
grayscale or if
Select Targa output format [legacy feature]. Grayscale format is emitted if
the JPEG file is grayscale or if
.B \-grayscale
is specified; otherwise, colormapped format is emitted if
.B \-colors
is specified; otherwise, 24-bit full-color format is emitted.
is specified; otherwise, 24-bit full-color format is emitted. This format can
only be used when decompressing 8-bit-per-sample JPEG images.
.PP
Switches for advanced users:
.TP
@ -157,18 +161,18 @@ behavior, whereas the integer methods should give the same results on all
machines.
.TP
.B \-dither fs
Use Floyd-Steinberg dithering in color quantization.
Use Floyd-Steinberg dithering when quantizing colors [legacy feature].
.TP
.B \-dither ordered
Use ordered dithering in color quantization.
Use ordered dithering when quantizing colors [legacy feature].
.TP
.B \-dither none
Do not use dithering in color quantization.
By default, Floyd-Steinberg dithering is applied when quantizing colors; this
is slow but usually produces the best results. Ordered dither is a compromise
between speed and quality; no dithering is fast but usually looks awful. Note
that these switches have no effect unless color quantization is being done.
Ordered dither is only available in
Do not use dithering when quantizing colors [legacy feature]. By default,
Floyd-Steinberg dithering is applied when quantizing colors. This is slower
but usually produces the best results. Ordered dithering is a compromise
between speed and quality. No dithering is faster but usually looks awful.
Note that these switches have no effect unless color quantization is being
done. Ordered dithering is only available in
.B \-onepass
mode.
.TP
@ -176,9 +180,9 @@ mode.
Extract ICC color management profile to the specified file.
.TP
.BI \-map " file"
Quantize to the colors used in the specified image file. This is useful for
producing multiple files with identical color maps, or for forcing a
predefined set of colors to be used. The
Quantize to the colors used in the specified image file [legacy feature]. This
is useful for producing multiple files with identical color maps, or for
forcing a predefined set of colors to be used. The
.I file
must be a GIF or PPM file. This option overrides
.B \-colors
@ -189,14 +193,14 @@ and
Use a faster, lower-quality upsampling routine.
.TP
.B \-onepass
Use one-pass instead of two-pass color quantization. The one-pass method is
faster and needs less memory, but it produces a lower-quality image.
Use one-pass instead of two-pass color quantization [legacy feature]. The
one-pass method needs less memory, but it produces a lower-quality image.
.B \-onepass
is ignored unless you also say
is ignored unless you also specify
.B \-colors
.IR N .
Also, the one-pass method is always used for grayscale output (the two-pass
method is no improvement then).
Also, the one-pass method is always used for grayscale output. (The two-pass
method has no improvement in that case.)
.TP
.BI \-maxmemory " N"
Set limit for amount of memory to use in processing large images. Value is
@ -260,36 +264,13 @@ Same as
Print version information and exit.
.SH EXAMPLES
.LP
This example decompresses the JPEG file foo.jpg, quantizes it to
256 colors, and saves the output in 8-bit BMP format in foo.bmp:
This example decompresses the JPEG file foo.jpg and saves the output in 8-bit
BMP format in foo.bmp:
.IP
.B djpeg \-colors 256 \-bmp
.B djpeg \-bmp
.I foo.jpg
.B >
.I foo.bmp
.SH HINTS
To get a quick preview of an image, use the
.B \-grayscale
and/or
.B \-scale
switches.
.B \-grayscale \-scale 1/8
is the fastest case.
.PP
Several options are available that trade off image quality to gain speed.
.B \-fast
turns on the recommended settings.
.PP
.B \-dct fast
and/or
.B \-nosmooth
gain speed at a small sacrifice in quality.
When producing a color-quantized image,
.B \-onepass \-dither ordered
is fast but much lower quality than the default behavior.
.B \-dither none
may give acceptable results in two-pass mode, but is seldom tolerable in
one-pass mode.
.SH ENVIRONMENT
.TP
.B JPEGMEM

14
doc/jpegtran.1
View File

@ -1,4 +1,4 @@
.TH JPEGTRAN 1 "13 July 2021"
.TH JPEGTRAN 1 "17 June 2024"
.SH NAME
jpegtran \- lossless transformation of JPEG files
.SH SYNOPSIS
@ -13,7 +13,7 @@ jpegtran \- lossless transformation of JPEG files
.SH DESCRIPTION
.LP
.B jpegtran
performs various useful transformations of JPEG files.
performs various useful transformations of lossy (DCT-based) JPEG files.
It can translate the coded representation from one variant of JPEG to another,
for example from baseline JPEG to progressive JPEG or vice versa. It can also
perform some rearrangements of the image data, for example turning an image
@ -64,13 +64,13 @@ Perform optimization of entropy encoding parameters.
.B \-progressive
Create progressive JPEG file.
.TP
.B \-arithmetic
Use arithmetic coding.
.TP
.BI \-restart " N"
Emit a JPEG restart marker every N MCU rows, or every N MCU blocks if "B" is
attached to the number.
.TP
.B \-arithmetic
Use arithmetic coding.
.TP
.BI \-scans " file"
Use the scan script given in the specified text file.
.PP
@ -166,8 +166,8 @@ the current JPEG format; the upper left corner of the selected region must fall
on an iMCU boundary. If it doesn't, then it is silently moved up and/or left
to the nearest iMCU boundary (the lower right corner is unchanged.) Thus, the
output image covers at least the requested region, but it may cover more. The
adjustment of the region dimensions may be optionally disabled by attaching an
'f' character ("force") to the width or height number.
adjustment of the region dimensions may be optionally disabled by attaching
an 'f' character ("force") to the width or height number.
The image can be losslessly cropped by giving the switch:
.TP

127
doc/libjpeg.txt
View File

@ -5,7 +5,7 @@ Copyright (C) 1994-2013, Thomas G. Lane, Guido Vollbeding.
Lossless JPEG Modifications:
Copyright (C) 1999, Ken Murchison.
libjpeg-turbo Modifications:
Copyright (C) 2010, 2014-2018, 2020, 2022-2023, D. R. Commander.
Copyright (C) 2010, 2014-2018, 2020, 2022-2024, D. R. Commander.
Copyright (C) 2015, Google, Inc.
For conditions of distribution and use, see the accompanying README.ijg file.
@ -114,22 +114,24 @@ used by the free LIBTIFF library to support JPEG compression in TIFF.)
12-bit and 16-bit Data Precision
--------------------------------
The JPEG standard provides for baseline 8-bit and 12-bit DCT processes as well
as 8-bit, 12-bit, and 16-bit lossless (predictive) processes. This code
supports 12-bit-per-component lossy or lossless JPEG if you set
cinfo->data_precision to 12 and 16-bit-per-component lossless JPEG if you set
cinfo->data_precision to 16. Note that this causes the sample size to be
larger than a char, so it affects the surrounding application's image data.
The sample applications cjpeg and djpeg can support 12-bit mode only for PPM,
PGM, and GIF file formats and 16-bit mode only for PPM and PGM file formats.
The JPEG standard provides for baseline (8-bit-per-sample) and
12-bit-per-sample DCT processes as well as 8-bit-per-sample, 12-bit-per-sample,
and 16-bit-per-sample lossless (predictive) processes. This code supports
12-bit-per-sample lossy or lossless JPEG if you set cinfo->data_precision to 12
and 16-bit-per-sample lossless JPEG if you set cinfo->data_precision to 16.
Note that this causes the sample size to be larger than a char, so it affects
the surrounding application's image data. The sample applications cjpeg and
djpeg can support 12-bit data precision only for PPM, PGM, and GIF file formats
and 16-bit data precision only for PPM and PGM file formats.
Note that, when 12-bit data precision is enabled, the library always compresses
in Huffman optimization mode, in order to generate valid Huffman tables. This
is necessary because our default Huffman tables only cover 8-bit data. If you
need to output 12-bit files in one pass, you'll have to supply suitable default
Huffman tables. You may also want to supply your own DCT quantization tables;
the existing quality-scaling code has been developed for 8-bit use, and
probably doesn't generate especially good tables for 12-bit.
Note that, when 12-bit data precision is enabled in lossy mode, the library
compresses in Huffman optimization mode by default, in order to generate valid
Huffman tables. This is necessary because our default Huffman tables only
cover 8-bit data. If you need to output 12-bit-per-sample JPEG files in one
pass, you'll have to supply suitable default Huffman tables. You may also want
to supply your own DCT quantization tables; the existing quality-scaling code
has been developed for 8-bit data precision and probably doesn't generate
especially good tables for 12-bit data precision.
Functions that are specific to 12-bit data precision have a prefix of "jpeg12_"
instead of "jpeg_" and use the following data types and macros:
@ -160,7 +162,8 @@ Refer to the descriptions of the data_precision compression and decompression
parameters below for further information.
This documentation uses "J*SAMPLE", "J*SAMPROW", "J*SAMPARRAY", and
"J*SAMPIMAGE" to generically refer to the 8-bit, 12-bit, or 16-bit data types.
"J*SAMPIMAGE" to generically refer to the 8-bit-per-sample, 12-bit-per-sample,
or 16-bit-per-sample data types.
Outline of typical usage
@ -267,10 +270,9 @@ and the other references mentioned in the README.ijg file.
Pixels are stored by scanlines, with each scanline running from left to
right. The component values for each pixel are adjacent in the row; for
example, R,G,B,R,G,B,R,G,B,... for 24-bit RGB color. Each scanline is an
array of data type JSAMPLE or J12SAMPLE --- which is typically "unsigned char"
or "short" (respectively), unless you've changed jmorecfg.h. (You can also
change the RGB pixel layout, say to B,G,R order, by modifying jmorecfg.h. But
see the restrictions listed in that file before doing so.)
array of data type JSAMPLE, J12SAMPLE, or J16SAMPLE --- which is typically
"unsigned char", "short", or "unsigned short" (respectively) unless you've
changed jmorecfg.h.
A 2-D array of pixels is formed by making a list of pointers to the starts of
scanlines; so the scanlines need not be physically adjacent in memory. Even
@ -285,10 +287,11 @@ have it all in memory, but usually it's simplest to process one scanline at
a time.
For best results, source data values should have the precision specified by
cinfo->data_precision (normally 8 bits). For instance, if you choose to
compress data that's only 6 bits/channel, you should left-justify each value in
a byte before passing it to the compressor. If you need to compress data
that has more than 8 bits/channel, set cinfo->data_precision = 12 or 16.
cinfo->data_precision (normally 8 bits per sample). For instance, if you
choose to compress data that's only 6 bits/channel, you should left-justify
each value in a byte before passing it to the compressor. If you need to
compress data that has more than 8 bits/channel, set cinfo->data_precision = 12
or 16.
The data format returned by the decompressor is the same in all details,
@ -301,8 +304,8 @@ a 2-D J*SAMPARRAY in which each row holds the values of one color component,
that is, colormap[i][j] is the value of the i'th color component for pixel
value (map index) j. Note that since the colormap indexes are stored in
J*SAMPLEs, the maximum number of colors is limited by the size of J*SAMPLE
(ie, at most 256 colors for 8-bit data precision, 4096 colors for 12-bit data
precision, and 65536 colors for 16-bit data precision).
(ie, at most 256 colors for 8-bit data precision and 4096 colors for 12-bit
data precision).
Compression details
@ -972,7 +975,7 @@ jpeg_set_quality (j_compress_ptr cinfo, int quality, boolean force_baseline)
entries are constrained to the range 1..255 for full JPEG baseline
compatibility. In the current implementation, this only makes a
difference for quality settings below 25, and it effectively prevents
very small/low quality files from being generated. The IJG decoder
very small/low-quality files from being generated. The IJG decoder
is capable of reading the non-baseline files generated at low quality
settings when force_baseline is FALSE, but other decoders may not be.
@ -1079,12 +1082,12 @@ boolean arith_code
If FALSE, use Huffman coding.
int data_precision
To create a 12-bit-per-component JPEG file, set data_precision to 12
prior to calling jpeg_start_compress() or using the memory manager,
then use jpeg12_write_scanlines() or jpeg12_write_raw_data() instead of
jpeg_write_scanlines() or jpeg_write_raw_data(). To create a
16-bit-per-component lossless JPEG file, set data_precision to 16 prior
To create a 12-bit-per-sample JPEG file, set data_precision to 12 prior
to calling jpeg_start_compress() or using the memory manager, then use
jpeg12_write_scanlines() or jpeg12_write_raw_data() instead of
jpeg_write_scanlines() or jpeg_write_raw_data(). To create a
16-bit-per-sample lossless JPEG file, set data_precision to 16 prior to
calling jpeg_start_compress() or using the memory manager, then use
jpeg16_write_scanlines() instead of jpeg_write_scanlines(). Note that
16-bit data precision requires lossless mode. (See
jpeg_enable_lossless().)
@ -1138,7 +1141,11 @@ boolean optimize_coding
Huffman tables. In most cases optimal tables save only a few percent
of file size compared to the default tables. Note that when this is
TRUE, you need not supply Huffman tables at all, and any you do
supply will be overwritten.
supply will be overwritten. Optimal Huffman tables are always
computed, and this parameter has no effect, in progressive mode or
lossless mode or with 12-bit data precision (unless Huffman tables have
been supplied.) This parameter also has no effect when using
arithmetic coding.
unsigned int restart_interval
int restart_in_rows
@ -1303,13 +1310,13 @@ recorded in the source file and need not be supplied by the application.
the postprocessing done on the image to deliver it in a format suitable
for the application's use. Many of the parameters control speed/quality
tradeoffs, in which faster decompression may be obtained at the price of
a poorer-quality image. The defaults select the highest quality (slowest)
a poorer-quality image. The defaults select the highest-quality (slowest)
processing.
The following fields in the JPEG object are set by jpeg_read_header() and
may be useful to the application in choosing decompression parameters:
int data_precision Data precision (bits per component)
int data_precision Data precision (bits per sample)
If data_precision is 12, then use jpeg12_read_scanlines(),
jpeg12_skip_scanlines(), jpeg12_crop_scanline(), and/or
jpeg12_read_raw_data() instead of jpeg_read_scanlines(),
@ -1344,11 +1351,8 @@ J_COLOR_SPACE out_color_space
based on jpeg_color_space; typically it will be RGB or grayscale.
The application can change this field to request output in a different
colorspace. For example, set it to JCS_GRAYSCALE to get grayscale
output from a color file. (This is useful for previewing: grayscale
output is faster than full color since the color components need not
be processed.) Note that not all possible color space transforms are
currently implemented; you may need to extend jdcolor.c if you want an
unusual conversion.
output from a color file. Note that not all possible color space
transforms are currently implemented.
unsigned int scale_num, scale_denom
Scale the image by the fraction scale_num/scale_denom. Default is
@ -1356,31 +1360,33 @@ unsigned int scale_num, scale_denom
are M/8 with all M from 1 to 16, or any reduced fraction thereof (such
as 1/2, 3/4, etc.) (The library design allows for arbitrary
scaling ratios but this is not likely to be implemented any time soon.)
Smaller scaling ratios permit significantly faster decoding since
fewer pixels need be processed and a simpler IDCT method can be used.
boolean quantize_colors
[legacy feature]
If set TRUE, colormapped output will be delivered. Default is FALSE,
meaning that full-color output will be delivered.
The next three parameters are relevant only if quantize_colors is TRUE.
int desired_number_of_colors
[legacy feature]
Maximum number of colors to use in generating a library-supplied color
map (the actual number of colors is returned in a different field).
Default 256. Ignored when the application supplies its own color map.
boolean two_pass_quantize
[legacy feature]
If TRUE, an extra pass over the image is made to select a custom color
map for the image. This usually looks a lot better than the one-size-
fits-all colormap that is used otherwise. Default is TRUE. Ignored
when the application supplies its own color map.
J_DITHER_MODE dither_mode
[legacy feature]
Selects color dithering method. Supported values are:
JDITHER_NONE no dithering: fast, very low quality
JDITHER_NONE no dithering: faster, very low quality
JDITHER_ORDERED ordered dither: moderate speed and quality
JDITHER_FS Floyd-Steinberg dither: slow, high quality
JDITHER_FS Floyd-Steinberg dither: slower, high quality
Default is JDITHER_FS. (At present, ordered dither is implemented
only in the single-pass, standard-colormap case. If you ask for
ordered dither when two_pass_quantize is TRUE or when you supply
@ -1395,16 +1401,18 @@ selects a suitable color map and sets these two fields itself.
only accepted for 3-component output color spaces.]
JSAMPARRAY colormap
[legacy feature]
The color map, represented as a 2-D pixel array of out_color_components
rows and actual_number_of_colors columns. Ignored if not quantizing.
CAUTION: if the JPEG library creates its own colormap, the storage
pointed to by this field is released by jpeg_finish_decompress().
Copy the colormap somewhere else first, if you want to save it.
CAUTION: if data_precision is 12 or 16, then this is actually a
J12SAMPARRAY or a J16SAMPARRAY, so it must be type-cast in order to
read/write 12-bit or 16-bit samples from/to the array.
CAUTION: if data_precision is 12, then this is actually a J12SAMPARRAY,
so it must be type-cast in order to read/write 12-bit samples from/to
the array.
int actual_number_of_colors
[legacy feature]
The number of colors in the color map.
Additional decompression parameters that the application may set include:
@ -1461,6 +1469,7 @@ boolean do_block_smoothing
boolean enable_1pass_quant
boolean enable_external_quant
boolean enable_2pass_quant
[legacy feature]
These are significant only in buffered-image mode, which is
described in its own section below.
@ -2330,7 +2339,7 @@ limited changes of parameters. ONLY THE FOLLOWING parameter changes are
allowed after jpeg_start_decompress() is called:
* dct_method can be changed before each call to jpeg_start_output().
For example, one could use a fast DCT method for early scans, changing
to a higher quality method for the final scan.
to a higher-quality method for the final scan.
* dither_mode can be changed before each call to jpeg_start_output();
of course this has no impact if not using color quantization. Typically
one would use ordered dither for initial passes, then switch to
@ -3182,10 +3191,10 @@ This does not count any memory allocated by the application, such as a
buffer to hold the final output image.
The above figures are valid for 8-bit JPEG data precision and a machine with
32-bit ints. For 12-bit and 16-bit JPEG data, double the size of the strip
buffers and quantization pixel buffer. The "fixed-size" data will be somewhat
smaller with 16-bit ints, larger with 64-bit ints. Also, CMYK or other unusual
color spaces will require different amounts of space.
32-bit ints. For 12-bit-per-sample and 16-bit-per-sample JPEG data, double the
size of the strip buffers and quantization pixel buffer. The "fixed-size" data
will be somewhat smaller with 16-bit ints, larger with 64-bit ints. Also, CMYK
or other unusual color spaces will require different amounts of space.
The full-image coefficient and pixel buffers, if needed at all, do not
have to be fully RAM resident; you can have the library use temporary
@ -3211,14 +3220,6 @@ The maximum number of components (color channels) in the image is determined
by MAX_COMPONENTS. The JPEG standard allows up to 255 components, but we
expect that few applications will need more than four or so.
On machines with unusual data type sizes, you may be able to improve
performance or reduce memory space by tweaking the various typedefs in
jmorecfg.h. In particular, on some RISC CPUs, access to arrays of "short"s
is quite slow; consider trading memory for speed by making JCOEF, INT16, and
UINT16 be "int" or "unsigned int". UINT8 is also a candidate to become int.
You probably don't want to make J*SAMPLE be int unless you have lots of memory
to burn.
You can reduce the size of the library by compiling out various optional
functions. To do this, undefine xxx_SUPPORTED symbols as necessary.
@ -3257,9 +3258,7 @@ than 8 bits or short is much bigger than 16 bits. The code should work
equally well with 16- or 32-bit ints.
In a system where these assumptions are not met, you may be able to make the
code work by modifying the typedefs in jmorecfg.h. However, you will probably
have difficulty if int is less than 16 bits wide, since references to plain
int abound in the code.
code work by modifying the typedefs in jmorecfg.h.
char can be either signed or unsigned, although the code runs faster if an
unsigned char type is available. If char is wider than 8 bits, you will need

319
doc/usage.txt
View File

@ -1,5 +1,8 @@
NOTE: This file was modified by The libjpeg-turbo Project to include only
information relevant to libjpeg-turbo and to wordsmith certain sections.
This file was part of the Independent JPEG Group's software:
Copyright (C) 1991-2020, Thomas G. Lane, Guido Vollbeding.
libjpeg-turbo Modifications:
Copyright (C) 2010, 2012, 2014-2017, 2020-2024, D. R. Commander.
For conditions of distribution and use, see the accompanying README.ijg file.
USAGE instructions for the Independent JPEG Group's JPEG software
=================================================================
@ -50,9 +53,10 @@ or
This syntax works on all systems, so it is useful for scripts.
The currently supported image file formats are: PPM (PBMPLUS color format),
PGM (PBMPLUS grayscale format), BMP, GIF, and Targa. cjpeg recognizes the
input image format automatically, with the exception of some Targa files. You
have to tell djpeg which format to generate.
PGM (PBMPLUS grayscale format), BMP, GIF [legacy feature], and Targa [legacy
feature]. cjpeg recognizes the input image format automatically, with the
exception of some Targa files. You have to tell djpeg which format to
generate.
JPEG files are in the defacto standard JFIF file format. There are other,
less widely used JPEG-based file formats, but we don't support them.
@ -73,12 +77,12 @@ The basic command line switches for cjpeg are:
(See below for more info.)
-grayscale Create monochrome JPEG file from color input. By
saying -grayscale, you'll get a smaller JPEG file that
takes less time to process.
specifying -grayscale, you'll get a smaller JPEG file
that takes less time to process.
-rgb Create RGB JPEG file.
Using this switch suppresses the conversion from RGB
colorspace input to the default YCbCr JPEG colorspace.
-rgb Create RGB JPEG file. Using this switch suppresses the
conversion from RGB colorspace input to the default
YCbCr JPEG colorspace.
-optimize Perform optimization of entropy encoding parameters.
Without this, default encoding parameters are used.
@ -87,13 +91,15 @@ The basic command line switches for cjpeg are:
memory. Image quality and speed of decompression are
unaffected by -optimize.
-progressive Create progressive JPEG file (see below).
-progressive Create progressive JPEG file (see below). Implies
-optimize unless -arithmetic is also specified.
-targa Input file is Targa format. Targa files that contain
an "identification" field will not be automatically
recognized by cjpeg; for such files you must specify
-targa to make cjpeg treat the input as Targa format.
For most Targa files, you won't need this switch.
-targa Input file is Targa format [legacy feature]. Targa
files that contain an "identification" field will not
be automatically recognized by cjpeg. For such files,
you must specify -targa to make cjpeg treat the input
as Targa format. For most Targa files, you won't need
this switch.
The -quality switch lets you trade off compressed file size against quality of
the reconstructed image: the higher the quality setting, the larger the JPEG
@ -162,10 +168,22 @@ Switches for advanced users:
-precision N Create JPEG file with N-bit data precision.
N is 8, 12, or 16; default is 8. If N is 16, then
-lossless must also be specified. CAUTION: 12-bit and
16-bit JPEG is not yet widely implemented, so many
decoders will be unable to view a 12-bit or 16-bit JPEG
file at all.
-lossless must also be specified. Note that only the
PBMPLUS input file format supports data precisions other
than 8. (For historical reasons, cjpeg allows GIF input
files to be converted into 12-bit-per-sample JPEG files,
but this is not a useful conversion.) Note also that
PBMPLUS input files are silently scaled to the target
data precision, even if it is lower than the precision
of the input file. Passing an argument of -verbose to
cjpeg will cause it to print information about the
precision of the input file. CAUTION: 12-bit and 16-bit
data precision is not yet widely implemented, so many
decoders will be unable to handle a 12-bit-per-sample or
16-bit-per-sample JPEG file at all.
"-precision 12" implies -optimize unless -arithmetic is
also specified.
-lossless psv[,Pt] Create a lossless JPEG file using the specified
predictor selection value (1 - 7) and optional point
@ -177,7 +195,7 @@ Switches for advanced users:
number of bits, which is effectively a form of lossy
color quantization.) CAUTION: lossless JPEG is not yet
widely implemented, so many decoders will be unable to
view a lossless JPEG file at all. In most cases,
handle a lossless JPEG file at all. In most cases,
compressing and decompressing a lossless JPEG file is
considerably slower than compressing and decompressing
a lossy JPEG file, and lossless JPEG files are much
@ -197,9 +215,9 @@ Switches for advanced users:
Any switches used to enable or configure those features
will be ignored.
-arithmetic Use arithmetic coding. CAUTION: arithmetic coded JPEG
-arithmetic Use arithmetic coding. CAUTION: arithmetic-coded JPEG
is not yet widely implemented, so many decoders will
be unable to view an arithmetic coded JPEG file at
be unable to handle an arithmetic-coded JPEG file at
all.
-dct int Use accurate integer DCT method (default).
@ -240,6 +258,9 @@ Switches for advanced users:
behavior, whereas the integer methods should give the
same results on all machines.
-icc FILE Embed ICC color management profile contained in the
specified file.
-restart N Emit a JPEG restart marker every N MCU rows, or every
N MCU blocks (samples in lossless mode) if "B" is
attached to the number. -restart 0 (the default) means
@ -255,9 +276,23 @@ Switches for advanced users:
For example, -max 4m selects 4000000 bytes. If more
space is needed, an error will occur.
-verbose Enable debug printout. More -v's give more printout.
-memdst Compress to memory instead of a file. This feature was
implemented mainly as a way of testing the in-memory
destination manager (jpeg_mem_dest()), but it is also
useful for benchmarking, since it reduces the I/O
overhead.
-report Report compression progress.
-strict Treat all warnings as fatal. Enabling this option will
cause the compressor to abort if an LZW-compressed GIF
input image contains incomplete or corrupt image data.
-verbose Enable debug printout. More -v's give more output.
or -debug Also, version information is printed at startup.
-version Print version information and exit.
The -restart option inserts extra markers that allow a JPEG decoder to
resynchronize after a transmission error. Without restart markers, any damage
to a compressed file will usually ruin the image from the point of the error
@ -300,64 +335,78 @@ DJPEG DETAILS
The basic command line switches for djpeg are:
-colors N Reduce image to at most N colors. This reduces the
or -quantize N number of colors used in the output image, so that it
can be displayed on a colormapped display or stored in
a colormapped file format. For example, if you have
an 8-bit display, you'd need to reduce to 256 or fewer
colors. (-colors is the recommended name, -quantize
is provided only for backwards compatibility.)
-colors N Reduce image to at most N colors [legacy feature].
or -quantize N This reduces the number of colors used in the output
image so that it can be stored in a colormapped file
format. This feature cannot be used when decompressing
lossless JPEG images. (-colors is the recommended
name. -quantize is provided only for backward
compatibility.)
-fast Select recommended processing options for fast, low
quality output. (The default options are chosen for
highest quality output.) Currently, this is equivalent
to "-dct fast -nosmooth -onepass -dither ordered".
-fast Select recommended processing options for low-quality
output [legacy feature]. (The default options are
chosen for highest-quality output.) Currently, this is
equivalent to "-dct fast -nosmooth -onepass -dither
ordered". On modern CPUs, these settings have little
or no performance benefit and are retained solely for
backward compatibility.
-grayscale Force grayscale output even if JPEG file is color.
Useful for viewing on monochrome displays; also,
djpeg runs noticeably faster in this mode.
-grayscale Force grayscale output even if JPEG file is full-color.
This feature cannot be used when decompressing
full-color lossless JPEG images.
-rgb Force RGB output even if JPEG file is grayscale.
-rgb Force RGB output even if JPEG file is grayscale. This
feature cannot be used when decompressing grayscale
lossless JPEG images.
-scale M/N Scale the output image by a factor M/N. Currently
the scale factor must be M/8, where M is an integer
between 1 and 16 inclusive, or any reduced fraction
thereof (such as 1/2, 3/4, etc. Scaling is handy if
the image is larger than your screen; also, djpeg runs
much faster when scaling down the output.
-scale M/N Scale the output image by a factor M/N. Currently the
scale factor must be M/8, where M is an integer between
1 and 16 inclusive, or any reduced fraction thereof
(such as 1/2, 3/4, etc.) Scaling is handy if the image
is larger than your screen. This feature cannot be
used when decompressing lossless JPEG images.
-bmp Select BMP output format (Windows flavor). 8-bit
colormapped format is emitted if -colors or -grayscale
is specified, or if the JPEG file is grayscale;
otherwise, 24-bit full-color format is emitted.
otherwise, 24-bit full-color format is emitted. This
format can only be used when decompressing
8-bit-per-sample JPEG images.
-gif Select GIF output format (LZW-compressed). Since GIF
does not support more than 256 colors, -colors 256 is
assumed (unless you specify a smaller number of
colors). If you specify -fast, the default number of
colors is 216.
-gif Select GIF output format (LZW-compressed) [legacy
feature]. Since GIF does not support more than 256
colors, -colors 256 is assumed (unless you specify a
smaller number of colors). If you specify -fast, the
default number of colors is 216. This format can only
be used when decompressing 8-bit-per-sample or
12-bit-per-sample lossy JPEG images.
-gif0 Select GIF output format (uncompressed). Since GIF
does not support more than 256 colors, -colors 256 is
assumed (unless you specify a smaller number of
colors). If you specify -fast, the default number of
colors is 216.
-gif0 Select GIF output format (uncompressed) [legacy
feature]. Since GIF does not support more than 256
colors, -colors 256 is assumed (unless you specify a
smaller number of colors). If you specify -fast, the
default number of colors is 216. This format can only
be used when decompressing 8-bit-per-sample or
12-bit-per-sample lossy JPEG images.
-os2 Select BMP output format (OS/2 1.x flavor). 8-bit
colormapped format is emitted if -colors or -grayscale
is specified, or if the JPEG file is grayscale;
otherwise, 24-bit full-color format is emitted.
-os2 Select BMP output format (OS/2 1.x flavor) [legacy
feature]. 8-bit colormapped format is emitted if
-colors or -grayscale is specified, or if the JPEG file
is grayscale; otherwise, 24-bit full-color format is
emitted. This format can only be used when
decompressing 8-bit-per-sample JPEG images.
-pnm Select PBMPLUS (PPM/PGM) output format (this is the
default format). PGM is emitted if the JPEG file is
grayscale or if -grayscale is specified; otherwise
PPM is emitted.
grayscale or if -grayscale is specified; otherwise PPM
is emitted.
-targa Select Targa output format. Grayscale format is
emitted if the JPEG file is grayscale or if
-targa Select Targa output format [legacy feature]. Grayscale
format is emitted if the JPEG file is grayscale or if
-grayscale is specified; otherwise, colormapped format
is emitted if -colors is specified; otherwise, 24-bit
full-color format is emitted.
full-color format is emitted. This format can only be
used when decompressing 8-bit-per-sample JPEG images.
Switches for advanced users:
@ -401,32 +450,39 @@ Switches for advanced users:
behavior, whereas the integer methods should give the
same results on all machines.
-dither fs Use Floyd-Steinberg dithering in color quantization.
-dither ordered Use ordered dithering in color quantization.
-dither none Do not use dithering in color quantization.
By default, Floyd-Steinberg dithering is applied when
quantizing colors; this is slow but usually produces
the best results. Ordered dither is a compromise
between speed and quality; no dithering is fast but
usually looks awful. Note that these switches have
no effect unless color quantization is being done.
Ordered dither is only available in -onepass mode.
-dither fs Use Floyd-Steinberg dithering when quantizing colors
[legacy feature].
-dither ordered Use ordered dithering when quantizing colors [legacy
feature].
-dither none Do not use dithering when quantizing colors [legacy
feature]. By default, Floyd-Steinberg dithering is
applied when quantizing colors. This is slower but
usually produces the best results. Ordered dithering
is a compromise between speed and quality. No
dithering is faster but usually looks awful. Note that
these switches have no effect unless color quantization
is being done. Ordered dithering is only available in
-onepass mode.
-map FILE Quantize to the colors used in the specified image
file. This is useful for producing multiple files
with identical color maps, or for forcing a predefined
set of colors to be used. The FILE must be a GIF
or PPM file. This option overrides -colors and
-onepass.
-icc FILE Extract ICC color management profile to the specified
file.
-map FILE Quantize to the colors used in the specified image file
[legacy feature]. This is useful for producing
multiple files with identical color maps, or for
forcing a predefined set of colors to be used. The
FILE must be a GIF or PPM file. This option overrides
-colors and -onepass.
-nosmooth Use a faster, lower-quality upsampling routine.
-onepass Use one-pass instead of two-pass color quantization.
The one-pass method is faster and needs less memory,
but it produces a lower-quality image. -onepass is
ignored unless you also say -colors N. Also,
the one-pass method is always used for grayscale
output (the two-pass method is no improvement then).
-onepass Use one-pass instead of two-pass color quantization
[legacy feature]. The one-pass method needs less
memory, but it produces a lower-quality image.
-onepass is ignored unless you also specify -colors N.
Also, the one-pass method is always used for grayscale
output. (The two-pass method has no improvement in
that case.)
-maxmemory N Set limit for amount of memory to use in processing
large images. Value is in thousands of bytes, or
@ -434,18 +490,62 @@ Switches for advanced users:
For example, -max 4m selects 4000000 bytes. If more
space is needed, an error will occur.
-verbose Enable debug printout. More -v's give more printout.
-maxscans N Abort if the JPEG image contains more than N scans.
This feature demonstrates a method by which
applications can guard against denial-of-service
attacks instigated by specially-crafted malformed JPEG
images containing numerous scans with missing image
data or image data consisting only of "EOB runs" (a
feature of progressive JPEG images that allows
potentially hundreds of thousands of adjoining
zero-value pixels to be represented using only a few
bytes.) Attempting to decompress such malformed JPEG
images can cause excessive CPU activity, since the
decompressor must fully process each scan (even if the
scan is corrupt) before it can proceed to the next
scan.
-memsrc Load input file into memory before decompressing. This
feature was implemented mainly as a way of testing the
in-memory source manager (jpeg_mem_src().)
-report Report decompression progress.
-skip Y0,Y1 Decompress all rows of the JPEG image except those
between Y0 and Y1 (inclusive.) Note that if
decompression scaling is being used, then Y0 and Y1 are
relative to the scaled image dimensions.
-crop WxH+X+Y Decompress only a rectangular subregion of the image,
starting at point X,Y with width W and height H. If
necessary, X will be shifted left to the nearest iMCU
boundary, and the width will be increased accordingly.
Note that if decompression scaling is being used, then
X, Y, W, and H are relative to the scaled image
dimensions. Currently this option only works with the
PBMPLUS (PPM/PGM), GIF, and Targa output formats.
-strict Treat all warnings as fatal. This feature also
demonstrates a method by which applications can guard
against attacks instigated by specially-crafted
malformed JPEG images. Enabling this option will cause
the decompressor to abort if the JPEG image contains
incomplete or corrupt image data.
-verbose Enable debug printout. More -v's give more output.
or -debug Also, version information is printed at startup.
-version Print version information and exit.
HINTS FOR CJPEG
Color GIF files are not the ideal input for JPEG; JPEG is really intended for
compressing full-color (24-bit) images. In particular, don't try to convert
cartoons, line drawings, and other images that have only a few distinct
colors. GIF works great on these, JPEG does not. If you want to convert a
GIF to JPEG, you should experiment with cjpeg's -quality and -smooth options
to get a satisfactory conversion. -smooth 10 or so is often helpful.
compressing full-color (24-bit through 48-bit) images. In particular, don't
try to convert cartoons, line drawings, and other images that have only a few
distinct colors. GIF works great on these; JPEG does not. If you want to
convert a GIF to JPEG, you should experiment with cjpeg's -quality and -smooth
options to get a satisfactory conversion. -smooth 10 or so is often helpful.
Avoid running an image through a series of JPEG compression/decompression
cycles. Image quality loss will accumulate; after ten or so cycles the image
@ -460,20 +560,6 @@ is often a lot more than it is on larger files. (At present, -optimize
mode is always selected when generating progressive JPEG files.)
HINTS FOR DJPEG
To get a quick preview of an image, use the -grayscale and/or -scale switches.
"-grayscale -scale 1/8" is the fastest case.
Several options are available that trade off image quality to gain speed.
"-fast" turns on the recommended settings.
"-dct fast" and/or "-nosmooth" gain speed at a small sacrifice in quality.
When producing a color-quantized image, "-onepass -dither ordered" is fast but
much lower quality than the default behavior. "-dither none" may give
acceptable results in two-pass mode, but is seldom tolerable in one-pass mode.
HINTS FOR BOTH PROGRAMS
If the memory needed by cjpeg or djpeg exceeds the limit specified by
@ -489,12 +575,12 @@ explicit -maxmemory switch.
JPEGTRAN
jpegtran performs various useful transformations of JPEG files.
It can translate the coded representation from one variant of JPEG to another,
for example from baseline JPEG to progressive JPEG or vice versa. It can also
perform some rearrangements of the image data, for example turning an image
from landscape to portrait format by rotation. For EXIF files and JPEG files
containing Exif data, you may prefer to use exiftran instead.
jpegtran performs various useful transformations of lossy (DCT-based) JPEG
files. It can translate the coded representation from one variant of JPEG to
another, for example from baseline JPEG to progressive JPEG or vice versa. It
can also perform some rearrangements of the image data, for example turning an
image from landscape to portrait format by rotation. For EXIF files and JPEG
files containing Exif data, you may prefer to use exiftran instead.
jpegtran works by rearranging the compressed data (DCT coefficients), without
ever fully decoding the image. Therefore, its transformations are lossless:
@ -650,10 +736,15 @@ The default behavior is -copy comments. (Note: in IJG releases v6 and v6a,
jpegtran always did the equivalent of -copy none.)
Additional switches recognized by jpegtran are:
-outfile filename
-icc FILE
-maxmemory N
-maxscans N
-outfile filename
-report
-strict
-verbose
-debug
-version
These work the same as in cjpeg or djpeg.

7
java/TJBench.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (C)2009-2014, 2016-2019, 2021-2023 D. R. Commander.
* Copyright (C)2009-2014, 2016-2019, 2021-2024 D. R. Commander.
* All Rights Reserved.
*
* Redistribution and use in source and binary forms, with or without
@ -926,7 +926,6 @@ final class TJBench {
System.out.println("Using fastest DCT/IDCT algorithm\n");
fastDCT = true;
} else if (argv[i].equalsIgnoreCase("-optimize")) {
System.out.println("Using optimized baseline entropy coding\n");
optimize = true;
xformOpt |= TJTransform.OPT_OPTIMIZE;
} else if (argv[i].equalsIgnoreCase("-progressive")) {
@ -1127,6 +1126,10 @@ final class TJBench {
}
}
if (optimize && !progressive && !arithmetic && !lossless &&
precision != 12)
System.out.println("Using optimized baseline entropy coding\n");
if (precision == 16 && !lossless)
throw new Exception("-lossless must be specified along with -precision 16");
if (precision != 8 && doYUV)

2
java/doc/index-all.html
View File

@ -968,7 +968,7 @@ $('.navPadding').css('padding-top', $('.fixedNav').css("height"));
</dd>
<dt><span class="memberNameLink"><a href="org/libjpegturbo/turbojpeg/TJCompressor.html#setSourceImage(java.awt.image.BufferedImage,int,int,int,int)">setSourceImage(BufferedImage, int, int, int, int)</a></span> - Method in class org.libjpegturbo.turbojpeg.<a href="org/libjpegturbo/turbojpeg/TJCompressor.html" title="class in org.libjpegturbo.turbojpeg">TJCompressor</a></dt>
<dd>
<div class="block">Associate an 8-bit-per-pixel packed-pixel RGB or grayscale source image
<div class="block">Associate an 8-bit-per-sample packed-pixel RGB or grayscale source image
with this compressor instance.</div>
</dd>
<dt><span class="memberNameLink"><a href="org/libjpegturbo/turbojpeg/TJCompressor.html#setSourceImage(org.libjpegturbo.turbojpeg.YUVImage)">setSourceImage(YUVImage)</a></span> - Method in class org.libjpegturbo.turbojpeg.<a href="org/libjpegturbo/turbojpeg/TJCompressor.html" title="class in org.libjpegturbo.turbojpeg">TJCompressor</a></dt>

BIN
java/doc/member-search-index.zip
View File

Binary file not shown.

4
java/doc/org/libjpegturbo/turbojpeg/TJCompressor.html
View File

@ -369,7 +369,7 @@ implements java.io.Closeable</pre>
int&nbsp;width,
int&nbsp;height)</code></th>
<td class="colLast">
<div class="block">Associate an 8-bit-per-pixel packed-pixel RGB or grayscale source image
<div class="block">Associate an 8-bit-per-sample packed-pixel RGB or grayscale source image
with this compressor instance.</div>
</td>
</tr>
@ -677,7 +677,7 @@ implements java.io.Closeable</pre>
int&nbsp;width,
int&nbsp;height)
throws <a href="TJException.html" title="class in org.libjpegturbo.turbojpeg">TJException</a></pre>
<div class="block">Associate an 8-bit-per-pixel packed-pixel RGB or grayscale source image
<div class="block">Associate an 8-bit-per-sample packed-pixel RGB or grayscale source image
with this compressor instance.</div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>

4
java/doc/org/libjpegturbo/turbojpeg/TJDecompressor.html
View File

@ -1184,7 +1184,7 @@ public&nbsp;byte[]&nbsp;decompress&#8203;(int&nbsp;desiredWidth,
<dd><code>pixelFormat</code> - pixel format of the decompressed image (one of
<a href="TJ.html#PF_RGB"><code>TJ.PF_*</code></a>)</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>a buffer containing an 8-bit-per-sample packed-pixel decompressed
<dd>a buffer containing a 12-bit-per-sample packed-pixel decompressed
image.</dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="TJException.html" title="class in org.libjpegturbo.turbojpeg">TJException</a></code></dd>
@ -1258,7 +1258,7 @@ public&nbsp;byte[]&nbsp;decompress&#8203;(int&nbsp;desiredWidth,
<dd><code>pixelFormat</code> - pixel format of the decompressed image (one of
<a href="TJ.html#PF_RGB"><code>TJ.PF_*</code></a>)</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>a buffer containing an 8-bit-per-sample packed-pixel decompressed
<dd>a buffer containing a 16-bit-per-sample packed-pixel decompressed
image.</dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="TJException.html" title="class in org.libjpegturbo.turbojpeg">TJException</a></code></dd>

BIN
java/doc/package-search-index.zip
View File

Binary file not shown.

BIN
java/doc/type-search-index.zip
View File

Binary file not shown.

2
java/org/libjpegturbo/turbojpeg/TJCompressor.java
View File

@ -263,7 +263,7 @@ public class TJCompressor implements Closeable {
}
/**
* Associate an 8-bit-per-pixel packed-pixel RGB or grayscale source image
* Associate an 8-bit-per-sample packed-pixel RGB or grayscale source image
* with this compressor instance.
*
* @param srcImage a <code>BufferedImage</code> instance containing a

4
java/org/libjpegturbo/turbojpeg/TJDecompressor.java
View File

@ -582,7 +582,7 @@ public class TJDecompressor implements Closeable {
* @param pixelFormat pixel format of the decompressed image (one of
* {@link TJ#PF_RGB TJ.PF_*})
*
* @return a buffer containing an 8-bit-per-sample packed-pixel decompressed
* @return a buffer containing a 12-bit-per-sample packed-pixel decompressed
* image.
*/
public short[] decompress12(int pitch, int pixelFormat) throws TJException {
@ -655,7 +655,7 @@ public class TJDecompressor implements Closeable {
* @param pixelFormat pixel format of the decompressed image (one of
* {@link TJ#PF_RGB TJ.PF_*})
*
* @return a buffer containing an 8-bit-per-sample packed-pixel decompressed
* @return a buffer containing a 16-bit-per-sample packed-pixel decompressed
* image.
*/
public short[] decompress16(int pitch, int pixelFormat) throws TJException {

19
src/cderror.h
View File

@ -5,7 +5,7 @@
* Copyright (C) 1994-1997, Thomas G. Lane.
* Modified 2009-2017 by Guido Vollbeding.
* libjpeg-turbo Modifications:
* Copyright (C) 2021, D. R. Commander.
* Copyright (C) 2021, 2024, D. R. Commander.
* For conditions of distribution and use, see the accompanying README.ijg
* file.
*
@ -42,7 +42,6 @@ typedef enum {
JMESSAGE(JMSG_FIRSTADDONCODE = 1000, NULL) /* Must be first entry! */
#ifdef BMP_SUPPORTED
JMESSAGE(JERR_BMP_BADCMAP, "Unsupported BMP colormap format")
JMESSAGE(JERR_BMP_BADDEPTH, "Only 8-, 24-, and 32-bit BMP files are supported")
JMESSAGE(JERR_BMP_BADHEADER, "Invalid BMP file: bad header length")
@ -56,9 +55,7 @@ JMESSAGE(JTRC_BMP, "%ux%u %d-bit BMP image")
JMESSAGE(JTRC_BMP_MAPPED, "%ux%u 8-bit colormapped BMP image")
JMESSAGE(JTRC_BMP_OS2, "%ux%u %d-bit OS2 BMP image")
JMESSAGE(JTRC_BMP_OS2_MAPPED, "%ux%u 8-bit colormapped OS2 BMP image")
#endif /* BMP_SUPPORTED */
#ifdef GIF_SUPPORTED
JMESSAGE(JERR_GIF_BUG, "GIF output got confused")
JMESSAGE(JERR_GIF_CODESIZE, "Bogus GIF codesize %d")
JMESSAGE(JERR_GIF_COLORSPACE, "GIF output must be grayscale or RGB")
@ -74,29 +71,23 @@ JMESSAGE(JWRN_GIF_BADDATA, "Corrupt data in GIF file")
JMESSAGE(JWRN_GIF_CHAR, "Bogus char 0x%02x in GIF file, ignoring")
JMESSAGE(JWRN_GIF_ENDCODE, "Premature end of GIF image")
JMESSAGE(JWRN_GIF_NOMOREDATA, "Ran out of GIF bits")
#endif /* GIF_SUPPORTED */
#ifdef PPM_SUPPORTED
JMESSAGE(JERR_PPM_COLORSPACE, "PPM output must be grayscale or RGB")
JMESSAGE(JERR_PPM_NONNUMERIC, "Nonnumeric data in PPM file")
JMESSAGE(JERR_PPM_NOT, "Not a PPM/PGM file")
JMESSAGE(JERR_PPM_OUTOFRANGE, "Numeric value out of range in PPM file")
JMESSAGE(JTRC_PGM, "%ux%u PGM image")
JMESSAGE(JTRC_PGM_TEXT, "%ux%u text PGM image")
JMESSAGE(JTRC_PPM, "%ux%u PPM image")
JMESSAGE(JTRC_PPM_TEXT, "%ux%u text PPM image")
#endif /* PPM_SUPPORTED */
JMESSAGE(JTRC_PGM, "%ux%u PGM image (maximum color value = %u)")
JMESSAGE(JTRC_PGM_TEXT, "%ux%u text PGM image (maximum color value = %u)")
JMESSAGE(JTRC_PPM, "%ux%u PPM image (maximum color value = %u)")
JMESSAGE(JTRC_PPM_TEXT, "%ux%u text PPM image (maximum color value = %u)")
#ifdef TARGA_SUPPORTED
JMESSAGE(JERR_TGA_BADCMAP, "Unsupported Targa colormap format")
JMESSAGE(JERR_TGA_BADPARMS, "Invalid or unsupported Targa file")
JMESSAGE(JERR_TGA_COLORSPACE, "Targa output must be grayscale or RGB")
JMESSAGE(JTRC_TGA, "%ux%u RGB Targa image")
JMESSAGE(JTRC_TGA_GRAY, "%ux%u grayscale Targa image")
JMESSAGE(JTRC_TGA_MAPPED, "%ux%u colormapped Targa image")
#else
JMESSAGE(JERR_TGA_NOTCOMP, "Targa support was not compiled")
#endif /* TARGA_SUPPORTED */
JMESSAGE(JERR_BAD_CMAP_FILE,
"Color map file is invalid or of unsupported format")

10
src/cjpeg.c
View File

@ -290,7 +290,7 @@ parse_switches(j_compress_ptr cinfo, int argc, char **argv,
int argn;
char *arg;
#ifdef C_LOSSLESS_SUPPORTED
int psv, pt = 0;
int psv = 0, pt = 0;
#endif
boolean force_baseline;
boolean simple_progressive;
@ -403,7 +403,8 @@ parse_switches(j_compress_ptr cinfo, int argc, char **argv,
string */
if (*ptr)
sscanf(ptr, "%d", &pt);
jpeg_enable_lossless(cinfo, psv, pt);
/* We must postpone execution until data_precision is known. */
#else
fprintf(stderr, "%s: sorry, lossless output was not compiled\n",
progname);
@ -589,6 +590,11 @@ parse_switches(j_compress_ptr cinfo, int argc, char **argv,
jpeg_simple_progression(cinfo);
#endif
#ifdef C_LOSSLESS_SUPPORTED
if (psv != 0) /* process -lossless */
jpeg_enable_lossless(cinfo, psv, pt);
#endif
#ifdef C_MULTISCAN_FILES_SUPPORTED
if (scansarg != NULL) /* process -scans if it was present */
if (!read_scan_script(cinfo, scansarg))

26
src/djpeg.c
View File

@ -107,8 +107,8 @@ usage(void)
#endif
fprintf(stderr, "Switches (names may be abbreviated):\n");
fprintf(stderr, " -colors N Reduce image to no more than N colors\n");
fprintf(stderr, " -fast Fast, low-quality processing\n");
fprintf(stderr, " -colors N Reduce image to no more than N colors [legacy feature]\n");
fprintf(stderr, " -fast Low-quality processing [legacy feature]\n");
fprintf(stderr, " -grayscale Force grayscale output\n");
fprintf(stderr, " -rgb Force RGB output\n");
fprintf(stderr, " -rgb565 Force RGB565 output\n");
@ -120,13 +120,13 @@ usage(void)
(DEFAULT_FMT == FMT_BMP ? " (default)" : ""));
#endif
#ifdef GIF_SUPPORTED
fprintf(stderr, " -gif Select GIF output format (LZW-compressed)%s\n",
fprintf(stderr, " -gif Select GIF output format (LZW-compressed)%s [legacy feature]\n",
(DEFAULT_FMT == FMT_GIF ? " (default)" : ""));
fprintf(stderr, " -gif0 Select GIF output format (uncompressed)%s\n",
fprintf(stderr, " -gif0 Select GIF output format (uncompressed)%s [legacy feature]\n",
(DEFAULT_FMT == FMT_GIF0 ? " (default)" : ""));
#endif
#ifdef BMP_SUPPORTED
fprintf(stderr, " -os2 Select BMP output format (OS/2 style)%s\n",
fprintf(stderr, " -os2 Select BMP output format (OS/2 style)%s [legacy feature]\n",
(DEFAULT_FMT == FMT_OS2 ? " (default)" : ""));
#endif
#ifdef PPM_SUPPORTED
@ -134,7 +134,7 @@ usage(void)
(DEFAULT_FMT == FMT_PPM ? " (default)" : ""));
#endif
#ifdef TARGA_SUPPORTED
fprintf(stderr, " -targa Select Targa output format%s\n",
fprintf(stderr, " -targa Select Targa output format%s [legacy feature]\n",
(DEFAULT_FMT == FMT_TARGA ? " (default)" : ""));
#endif
fprintf(stderr, "Switches for advanced users:\n");
@ -150,16 +150,18 @@ usage(void)
fprintf(stderr, " -dct float Use floating-point DCT method [legacy feature]%s\n",
(JDCT_DEFAULT == JDCT_FLOAT ? " (default)" : ""));
#endif
fprintf(stderr, " -dither fs Use F-S dithering (default)\n");
fprintf(stderr, " -dither none Don't use dithering in quantization\n");
fprintf(stderr, " -dither ordered Use ordered dither (medium speed, quality)\n");
fprintf(stderr, " -dither fs Use Floyd-Steinberg dithering when quantizing colors (default)\n");
fprintf(stderr, " [legacy feature]\n");
fprintf(stderr, " -dither none Don't use dithering when quantizing colors [legacy feature]\n");
fprintf(stderr, " -dither ordered Use ordered dithering when quantizing colors\n");
fprintf(stderr, " [legacy feature]\n");
fprintf(stderr, " -icc FILE Extract ICC profile to FILE\n");
#ifdef QUANT_2PASS_SUPPORTED
fprintf(stderr, " -map FILE Map to colors used in named image file\n");
fprintf(stderr, " -map FILE Quantize to colors used in named image file [legacy feature]\n");
#endif
fprintf(stderr, " -nosmooth Don't use high-quality upsampling\n");
fprintf(stderr, " -nosmooth Use faster, lower-quality upsampling\n");
#ifdef QUANT_1PASS_SUPPORTED
fprintf(stderr, " -onepass Use 1-pass quantization (fast, low quality)\n");
fprintf(stderr, " -onepass Use 1-pass color quantization (low quality) [legacy feature]\n");
#endif
fprintf(stderr, " -maxmemory N Maximum memory to use (in kbytes)\n");
fprintf(stderr, " -maxscans N Maximum number of scans to allow in input file\n");

31
src/jcmaster.c
View File

@ -751,22 +751,25 @@ jinit_c_master_control(j_compress_ptr cinfo, boolean transcode_only)
/* Validate parameters, determine derived values */
initial_setup(cinfo, transcode_only);
if (cinfo->master->lossless || /* TEMPORARY HACK ??? */
(cinfo->progressive_mode && !cinfo->arith_code))
cinfo->optimize_coding = TRUE; /* assume default tables no good for
progressive mode or lossless mode */
for (i = 0; i < NUM_HUFF_TBLS; i++) {
if (cinfo->dc_huff_tbl_ptrs[i] != NULL ||
cinfo->ac_huff_tbl_ptrs[i] != NULL) {
empty_huff_tables = FALSE;
break;
if (cinfo->arith_code)
cinfo->optimize_coding = FALSE;
else {
if (cinfo->master->lossless || /* TEMPORARY HACK ??? */
cinfo->progressive_mode)
cinfo->optimize_coding = TRUE; /* assume default tables no good for
progressive mode or lossless mode */
for (i = 0; i < NUM_HUFF_TBLS; i++) {
if (cinfo->dc_huff_tbl_ptrs[i] != NULL ||
cinfo->ac_huff_tbl_ptrs[i] != NULL) {
empty_huff_tables = FALSE;
break;
}
}
if (cinfo->data_precision == 12 && !cinfo->optimize_coding &&
(empty_huff_tables || using_std_huff_tables(cinfo)))
cinfo->optimize_coding = TRUE; /* assume default tables no good for
12-bit data precision */
}
if (cinfo->data_precision == 12 && !cinfo->arith_code &&
!cinfo->optimize_coding &&
(empty_huff_tables || using_std_huff_tables(cinfo)))
cinfo->optimize_coding = TRUE; /* assume default tables no good for 12-bit
data precision */
/* Initialize my private state */
if (transcode_only) {

2
src/jcparam.c
View File

@ -233,7 +233,7 @@ jpeg_set_defaults(j_compress_ptr cinfo)
* tables will be computed. This test can be removed if default tables
* are supplied that are valid for the desired precision.
*/
if (cinfo->data_precision == 12 && !cinfo->arith_code)
if (cinfo->data_precision == 12)
cinfo->optimize_coding = TRUE;
/* By default, use the simpler non-cosited sampling alignment */

9
src/jpeglib.h
View File

@ -585,11 +585,10 @@ struct jpeg_decompress_struct {
*/
int actual_number_of_colors; /* number of entries in use */
JSAMPARRAY colormap; /* The color map as a 2-D pixel array
If data_precision is 12 or 16, then this is
actually a J12SAMPARRAY or a J16SAMPARRAY,
so callers must type-cast it in order to
read/write 12-bit or 16-bit samples from/to
the array. */
If data_precision is 12, then this is
actually a J12SAMPARRAY, so callers must
type-cast it in order to read/write 12-bit
samples from/to the array. */
/* State variables: these variables indicate the progress of decompression.
* The application may examine these but must not modify them.

10
src/rdppm.c
View File

@ -5,7 +5,7 @@
* Copyright (C) 1991-1997, Thomas G. Lane.
* Modified 2009 by Bill Allombert, Guido Vollbeding.
* libjpeg-turbo Modifications:
* Copyright (C) 2015-2017, 2020-2023, D. R. Commander.
* Copyright (C) 2015-2017, 2020-2024, D. R. Commander.
* For conditions of distribution and use, see the accompanying README.ijg
* file.
*
@ -707,7 +707,7 @@ start_input_ppm(j_compress_ptr cinfo, cjpeg_source_ptr sinfo)
if (cinfo->in_color_space == JCS_UNKNOWN ||
cinfo->in_color_space == JCS_RGB)
cinfo->in_color_space = JCS_GRAYSCALE;
TRACEMS2(cinfo, 1, JTRC_PGM_TEXT, w, h);
TRACEMS3(cinfo, 1, JTRC_PGM_TEXT, w, h, maxval);
if (cinfo->in_color_space == JCS_GRAYSCALE)
source->pub.get_pixel_rows = get_text_gray_row;
else if (IsExtRGB(cinfo->in_color_space))
@ -722,7 +722,7 @@ start_input_ppm(j_compress_ptr cinfo, cjpeg_source_ptr sinfo)
case '3': /* it's a text-format PPM file */
if (cinfo->in_color_space == JCS_UNKNOWN)
cinfo->in_color_space = JCS_EXT_RGB;
TRACEMS2(cinfo, 1, JTRC_PPM_TEXT, w, h);
TRACEMS3(cinfo, 1, JTRC_PPM_TEXT, w, h, maxval);
if (IsExtRGB(cinfo->in_color_space))
source->pub.get_pixel_rows = get_text_rgb_row;
else if (cinfo->in_color_space == JCS_CMYK)
@ -736,7 +736,7 @@ start_input_ppm(j_compress_ptr cinfo, cjpeg_source_ptr sinfo)
if (cinfo->in_color_space == JCS_UNKNOWN ||
cinfo->in_color_space == JCS_RGB)
cinfo->in_color_space = JCS_GRAYSCALE;
TRACEMS2(cinfo, 1, JTRC_PGM, w, h);
TRACEMS3(cinfo, 1, JTRC_PGM, w, h, maxval);
if (maxval > 255) {
if (cinfo->in_color_space == JCS_GRAYSCALE)
source->pub.get_pixel_rows = get_word_gray_row;
@ -766,7 +766,7 @@ start_input_ppm(j_compress_ptr cinfo, cjpeg_source_ptr sinfo)
case '6': /* it's a raw-format PPM file */
if (cinfo->in_color_space == JCS_UNKNOWN)
cinfo->in_color_space = JCS_EXT_RGB;
TRACEMS2(cinfo, 1, JTRC_PPM, w, h);
TRACEMS3(cinfo, 1, JTRC_PPM, w, h, maxval);
if (maxval > 255) {
if (IsExtRGB(cinfo->in_color_space))
source->pub.get_pixel_rows = get_word_rgb_row;

4
src/tjbench.c
View File

@ -1047,7 +1047,6 @@ int main(int argc, char *argv[])
printf("Using fastest DCT/IDCT algorithm\n\n");
fastDCT = 1;
} else if (!strcasecmp(argv[i], "-optimize")) {
printf("Using optimized baseline entropy coding\n\n");
optimize = 1;
xformOpt |= TJXOPT_OPTIMIZE;
} else if (!strcasecmp(argv[i], "-progressive")) {
@ -1197,6 +1196,9 @@ int main(int argc, char *argv[])
}
}
if (optimize && !progressive && !arithmetic && !lossless && precision != 12)
printf("Using optimized baseline entropy coding\n\n");
if (precision == 16 && !lossless) {
printf("ERROR: -lossless must be specified along with -precision 16\n");
retval = -1; goto bailout;