Markdown versions of README, LICENSE, BUILDING

LICENSE.md

@@ -1,25 +1,27 @@
 libjpeg-turbo Licenses
-----------------------
+======================
 
 libjpeg-turbo is covered by three compatible BSD-style open source licenses:
 
--- The IJG (Independent JPEG Group) License, which is listed in README
+- The IJG (Independent JPEG Group) License, which is listed in
+  [README.ijg](README.ijg)
 
   This license applies to the libjpeg API library and associated programs
   (any code inherited from libjpeg, and any modifications to that code.)
 
--- The Modified (3-clause) BSD License, which is listed in turbojpeg.c
+- The Modified (3-clause) BSD License, which is listed in
+  [turbojpeg.c](turbojpeg.c)
 
   This license covers the TurboJPEG API library and associated programs.
 
--- The zlib License, which is listed in simd/jsimdext.inc
+- The zlib License, which is listed in [simd/jsimdext.inc](simd/jsimdext.inc)
 
   This license is a subset of the other two, and it covers the libjpeg-turbo
   SIMD extensions.
 
 
 Complying with the libjpeg-turbo Licenses
------------------------------------------
+=========================================
 
 This section provides a roll-up of the libjpeg-turbo licensing terms, to the
 best of our understanding.
@@ -27,53 +29,60 @@ best of our understanding.
 1.  If you are distributing a modified version of the libjpeg-turbo source,
     then:
 
-    a.  You cannot alter or remove any existing copyright or license notices
+    1.  You cannot alter or remove any existing copyright or license notices
         from the source.
 
-        Origin:  Clause 1 of the IJG License
+        **Origin**
-                 Clause 1 of the Modified BSD License
+        - Clause 1 of the IJG License
-                 Clauses 1 and 3 of the zlib License
+        - Clause 1 of the Modified BSD License
+        - Clauses 1 and 3 of the zlib License
 
-    b.  You must add your own copyright notice to the header of each source
+    2.  You must add your own copyright notice to the header of each source
         file you modified, so others can tell that you modified that file (if
         there is not an existing copyright header in that file, then you can
         simply add a notice stating that you modified the file.)
 
-        Origin:  Clause 1 of the IJG License
+        **Origin**
-                 Clause 2 of the zlib License
+        - Clause 1 of the IJG License
+        - Clause 2 of the zlib License
 
-    c.  You must include the IJG README file, and you must not alter any of the
+    3.  You must include the IJG README file, and you must not alter any of the
         copyright or license text in that file.
 
-        Origin:  Clause 1 of the IJG License
+        **Origin**
+        - Clause 1 of the IJG License
 
 2.  If you are distributing only libjpeg-turbo binaries without the source, or
     if you are distributing an application that statically links with
     libjpeg-turbo, then:
 
-    a.  Your product documentation must include a message stating:
+    1.  Your product documentation must include a message stating:
 
         This software is based in part on the work of the Independent JPEG
         Group.
 
-        Origin:  Clause 2 of the IJG license
+        **Origin**
+        - Clause 2 of the IJG license
 
-    b.  If your binary distribution includes or uses the TurboJPEG API, then
+    2.  If your binary distribution includes or uses the TurboJPEG API, then
         your product documentation must include the text of the Modified BSD
         License.
 
-        Origin:  Clause 2 of the Modified BSD License
+        **Origin**
+        - Clause 2 of the Modified BSD License
 
 3.  You cannot use the name of the IJG or The libjpeg-turbo Project or the
     contributors thereof in advertising, publicity, etc.
 
-    Origin:  IJG License
+    **Origin**
-             Clause 3 of the Modified BSD License
+    - IJG License
+    - Clause 3 of the Modified BSD License
 
 4.  The IJG and The libjpeg-turbo Project do not warrant libjpeg-turbo to be
     free of defects, nor do we accept any liability for undesirable
     consequences resulting from your use of the software.
 
-    Origin:  IJG License
+    **Origin**
-             Modified BSD License
+    - IJG License
-             zlib License
+    - Modified BSD License
+    - zlib License

README.md

@@ -1,6 +1,5 @@
-*******************************************************************************
+Background
-**     Background
+==========
-*******************************************************************************
 
 libjpeg-turbo is a JPEG image codec that uses SIMD instructions (MMX, SSE2,
 NEON, AltiVec) to accelerate baseline JPEG compression and decompression on
@@ -24,41 +23,40 @@ of making high-speed JPEG compression/decompression technology available to a
 broader range of users and developers.
 
 
-*******************************************************************************
+License
-**     License
+=======
-*******************************************************************************
 
 libjpeg-turbo is covered by three compatible BSD-style open source licenses.
