mame/3rdparty/libjpeg/cdaltui.txt

IJG JPEG LIBRARY:  ALTERNATE USER INTERFACE FOR CJPEG/DJPEG

Copyright (C) 2020, Guido Vollbeding.
This file is part of the Independent JPEG Group's software.
For conditions of distribution and use, see the accompanying README file.


There is an alternate command-line user interface for the IJG JPEG software.
It is designed for use under MS-DOS, and may also be useful on other non-Unix
operating systems.  (For that matter, this code works fine on Unix, but the
standard command-line syntax is better on Unix because it is pipe-friendly.)

With this user interface, cjpeg and djpeg accept multiple input file names
on the command line; output file names are generated by substituting
appropriate extensions.  The user is prompted before any already-existing
file will be overwritten.

Expansion of wild-card file specifications is useful but is not directly
provided by this code.  Most DOS C compilers have the ability to do wild-card
expansion "behind the scenes", and we rely on that feature.  On other systems,
the shell may do it for you, as is done on Unix.

Also, a DOS-specific routine is provided to determine available memory;
this makes the -maxmemory switch unnecessary except in unusual cases.
If you know how to determine available memory on a different system,
you can easily add the necessary code.  (And please send it along to
jpeg-info@jpegclub.org so we can include it in future releases!)


INSTALLATION
============

Rename the standard cjpeg.c file to cjpegstd.c, then rename cjpegalt.c to
cjpeg.c.
Rename the standard djpeg.c file to djpegstd.c, then rename djpegalt.c to
djpeg.c.
Then build the software as described in install.txt, with these exceptions:

* Define PROGRESS_REPORT in jconfig.h if you want the percent-done display.
* Define NO_OVERWRITE_CHECK if you *don't* want overwrite confirmation.
* You may ignore the USE_SETMODE and TWO_FILE_COMMANDLINE symbols discussed
  in install.txt; these files do not use them.
* As given, djpegalt.c defaults to BMP output (not PPM output as in the
  standard djpeg.c).  If you want something different, modify DEFAULT_FMT.

You may also need to do something special to enable filename wild-card
expansion, assuming your compiler has that capability at all.

Modify the standard usage.txt file as described below.  (If you want to use
the Unix-style manual pages cjpeg.1 and djpeg.1, better fix them too.)

To restore the standard user interface:
Rename cjpeg.c to cjpegalt.c, then rename cjpegstd.c to cjpeg.c.
Rename djpeg.c to djpegalt.c, then rename djpegstd.c to djpeg.c.
Then recompile/rebuild.


Here are some specific notes for popular MS-DOS compilers:

Borland C:
  Add "-DMSDOS" to CFLAGS to enable use of the DOS memory determination code.
  Link with the standard library file WILDARGS.OBJ to get wild-card expansion.

Microsoft C:
  Add "-DMSDOS" to CFLAGS to enable use of the DOS memory determination code.
  Link with the standard library file SETARGV.OBJ to get wild-card expansion.
  In the versions I've used, you must also add /NOE to the linker switches to
  avoid a duplicate-symbol error from including SETARGV.

DJGPP (we recommend version 2.0 or later):
  Add "-DFREE_MEM_ESTIMATE=0" to CFLAGS.  Wild-card expansion is automatic.


USAGE
=====

Most of the standard usage.txt file also applies to the alternate version,
but replace its "GENERAL USAGE" section with the text below.  Edit the text
as necessary if you don't support wildcards or overwrite checking.  Be sure
to fix the djpeg switch descriptions if you are not defaulting to PPM output.
Also, if you've provided an accurate memory-estimation procedure, you can
probably eliminate the HINTS related to the -maxmemory switch.


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.

The basic command line is:
	cjpeg [switches] list of image files
or
	djpeg [switches] list of jpeg files

Each file named is compressed or decompressed.  The input file(s) are not
modified; the output data is written to files which have the same names
except for extension.  cjpeg always uses ".jpg" for the output file name's
extension; djpeg uses one of ".bmp", ".gif", ".ppm", ".rle", or ".tga",
depending on what output format is selected by the switches.

For example, to convert xxx.bmp to xxx.jpg and yyy.ppm to yyy.jpg, say:
	cjpeg xxx.bmp yyy.ppm

On most systems you can use standard wildcards to specify the list of input
files; for example, on DOS "djpeg *.jpg" decompresses all the JPEG files in
the current directory.

If an intended output file already exists, you'll be asked whether or not to
overwrite it.  If you say no, the program skips that input file and goes on
to the next one.

You can intermix switches and file names; for example
	djpeg -gif file1.jpg -targa file2.jpg
decompresses file1.jpg into GIF format (file1.gif) and file2.jpg into Targa
format (file2.tga).  Only switches to the left of a given file name affect
processing of that file; when there are conflicting switches, the rightmost
one takes precedence.

You can override the program's choice of output file name by using the
-outfile switch, as in
	cjpeg -outfile output.jpg input.ppm
-outfile only affects the first input file name to its right.

The currently supported image file formats are: PPM (PBMPLUS color format),
PGM (PBMPLUS grayscale format), BMP, GIF, Targa, and RLE (Utah Raster Toolkit
format).  (RLE is supported only if the URT library is available, which it
isn't on most non-Unix systems.)  cjpeg recognizes the input image format
automatically, with the exception of some Targa-format files.  You have to
tell djpeg which format to generate.

JPEG files are in the standard JFIF file format.  There are other,
less widely used JPEG-based file formats, but we don't support them.

All switch names may be abbreviated; for example, -grayscale may be written
-gray or -gr.  Most of the "basic" switches can be abbreviated to as little as
one letter.  Upper and lower case are equivalent (-BMP is the same as -bmp).
British spellings are also accepted (e.g., -greyscale), though for brevity
these are not mentioned below.