IJG dox: Wordsmithing and formatting tweaks

- Remove the section in libjpeg.txt that advised against building
  libjpeg as a shared library.  We obviously do not follow that advice,
  and libjpeg-turbo does guarantee backward ABI compatibility in our
  libjpeg API library, even though libjpeg did not and does not.
  (Future expansion of our libjpeg API library, if necessary, will be
  accomplished using get/set functions that store the new parameters
  in the opaque master structs.  Refer to
  db2986c96f.)

- Unmention install.txt, which was never relevant to libjpeg-turbo and
  was removed in v1.3 (6f96153c67).

- Remove extraneous spaces.

- Document the fact that TWO_FILE_COMMANDLINE must be defined in order
  to use the two-file interface with cjpeg, djpeg, jpegtran, and
  wrjpgcom.  libjpeg-turbo never enables that interface by default.
This commit is contained in:
DRC
2022-03-09 10:50:51 -06:00
parent fdab4a7af4
commit 932b5bb0d5
2 changed files with 18 additions and 29 deletions

View File

@@ -3,7 +3,7 @@ USING THE IJG JPEG LIBRARY
This file was part of the Independent JPEG Group's software:
Copyright (C) 1994-2013, Thomas G. Lane, Guido Vollbeding.
libjpeg-turbo Modifications:
Copyright (C) 2010, 2014-2018, 2020, D. R. Commander.
Copyright (C) 2010, 2014-2018, 2020, 2022, D. R. Commander.
Copyright (C) 2015, Google, Inc.
For conditions of distribution and use, see the accompanying README.ijg file.
@@ -840,18 +840,7 @@ is to prepare a library file ("libjpeg.a", or a corresponding name on non-Unix
machines) and reference it at your link step. If you use only half of the
library (only compression or only decompression), only that much code will be
included from the library, unless your linker is hopelessly brain-damaged.
The supplied makefiles build libjpeg.a automatically (see install.txt).
While you can build the JPEG library as a shared library if the whim strikes
you, we don't really recommend it. The trouble with shared libraries is that
at some point you'll probably try to substitute a new version of the library
without recompiling the calling applications. That generally doesn't work
because the parameter struct declarations usually change with each new
version. In other words, the library's API is *not* guaranteed binary
compatible across versions; we only try to ensure source-code compatibility.
(In hindsight, it might have been smarter to hide the parameter structs from
applications and introduce a ton of access functions instead. Too late now,
however.)
The supplied build system builds libjpeg.a automatically.
It may be worth pointing out that the core JPEG library does not actually
require the stdio library: only the default source/destination managers and
@@ -3075,9 +3064,8 @@ BITS_IN_JSAMPLE as 12 rather than 8. Note that this causes JSAMPLE to be
larger than a char, so it affects the surrounding application's image data.
The sample applications cjpeg and djpeg can support 12-bit mode only for PPM
and GIF file formats; you must disable the other file formats to compile a
12-bit cjpeg or djpeg. (install.txt has more information about that.)
At present, a 12-bit library can handle *only* 12-bit images, not both
precisions.
12-bit cjpeg or djpeg. At present, a 12-bit library can handle *only* 12-bit
images, not both precisions.
Note that a 12-bit library always compresses in Huffman optimization mode,
in order to generate valid Huffman tables. This is necessary because our

View File

@@ -25,7 +25,7 @@ GENERAL USAGE
We provide two programs, cjpeg to compress an image file into JPEG format,
and djpeg to decompress a JPEG file back into a conventional image format.
On Unix-like systems, you say:
On most systems, you say:
cjpeg [switches] [imagefile] >jpegfile
or
djpeg [switches] [jpegfile] >imagefile
@@ -34,19 +34,19 @@ named. They always write to standard output (with trace/error messages to
standard error). These conventions are handy for piping images between
programs.
On most non-Unix systems, you say:
If you defined TWO_FILE_COMMANDLINE when compiling the programs, you can
instead say:
cjpeg [switches] imagefile jpegfile
or
djpeg [switches] jpegfile imagefile
i.e., both the input and output files are named on the command line. This
style is a little more foolproof, and it loses no functionality if you don't
have pipes. (You can get this style on Unix too, if you prefer, by defining
TWO_FILE_COMMANDLINE when you compile the programs; see install.txt.)
have pipes.
You can also say:
cjpeg [switches] -outfile jpegfile imagefile
or
djpeg [switches] -outfile imagefile jpegfile
djpeg [switches] -outfile imagefile jpegfile
This syntax works on all systems, so it is useful for scripts.
The currently supported image file formats are: PPM (PBMPLUS color format),
@@ -143,8 +143,8 @@ customized) quantization tables can be set with the -qtables option and
assigned to components with the -qslots option (see the "wizard" switches
below.)
JPEG files generated with separate luminance and chrominance quality are
fully compliant with standard JPEG decoders.
JPEG files generated with separate luminance and chrominance quality are fully
compliant with standard JPEG decoders.
CAUTION: For this setting to be useful, be sure to pass an argument of
-sample 1x1 to cjpeg to disable chrominance subsampling. Otherwise, the
@@ -218,7 +218,7 @@ Switches for advanced users:
space is needed, an error will occur.
-verbose Enable debug printout. More -v's give more printout.
or -debug Also, version information is printed at startup.
or -debug Also, version information is printed at startup.
The -restart option inserts extra markers that allow a JPEG decoder to
resynchronize after a transmission error. Without restart markers, any damage
@@ -467,9 +467,10 @@ quality. However, while the image data is losslessly transformed, metadata
can be removed. See the -copy option for specifics.
jpegtran uses a command line syntax similar to cjpeg or djpeg.
On Unix-like systems, you say:
On most systems, you say:
jpegtran [switches] [inputfile] >outputfile
On most non-Unix systems, you say:
If you defined TWO_FILE_COMMANDLINE when compiling the program, you can instead
say:
jpegtran [switches] inputfile outputfile
where both the input and output files are JPEG files.
@@ -649,13 +650,13 @@ file; it does not modify the input file. DO NOT try to overwrite the input
file by directing wrjpgcom's output back into it; on most systems this will
just destroy your file.
The command line syntax for wrjpgcom is similar to cjpeg's. On Unix-like
systems, it is
The command line syntax for wrjpgcom is similar to cjpeg's. On most systems,
it is
wrjpgcom [switches] [inputfilename]
The output file is written to standard output. The input file comes from
the named file, or from standard input if no input file is named.
On most non-Unix systems, the syntax is
If you defined TWO_FILE_COMMANDLINE when compiling the program, the syntax is:
wrjpgcom [switches] inputfilename outputfilename
where both input and output file names must be given explicitly.