Various doc tweaks

- "bits per component" = "bits per sample"

  Describing the data precision of a JPEG image using "bits per
  component" is technically correct, but "bits per sample" is the
  terminology that the JPEG-1 spec uses.  Also, "bits per component" is
  more commonly used to describe the precision of packed-pixel formats
  (as opposed to "bits per pixel") rather than planar formats, in which
  all components are grouped together.

- Unmention legacy display technologies.  Colormapped and monochrome
  displays aren't a thing anymore, and even when they were still a
  thing, it was possible to display full-color images to them.  In 1991,
  when JPEG decompression time was measured in minutes per megapixel, it
  made sense to keep a decompressed copy of JPEG images on disk, in a
  format that could be displayed without further color conversion (since
  color conversion was slow and memory-intensive.)  In 2024, JPEG
  decompression time is measured in milliseconds per megapixel, and
  color conversion is even faster.  Thus, JPEG images can be
  decompressed, displayed, and color-converted (if necessary) "on the
  fly" at speeds too fast for human vision to perceive.  (In fact, your
  TV performs much more complicated decompression algorithms at least 60
  times per second.)

- Document that color quantization (and associated features), GIF
  input/output, Targa input/output, and OS/2 BMP input/output are legacy
  features.  Legacy status doesn't necessarily mean that the features
  are deprecated.  Rather, it is meant to discourage users from using
  features that may be of little or no benefit on modern machines (such
  as low-quality modes that had significant performance advantages in
  the early 1990s but no longer do) and that are maintained on a
  break/fix basis only.

- General wordsmithing, grammar/punctuation policing, and formatting
  tweaks

- Clarify which data precisions each cjpeg input format and each djpeg
  output format supports.

- cjpeg.1: Remove unnecessary and impolitic statement about the -targa
  switch.

- Adjust or remove performance claims to reflect the fact that:
  * On modern machines, the djpeg "-fast" switch has a negligible effect
    on performance.
  * There is a measurable difference between the performance of Floyd-
    Steinberg dithering and no dithering, but it is not likely
    perceptible to most users.
  * There is a measurable difference between the performance of 1-pass
    and 2-pass color quantization, but it is not likely perceptible to
    most users.
  * There is a measurable difference between the performance of
    full-color and grayscale output when decompressing a full-color JPEG
    image, but it is not likely perceptible to most users.
  * IDCT scaling does not necessarily improve performance.  (It
    generally does if the scaling factor is <= 1/2 and generally doesn't
    if the scaling factor is > 1/2, at least on my machine.  The
    performance claim made in jpeg-6b was probably invalidated when we
    merged the additional scaling factors from jpeg-7.)

- Clarify which djpeg switches/output formats cannot be used when
  decompressing lossless JPEG images.

- Remove djpeg hints, since those involve quality vs. speed tradeoffs
  that are no longer relevant for modern machines.

- Remove documentation regarding using color quantization with 16-bit
  data precision.  (Color quantization requires lossy mode.)

- Java: Fix typos in TJDecompressor.decompress12() and
  TJDecompressor.decompress16() documentation.

- jpegtran.1: Fix truncated paragraph

  In a man page, a single quote at the start of a line is interpreted as
  a macro.

  Closes #775

- libjpeg.txt:
  * Mention J16SAMPLE data type (oversight.)
  * Remove statement about extending jdcolor.c.  (libjpeg-turbo is not
    quite as DIY as libjpeg once was.)
  * Remove paragraph about tweaking the various typedefs in jmorecfg.h.
    It is no longer relevant for modern machines.
  * Remove caveat regarding systems with ints less than 16 bits wide.
    (ANSI/ISO C requires an int to be at least 16 bits wide, and
    libjpeg-turbo has never supported non-ANSI compilers.)

- usage.txt:
  * Add copyright header.
  * Document cjpeg -icc, -memdst, -report, -strict, and -version
    switches.
  * Document djpeg -icc, -maxscans, -memsrc, -report, -skip, -crop,
    -strict, and -version switches.
  * Document jpegtran -icc, -maxscans, -report, -strict, and -version
    switches.

CMakeLists.txt

@@ -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)

ChangeLog.md

@@ -13,8 +13,8 @@ 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
+12-bit-per-sample Start Of Frame segment followed by an incomplete
-8-bit-per-component Start Of Frame segment) using buffered-image mode and input
+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.

README.ijg

