C++ API

Contents

  1. LibRaw Objects
  2. Returned values
  3. Methods Loading Data from a File
  4. Auxiliary Functions
  5. Data Postprocessing: Emulation of dcraw Behavior
  6. Data Output to Files: Emulation of dcraw Behavior
  7. Copying unpacked data into memory buffer
  8. Input layer abstraction

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

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:

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[,INT64 bigfile_size])

Win32 only: int LibRaw::open_file(const wchar_t *filename[,INT64 bigfile_size])

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.

Second optional parameter bigfile_size controls background I/O interface used for file operations. For files smaller than bigfile_size the LibRaw_file_datastream will be used and the LibRaw_bigfile_datastream otherwise.

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). 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).

int LibRaw::set_rawspeed_camerafile(char *path_to_cameras_xml)

(Only if LibRaw was built with RawSpeed support).

Loads XML file with RawSpeed camera description data (cameras.xml) specified by path_to_cameras_xml. Returns 0 on success, nonzero on error.

int LibRaw::get_decoder_info(libraw_decoder_info_t *)

The function fills libraw_decoder_info_t structure by passed pointer with current raw decoder 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.

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::setCancelFlag()

This call sets internal fast cancel flags. If set, current Raw decoder will be terminated ASAP. This call is useful if you need to cancel all LibRaw decoders in multithreaded program (e.g. for fast program termination or just for cancel current processing).

void LibRaw::clearCancelFlag()

This call clears internal fast cancel flags, so (early) terminated LibRaw decoder may work again.

int LibRaw::COLOR(int row, int col)

This call returns pixel color (color component number) in bayer patter at row,col. The returned value is in 0..3 range for 4-component Bayer (RGBG2, CMYG and so on) and in 0..2 range for 3-color data.

int LibRaw::error_count()

This call returns count of non-fatal data errors (out of range, etc) occured in unpack() stage.

void LibRaw::subtract_black()

This call will subtract black level values from RAW data (for suitable RAW data). colordata.data_maximum and colordata.maximum and black level data (colordata.black and colordata.cblack) will be adjusted too.

This call should be used if you postprocess RAW data by your own code. LibRaw postprocessing functions will call subtract_black() by oneself.

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.

Support for floating point data

Libraw can read floating point DNG files (no other RAW formats may use floating point) with or without conversion to integer data. Floating point values are stored in imgdata.rawdata buffers:

  • float * float_image (if not NULL) points to floating point bayer data
  • float (*float3_image)[3] (if not NULL) points to floating point 3-channel buffer
  • float (*float4_image)[4] (if not NULL) points to floating point 4-channel buffer

Function calls for floating point support:

  • int LibRaw::is_floating_point(); function will return 1 if file contains floating point data
  • int LibRaw::have_fpdata(); function will return 1 if FP data has read (decoded) into memory and not converted to integer data
  • int LibRaw::convertFloatToInt(float dmin=4096.f, float dmax=32767.f, float dtarget = 16383.f) converts floating point data to integer. If data maximum is out of dmin..dmax range, than data scaled to set maximum to dtarget

Support for YCC formats (Canon sRAW/mRAW and Nikon Small NEF)

       int LibRaw::is_sraw();
int LibRaw::is_nikon_sraw();
int LibRaw::sraw_midpoint()
  • is_sraw() call returns nonzero if current image is YCC-based.
  • is_nikon_sraw() call returns nonzero for Nikon Small NEF files
  • sraw_midpoint() call returns neutral (gray) point for color channels

void LibRaw::set_dng_host(void* p)

If LibRaw is compiled with Adobe DNG SDK support and you wish to use this support:

  • you need to create own dng_host object
  • and pass it to LibRaw object using this function

void LibRaw::recycle_datastream(void)

This call closes input datastream with associated data buffer and unblocks opened file.

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().

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() 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
}

User-specified exif tag parser callback

       typedef void (*exif_parser_callback) (void *context, int tag, int type, int len,unsigned int ord, void *ifp);
void LibRaw::set_exifparser_handler( exif_parser_callback cb,void *context);

Callback to be called on each parsed EXIF/Makernotes tag with parameters:

  • context - pointer to context passed to set_exifparser_handler();
  • tag - EXIF/Makernotes tag value
  • type - TIFF(EXIF) tag type
  • len - tag length
  • ord - byte order (II or MM)
  • void *ifp - pointer to LibRaw_abstract_datastream, positioned to tag data

 

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::raw2image

