C++ API

Contents

1. LibRaw Objects
2. Returned values
3. Methods Loading Data from a File
   • int LibRaw::open_datastream(LibRaw_abstract_datastream *stream)
   • int LibRaw::open_file(const char *rawfile)
   • int LibRaw::open_buffer(void *buffer, size_t bufsize)
   • int LibRaw::unpack(void)
   • int LibRaw::unpack_thumb(void)
4. Auxiliary Functions
   • Library version info
     • const char* LibRaw::version()
     • int LibRaw::versionNumber()
     • bool LIBRAW_CHECK_VERSION(major,minor,patch)
   • List of supported cameras
     • int LibRaw::cameraCount()
     • const char** LibRaw::cameraList()
   const char* LibRaw::unpack_function_name()
   • void LibRaw::add_masked_borders_to_bitmap
   • int LibRaw:: rotate_fuji_raw()
   • void LibRaw::recycle(void)
   • LibRaw::~LibRaw()
   • const char* LibRaw::strprogress(enum LibRaw_progress code)
   • const char* LibRaw::strerror(int errorcode)
   • Setting Error Notification Functions
     • User callback for progress indication/interruption
     • Out-of-Memory Notifier
     • File Reading Notifier
5. Data Postprocessing: Emulation of dcraw Behavior
   • Parameter Setting
   • int LibRaw::adjust_sizes_info_only(void)
   • int LibRaw::dcraw_document_mode_processing(void)
   • int LibRaw::dcraw_process(void)
6. Data Output to Files: Emulation of dcraw Behavior
   • int LibRaw::dcraw_ppm_tiff_writer(const char *outfile)
   • int LibRaw::dcraw_thumb_writer(const char *thumbfile)
7. Copying unpacked data into memory buffer
   • libraw_processed_image_t *dcraw_make_mem_image(int *errorcode)
   • libraw_processed_image_t *dcraw_make_mem_thumb(int *errorcode)
8. Input layer abstraction
   • class LibRaw_abstract_datastream - abstract RAW read interface
     • LibRaw_abstract_datastream class methods
       • Object verification
       • Stream read and positioning
       • Other methods
   • Derived input classes included in LibRaw
     • class LibRaw_file_datastream - file input interface
   • Own datastream derived classes
     • substream field: secondary input stream

LibRaw Objects

The main LibRaw object (class) is created either without parameters or with flags determining the object behavior.

#include "libraw/libraw.h"
...

   LibRaw ImageProcessor(unsigned int flags=0);
...
    

Flags (several flags are combined via operator |, i.e., bitwise OR):

• LIBRAW_OPTIONS_NO_MEMERR_CALLBACK: do not set the standard out-of-memory error handler (standard handler outputs the error report in stderr);
• LIBRAW_OPTIONS_NO_DATAERR_CALLBACK: do not set the standard file read error handler (standard handler outputs the error report in stderr).

Three groups of methods are used for image processing

• Data loading from the RAW file
• Postprocessing functions emulating the dcraw behavior
• File output functions emulating the dcraw behavior.

The results of processing are placed in the imgdata field of type libraw_data_t; the same data set contains fields that control the postprocessing and output.

Returned Values

All LibRaw API functions return an integer number in accordance with the return code convention. Please read the descriptions of this convention and LibRaw behavior in cases of fatal errors.

Methods Loading Data from a File

int LibRaw::open_datastream(LibRaw_abstract_datastream *stream)

Opens a datastream with RAW data, reads metadata (EXIF) from it, and fills the following structures:

• imgdata.idata (libraw_iparams_t),
• imgdata.sizes (libraw_image_sizes_t),
• imgdata.color (libraw_colordata_t),
• imgdata.other (libraw_imgother_t), and
• imgdata.thumbnail (libraw_thumbnail_t).

The function returns an integer number in accordance with the return code convention: positive if any system call has returned an error, negative (from the LibRaw error list) if there has been an error situation within LibRaw.

Before file opening, recycle() is always called; hence, if several images are processed in the batch mode, there is no need to call recycle() at the end of each processing cycle.

Input data: pointer to object, derived from LibRaw_abstract_datastream class. This object should be initialized and ready to read. This object should be destroyed in calling application after use.

int LibRaw::open_file(const char *filename)

Creates an LibRaw_file_datastream object, calls open_datastream(). If succeed, sets internal flag which signals to destroy internal datastream object on recycle(). On failure, just created file_datastream destroyed immediately.

The function returns an integer number in accordance with the return code convention: positive if any system call has returned an error, negative (from the LibRaw error list) if there has been an error situation within LibRaw.

int LibRaw::open_buffer(void *buffer, size_t bufsize)

Created an LibRaw_buffer_datastream object, calls open_datastream(). If succeed, sets internal flag which signals to destroy internal datastream object on recycle(). On failure, just created file_datastream destroyed immediately.

The function returns an integer number in accordance with the return code convention: positive if any system call has returned an error, negative (from the LibRaw error list) if there has been an error situation within LibRaw.

int LibRaw::unpack(void)

Unpacks the RAW files of the image, calculates the black level (not for all formats), subtracts black (not for all formats). The results are placed in imgdata.image.

Data reading is sometimes (not frequently) affected by settings made in imgdata.params (libraw_output_params_t); see API notes for details.

The function returns an integer number in accordance with the return code convention: positive if any system call has returned an error, negative (from the LibRaw error list) if there has been an error situation within LibRaw.