@@ -89,9 +89,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
+decoding, but they are essential for output to colormapped file formats.  These
-colormapped displays.  These extra functions can be compiled out of the
+extra functions can be compiled out of the library if not required for a
-library if not required for a particular application.
+particular application.
 
 We have also included "jpegtran", a utility for lossless transcoding between
 different JPEG processes, and "rdjpgcom" and "wrjpgcom", two simple

cjpeg.1

@@ -1,4 +1,4 @@
-.TH CJPEG 1 "14 Dec 2023"
+.TH CJPEG 1 "21 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.
+Create RGB JPEG file.  Using this switch suppresses the conversion from RGB
-Using this switch suppresses the conversion from RGB
 colorspace input to the default YCbCr JPEG colorspace.
 .TP
 .B \-optimize
@@ -63,15 +63,15 @@ decompression are unaffected by
 Create progressive JPEG file (see below).
 .TP
 .B \-targa
-Input file is Targa format.  Targa files that contain an "identification"
+Input file is Targa format [legacy feature].  Targa files that contain an
-field will not be automatically recognized by
+"identification" field will not be automatically recognized by
-.BR cjpeg ;
+.BR cjpeg .
-for such files you must specify
+For such files, you must specify
 .B \-targa
 to make
 .B cjpeg
-treat the input as Targa format.
+treat the input as Targa format.  For most Targa files, you won't need this
-For most Targa files, you won't need this switch.
+switch.
 .PP
 The
 .B \-quality
@@ -153,10 +153,15 @@ 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.)
 .B Caution:
-12-bit and 16-bit JPEG is not yet widely implemented, so many decoders will be
+12-bit and 16-bit data precision is not yet widely implemented, so many
-unable to view a 12-bit or 16-bit JPEG file at all.
+decoders will be unable to handle a 12-bit-per-sample or 16-bit-per-sample JPEG
+file at all.
 .TP
 .BI \-lossless " psv[,Pt]"
 Create a lossless JPEG file using the specified predictor selection value
@@ -174,11 +179,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
+handle a lossless JPEG file at all.  In most cases, compressing and
-a lossless JPEG file is considerably slower than compressing and decompressing
+decompressing a lossless JPEG file is considerably slower than compressing and
-a lossy JPEG file, and lossless JPEG files are much larger than lossy JPEG
+decompressing a lossy JPEG file, and lossless JPEG files are much larger than
-files.  Also note that the following features will be unavailable when
+lossy JPEG files.  Also note that the following features will be unavailable
-compressing or decompressing a lossless JPEG file:
+when compressing or decompressing a lossless JPEG file:
 .IP
 - Quality/quantization table selection
 .IP
@@ -205,8 +210,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
+arithmetic-coded JPEG is not yet widely implemented, so many decoders will be
-unable to view an arithmetic coded JPEG file at all.
+unable to handle an arithmetic-coded JPEG file at all.
 .TP
 .B \-dct int
 Use accurate integer DCT method (default).
@@ -349,10 +354,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
+compressing full-color (24-bit through 48-bit) images.  In particular, don't
-cartoons, line drawings, and other images that have only a few distinct
+try to convert cartoons, line drawings, and other images that have only a few
-colors.  GIF works great on these, JPEG does not.  If you want to convert a
+distinct colors.  GIF works great on these; JPEG does not.  If you want to
-GIF to JPEG, you should experiment with
+convert a GIF to JPEG, you should experiment with
 .BR cjpeg 's
 .B \-quality
 and
@@ -407,8 +412,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.)

djpeg.1

@@ -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
+Reduce image to at most N colors [legacy feature].  This reduces the number of
-the output image, so that it can be displayed on a colormapped display or
+colors used in the output image so that it can be stored in a colormapped file
-stored in a colormapped file format.  For example, if you have an 8-bit
+format.  This feature cannot be used when decompressing lossless JPEG images.
-display, you'd need to reduce to 256 or fewer colors.
 .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
+Select recommended processing options for low-quality output [legacy feature].
-default options are chosen for highest quality output.)  Currently, this is
+(The default options are chosen for highest-quality output.)  Currently, this
-equivalent to \fB\-dct fast \-nosmooth \-onepass \-dither ordered\fR.
+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
+Force grayscale output even if JPEG file is full-color.  This feature cannot be
-monochrome displays; also,
+used when decompressing full-color lossless JPEG images.
-.B djpeg
-runs noticeably faster in this mode.
 .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,
+your screen.  This feature cannot be used when decompressing lossless JPEG
-.B djpeg
+images.
-runs much faster when scaling down the output.
 .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