-Refer to LICENSE.txt for a roll-up of license terms.
+Refer to [LICENSE.md](LICENSE.md) for a roll-up of license terms.
 
 
-*******************************************************************************
+Using libjpeg-turbo
-**     Using libjpeg-turbo
+===================
-*******************************************************************************
 
 libjpeg-turbo includes two APIs that can be used to compress and decompress
 JPEG images:
 
-  TurboJPEG API:  This API provides an easy-to-use interface for compressing
+- **TurboJPEG API**  
-  and decompressing JPEG images in memory.  It also provides some functionality
+  This API provides an easy-to-use interface for compressing and decompressing
-  that would not be straightforward to achieve using the underlying libjpeg
+  JPEG images in memory.  It also provides some functionality that would not be
-  API, such as generating planar YUV images and performing multiple
+  straightforward to achieve using the underlying libjpeg API, such as
-  simultaneous lossless transforms on an image.  The Java interface for
+  generating planar YUV images and performing multiple simultaneous lossless
-  libjpeg-turbo is written on top of the TurboJPEG API.
+  transforms on an image.  The Java interface for libjpeg-turbo is written on
+  top of the TurboJPEG API.
 
-  libjpeg API:  This is the de facto industry-standard API for compressing and
+- **libjpeg API**  
-  decompressing JPEG images.  It is more difficult to use than the TurboJPEG
+  This is the de facto industry-standard API for compressing and decompressing
-  API but also more powerful.  The libjpeg API implementation in libjpeg-turbo
+  JPEG images.  It is more difficult to use than the TurboJPEG API but also
-  is both API/ABI-compatible and mathematically compatible with libjpeg v6b.
+  more powerful.  The libjpeg API implementation in libjpeg-turbo is both
-  It can also optionally be configured to be API/ABI-compatible with libjpeg v7
+  API/ABI-compatible and mathematically compatible with libjpeg v6b.  It can
-  and v8 (see below.)
+  also optionally be configured to be API/ABI-compatible with libjpeg v7 and v8
+  (see below.)
 
 There is no significant performance advantage to either API when both are used
 to perform similar operations.
 
-=====================
 Colorspace Extensions
-=====================
+---------------------
 
 libjpeg-turbo includes extensions that allow JPEG images to be compressed
 directly from (and decompressed directly to) buffers that use BGR, BGRX,
@@ -76,7 +74,7 @@ colorspace constants:
     JCS_EXT_ABGR  /* alpha/blue/green/red */
     JCS_EXT_ARGB  /* alpha/red/green/blue */
 
-Setting cinfo.in_color_space (compression) or cinfo.out_color_space
+Setting `cinfo.in_color_space` (compression) or `cinfo.out_color_space`
 (decompression) to one of these values will cause libjpeg-turbo to read the
 red, green, and blue values from (or write them to) the appropriate position in
 the pixel when compressing from/decompressing to an RGB buffer.
@@ -94,9 +92,10 @@ available for the colorspace extensions.
 When using the RGBX, BGRX, XBGR, and XRGB colorspaces during decompression, the
 X byte is undefined, and in order to ensure the best performance, libjpeg-turbo
 can set that byte to whatever value it wishes.  If an application expects the X
-byte to be used as an alpha channel, then it should specify JCS_EXT_RGBA,
+byte to be used as an alpha channel, then it should specify `JCS_EXT_RGBA`,
-JCS_EXT_BGRA, JCS_EXT_ABGR, or JCS_EXT_ARGB.  When these colorspace constants
+`JCS_EXT_BGRA`, `JCS_EXT_ABGR`, or `JCS_EXT_ARGB`.  When these colorspace
-are used, the X byte is guaranteed to be 0xFF, which is interpreted as opaque.
+constants are used, the X byte is guaranteed to be 0xFF, which is interpreted
+as opaque.
 
 Your application can check for the existence of the alpha channel colorspace
 extensions at compile time with:
@@ -106,9 +105,8 @@ extensions at compile time with:
 jcstest.c, located in the libjpeg-turbo source tree, demonstrates how to check
 for the existence of the colorspace extensions at compile time and run time.
 
-===================================
 libjpeg v7 and v8 API/ABI Emulation
-===================================
+-----------------------------------
 
 With libjpeg v7 and v8, new features were added that necessitated extending the
 compression and decompression structures.  Unfortunately, due to the exposed
@@ -125,49 +123,48 @@ without recompiling.  libjpeg-turbo does not claim to support all of the
 libjpeg v7+ features, nor to produce identical output to libjpeg v7+ in all
 cases (see below.)
 