int LibRaw::unpack_thumb(void)

Reads (or unpacks) the image preview (thumbnail), placing the result into the imgdata.thumbnail.thumb buffer.
JPEG previews are placed into this buffer without any changes (with the header etc.). Other preview formats are placed into the buffer in the form of the unpacked bitmap image (three components, 8 bits per component).
The thumbnail format is written to the imgdata.thumbnail.tformat field; for the possible values, see description of constants and data structures.

The function returns an integer number in accordance with the return code convention: positive if any system call has returned an error, negative (from the LibRaw error list) if there has been an error situation within LibRaw.

Auxiliary Functions

Library version check

const char* LibRaw::version()

Returns string representation of LibRaw version in MAJOR.MINOR.PATCH-Status format (i.e. 0.6.0-Alpha2 or 0.6.1-Release).

int LibRaw::versionNumber()

Returns integer representation of LibRaw version. During LibRaw development, the version number is always increase .

bool LIBRAW_CHECK_VERSION(major,minor,patch)

Macro for version check in caller applications. Returns 'true' if current library version is greater or equal to set in macro parameters. This macro executes at runtime (not at compile time) and may be used for checking version of dynamically loaded LibRaw (from DLL/shared library).

List of supported RAW formats (cameras)

int LibRaw::cameraCount()

Returns count of cameras supported.

const char** LibRaw::cameraList()

Returns list of supported cameras. Latest item of list is set to NULL (for easy printing).

const char* LibRaw::unpack_function_name()

Returns function name of file unpacking function. Intended only for LibRaw test suite designers to use in test coverage evaluation.

void LibRaw::add_masked_borders_to_bitmap

This call rebuilds imgdata.image bitmap and makes full bitmap, contains both image data (active pixels) and 'black border' (masked pixels). If no masked pixels data present, then this call does nothing. Function call changes data fields sizes.width,sizes.height,sizes.iwidth,sizes.iheight to full image size (i.e. raw_width/raw_height).
This call does nothing:

• for images containing more than one color component per pixel (full-color DNG, already demosaiced files: Canon sRAW, Sinar 4-shot etc).
• for images, unpacked with half resolution (one of parameters set in options: half_mode, wavelet denoising threshold, aberration fixing data).

The function returns an integer number in accordance with the return code convention: positive if any system call has returned an error, negative (from the LibRaw error list) if there has been an error situation within LibRaw.

int LibRaw:: rotate_fuji_raw()

This function rotates non-interpolated RAW bitmap from FujiCCD sensors into 45-degree-rotated position, compatible with old LibRaw versions (prior to LibRaw 0.7). This call is intended for applications, which works with non-interpolated/non-demosaiced RAW data itself. If dcraw_process/dcraw_document_mode_processing calls are used, these call make the rotation internally.

The function returns an integer number in accordance with the return code convention: positive if any system call has returned an error, negative (from the LibRaw error list) if there has been an error situation within LibRaw.

void LibRaw::recycle(void)

Frees the allocated data of LibRaw instance, enabling one to process the next file using the same processor. Repeated calls of recycle() are quite possible and do not conflict with anything.

LibRaw::~LibRaw()

Destructor, which consists in calling recycle().

const char* LibRaw::strprogress(enum LibRaw_progress code)

Converts progress stage code to description string (in English).

const char* LibRaw::strerror(int errorcode)

Analog of strerror(3) function: outputs the text descriptions of LibRaw error codes (in English).

Setting Error Notification Functions

In process of RAW conversion LibRaw can call user-setted callback. This callback can be used for:

• Dynamic status update (progress bar and so on).
• Cancel of processing (for example, user pressed Cancel button).

Also, work of the library may cause two types of exceptional situations that require notification of the calling application:

• Memory shortage
• Data read error.

An application may set its own callbacks that will be called in the cases mentioned above to notify the user (or the calling program).

Progress indication/processing termination

        typedef int (*progress_callback)(void *callback_data,enum LibRaw_progress stage, int iteration, int expected);
        void LibRaw::set_progress_handler(progress_callback func,void *callback_data);
    

LibRaw user can set own callback which will be called 10-50 times during RAW postprocessing by dcraw_process()/dcraw_document_mode_processing();

This callback may terminate current image processing by returning of non-zero value. In such case all processing will be cancelled immediately and all resources will be returned to system by recycle() call. Current call of dcraw_process()/dcraw_document_mode_processing() will return error code LIBRAW_CANCELLED_BY_CALLBACK.

Callback parameters:

void *callback_data

void*-pointer, passed as 2nd argument to set_progress_handler(). This pointer should be used to pass additional data to callback (i.e. thread local data and so on).

enum LibRaw_progress stage

Current processing stage. This number can be converted to string by call to LibRaw::strprogress. Not all processing stages are covered by callback calls.

int iteration

Iteration number within current stage (from 0 to expected-1).

int expected

Expected number of iterations on current stage.

Callback should return value of: 0 for continue processing and non-zero for immediate cancel of processing.

If LibRaw compiled with OpenMP support, iteration parameter may not always increase within one stage. Out of order callback calls are possible.

Callback code sample:

int my_progress_callback(void *data,enum LibRaw_progress p,int iteration, int expected)
{
    char *passed_string = (char *data);
    printf("Callback: %s  pass %d of %d, data passed: %s\n",libraw_strprogress(p),iteration,expected,passed_string);
    if(timeout || key_pressed )
        return 1; // cancel processing immediately
    else
        return 0; // can continue
}

Out-of-Memory Notifier

        typedef void (* memory_callback)(void *callback_data,const char *file, const char *where);
        void LibRaw::set_memerror_handler(memory_callback func,void *callback_data);
    

The user may set his or her own function called in the case of memory shortage. It is a void function receiving two string parameters:

• void *callback_data - void*-pointer, passed as 2nd argument to set_progress_handler(). This pointer should be used to pass additional data to callback (i.e. thread local data and so on).
• file is the name of the RAW file whose processing evoked the out-of-memory error. This name can be NULL if underlying data input layer does not know the name. So, if calling application sets own callback, this callback should work with NULL file name.
• where is the name of the function where memory shortage occurred.

The callback function is intended for information purposes: it notifies the user or the program code that processing is impossible.

If the user does not set his or her own handler, the standard one (output of error message in stderr) will be used.

One can set the null handler by passing NULL to set_memerror_handler; then no notifier function will be called. The same effect can be achieved by creating a LibRaw object with the LIBRAW_OPTIONS_NO_MEMERR_CALLBACK flag in the contructor.

In the case of memory shortage, processing of the current file is terminated and a notifier is called; all allocated resources are freed, and recycle() is performed. The current call will return LIBRAW_UNSUFFICIENT_MEMORY.
At an attempt to continue data processing, all subsequent calls will return LIBRAW_OUT_OF_ORDER_CALL. Processing of a new file may be started in the usual way, by calling LibRaw::open_file().

File Read Error Notifier

        typedef void (*data_callback)(void *callback_data,const char *file, const int offset);
        void LibRaw::set_dataerror_handler(data_callback func, void *callback_data); 
    

The user can define his or her own function to be called in the case of error in the input data. It is a void function receiving two parameters:

• void *callback_data - void*-pointer, passed as 2nd argument to set_progress_handler(). This pointer should be used to pass additional data to callback (i.e. thread local data and so on).
• file is the name of the RAW file whose processing evoked the file read error. This name can be NULL if underlying data input layer does not know the name. So, if calling application sets own callback, this callback should work with NULL file name.
• offset is -1 at end-of-file (if LibRaw expects more data) or a positive number equal to the file position (bytes from file beginning) where the unpacking error occurred.

The callback function is intended for information purposes: it notifies the user or the program code that processing is impossible.

If the user does not set his or her own handler, the standard one (output of error message in stderr) will be used.

One can set the null handler by passing NULL to set_memerror_handler; then no notifier function will be called. The same effect can be achieved by creating a LibRaw object with the LIBRAW_OPTIONS_NO_DATAERR_CALLBACK flag in the contructor.

In the case of error in the input data, processing of the current file is terminated and a notifier is called; all allocated resources are freed, and recycle() is performed. The current call will return LIBRAW_IO_ERROR.
At an attempt to continue data processing, all subsequent calls will return LIBRAW_OUT_OF_ORDER_CALL. Processing of a new file may be started in the usual way, by calling LibRaw::open_file().

Data Postprocessing: Emulation of dcraw Behavior

Instead of writing one's own Bayer pattern postprocessing, one can use the dcraw functions, which are called after the calls of open_file() + unpack() /+ unpack_thumb()/

Parameter Setting

Virtually all parameters that can be set through the dcraw command line are specified by assigning values to fields of the LibRaw::imgdata.params structure. The type of this structure is libraw_output_params_t; all fields are listed and described in sufficient detail in the description of data structures.

int LibRaw::adjust_sizes_info_only(void)

The function calculates the correct size of the output image (imgdata.sizes.iwidth and imgdata.sizes.iheight) for the following cases:

• Files from Fuji cameras (with a 45-degree rotation)
• Files from cameras with non-square pixels
• Images shot by a rotated camera.

In the aforementioned cases, the function changes the fields of the image output size; note that this change cannot be repeated again.

The function should be used for information purposes; it is incompatible with dcraw_document_mode_processing() and dcraw_process() calls.

int LibRaw::dcraw_document_mode_processing(void)

The function emulates dcraw -D: no interpolation, white balance, and color conversion.
It is called after calling LibRaw::unpack();

The function returns an integer number in accordance with the error code convention: positive if any system call has returned an error, negative (from the LibRaw error list) if there has been an error situation within LibRaw.

int LibRaw::dcraw_process(void)

The function emulates the postprocessing capabilities available in dcraw.
Called after calling LibRaw::unpack();

The entire functionality of dcraw (set via the field values in imgdata.params) is supported, except for

• Dark frame subtraction
• Work with bad pixels.

The function is intended solely for demonstration and testing purposes; it is assumed that its source code will be used in most real applications as the reference material concerning the order of RAW data processing.

The function returns an integer number in accordance with the error code convention: positive if any system call has returned an error, negative (from the LibRaw error list) if there has been an error situation within LibRaw.

Data Output to Files: Emulation of dcraw Behavior

In spite of the abundance of libraries for file output in any formats, LibRaw includes calls that emulate the file output provided by dcraw. This is done primarily for easier verification of library work: the resultant files must be binary identical.

int LibRaw::dcraw_ppm_tiff_writer(const char *outfile)