+Select GIF output format (LZW-compressed) [legacy feature].  Since GIF does not
-than 256 colors,
+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
+Select GIF output format (uncompressed) [legacy feature].  Since GIF does not
-256 colors,
+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
+Select BMP output format (OS/2 1.x flavor) [legacy feature].  8-bit colormapped
-emitted if
+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
+Select Targa output format [legacy feature].  Grayscale format is emitted if
-grayscale or 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.
+Do not use dithering when quantizing colors [legacy feature].  By default,
-By default, Floyd-Steinberg dithering is applied when quantizing colors; this
+Floyd-Steinberg dithering is applied when quantizing colors.  This is slower
-is slow but usually produces the best results.  Ordered dither is a compromise
+but usually produces the best results.  Ordered dithering is a compromise
-between speed and quality; no dithering is fast but usually looks awful.  Note
+between speed and quality.  No dithering is faster but usually looks awful.
-that these switches have no effect unless color quantization is being done.
+Note that these switches have no effect unless color quantization is being
-Ordered dither is only available in
+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
+Quantize to the colors used in the specified image file [legacy feature].  This
-producing multiple files with identical color maps, or for forcing a
+is useful for producing multiple files with identical color maps, or for
-predefined set of colors to be used.  The
+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
+Use one-pass instead of two-pass color quantization [legacy feature].  The
-faster and needs less memory, but it produces a lower-quality image.
+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
+Also, the one-pass method is always used for grayscale output.  (The two-pass
-method is no improvement then).
+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
+This example decompresses the JPEG file foo.jpg and saves the output in 8-bit
-256 colors, and saves the output in 8-bit BMP format in foo.bmp:
+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

djpeg.c

@@ -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, "  -colors N      Reduce image to no more than N colors [legacy feature]\n");
-  fprintf(stderr, "  -fast          Fast, low-quality processing\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 fs     Use Floyd-Steinberg dithering when quantizing colors (default)\n");
-  fprintf(stderr, "  -dither none   Don't use dithering in quantization\n");
+  fprintf(stderr, "                 [legacy feature]\n");
-  fprintf(stderr, "  -dither ordered  Use ordered dither (medium speed, quality)\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");

java/doc/index-all.html

@@ -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>

java/doc/org/libjpegturbo/turbojpeg/TJCompressor.html

@@ -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>

java/doc/org/libjpegturbo/turbojpeg/TJDecompressor.html