This function allocates buffer for postprocessing (imgdata.image) and fills it with data layout compatible with LibRaw 0.13/0.14 and below. If the buffer is already allocated, it will be free()ed and allocated again.

This function should be called only if your code do postprocessing stage. If you use LibRaw's postprocessing calls (see below) you don't need to call raw2image().

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::free_image

This function releases the imgdata.image buffer allocated by raw2image();

This method should be called if current postprocessing results are not needed by the program (e.g. already copied somewhere), but new postprocessing calls (with another settings) are possible, so it is to early to call recycle().

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.

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 several function calls for store unpacked data into memory buffer (after using dcraw_process() and so on):

  • get_mem_image_format - get resulting bitmap size and bit depth.
  • copy_mem_image - copy postprocessed data into some memory buffer with different color order and line stride.
  • 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.

 

void get_mem_image_format(int *widthp, int *heightp, int *colorsp, int *bpp) const - return processing bitmap size

This function returns size of postprocessed image:

  • Image width is returned in *widthp;
  • Bitmap height is returned in *heightp;
  • Image color count is returned in *colorsp;
  • Bits per pixel (8 or 16) is returned in *bpp;

int LibRaw::copy_mem_image(void* scan0, int stride, int bgr) - copies postprocessed bitmap data into buffer

Function parameters:

  • void *scan0 - pointer to buffer to copy data to. The buffer should be at least stride*image_height bytes;
  • int stride - stride of each other image line (row) in bytes. Usually image_width*(bit_per_pixel/8)*image_colors, but may be more if you wish to align image rows to, for example, 8 or 16 or 32 bytes to make CPU more happy.
  • int bgr - pixel copy order. RGB if bgr==0 and BGR overwise.

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.

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() 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 LibRaw::dcraw_clear_mem().

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 LibRaw::dcraw_clear_mem().

void LibRaw::dcraw_clear_mem(libraw_processed_image_t *)

This function will free the memory allocated by dcraw_make_mem_image or dcraw_make_mem_thumb.

This is static class member, so call syntax should be LibRaw::dcraw_clear_mem(...).

This call translates directly to free() system function, but it is better to use dcraw_clear_mem because LibRaw (DLL) may be compiled with memory manager other than in calling application.

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.
virtual int jpeg_src(void * p);
Initializes read structures in j_decompress_ptr object passed as *p. This object is used by libjpeg for JPEG data reading from datastream.

Retuens -1 on error and 0 on success.

virtual void * make_jas_stream();
Creates LibJasper input stream (for JPEG2000 decoding).

returns NULL on error or data pointer on success.

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 notification 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 three "standard" input classes in LibRaw distribution:

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_bigfile_datastream - file input interface

This class implements input from file.

Class methods:

LibRaw_bigfile_datastream(const char *fname)
This constructor creates LibRaw_bigfile_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).

The difference between file and bigfile datastreams are obvious from class name: bigfile one supports large files (more than 2Gb) on all supported systems. File one uses streambuf interface which is limited to 2Gb on many systems.

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);

Comments

LibRaw::unpack: does it return 4 or 1 value per pixel

The LibRaw::unpack fills imgdata.image with values. However, imgdata.image is of type ushort (*image)[4] rather than ushort *image, although raw files of Bayer sensors have only one 16 bit value per value. What do I misunderstand here?

Each pixel is 4-component, 16

Each pixel is 4-component, 16 bit per component.

On unpack() sensors only one component is filled. There is two exceptions:
* if half_size parameter is set, then image is resized two-fold (in each dimension), and all 4 components if image[i] filled with data
* for foveon-based sensors three components is filled.

On postprocessing stage remaining components are interpolated 'in-place', without image[] reallocation

-- Alex Tutubalin

Thank you for your prompt

Thank you for your prompt information.
If only one of the four possible values is filled with data by unpack, then there must be either some information about the mosaic pattern or the unfilled items must be marked by a special value?
It would be nice to have a low level funtion, which just writes the sensor data (only 1 ushort per pixel) to a specified buffer:
unpack(unsigned short *buffer, int pitch)
Of course, the user has to assure that there ist enough memory allocated. This rather flexible function has also the advantage that the user can padd the data appropriately, which is often neccessary. Also the DNG-SDK unpacks in stage1 the raw data with just one 16 bit value per pixel, if it's not a Foveon sensor. At least internally such a function should precede libraw::unpack(). It would be nice to have such a function also for libraw users.

