diff options
Diffstat (limited to 'src/3rdparty/libjpeg/libjpeg.doc')
| -rw-r--r-- | src/3rdparty/libjpeg/libjpeg.doc | 68 |
1 files changed, 34 insertions, 34 deletions
diff --git a/src/3rdparty/libjpeg/libjpeg.doc b/src/3rdparty/libjpeg/libjpeg.doc index 95da39e78..d8fb38759 100644 --- a/src/3rdparty/libjpeg/libjpeg.doc +++ b/src/3rdparty/libjpeg/libjpeg.doc @@ -84,7 +84,7 @@ provides multiple implementations that cover most of the useful tradeoffs, ranging from very-high-quality down to fast-preview operation. On the compression side we have generally not provided low-quality choices, since compression is normally less time-critical. It should be understood that the -low-quality modes may not meet the JPEG standard's accuracy retquirements; +low-quality modes may not meet the JPEG standard's accuracy requirements; nonetheless, they are useful for viewers. A word about functions *not* provided by the library. We handle a subset of @@ -379,7 +379,7 @@ the compression cycle. 5. while (scan lines remain to be written) jpeg_write_scanlines(...); -Now write all the retquired image data by calling jpeg_write_scanlines() +Now write all the required image data by calling jpeg_write_scanlines() one or more times. You can pass one or more scanlines in each call, up 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 @@ -496,7 +496,7 @@ in either of two ways: This will return the object to an idle state, releasing any working memory. jpeg_abort() is allowed at any time after successful object creation. -Note that cleaning up the data destination, if retquired, is your +Note that cleaning up the data destination, if required, is your responsibility; neither of these routines will call term_destination(). (See "Compressed data handling", below, for more about that.) @@ -645,7 +645,7 @@ You will need output_width * output_components JSAMPLEs per scanline in your output buffer, and a total of output_height scanlines will be returned. Note: if you are using the JPEG library's internal memory manager to allocate -data buffers (as djpeg does), then the manager's protocol retquires that you +data buffers (as djpeg does), then the manager's protocol requires that you request large buffers *before* calling jpeg_start_decompress(). This is a little tricky since the output_XXX fields are not normally valid then. You can make them valid by calling jpeg_calc_output_dimensions() after setting the @@ -770,10 +770,10 @@ it will try to grab extended memory for temp files, and that space will NOT be freed automatically. See cjpeg.c or djpeg.c for an example signal handler. It may be worth pointing out that the core JPEG library does not actually -retquire the stdio library: only the default source/destination managers and +require the stdio library: only the default source/destination managers and error handler need it. You can use the library in a stdio-less environment if you replace those modules and use jmemnobs.c (or another memory manager of -your own devising). More info about the minimum system library retquirements +your own devising). More info about the minimum system library requirements may be found in jinclude.h. @@ -785,7 +785,7 @@ Compression parameter selection This section describes all the optional parameters you can set for JPEG compression, as well as the "helper" routines provided to assist in this -task. Proper setting of some parameters retquires detailed understanding +task. Proper setting of some parameters requires detailed understanding of the JPEG standard; if you don't know what a parameter is for, it's best not to mess with it! See REFERENCES in the README file for pointers to more info about JPEG. @@ -897,7 +897,7 @@ int num_components boolean optimize_coding TRUE causes the compressor to compute optimal Huffman coding tables - for the image. This retquires an extra pass over the data and + for the image. This requires an extra pass over the data and therefore costs a good deal of space and time. The default is FALSE, which tells the compressor to use the supplied or default Huffman tables. In most cases optimal tables save only a few percent @@ -1168,7 +1168,7 @@ int rec_outbuf_height Recommended height of scanline buffer. When quantizing colors, output_components is 1, indicating a single color map index per pixel. Otherwise it equals out_color_components. The output arrays -are retquired to be output_width * output_components JSAMPLEs wide. +are required to be output_width * output_components JSAMPLEs wide. rec_outbuf_height is the recommended minimum height (in scanlines) of the buffer passed to jpeg_read_scanlines(). If the buffer is smaller, the @@ -1568,7 +1568,7 @@ regenerated after resumption. Because of the backtracking behavior, a good-size output buffer is essential for efficiency; you don't want the compressor to suspend often. (In fact, an -overly small buffer could lead to infinite looping, if a single MCU retquired +overly small buffer could lead to infinite looping, if a single MCU required more data than would fit in the buffer.) We recommend a buffer of at least several Kbytes. You may want to insert explicit code to ensure that you don't call jpeg_write_scanlines() unless there is a reasonable amount of space in @@ -1624,7 +1624,7 @@ for decent performance; furthermore, you should load a reasonable amount of new data before resuming decompression. (If you loaded, say, only one new byte each time around, you could waste a LOT of cycles.) -The skip_input_data() source manager routine retquires special care in a +The skip_input_data() source manager routine requires special care in a suspension scenario. This routine is NOT granted the ability to suspend the decompressor; it can decrement bytes_in_buffer to zero, but no more. If the requested skip distance exceeds the amount of data currently in the input @@ -1693,7 +1693,7 @@ with the case of skipping not-yet-received data, however. It's much simpler to use only a single buffer; when fill_input_buffer() is called, move any unconsumed data (beyond the current pointer/count) down to the beginning of this buffer and then load new data into the remaining buffer -space. This approach retquires a little more data copying but is far easier +space. This approach requires a little more data copying but is far easier to get right. @@ -1721,7 +1721,7 @@ To perform incremental display, an application needs to use the decoder library's "buffered-image" mode, in which it receives a decoded image multiple times. -Each displayed scan retquires about as much work to decode as a full JPEG +Each displayed scan requires about as much work to decode as a full JPEG image of the same size, so the decoder must be fairly fast in relation to the data transmission rate in order to make incremental display useful. However, it is possible to skip displaying the image and simply add the incoming bits @@ -1791,7 +1791,7 @@ The basic control flow for buffered-image decoding is cinfo.buffered_image = TRUE; /* select buffered-image mode */ jpeg_start_decompress() for (each output pass) { - adjust output decompression parameters if retquired + adjust output decompression parameters if required jpeg_start_output() /* start a new output pass */ for (all scanlines in image) { jpeg_read_scanlines() @@ -1855,14 +1855,14 @@ immediately return JPEG_REACHED_EOI without attempting to read more data.) The library's output processing will automatically call jpeg_consume_input() whenever the output processing overtakes the input; thus, simple lockstep -display retquires no direct calls to jpeg_consume_input(). But by adding +display requires no direct calls to jpeg_consume_input(). But by adding calls to jpeg_consume_input(), you can absorb data in advance of what is being displayed. This has two benefits: * You can limit buildup of unprocessed data in your input buffer. * You can eliminate extra display passes by paying attention to the state of the library's input processing. -The first of these benefits only retquires interspersing calls to +The first of these benefits only requires interspersing calls to jpeg_consume_input() with your display operations and any other processing you may be doing. To avoid wasting cycles due to backtracking, it's best to call jpeg_consume_input() only after a hundred or so new bytes have arrived. @@ -1926,7 +1926,7 @@ something like this: do { absorb any waiting input by calling jpeg_consume_input() final_pass = jpeg_input_complete(&cinfo); - adjust output decompression parameters if retquired + adjust output decompression parameters if required jpeg_start_output(&cinfo, cinfo.input_scan_number); ... jpeg_finish_output() @@ -2029,7 +2029,7 @@ allowed after jpeg_start_decompress() is called: up on smooth gradients until the lowest coefficient bits are sent. * Color quantization mode can be changed under the rules described below. You *cannot* change between full-color and quantized output (because that - would alter the retquired I/O buffer sizes), but you can change which + would alter the required I/O buffer sizes), but you can change which quantization method is used. When generating color-quantized output, changing quantization method is a @@ -2048,9 +2048,9 @@ These methods offer successively better quality and lesser speed. However, only the first method is available for quantizing in non-RGB color spaces. IMPORTANT: because the different quantizer methods have very different -working-storage retquirements, the library retquires you to indicate which +working-storage requirements, the library requires you to indicate which one(s) you intend to use before you call jpeg_start_decompress(). (If we did -not retquire this, the max_memory_to_use setting would be a complete fiction.) +not require this, the max_memory_to_use setting would be a complete fiction.) You do this by setting one or more of these three cinfo fields to TRUE: enable_1pass_quant Fixed color cube colormap enable_external_quant Externally-supplied colormap @@ -2073,7 +2073,7 @@ special rules apply: NOTE: if you want to use the same colormap as was used in the prior pass, you should not do either of these things. This will save some nontrivial switchover costs. -(These retquirements exist because cinfo.colormap will always be non-NULL +(These requirements exist because cinfo.colormap will always be non-NULL after completing a prior output pass, since both the 1-pass and 2-pass quantizers set it to point to their output colormaps. Thus you have to do one of these two things to notify the library that something has changed. @@ -2269,7 +2269,7 @@ into it, as illustrated above. Ditto for Huffman tables, of course.) You might want to read the tables from a tables-only file, rather than hard-wiring them into your application. The jpeg_read_header() call is sufficient to read a tables-only file. You must pass a second parameter of -FALSE to indicate that you do not retquire an image to be present. Thus, the +FALSE to indicate that you do not require an image to be present. Thus, the typical scenario is create JPEG decompression object @@ -2474,7 +2474,7 @@ Raw (downsampled) image data Some applications need to supply already-downsampled image data to the JPEG compressor, or to receive raw downsampled data from the decompressor. The -library supports this retquirement by allowing the application to write or +library supports this requirement by allowing the application to write or read raw data, bypassing the normal preprocessing or postprocessing steps. The interface is different from the standard one and is somewhat harder to use. If your interest is merely in bypassing color conversion, we recommend @@ -2529,7 +2529,7 @@ be exactly that amount (or possibly some multiple of that amount, in future library versions). This is true even on the last call at the bottom of the image; don't forget to pad your data as necessary. -The retquired dimensions of the supplied data can be computed for each +The required dimensions of the supplied data can be computed for each component as cinfo->comp_info[i].width_in_blocks*DCTSIZE samples per row cinfo->comp_info[i].height_in_blocks*DCTSIZE rows in image @@ -2771,10 +2771,10 @@ Use alloc_large instead of alloc_small for anything bigger than a few Kbytes. There are also alloc_sarray and alloc_barray routines that automatically build 2-D sample or block arrays. -The library's minimum space retquirements to process an image depend on the +The library's minimum space requirements to process an image depend on the image's width, but not on its height, because the library ordinarily works with "strip" buffers that are as wide as the image but just a few rows high. -Some operating modes (eg, two-pass color quantization) retquire full-image +Some operating modes (eg, two-pass color quantization) require full-image buffers. Such buffers are treated as "virtual arrays": only the current strip need be in memory, and the rest can be swapped out to a temporary file. @@ -2801,7 +2801,7 @@ If you use the jmemname.c or jmemdos.c memory manager back end, it is important to clean up the JPEG object properly to ensure that the temporary files get deleted. (This is especially crucial with jmemdos.c, where the "temporary files" may be extended-memory segments; if they are not freed, -DOS will retquire a reboot to recover the memory.) Thus, with these memory +DOS will require a reboot to recover the memory.) Thus, with these memory managers, it's a good idea to provide a signal handler that will trap any early exit from your program. The handler should call either jpeg_abort() or jpeg_destroy() for any active JPEG objects. A handler is not needed with @@ -2813,11 +2813,11 @@ tmpfile(). Memory usage ------------ -Working memory retquirements while performing compression or decompression +Working memory requirements while performing compression or decompression depend on image dimensions, image characteristics (such as colorspace and JPEG process), and operating mode (application-selected options). -As of v6b, the decompressor retquires: +As of v6b, the decompressor requires: 1. About 24K in more-or-less-fixed-size data. This varies a bit depending on operating mode and image characteristics (particularly color vs. grayscale), but it doesn't depend on image dimensions. @@ -2828,7 +2828,7 @@ As of v6b, the decompressor retquires: 3. A full-image DCT coefficient buffer is needed to decode a multi-scan JPEG file (including progressive JPEGs), or whenever you select buffered-image mode. This takes 2 bytes/coefficient. At typical 2x2 sampling, that's - 3 bytes per pixel for a color image. Worst case (1x1 sampling) retquires + 3 bytes per pixel for a color image. Worst case (1x1 sampling) requires 6 bytes/pixel. For grayscale, figure 2 bytes/pixel. 4. To perform 2-pass color quantization, the decompressor also needs a 128K color lookup table and a full-image pixel buffer (3 bytes/pixel). @@ -2839,7 +2839,7 @@ The above figures are valid for 8-bit JPEG data precision and a machine with 32-bit ints. For 12-bit JPEG data, double the size of the strip buffers and quantization pixel buffer. The "fixed-size" data will be somewhat smaller with 16-bit ints, larger with 64-bit ints. Also, CMYK or other unusual -color spaces will retquire different amounts of space. +color spaces will require different amounts of space. The full-image coefficient and pixel buffers, if needed at all, do not have to be fully RAM resident; you can have the library use temporary @@ -2847,7 +2847,7 @@ files instead when the total memory usage would exceed a limit you set. (But if your OS supports virtual memory, it's probably better to just use jmemnobs and let the OS do the swapping.) -The compressor's memory retquirements are similar, except that it has no need +The compressor's memory requirements are similar, except that it has no need for color quantization. Also, it needs a full-image DCT coefficient buffer if Huffman-table optimization is asked for, even if progressive mode is not requested. @@ -2928,7 +2928,7 @@ distributed, we make the assumptions that short is at least 16 bits wide int is at least 16 bits wide long is at least 32 bits wide -(These are the minimum retquirements of the ANSI C standard.) Wider types will +(These are the minimum requirements of the ANSI C standard.) Wider types will work fine, although memory may be used inefficiently if char is much larger than 8 bits or short is much bigger than 16 bits. The code should work equally well with 16- or 32-bit ints. @@ -2996,7 +2996,7 @@ save a JPEG object between compression or decompression operations. Far data space may also be a tight resource when you are dealing with large images. The most memory-intensive case is decompression with two-pass color quantization, or single-pass quantization to an externally supplied color -map. This retquires a 128Kb color lookup table plus strip buffers amounting +map. This requires a 128Kb color lookup table plus strip buffers amounting to about 40 bytes per column for typical sampling ratios (eg, about 25600 bytes for a 640-pixel-wide image). You may not be able to process wide images if you have large data structures of your own. |