From: DRC Date: Tue, 24 Jul 2018 23:36:51 +0000 (-0500) Subject: Fix JPEG spec references per ISO/ITU-T suggestions X-Git-Tag: 2.0.0~3 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=a62895265f425db48c8538bb3f468ddb4961bf0f;p=libjpeg-turbo Fix JPEG spec references per ISO/ITU-T suggestions - When referring to specific clauses, annexes, tables, and figures, a "timed reference" (a reference that includes the year) must be used in order to avoid confusion. - "CCITT" = "ITU-T" - Replace ambiguous "JPEG spec" with the specific document number. --- diff --git a/ChangeLog.md b/ChangeLog.md index bf65be9..8f0d11b 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -366,8 +366,8 @@ specified.) 2x2 luminance sampling factors and 2x1 or 1x2 chrominance sampling factors. This is a non-standard way of specifying 2x subsampling (normally 4:2:2 JPEGs have 2x1 luminance and 1x1 chrominance sampling factors, and 4:4:0 JPEGs have -1x2 luminance and 1x1 chrominance sampling factors), but the JPEG specification -and the libjpeg API both allow it. +1x2 luminance and 1x1 chrominance sampling factors), but the JPEG format and +the libjpeg API both allow it. 7. Fixed an unsigned integer overflow in the libjpeg memory manager, detected by the Clang undefined behavior sanitizer, that could be triggered by diff --git a/jaricom.c b/jaricom.c index 774be9e..215640c 100644 --- a/jaricom.c +++ b/jaricom.c @@ -4,16 +4,16 @@ * This file was part of the Independent JPEG Group's software: * Developed 1997-2009 by Guido Vollbeding. * libjpeg-turbo Modifications: - * Copyright (C) 2015, D. R. Commander. + * Copyright (C) 2015, 2018, D. R. Commander. * For conditions of distribution and use, see the accompanying README.ijg * file. * * This file contains probability estimation tables for common use in * arithmetic entropy encoding and decoding routines. * - * This data represents Table D.2 in the JPEG spec (ISO/IEC IS 10918-1 - * and CCITT Recommendation ITU-T T.81) and Table 24 in the JBIG spec - * (ISO/IEC IS 11544 and CCITT Recommendation ITU-T T.82). + * This data represents Table D.2 in + * Recommendation ITU-T T.81 (1992) | ISO/IEC 10918-1:1994 and Table 24 in + * Recommendation ITU-T T.82 (1993) | ISO/IEC 11544:1993. */ #define JPEG_INTERNALS diff --git a/jcarith.c b/jcarith.c index c55c0ea..b6d093f 100644 --- a/jcarith.c +++ b/jcarith.c @@ -9,11 +9,14 @@ * file. * * This file contains portable arithmetic entropy encoding routines for JPEG - * (implementing the ISO/IEC IS 10918-1 and CCITT Recommendation ITU-T T.81). + * (implementing Recommendation ITU-T T.81 | ISO/IEC 10918-1). * * Both sequential and progressive modes are supported in this single module. * * Suspension is not currently supported in this module. + * + * NOTE: All referenced figures are from + * Recommendation ITU-T T.81 (1992) | ISO/IEC 10918-1:1994. */ #define JPEG_INTERNALS diff --git a/jchuff.c b/jchuff.c index dc5a1f3..939b3e7 100644 --- a/jchuff.c +++ b/jchuff.c @@ -4,7 +4,7 @@ * This file was part of the Independent JPEG Group's software: * Copyright (C) 1991-1997, Thomas G. Lane. * libjpeg-turbo Modifications: - * Copyright (C) 2009-2011, 2014-2016, D. R. Commander. + * Copyright (C) 2009-2011, 2014-2016, 2018, D. R. Commander. * Copyright (C) 2015, Matthieu Darbois. * For conditions of distribution and use, see the accompanying README.ijg * file. @@ -16,6 +16,9 @@ * back up to the start of the current MCU. To do this, we copy state * variables into local working storage, and update them back to the * permanent JPEG objects only upon successful completion of an MCU. + * + * NOTE: All referenced figures are from + * Recommendation ITU-T T.81 (1992) | ISO/IEC 10918-1:1994. */ #define JPEG_INTERNALS @@ -859,13 +862,14 @@ encode_mcu_gather(j_compress_ptr cinfo, JBLOCKROW *MCU_data) * one bits (so that padding bits added at the end of a compressed segment * can't look like a valid code). Because of the canonical ordering of * codewords, this just means that there must be an unused slot in the - * longest codeword length category. Section K.2 of the JPEG spec suggests - * reserving such a slot by pretending that symbol 256 is a valid symbol - * with count 1. In theory that's not optimal; giving it count zero but - * including it in the symbol set anyway should give a better Huffman code. - * But the theoretically better code actually seems to come out worse in - * practice, because it produces more all-ones bytes (which incur stuffed - * zero bytes in the final file). In any case the difference is tiny. + * longest codeword length category. Annex K (Clause K.2) of + * Rec. ITU-T T.81 (1992) | ISO/IEC 10918-1:1994 suggests reserving such a slot + * by pretending that symbol 256 is a valid symbol with count 1. In theory + * that's not optimal; giving it count zero but including it in the symbol set + * anyway should give a better Huffman code. But the theoretically better code + * actually seems to come out worse in practice, because it produces more + * all-ones bytes (which incur stuffed zero bytes in the final file). In any + * case the difference is tiny. * * The JPEG standard requires Huffman codes to be no more than 16 bits long. * If some symbols have a very small but nonzero probability, the Huffman tree @@ -967,13 +971,13 @@ jpeg_gen_optimal_table(j_compress_ptr cinfo, JHUFF_TBL *htbl, long freq[]) /* JPEG doesn't allow symbols with code lengths over 16 bits, so if the pure * Huffman procedure assigned any such lengths, we must adjust the coding. - * Here is what the JPEG spec says about how this next bit works: - * Since symbols are paired for the longest Huffman code, the symbols are - * removed from this length category two at a time. The prefix for the pair - * (which is one bit shorter) is allocated to one of the pair; then, - * skipping the BITS entry for that prefix length, a code word from the next - * shortest nonzero BITS entry is converted into a prefix for two code words - * one bit longer. + * Here is what Rec. ITU-T T.81 | ISO/IEC 10918-1 says about how this next + * bit works: Since symbols are paired for the longest Huffman code, the + * symbols are removed from this length category two at a time. The prefix + * for the pair (which is one bit shorter) is allocated to one of the pair; + * then, skipping the BITS entry for that prefix length, a code word from the + * next shortest nonzero BITS entry is converted into a prefix for two code + * words one bit longer. */ for (i = MAX_CLEN; i > 16; i--) { @@ -999,7 +1003,8 @@ jpeg_gen_optimal_table(j_compress_ptr cinfo, JHUFF_TBL *htbl, long freq[]) /* Return a list of the symbols sorted by code length */ /* It's not real clear to me why we don't need to consider the codelength - * changes made above, but the JPEG spec seems to think this works. + * changes made above, but Rec. ITU-T T.81 | ISO/IEC 10918-1 seems to think + * this works. */ p = 0; for (i = 1; i <= MAX_CLEN; i++) { diff --git a/jcmaster.c b/jcmaster.c index 8516f4b..93b3de6 100644 --- a/jcmaster.c +++ b/jcmaster.c @@ -5,7 +5,7 @@ * Copyright (C) 1991-1997, Thomas G. Lane. * Modified 2003-2010 by Guido Vollbeding. * libjpeg-turbo Modifications: - * Copyright (C) 2010, 2016, D. R. Commander. + * Copyright (C) 2010, 2016, 2018, D. R. Commander. * For conditions of distribution and use, see the accompanying README.ijg * file. * @@ -234,9 +234,9 @@ validate_script(j_compress_ptr cinfo) Al = scanptr->Al; if (cinfo->progressive_mode) { #ifdef C_PROGRESSIVE_SUPPORTED - /* The JPEG spec simply gives the ranges 0..13 for Ah and Al, but that - * seems wrong: the upper bound ought to depend on data precision. - * Perhaps they really meant 0..N+1 for N-bit precision. + /* Rec. ITU-T T.81 | ISO/IEC 10918-1 simply gives the ranges 0..13 for Ah + * and Al, but that seems wrong: the upper bound ought to depend on data + * precision. Perhaps they really meant 0..N+1 for N-bit precision. * Here we allow 0..10 for 8-bit data; Al larger than 10 results in * out-of-range reconstructed DC values during the first DC scan, * which might cause problems for some decoders. diff --git a/jcparam.c b/jcparam.c index bcea927..5bc7174 100644 --- a/jcparam.c +++ b/jcparam.c @@ -5,7 +5,7 @@ * Copyright (C) 1991-1998, Thomas G. Lane. * Modified 2003-2008 by Guido Vollbeding. * libjpeg-turbo Modifications: - * Copyright (C) 2009-2011, D. R. Commander. + * Copyright (C) 2009-2011, 2018, D. R. Commander. * For conditions of distribution and use, see the accompanying README.ijg * file. * @@ -65,7 +65,8 @@ jpeg_add_quant_table(j_compress_ptr cinfo, int which_tbl, } -/* These are the sample quantization tables given in JPEG spec section K.1. +/* These are the sample quantization tables given in Annex K (Clause K.1) of + * Recommendation ITU-T T.81 (1992) | ISO/IEC 10918-1:1994. * The spec says that the values given produce "good" quality, and * when divided by 2, "very good" quality. */ diff --git a/jdarith.c b/jdarith.c index a67995b..6002481 100644 --- a/jdarith.c +++ b/jdarith.c @@ -4,16 +4,19 @@ * This file was part of the Independent JPEG Group's software: * Developed 1997-2015 by Guido Vollbeding. * libjpeg-turbo Modifications: - * Copyright (C) 2015-2017, D. R. Commander. + * Copyright (C) 2015-2018, D. R. Commander. * For conditions of distribution and use, see the accompanying README.ijg * file. * - * This file contains portable arithmetic entropy decoding routines for JPEG - * (implementing the ISO/IEC IS 10918-1 and CCITT Recommendation ITU-T T.81). + * This file contains portable arithmetic entropy encoding routines for JPEG + * (implementing Recommendation ITU-T T.81 | ISO/IEC 10918-1). * * Both sequential and progressive modes are supported in this single module. * * Suspension is not currently supported in this module. + * + * NOTE: All referenced figures are from + * Recommendation ITU-T T.81 (1992) | ISO/IEC 10918-1:1994. */ #define JPEG_INTERNALS diff --git a/jdhuff.c b/jdhuff.c index 84b9b71..95f38e5 100644 --- a/jdhuff.c +++ b/jdhuff.c @@ -4,7 +4,7 @@ * This file was part of the Independent JPEG Group's software: * Copyright (C) 1991-1997, Thomas G. Lane. * libjpeg-turbo Modifications: - * Copyright (C) 2009-2011, 2016, D. R. Commander. + * Copyright (C) 2009-2011, 2016, 2018, D. R. Commander. * For conditions of distribution and use, see the accompanying README.ijg * file. * @@ -15,6 +15,9 @@ * up to the start of the current MCU. To do this, we copy state variables * into local working storage, and update them back to the permanent * storage only upon successful completion of an MCU. + * + * NOTE: All referenced figures are from + * Recommendation ITU-T T.81 (1992) | ISO/IEC 10918-1:1994. */ #define JPEG_INTERNALS @@ -459,7 +462,7 @@ jpeg_huff_decode(bitread_working_state *state, code = GET_BITS(l); /* Collect the rest of the Huffman code one bit at a time. */ - /* This is per Figure F.16 in the JPEG spec. */ + /* This is per Figure F.16. */ while (code > htbl->maxcode[l]) { code <<= 1; diff --git a/jdinput.c b/jdinput.c index fbf8b29..deec618 100644 --- a/jdinput.c +++ b/jdinput.c @@ -4,7 +4,7 @@ * This file was part of the Independent JPEG Group's software: * Copyright (C) 1991-1997, Thomas G. Lane. * libjpeg-turbo Modifications: - * Copyright (C) 2010, 2016, D. R. Commander. + * Copyright (C) 2010, 2016, 2018, D. R. Commander. * Copyright (C) 2015, Google, Inc. * For conditions of distribution and use, see the accompanying README.ijg * file. @@ -234,10 +234,10 @@ per_scan_setup(j_decompress_ptr cinfo) * means that we have to save away the table actually used for each component. * We do this by copying the table at the start of the first scan containing * the component. - * The JPEG spec prohibits the encoder from changing the contents of a Q-table - * slot between scans of a component using that slot. If the encoder does so - * anyway, this decoder will simply use the Q-table values that were current - * at the start of the first scan for the component. + * Rec. ITU-T T.81 | ISO/IEC 10918-1 prohibits the encoder from changing the + * contents of a Q-table slot between scans of a component using that slot. If + * the encoder does so anyway, this decoder will simply use the Q-table values + * that were current at the start of the first scan for the component. * * The decompressor output side looks only at the saved quant tables, * not at the current Q-table slots. diff --git a/jdphuff.c b/jdphuff.c index 2d23177..9e82636 100644 --- a/jdphuff.c +++ b/jdphuff.c @@ -4,7 +4,7 @@ * This file was part of the Independent JPEG Group's software: * Copyright (C) 1995-1997, Thomas G. Lane. * libjpeg-turbo Modifications: - * Copyright (C) 2015-2016, D. R. Commander. + * Copyright (C) 2015-2016, 2018, D. R. Commander. * For conditions of distribution and use, see the accompanying README.ijg * file. * @@ -15,6 +15,9 @@ * up to the start of the current MCU. To do this, we copy state variables * into local working storage, and update them back to the permanent * storage only upon successful completion of an MCU. + * + * NOTE: All referenced figures are from + * Recommendation ITU-T T.81 (1992) | ISO/IEC 10918-1:1994. */ #define JPEG_INTERNALS diff --git a/jmorecfg.h b/jmorecfg.h index 08d1d50..d0b9300 100644 --- a/jmorecfg.h +++ b/jmorecfg.h @@ -5,7 +5,7 @@ * Copyright (C) 1991-1997, Thomas G. Lane. * Modified 1997-2009 by Guido Vollbeding. * libjpeg-turbo Modifications: - * Copyright (C) 2009, 2011, 2014-2015, D. R. Commander. + * Copyright (C) 2009, 2011, 2014-2015, 2018, D. R. Commander. * For conditions of distribution and use, see the accompanying README.ijg * file. * @@ -17,9 +17,9 @@ /* * Maximum number of components (color channels) allowed in JPEG image. - * To meet the letter of the JPEG spec, set this to 255. However, darn - * few applications need more than 4 channels (maybe 5 for CMYK + alpha - * mask). We recommend 10 as a reasonable compromise; use 4 if you are + * To meet the letter of Rec. ITU-T T.81 | ISO/IEC 10918-1, set this to 255. + * However, darn few applications need more than 4 channels (maybe 5 for CMYK + + * alpha mask). We recommend 10 as a reasonable compromise; use 4 if you are * really short on memory. (Each allowed component costs a hundred or so * bytes of storage, whether actually used in an image or not.) */ diff --git a/libjpeg.txt b/libjpeg.txt index 7e2341c..c50cf90 100644 --- a/libjpeg.txt +++ b/libjpeg.txt @@ -3,7 +3,7 @@ USING THE IJG JPEG LIBRARY This file was part of the Independent JPEG Group's software: Copyright (C) 1994-2013, Thomas G. Lane, Guido Vollbeding. libjpeg-turbo Modifications: -Copyright (C) 2010, 2014-2017, D. R. Commander. +Copyright (C) 2010, 2014-2018, D. R. Commander. Copyright (C) 2015, Google, Inc. For conditions of distribution and use, see the accompanying README.ijg file. @@ -388,13 +388,13 @@ to the total image height. In most applications it is convenient to pass just one or a few scanlines at a time. The expected format for the passed data is discussed under "Data formats", above. -Image data should be written in top-to-bottom scanline order. The JPEG spec -contains some weasel wording about how top and bottom are application-defined -terms (a curious interpretation of the English language...) but if you want -your files to be compatible with everyone else's, you WILL use top-to-bottom -order. If the source data must be read in bottom-to-top order, you can use -the JPEG library's virtual array mechanism to invert the data efficiently. -Examples of this can be found in the sample application cjpeg. +Image data should be written in top-to-bottom scanline order. +Rec. ITU-T T.81 | ISO/IEC 10918-1 says, "Applications determine which edges of +a source image are defined as top, bottom, left, and right." However, if you +want your files to be compatible with everyone else's, then top-to-bottom order +must be used. If the source data must be read in bottom-to-top order, then you +can use the JPEG library's virtual array mechanism to invert the data +efficiently. Examples of this can be found in the sample application cjpeg. The library maintains a count of the number of scanlines written so far in the next_scanline field of the JPEG object. Usually you can just use @@ -917,7 +917,8 @@ jpeg_set_quality (j_compress_ptr cinfo, int quality, boolean force_baseline) jpeg_set_linear_quality (j_compress_ptr cinfo, int scale_factor, boolean force_baseline) Same as jpeg_set_quality() except that the generated tables are the - sample tables given in the JPEC spec section K.1, multiplied by the + sample tables given in Annex K (Clause K.1) of + Rec. ITU-T T.81 (1992) | ISO/IEC 10918-1:1994, multiplied by the specified scale factor (which is expressed as a percentage; thus scale_factor = 100 reproduces the spec's tables). Note that larger scale factors give lower quality. This entry point is useful for diff --git a/rdswitch.c b/rdswitch.c index 610346b..c50c33e 100644 --- a/rdswitch.c +++ b/rdswitch.c @@ -4,7 +4,7 @@ * This file was part of the Independent JPEG Group's software: * Copyright (C) 1991-1996, Thomas G. Lane. * libjpeg-turbo Modifications: - * Copyright (C) 2010, D. R. Commander. + * Copyright (C) 2010, 2018, D. R. Commander. * For conditions of distribution and use, see the accompanying README.ijg * file. * @@ -276,7 +276,8 @@ bogus: #if JPEG_LIB_VERSION < 70 -/* These are the sample quantization tables given in JPEG spec section K.1. +/* These are the sample quantization tables given in Annex K (Clause K.1) of + * Recommendation ITU-T T.81 (1992) | ISO/IEC 10918-1:1994. * The spec says that the values given produce "good" quality, and * when divided by 2, "very good" quality. */ diff --git a/structure.txt b/structure.txt index f69c9d8..c0792a3 100644 --- a/structure.txt +++ b/structure.txt @@ -89,12 +89,12 @@ nonetheless, they are useful for viewers. The compressor and decompressor are each divided into two main sections: the JPEG compressor or decompressor proper, and the preprocessing or postprocessing functions. The interface between these two sections is the -image data that the official JPEG spec regards as its input or output: this -data is in the colorspace to be used for compression, and it is downsampled -to the sampling factors to be used. The preprocessing and postprocessing -steps are responsible for converting a normal image representation to or from -this form. (Those few applications that want to deal with YCbCr downsampled -data can skip the preprocessing or postprocessing step.) +image data that Rec. ITU-T T.81 | ISO/IEC 10918-1 regards as its input or +output: this data is in the colorspace to be used for compression, and it is +downsampled to the sampling factors to be used. The preprocessing and +postprocessing steps are responsible for converting a normal image +representation to or from this form. (Those few applications that want to deal +with YCbCr downsampled data can skip the preprocessing or postprocessing step.) Looking more closely, the compressor library contains the following main elements: @@ -141,22 +141,22 @@ allow such merging where appropriate. Note: it is convenient to regard edge expansion (padding to block boundaries) -as a preprocessing/postprocessing function, even though the JPEG spec includes -it in compression/decompression. We do this because downsampling/upsampling -can be simplified a little if they work on padded data: it's not necessary to -have special cases at the right and bottom edges. Therefore the interface -buffer is always an integral number of blocks wide and high, and we expect -compression preprocessing to pad the source data properly. Padding will occur -only to the next block (8-sample) boundary. In an interleaved-scan situation, -additional dummy blocks may be used to fill out MCUs, but the MCU assembly and -disassembly logic will create or discard these blocks internally. (This is -advantageous for speed reasons, since we avoid DCTing the dummy blocks. -It also permits a small reduction in file size, because the compressor can -choose dummy block contents so as to minimize their size in compressed form. -Finally, it makes the interface buffer specification independent of whether -the file is actually interleaved or not.) Applications that wish to deal -directly with the downsampled data must provide similar buffering and padding -for odd-sized images. +as a preprocessing/postprocessing function, even though +Rec. ITU-T T.81 | ISO/IEC 10918-1 includes it in compression/decompression. We +do this because downsampling/upsampling can be simplified a little if they work +on padded data: it's not necessary to have special cases at the right and +bottom edges. Therefore the interface buffer is always an integral number of +blocks wide and high, and we expect compression preprocessing to pad the source +data properly. Padding will occur only to the next block (8-sample) boundary. +In an interleaved-scan situation, additional dummy blocks may be used to fill +out MCUs, but the MCU assembly and disassembly logic will create or discard +these blocks internally. (This is advantageous for speed reasons, since we +avoid DCTing the dummy blocks. It also permits a small reduction in file size, +because the compressor can choose dummy block contents so as to minimize their +size in compressed form. Finally, it makes the interface buffer specification +independent of whether the file is actually interleaved or not.) Applications +that wish to deal directly with the downsampled data must provide similar +buffering and padding for odd-sized images. *** Poor man's object-oriented programming *** diff --git a/wizard.txt b/wizard.txt index ede721e..c57fe38 100644 --- a/wizard.txt +++ b/wizard.txt @@ -43,7 +43,8 @@ appear between numbers. Also, comments can be included: a comment starts with '#' and extends to the end of the line. Here is an example file that duplicates the default quantization tables: - # Quantization tables given in JPEG spec, section K.1 + # Quantization tables given in Annex K (Clause K.1) of + # Recommendation ITU-T T.81 (1992) | ISO/IEC 10918-1:1994. # This is table 0 (the luminance table): 16 11 10 16 24 40 51 61