There is FC(row,col)

There is FC(row,col) function, which returns index (in 0..3) range of value within image[i][4].
Look in the samples/unprocessed_raw.cpp for usage example

You're right, that raw_image[row*col], than processed_image[row*col][3] may be better alternative. Sometimes in future, LibRaw may be refactored this way.
There is many reasons to have current memory allocation pattern:
* (main one) LibRaw derived from dcraw sources, so memory pattern is preserved

* there is some special cases (Foveon, Sinar 4-shot) where more than one component is needed, so 4-component image[] is more general and fits all cases.

* most LibRaw users uses post-processing stage too. With postprocessing there is no advantage in 2-phase allocation (one for raw data and one for postprocessing).

-- Alex Tutubalin

I remember FC(row,col) from

I remember FC(row,col) from the times, when I tried to dig through dcraw.c. I didn't succeed, because after a pause a had to start all over again. I'm very grateful for your work here. Being frustrated by dcraw.c I turned to the DNG-SDK, which also has the ability to write raw files, which is crucial for my RawImageClearer ( http://www.RawImageClearer.de.tf ). The DNG-SDK has lots of pitfalls and is very bloated, I have to say.
I would like to implement a new kind of demosaicing with libraw. Rather than creating an RGB 4:4:4 image it creates directly a YUV 4:2:0 image, which is exactly the color space used for JPEG compression. Thus I do not really fill in the remaining 2 or 3 values as it is done with the usual RGB demosaicing methods.

dcraw's (and LibRaw's)

dcraw's (and LibRaw's) internal structures are 'one size fits all': image[][4] can fit all 'life types' of RAWs (1-color bayer, 3-color foveon, 4-color Sinar 4-shot). Sure, ~99% of RAW images are simply bayer-pattern RGB, but we should not ignore remaining 1%.

If you want to save memory, you can use 'half-size' processing on unpack() stage. In this case each 4 pixels of raw data are packed into one image[][4] item. You should take in account the exact bayer pattern layout to restore original pixel position.

-- Alex Tutubalin

I understand the philosophy

I understand the philosophy of "one size fits all". The DNG-SDK persues the same strategy, but uses more than one plane for the remaining 1% of sensors, i.e. instead of using four values for one pixels it uses up to four pixel planes. But I certainly understand that you have to follow the design of dcraw.c closely. That will allow you to incorporate new cameras very easily into libraw.
Does 'half-size' processing mean that the top left corner, which may look as follows:
RG
GB
is merged into one pixel with four values? In other words, is 'half-size' processing lossless?

Yes, for '99%' of cameras

Yes, for '99%' of cameras (bayer pattern ones) half_size is lossless. For most RGB-bayer patterns there is four different pixel positions in 2x2 block, so if you want to recover exact pixel position you need to examine "filter" field which describes exact layout.

There is some 'special cases': CMYG cameras, Leaf cameras with 8x2 blocks, but most cases are simple.

Also, we'll sometimes refactor this place in LibRaw. Having multiple planes will make simpler to deal with multi-planes cameras: Fuji SuperCCD (2 images in one file), Sinar 4-shot and 16-shot.....

Sometimes on LibRaw 0.9

-- Alex Tutubalin

unpack doesn't fill image

Has anything changed since this page was written?
From my observations unpack doesn't fill image, as the documentation suggests, but it does fill raw_image. Is there an issue with the documentation, or am I doing something wrong?
I want to access unscaled, uneverything, as raw as possible, bayer data. For this, I assume I should only set the use_camera_matrix = 0; use_camera_wb=0; and unpack().

Thank you

I noticed that raw2image() does this and it felt redundant. So I was confused as what is the utility of it, having no historical knowledge about the library. I just started using libraw ( expect more of me around here :) ), so I think there's no point to use old workflows, which will most likely become obsolete soon.
I only wanted to make sure I understand what I am doing. Thank you for your explanation, now it is clear.
As a suggestion: if there would have been a repository for the documentation, I would have done the change myself.

Depending of what you do in

Depending of what you do in your code, you may prefer

- do not call raw2image()
- and use imgdata.rawdata.raw_image[] array

This way will not allocate extra (4-component per pixel) image array. It is preferred if you, for example, do own processing in floating point: image[] array is not needed in this case.

For non-bayer images:
- imgdata.rawdata.raw_image array will be NULL after unpack()
- and one of color3_image or color4_image will be not NULL.

-- Alex Tutubalin