-By passing an argument of --with-jpeg7 or --with-jpeg8 to configure, or an
+By passing an argument of `--with-jpeg7` or `--with-jpeg8` to `configure`, or
-argument of -DWITH_JPEG7=1 or -DWITH_JPEG8=1 to cmake, you can build a version
+an argument of `-DWITH_JPEG7=1` or `-DWITH_JPEG8=1` to `cmake`, you can build a
-of libjpeg-turbo that emulates the libjpeg v7 or v8 ABI, so that programs
+version of libjpeg-turbo that emulates the libjpeg v7 or v8 ABI, so that
-that are built against libjpeg v7 or v8 can be run with libjpeg-turbo.  The
+programs that are built against libjpeg v7 or v8 can be run with libjpeg-turbo.
-following section describes which libjpeg v7+ features are supported and which
+The following section describes which libjpeg v7+ features are supported and
-aren't.
+which aren't.
 
-Support for libjpeg v7 and v8 Features:
+### Support for libjpeg v7 and v8 Features
----------------------------------------
 
-Fully supported:
+#### Fully supported
 
--- libjpeg: IDCT scaling extensions in decompressor
+- **libjpeg: IDCT scaling extensions in decompressor**  
   libjpeg-turbo supports IDCT scaling with scaling factors of 1/8, 1/4, 3/8,
   1/2, 5/8, 3/4, 7/8, 9/8, 5/4, 11/8, 3/2, 13/8, 7/4, 15/8, and 2/1 (only 1/4
   and 1/2 are SIMD-accelerated.)
 
--- libjpeg: arithmetic coding
+- **libjpeg: Arithmetic coding**
 
--- libjpeg: In-memory source and destination managers
+- **libjpeg: In-memory source and destination managers**  
   See notes below.
 
--- cjpeg: Separate quality settings for luminance and chrominance
+- **cjpeg: Separate quality settings for luminance and chrominance**  
   Note that the libpjeg v7+ API was extended to accommodate this feature only
   for convenience purposes.  It has always been possible to implement this
   feature with libjpeg v6b (see rdswitch.c for an example.)
 
--- cjpeg: 32-bit BMP support
+- **cjpeg: 32-bit BMP support**
 
--- cjpeg: -rgb option
+- **cjpeg: `-rgb` option**
 
--- jpegtran: lossless cropping
+- **jpegtran: Lossless cropping**
 
--- jpegtran: -perfect option
+- **jpegtran: `-perfect` option**
 
--- jpegtran: forcing width/height when performing lossless crop
+- **jpegtran: Forcing width/height when performing lossless crop**
 
--- rdjpgcom: -raw option
+- **rdjpgcom: `-raw` option**
 
--- rdjpgcom: locale awareness
+- **rdjpgcom: Locale awareness**
 
 
-Not supported:
+#### Not supported
 
 NOTE:  As of this writing, extensive research has been conducted into the
 usefulness of DCT scaling as a means of data reduction and SmartScale as a
@@ -176,15 +173,15 @@ http://www.libjpeg-turbo.org/About/SmartScale and draw his/her own conclusions,
 but it is the general belief of our project that these features have not
 demonstrated sufficient usefulness to justify inclusion in libjpeg-turbo.
 
--- libjpeg: DCT scaling in compressor
+- **libjpeg: DCT scaling in compressor**  
-   cinfo.scale_num and cinfo.scale_denom are silently ignored.
+  `cinfo.scale_num` and `cinfo.scale_denom` are silently ignored.  
   There is no technical reason why DCT scaling could not be supported when
   emulating the libjpeg v7+ API/ABI, but without the SmartScale extension (see
   below), only scaling factors of 1/2, 8/15, 4/7, 8/13, 2/3, 8/11, 4/5, and
   8/9 would be available, which is of limited usefulness.
 
--- libjpeg: SmartScale
+- **libjpeg: SmartScale**  
-   cinfo.block_size is silently ignored.
+  `cinfo.block_size` is silently ignored.  
   SmartScale is an extension to the JPEG format that allows for DCT block
   sizes other than 8x8.  Providing support for this new format would be
   feasible (particularly without full acceleration.)  However, until/unless
@@ -192,58 +189,57 @@ demonstrated sufficient usefulness to justify inclusion in libjpeg-turbo.
   accepted solution in the community, we are hesitant to implement it, as
   there is no sense of whether or how it might change in the future.  It is
   our belief that SmartScale has not demonstrated sufficient usefulness as a
-   lossless format nor as a means of quality enhancement, and thus, our primary
+  lossless format nor as a means of quality enhancement, and thus our primary
   interest in providing this feature would be as a means of supporting
   additional DCT scaling factors.
 
