The following conventions concern the returned errors:
If the program has encountered a nonstandard situation that does not prevent retrieval of some data from a file, it sends a signal by setting the corresponding bit in imgdata.process_warnings. The possible types of warnings are listed and deciphered here.
Thread safety is ensured if a LibRaw object is created and used within one thread. At the same time, the number of threads (each with its own LibRaw object) is not limited in any way (except by memory requirements).
If a LibRaw object is created in one execution thread and used in another, external synchronization is necessary.
For building in the multithreaded mode, the application should be compiled with the preprocessor flag -DLIBRAW_THREADS and compiler key -pthread (Unix/gcc) and linked with the libraw_r.a library. In this mode (and with this preprocessor flag), the local data of the decoder is stored in fields of the LibRaw object rather than in common static memory. In this case, a separate control thread will work somewhat slower but overall gain will be achieved if several parallel threads are used.
If the program uses one instance of LibRaw without simultaneous calls of its methods from different threads, then linking with the multithreaded version of the library (as well as the aforementioned flags used in building) is not obligatory.
Exception situations within LibRaw are handled using the C++ exception mechanism. All exceptions are caught inside the library functions and should not penetrate outside.
Memory is allocated/freed using functions malloc(calloc)/free rather than new/delete.
No specific libraries (STL, Boost, smart pointers) are used.
If C API is used, references to C++ calls new/delete still remain, and so linking with libstdc++(Unix)/....(Windows) is necessary.
Most data fields of structure LibRaw::imgdata.params affect only data postprocessing, but there are some exceptions, which have been inherited by the current version of LibRaw from dcraw source texts (these dependences will be gradually removed).
imgdata.sizes.flip = imgdata.params.user_flip
is
performed at the open_file() stage.
An instance of the LibRaw class has its own size about 100 Kb; if constructions like LibRaw imageProcessor;
are used, this memory is stack-allocated.
Methods of class LibRaw (and C API calls) may allocate up to 130-140 Kb of data on the stack (to place auto variables) during their work.
Thus, the work of one LibRaw instance may require about 250 Kb of stack memory. This is not a problem for most contemporary architectures. However, when working in a multithreaded environment, one should not forget to allocate a sufficient amount of memory for the thread stack.
In the case of dynamic allocation (LibRaw *iProcessor = new LibRaw;
), the requirements to stack memory will decrease
(by 100 Kb, which is the size of a class instance). If C API is used, the LibRaw instance is allocated dynamically.
LibRaw keeps record of all allocated dynamic memory blocks; in the case of an exceptional situation (fatal error), they are all freed. The code for keeping this record is fairly primitive and not designed to consider allocation of many blocks (in the normal situation, allocation takes place from 2 to 6 times during file processing); this fact should be taken into account by developers trying to add new methods to LibRaw.
LibRaw uses dynamic memory
To simplify further processing, memory for the extracted RAW data is allocated with a fourfold (for Bayer sensor cameras) excess: for each
pixel, four 16-bit components are available (three of them will be zero after RAW unpacking). Thus, one can perform debayer and
other postprocessing actions directly in the same buffer as the one used for data extraction, but the required amount of memory becomes
four times higher.
Hence, the size of memory for the image buffer is 6-10 times greater than the size of the source RAW file.
It is quite likely that allocation of this buffer in next versions of LibRaw will be more economical, under the condition that
postprocessing calls inherited from dcraw will not be used..
The buffer for the decoded image is allocated upon calling unpack() and freed upon calling recycle().
Memory for the thumbmail is allocated upon calling unpack_thumb() and freed upon calling recycle(). The size of the allocated buffer is precisely adjusted to the thumbnail size, i.e., up to several Mb.
Memory for the ICC profile is allocated upon calling unpack_profile() and freed upon calling recycle(). The size of the allocated buffer is precisely adjusted to the ICC profile size, i.e., up to several hundred Kb.
Memory for temporary buffer needed during RAW data unpacking may be allocated during the work of unpack() and freed before completion of this function. The sizes of the allocated buffers are small, up to tens of Kb.
During image postprocessing (inherited from dcraw), memory for the histogram (128 Kb) is allocated. This memory is allocated upon calling dcraw_document_mode_processing() and dcraw_process() and freed upon calling recycle().
In addition, during the work of dcraw_process() and during the usage of some available possibilities, like
a temporary buffer with the size equal to the size of the resultant image (6-8 bytes per pixel for various processing stages)
will be allocated. As soon as the intermediate substage of processing is completed, the buffer with the previous copy
of the image will be freed.
If postprocessing is not used, then temporary buffers are not allocated.
Upon calling dcraw_ppm_tiff_writer(), memory for a single row of the output image is allocated. The allocated memory is freed before the end of this call.
For faster reading, the entire file under processing is placed into memory. On Unix systems, this is achieved via mmap(), which does not lead to explicit allocation of the buffer. On Win32 systems, a buffer of length equal to the size of the input file is allocated.
In some Kodak cameras, the preview (thumbnail) is stored in the form of uncorrected image. During its extraction using
dcraw -e, the white balance, color conversion, and other settings are the same as those used for extraction of the main RAW data
(including defect removal and dark frame subtraction, which is erroneous, since the image size is different).
In LibRaw::unpack_thumb() calls, the white balance taken from the camera ("as shot") is used and no settings from
imgdata.params are considered.
For all other cameras, thumbnails are extracted "as is," without any color conversions, both in dcraw and in LibRaw.
[back to Index]