fpc/packages/pasjpeg/readme.txt

_____________________________________________________________________________

PASJPEG 1.1                                                   May 29th, 1999

Based on the Independent JPEG Group's JPEG software release 6b

Copyright (C) 1996,1998,1999 by NOMSSI NZALI Jacques H. C.
[kn&n DES]         See "Legal issues" for conditions of distribution and use.
_____________________________________________________________________________


Information in this file
========================

  o Introduction
  o Notes
  o File list
  o Translation
  o Legal issues
  o Archive Locations

Introduction
============

PASJPEG is a port of the sixth public release of the IJG C source (release
6b of 27-Mar-98) [3], that implements JPEG baseline, extended-sequential, and
progressive compression processes to Turbo Pascal 7.0 for DOS (TP). The code
has been tested under Delphi 3.0, it can be ported to other Pascal
environments, since many compilers try to be compatible to TP.

JPEG (pronounced "jay-peg") is a standardized familly of algorithms for
compression of continous tone still images. Most JPEG processes are lossy,
the output image is not exactly identical to the input image. However, on
typical photographic images, very good compression levels can be obtained
with no visible change, and remarkably high compression levels are possible
if you can tolerate a low-quality image [1],[2]. The Independent JPEG Group
(IJG) has created a free, portable C library for JPEG compression and
decompression of JPEG images.

The IJG documentation (system architecture, using the IJG JPEG library,
usage and file list) is a must read. The files DEMO.PAS, TEST.PAS, CJPEG.PAS,
DJPEG.PAS and EXAMPLE.PAS demonstrate the usage of the JPEG decompression
and compression library. The RDJPGCOM application shows how to parse a JFIF
file.

Notes:
======

* Please report any errors/problems you may find in code and in the
  documentation (e.g. this README.TXT file).

* The sample applications (CJPEG, DJPEG) doesn't support all the options
  of the original C code. WRJPGCOM is not ported.

* Environment variable JPEGMEM syntax changed;

* You can modify the jpeg.pas unit from the Delphi 3 distribution to
  use PasJPEG.

Change log
==========

1. bugs fixed: 
   * in procedure read_gif_map(), unit RDCOLMAP.PAS (used by DJPEG sample 
     application). Davie Lee Reed <[email protected]>
   * -dct int and -dct fast now bytewise equal to the IJG output.
   * -dct float produced large files

2. Support for scripts

3. BASM version of JIDCTINT.PAS for Delphi 2 and 3.

4. images with integral sampling ratios were not decoded correctly.
   Create a jpeg file with cjpeg and the option "-sample 4x1" and try to decode 
   it with any software that uses PasJpeg. Thanks to Jannie Gerber for reporting
   this with a fix: In JDSAMPLE.PAS, procedure int_upsample(), 
         
    for h := pred(h_expand) downto 0 do
    begin
      outptr^ := invalue;
 +=>  inc(outptr);   { this is the culprit that was left out!!! }
      Dec(outcount);
    end;

File list
=========

Here is a road map to the files in the PasJPEG distribution.  The
distribution includes the JPEG library proper, plus two application
programs ("cjpeg" and "djpeg") which use the library to convert JPEG
files to and from some other popular image formats.  A third application
"jpegtran" uses the library to do lossless conversion between different
variants of JPEG.  There is also the stand-alone applications "rdjpgcom".

Documentation(see README for a guide to the documentation files):

readme.txt      Introduction, Documentation

Additional files

demo.pas        Demo program, uses example.pas
example.pas     Sample code for calling JPEG library.
test.pas        Sample application code for demo.pas

Configuration/installation files and programs (see install.doc for more info):

jconfig.inc     Configuration declarations.

*.ijg           script files

Pascal source code files:

jinclude.pas    Central include file used by all IJG .c files to reference
		system include files.
jpeglib.pas     JPEG library's internal data structures, exported data
                and function declarations.
jmorecfg.pas    Additional configuration declarations; need not be changed
                for a standard installation.
jdeferr.pas     defines the error and message text.
jerror.pas      Declares JPEG library's error and trace message codes.
jinclude.pas    the place to specify system depedent input/output code.
jdct.pas        Private declarations for forward & reverse DCT subsystems.

These files contain most of the functions intended to be called directly by
an application program:

jcapimin.pas    Application program interface: core routines for compression.
jcapistd.pas    Application program interface: standard compression.
jdapimin.pas    Application program interface: core routines for decompression.
jdapistd.pas    Application program interface: standard decompression.
jcomapi.pas     Application program interface routines common to compression
                and decompression.
jcparam.pas     Compression parameter setting helper routines.
jctrans.pas     API and library routines for transcoding compression.
jdtrans.pas     API and library routines for transcoding decompression.

Compression side of the library:

jcinit.pas      Initialization: determines which other modules to use.
jcmaster.pas    Master control: setup and inter-pass sequencing logic.
jcmainct.pas    Main buffer controller (preprocessor => JPEG compressor).
jcprepct.pas    Preprocessor buffer controller.
jccoefct.pas    Buffer controller for DCT coefficient buffer.
jccolor.pas     Color space conversion.
jcsample.pas    Downsampling.
jcdctmgr.pas    DCT manager (DCT implementation selection & control).
jfdctint.pas    Forward DCT using slow-but-accurate integer method.
jfdctfst.pas    Forward DCT using faster, less accurate integer method.
jfdctflt.pas    Forward DCT using floating-point arithmetic.
jchuff.pas      Huffman entropy coding for sequential JPEG.
jcphuff.pas     Huffman entropy coding for progressive JPEG.
jcmarker.pas    JPEG marker writing.
jdatadst.pas    Data destination manager for stdio output.

Decompression side of the library:

jdmaster.pas    Master control: determines which other modules to use.
jdinput.pas     Input controller: controls input processing modules.
jdmainct.pas    Main buffer controller (JPEG decompressor => postprocessor).
jdcoefct.pas    Buffer controller for DCT coefficient buffer.
jdpostct.pas    Postprocessor buffer controller.
jdmarker.pas    JPEG marker reading.
jdhuff.pas      Huffman entropy decoding for sequential JPEG.
jdphuff.pas     Huffman entropy decoding for progressive JPEG.
jddctmgr.pas    IDCT manager (IDCT implementation selection & control).
jidctint.pas    Inverse DCT using slow-but-accurate integer method.
jidctasm.pas    BASM specific version of jidctint.pas for 32bit Delphi.
jidctfst.pas    Inverse DCT using faster, less accurate integer method.
jidctflt.pas    Inverse DCT using floating-point arithmetic.
jidctred.pas    Inverse DCTs with reduced-size outputs.
jidct2d.pas     How to for a direct 2D Inverse DCT - not used
jdsample.pas    Upsampling.
jdcolor.pas     Color space conversion.
jdmerge.pas     Merged upsampling/color conversion (faster, lower quality).
jquant1.pas     One-pass color quantization using a fixed-spacing colormap.
jquant2.pas     Two-pass color quantization using a custom-generated colormap.
		Also handles one-pass quantization to an externally given map.
jdatasrc.pas    Data source manager for stdio input.

Support files for both compression and decompression:

jerror.pas      Standard error handling routines (application replaceable).
jmemmgr.pas     System-independent (more or less) memory management code.
jutils.pas      Miscellaneous utility routines.

jmemmgr.pas relies on a system-dependent memory management module.  The
PASJPEG distribution includes the following implementations of the system-
dependent module:

jmemnobs.pas    "No backing store": assumes adequate virtual memory exists.
jmemdos.pas     Custom implementation for MS-DOS (16-bit environment only):
                can use extended and expanded memory as well as temporary
                files.
jmemsys.pas     A skeleton with all the declaration you need to create a
                working system-dependent JPEG memory manager on unusual
                systems.

Exactly one of the system-dependent units should be used in jmemmgr.pas.

jmemdosa.pas    BASM 80x86 assembly code support for jmemdos.pas; used only
                in MS-DOS-specific configurations of the JPEG library.


Applications using the library should use jmorecfg, jerror, jpeglib, and
include jconfig.inc.

CJPEG/DJPEG/JPEGTRAN

Pascal source code files:

cderror.pas     Additional error and trace message codes for cjpeg/djpeg.
                Not used, Those errors have been added to jdeferr.
cjpeg.pas       Main program for cjpeg.
djpeg.pas       Main program for djpeg.
jpegtran.pas    Main program for jpegtran.
cdjpeg.pas      Utility routines used by all three programs.
rdcolmap.pas    Code to read a colormap file for djpeg's "-map" switch.
rdswitch.pas    Code to process some of cjpeg's more complex switches.
                Also used by jpegtran.
transupp.pas    Support code for jpegtran: lossless image manipulations.

fcache.pas
rdswitch.pas    Code to process some of cjpeg's more complex switches.
                Also used by jpegtran.

Image file writer modules for djpeg:

wrbmp.pas       BMP file output.
wrppm.pas	PPM/PGM file output.
wrtarga.pas     Targa file output.

Image file reader modules for cjpeg:

rdbmp.pas       BMP file input.
rdppm.pas       PPM/PGM file input.
rdtarga.pas     Targa file input. - NOT READY YET

This program does not depend on the JPEG library

rdjpgcom.pas	Stand-alone rdjpgcom application.


Translation
===========

TP is unit-centric, exported type definitions and routines are declared
in the "interface" part of the unit, "make" files are not needed.
Macros are not supported, they were either copied as needed or translated
to Pascal routines (procedure). The procedures will be replaced by code in
later releases.
Conditional defines that indicate whether to include various optional
functions are defined in the file JCONFIG.INC. This file is included first
in all source files.