--- libjpeg: Fancy downsampling in compressor
+- **libjpeg: Fancy downsampling in compressor**  
-   cinfo.do_fancy_downsampling is silently ignored.
+  `cinfo.do_fancy_downsampling` is silently ignored.  
   This requires the DCT scaling feature, which is not supported.
 
--- jpegtran: Scaling
+- **jpegtran: Scaling**  
   This requires both the DCT scaling and SmartScale features, which are not
   supported.
 
--- Lossless RGB JPEG files
+- **Lossless RGB JPEG files**  
   This requires the SmartScale feature, which is not supported.
 
-What About libjpeg v9?
+### What About libjpeg v9?
-----------------------
 
 libjpeg v9 introduced yet another field to the JPEG compression structure
-(color_transform), thus making the ABI backward incompatible with that of
+(`color_transform`), thus making the ABI backward incompatible with that of
 libjpeg v8.  This new field was introduced solely for the purpose of supporting
-lossless SmartScale encoding.  Further, there was actually no reason to extend
+lossless SmartScale encoding.  Furthermore, there was actually no reason to
-the API in this manner, as the color transform could have just as easily been
+extend the API in this manner, as the color transform could have just as easily
-activated by way of a new JPEG colorspace constant, thus preserving backward
+been activated by way of a new JPEG colorspace constant, thus preserving
-ABI compatibility.
+backward ABI compatibility.
 
 Our research (see link above) has shown that lossless SmartScale does not
 generally accomplish anything that can't already be accomplished better with
-existing, standard lossless formats.  Thus, at this time, it is our belief that
+existing, standard lossless formats.  Therefore, at this time it is our belief
-there is not sufficient technical justification for software to upgrade from
+that there is not sufficient technical justification for software projects to
-libjpeg v8 to libjpeg v9, and therefore, not sufficient technical justification
+upgrade from libjpeg v8 to libjpeg v9, and thus there is not sufficient
-for us to emulate the libjpeg v9 ABI.
+echnical justification for us to emulate the libjpeg v9 ABI.
 
-=====================================
 In-Memory Source/Destination Managers
-=====================================
+-------------------------------------
 
-By default, libjpeg-turbo 1.3 and later includes the jpeg_mem_src() and
+By default, libjpeg-turbo 1.3 and later includes the `jpeg_mem_src()` and
-jpeg_mem_dest() functions, even when not emulating the libjpeg v8 API/ABI.
+`jpeg_mem_dest()` functions, even when not emulating the libjpeg v8 API/ABI.
 Previously, it was necessary to build libjpeg-turbo from source with libjpeg v8
 API/ABI emulation in order to use the in-memory source/destination managers,
 but several projects requested that those functions be included when emulating
 the libjpeg v6b API/ABI as well.  This allows the use of those functions by
-programs that need them without breaking ABI compatibility for programs that
+programs that need them, without breaking ABI compatibility for programs that
 don't, and it allows those functions to be provided in the "official"
 libjpeg-turbo binaries.
 
 Those who are concerned about maintaining strict conformance with the libjpeg
-v6b or v7 API can pass an argument of --without-mem-srcdst to configure or
+v6b or v7 API can pass an argument of `--without-mem-srcdst` to `configure` or
-an argument of -DWITH_MEM_SRCDST=0 to CMake prior to building libjpeg-turbo.
+an argument of `-DWITH_MEM_SRCDST=0` to `cmake` prior to building
-This will restore the pre-1.3 behavior, in which jpeg_mem_src() and
+libjpeg-turbo.  This will restore the pre-1.3 behavior, in which
-jpeg_mem_dest() are only included when emulating the libjpeg v8 API/ABI.
+`jpeg_mem_src()` and `jpeg_mem_dest()` are only included when emulating the
+libjpeg v8 API/ABI.
 
 On Un*x systems, including the in-memory source/destination managers changes
 the dynamic library version from 62.0.0 to 62.1.0 if using libjpeg v6b API/ABI
@@ -251,32 +247,33 @@ emulation and from 7.0.0 to 7.1.0 if using libjpeg v7 API/ABI emulation.
 
 Note that, on most Un*x systems, the dynamic linker will not look for a
 function in a library until that function is actually used.  Thus, if a program