@@ -1184,7 +1184,7 @@ public byte[] decompress​(int 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>

java/org/libjpegturbo/turbojpeg/TJCompressor.java

@@ -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

java/org/libjpegturbo/turbojpeg/TJDecompressor.java

@@ -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 {

jpeglib.h

@@ -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
+                                   If data_precision is 12, then this is
-                                   actually a J12SAMPARRAY or a J16SAMPARRAY,
+                                   actually a J12SAMPARRAY, so callers must
-                                   so callers must type-cast it in order to
+                                   type-cast it in order to read/write 12-bit
-                                   read/write 12-bit or 16-bit samples from/to
+                                   samples from/to the array. */
-                                   the array. */
 
   /* State variables: these variables indicate the progress of decompression.
    * The application may examine these but must not modify them.

jpegtran.1

@@ -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
+adjustment of the region dimensions may be optionally disabled by attaching
-'f' character ("force") to the width or height number.
+an 'f' character ("force") to the width or height number.
 
 The image can be losslessly cropped by giving the switch:
 .TP

libjpeg.txt

@@ -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
+The JPEG standard provides for baseline (8-bit-per-sample) and
-as 8-bit, 12-bit, and 16-bit lossless (predictive) processes.  This code
+12-bit-per-sample DCT processes as well as 8-bit-per-sample, 12-bit-per-sample,
-supports 12-bit-per-component lossy or lossless JPEG if you set
+and 16-bit-per-sample lossless (predictive) processes.  This code supports
-cinfo->data_precision to 12 and 16-bit-per-component lossless JPEG if you set
+12-bit-per-sample lossy or lossless JPEG if you set cinfo->data_precision to 12
-cinfo->data_precision to 16.  Note that this causes the sample size to be
+and 16-bit-per-sample lossless JPEG if you set cinfo->data_precision to 16.
-larger than a char, so it affects the surrounding application's image data.
+Note that this causes the sample size to be larger than a char, so it affects
-The sample applications cjpeg and djpeg can support 12-bit mode only for PPM,
+the surrounding application's image data.  The sample applications cjpeg and
-PGM, and GIF file formats and 16-bit mode only for PPM and PGM file formats.
+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
+Note that, when 12-bit data precision is enabled in lossy mode, the library
-in Huffman optimization mode, in order to generate valid Huffman tables.  This
+compresses in Huffman optimization mode by default, in order to generate valid
-is necessary because our default Huffman tables only cover 8-bit data.  If you
+Huffman tables.  This is necessary because our default Huffman tables only
-need to output 12-bit files in one pass, you'll have to supply suitable default
+cover 8-bit data.  If you need to output 12-bit-per-sample JPEG files in one
-Huffman tables.  You may also want to supply your own DCT quantization tables;
+pass, you'll have to supply suitable default Huffman tables.  You may also want
-the existing quality-scaling code has been developed for 8-bit use, and
+to supply your own DCT quantization tables; the existing quality-scaling code
-probably doesn't generate especially good tables for 12-bit.
+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"
+array of data type JSAMPLE, J12SAMPLE, or J16SAMPLE --- which is typically
-or "short" (respectively), unless you've changed jmorecfg.h.  (You can also
+"unsigned char", "short", or "unsigned short" (respectively) unless you've
-change the RGB pixel layout, say to B,G,R order, by modifying jmorecfg.h.  But
+changed jmorecfg.h.
-see the restrictions listed in that file before doing so.)
 
 A 2-D array of pixels is formed by making a list of pointers to the starts of
 scanlines; so the scanlines need not be physically adjacent in memory.  Even
@@ -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
+cinfo->data_precision (normally 8 bits per sample).  For instance, if you
-compress data that's only 6 bits/channel, you should left-justify each value in
+choose to compress data that's only 6 bits/channel, you should left-justify
-a byte before passing it to the compressor.  If you need to compress data
+each value in a byte before passing it to the compressor.  If you need to
-that has more than 8 bits/channel, set cinfo->data_precision = 12 or 16.
+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
+(ie, at most 256 colors for 8-bit data precision and 4096 colors for 12-bit
-precision, and 65536 colors for 16-bit data precision).
+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
+        To create a 12-bit-per-sample JPEG file, set data_precision to 12 prior
-        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 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,10 @@ 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.  This parameter has no effect in
+        progressive mode or lossless mode, in which optimal Huffman tables are
+        always computed, and it defaults to TRUE for 12-bit data precision
+        unless Huffman tables have been supplied.
 
 unsigned int restart_interval
 int restart_in_rows
@@ -1303,13 +1309,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 +1350,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 from a color file.  Note that not all possible color space
-        output is faster than full color since the color components need not
+        transforms are currently implemented.
-        be processed.)  Note that not all possible color space transforms are
-        currently implemented; you may need to extend jdcolor.c if you want an
-        unusual conversion.
 
 unsigned int scale_num, scale_denom
         Scale the image by the fraction scale_num/scale_denom.  Default is
@@ -1356,31 +1359,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 +1400,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
+        CAUTION: if data_precision is 12, then this is actually a J12SAMPARRAY,
-        J12SAMPARRAY or a J16SAMPARRAY, so it must be type-cast in order to
+        so it must be type-cast in order to read/write 12-bit samples from/to
-        read/write 12-bit or 16-bit samples from/to the array.
+        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 +1468,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 +2338,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 +3190,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
+32-bit ints.  For 12-bit-per-sample and 16-bit-per-sample JPEG data, double the
-buffers and quantization pixel buffer.  The "fixed-size" data will be somewhat
+size of the strip buffers and quantization pixel buffer.  The "fixed-size" data
-smaller with 16-bit ints, larger with 64-bit ints.  Also, CMYK or other unusual
+will be somewhat smaller with 16-bit ints, larger with 64-bit ints.  Also, CMYK
-color spaces will require different amounts of space.
+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 +3219,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 +3257,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
+code work by modifying the typedefs in jmorecfg.h.
-have difficulty if int is less than 16 bits wide, since references to plain
-int abound in the code.
 
 char can be either signed or unsigned, although the code runs faster if an
 unsigned char type is available.  If char is wider than 8 bits, you will need

usage.txt

@@ -1,5 +1,8 @@
-NOTE:  This file was modified by The libjpeg-turbo Project to include only
+This file was part of the Independent JPEG Group's software:
-information relevant to libjpeg-turbo and to wordsmith certain sections.
+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
+PGM (PBMPLUS grayscale format), BMP, GIF [legacy feature], and Targa [legacy
-input image format automatically, with the exception of some Targa files.  You
+feature].  cjpeg recognizes the input image format automatically, with the
-have to tell djpeg which format to generate.
+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
+                        specifying -grayscale, you'll get a smaller JPEG file
-                        takes less time to process.
+                        that takes less time to process.
 
-        -rgb            Create RGB JPEG file.
+        -rgb            Create RGB JPEG file.  Using this switch suppresses the
-                        Using this switch suppresses the conversion from RGB
+                        conversion from RGB colorspace input to the default
-                        colorspace input to the default YCbCr JPEG colorspace.
+                        YCbCr JPEG colorspace.
 
         -optimize       Perform optimization of entropy encoding parameters.
                         Without this, default encoding parameters are used.
@@ -89,11 +93,12 @@ The basic command line switches for cjpeg are:
 
         -progressive    Create progressive JPEG file (see below).
 
-        -targa          Input file is Targa format.  Targa files that contain
+        -targa          Input file is Targa format [legacy feature].  Targa
-                        an "identification" field will not be automatically
+                        files that contain an "identification" field will not
-                        recognized by cjpeg; for such files you must specify
+                        be automatically recognized by cjpeg.  For such files,
-                        -targa to make cjpeg treat the input as Targa format.
+                        you must specify -targa to make cjpeg treat the input
-                        For most Targa files, you won't need this switch.
+                        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 +167,14 @@ 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
+                       -lossless must also be specified.  Note that only the
-                       16-bit JPEG is not yet widely implemented, so many
+                       PBMPLUS input file format supports data precisions other
-                       decoders will be unable to view a 12-bit or 16-bit JPEG
+                       than 8.  (For historical reasons, cjpeg allows GIF input
-                       file at all.
+                       files to be converted into 12-bit-per-sample JPEG files,
+                       but this is not a useful conversion.)  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.
 
         -lossless psv[,Pt] Create a lossless JPEG file using the specified
                         predictor selection value (1 - 7) and optional point
@@ -177,7 +186,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 +206,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 +249,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 +267,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 +326,78 @@ DJPEG DETAILS
 
 The basic command line switches for djpeg are:
 
-        -colors N       Reduce image to at most N colors.  This reduces the
+        -colors N       Reduce image to at most N colors [legacy feature].
-        or -quantize N  number of colors used in the output image, so that it
+        or -quantize N  This reduces the number of colors used in the output
-                        can be displayed on a colormapped display or stored in
+                        image so that it can be stored in a colormapped file
-                        a colormapped file format.  For example, if you have
+                        format.  This feature cannot be used when decompressing
-                        an 8-bit display, you'd need to reduce to 256 or fewer
+                        lossless JPEG images.  (-colors is the recommended
-                        colors.  (-colors is the recommended name, -quantize
+                        name.  -quantize is provided only for backward
-                        is provided only for backwards compatibility.)
+                        compatibility.)
 
-        -fast           Select recommended processing options for fast, low
+        -fast           Select recommended processing options for low-quality
-                        quality output.  (The default options are chosen for
+                        output [legacy feature].  (The default options are
-                        highest quality output.)  Currently, this is equivalent
+                        chosen for highest-quality output.)  Currently, this is
-                        to "-dct fast -nosmooth -onepass -dither ordered".
+                        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.
+        -grayscale      Force grayscale output even if JPEG file is full-color.
-                        Useful for viewing on monochrome displays; also,
+                        This feature cannot be used when decompressing
-                        djpeg runs noticeably faster in this mode.
+                        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
+        -scale M/N      Scale the output image by a factor M/N.  Currently the
-                        the scale factor must be M/8, where M is an integer
+                        scale factor must be M/8, where M is an integer between
-                        between 1 and 16 inclusive, or any reduced fraction
+                        1 and 16 inclusive, or any reduced fraction thereof
-                        thereof (such as 1/2, 3/4, etc.  Scaling is handy if
+                        (such as 1/2, 3/4, etc.)  Scaling is handy if the image
-                        the image is larger than your screen; also, djpeg runs
+                        is larger than your screen.  This feature cannot be
-                        much faster when scaling down the output.
+                        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
+        -gif            Select GIF output format (LZW-compressed) [legacy
-                        does not support more than 256 colors, -colors 256 is
+                        feature].  Since GIF does not support more than 256
-                        assumed (unless you specify a smaller number of
+                        colors, -colors 256 is assumed (unless you specify a
-                        colors).  If you specify -fast, the default number of
+                        smaller number of colors).  If you specify -fast, the
-                        colors is 216.
+                        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
+        -gif0           Select GIF output format (uncompressed) [legacy
-                        does not support more than 256 colors, -colors 256 is
+                        feature].  Since GIF does not support more than 256
-                        assumed (unless you specify a smaller number of
+                        colors, -colors 256 is assumed (unless you specify a
-                        colors).  If you specify -fast, the default number of
+                        smaller number of colors).  If you specify -fast, the
-                        colors is 216.
+                        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
+        -os2            Select BMP output format (OS/2 1.x flavor) [legacy
-                        colormapped format is emitted if -colors or -grayscale
+                        feature].  8-bit colormapped format is emitted if
-                        is specified, or if the JPEG file is grayscale;
+                        -colors or -grayscale is specified, or if the JPEG file
-                        otherwise, 24-bit full-color format is emitted.
+                        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
+                        grayscale or if -grayscale is specified; otherwise PPM
-                        PPM is emitted.
+                        is emitted.
 
-        -targa          Select Targa output format.  Grayscale format is
+        -targa          Select Targa output format [legacy feature].  Grayscale
-                        emitted if the JPEG file is grayscale or if
+                        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 +441,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 fs      Use Floyd-Steinberg dithering when quantizing colors
-        -dither ordered Use ordered dithering in color quantization.
+                        [legacy feature].
-        -dither none    Do not use dithering in color quantization.
+        -dither ordered Use ordered dithering when quantizing colors [legacy
-                        By default, Floyd-Steinberg dithering is applied when
+                        feature].
-                        quantizing colors; this is slow but usually produces
+        -dither none    Do not use dithering when quantizing colors [legacy
-                        the best results.  Ordered dither is a compromise
+                        feature].  By default, Floyd-Steinberg dithering is
-                        between speed and quality; no dithering is fast but
+                        applied when quantizing colors.  This is slower but
-                        usually looks awful.  Note that these switches have
+                        usually produces the best results.  Ordered dithering
-                        no effect unless color quantization is being done.
+                        is a compromise between speed and quality.  No
-                        Ordered dither is only available in -onepass mode.
+                        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
+        -icc FILE       Extract ICC color management profile to the specified
-                        file.  This is useful for producing multiple files
+                        file.
-                        with identical color maps, or for forcing a predefined
+
-                        set of colors to be used.  The FILE must be a GIF
+        -map FILE       Quantize to the colors used in the specified image file
-                        or PPM file.  This option overrides -colors and
+                        [legacy feature].  This is useful for producing
-                        -onepass.
+                        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.
+        -onepass        Use one-pass instead of two-pass color quantization
-                        The one-pass method is faster and needs less memory,
+                        [legacy feature].  The one-pass method needs less
-                        but it produces a lower-quality image.  -onepass is
+                        memory, but it produces a lower-quality image.
-                        ignored unless you also say -colors N.  Also,
+                        -onepass is ignored unless you also specify -colors N.
-                        the one-pass method is always used for grayscale
+                        Also, the one-pass method is always used for grayscale
-                        output (the two-pass method is no improvement then).
+                        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 +481,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
+compressing full-color (24-bit through 48-bit) images.  In particular, don't
-cartoons, line drawings, and other images that have only a few distinct
+try to convert cartoons, line drawings, and other images that have only a few
-colors.  GIF works great on these, JPEG does not.  If you want to convert a
+distinct colors.  GIF works great on these; JPEG does not.  If you want to
-GIF to JPEG, you should experiment with cjpeg's -quality and -smooth options
+convert a GIF to JPEG, you should experiment with cjpeg's -quality and -smooth
-to get a satisfactory conversion.  -smooth 10 or so is often helpful.
+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 +551,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 +566,12 @@ explicit -maxmemory switch.
 
 JPEGTRAN
 
-jpegtran performs various useful transformations of JPEG files.
+jpegtran performs various useful transformations of lossy (DCT-based) JPEG
-It can translate the coded representation from one variant of JPEG to another,
+files.  It can translate the coded representation from one variant of JPEG to
-for example from baseline JPEG to progressive JPEG or vice versa.  It can also
+another, for example from baseline JPEG to progressive JPEG or vice versa.  It
-perform some rearrangements of the image data, for example turning an image
+can also perform some rearrangements of the image data, for example turning an
-from landscape to portrait format by rotation.  For EXIF files and JPEG files
+image from landscape to portrait format by rotation.  For EXIF files and JPEG
-containing Exif data, you may prefer to use exiftran instead.
+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 +727,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.