The base type definitions are in the unit JMORECFG.PAS. The error handling
macros have been converted to procedures in JERROR.PAS. The error codes are
in JDEFERR.PAS. jpegint.h and jpeglib.h were merged into one large unit
JPEGLIB.PAS containing type definitions with global scope.

The translation of the header file is the most sophisticated work, a good
understanding of the syntax is required. Once the header files are done,
the translation turns into a lot of editing work. Each C source file was
converted to a unit by editing the syntax (separate variable definition
and usage, define labels, group variable definitions, expanding macros, etc).

The IJG source labels routines GLOBAL, METHODDEF and LOCAL. All globals
routines are in the interface section of the units. The "far" directive is
used for methods (METHODDEF).

Some C  ->  Pascal  examples.

* "{"  -> "begin"    "->"  ->  "^."        " = "  -> " := "  "<<"  -> " shl "
  "}"  -> "end;"     "!="  ->  "<>"        " == " -> " = "   ">>"  -> " shr "
  "/*" -> "{"      routine ->  function    "0x"   -> "$"
  "*/" -> "}"      (void)      procedure   "NULL" -> "NIL"

* structs are records, Unions are variable records, pointers are always far,
  the operators && and || (and/or) have not the same priority in both
  languages, so parenthesis are important. The Pascal "case" doesn't have the
  falltrough option of the C "switch" statement, my work around is to split
  one "switch" statement into many case statements.
* The pointer type in C is not readily interchangeable. It is used to address
  an array (Pascal pointer to an array) or in pointer arithmetic a pointer to
  a single element. I've used the Inc() statement with type casting to
  translate pointer arithmetic most of the time.

  C example:
    typedef JSAMPLE* JSAMPROW;  /* ptr to one image row of pixel samples. */

  Pascal
  type
    JSAMPLE_PTR = ^JSAMPLE;     { ptr to a single pixel sample. }
    jTSample = 0..(MaxInt div SIZEOF(JSAMPLE))-1;
    JSAMPLE_ARRAY = Array[jTSample] of JSAMPLE;  {far}
    JSAMPROW = ^JSAMPLE_ARRAY;  { ptr to one image row of pixel samples. }

  The following code

    JSAMPROW buffer0, buffer1;  /* ptr to a JSAMPLE buffer. */

    ...

    buffer1 = buffer0 + i;

  can be translated to

  var
    buffer0, buffer1 : JSAMPROW;

  ...

    buffer1 := buffer0;
    Inc(JSAMPLE_PTR(buffer1), i);

  or

    buffer1 := JSAMPROW(@ buffer0^[i]);

  Declaring the variables as JSAMPLE_PTR may reduce type casting in some
  places. I use help pointers to handle negative array offsets.

While translating the type of function parameter from C to Pascal, one can
often use "var", "const", or "array of" parameters instead of pointers.

While translating for(;;)-loops with more than one induction variable to
Pascal "for to/downto do"-loops, the extra induction variables have to be
manually updated at the end of the loop and before "continue"-statements.


Legal issues
============

Copyright (C) 1996,1998 by Jacques Nomssi Nzali

  This software is provided 'as-is', without any express or implied
  warranty.  In no event will the author be held liable for any damages
  arising from the use of this software.

  Permission is granted to anyone to use this software for any purpose,
  including commercial applications, and to alter it and redistribute it
  freely, subject to the following restrictions:

  1. The origin of this software must not be misrepresented; you must not
     claim that you wrote the original software. If you use this software
     in a product, an acknowledgment in the product documentation would be
     appreciated but is not required.
  2. Altered source versions must be plainly marked as such, and must not be
     misrepresented as being the original software.
  3. This notice may not be removed or altered from any source distribution.


Archive Locations:
==================

[1] Thomas G. Lane, JPEG FAQ

      in comp.graphics.misc and related newsgroups

[2] Wallace, Gregory K.: The JPEG Still Picture Compression Standard

      ftp.uu.net, graphics/jpeg/wallace.ps.Z

[3] The Independent JPEG Group C library for JPEG encoding and decoding,
    rev 6b.

      ftp://ftp.uu.net/graphics/jpeg/

      or SimTel in msdos/graphics/

[4] JPEG implementation, written by the PVRG group at Stanford,
      ftp havefun.stanford.edu:/pub/jpeg/JPEGv1.2.tar.Z.

[5] PASJPEG.ZIP at NView ftp site

      ftp://druckfix.physik.tu-chemnitz.de/pub/nv/
      http://www.tu-chemnitz.de/~nomssi/pub/pasjpeg.zip

[6] The PasJPEG home page with links

      http://www.tu-chemnitz.de/~nomssi/pasjpeg.html
_____________________________________________________________________________