-is built against libjpeg-turbo 1.3+ and uses jpeg_mem_src() or jpeg_mem_dest(),
+is built against libjpeg-turbo 1.3+ and uses `jpeg_mem_src()` or
-that program will not fail if run against an older version of libjpeg-turbo or
+`jpeg_mem_dest()`, that program will not fail if run against an older version
-against libjpeg v7- until the program actually tries to call jpeg_mem_src() or
+of libjpeg-turbo or against libjpeg v7- until the program actually tries to
-jpeg_mem_dest().  Such is not the case on Windows.  If a program is built
+call `jpeg_mem_src()` or `jpeg_mem_dest()`.  Such is not the case on Windows.
-against the libjpeg-turbo 1.3+ DLL and uses jpeg_mem_src() or jpeg_mem_dest(),
+If a program is built against the libjpeg-turbo 1.3+ DLL and uses
-then it must use the libjpeg-turbo 1.3+ DLL at run time.
+`jpeg_mem_src()` or `jpeg_mem_dest()`, then it must use the libjpeg-turbo 1.3+
+DLL at run time.
 
 Both cjpeg and djpeg have been extended to allow testing the in-memory
 source/destination manager functions.  See their respective man pages for more
 details.
 
 
-*******************************************************************************
+Mathematical Compatibility
-**     Mathematical Compatibility
+==========================
-*******************************************************************************
 
 For the most part, libjpeg-turbo should produce identical output to libjpeg
 v6b.  The one exception to this is when using the floating point DCT/IDCT, in
 which case the outputs of libjpeg v6b and libjpeg-turbo can differ for the
 following reasons:
 
--- The SSE/SSE2 floating point DCT implementation in libjpeg-turbo is ever so
+- The SSE/SSE2 floating point DCT implementation in libjpeg-turbo is ever so
   slightly more accurate than the implementation in libjpeg v6b, but not by
   any amount perceptible to human vision (generally in the range of 0.01 to
   0.08 dB gain in PNSR.)
--- When not using the SIMD extensions, libjpeg-turbo uses the more accurate
+
+- When not using the SIMD extensions, libjpeg-turbo uses the more accurate
   (and slightly faster) floating point IDCT algorithm introduced in libjpeg
   v8a as opposed to the algorithm used in libjpeg v6b.  It should be noted,
   however, that this algorithm basically brings the accuracy of the floating
@@ -286,37 +283,36 @@ following reasons:
   numbers on this, the typical difference in PNSR between the two algorithms
   is less than 0.10 dB, whereas changing the quality level by 1 in the upper
   range of the quality scale is typically more like a 1.0 dB difference.)
--- If the floating point algorithms in libjpeg-turbo are not implemented using
+
+- If the floating point algorithms in libjpeg-turbo are not implemented using
   SIMD instructions on a particular platform, then the accuracy of the
   floating point DCT/IDCT can depend on the compiler settings.
 
-While libjpeg-turbo does emulate the libjpeg v8 API/ABI, under the hood, it is
+While libjpeg-turbo does emulate the libjpeg v8 API/ABI, under the hood it is
 still using the same algorithms as libjpeg v6b, so there are several specific
 cases in which libjpeg-turbo cannot be expected to produce the same output as
 libjpeg v8:
 
--- When decompressing using scaling factors of 1/2 and 1/4, because libjpeg v8
+- When decompressing using scaling factors of 1/2 and 1/4, because libjpeg v8
   implements those scaling algorithms differently than libjpeg v6b does, and
   libjpeg-turbo's SIMD extensions are based on the libjpeg v6b behavior.
 
--- When using chrominance subsampling, because libjpeg v8 implements this
+- When using chrominance subsampling, because libjpeg v8 implements this
   with its DCT/IDCT scaling algorithms rather than with a separate
   downsampling/upsampling algorithm.  In our testing, the subsampled/upsampled
   output of libjpeg v8 is less accurate than that of libjpeg v6b for this
   reason.
 
--- When decompressing using a scaling factor > 1 and merged (AKA "non-fancy" or
+- When decompressing using a scaling factor > 1 and merged (AKA "non-fancy" or
   "non-smooth") chrominance upsampling, because libjpeg v8 does not support
   merged upsampling with scaling factors > 1.
 
 
-*******************************************************************************
+Performance Pitfalls
-**     Performance Pitfalls
+====================
-*******************************************************************************
 
-===============
 Restart Markers
-===============
+---------------
 
 The optimized Huffman decoder in libjpeg-turbo does not handle restart markers
 in a way that makes the rest of the libjpeg infrastructure happy, so it is
@@ -327,9 +323,8 @@ libjpeg.  Many consumer packages, such as PhotoShop, use restart markers when
 generating JPEG images, so images generated by those programs will experience
 this issue.
 
-===============================================
 Fast Integer Forward DCT at High Quality Levels
-===============================================
+-----------------------------------------------
 
 The algorithm used by the SIMD-accelerated quantization function cannot produce
 correct results whenever the fast integer forward DCT is used along with a JPEG