The function outputs the postprocessing results to a file in the PPM/PGM or TIFF format (the format is set via imgdata.params.output_tiff). The results are binary identical to those provided by dcraw.

The function returns an integer number in accordance with the error code convention: positive if any system call has returned an error, negative (from the LibRaw error list) if there has been an error situation within LibRaw.

int LibRaw::dcraw_thumb_writer(const char *thumbfile)

Writes the thumbnail to a file in the PPM format for bitmap thumbnails and in the JPEG format for JPEG thumbnails, i.e., in the format completely identical to the results provided by dcraw.

The function returns an integer number in accordance with the error code convention: positive if any system call has returned an error, negative (from the LibRaw error list) if there has been an error situation within LibRaw.

Copying unpacked data into memory buffer

There is two function calls for store unpacked data into memory buffer (after using dcraw_process() and so on):

• dcraw_make_mem_image - store processed image data into allocated buffer;
• dcraw_make_mem_thumb - store extracted thumbnail into buffer as JPEG-file image (for most cameras) or as RGB-bitmap.

For usage primer see samples/mem_image.c sample.

libraw_processed_image_t *dcraw_make_mem_image(int *errorcode=NULL) - store unpacked and processed image into memory buffer as RGB-bitmap

This function allocates memory buffer and stores unpacked-preprocessed image into this buffer. Function returns allocated structure libraw_processed_image_t with filled fields. Always returns data as RGB bitmap (i.e. type field is equal to LIBRAW_IMAGE_BITMAP).

dcraw_process() or dcraw_document_mode_processing() should be called before dcraw_make_mem_image();

Returns NULL in case of an error. If caller has passed not-NULL value as errorcode parameter, than *errorcode will be set to error code according to error code convention.

NOTE! Memory, allocated for return value will not be fried at destructor or LibRaw::recycle calls. Caller of dcraw_make_mem_image should free this memory by call to free().

libraw_processed_image_t *dcraw_make_mem_thumb(int *errorcode=NULL) - store unpacked thumbnail into memory buffer

This function allocates memory buffer and stores thumbnail data in it. Function returns allocated structure libraw_processed_image_t with filled fields. For most RAW images allocated structure will contains JPEG image (i.e. type field is equal to LIBRAW_IMAGE_JPEG). For some cameras with RGB-bitmap thumbnail (Kodak SLRs) returned structure contains RGB bitmap (type field is equal to LIBRAW_IMAGE_JPEG, see structure description for details).

unpack_thumb() should be called before dcraw_make_mem_thumb();

Returns NULL in case of an error. If caller has passed not-NULL value as errorcode parameter, than *errorcode will be set to error code according to с error code convention.

NOTE! Memory, allocated for return value will not be fried at destructor or LibRaw::recycle calls. Caller of dcraw_make_mem_image should free this memory by call to free().

Input layer abstraction

class LibRaw_abstract_datastream - abstract RAW read interface

LibRaw reads RAW-data by calling (virtual) methods of C++ object derived from LibRaw_abstract_datastream. This C++ class does not implement any read, but defines interface to be called. Call to base class methods always results in error.

LibRaw_abstract_datastream class methods

Object verification

virtual int valid()

Checks input datastream validity. Returns 1 on valid stream and 0 if datastream was created on non-valid input parameters (wrong filename for file stream and so on).

Stream read and positioning

This group of methods implements file object (FILE*) semantics.

virtual int read(void * ptr,size_t size, size_t nmemb)

Similar to fread(ptr,size,nmemb,file).

virtual int seek(off_t o, int whence)

Similar to fseek(file,o,whence).

