src/lib/vampimg/JpegLib/readme.txt

   1 _____________________________________________________________________________
   2
   3 PASJPEG 1.1                                                   May 29th, 1999
   4
   5 Based on the Independent JPEG Group's JPEG software release 6b
   6
   7 Copyright (C) 1996,1998,1999 by NOMSSI NZALI Jacques H. C.
   8 [kn&n DES]         See "Legal issues" for conditions of distribution and use.
   9 _____________________________________________________________________________
  10
  11
  12 Information in this file
  13 ========================
  14
  15   o Introduction
  16   o Notes
  17   o File list
  18   o Translation
  19   o Legal issues
  20   o Archive Locations
  21
  22 Introduction
  23 ============
  24
  25 PASJPEG is a port of the sixth public release of the IJG C source (release
  26 6b of 27-Mar-98) [3], that implements JPEG baseline, extended-sequential, and
  27 progressive compression processes to Turbo Pascal 7.0 for DOS (TP). The code
  28 has been tested under Delphi 3.0, it can be ported to other Pascal
  29 environments, since many compilers try to be compatible to TP.
  30
  31 JPEG (pronounced "jay-peg") is a standardized familly of algorithms for
  32 compression of continous tone still images. Most JPEG processes are lossy,
  33 the output image is not exactly identical to the input image. However, on
  34 typical photographic images, very good compression levels can be obtained
  35 with no visible change, and remarkably high compression levels are possible
  36 if you can tolerate a low-quality image [1],[2]. The Independent JPEG Group
  37 (IJG) has created a free, portable C library for JPEG compression and
  38 decompression of JPEG images.
  39
  40 The IJG documentation (system architecture, using the IJG JPEG library,
  41 usage and file list) is a must read. The files DEMO.PAS, TEST.PAS, CJPEG.PAS,
  42 DJPEG.PAS and EXAMPLE.PAS demonstrate the usage of the JPEG decompression
  43 and compression library. The RDJPGCOM application shows how to parse a JFIF
  44 file.
  45
  46 Notes:
  47 ======
  48
  49 * Please report any errors/problems you may find in code and in the
  50   documentation (e.g. this README.TXT file).
  51
  52 * The sample applications (CJPEG, DJPEG) doesn't support all the options
  53   of the original C code. WRJPGCOM is not ported.
  54
  55 * Environment variable JPEGMEM syntax changed;
  56
  57 * You can modify the jpeg.pas unit from the Delphi 3 distribution to
  58   use PasJPEG.
  59
  60 Change log
  61 ==========
  62
  63 1. bugs fixed:
  64    * in procedure read_gif_map(), unit RDCOLMAP.PAS (used by DJPEG sample
  65      application). Davie Lee Reed <smatters@iquest.net>
  66    * -dct int and -dct fast now bytewise equal to the IJG output.
  67    * -dct float produced large files
  68
  69 2. Support for scripts
  70
  71 3. BASM version of JIDCTINT.PAS for Delphi 2 and 3.
  72
  73 4. images with integral sampling ratios were not decoded correctly.
  74    Create a jpeg file with cjpeg and the option "-sample 4x1" and try to decode
  75    it with any software that uses PasJpeg. Thanks to Jannie Gerber for reporting
  76    this with a fix: In JDSAMPLE.PAS, procedure int_upsample(),
  77
  78     for h := pred(h_expand) downto 0 do
  79     begin
  80       outptr^ := invalue;
  81  +=>  inc(outptr);   { this is the culprit that was left out!!! }
  82       Dec(outcount);
  83     end;
  84
  85 File list
  86 =========
  87
  88 Here is a road map to the files in the PasJPEG distribution.  The
  89 distribution includes the JPEG library proper, plus two application
  90 programs ("cjpeg" and "djpeg") which use the library to convert JPEG
  91 files to and from some other popular image formats.  A third application
  92 "jpegtran" uses the library to do lossless conversion between different
  93 variants of JPEG.  There is also the stand-alone applications "rdjpgcom".
  94
  95 Documentation(see README for a guide to the documentation files):
  96
  97 readme.txt      Introduction, Documentation
  98
  99 Additional files
 100
 101 demo.pas        Demo program, uses example.pas
 102 example.pas     Sample code for calling JPEG library.
 103 test.pas        Sample application code for demo.pas
 104
 105 Configuration/installation files and programs (see install.doc for more info):
 106
 107 jconfig.inc     Configuration declarations.
 108
 109 *.ijg           script files
 110
 111 Pascal source code files:
 112
 113 jinclude.pas    Central include file used by all IJG .c files to reference
 114     system include files.
 115 jpeglib.pas     JPEG library's internal data structures, exported data
 116                 and function declarations.
 117 jmorecfg.pas    Additional configuration declarations; need not be changed
 118                 for a standard installation.
 119 jdeferr.pas     defines the error and message text.
 120 jerror.pas      Declares JPEG library's error and trace message codes.
 121 jinclude.pas    the place to specify system depedent input/output code.
 122 jdct.pas        Private declarations for forward & reverse DCT subsystems.
 123
 124 These files contain most of the functions intended to be called directly by
 125 an application program:
 126
 127 jcapimin.pas    Application program interface: core routines for compression.
 128 jcapistd.pas    Application program interface: standard compression.
 129 jdapimin.pas    Application program interface: core routines for decompression.
 130 jdapistd.pas    Application program interface: standard decompression.
 131 jcomapi.pas     Application program interface routines common to compression
 132                 and decompression.
 133 jcparam.pas     Compression parameter setting helper routines.
 134 jctrans.pas     API and library routines for transcoding compression.
 135 jdtrans.pas     API and library routines for transcoding decompression.
 136
 137 Compression side of the library:
 138
 139 jcinit.pas      Initialization: determines which other modules to use.
 140 jcmaster.pas    Master control: setup and inter-pass sequencing logic.
 141 jcmainct.pas    Main buffer controller (preprocessor => JPEG compressor).
 142 jcprepct.pas    Preprocessor buffer controller.
 143 jccoefct.pas    Buffer controller for DCT coefficient buffer.
 144 jccolor.pas     Color space conversion.
 145 jcsample.pas    Downsampling.
 146 jcdctmgr.pas    DCT manager (DCT implementation selection & control).
 147 jfdctint.pas    Forward DCT using slow-but-accurate integer method.
 148 jfdctfst.pas    Forward DCT using faster, less accurate integer method.
 149 jfdctflt.pas    Forward DCT using floating-point arithmetic.
 150 jchuff.pas      Huffman entropy coding for sequential JPEG.
 151 jcphuff.pas     Huffman entropy coding for progressive JPEG.
 152 jcmarker.pas    JPEG marker writing.
 153 jdatadst.pas    Data destination manager for stdio output.
 154
 155 Decompression side of the library:
 156
 157 jdmaster.pas    Master control: determines which other modules to use.
 158 jdinput.pas     Input controller: controls input processing modules.
 159 jdmainct.pas    Main buffer controller (JPEG decompressor => postprocessor).
 160 jdcoefct.pas    Buffer controller for DCT coefficient buffer.
 161 jdpostct.pas    Postprocessor buffer controller.
 162 jdmarker.pas    JPEG marker reading.
 163 jdhuff.pas      Huffman entropy decoding for sequential JPEG.
 164 jdphuff.pas     Huffman entropy decoding for progressive JPEG.
 165 jddctmgr.pas    IDCT manager (IDCT implementation selection & control).
 166 jidctint.pas    Inverse DCT using slow-but-accurate integer method.
 167 jidctasm.pas    BASM specific version of jidctint.pas for 32bit Delphi.
 168 jidctfst.pas    Inverse DCT using faster, less accurate integer method.
 169 jidctflt.pas    Inverse DCT using floating-point arithmetic.
 170 jidctred.pas    Inverse DCTs with reduced-size outputs.
 171 jidct2d.pas     How to for a direct 2D Inverse DCT - not used
 172 jdsample.pas    Upsampling.
 173 jdcolor.pas     Color space conversion.
 174 jdmerge.pas     Merged upsampling/color conversion (faster, lower quality).
 175 jquant1.pas     One-pass color quantization using a fixed-spacing colormap.
 176 jquant2.pas     Two-pass color quantization using a custom-generated colormap.
 177     Also handles one-pass quantization to an externally given map.
 178 jdatasrc.pas    Data source manager for stdio input.
 179
 180 Support files for both compression and decompression:
 181
 182 jerror.pas      Standard error handling routines (application replaceable).
 183 jmemmgr.pas     System-independent (more or less) memory management code.
 184 jutils.pas      Miscellaneous utility routines.
 185
 186 jmemmgr.pas relies on a system-dependent memory management module.  The
 187 PASJPEG distribution includes the following implementations of the system-
 188 dependent module:
 189
 190 jmemnobs.pas    "No backing store": assumes adequate virtual memory exists.
 191 jmemdos.pas     Custom implementation for MS-DOS (16-bit environment only):
 192                 can use extended and expanded memory as well as temporary
 193                 files.
 194 jmemsys.pas     A skeleton with all the declaration you need to create a
 195                 working system-dependent JPEG memory manager on unusual
 196                 systems.
 197
 198 Exactly one of the system-dependent units should be used in jmemmgr.pas.
 199
 200 jmemdosa.pas    BASM 80x86 assembly code support for jmemdos.pas; used only
 201                 in MS-DOS-specific configurations of the JPEG library.
 202
 203
 204 Applications using the library should use jmorecfg, jerror, jpeglib, and
 205 include jconfig.inc.
 206
 207 CJPEG/DJPEG/JPEGTRAN
 208
 209 Pascal source code files:
 210
 211 cderror.pas     Additional error and trace message codes for cjpeg/djpeg.
 212                 Not used, Those errors have been added to jdeferr.
 213 cjpeg.pas       Main program for cjpeg.
 214 djpeg.pas       Main program for djpeg.
 215 jpegtran.pas    Main program for jpegtran.
 216 cdjpeg.pas      Utility routines used by all three programs.
 217 rdcolmap.pas    Code to read a colormap file for djpeg's "-map" switch.
 218 rdswitch.pas    Code to process some of cjpeg's more complex switches.
 219                 Also used by jpegtran.
 220 transupp.pas    Support code for jpegtran: lossless image manipulations.
 221
 222 fcache.pas
 223 rdswitch.pas    Code to process some of cjpeg's more complex switches.
 224                 Also used by jpegtran.
 225
 226 Image file writer modules for djpeg:
 227
 228 wrbmp.pas       BMP file output.
 229 wrppm.pas PPM/PGM file output.
 230 wrtarga.pas     Targa file output.
 231
 232 Image file reader modules for cjpeg:
 233
 234 rdbmp.pas       BMP file input.
 235 rdppm.pas       PPM/PGM file input.
 236 rdtarga.pas     Targa file input. - NOT READY YET
 237
 238 This program does not depend on the JPEG library
 239
 240 rdjpgcom.pas  Stand-alone rdjpgcom application.
 241
 242
 243 Translation
 244 ===========
 245
 246 TP is unit-centric, exported type definitions and routines are declared
 247 in the "interface" part of the unit, "make" files are not needed.
 248 Macros are not supported, they were either copied as needed or translated
 249 to Pascal routines (procedure). The procedures will be replaced by code in
 250 later releases.
 251 Conditional defines that indicate whether to include various optional
 252 functions are defined in the file JCONFIG.INC. This file is included first
 253 in all source files.
 254
 255 The base type definitions are in the unit JMORECFG.PAS. The error handling
 256 macros have been converted to procedures in JERROR.PAS. The error codes are
 257 in JDEFERR.PAS. jpegint.h and jpeglib.h were merged into one large unit
 258 JPEGLIB.PAS containing type definitions with global scope.
 259
 260 The translation of the header file is the most sophisticated work, a good
 261 understanding of the syntax is required. Once the header files are done,
 262 the translation turns into a lot of editing work. Each C source file was
 263 converted to a unit by editing the syntax (separate variable definition
 264 and usage, define labels, group variable definitions, expanding macros, etc).
 265
 266 The IJG source labels routines GLOBAL, METHODDEF and LOCAL. All globals
 267 routines are in the interface section of the units. The "far" directive is
 268 used for methods (METHODDEF).
 269
 270 Some C  ->  Pascal  examples.
 271
 272 * "{"  -> "begin"    "->"  ->  "^."        " = "  -> " := "  "<<"  -> " shl "
 273   "}"  -> "end;"     "!="  ->  "<>"        " == " -> " = "   ">>"  -> " shr "
 274   "/*" -> "{"      routine ->  function    "0x"   -> "$"
 275   "*/" -> "}"      (void)      procedure   "NULL" -> "NIL"
 276
 277 * structs are records, Unions are variable records, pointers are always far,
 278   the operators && and || (and/or) have not the same priority in both
 279   languages, so parenthesis are important. The Pascal "case" doesn't have the
 280   falltrough option of the C "switch" statement, my work around is to split
 281   one "switch" statement into many case statements.
 282 * The pointer type in C is not readily interchangeable. It is used to address
 283   an array (Pascal pointer to an array) or in pointer arithmetic a pointer to
 284   a single element. I've used the Inc() statement with type casting to
 285   translate pointer arithmetic most of the time.
 286
 287   C example:
 288     typedef JSAMPLE* JSAMPROW;  /* ptr to one image row of pixel samples. */
 289
 290   Pascal
 291   type
 292     JSAMPLE_PTR = ^JSAMPLE;     { ptr to a single pixel sample. }
 293     jTSample = 0..(MaxInt div SIZEOF(JSAMPLE))-1;
 294     JSAMPLE_ARRAY = Array[jTSample] of JSAMPLE;  {far}
 295     JSAMPROW = ^JSAMPLE_ARRAY;  { ptr to one image row of pixel samples. }
 296
 297   The following code
 298
 299     JSAMPROW buffer0, buffer1;  /* ptr to a JSAMPLE buffer. */
 300
 301     ...
 302
 303     buffer1 = buffer0 + i;
 304
 305   can be translated to
 306
 307   var
 308     buffer0, buffer1 : JSAMPROW;
 309
 310   ...
 311
 312     buffer1 := buffer0;
 313     Inc(JSAMPLE_PTR(buffer1), i);
 314
 315   or
 316
 317     buffer1 := JSAMPROW(@ buffer0^[i]);
 318
 319   Declaring the variables as JSAMPLE_PTR may reduce type casting in some
 320   places. I use help pointers to handle negative array offsets.
 321
 322 While translating the type of function parameter from C to Pascal, one can
 323 often use "var", "const", or "array of" parameters instead of pointers.
 324
 325 While translating for(;;)-loops with more than one induction variable to
 326 Pascal "for to/downto do"-loops, the extra induction variables have to be
 327 manually updated at the end of the loop and before "continue"-statements.
 328
 329
 330 Legal issues
 331 ============
 332
 333 Copyright (C) 1996,1998 by Jacques Nomssi Nzali
 334
 335   This software is provided 'as-is', without any express or implied
 336   warranty.  In no event will the author be held liable for any damages
 337   arising from the use of this software.
 338
 339   Permission is granted to anyone to use this software for any purpose,
 340   including commercial applications, and to alter it and redistribute it
 341   freely, subject to the following restrictions:
 342
 343   1. The origin of this software must not be misrepresented; you must not
 344      claim that you wrote the original software. If you use this software
 345      in a product, an acknowledgment in the product documentation would be
 346      appreciated but is not required.
 347   2. Altered source versions must be plainly marked as such, and must not be
 348      misrepresented as being the original software.
 349   3. This notice may not be removed or altered from any source distribution.
 350
 351
 352 Archive Locations:
 353 ==================
 354
 355 [1] Thomas G. Lane, JPEG FAQ
 356
 357       in comp.graphics.misc and related newsgroups
 358
 359 [2] Wallace, Gregory K.: The JPEG Still Picture Compression Standard
 360
 361       ftp.uu.net, graphics/jpeg/wallace.ps.Z
 362
 363 [3] The Independent JPEG Group C library for JPEG encoding and decoding,
 364     rev 6b.
 365
 366       ftp://ftp.uu.net/graphics/jpeg/
 367
 368       or SimTel in msdos/graphics/
 369
 370 [4] JPEG implementation, written by the PVRG group at Stanford,
 371       ftp havefun.stanford.edu:/pub/jpeg/JPEGv1.2.tar.Z.
 372
 373 [5] PASJPEG.ZIP at NView ftp site
 374
 375       ftp://druckfix.physik.tu-chemnitz.de/pub/nv/
 376       http://www.tu-chemnitz.de/~nomssi/pub/pasjpeg.zip
 377
 378 [6] The PasJPEG home page with links
 379
 380       http://www.tu-chemnitz.de/~nomssi/pasjpeg.html
 381 _____________________________________________________________________________