home *** CD-ROM | disk | FTP | other *** search
/ Source Code 1994 March / Source_Code_CD-ROM_Walnut_Creek_March_1994.iso / compsrcs / misc / volume29 / jpeg / part01 < prev    next >
Encoding:
Text File  |  1992-03-23  |  53.7 KB  |  1,078 lines

  1. Newsgroups: comp.sources.misc
  2. From: jpeg-info@uunet.uu.net (Independent JPEG Group)
  3. Subject:  v29i001:  jpeg - JPEG image compression, Part01/18
  4. Message-ID: <csm-v29i001=jpeg.000528@sparky.IMD.Sterling.COM>
  5. X-Md4-Signature: d2cb37aa88f4056bc732781ec08a6f51
  6. Date: Tue, 24 Mar 1992 06:06:13 GMT
  7. Approved: kent@sparky.imd.sterling.com
  8.  
  9. Submitted-by: jpeg-info@uunet.uu.net (Independent JPEG Group)
  10. Posting-number: Volume 29, Issue 1
  11. Archive-name: jpeg/part01
  12. Environment: UNIX, VMS, MS-DOS, Mac, Amiga, Cray
  13.  
  14. This package contains C software to implement JPEG image compression and
  15. decompression.  JPEG is a standardized compression method for full-color
  16. and gray-scale images.  JPEG is intended for "real-world" scenes; cartoons
  17. and other non-realistic images are not its strong suit.  JPEG is lossy,
  18. meaning that the output image is not identical to the input image.
  19. The user can trade off output image quality against compressed file size by
  20. adjusting a compression parameter.
  21.  
  22. The distributed programs provide conversion between JPEG "JFIF" format and
  23. image files in PBMPLUS PPM/PGM, Utah RLE, Truevision Targa, and GIF file
  24. formats.  The core compression and decompression modules can easily be
  25. reused in other programs, such as image viewers.  The package is highly
  26. portable C code; we have tested it on many machines ranging from PCs to Crays.
  27.  
  28. We are releasing this software for both noncommercial and commercial use.
  29. Companies are welcome to use it as the basis for JPEG-related products.
  30. We do not ask a royalty, although we do ask for an acknowledgement in
  31. product literature (see the README file in the distribution for details).
  32. We hope to make this software industrial-quality --- although, as with
  33. anything that's free, we offer no warranty and accept no liability.
  34.  
  35. Tom Lane
  36. --------------
  37. #! /bin/sh
  38. # This is a shell archive.  Remove anything before this line, then feed it
  39. # into a shell via "sh file" or similar.  To overwrite existing files,
  40. # type "sh file -c".
  41. # The tool that generated this appeared in the comp.sources.unix newsgroup;
  42. # send mail to comp-sources-unix@uunet.uu.net if you want that tool.
  43. # Contents:  README arch.a makefile.vms
  44. # Wrapped by kent@sparky on Mon Mar 23 16:02:39 1992
  45. PATH=/bin:/usr/bin:/usr/ucb ; export PATH
  46. echo If this archive is complete, you will see the following message:
  47. echo '          "shar: End of archive 1 (of 18)."'
  48. if test -f 'README' -a "${1}" != "-c" ; then 
  49.   echo shar: Will not clobber existing file \"'README'\"
  50. else
  51.   echo shar: Extracting \"'README'\" \(18730 characters\)
  52.   sed "s/^X//" >'README' <<'END_OF_FILE'
  53. XThe Independent JPEG Group's JPEG software
  54. X==========================================
  55. X
  56. XREADME for release 3 of  17-Mar-92
  57. X==================================
  58. X
  59. XThis distribution contains the third official release of the Independent JPEG
  60. XGroup's free JPEG software.  You are welcome to redistribute this software and
  61. Xto use it for any purpose, subject to the conditions under LEGAL ISSUES, below.
  62. X
  63. XFor installation instructions, see file SETUP; for usage instructions, see
  64. Xfile USAGE (or the cjpeg.1 and djpeg.1 manual pages).
  65. X
  66. XThis software is still undergoing revision.  Updated versions may be obtained
  67. Xby FTP or UUCP to UUNET and other archive sites; see ARCHIVE LOCATIONS below
  68. Xfor details.
  69. X
  70. XIf you intend to become a serious user of this software, please contact
  71. Xjpeg-info@uunet.uu.net to be added to our electronic mailing list.  Then
  72. Xyou'll be notified of updates and have a chance to participate in discussions,
  73. Xetc.
  74. X
  75. XThis software is the work of Tom Lane, Philip Gladstone, Luis Ortiz,
  76. XLee Crocker, Ge' Weijers, and other members of the Independent JPEG Group.
  77. X
  78. X
  79. XDISCLAIMER
  80. X==========
  81. X
  82. XTHIS SOFTWARE IS NOT COMPLETE NOR FULLY DEBUGGED.  It is not guaranteed to be
  83. Xuseful for anything, nor to be compatible with subsequent releases, nor to be
  84. Xan accurate implementation of the JPEG standard.  (See LEGAL ISSUES for even
  85. Xmore disclaimers.)
  86. X
  87. XPlease report any problems with this software to jpeg-info@uunet.uu.net.
  88. X
  89. X
  90. XWHAT'S HERE
  91. X===========
  92. X
  93. XThis distribution contains C software to implement JPEG image compression and
  94. Xdecompression.  JPEG (pronounced "jay-peg") is a standardized compression
  95. Xmethod for full-color and gray-scale images.  JPEG is intended for
  96. X"real-world" scenes; cartoons and other non-realistic images are not its
  97. Xstrong suit.  JPEG is lossy, meaning that the output image is not necessarily
  98. Xidentical to the input image.  Hence you should not use JPEG if you have to
  99. Xhave identical output bits.  However, on typical images of real-world scenes,
  100. Xvery good compression levels can be obtained with no visible change, and
  101. Xamazingly high compression levels can be obtained if you can tolerate a
  102. Xlow-quality image.  For more details, see the references, or just experiment
  103. Xwith various compression settings.
  104. X
  105. XThe software implements JPEG baseline and extended-sequential compression
  106. Xprocesses.  Provision is made for supporting all variants of these processes,
  107. Xalthough some uncommon parameter settings aren't implemented yet.  For legal
  108. Xreasons, we are not distributing code for the arithmetic-coding process; see
  109. XLEGAL ISSUES.  At present we have made no provision for supporting the
  110. Xprogressive, hierarchical, or lossless processes defined in the standard.
  111. X
  112. XThe present software is not far beyond the prototype stage.  It does not
  113. Xsupport all possible variants of the JPEG standard, and some functions have
  114. Xrather slow and/or crude implementations.  However, it is useful already.
  115. X
  116. XThe emphasis in designing this software has been on achieving portability and
  117. Xflexibility, while also making it fast enough to be useful.  We have not yet
  118. Xundertaken serious performance measurement or tuning; we intend to do so in
  119. Xthe future.
  120. X
  121. X
  122. XThis software can be used on several levels:
  123. X
  124. X* As canned software for JPEG compression and decompression.  Just edit the
  125. X  Makefile and configuration files as needed (see file SETUP), compile and go.
  126. X  Members of the Independent JPEG Group will improve the out-of-the-box
  127. X  functionality and speed as time goes on.
  128. X
  129. X* As the basis for other JPEG programs.  For example, you could incorporate
  130. X  the decompressor into a general image viewing package by replacing the
  131. X  output module with write-to-screen functions.  For an implementation on
  132. X  specific hardware, you might want to replace some of the inner loops with
  133. X  assembly code.  For a non-command-line-driven system, you might want a
  134. X  different user interface.  (Members of the group will be producing Macintosh
  135. X  and Amiga versions with more appropriate user interfaces, for example.)
  136. X
  137. X* As a toolkit for experimentation with JPEG and JPEG-like algorithms.  Most
  138. X  of the individual decisions you might want to mess with are packaged up into
  139. X  separate modules.  For example, the details of color-space conversion and
  140. X  subsampling techniques are each localized in one compressor and one
  141. X  decompressor module.  You'd probably also want to extend the user interface
  142. X  to give you more detailed control over the JPEG compression parameters.
  143. X
  144. XIn particular, we welcome the use of this software as a component of commercial
  145. Xproducts; no royalty is required.
  146. X
  147. X
  148. XARCHIVE LOCATIONS
  149. X=================
  150. X
  151. XThe "official" archive site for this software is ftp.uu.net (Internet
  152. Xaddress 137.39.1.9 or 192.48.96.9).  The most recent released version can
  153. Xalways be found there in directory graphics/jpeg.  This particular version
  154. Xwill be archived as jpegsrc.v3.tar.Z.  If you are on the Internet, you can
  155. Xretrieve files from UUNET by anonymous FTP.  If you don't have FTP access,
  156. XUUNET's archives are also available via UUCP; contact postmaster@uunet.uu.net
  157. Xfor information on retrieving files that way.
  158. X
  159. XVarious other Internet sites maintain copies of the UUNET file, which may or
  160. Xmay not be up-to-date.  In Europe, try nic.funet.fi (128.214.6.100; look in
  161. Xdirectory pub/graphics/programs/jpeg).
  162. X
  163. XYou can also obtain this software from CompuServe, in the GRAPHSUPPORT forum
  164. X(GO PICS), library 10; this version will be file jpsrc3.zip.
  165. X
  166. XIf you are not reasonably handy at configuring and installing portable C
  167. Xprograms, you may have some difficulty installing this package.  You may
  168. Xprefer to obtain a pre-built executable version.  A collection of pre-built
  169. Xexecutables for various machines is currently available for anonymous FTP at
  170. Xprocyon.cis.ksu.edu (129.130.10.80 --- this number is due to change soon);
  171. Xlook under /pub/JPEG.  The administrators of this system ask that FTP traffic
  172. Xbe limited to non-prime hours.  For more information on this archive, please
  173. Xcontact Steve Davis (strat@cis.ksu.edu).  This collection is not maintained by
  174. Xthe Independent JPEG Group, and programs in it may not be the latest version.
  175. X
  176. X
  177. XSUPPORTING SOFTWARE
  178. X===================
  179. X
  180. XYou will probably want Jef Poskanzer's PBMPLUS image software, which provides
  181. Xmany useful operations on PPM-format image files.  In particular, it can
  182. Xconvert PPM images to and from a wide range of other formats.  You can FTP
  183. Xthis free software from export.lcs.mit.edu (contrib/pbmplus*.tar.Z) or
  184. Xftp.ee.lbl.gov (pbmplus*.tar.Z).  Unfortunately PBMPLUS is not nearly as
  185. Xportable as the JPEG software is; you are likely to have difficulty making it
  186. Xwork on any non-Unix machine.
  187. X
  188. XIf you are using X Windows you might want to use the xv or xloadimage viewers
  189. Xto save yourself the trouble of converting PPM to some other format.  Both of
  190. Xthese can be found in the contrib directory at export.lcs.mit.edu.  Actually,
  191. Xxv version 2.00 and up incorporates our software and thus can read and write
  192. XJPEG files directly.  (NOTE: since xv internally reduces all images to 8
  193. Xbits/pixel, a JPEG file written by xv will not be very high quality; you may
  194. Xalso prefer xloadimage for viewing if you have a 24-bit display.  Caveat user.)
  195. X
  196. XFor DOS machines, Lee Crocker's free Piclab program is a useful companion to
  197. Xthe JPEG software.  The latest version, currently 1.91, is available by FTP
  198. Xfrom SIMTEL20 and its various mirror sites, file <msdos.graphics>piclb191.zip.
  199. XCompuServe also has it, in the same library as the JPEG software.
  200. X
  201. X
  202. XSOFTWARE THAT'S NO HELP AT ALL
  203. X==============================
  204. X
  205. XHandmade Software's shareware PC program GIF2JPG produces files that are
  206. Xtotally incompatible with our programs.  They use a proprietary format that is
  207. Xan amalgam of GIF and JPEG representations.  However, you can force GIF2JPG
  208. Xto produce compatible files with its -j switch, and their decompression
  209. Xprogram JPG2GIF can read our files (at least ones produced with our default
  210. Xoption settings).
  211. X
  212. XUnfortunately, many commercial JPEG implementations are also incompatible as
  213. Xof this writing, especially programs released before summer 1991.  The root of
  214. Xthe problem is that the ISO JPEG committee failed to specify a concrete file
  215. Xformat.  Some vendors "filled in the blanks" on their own, creating
  216. Xproprietary formats that no one else could read.  (For example, none of the
  217. Xearly commercial JPEG implementations for the Macintosh were able to exchange
  218. Xcompressed files.)
  219. X
  220. XThe file format we have adopted is called JFIF (see REFERENCES).  This format
  221. Xhas been agreed to by a number of major commercial JPEG vendors, and we expect
  222. Xthat it will become the de facto standard.  JFIF is a minimal representation;
  223. Xwork is also going forward to incorporate JPEG compression into the TIFF
  224. Xstandard, for use in "high end" applications that need to record a lot of
  225. Xadditional data about an image.  We intend to support JPEG-in-TIFF in the
  226. Xfuture.  We hope that these two formats will be sufficient and that other,
  227. Xincompatible JPEG file formats will not proliferate.
  228. X
  229. XIndeed, part of the reason for developing and releasing this free software is
  230. Xto help force rapid convergence to de facto standards for JPEG file formats.
  231. XSUPPORT STANDARD, NON-PROPRIETARY FORMATS: demand JFIF or JPEG-in-TIFF!
  232. X
  233. X
  234. XUSING JPEG AS A SUBROUTINE IN A LARGER PROGRAM
  235. X==============================================
  236. X
  237. XYou can readily incorporate the JPEG compression and decompression routines in
  238. Xa larger program.  The file example.c provides a skeleton of the interface
  239. Xroutines you'll need for this purpose.  Essentially, you replace jcmain.c (for
  240. Xcompression) and/or jdmain.c (for decompression) with your own code.  Note
  241. Xthat the fewer JPEG options you allow the user to twiddle, the less code you
  242. Xneed; all the default options are set up automatically.  (Alternately, if you
  243. Xknow a lot about JPEG or have a special application, you may want to twiddle
  244. Xthe default options even more extensively than jcmain/jdmain do.)
  245. X
  246. XMost likely, you will want the uncompressed image to come from memory (for
  247. Xcompression) or go to memory or the screen (for decompression).  For this
  248. Xpurpose you must provide image reading or writing routines that match the
  249. Xinterface used by the image file I/O modules (jrdXXX or jwrXXX); again,
  250. Xexample.c shows a skeleton of what is required.
  251. X
  252. XBy default, any error detected inside the JPEG routines will cause a message
  253. Xto be printed on stderr, followed by exit().  You can override this behavior
  254. Xby supplying your own message-printing and/or error-exit routines; again,
  255. Xexample.c shows how.
  256. X
  257. XMechanics: we recommend you create libjpeg.a as shown in the Makefile, then
  258. Xlink that with your surrounding program.  (If your linker is at all
  259. Xreasonable, only the code you actually need will get loaded.)  Include the
  260. Xfiles jconfig.h and jpegdata.h in C files that need to call the JPEG routines.
  261. X
  262. XCAUTION: some people have tried to compile JPEG and their surrounding code
  263. Xwith different compilers, e.g., cc for JPEG and c++ or gcc for the rest.  This
  264. Xis a Real Bad Move and you will deserve what happens to you if you try it.
  265. X(Hint: the parameter structures can get laid out differently with no warning.)
  266. X
  267. XRead our "architecture" file for more info.  If it seems to you that the
  268. Xsoftware structure doesn't accommodate what you want to do, please contact
  269. Xthe authors.
  270. X
  271. XBeginning with version 3, we will endeavor to hold the interface described by
  272. Xexample.c constant, so that you can plug in updated versions of the JPEG code
  273. Xjust by recompiling.  However, we can't guarantee this, especially if you
  274. Xchoose to twiddle any JPEG options not listed in example.c.  Check the
  275. XCHANGELOG when installing any new version, and compare example.c against the
  276. Xprior version.  Recompile your calling software (don't just relink), as we may
  277. Xadd or subtract fields in the parameter structures.
  278. X
  279. X
  280. XREFERENCES
  281. X==========
  282. X
  283. XThe best and most readily available introduction to the JPEG compression
  284. Xalgorithm is Wallace's article in the April '91 CACM:
  285. X    Wallace, Gregory K.  "The JPEG Still Picture Compression Standard",
  286. X    Communications of the ACM, April 1991 (vol. 34 no. 4), pp. 30-44.
  287. X(Adjacent articles in that issue discuss MPEG motion picture compression,
  288. Xapplications of JPEG, and related topics.)  We highly recommend reading that
  289. Xarticle before trying to understand the innards of any JPEG software.
  290. XIf you don't have the CACM issue handy, a PostScript file containing a revised
  291. Xversion of the article is available at ftp.uu.net, graphics/jpeg/wallace.ps.Z.
  292. XThe file (actually a preprint for an article to appear in IEEE Trans. Consumer
  293. XElectronics) omits the sample images that appeared in CACM, but it includes
  294. Xcorrections and some added material.  Note: the Wallace article is copyright
  295. XACM and IEEE, and it may not be used for commercial purposes.
  296. X
  297. XFor more detail about the JPEG standard you pretty much have to go to the
  298. Xdraft standard (which is not nearly as intelligible as Wallace's article).
  299. XThe standard is not now available electronically; you must order a paper copy
  300. Xthrough ISO.  In the US, copies may be ordered from ANSI Sales at (212)
  301. X642-4900.  The standard is divided into two parts: Part 1 is the actual
  302. Xspecification, and Part 2 covers compliance testing methods.  The current
  303. X"committee draft" version of Part 1 is titled "Digital Compression and Coding
  304. Xof Continuous-tone Still Images, Part 1: Requirements and guidelines" and has
  305. Xdocument number ISO/IEC CD 10918-1.  (The alternate number SC2 N2215 should
  306. Xalso be mentioned when ordering.)  This draft is expected to be superseded by
  307. Xthe Draft International Standard version around the end of November 1991.
  308. XOrdering info will be the same as above, but replace "CD" with "DIS" in the
  309. Xdocument number (alternate number not yet known).  The committee draft of
  310. XPart 2 is expected to be available around the end of December 1991.  It will
  311. Xbe titled "Digital Compression and Coding of Continuous-tone Still Images,
  312. XPart 2: Compliance testing" and will have document number ISO/IEC CD 10918-2
  313. X(alternate number not yet known).
  314. X
  315. XThe JPEG standard does not specify all details of an interchangeable file
  316. Xformat.  For the omitted details we follow the "JFIF" conventions, revision
  317. X1.01.  A copy of the JFIF spec is available from:
  318. X    Literature Department
  319. X    C-Cube Microsystems, Inc.
  320. X    399A West Trimble Road
  321. X    San Jose, CA  95131
  322. X    (408) 944-6300
  323. XThe same source can supply copies of the draft JPEG-in-TIFF documents
  324. X(Appendixes O and P to the TIFF spec).  PostScript versions of these
  325. Xdocuments can also be obtained by e-mail from the C-Cube mail server,
  326. Xnetlib@c3.pla.ca.us.  Send the message "send jfif_ps from jpeg" to obtain the
  327. XJFIF document; "send app_o_ps from jpeg" and "send app_p_ps from jpeg" will
  328. Xproduce the TIFF documents.  Send the message "help" if you have trouble.
  329. X
  330. XIf you want to understand this implementation, start by reading the
  331. X"architecture" documentation file.  Please read "codingrules" if you want to
  332. Xcontribute any code.
  333. X
  334. X
  335. XLEGAL ISSUES
  336. X============
  337. X
  338. XThe authors make NO WARRANTY or representation, either express or implied,
  339. Xwith respect to this software, its quality, accuracy, merchantability, or
  340. Xfitness for a particular purpose.  This software is provided "AS IS", and you,
  341. Xits user, assume the entire risk as to its quality and accuracy.
  342. X
  343. XThis software is copyright (C) 1991, 1992, Thomas G. Lane.
  344. XAll Rights Reserved except as specified below.
  345. X
  346. XPermission is hereby granted to use, copy, modify, and distribute this
  347. Xsoftware (or portions thereof) for any purpose, without fee, subject to these
  348. Xconditions:
  349. X(1) If any part of the source code for this software is distributed, then this
  350. XREADME file must be included, with this copyright and no-warranty notice
  351. Xunaltered; and any additions, deletions, or changes to the original files
  352. Xmust be clearly indicated in accompanying documentation.
  353. X(2) If only executable code is distributed, then the accompanying
  354. Xdocumentation must state that "this software is based in part on the work of
  355. Xthe Independent JPEG Group".
  356. X(3) Permission for use of this software is granted only if the user accepts
  357. Xfull responsibility for any undesirable consequences; the authors accept
  358. XNO LIABILITY for damages of any kind.
  359. X
  360. XPermission is NOT granted for the use of any author's name or author's company
  361. Xname in advertising or publicity relating to this software or products derived
  362. Xfrom it.  This software may be referred to only as "the Independent JPEG
  363. XGroup's software".
  364. X
  365. XWe specifically permit and encourage the use of this software as the basis of
  366. Xcommercial products, provided that all warranty or liability claims are
  367. Xassumed by the product vendor.
  368. X
  369. X
  370. Xansi2knr.c is included in this distribution by permission of L. Peter Deutsch,
  371. Xsole proprietor of its copyright holder, Aladdin Enterprises of Menlo Park, CA.
  372. Xansi2knr.c is NOT covered by the above copyright and conditions, but instead
  373. Xby the usual distribution terms of the Free Software Foundation; principally,
  374. Xthat you must include source code if you redistribute it.  (See the file
  375. Xansi2knr.c for full details.)  However, since ansi2knr.c is not needed as part
  376. Xof any product generated from the JPEG code, this does not limit you more than
  377. Xthe foregoing paragraphs do.
  378. X
  379. X
  380. XIt appears that the arithmetic coding option of the JPEG spec is covered by
  381. Xpatents owned by IBM and AT&T, as well as a pending Japanese patent of
  382. XMitsubishi.  Hence arithmetic coding cannot legally be used without obtaining
  383. Xone or more licenses.  For this reason, support for arithmetic coding has been
  384. Xremoved from the free JPEG software.  (Since arithmetic coding provides only a
  385. Xmarginal gain over the unpatented Huffman mode, it is unlikely that very many
  386. Xpeople will choose to use it.  If you do obtain the necessary licenses,
  387. Xcontact jpeg-info@uunet.uu.net for a copy of our arithmetic coding modules.)
  388. XSo far as we are aware, there are no patent restrictions on the remaining
  389. Xcode.
  390. X
  391. X
  392. XWe are required to state that
  393. X    "The Graphics Interchange Format(c) is the Copyright property of
  394. X    CompuServe Incorporated.  GIF(sm) is a Service Mark property of
  395. X    CompuServe Incorporated."
  396. X
  397. X
  398. XTO DO
  399. X=====
  400. X
  401. XMany of the modules need fleshing out to provide more complete
  402. Ximplementations, or to provide faster paths for common cases.
  403. XImproving the speed will be the next big work item for the JPEG group.
  404. X
  405. XWe'd appreciate it if people would compile and check out the code on as wide a
  406. Xvariety of systems as possible, and report any portability problems
  407. Xencountered (with solutions, if possible).  Checks of file compatibility with
  408. Xother JPEG implementations would also be of interest.  Finally, we would
  409. Xappreciate code profiles showing where the most time is spent, especially on
  410. Xunusual systems.
  411. X
  412. XPlease send bug reports, offers of help, etc. to jpeg-info@uunet.uu.net.
  413. END_OF_FILE
  414.   if test 18730 -ne `wc -c <'README'`; then
  415.     echo shar: \"'README'\" unpacked with wrong size!
  416.   fi
  417.   # end of 'README'
  418. fi
  419. if test -f 'arch.a' -a "${1}" != "-c" ; then 
  420.   echo shar: Will not clobber existing file \"'arch.a'\"
  421. else
  422.   echo shar: Extracting \"'arch.a'\" \(29060 characters\)
  423.   sed "s/^X//" >'arch.a' <<'END_OF_FILE'
  424. X
  425. X    JPEG SYSTEM ARCHITECTURE        29-FEB-92
  426. X
  427. X
  428. XThis file provides an overview of the "architecture" of the portable JPEG
  429. Xsoftware; that is, the functions of the various modules in the system and the
  430. Xinterfaces between modules.  For more precise details about any data structure
  431. Xor calling convention, see the header files.
  432. X
  433. XImportant note: when I say "module" I don't mean "a C function", which is what
  434. Xsome people seem to think the term means.  A separate C source file is closer
  435. Xto the mark.  Also, it is frequently the case that several different modules
  436. Xpresent a common interface to callers; the term "object" or "method" refers to
  437. Xthis common interface (see "Poor man's object-oriented programming", below).
  438. X
  439. XJPEG-specific terminology follows the JPEG standard:
  440. X  A "component" means a color channel, e.g., Red or Luminance.
  441. X  A "sample" is a pixel component value (i.e., one number in the image data).
  442. X  A "coefficient" is a frequency coefficient (a DCT transform output number).
  443. X  The term "block" refers to an 8x8 group of samples or coefficients.
  444. X  "MCU" (minimum coded unit) is the same as "MDU" of the R8 draft; i.e., an
  445. X    interleaved set of blocks of size determined by the sampling factors,
  446. X    or a single block in a noninterleaved scan.
  447. X
  448. X
  449. X*** System requirements ***
  450. X
  451. XWe must support compression and decompression of both Huffman and
  452. Xarithmetic-coded JPEG files.  Any set of compression parameters allowed by the
  453. XJPEG spec should be readable for decompression.  (We can be more restrictive
  454. Xabout what formats we can generate.)  (Note: for legal reasons no arithmetic
  455. Xcoding implementation is currently included in the publicly available sources.
  456. XHowever, the architecture still supports it.)
  457. X
  458. XWe need to be able to handle both raw JPEG files (more specifically, the JFIF
  459. Xformat) and JPEG-in-TIFF (C-cubed's format, and perhaps Kodak's).  Even if we
  460. Xdon't implement TIFF ourselves, other people will want to use our code for
  461. Xthat.  This means that generation and scanning of the file header has to be
  462. Xseparated out.
  463. X
  464. XPerhaps we should be prepared to support the JPEG lossless mode (also referred
  465. Xto in the spec as spatial DPCM coding).  A lot of people seem to believe they
  466. Xneed this... whether they really do is debatable, but the customer is always
  467. Xright.  On the other hand, there will not be much sharable code between the
  468. Xlossless and lossy modes!  At best, a lossless program could be derived from
  469. Xparts of the lossy version.  For now we will only worry about the lossy mode.
  470. X
  471. XI see no real value in supporting the JPEG progressive modes (note that
  472. Xspectral selection and successive approximation are two different progressive
  473. Xmodes).  These are only of interest when painting the decompressed image in
  474. Xreal-time, which nobody is going to do with a pure software implementation.
  475. X
  476. XThere is some value in supporting the hierarchical mode, which allows for
  477. Xsuccessive frames of higher resolution.  This could be of use for including
  478. X"thumbnail" representations.  However, this appears to add a lot more
  479. Xcomplexity than it is worth.
  480. X
  481. XA variety of uncompressed image file formats and user interfaces must be
  482. Xsupported.  These aspects therefore have to be kept separate from the rest of
  483. Xthe system.  A particularly important issue is whether color quantization of
  484. Xthe output is needed (i.e., whether a colormap is used).  We should be able to
  485. Xsupport both adaptive quantization (which requires two or more passes over the
  486. Ximage) and nonadaptive (quantization to a prespecified colormap, which can be
  487. Xdone in one pass).
  488. X
  489. XMemory usage is an important concern, since we will port this code to 80x86
  490. Xand other limited-memory machines.  For large intermediate structures, we
  491. Xshould be able to use either virtual memory or temporary files.
  492. X
  493. XIt should be possible to build programs that handle compression only,
  494. Xdecompression only, or both, without much duplicate or unused code in any
  495. Xversion.  (In particular, a decompression-only version should have no extra
  496. Xbaggage.)
  497. X
  498. X
  499. X*** Compression overview ***
  500. X
  501. XThe *logical* steps needed in (non-lossless) JPEG compression are:
  502. X
  503. X1. Conversion from incoming image format to a standardized internal form
  504. X   (either RGB or grayscale).
  505. X
  506. X2. Color space conversion (e.g., RGB to YCbCr).  This is a null step for
  507. X   grayscale (unless we support mapping color inputs to grayscale, which
  508. X   would most easily be done here).  Gamma adjustment may also be needed here.
  509. X
  510. X3. Subsampling (reduction of number of samples in some color components).
  511. X   This step operates independently on each color component.
  512. X
  513. X4. MCU extraction (creation of a single sequence of 8x8 sample blocks).
  514. X   This step and the following ones are performed once for each scan
  515. X   in the output JPEG file, i.e., once if making an interleaved file and more
  516. X   than once for a noninterleaved file.
  517. X   Note: both this step and the previous one must deal with edge conditions
  518. X   for pictures that aren't a multiple of the MCU dimensions.  Alternately,
  519. X   we could expand the picture to a multiple of an MCU before doing these
  520. X   two steps.  (The latter seems better and has been adopted below.)
  521. X
  522. X5. DCT transformation of each 8x8 block.
  523. X
  524. X6. Quantization scaling and zigzag reordering of the elements in each 8x8
  525. X   block.
  526. X
  527. X7. Huffman or arithmetic encoding of the transformed block sequence.
  528. X
  529. X8. Output of the JPEG file with whatever headers/markers are wanted.
  530. X
  531. XOf course, the actual implementation will combine some of these logical steps
  532. Xfor efficiency.  The trick is to keep these logical functions as separate as
  533. Xpossible without losing too much performance.
  534. X
  535. XIn addition to these logical pipeline steps, we need various modules that
  536. Xaren't part of the data pipeline.  These are:
  537. X
  538. XA. Overall control (sequencing of other steps & management of data passing).
  539. X
  540. XB. User interface; this will determine the input and output files, and supply
  541. X   values for some compression parameters.  Note that this module is highly
  542. X   platform-dependent.
  543. X
  544. XC. Compression parameter selection: some parameters should be chosen
  545. X   automatically rather than requiring the user to find a good value.
  546. X   The prototype only does this for the back-end (Huffman or arithmetic)
  547. X   parameters, but further in the future, more might be done.  A
  548. X   straightforward approach to selection is to try several values; this
  549. X   requires being able to repeatedly apply some portion of the pipeline and
  550. X   inspect the results (without actually outputting them).  Probably only
  551. X   entropy encoding parameters can reasonably be done this way; optimizing
  552. X   earlier steps would require too much data to be reprocessed (not to mention
  553. X   the problem of interactions between parameters for different steps).
  554. X   What other facilities do we need to support automatic parameter selection?
  555. X
  556. XD. A memory management module to deal with small-memory machines.  This must
  557. X   create the illusion of virtual memory for certain large data structures
  558. X   (e.g., the subsampled image or the transformed coefficients).
  559. X   The interface to this must be defined to minimize the overhead incurred,
  560. X   especially on virtual-memory machines where the module won't do much.
  561. X
  562. XIn many cases we can arrange things so that a data stream is produced in
  563. Xsegments by one module and consumed by another without the need to hold it all
  564. Xin (virtual) memory.  This is obviously not possible for any data that must be
  565. Xscanned more than once, so it won't work everywhere.
  566. X
  567. XThe major variable at this level of detail is whether the JPEG file is to be
  568. Xinterleaved or not; that affects the order of processing so fundamentally that
  569. Xthe central control module must know about it.  Some of the other modules may
  570. Xneed to know it too.  It would simplify life if we didn't need to support
  571. Xnoninterleaved images, but that is not reasonable.
  572. X
  573. XMany of these steps operate independently on each color component; the
  574. Xknowledge of how many components there are, and how they are interleaved,
  575. Xought to be confined to the central control module.  (Color space conversion
  576. Xand MCU extraction probably have to know it too.)
  577. X
  578. X
  579. X*** Decompression overview ***
  580. X
  581. XDecompression is roughly the inverse process from compression, but there are
  582. Xsome additional steps needed to produce a good output image.
  583. X
  584. XThe *logical* steps needed in (non-lossless) JPEG decompression are:
  585. X
  586. X1. Scanning of the JPEG file, decoding of headers/markers etc.
  587. X
  588. X2. Huffman or arithmetic decoding of the coefficient sequence.
  589. X
  590. X3. Quantization descaling and zigzag reordering of the elements in each 8x8
  591. X   block.
  592. X
  593. X4. MCU disassembly (conversion of a possibly interleaved sequence of 8x8
  594. X   blocks back to separate components in pixel map order).
  595. X
  596. X5. (Optional)  Cross-block smoothing per JPEG section K.8 or a similar
  597. X   algorithm.  (Steps 5-8 operate independently on each component.)
  598. X
  599. X6. Inverse DCT transformation of each 8x8 block.
  600. X
  601. X7. De-subsampling.  At this point a pixel image of the original dimensions
  602. X   has been recreated.
  603. X
  604. X8. Post-subsampling smoothing.  This can be combined with de-subsampling,
  605. X   by using a convolution-like calculation to generate each output pixel
  606. X   directly from one or more input pixels.
  607. X
  608. X9. Cropping to the original pixel dimensions (throwing away duplicated
  609. X   pixels at the edges).  It is most convenient to do this now, as the
  610. X   preceding steps are simplified by not having to worry about odd picture
  611. X   sizes.
  612. X
  613. X10. Color space reconversion (e.g., YCbCr to RGB).  This is a null step for
  614. X    grayscale.  (Note that mapping a color JPEG to grayscale output is most
  615. X    easily done in this step.)  Gamma adjustment may also be needed here.
  616. X
  617. X11. Color quantization (only if a colormapped output format is requested).
  618. X    NOTE: it is probably preferable to perform quantization in the internal
  619. X    (JPEG) colorspace rather than the output colorspace.  Doing it that way,
  620. X    color conversion need only be applied to the colormap entries, not to
  621. X    every pixel; and quantization gets to operate in a non-gamma-corrected
  622. X    space.  But the internal space may not be suitable for some algorithms.
  623. X    The system design is such that only the color quantizer module knows
  624. X    whether color conversion happens before or after quantization.
  625. X
  626. X12. Writing of the desired image format.
  627. X
  628. XAs before, some of these will be combined into single steps.  When dealing
  629. Xwith a noninterleaved JPEG file, steps 2-9 will be performed once for each
  630. Xscan; the resulting data will need to be buffered up so that steps 10-12 can
  631. Xprocess all the color components together.
  632. X
  633. XThe same auxiliary modules are needed as before, except for compression
  634. Xparameter selection.  Note that rerunning a pipeline stage should never be
  635. Xneeded during decompression.  This may allow a simpler control module.  The
  636. Xuser interface might also be simpler since it need not supply any compression
  637. Xparameters.
  638. X
  639. XAs before, not all of these steps require the whole image to be stored.
  640. XActually, two-pass color quantization is the only step that logically requires
  641. Xthis; everything else could be done a few raster lines at a time (at least for
  642. Xinterleaved images).  We might want to make color quantization be a separate
  643. Xprogram because of this fact.
  644. X
  645. XAgain, many of the steps should be able to work on one color component in
  646. Xignorance of the other components.
  647. X
  648. X
  649. X*** Implications of noninterleaved formats ***
  650. X
  651. XMuch of the work can be done in a single pass if an interleaved JPEG file
  652. Xformat is used.  With a noninterleaved JPEG file, separating or recombining
  653. Xthe components will force use of virtual memory (on a small-memory machine,
  654. Xwe probably would want one temp file per color component).
  655. X
  656. XIf any of the image formats we read or write are noninterleaved, the opposite
  657. Xcondition might apply: processing a noninterleaved JPEG file would be more
  658. Xefficient.  Offhand, though, I can't think of any popular image formats that
  659. Xwork that way; besides the win would only come if the same color space were
  660. Xused in JPEG and non-JPEG files.  It's not worth the complexity to make the
  661. Xsystem design accommodate that case efficiently.
  662. X
  663. XAn argument against interleaving is that it makes the decompressor need more
  664. Xmemory for cross-block smoothing (since the minimum processable chunk of the
  665. Ximage gets bigger).  With images more than 1000 pixels across, 80x86 machines
  666. Xare likely to have difficulty in handling this feature.
  667. X
  668. XAnother argument against interleaving is that the noninterleaved format allows
  669. Xa wider range of sampling factors, since the limit of ten blocks per MCU no
  670. Xlonger applies.  We could get around this by blithely ignoring the spec's
  671. Xlimit of ten blocks, but that seems like a bad idea (especially since it makes
  672. Xthe above problem worse).
  673. X
  674. XThe upshot is that we need to support both interleaved and noninterleaved JPEG
  675. Xformats, since for any given machine and picture size one may be much more
  676. Xefficient than the other.  However, the non-JPEG format we convert to or from
  677. Xwill be assumed to be an interleaved format (i.e., it produces or stores all
  678. Xthe components of a pixel together).
  679. X
  680. XI do not think it is necessary for the compressor to be able to output
  681. Xpartially-interleaved formats (multiple scans, some of which interleave a
  682. Xsubset of the components).  However, the decompressor must be able to read
  683. Xsuch files to conform to the spec.
  684. X
  685. X
  686. X*** Data formats ***
  687. X
  688. XPipeline steps that work on pixel sample values will use the following data
  689. Xstructure:
  690. X
  691. X    typedef something JSAMPLE;        a pixel component value, 0..MAXJSAMPLE
  692. X    typedef JSAMPLE *JSAMPROW;        ptr to a row of samples
  693. X    typedef JSAMPROW *JSAMPARRAY;    ptr to a list of rows
  694. X    typedef JSAMPARRAY *JSAMPIMAGE;    ptr to a list of color-component arrays
  695. X
  696. XThe basic element type JSAMPLE will be one of unsigned char, (signed) char, or
  697. Xunsigned short.  Unsigned short will be used if samples wider than 8 bits are
  698. Xto be supported (this is a compile-time option).  Otherwise, unsigned char is
  699. Xused if possible.  If the compiler only supports signed chars, then it is
  700. Xnecessary to mask off the value when reading.  Thus, all reads of sample
  701. Xvalues should be coded as "GETJSAMPLE(value)", where the macro will be defined
  702. Xas "((value)&0xFF)" on signed-char machines and "(value)" elsewhere.
  703. X
  704. XWith these conventions, JSAMPLE values can be assumed to be >= 0.  This should
  705. Xsimplify correct rounding during subsampling, etc.  The JPEG draft's
  706. Xspecification that sample values run from -128..127 will be accommodated by
  707. Xsubtracting 128 just as the sample value is copied into the source array for
  708. Xthe DCT step (this will be an array of signed shorts or longs).  Similarly,
  709. Xduring decompression the output of the IDCT step will be immediately shifted
  710. Xback to 0..255.  (NB: different values are required when 12-bit samples are in
  711. Xuse.  The code should be written in terms of MAXJSAMPLE and CENTERJSAMPLE,
  712. Xwhich will be #defined as 255 and 128 respectively in an 8-bit implementation,
  713. Xand as 4095 and 2048 in a 12-bit implementation.)
  714. X
  715. XOn compilers that don't support "unsigned short", signed short can be used for
  716. Xa 12-bit implementation.  To support lossless coding (which allows up to
  717. X16-bit data precision) masking with 0xFFFF in GETJSAMPLE might be necessary.
  718. X(But if "int" is 16 bits then using "unsigned int" is the best solution.)
  719. X
  720. XNotice that we use a pointer per row, rather than a two-dimensional JSAMPLE
  721. Xarray.  This choice costs only a small amount of memory and has several
  722. Xbenefits:
  723. X
  724. X* Code using the data structure doesn't need to know the allocated width of
  725. Xthe rows.  This will simplify edge expansion/compression, since we can work
  726. Xin an array that's wider than the logical picture width.
  727. X
  728. X* The rows forming a component array may be allocated at different times
  729. Xwithout extra copying.  This will simplify working a few scanlines at a time,
  730. Xespecially in smoothing steps that need access to the previous and next rows.
  731. X
  732. X* Indexing doesn't require multiplication; this is a performance win on many
  733. Xmachines.
  734. X
  735. XNote that each color component is stored in a separate array; we don't use the
  736. Xtraditional structure in which the components of a pixel are stored together.
  737. XThis simplifies coding of steps that work on each component independently,
  738. Xbecause they don't need to know how many components there are.  Furthermore,
  739. Xwe can read or write each component to a temp file independently, which is
  740. Xhelpful when dealing with noninterleaved JPEG files.
  741. X
  742. XA specific sample value will be accessed by code such as
  743. X    GETJSAMPLE(image[colorcomponent][row][col])
  744. Xwhere col is measured from the image left edge, but row is measured from the
  745. Xfirst sample row currently in memory.  Either of the first two indexings can
  746. Xbe precomputed by copying the relevant pointer.
  747. X
  748. X
  749. XPipeline steps that work on frequency-coefficient values will use the
  750. Xfollowing data structure:
  751. X
  752. X    typedef short JCOEF;        a 16-bit signed integer
  753. X    typedef JCOEF JBLOCK[64];        an 8x8 block of coefficients
  754. X    typedef JBLOCK *JBLOCKROW;        ptr to one horizontal row of 8x8 blocks
  755. X    typedef JBLOCKROW *JBLOCKARRAY;    ptr to a list of such rows
  756. X    typedef JBLOCKARRAY *JBLOCKIMAGE;    ptr to a list of color component arrays
  757. X
  758. XThe underlying type is always a 16-bit signed integer (this is "short" on all
  759. Xmachines of interest, but let's use the typedef name anyway).  These are
  760. Xgrouped into 8x8 blocks (we should use #defines DCTSIZE and DCTSIZE2 rather
  761. Xthan "8" and "64").  The contents of a block may be either in "natural" or
  762. Xzigzagged order, and may be true values or divided by the quantization
  763. Xcoefficients, depending on where the block is in the pipeline.
  764. X
  765. XNotice that the allocation unit is now a row of 8x8 blocks, corresponding to
  766. Xeight rows of samples.  Otherwise the structure is much the same as for
  767. Xsamples, and for the same reasons.
  768. X
  769. XOn machines where malloc() can't handle a request bigger than 64Kb, this data
  770. Xstructure limits us to rows of less than 512 JBLOCKs, which would be a picture
  771. Xwidth of 4000 pixels.  This seems an acceptable restriction.
  772. X
  773. X
  774. XOn 80x86 machines, the bottom-level pointer types (JSAMPROW and JBLOCKROW)
  775. Xmust be declared as "far" pointers, but the upper levels can be "near"
  776. X(implying that the pointer lists are allocated in the DS segment).
  777. XTo simplify sharing code, we'll have a #define symbol FAR, which expands to
  778. Xthe "far" keyword when compiling on 80x86 machines and to nothing elsewhere.
  779. X
  780. X
  781. XThe data arrays used as input and output of the DCT transform subroutine will
  782. Xbe declared using a separate typedef; they could be arrays of "short", "int"
  783. Xor "long" independently of the above choices.  This would depend on what is
  784. Xneeded to make the compiler generate correct and efficient multiply/add code
  785. Xin the DCT inner loops.  No significant speed or memory penalty will be paid
  786. Xto have a different representation than is used in the main image storage
  787. Xarrays, since some additional value-by-value processing is done at the time of
  788. Xcreation or extraction of the DCT data anyway (e.g., add/subtract 128).
  789. X
  790. X
  791. X*** Poor man's object-oriented programming ***
  792. X
  793. XIt should be pretty clear by now that we have a lot of quasi-independent
  794. Xsteps, many of which have several possible behaviors.  To avoid cluttering the
  795. Xcode with lots of switch statements, we'll use a simple form of object-style
  796. Xprogramming to separate out the different possibilities.
  797. X
  798. XFor example, Huffman and arithmetic coding will be implemented as two separate
  799. Xmodules that present the same external interface; at runtime, the calling code
  800. Xwill access the proper module indirectly through an "object".
  801. X
  802. XWe can get the limited features we need while staying within portable C.  The
  803. Xbasic tool is a function pointer.  An "object" is just a struct containing one
  804. Xor more function pointer fields, each of which corresponds to a method name in
  805. Xreal object-oriented languages.  During initialization we fill in the function
  806. Xpointers with references to whichever module we have determined we need to use
  807. Xin this run.  Then invocation of the module is done by indirecting through a
  808. Xfunction pointer; on most architectures this is no more expensive (and
  809. Xpossibly cheaper) than a switch, which would be the only other way of making
  810. Xthe required run-time choice.  The really significant benefit, of course, is
  811. Xkeeping the source code clean and well structured.
  812. X
  813. XFor example, the interface for entropy decoding (Huffman or arithmetic
  814. Xdecoding) might look like this:
  815. X
  816. X    struct function_ptr_struct {
  817. X        ...
  818. X        /* Entropy decoding methods */
  819. X        void (*prepare_for_scan) ();
  820. X        void (*get_next_mcu) ();
  821. X        ...
  822. X        };
  823. X
  824. X    typedef struct function_ptr_struct * function_ptrs;
  825. X
  826. XThe struct pointer is what will actually be passed around.  A call site might
  827. Xlook like this:
  828. X
  829. X    some_function (function_ptrs fptrs)
  830. X        {
  831. X        ...
  832. X        (*fptrs->get_next_mcu) (...);
  833. X        ...
  834. X        }
  835. X
  836. X(It might be worth inventing some specialized macros to hide the rather ugly
  837. Xsyntax for method definition and call.)  Note that the caller doesn't know how
  838. Xmany different get_next_mcu procedures there are, what their real names are,
  839. Xnor how to choose which one to call.
  840. X
  841. XAn important benefit of this scheme is that it is easy to provide multiple
  842. Xversions of any method, each tuned to a particular case.  While a lot of
  843. Xprecalculation might be done to select an optimal implementation of a method,
  844. Xthe cost per invocation is constant.  For example, the MCU extraction step
  845. Xmight have a "generic" method, plus one or more "hardwired" methods for the
  846. Xmost popular sampling factors; the hardwired methods would be faster because
  847. Xthey'd use straight-line code instead of for-loops.  The cost to determine
  848. Xwhich method to use is paid only once, at startup, and the selection criteria
  849. Xare hidden from the callers of the method.
  850. X
  851. XThis plan differs a little bit from usual object-oriented structures, in that
  852. Xonly one instance of each object class will exist during execution.  The
  853. Xreason for having the class structure is that on different runs we may create
  854. Xdifferent instances (choose to execute different modules).
  855. X
  856. XTo minimize the number of object pointers that have to be passed around, it
  857. Xwill be easiest to have just a few big structs containing all the method
  858. Xpointers.  We'll actually use two such structs, one for "system-dependent"
  859. Xmethods (memory allocation and error handling) and one for everything else.
  860. X
  861. XBecause of this choice, it's best not to think of an "object" as a specific
  862. Xdata structure.  Rather, an "object" is just a group of related methods.
  863. XThere would typically be one or more C modules (source files) providing
  864. Xconcrete implementations of those methods.  You can think of the term
  865. X"method" as denoting the common interface presented by some set of functions,
  866. Xand "object" as denoting a group of common method interfaces, or the total
  867. Xshared interface behavior of a group of modules.
  868. X
  869. X
  870. X*** Data chunk sizes ***
  871. X
  872. XTo make the cost of this object-oriented style really minimal, we should make
  873. Xsure that each method call does a fair amount of computation.  To do that we
  874. Xshould pass large chunks of data around; for example, the colorspace
  875. Xconversion method should process much more than one pixel per call.
  876. X
  877. XFor many steps, the most natural unit of data seems to be an "MCU row".
  878. XThis consists of one complete horizontal strip of the image, as high as an
  879. XMCU.  In a noninterleaved scan, an MCU row is always eight samples high (when
  880. Xlooking at samples) or one 8x8 block high (when looking at coefficients).  In
  881. Xan interleaved scan, an MCU row consists of all the data for one horizontal
  882. Xrow of MCUs; this may be from one to four blocks high (eight to thirty-two
  883. Xsamples) depending on the sampling factors.  The height and width of an MCU
  884. Xrow may be different in each component.  (Note that the height and width of an
  885. XMCU row changes at the subsampling and de-subsampling steps.  An unsubsampled
  886. Ximage has the same size in each component.  The preceding statements apply to
  887. Xthe subsampled dimensions.)
  888. X
  889. XFor example, consider a 1024-pixel-wide image using (2h:2v)(1h:1v)(1h:1v)
  890. Xsubsampling.  In the noninterleaved case, an MCU row of Y would contain 8x1024
  891. Xsamples or the same number of frequency coefficients, so it would occupy
  892. X8K bytes (samples) or 16K bytes (coefficients).  An MCU row of Cb or Cr would
  893. Xcontain 8x512 samples and occupy half as much space.  In the interleaved case,
  894. Xan MCU row would contain 16x1024 Y samples, 8x512 Cb and 8x512 Cr samples, so
  895. Xa total of 24K (samples) or 48K (coefficients) would be needed.  This is a
  896. Xreasonable amount of data to expect to retain in memory at one time.  (Bear in
  897. Xmind that we'll usually need to have several MCU rows resident in memory at
  898. Xonce, at the inputs and outputs to various pipeline steps.)
  899. X
  900. XThe worst case is probably (2h:4v)(1h:1v)(1h:1v) interleaving (this uses 10
  901. Xblocks per MCU, which is the maximum allowed by the spec).  An MCU will then
  902. Xcontain 32 sample rows worth of Y, so it would occupy 40K or 80K bytes for a
  903. X1024-pixel-wide image.  The most memory-intensive step is probably cross-block
  904. Xsmoothing, for which we'd need 3 MCU rows of coefficients as input and another
  905. Xone as output; that would be 320K of working storage.  Anything much larger
  906. Xwould not fit in an 80x86 machine.  (To decompress wider pictures on an 80x86,
  907. Xwe'll have to skip cross-block smoothing or else use temporary files.)
  908. X
  909. XThis unit is thus a reasonable-sized chunk for passing through the pipeline.
  910. XOf course, its major advantage is that it is a natural chunk size for the MCU
  911. Xassembly and disassembly steps to work with.
  912. X
  913. XFor the entropy (Huffman or arithmetic) encoding/decoding steps, the most
  914. Xconvenient chunk is a single MCU: one 8x8 block if not interleaved, three to
  915. Xten such blocks if interleaved.  The advantage of this is that when handling
  916. Xinterleaved data, the blocks have the same sequence of component membership on
  917. Xeach call.  (For example, Y,Y,Y,Y,Cb,Cr when using (2h:2v)(1h:1v)(1h:1v)
  918. Xsubsampling.)  The code needs to know component membership so that it can
  919. Xapply the right set of compression coefficients to each block.  A prebuilt
  920. Xarray describing this membership can be used during each call.  This chunk
  921. Xsize also makes it easy to handle restart intervals: just count off one MCU
  922. Xper call and reinitialize when the count reaches zero (restart intervals are
  923. Xspecified in numbers of MCU).
  924. X
  925. XFor similar reasons, one MCU is also the best chunk size for the frequency
  926. Xcoefficient quantization and dequantization steps.
  927. X
  928. XFor subsampling and desubsampling, the best chunk size is to have each call
  929. Xtransform Vk sample rows from or to Vmax sample rows (Vk = this component's
  930. Xvertical sampling factor, Vmax = largest vertical sampling factor).  There are
  931. Xeight such chunks in each MCU row.  Using a whole MCU row as the chunk size
  932. Xwould reduce function call overhead a fraction, but would imply more buffering
  933. Xto provide context for cross-pixel smoothing.
  934. X
  935. X
  936. X*** Compression object structure ***
  937. X
  938. XI propose the following set of objects for the compressor.  Here an "object"
  939. Xis the common interface for one or more modules having comparable functions.
  940. X
  941. XMost of these objects can be justified as information-hiding modules.
  942. XI've indicated what information is private to each object/module.
  943. X
  944. XNote that in all cases, the caller of a method is expected to have allocated
  945. Xany storage needed for it to return its result.  (Typically this storage can
  946. Xbe re-used in successive calls, so malloc'ing and free'ing once per call is
  947. Xnot reasonable.)  Also, much of the context required (compression parameters,
  948. Ximage size, etc) will be passed around in large common data structures, which
  949. Xaren't described here; see the header files.  Notice that any object that
  950. Xmight need to allocate working storage receives an "init" and a "term" call;
  951. X"term" should be careful to free all allocated storage so that the JPEG system
  952. Xcan be used multiple times during a program run.  (For the same reason,
  953. Xdepending on static initialization of variables is a no-no.  The only
  954. Xexception to the free-all-allocated-storage rule is that storage allocated for
  955. Xthe entire processing of an image need not be explicitly freed, since the
  956. Xmemory manager's free_all cleanup will free it.)
  957. X
  958. X1. Input file conversion to standardized form.  This provides these methods:
  959. X    input_init: read the file header, report image size & component count.
  960. X    get_input_row: read one pixel row, return it in our standard format.
  961. X    input_term: finish up at the end.
  962. X   In implementations that support multiple input formats, input_init could
  963. X   set up an appropriate get_input_row method depending on the format it
  964. X   finds.  Note that in most applications, the selection and opening of the
  965. X   input file will be under the control of the user interface module; and
  966. X   indeed the user interface may have already read the input header, so that
  967. X   all that input_init may have to do is return previously saved values.  The
  968. X   behind-the-scenes interaction between this object and the user interface is
  969. X   not specified by this architecture.
  970. X   (Hides format of input image and mechanism used to read it.  This code is
  971. X   likely to vary considerably from one implementation to another.  Note that
  972. X   the color space and number of color components of the source are not hidden;
  973. X   but they are used only by the next object.)
  974. X
  975. END_OF_FILE
  976.   if test 29060 -ne `wc -c <'arch.a'`; then
  977.     echo shar: \"'arch.a'\" unpacked with wrong size!
  978.   elif [ -f arch.b ]; then
  979.     echo shar: Combining \"'arch.a'\" and \"'arch.b'\" into \"'architecture'\"
  980.     cat arch.a arch.b > architecture
  981.     echo shar: Removing \"'arch.a'\" and \"'arch.b'\"
  982.     rm arch.a arch.b
  983.   # end of 'arch.a'
  984.   fi
  985. fi
  986. if test -f 'makefile.vms' -a "${1}" != "-c" ; then 
  987.   echo shar: Will not clobber existing file \"'makefile.vms'\"
  988. else
  989.   echo shar: Extracting \"'makefile.vms'\" \(2044 characters\)
  990.   sed "s/^X//" >'makefile.vms' <<'END_OF_FILE'
  991. X$! Makefile for Independent JPEG Group's software
  992. X$!
  993. X$! This is a command procedure for use on VAX/VMS systems that do not have MMS.
  994. X$! It builds the JPEG software by brute force, recompiling everything whether
  995. X$! or not it is necessary.
  996. X$! Thanks to Rick Dyson (dyson@iowasp.physics.uiowa.edu) for his help.
  997. X$!
  998. X$! Read SETUP instructions before running this!!
  999. X$!
  1000. X$ DoCompile := CC /NoDebug /Optimize /Define = (TWO_FILE_COMMANDLINE,HAVE_STDC,INCLUDES_ARE_ANSI)
  1001. X$!
  1002. X$ DoCompile jcmain.c
  1003. X$ DoCompile jdmain.c
  1004. X$ DoCompile jcmaster.c
  1005. X$ DoCompile jcdeflts.c
  1006. X$ DoCompile jcarith.c
  1007. X$ DoCompile jccolor.c
  1008. X$ DoCompile jcexpand.c
  1009. X$ DoCompile jchuff.c
  1010. X$ DoCompile jcmcu.c
  1011. X$ DoCompile jcpipe.c
  1012. X$ DoCompile jcsample.c
  1013. X$ DoCompile jfwddct.c
  1014. X$ DoCompile jwrjfif.c
  1015. X$ DoCompile jrdgif.c
  1016. X$ DoCompile jrdppm.c
  1017. X$ DoCompile jrdrle.c
  1018. X$ DoCompile jrdtarga.c
  1019. X$ DoCompile jdmaster.c
  1020. X$ DoCompile jddeflts.c
  1021. X$ DoCompile jbsmooth.c
  1022. X$ DoCompile jdarith.c
  1023. X$ DoCompile jdcolor.c
  1024. X$ DoCompile jdhuff.c
  1025. X$ DoCompile jdmcu.c
  1026. X$ DoCompile jdpipe.c
  1027. X$ DoCompile jdsample.c
  1028. X$ DoCompile jquant1.c
  1029. X$ DoCompile jquant2.c
  1030. X$ DoCompile jrevdct.c
  1031. X$ DoCompile jrdjfif.c
  1032. X$ DoCompile jwrgif.c
  1033. X$ DoCompile jwrppm.c
  1034. X$ DoCompile jwrrle.c
  1035. X$ DoCompile jwrtarga.c
  1036. X$ DoCompile jutils.c
  1037. X$ DoCompile jerror.c
  1038. X$ DoCompile jmemmgr.c
  1039. X$ DoCompile jmemsys.c
  1040. X$!
  1041. X$ Library /Create libjpeg.olb  jcmaster.obj,jcdeflts.obj,jcarith.obj, -
  1042. X          jccolor.obj,jcexpand.obj,jchuff.obj,jcmcu.obj,jcpipe.obj, -
  1043. X          jcsample.obj,jfwddct.obj,jwrjfif.obj,jrdgif.obj,jrdppm.obj, -
  1044. X          jrdrle.obj,jrdtarga.obj,jdmaster.obj,jddeflts.obj,jbsmooth.obj, -
  1045. X          jdarith.obj,jdcolor.obj,jdhuff.obj,jdmcu.obj,jdpipe.obj, -
  1046. X          jdsample.obj,jquant1.obj,jquant2.obj,jrevdct.obj,jrdjfif.obj, -
  1047. X          jwrgif.obj,jwrppm.obj,jwrrle.obj,jwrtarga.obj,jutils.obj, -
  1048. X          jerror.obj,jmemmgr.obj,jmemsys.obj
  1049. X$!
  1050. X$ Link /Executable = cjpeg.exe  jcmain.obj,libjpeg.olb/Library,Sys$Disk:[]MAKVMS.OPT/Option
  1051. X$!
  1052. X$ Link /Executable = djpeg.exe  jdmain.obj,libjpeg.olb/Library,Sys$Disk:[]MAKVMS.OPT/Option
  1053. X$!
  1054. X$ Exit
  1055. END_OF_FILE
  1056.   if test 2044 -ne `wc -c <'makefile.vms'`; then
  1057.     echo shar: \"'makefile.vms'\" unpacked with wrong size!
  1058.   fi
  1059.   # end of 'makefile.vms'
  1060. fi
  1061. echo shar: End of archive 1 \(of 18\).
  1062. cp /dev/null ark1isdone
  1063. MISSING=""
  1064. for I in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 ; do
  1065.     if test ! -f ark${I}isdone ; then
  1066.     MISSING="${MISSING} ${I}"
  1067.     fi
  1068. done
  1069. if test "${MISSING}" = "" ; then
  1070.     echo You have unpacked all 18 archives.
  1071.     rm -f ark[1-9]isdone ark[1-9][0-9]isdone
  1072. else
  1073.     echo You still must unpack the following archives:
  1074.     echo "        " ${MISSING}
  1075. fi
  1076. exit 0
  1077. exit 0 # Just in case...
  1078.