virtual int tell(

Similar to ftell(file).

virtual int get_char()

Similar to getc(file)/fgetc(file).

virtual char* gets(char *s, int n)

Similar to fgets(s,n,file).

virtual int eof()

Similar to feof(file).

virtual int scanf_one(const char *fmt, void *val)

Simplified variant of fscanf(file,fmt,val): format string is always contains one argument to read. So, variable args call is not needed and only one pointer to data passed.

Other methods

This group of methods includes several supplementary calls. These calls are used to temporary switch to another data stream (file and/or memory buffer).

virtual const char* fname()

Returns name of opened file if datastream object knows it (for example, LibRaw_file_datastream used). Filename used in:

• error notofocation callbacks;
• generation of filename of JPEG-file with metadata when needed (i.e. cameras with 'Diag RAW hack').

virtual int subfile_open(const char *fn)

This call temporary switches input to file fn. Returns 0 on success and error code on error.
The function used to read metadata from external JPEG file (on cameras with "Diag RAW hack").
This call is not implemented for LibRaw_buffer_datastream, so external JPEG processing is not possible when buffer datastream used.
This functon should be implemented in real input class, base class call always return error.
Working implementation sample can be found in LibRaw_file_datastream implementation in libraw/libraw_datastream.h file.

virtual void subfile_close()

This call switches input stream from temporary open file back to main data stream.

virtual int tempbuffer_open(void *buf, size_t size)

This call temporary switches input to LibRaw_buffer_datastream object, created from buf.
This method is needed for Sony encrypted metadata parser.

This call implemented in base class (LibRaw_abstract_datastream), there is no need to reimplement in in derived classes.
Possible activity of temporary datastream requires very accurate programming when implementing datastreams derived from base LibRaw_abstract_datastream. See below for more details.

virtual void tempbuffer_close()

This call switch input back from temporary datastream to main stream. This call implemented in base LibRaw_abstract_datastream class.

Derived input classes included in LibRaw

There is two "standard" input classes in LibRaw distribution:

• LibRaw_file_datastream implements input from file (in filesystem).
• LibRaw_buffer_datastream implements input from memory buffer.

LibRaw C++ interface users can implement their own input classes and use them via LibRaw::open_datastream call. Requirements and implementation specifics are described below.

class LibRaw_file_datastream - file input interface

This class implements input from file.

Class methods:

LibRaw_file_datastream(const char *fname)

This constructor creates LibRaw_file_datastream object from file fname.
Unfortunately, C++ constructor cannot return an error. So if bad filename passed (e.g. nonexistent file) object is created as non-valid (valid() call returns zero).

All other class methods are described above.
This class implements all possble methods, including fname() and subfile_open().

class LibRaw_buffer_datastream - memory buffer input interface

This class implements input from memory buffer.

Class methods:

LibRaw_buffer_datastream(void *buffer, size_t bsize)

This constructor creates datastream object from buffer with size bsize.
It is not possibly to verify the pointer passed, so buffer address is checked against 0 and -1 only.

All other class methods are described above.
This class does not implement fname() and subfile_open() calls, so external JPEG metadata parsing is not possible.

Own datastream derived classes

To create own read interface LibRaw user should implement C++ class derived from LibRaw_abstract_datastream with all read methods.
LibRaw standard implementations may be used as reference. See libraw/libraw_datastream.h file for details (all standard LibRaw input classes are implemented using inline functions only).

substream field: secondary input stream

substream field, defined in base LibRaw_abstract_datastream class requires some additional notes. This field is used when input switched to temporary buffer (used for Sony metadata processing). Unfortunately, there is now ideal C++ way to hide this functionality into base class internals. So, any read call in derived class should include 1-line statement like this:
int method(...args...){ if(substream) return substream->method(...args...). For example:

    virtual int eof() 
    { 
        if(substream) return substream->eof();
....
    virtual int scanf_one(const char *fmt, void* val) 
    { 
        if(substream) return substream->scanf_one(fmt,val);

C API

LibRaw C API is a wrapper around C++ API; therefore, virtually all documentation to C API functions is represented by a set of hyperlinks to the corresponding places in the description of C++ API.

Contents

1. Initialization: libraw_data_t *libraw_init(unsigned int flags);
2. Returned values
3. Data loading
4. Auxiliary Functions
5. Data Postprocessing, Emulation of dcraw Behavior
   • Setting of Parameters
   • Emulation of dcraw Behavior
6. Writing to Output Files
7. Writing processing results to memory buffer

Initialization: libraw_data_t *libraw_init(unsigned int flags);

The function returns the pointer to the instance of libraw_data_t structure.
The resultant pointer should be passed as the first argument to all C API functions (except for libraw_strerror).

Returns NULL in case of error, pointer to the structure in all other cases.

Returned values

Functions of C API return EINVAL (see errno.h) if the null pointer was passed to them as the first argument. In all other cases, the C++ API return code is returned.

Data Loading from a File

int libraw_open_file(libraw_data_t*, const char *)

See LibRaw::open_file()

int libraw_open_buffer(libraw_data_t*, void *buffer, size_t bufsize)

See LibRaw::open_buffer()

int libraw_unpack(libraw_data_t*);

See LibRaw::unpack()

int libraw_unpack_thumb(libraw_data_t*);

See LibRaw::unpack_thumb()

Auxiliary Functions

const char* libraw_version()

See LibRaw::version()

const char* libraw_versionNumber()

See LibRaw::versionNumber()

bool LIBRAW_CHECK_VERSION(major,minor,patch)

See LIBRAW_CHECK_VERSION в описании C++ API

int libraw_cameraCount()

See LibRaw::cameraCount()

int libraw_cameraList()

See LibRaw::cameraList()

void libraw_unpack_function_name(libraw_data_t*);

See LibRaw::unpack_function_name()

void libraw_add_masked_borders_to_bitmap(libraw_data_t*);

See LibRaw::add_masked_borders_to_bitmap()

void libraw_rotate_fuji_raw(libraw_data_t*);

See LibRaw::rotate_fuji_raw()

void libraw_recycle(libraw_data_t*);

See LibRaw::recycle()

void libraw_close(libraw_data_t*);

See LibRaw::~LibRaw()

const char *libraw_strerror(int errorcode);

See LibRaw::strerror

const char *libraw_strprogress(enum LibRaw_progress);

See LibRaw::strprogress

void libraw_set_memerror_handler(libraw_data_t*, memory_callback cb);

See LibRaw::set_memerror_handler()

void libraw_set_dataerror_handler(libraw_data_t*,data_callback func);

See LibRaw::set_dataerror_handler()

void libraw_set_progress_handler(libraw_data_t*,progress_callback func);

See LibRaw::set_progress_handler()

Data Postprocessing, Emulation of dcraw Behavior

Setting of Parameters

The postprocessing parameters for the calls described below are set, just as for C++ API, via setting of fields in the libraw_output_params_t structure:

 libraw_data_t *ptr = libraw_init(0);
 ptr->params.output_tiff = 1; //  output to TIFF
    

Fields of this structure are described in the documentation to libraw_output_params_t. For notes on their use, see API notes.

Emulation of dcraw Behavior

int libraw_adjust_sizes_info_only(libraw_data_t*);

See LibRaw::adjust_sizes_info_only()

int libraw_dcraw_document_mode_processing(libraw_data_t*);

See LibRaw::dcraw_document_mode_processing()

int libraw_dcraw_process(libraw_data_t* lr);

See LibRaw::dcraw_process()

Writing to Output Files

int libraw_dcraw_ppm_tiff_writer(libraw_data_t* lr,const char *filename);

See LibRaw::dcraw_ppm_tiff_writer()

int libraw_dcraw_thumb_writer(libraw_data_t* lr,const char *fname);

See LibRaw::dcraw_thumb_writer()

Writing processing results to memory buffer

libraw_processed_image_t *libraw_dcraw_make_mem_image(libraw_data_t* lr,int * errcode)

See LibRaw::dcraw_make_mem_image()

libraw_processed_image_t *libraw_dcraw_make_mem_thumb(libraw_data_t* lr,int * errcode)

See LibRaw::dcraw_make_mem_thumb()

General Notes on API

Contents

1. LibRaw editions
2. Error Code Conventions and Error Handling
3. Nonstandard Situations That Are Not Errors
4. Input Layer Abstraction
5. Thread Safety
6. The Use of C++
7. Parameters of the LibRaw::imgdata.params Structure Affecting the Behavior of open_file/unpack/unpack_thumb
8. RAW-data filtering
9. Masked pixels storage
10. Memory Usage
    1. Stack Usage
    2. Dynamic Memory Management
    3. Dynamic Memory Usage
       1. Memory for the Decoded Image
       2. Memory for the Decoded Thumbnail
       3. Memory for the Decoded ICC Profile
       4. Memory for RAW Unpacking
       5. Memory for Postprocessing
       6. Memory for File Writing
       7. Unpacking into memory buffer
11. Incompatibilities with dcraw
    1. Processing of Thumbnails from Kodak cameras

LibRaw Versions

Since version 0.9, there is only one LibRaw variants. Older versions have three separate editions (normal, -Lite and -Commercial versions).

Error Code Conventions and Error Handling

The following conventions concern the returned errors:

1. All functions that can return an error code have integer type of return data.
2. If there is no error, the return value is 0 (LIBRAW_SUCCESS).
3. If an error has happened in a system call, the return value is errno (a positive number), which can be analyzed using strerror() or similar means.
4. All LibRaw's own error codes are negative; each of these errors belongs to one of two types:

   Non-fatal errors

   Non-fatal errors do not forbid execution of other functions in the processing succession (e.g., unpack_thumb() can easily return the code corresponding to "preview is absent" but this does not prevent further call of unpack().

   Fatal errors

   In the case of fatal errors (memory shortage, input data error, data unpacking failure), the current stage of processing is terminated and all allocated resouces are freed.
   If an attempt to continue processing is made, all subsequent API calls will return the LIBRAW_OUT_OF_ORDER_CALL error.
   At the same time, the LibRaw instance in which a fatal error has occurred can process the next RAW files in the usual way (by calling open_file() (or other input methods), then unpack(), etc.).

5. The macro LIBRAW_FATAL_ERROR(error code) checks if an error is fatal or not.
6. The error codes are listed and deciphered here.

Nonstandard Situations That Are Not 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.

Input Layer Abstraction

LibRaw uses objects derived from LibRaw_abstract_datastream for data input. Semantics of these objects is similar to 'file with arbitrary seek' object: both read and seek operations are used.

Some RAW formats requires temporary switch to another data stream created on top on memory buffer for metadata read. Methods for doing so are implemented in base class LibRaw_abstract_datastream by internal data field substream. Look into source code of LibRaw_file_datastream class in libraw/libraw_datastream.h file for more details.
When implementing own datastream classes, you need to take substream into account and pass control to methods of this field if it is active (not NULL).

If datastream implementaton knows name of input file, it should provide fname() call. This name will be used in error callbacks and in guessing name of JPEG file with metadata (for RAW files with external metadata).

For external metadata support input class should implement subfile_open()/subfile_close() methods.
Sample of these methods implementation may be found in LibRaw_file_datastream class (look into libraw/libraw_datastream.h file for details).

Thread safety

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.

There is two libraries under Unix enviroment (Linux/FreeBSD/MacOS): libraw_r.a (thread-safe) and libraw.a (single-threaded, slightly faster).

Thread-safe library version stores intermediate unpacker data into LibRaw class data. So, several copies of LibRaw, working in parallel, is possible.

Not thread-safe library uses global variable for intermediate data store which is faster but not reenterant. This library may be used in multi-threaded apps, but only if exactly one LibRaw class copy exists in program.

Windows version is similar to multi-threaded Unix one.

The Use of C++

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.

Parameters of the LibRaw::imgdata.params Structure Affecting the Behavior of open_file/unpack/unpack_thumb

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.params.use_camera_matrix and imgdata.params.use_camera_wb

These fields affect loading of RAW data for cameras with a color matrix.
Attention! If parameter imgdata.params.use_camera_matrix is not set by the user, it is copied from imgdata.params.use_camera_wb at the stage of file opening.

imgdata.params.user_flip

If this parameter is greater than or equal to zero, assignment imgdata.sizes.flip = imgdata.params.user_flip is performed at the open_file() stage.

imgdata.params.shot_select

This parameter makes it possible to select the number of the extracted image for data formats in which storage of several RAW images in one data file is possible.

imgdata.params.half_size

Affects RAW data loading for Phase One and Sinar backs. Also, it this parameter is set then image bitmap will be reduced by half in each dimension. In later case, all 4 components of bitmap will be filled during data extraction phase.

imgdata.params.threshold, imgdata.params.aber

If these parameters used, then half-sized bitmap will be used for data unpacking. See above for details.

imgdata.params.filtering_mode

Affects RAW data loading for cameras with black level subtraction/de-banding during RAW read phase: Canon A600, A5, CRW/CR2; cameras with LJPEG-compression (some Nikon, Kodak and Hasselblad cameras).

imgdata.params.use_camera_wb

Affects loading of white balance matrix for Leaf backs.

imgdata.params.document_mode

Does not affect data reading in the current version of LibRaw. In dcraw, this parameter affects the thumbnail data for certain Kodak cameras.

RAW-data filtration

During RAW unpacking and post-process stages LibRaw can filter RAW data:

• Black level subtraction (required if not already done by camera firmware).
• Zero pixels removal (averaging with nearest pixel values).
• Tone curve operations on RAW-data.

Current LibRaw version allows tuning of filtration process by setting imgdata.params.filtering_mode option to one of enum LibRaw_filtering vales:

• Dcraw-compatible filtration. This mode is default for old LibRaw versions compatibility. This mode is not recommended for new applications.
• One or several (or all) filtering stages can be turned off. This mode recommended for RAW analysers and advanced data filtration made by calling program (this programs may calculate black level by analyzing masked frame data.
• Automatic selection of best filtration avaliable in LibRaw (e.g. camera/model specific routines). This mode is recommended for most applications.

Masked pixels storage

Some of RAW images contains data for not-active ("black","masked") pixels. For some of these formats LibRaw can extract these pixels values and store it in imgdata.masked_pixels data structure. These values can be explored for:

• Black level calculation (with banding suppression on some cameras).
• Noise level calculation, e.g. per-channel noise. This is useful for cameras with per-channel amplification.

Masked pixel data avaliable only for bayer-pattern data (one component per pixel) and only for cameras with masked frame. Masked pixels extraction for other color models (Canon sRAW, Kodak YRGB, Sinar 4-shot files) will possibly be added in future LibRaw versions.

LibRaw provides interface for merging active pixel data and masked pixels into one bitmap: add_masked_borders_to_bitmap(). This call is useful for RAW analyzers.

Memory Usage

Stack Usage

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.

Dynamic Memory Management

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.

Dynamic Memory Usage

LibRaw uses dynamic memory

• for the decoded image;
• for the decoded thumbnail;
• for the ICC profile retrieved from the RAW file (if available);
• for temporary data at the stage of RAW file unpacking;
• for temporary data at the stage of postprocessing and result output;
• for reading of the RAW source file (only under Win32).

Memory for the Decoded Image

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 Decoded Thumbnail

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 Decoded ICC Profile

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 RAW Unpacking

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.

Memory for Postprocessing

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

• rotation of images from FUJI cameras;
• correction of chromatic aberrations;
• image size changes (including correction of non-square pixels);
• highlight recovery;

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.

Memory for File Writing

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.

Unpacking into memory buffer

Functons dcraw_make_mem_image() Х dcraw_make_mem_thumb() (and complementary calls in C-API) allocates memory for entire output datasets (full RGB bitmap and thumbnail, respectively). Calling function should free() this memory themself.

Incompatibilities with dcraw

Processing of Thumbnails from Kodak cameras

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.

Usage Examples

Overview of Examples in the Distribution Package (samples/*)

The LibRaw package contains several examples illustrating the use of this library. Their source codes are located in the samples/ folder, and after library build they will be in the bin/ folder:

• raw-identify The only LibRaw call it uses is open_file(); further code prints the values of the fields of the imgdata structure. The output of raw-identify/raw-identify -v is virtually identical to the output of dcraw -i/dcraw -i -v (in the output of this example, the sources of color data in the numeric form are additionally printed). Command line key -u shows unpacking function name.
• simple_dcraw A simple "emulation" of dcraw reproducing the behavior of dcraw [-D] [-e] [-v] [-T]. The result of its work must be binary identical to the result produced by a dcraw run with relevant keys. A simplified version of this example is considered below.
  -B command-line switch turns on use of open_buffer() API call used via mmap() of input file (Unix only).
• dcraw_half Demonstrates the use of C API. The example emulates the behavior of dcraw -h (no other control parameters can be specified in this example). The result of its work must be binary identical to the results produced by dcraw -h.
• dcraw_emu Complete emulation of dcraw (except for keys -D -d -P -K -i -e, which are considered in other usage examples). Of most interest is processing of command line keys (copied from dcraw). The result of its work must be binary identical to the results produced by dcraw with the same command line keys.
  This sample supports gamma-corrected output of 16-bit data (use -1 command-line switch).
  -B command-line switch turns on use of open_buffer() API call used via mmap() of input file (Unix only).
  The -c float-value command-line switch sets params.adjust_maximum value to nondefault. Set it to zero to disable maximum adjustment and to nonzero to enable it. Disabling this feature may result to incorrect highlights processing on some cameras.
• half_mt Emulation of dcraw -h. It "understands" the following keys: -a (automatic white balance over the entire image), -w (white balance of the camera), -T (output in the tiff format), and -J n (number of parallel threads launched for image processing).
  On multiprocessor/multicore computers, the speed gain is notable in the case of mass processing. On a Win32 machine, the example is assembled from the initial file half_mt_win32.c, since work with threads under Windows is fundamentally different and it it easier to copy simple source codes than write one complex code.
• mem_image This sample uses dcraw_make_mem_image and dcraw_make_mem_thumb calls, than writes data in PPM format. Results should be identical with dcraw with same command-line options (options supported: -4, -1, -e, -h).
• unprocessed_raw This sample extracts (mostly) unaltered RAW data including masked pixels data (on supported cameras). Black level subtraction and zero pixel averaging is turned off. If black frame exists and black frame extraction is supported for given format, masked pixels data is added to resulting .TIFF file. Command line options: -q - be quiet, -A - autoscale data (integer multiplier), -g gamma-correction (gamma 2.2) for data (instead of precise linear one), -N turns off tone curve correction of RAW data.
• 4channnels - splits RAW-file into four separate 16-bit grayscale TIFFs (per RAW channel).
  Command line switches:
  • -s N selects N-th image from RAW with multiple images
  • -g gamma correction (gamma 2.2)
  • -A values autoscale by auto-calculated integer factor
  • -B turn off black subtraction
  • -N no RAW curve

Example of docmode

Below we consider the samples/simple_dcraw.cpp example, which emulates the behavior of dcraw [-D] [-e][-v][-t]. To save space, let us assume that keys -t -v are always specified (to avoid comments on command line parsing) and there is always one parameter (name of file), which is the only one and always passed to the program.

int main(int ac, char *av[])
{
    int  i, ret, verbose=0, output_thumbs=0;
    char outfn[1024],thumbfn[1024]; 

    // Creation of image processing object
    LibRaw RawProcessor;
    
    // The date in TIFF is written in the local format; let us specify the timezone for compatibility with dcraw 
    putenv ((char*)"TZ=UTC"); 

// Let us define variables for convenient access to fields of RawProcessor

#define P1  RawProcessor.imgdata.idata
#define S   RawProcessor.imgdata.sizes
#define C   RawProcessor.imgdata.color
#define T   RawProcessor.imgdata.thumbnail
#define P2  RawProcessor.imgdata.other
#define OUT RawProcessor.imgdata.params

    OUT.output_tiff = 1; // Let us output TIFF

   // Let us open the file
   if( (ret = RawProcessor.open_file(av[1])) != LIBRAW_SUCCESS)
      {
          fprintf(stderr,"Cannot open %s: %s\n",av[i],libraw_strerror(ret));

          // recycle() is needed only if we want to free the resources right now. 
          // If we process files in a cycle, the next open_file() 
          // will also call recycle(). If a fatal error has happened, it means that recycle()
          // has already been called (repeated call will not cause any harm either).

          RawProcessor.recycle(); 
          goto end;
      }

   // Let us unpack the image
   if( (ret = RawProcessor.unpack() ) != LIBRAW_SUCCESS)
      {
          fprintf(stderr,"Cannot unpack_thumb %s: %s\n",av[i],libraw_strerror(ret));

          if(LIBRAW_FATAL_ERROR(ret))
                    goto end;
          // if there has been a non-fatal error, we will try to continue
      }
  // Let us unpack the thumbnail
  if( (ret = RawProcessor.unpack_thumb() ) != LIBRAW_SUCCESS)
     {
          // error processing is completely similar to the previous case
           fprintf(stderr,"Cannot unpack_thumb %s: %s\n",av[i],libraw_strerror(ret));
           if(LIBRAW_FATAL_ERROR(ret))
                   goto end; 
    }
  else // We have successfully unpacked the thumbnail, now let us write it to a file
    {
      snprintf(thumbfn,sizeof(thumbfn),"%s.%s",av[i],T.tformat == LIBRAW_THUMBNAIL_JPEG ? "thumb.jpg" : "thumb.ppm");
      if( LIBRAW_SUCCESS != (ret = RawProcessor.dcraw_thumb_writer(thumbfn)))
        {
                fprintf(stderr,"Cannot write %s: %s\n",thumbfn,libraw_strerror(ret));

                // in the case of fatal error, we should terminate processing of the current file
                if(LIBRAW_FATAL_ERROR(ret))
                          goto end; 
        }
    }
   // Data unpacking
   if(OUT.document_mode)
           ret = RawProcessor.dcraw_document_mode_processing();
   else
           ret = RawProcessor.dcraw_process();

    if(LIBRAW_SUCCESS != ret ) // error at the previous step
          {
               fprintf(stderr,"Cannot do postprocessing on %s: %s\n",av[i],libraw_strerror(ret));
               if(LIBRAW_FATAL_ERROR(ret))
                        goto end;
          }
   else  // Successful document processing
     {
        snprintf(outfn,sizeof(outfn),"%s.%s", av[i], "tiff");
        if( LIBRAW_SUCCESS != (ret = RawProcessor.dcraw_ppm_tiff_writer(outfn)))
                fprintf(stderr,"Cannot write %s: error %d\n",outfn,ret);
     }

  // we don't evoke recycle() or call the desctructor; C++ will do everything for us
  return 0;
end:
  // got here after an error
  return 1;
}