Lines Matching +full:dozen +full:- +full:test +full:- +full:rules
4 Copyright (C) 1994-2013, Thomas G. Lane, Guido Vollbeding.
5 libjpeg-turbo Modifications:
6 Copyright (C) 2010, 2014-2018, 2020, 2022, D. R. Commander.
22 features while trying to minimize application-interface changes. We have
28 -----------------
47 Buffered-image mode
56 Library compile-time options
68 ---------------------------------
70 The IJG JPEG library provides C code to read and write JPEG-compressed image
88 ranging from very-high-quality down to fast-preview operation. On the
89 compression side we have generally not provided low-quality choices, since
90 compression is normally less time-critical. It should be understood that the
91 low-quality modes may not meet the JPEG standard's accuracy requirements;
95 the ISO JPEG standard; most baseline, extended-sequential, and progressive
102 We support both 8- and 12-bit data precision, but this is a compile-time
103 choice rather than a run-time choice; hence it is difficult to use both
106 By itself, the library handles only interchange JPEG datastreams --- in
114 ------------------------
129 or finishing compression of an image; the same object can be re-used for a
130 series of image compression operations. This makes it easy to re-use the
131 same parameter settings for a sequence of images. Re-use of a JPEG object
136 in-memory buffers. If the application is doing file-to-file compression,
163 into in-memory buffers passed to jpeg_read_scanlines().
178 Both compression and decompression can be done in an incremental memory-to-
187 ------------
201 There is no provision for colormapped input. JPEG files are always full-color
203 feed in a colormapped image by expanding it to full-color format. However
210 example, R,G,B,R,G,B,R,G,B,... for 24-bit RGB color. Each scanline is an
211 array of data type JSAMPLE --- which is typically "unsigned char", unless
216 A 2-D array of pixels is formed by making a list of pointers to the starts of
218 if you process just one scanline at a time, you must make a one-element
224 processed top-to-bottom. You can process an entire image in one call if you
230 data that's only 6 bits/channel, you should left-justify each value in a
233 (See "Library compile-time options", later.)
238 colormapped. But you can ask the decompressor to perform on-the-fly color
242 a 2-D JSAMPARRAY in which each row holds the values of one color component,
246 (ie, at most 256 colors for an 8-bit JPEG library).
250 -------------------
309 output file unchanged. On non-Unix systems the stdio library may perform
350 Typical code for a 24-bit RGB source image is
391 Image data should be written in top-to-bottom scanline order.
392 Rec. ITU-T T.81 | ISO/IEC 10918-1 says, "Applications determine which edges of
394 want your files to be compatible with everyone else's, then top-to-bottom order
395 must be used. If the source data must be read in bottom-to-top order, then you
401 this variable as the loop counter, so that the loop test looks like
405 example.txt shows the following code for the case of a full-size 2-D source
406 array containing 3-byte RGB pixels:
446 If you have requested a multi-pass operating mode, such as Huffman code
472 works for either compression or decompression objects --- this may be more
479 it is your responsibility --- jpeg_destroy() won't. Ditto for the error
494 legitimate at any point after calling jpeg_create_compress() --- in fact,
497 * If you want to re-use the JPEG object, call jpeg_abort_compress(), or call
513 ---------------------
556 On non-Unix systems the stdio library may perform newline translation or
582 * A suspending data source is used --- in that case jpeg_read_header()
585 * Abbreviated JPEG files are to be processed --- see the section on
624 If you have requested a multi-pass operating mode, such as 2-pass color
627 to complete. With a single-scan (non progressive) JPEG file and default
669 Image data is returned in top-to-bottom scanline order. If you must write
670 out the image in bottom-to-top order, you can use the JPEG library's virtual
676 this variable as the loop counter, so that the loop test looks like
677 "while (cinfo.output_scanline < cinfo.output_height)". (Note that the test
736 ---------------------------
738 Partial image decompression is convenient for performance-critical applications
740 the whole thing. It it also useful in memory-constrained environments (such as
753 behavior. Two-pass color quantization is also not supported by this function.
754 Calling jpeg_skip_scanlines() with two-pass color quantization enabled will
805 After calling this function, cinfo->output_width will be set to the adjusted
809 The output image from a partial-width decompression will be identical to the
814 neighboring pixels.) When performing a partial-width decompression, these
823 -----------------------------------------------
828 size_t. On ANSI-conforming systems, including <stdio.h> is sufficient; on
839 is to prepare a library file ("libjpeg.a", or a corresponding name on non-Unix
842 included from the library, unless your linker is hopelessly brain-damaged.
847 error handler need it. You can use the library in a stdio-less environment
857 -------------------------------
882 and sets other color-space-dependent parameters appropriately. See
884 parameters, including all per-component parameters, are set by this
889 Selects an appropriate JPEG colorspace based on cinfo->in_color_space,
892 just the colorspace-dependent JPEG parameters.
897 recommended by IJG (cjpeg's "-quality" switch uses this routine).
905 is capable of reading the non-baseline files generated at low quality
912 Rec. ITU-T T.81 (1992) | ISO/IEC 10918-1:1994, multiplied by the
917 recommend linear scaling as a user-visible quality scale otherwise.
921 Converts a value on the IJG-recommended quality scale to a linear
923 in future releases --- IJG may choose to adopt a scaling method that
944 "#if JPEG_LIB_VERSION >= 61" is the right test.
947 Generates a default scan script for writing a progressive-JPEG file.
963 JDCT_FLOAT: floating-point method [legacy feature]
967 the compression time for a 1-megapixel JPEG image on a mainstream PC
969 performance benefits. On modern CPUs running libjpeg-turbo, however,
970 the compression time for a 1-megapixel JPEG image is measured in
972 less noticeable. On modern x86/x86-64 CPUs that support AVX2
974 other types of CPUs, JDCT_IFAST is generally about 5-15% faster than
981 JDCT_IFAST incurs generally about a 1-3 dB loss in PSNR relative to
986 libjpeg-turbo, JDCT_IFAST is not fully accelerated for quality levels
1026 single-scan sequential JPEG file. If not NULL, scan_info points to
1036 If non-zero, the input image is smoothed; the value should be 1 for
1042 jpeg_set_colorspace() set this TRUE if a JFIF-legal JPEG color space
1065 you probably shouldn't change the default settings at all --- the
1079 Linear quantization scaling factors (0-100, default 100)
1085 cjpeg -quality 90,70:
1090 cinfo->q_scale_factor[0] = jpeg_quality_scaling(90);
1092 cinfo->q_scale_factor[1] = jpeg_quality_scaling(70);
1101 cinfo->comp_info[0].v_samp_factor = 1;
1102 cinfo->comp_info[0].h_samp_factor = 1;
1127 Per-component parameters are stored in the struct cinfo.comp_info[i] for
1134 The one-byte identifier code to be recorded in the JPEG file for
1142 factors indicate a higher-resolution component; many people find
1163 ---------------------------------
1173 a poorer-quality image. The defaults select the highest quality (slowest)
1223 meaning that full-color output will be delivered.
1228 Maximum number of colors to use in generating a library-supplied color
1234 map for the image. This usually looks a lot better than the one-size-
1235 fits-all colormap that is used otherwise. Default is TRUE. Ignored
1242 JDITHER_FS Floyd-Steinberg dither: slow, high quality
1244 only in the single-pass, standard-colormap case. If you ask for
1246 an external color map, you'll get F-S dithering.)
1250 can supply a color map by setting colormap non-NULL and setting
1254 only accepted for 3-component output color spaces.]
1257 The color map, represented as a 2-D pixel array of out_color_components
1272 JDCT_FLOAT: floating-point method [legacy feature]
1276 the decompression time for a 1-megapixel JPEG image on a mainstream PC
1278 performance benefits. On modern CPUs running libjpeg-turbo, however,
1279 the decompression time for a 1-megapixel JPEG image is measured in
1281 less noticeable. On modern x86/x86-64 CPUs that support AVX2
1283 other types of CPUs, JDCT_IFAST is generally about 5-15% faster than
1292 about a 4-6 dB loss in PSNR relative to JDCT_ISLOW, but this can be
1315 when using buffered-image mode for progressive images.
1320 These are significant only in buffered-image mode, which is
1346 copying. In high-quality modes, rec_outbuf_height is always 1, but some
1347 faster, lower-quality modes set it to larger values (typically 2 to 4).
1348 If you are going to ask for a high-speed processing mode, you may as well
1355 --------------------
1360 existing de-facto JPEG file format standards specify YCbCr or grayscale data
1384 The de-facto file format standards (JFIF and Adobe) specify APPn markers that
1387 one of the ones supported by the de-facto standards. jpeg_set_colorspace()
1390 For example, if you are writing some random 3-component color space without
1393 APPn marker of your own devising to identify the colorspace --- see "Special
1397 luminance-quality compression parameters for all color components. You may
1419 The two-pass color quantizer, jquant2.c, is specialized to handle RGB data
1421 the code if you want to use it for non-RGB output color spaces. Note that
1422 jquant2.c is used to map to an application-supplied colormap as well as for
1423 the normal two-pass colormap selection process.
1431 Photoshop versions prior to 3.0 write EPS files containing JPEG-encoded CMYK
1432 data in the same inverted-YCCK representation used in bare JPEG files, but
1435 EPS/JPEG files, and will omit the PS-level inversion. (But the data
1442 --------------
1469 jpeg_decompress_struct; if you need to tell which, test the is_decompressor
1485 generate the error message has been stored in cinfo->err; call
1499 stored in cinfo->err. This method is called by output_message. Few
1507 would be to abort on warnings. msg_level is -1 for warnings,
1514 by the field err->jpeg_message_table. The messages are numbered from 0 to
1515 err->last_jpeg_message, and it is these code numbers that are used in the
1522 handled by the same mechanism. The error handler supports a second "add-on"
1524 err->addon_message_table and the message numbers err->first_addon_message and
1525 err->last_addon_message. If you number the addon messages beginning at 1000
1526 or so, you won't have to worry about conflicts with the library's built-in
1532 WARNMSn(...) for corrupt-data warnings
1544 ----------------------------------------------------------
1557 one-character buffer to force the manager to be invoked for each byte, but
1561 data in memory. In this case the buffer-reload procedure will be invoked
1568 source and destination modules to transcribe the work arrays into 8-bit units
1602 Terminate destination --- called by jpeg_finish_compress() after all
1613 the JPEG compression object. This can be done in-line in your setup code if
1658 A zero or negative skip count should be treated as a no-op.
1666 up in the input data stream, or if you have a-priori knowledge about
1673 Terminate source --- called by jpeg_finish_decompress() after all
1674 data has been read. Often a no-op.
1680 is the best course of action --- this will allow the decompressor to output
1690 decompression object. This can be done in-line in your setup code if you
1699 --------------
1701 Some applications need to use the JPEG library as an incremental memory-to-
1710 eliminate response-time problems in single-threaded applications. If you
1712 a real multi-tasking capability.
1718 fill_input_buffer() routine is a no-op, merely returning FALSE to indicate
1742 Because of the backtracking behavior, a good-size output buffer is essential
1761 current implementation, half a dozen bytes should suffice for this, but
1766 This means you cannot use suspension with multi-pass operating modes, namely
1767 Huffman code optimization and multiple-scan output. Those modes write the
1793 to be re-read upon resumption. In most implementations, you'll need to shift
1795 it. Again, this behavior means that a several-Kbyte work buffer is essential
1810 common case where a non-suspending source manager is used.)
1813 and insert dummy EOI markers just as a non-suspending data source manager
1818 though it had read more data in a non-suspending situation.
1827 damaged marker length counts, you may wish to insert a test in your
1829 the decoder has suspended without consuming any data --- otherwise, if this
1831 provide this test since it has no idea whether "the buffer is full", or
1832 even whether there is a fixed-size input buffer.)
1842 Multiple-buffer management:
1864 with the case of skipping not-yet-received data, however.
1874 ------------------------
1878 slow communications link, a decoder can generate a low-quality image very
1894 library's "buffered-image" mode, in which it receives a decoded image
1907 higher-quality display cycle can be performed from the buffered data after
1912 To create a progressive JPEG file (or a multiple-scan sequential JPEG file),
1917 applications that don't want to get involved in the nitty-gritty of
1924 multiple-scan output cannot be created with a suspending data destination
1932 When buffered-image mode is not used, the decoder library will read all of
1933 a multi-scan file during jpeg_start_decompress(), so that it can provide a
1934 final decoded image. (Here "multi-scan" means either progressive or
1935 multi-scan sequential.) This makes multi-scan files transparent to the
1941 buffered-image mode. This is described in the next section.
1944 Buffered-image mode
1945 -------------------
1947 In buffered-image mode, the library stores the partially decoded image in a
1958 The basic control flow for buffered-image decoding is
1964 cinfo.buffered_image = TRUE; /* select buffered-image mode */
1986 and the start-output call should read
1993 advances to the next scan or end-of-image marker (hence input_scan_number
2001 sequence. For example, a useful technique is to use fast one-pass color
2003 a final display pass using two-pass quantization for highest quality. This
2008 until after it is read, so a post-input display pass is the best approach if
2043 library currently is not thread-safe. You must not call jpeg_consume_input()
2052 consumed by the input processor. You can ensure that this is up-to-date by
2070 jpeg_start_decompress() does when you don't select buffered-image mode.)
2085 paying attention to the input, the effect seen on-screen is that the lower
2108 arrangement makes it simple to use higher-quality decoding parameters
2122 the final output pass; rather, what you want to test is whether the output
2146 higher-quality final pass is to be done, it should be started (aborting any
2158 In buffered-image mode, jpeg_start_decompress() never performs input and
2160 buffered-image mode must be prepared for suspension returns from these
2162 * jpeg_start_output() performs input only if you request 2-pass quantization
2176 and repeat the call. Applications that use non-suspending data sources need
2181 buffered-image mode. The decoder library currently supports only very
2190 Floyd-Steinberg dither for the final pass. Caution: changing dither mode
2194 case would result in an out-of-memory failure.
2197 During the first DC-only scan, block smoothing provides a very "fuzzy" look
2200 during later stages, especially when decoding a successive-approximation
2203 * Color quantization mode can be changed under the rules described below.
2204 You *cannot* change between full-color and quantized output (because that
2208 When generating color-quantized output, changing quantization method is a
2209 very useful way of switching between high-speed and high-quality display.
2211 1. Single-pass quantization to a fixed color cube.
2213 2. Single-pass quantization to an application-supplied colormap.
2216 3. Two-pass quantization to a colormap chosen specifically for the image.
2221 only the first method is available for quantizing in non-RGB color spaces.
2224 working-storage requirements, the library requires you to indicate which
2229 enable_external_quant Externally-supplied colormap
2230 enable_2pass_quant Two-pass custom colormap
2239 special rules apply:
2240 1. You must explicitly set cinfo.colormap to NULL when switching to 1-pass
2241 or 2-pass mode from a different mode, or when you want the 2-pass
2242 quantizer to be re-run to generate a new colormap.
2249 (These requirements exist because cinfo.colormap will always be non-NULL
2250 after completing a prior output pass, since both the 1-pass and 2-pass
2256 Note that in buffered-image mode, the library generates any requested colormap
2259 When using two-pass quantization, jpeg_start_output() makes a pass over the
2267 conditions. The combination of 2-pass quantization and a not-yet-fully-read
2271 Application authors who support buffered-image mode may be tempted to use it
2272 for all JPEG images, even single-scan ones. This will work, but it is
2273 inefficient: there is no need to create an image-sized coefficient buffer for
2274 single-scan images. Requesting buffered-image mode for such an image wastes
2277 maximum performance on baseline JPEG files, you should use buffered-image
2300 tables-only file this way, jpeg_consume_input() will return JPEG_REACHED_EOI
2304 using buffered-image mode, but in that case it's basically a no-op after the
2309 -------------------------------------------
2327 * "Abbreviated table specification" (henceforth "tables-only") datastreams
2331 tables-only file. A variant scheme uses a series of images in which the first
2344 tables-only datastreams and abbreviated images. In both compression and
2353 header-writing process emits the table and sets sent_table = TRUE unless it is
2370 To create a tables-only file, perform the same parameter setup that you
2378 A sure-fire way to create matching tables-only and abbreviated image files
2383 set destination to tables-only file
2402 tables-only file readable by the application. This can be done by setting up
2419 quant_ptr->quantval[i] = Qtable[i];
2429 huff_ptr->bits[i] = counts[i];
2432 /* symbols[] is the list of Huffman symbols, in code-length order */
2433 huff_ptr->huffval[i] = symbols[i];
2442 You might want to read the tables from a tables-only file, rather than
2443 hard-wiring them into your application. The jpeg_read_header() call is
2444 sufficient to read a tables-only file. You must pass a second parameter of
2449 set source to tables-only file
2464 image for which you haven't loaded the missing tables; the missing-table check
2486 ---------------
2490 "APP0" through "APP15" (application) to hold application-specific data.
2492 COM markers are fairly widely used to hold user-supplied text. The JFIF file
2498 If you wish to store user-supplied text, we recommend you use COM markers
2499 and place readable 7-bit ASCII text in them. Newline conventions are not
2500 standardized --- expect to find LF (Unix style), CR/LF (DOS style), or CR
2503 containing non-ASCII junk. (But yours should not be one of them.)
2505 For program-supplied data, use an APPn marker, and be sure to begin it with an
2558 on-the-fly as they are read.
2578 routine 17 times, for COM and APP0-APP15.) If the incoming marker is longer
2587 following the cinfo->marker_list pointer chain. All the special markers in
2612 16-bit environment, the maximum length limit may be constrained to less than
2617 If you want to supply your own marker-reading routine, you do it by calling
2622 in cinfo->unread_marker. At the time of call, the marker proper has been
2638 --- if you call one it overrides any previous call to the other, for the
2646 ------------
2684 ----------------------------
2686 Some applications need to supply already-downsampled image data to the JPEG
2703 namely a JSAMPIMAGE array. This is an array of pointers to two-dimensional
2704 arrays, each of type JSAMPARRAY. Each 2-D array holds the values for one
2719 * Set cinfo->raw_data_in to TRUE. (It is set FALSE by jpeg_set_defaults().)
2721 * Ensure jpeg_color_space is correct --- an explicit jpeg_set_colorspace()
2725 * Ensure the sampling factors, cinfo->comp_info[i].h_samp_factor and
2726 cinfo->comp_info[i].v_samp_factor, are correct. Since these indicate the
2745 cinfo->comp_info[i].width_in_blocks*DCTSIZE samples per row
2746 cinfo->comp_info[i].height_in_blocks*DCTSIZE rows in image
2754 cinfo->comp_info[0].h_samp_factor = 2 for Y
2755 cinfo->comp_info[0].v_samp_factor = 2
2756 cinfo->comp_info[1].h_samp_factor = 1 for Cb
2757 cinfo->comp_info[1].v_samp_factor = 1
2758 cinfo->comp_info[2].h_samp_factor = 1 for Cr
2759 cinfo->comp_info[2].v_samp_factor = 1
2760 and suppose that the nominal image dimensions (cinfo->image_width and
2761 cinfo->image_height) are 101x101 pixels. Then jpeg_start_compress() will
2774 Output suspension is supported with raw-data compression: if the data
2786 To obtain raw data output, set cinfo->raw_data_out = TRUE before
2794 the same as for raw-data compression). The buffer you pass must be large
2795 enough to hold the actual data plus padding to DCT-block boundaries. As with
2798 above example of computing buffer dimensions for raw-data compression is
2801 Input suspension is supported with raw-data decompression: if the data source
2803 buffered-image mode to read raw data in multiple passes.
2807 ---------------------------------
2813 multi-strip or multi-tile TIFF/JPEG file into a single JPEG datastream, etc.
2818 entire image into a set of virtual coefficient-block arrays, one array per
2819 component. The return value is a pointer to an array of virtual-array
2828 DCT blocks containing real data; any entirely-dummy blocks added to fill out
2840 NULL if it is forced to suspend; a non-NULL return value indicates successful
2841 completion. You need not test for a NULL return value when using a
2842 non-suspending data source.
2845 decoder's coefficient arrays during a normal decode cycle in buffered-image
2847 image and then re-encoding it without loss. To do this, decode in buffered-
2864 * Destroy or re-use compression object
2869 jpeg_write_coefficients() is called. A side-effect of
2884 JPEG input file --- that is, it should be awaiting jpeg_finish_decompress().
2896 -------------------
2899 often. The typical use of this feature is to produce a percent-done bar or
2901 Although you do get control back frequently during the data-transferring pass
2907 You can define a progress-monitor routine which will be called periodically
2916 the callback mechanism for time-critical tasks like mouse tracking, you could
2919 To establish a progress-monitor callback, create a struct jpeg_progress_mgr,
2921 and set cinfo->progress to point to the struct. The callback will be called
2922 whenever cinfo->progress is non-NULL. (This pointer is set to NULL by
2940 --------------------------------------------
2946 advance. The computed fraction-of-work-done may jump suddenly (if the library
2950 When using the decompressor's buffered-image mode, the progress monitor work
2963 -----------------
2965 This section covers some key facts about the JPEG library's built-in memory
2979 ptr = (*cinfo->mem->alloc_small) ((j_common_ptr)cinfo, JPOOL_IMAGE, size);
2983 build 2-D sample or block arrays.
2988 Some operating modes (eg, two-pass color quantization) require full-image
2992 When using temporary files, the library will make the in-memory buffers for
2994 Your application can set this limit by setting cinfo->mem->max_memory_to_use
2996 the buffers, so the max-memory setting is effective only if it is bigger than
3005 will never be used. The back end provided in libjpeg-turbo (jmemnobs.c) simply
3007 memory exceeds the limit specified in cinfo->mem->max_memory_to_use.
3011 ------------
3015 JPEG process), and operating mode (application-selected options).
3018 1. About 24K in more-or-less-fixed-size data. This varies a bit depending
3025 3. A full-image DCT coefficient buffer is needed to decode a multi-scan JPEG
3026 file (including progressive JPEGs), or whenever you select buffered-image
3030 4. To perform 2-pass color quantization, the decompressor also needs a
3031 128K color lookup table and a full-image pixel buffer (3 bytes/pixel).
3035 The above figures are valid for 8-bit JPEG data precision and a machine with
3036 32-bit ints. For 12-bit JPEG data, double the size of the strip buffers and
3037 quantization pixel buffer. The "fixed-size" data will be somewhat smaller
3038 with 16-bit ints, larger with 64-bit ints. Also, CMYK or other unusual
3041 The full-image coefficient and pixel buffers, if needed at all, do not
3048 for color quantization. Also, it needs a full-image DCT coefficient buffer
3049 if Huffman-table optimization is asked for, even if progressive mode is not
3056 Library compile-time options
3057 ----------------------------
3059 A number of compile-time options are available by modifying jmorecfg.h.
3061 The JPEG standard provides for both the baseline 8-bit DCT process and
3062 a 12-bit DCT process. The IJG code supports 12-bit lossy JPEG if you define
3065 The sample applications cjpeg and djpeg can support 12-bit mode only for PPM
3067 12-bit cjpeg or djpeg. At present, a 12-bit library can handle *only* 12-bit
3070 Note that a 12-bit library always compresses in Huffman optimization mode,
3072 default Huffman tables only cover 8-bit data. If you need to output 12-bit
3075 quality-scaling code has been developed for 8-bit use, and probably doesn't
3076 generate especially good tables for 12-bit.
3105 --------------------------
3114 system include file setups, and some not-so-popular ones too.
3125 equally well with 16- or 32-bit ints.
3139 dependencies in file-header manipulation; so does cjpeg's select_file_type()
3144 handler, all of which are application-replaceable. (cjpeg/djpeg are more