Doc: Lossless JPEG clarifications

- Clarify that lossless JPEG is slower than and doesn't compress as well
  as lossy JPEG.  (That should be obvious, because "lossy" literally
  means that data is thrown away.)
- Re-generate TurboJPEG C API documentation using Doxygen 1.9.8.
- Clarify that setting the data_precision field in jpeg_compress_struct
  to 16 requires lossless mode.
- Explain what the predictor selection value actually does.  (Refer to
  Recommendation ITU-T T.81 (1992) | ISO/IEC 10918-1:1994, Section
  H.1.2.1.)
This commit is contained in:
DRC
2023-12-14 13:18:20 -05:00
parent abeca1f0cc
commit be96fa0a40
124 changed files with 3775 additions and 2679 deletions

View File

@@ -621,9 +621,11 @@ enum TJPARAM {
* lossless/predictive.
*
* In most cases, compressing and decompressing lossless JPEG images is
* considerably slower than compressing and decompressing lossy JPEG images.
* Also note that the following features are not available with lossless JPEG
* images:
* considerably slower than compressing and decompressing lossy JPEG images,
* and lossless JPEG images are much larger than lossy JPEG images. Thus,
* lossless JPEG images are typically used only for applications that require
* mathematically lossless compression. Also note that the following
* features are not available with lossless JPEG images:
* - Colorspace conversion (lossless JPEG images always use #TJCS_RGB,
* #TJCS_GRAY, or #TJCS_CMYK, depending on the pixel format of the source
* image)
@@ -645,6 +647,30 @@ enum TJPARAM {
* **Value**
* - `1`-`7` *[default for compression: `1`]*
*
* Lossless JPEG compression shares no algorithms with lossy JPEG
* compression. Instead, it uses differential pulse-code modulation (DPCM),
* an algorithm whereby each sample is encoded as the difference between the
* sample's value and a "predictor", which is based on the values of
* neighboring samples. If Ra is the sample immediately to the left of the
* current sample, Rb is the sample immediately above the current sample, and
* Rc is the sample diagonally to the left and above the current sample, then
* the relationship between the predictor selection value and the predictor
* is as follows:
*
* PSV | Predictor
* ----|----------
* 1 | Ra
* 2 | Rb
* 3 | Rc
* 4 | Ra + Rb Rc
* 5 | Ra + (Rb Rc) / 2
* 6 | Rb + (Ra Rc) / 2
* 7 | (Ra + Rb) / 2
*
* Predictors 1-3 are 1-dimensional predictors, whereas Predictors 4-7 are
* 2-dimensional predictors. The best predictor for a particular image
* depends on the image.
*
* @see #TJPARAM_LOSSLESS
*/
TJPARAM_LOSSLESSPSV,