~ubuntu-branches/ubuntu/precise/libraw/precise-security : revision 1

1

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

2

<html>

3

<head>

4

<title>LibRaw C++ API</title>

5

6

</head>

7

8

<body>

9

<a href=index-eng.html>[back to Index]</a>

10

<h1>LibRaw C++ API</h1>

11

<p>Contents</p>

12

<ol>

13

<li><a href="#LibRaw">LibRaw Objects</a> </li>

14

<li><a href="#return">Returned values</a></li>

15

<li><a href="#dataload">Methods Loading Data from a File</a>

16

<ul>

17

<li><a href="#open_datastream">int LibRaw::open_datastream(LibRaw_abstract_datastream *stream)</a></li>

18

<li><a href="#open_file">int LibRaw::open_file(const char *rawfile)</a></li>

19

<li><a href="#open_buffer">int LibRaw::open_buffer(void *buffer, size_t bufsize)</a></li>

20

<li><a href="#unpack">int LibRaw::unpack(void)</a></li>

21

<li><a href="#unpack_thumb">int LibRaw::unpack_thumb(void)</a></li>

22

</ul>

23

</li>

24

<li><a href="#utility">Auxiliary Functions</a>

25

<ul>

26

<li>Library version info

27

<ul>

28

<li><a href="#version">const char* LibRaw::version()</a></li>

29

<li><a href="#versionNumber">int LibRaw::versionNumber()</a></li>

30

<li><a href="#LIBRAW_CHECK_VERSION">bool LIBRAW_CHECK_VERSION(major,minor,patch)</a>

31

</ul>

32

</li>

33

<li>List of supported cameras

34

<ul>

35

<li><a href="#cameraCount">int LibRaw::cameraCount()</a></li>

36

<li><a href="#cameraList">const char** LibRaw::cameraList()</a></li>

37

</ul>

38

</li>

39

<li<<a href="#unpack_function_name">const char* LibRaw::unpack_function_name()</a></li>

40

<li><a href="#add_masked_borders_to_bitmap">void LibRaw::add_masked_borders_to_bitmap</a></li>

41

<li><a href="#rotate_fuji_raw">int LibRaw:: rotate_fuji_raw()</a>

42

<li><a href="#recycle">void LibRaw::recycle(void)</a></li>

43

<li><a href="#~LibRaw">LibRaw::~LibRaw()</a></li>

44

<li><a href="#strprogress">const char* LibRaw::strprogress(enum LibRaw_progress code)</a></li>

45

<li><a href="#libraw_strerror">const char* LibRaw::strerror(int errorcode)</a></li>

46

<li><a href="#callbacks">Setting Error Notification Functions</a>

47

<ul>

48

<li><a href="#progress">User callback for progress indication/interruption</a></li>

49

<li><a href="#memerror">Out-of-Memory Notifier</a></li>

50

<li><a href="#dataerror">File Reading Notifier</a></li>

51

</ul>

52

</li>

53

</ul>

54

</li>

55

<li><a href="#dcrawemu">Data Postprocessing: Emulation of dcraw Behavior</a>

56

<ul>

57

<li><a href="#dcraw_params">Parameter Setting</a></li>

58

<li><a href="#adjust_sizes_info_only">int LibRaw::adjust_sizes_info_only(void)</a></li>

59

<li><a href="#dcraw_document_mode_processing">int LibRaw::dcraw_document_mode_processing(void)</a></li>

60

<li><a href="#dcraw_process">int LibRaw::dcraw_process(void)</a></li>

61

</ul>

62

</li>

63

<li><a href="#dcrawrite">Data Output to Files: Emulation of dcraw Behavior</a>

64

<ul>

65

<li><a href="#dcraw_ppm_tiff_writer">int LibRaw::dcraw_ppm_tiff_writer(const char *outfile)</a></li>

66

<li><a href="#dcraw_thumb_writer">int LibRaw::dcraw_thumb_writer(const char *thumbfile)</a></li>

67

</ul>

68

</li>

69

<li>

70

<a href="#memwrite">Copying unpacked data into memory buffer</a>

71

<ul>

72

<li>

73

<a href="#dcraw_make_mem_image">libraw_processed_image_t *dcraw_make_mem_image(int *errorcode)</a>

74

</li>

75

<li>

76

<a href="#dcraw_make_mem_thumb">libraw_processed_image_t *dcraw_make_mem_thumb(int *errorcode)</a>

77

</li>

78

</ul>

79

</li>

80

<li><a href="#datastream">Input layer abstraction</a>

81

<ul>

82

<li><a href="LibRaw_abstract_datastream">class LibRaw_abstract_datastream - abstract RAW read interface<a>

83

<ul>

84

<li><a href="#datastream_methods">LibRaw_abstract_datastream class methods</a>

85

<ul>

86

<li><a href="#datastream_methods_utility">Object verification</a></li>

87

<li><a href="#datastream_methods_read">Stream read and positioning</a></li>

88

<li><a href="#datastream_methods_other">Other methods</a></li>

89

</ul>

90

</li>

91

</ul>

92

</li>

93

<li><a href="#datastream_derived">Derived input classes included in LibRaw</a>

94

<ul>

95

<li><a href="#file_datastream">class LibRaw_file_datastream - file input interface</a></li>

96

</ul>

97

</li>

98

<li><a href="#own_datastreams">Own datastream derived classes</a>

99

<ul>

100

<li><a href="#substream">substream field: secondary input stream</a></li>

101

</ul>

102

<li>

103

</ul>

104

</li>

105

</ol>

106

107

108

<h2>LibRaw Objects</h2>

109

<p>

110

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

111

</p>

112

<pre>

113

#include "libraw/libraw.h"

114

...

115

116

LibRaw ImageProcessor(unsigned int flags=0);

117

...

118

</pre>

119

<p>Flags (several flags are combined via operator |, i.e., bitwise OR):</P>

120

<ul>

121

<li><b>LIBRAW_OPTIONS_NO_MEMERR_CALLBACK</b>: do not set the standard

122

<a href="#callbacks">out-of-memory error handler</a> (standard handler outputs the error report in stderr);</li>

123

<li><b>LIBRAW_OPTIONS_NO_DATAERR_CALLBACK</b>: do not set the standard

124

<a href="#callbacks">file read error handler</a> (standard handler outputs the error report in stderr).</li>

125

</ul>

126

<p>

127

Three groups of methods are used for image processing

128

</p>

129

<ul>

130

<li><a href="#dataload">Data loading from the RAW file</a></li>

131

<li><a href="#dcrawemu">Postprocessing functions emulating the dcraw behavior</a></li>

132

<li><a href="#dcrawrite">File output functions emulating the dcraw behavior</a>.</li>

133

</ul>

134

<p>

135

The results of processing are placed in the imgdata field of type <a

136

href=API-datastruct-eng.html>libraw_data_t</a>; the same data set contains fields that control the postprocessing

137

and output.

138

</p>

139

140

<h2>Returned Values</h2>

141

<p>

142

All LibRaw API functions return an integer number in accordance with the

143

<a href=API-notes-eng.html#errors>return code convention</a>. Please read the descriptions of

144

<a href=API-notes-eng.html#errors>this convention</a> and <a href="#callbacks">LibRaw behavior

145

in cases of fatal errors</a>.

146

</p>

147

148

149

<h2>Methods Loading Data from a File</h2>

150

151

<h3>int LibRaw::open_datastream(LibRaw_abstract_datastream *stream)</h3>

152

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

153

</p>

154

<ul>

155

<li>imgdata.idata (<a href="API-datastruct-eng.html#libraw_iparams_t">libraw_iparams_t</a>),</li>

156

<li>imgdata.sizes (<a href="API-datastruct-eng.html#libraw_image_sizes_t">libraw_image_sizes_t</a>),</li>

157

<li>imgdata.color (<a href="API-datastruct-eng.html#libraw_colordata_t">libraw_colordata_t</a>),</li>

158

<li>imgdata.other (<a href="API-datastruct-eng.html#libraw_imgother_t">libraw_imgother_t</a>), and </li>

159

<li>imgdata.thumbnail (<a href="API-datastruct-eng.html#libraw_thumbnail_t">libraw_thumbnail_t</a>).</li>

160

</ul>

161

<p>The function returns an integer number in accordance with the <a href=API-notes-eng.html#errors>return

162

code convention</a>: positive if any system call has returned an error, negative

163

(from the <a href=API-datastruct-eng.html#LibRaw_errors>LibRaw error list</a>) if there has been an error

164

situation within LibRaw.

165

</p>

166

<p>Before file opening, <a href="#recycle">recycle()</a> is always called; hence, if several images

167

are processed in the batch mode, there is no need to call recycle() at the end of each processing cycle.

168

</p>

169

<p><b>Input data</b>: pointer to object, derived from <a href="#datastream">LibRaw_abstract_datastream</a> class.

170

This object should be initialized and ready to read. This object should be destroyed in calling application

171

after use.

172

</p>

173

174

<h3>int LibRaw::open_file(const char *filename)</h3>

175

<p>

176

Creates an <a href="#file_datastream">LibRaw_file_datastream</a> object, calls

177

<a href="#open_datastream">open_datastream()</a>. If succeed, sets internal flag which signals

178

to destroy internal datastream object on <a href="#recycle">recycle()</a>. On failure,

179

just created file_datastream destroyed immediately.

180

</p>

181

<p>The function returns an integer number in accordance with the

182

<a href=API-notes-eng.html#errors>return code convention</a>: positive if any system call has returned an error, negative

183

(from the <a href=API-datastruct-eng.html#LibRaw_errors>LibRaw error list</a>) if there has been an error

184

situation within LibRaw.

185

</p>

186

187

188

<h3>int LibRaw::open_buffer(void *buffer, size_t bufsize)</h3>

189

<p>

190

Created an <a href="#buffer_datastream">LibRaw_buffer_datastream</a> object, calls

191

<a href="#open_datastream">open_datastream()</a>. If succeed, sets internal flag which signals

192

to destroy internal datastream object on <a href="#recycle">recycle()</a>. On failure,

193

just created file_datastream destroyed immediately.

194

</p>

195

<p>The function returns an integer number in accordance with the

196

<a href=API-notes-eng.html#errors>return code convention</a>: positive if any system call has returned an error, negative

197

(from the <a href=API-datastruct-eng.html#LibRaw_errors>LibRaw error list</a>) if there has been an error

198

situation within LibRaw.

199

</p>

200

201

202

<h3> int LibRaw::unpack(void)</h3>

203

<p>

204

Unpacks the RAW files of the image, calculates the black level (not for all formats), subtracts black

205

(not for all formats). The results are placed in imgdata.image.

206

</p>

207

<p>

208

Data reading is sometimes (not frequently) affected by settings made in imgdata.params (<a

209

href="API-datastruct-eng.html#libraw_output_params_t">libraw_output_params_t</a>); see <a

210

href=API-notes-eng.html>API notes</a> for details.

211

</p>

212

<p>The function returns an integer number in accordance with the <a href=API-notes-eng.html#errors>return code

213

convention</a>: positive if any system call has returned an error, negative (from the

214

<a href=API-datastruct-eng.html#LibRaw_errors>LibRaw error list</a>) if there has been an error

215

situation within LibRaw.

216

</p>

217

218

219

<h3>int LibRaw::unpack_thumb(void)</h3>

220

<p>

221

Reads (or unpacks) the image preview (thumbnail), placing the result into the imgdata.thumbnail.thumb buffer.<br/>

222

JPEG previews are placed into this buffer without any changes (with the header etc.). Other preview

223

formats are placed into the buffer in the form of the unpacked bitmap image (three components, 8 bits per component).<br/>

224

The thumbnail format is written to the imgdata.thumbnail.tformat field; for the possible values, see

225

<a href="API-datastruct-eng.html#LibRaw_thumbnail_formats">description of constants and data structures</a>.

226

227

</p>

228

<p>The function returns an integer number in accordance with the <a href=API-notes-eng.html#errors>return code

229

convention</a>: positive if any system call has returned an error, negative (from the

230

<a href=API-datastruct-eng.html#LibRaw_errors>LibRaw error list</a>) if there has been an error situation within

231

LibRaw.

232

</p>

233

234

<h2>Auxiliary Functions</h2>

235

<h3>Library version check</h3>

236

237

<h4>const char* LibRaw::version()</h4>

238

<p>

239

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

240

or 0.6.1-Release).

241

</p>

242

243

<h4>int LibRaw::versionNumber()</h4>

244

<p>

245

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

246

increase .

247

</p>

248

249

<h4>bool LIBRAW_CHECK_VERSION(major,minor,patch)</h4>

250

<p>

251

Macro for version check in caller applications. Returns 'true' if current library version is greater or equal to

252

set in macro parameters. This macro executes at runtime (not at compile time) and may be used for checking

253

version of dynamically loaded LibRaw (from DLL/shared library).

254

</p>

255

<h3>List of supported RAW formats (cameras)</h3>

256

257

<h4>int LibRaw::cameraCount()</h4>

258

<p>

259

Returns count of cameras supported.

260

</p>

261

262

<h4>const char** LibRaw::cameraList()</h4>

263

<p>

264

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

265

</p>

266

267

<h3>const char* LibRaw::unpack_function_name()</h3>

268

<p>

269

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

270

coverage evaluation.

271

</p>

272

273

274

<h3>void LibRaw::add_masked_borders_to_bitmap</h3>

275

<p>

276

This call rebuilds <b>imgdata.image</b> bitmap and makes full bitmap, contains both image data (active

277

pixels) and 'black border' (masked pixels). If no masked pixels data present, then this call does nothing.

278

Function call changes data fields <b>sizes.width,sizes.height,sizes.iwidth,sizes.iheight</b> to full image

279

size (i.e. raw_width/raw_height).<br/>

280

This call does nothing:

281

</p>

282

<ul>

283

<li>for images containing more than one color component per pixel (full-color DNG,

284

already demosaiced files: Canon sRAW, Sinar 4-shot etc).</li>

285

<li>for images, unpacked with half resolution (one of parameters set in options: half_mode, wavelet denoising

286

threshold, aberration fixing data).

287

</li>

288

</ul>

289

<p>The function returns an integer number in accordance with the <a href=API-notes-eng.html#errors>return code

290

convention</a>: positive if any system call has returned an error, negative (from the

291

<a href=API-datastruct-eng.html#LibRaw_errors>LibRaw error list</a>) if there has been an error situation within

292

LibRaw.

293

</p>

294

295

<h3> int LibRaw:: rotate_fuji_raw()</h3>

296

<p>

297

This function rotates non-interpolated RAW bitmap from FujiCCD sensors into 45-degree-rotated position,

298

compatible with old LibRaw versions (prior to LibRaw 0.7). This call is intended for applications,

299

which works with non-interpolated/non-demosaiced RAW data itself. If

300

dcraw_process/dcraw_document_mode_processing calls are used, these call make the rotation internally.

301

</p>

302

<p>The function returns an integer number in accordance with the <a href=API-notes-eng.html#errors>return code

303

convention</a>: positive if any system call has returned an error, negative (from the

304

<a href=API-datastruct-eng.html#LibRaw_errors>LibRaw error list</a>) if there has been an error situation within

305

LibRaw.

306

</p>

307

308

309

<h3>void LibRaw::recycle(void)</h3>

310

<p>Frees the allocated data of LibRaw instance, enabling one to process the next file using

311

the same processor. Repeated calls of recycle() are quite possible and do not conflict with anything.

312

</p>

313

314

315

<h3>LibRaw::~LibRaw()</h3>

316

<p>Destructor, which consists in calling recycle().</p>

317

318

319

<h3>const char* LibRaw::strprogress(enum LibRaw_progress code)</h3>

320

<p>Converts progress stage code to description string (in English).</p>

321

322

323

<h3>const char* LibRaw::strerror(int errorcode)</h3>

324

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

325

326

327

<h3>Setting Error Notification Functions</h3>

328

<p>

329

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

330

</p>

331

<ul>

332

<li>Dynamic status update (progress bar and so on).</li>

333

<li>Cancel of processing (for example, user pressed Cancel button).</li>

334

</ul>

335

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

336

</p>

337

<ul>

338

<li>Memory shortage</li>

339

<li>Data read error.</li>

340

</ul>

341

<p>

342

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

343

</p>

344

345

<h4>Progress indication/processing termination</h4>

346

<pre>

347

typedef int (*progress_callback)(void *callback_data,enum LibRaw_progress stage, int iteration, int expected);

348

void LibRaw::set_progress_handler(progress_callback func,void *callback_data);

349

</pre>

350

<p>

351

LibRaw user can set own callback which will be called 10-50 times during RAW postprocessing

352

by dcraw_process()/dcraw_document_mode_processing();

353

</p>

354

<p>

355

This callback may terminate current image processing by returning of non-zero value. In such case all processing

356

will be cancelled immediately and all resources will be returned to system by recycle() call.

357

Current call of dcraw_process()/dcraw_document_mode_processing() will return error code

358

LIBRAW_CANCELLED_BY_CALLBACK.

359

</p>

360

<p>

361

Callback parameters:

362

<dl>

363

<dt>void *callback_data</dt>

364

<dd>void*-pointer, passed as 2nd argument to set_progress_handler(). This pointer should be used to pass

365

additional data to callback (i.e. thread local data and so on).

366

</dd>

367

<dt>enum LibRaw_progress stage</dt>

368

<dd>Current processing stage. This number can be converted to string by call to

369

<a href="#strprogress">LibRaw::strprogress</a>. Not all processing stages are covered by callback calls.

370

</dd>

371

<dt>int iteration</dt>

372

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

373

</dd>

374

<dt>int expected</dt>

375

<dd>Expected number of iterations on current stage.</dd>

376

</dl>

377

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

378

</p>

379

<p>

380

If LibRaw compiled with OpenMP support, iteration parameter may not always increase within one stage. Out of

381

order callback calls are possible.

382

</p>

383

<p>

384

Callback code sample:

385

<pre>

386

int my_progress_callback(void *data,enum LibRaw_progress p,int iteration, int expected)

387

{

388

char *passed_string = (char *data);

389

printf("Callback: %s pass %d of %d, data passed: %s\n",libraw_strprogress(p),iteration,expected,passed_string);

390

if(timeout || key_pressed )

391

return 1; // cancel processing immediately

392

else

393

return 0; // can continue

394

}

395

396

</pre>

397

398

399

<h4>Out-of-Memory Notifier</h4>

400

<pre>

401

typedef void (* memory_callback)(void *callback_data,const char *file, const char *where);

402

void LibRaw::set_memerror_handler(memory_callback func,void *callback_data);

403

</pre>

404

<p>The user may set his or her own function called in the case of memory shortage. It is a void function

405

receiving two string parameters:

406

</p>

407

<ul>

408

<li><b>void *callback_data</b> - void*-pointer, passed as 2nd argument to set_progress_handler(). This pointer

409

should be used to pass additional data to callback (i.e. thread local data and so on).</li>

410

<li><b>file</b> is the name of the RAW file whose processing evoked the out-of-memory error.

411

This name <b>can be NULL</b> if underlying data input layer does not know the name. So, if calling

412

application sets own callback, this callback should work with NULL file name.

413

</li>

414

<li><b>where</b> is the name of the function where memory shortage occurred.</li>

415

</ul>

416

<p>The callback function is intended for information purposes: it notifies the user

417

or the program code that processing is impossible.</p>

418

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

419

<p>One can set the null handler by passing NULL to set_memerror_handler; then no notifier

420

function will be called. The same effect can be achieved by creating a LibRaw object with the LIBRAW_OPTIONS_NO_MEMERR_CALLBACK

421

flag in the contructor.

422

</p>

423

<p>In the case of memory shortage, processing of the current file is terminated and a notifier is called; all

424

allocated resources are freed, and <a href="#recycle">recycle()</a> is performed. The current call will return

425

LIBRAW_UNSUFFICIENT_MEMORY.

426

<br/>

427

At an attempt to continue data processing, all subsequent calls will return LIBRAW_OUT_OF_ORDER_CALL.

428

Processing of a new file may be started in the usual way, by calling LibRaw::open_file().

429

</p>

430

431

<h4>File Read Error Notifier</h4>

432

<pre>

433

typedef void (*data_callback)(void *callback_data,const char *file, const int offset);

434

void LibRaw::set_dataerror_handler(data_callback func, void *callback_data);

435

</pre>

436

<p>

437

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

438

two parameters:

439

</p>

440

<ul>

441

<li><b>void *callback_data</b> - void*-pointer, passed as 2nd argument to set_progress_handler(). This pointer

442

should be used to pass additional data to callback (i.e. thread local data and so on).</li>

443

<li><b>file</b> is the name of the RAW file whose processing evoked the file read error.

444

This name <b>can be NULL</b> if underlying data input layer does not know the name. So, if calling

445

application sets own callback, this callback should work with NULL file name.

446

</li>

447

<li><b>offset</b> is -1 at end-of-file (if LibRaw expects more data) or a positive number equal to

448

the file position (bytes from file beginning) where the unpacking error occurred.</li>

449

</ul>

450

<p>The callback function is intended for information purposes: it notifies the user

451

or the program code that processing is impossible.</p>

452

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

453

<p>One can set the null handler by passing NULL to set_memerror_handler; then no notifier

454

function will be called. The same effect can be achieved by creating a LibRaw object with the LIBRAW_OPTIONS_NO_DATAERR_CALLBACK

455

flag in the contructor. </p>

456

<p>In the case of error in the input data, processing of the current file is terminated and a notifier is called; all

457

allocated resources are freed, and <a href="#recycle">recycle()</a> is performed. The current call will return

458

LIBRAW_IO_ERROR.

459

<br/>

460

At an attempt to continue data processing, all subsequent calls will return LIBRAW_OUT_OF_ORDER_CALL.

461

Processing of a new file may be started in the usual way, by calling LibRaw::open_file().

462

</p>

463

464

465

<h2>Data Postprocessing: Emulation of dcraw Behavior</h2>

466

<p>

467

Instead of writing one's own Bayer pattern postprocessing, one can use the dcraw functions, which are called

468

after the calls of open_file() + unpack() /+ unpack_thumb()/

469

</p>

470

471

<h3>Parameter Setting</h3>

472

<p>

473

Virtually all parameters that can be set through the dcraw command line are specified by assigning values to

474

fields of the <b>LibRaw::imgdata.params</b> structure. The type of this structure is <b>libraw_output_params_t</b>;

475

all fields are listed and described in sufficient detail in the <a href="API-datastruct-eng.html#libraw_output_params_t">description

476

of data structures</a>.

477

</p>

478

479

480

<h3>int LibRaw::adjust_sizes_info_only(void)</h3>

481

<p>

482

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

483

following cases:

484

</p>

485

<ul>

486

<li>Files from Fuji cameras (with a 45-degree rotation)</li>

487

<li>Files from cameras with non-square pixels</li>

488

<li>Images shot by a rotated camera.</li>

489

</ul>

490

<p>

491

In the aforementioned cases, the function changes the fields of the image output size; note that

492

this change cannot be repeated again.

493

</p>

494

<p>

495

The function should be used for information purposes; it is incompatible with <a

496

href="#dcraw_document_mode_processing">dcraw_document_mode_processing()</a> and <a

497

href="#dcraw_process">dcraw_process()</a> calls.

498

</p>

499

500

501

<h3>int LibRaw::dcraw_document_mode_processing(void)</h3>

502

<p>

503

The function emulates <b>dcraw -D</b>: no interpolation, white balance, and color conversion.<br/>

504

It is called after calling LibRaw::unpack();

505

</p>

506

<p>The function returns an integer number in accordance with the <a href=API-notes-eng.html#errors>error

507

code convention</a>: positive if any system call has returned an error, negative (from the

508

<a href=API-datastruct-eng.html#LibRaw_errors>LibRaw error list</a>) if there has been an error situation within

509

LibRaw.

510

</p>

511

512

513

<h3>int LibRaw::dcraw_process(void)</h3>

514

<p>

515

The function emulates the postprocessing capabilities available in <b>dcraw</b>.<br/>

516

Called after calling LibRaw::unpack();

517

</p>

518

<p>The entire functionality of dcraw (set via the field values in <a

519

href="API-datastruct-eng.html#libraw_output_params_t">imgdata.params</a>) is supported, except for

520

</p>

521

<ul>

522

<li>Dark frame subtraction</li>

523

<li>Work with bad pixels.</li>

524

</ul>

525

<p>The function is intended solely for demonstration and testing purposes; it is assumed that its source code

526

will be used in most real applications as the reference material concerning the order of RAW data processing.

527

</p>

528

<p>The function returns an integer number in accordance with the <a href=API-notes-eng.html#errors>error

529

code convention</a>: positive if any system call has returned an error, negative (from the

530

<a href=API-datastruct-eng.html#LibRaw_errors>LibRaw error list</a>) if there has been an error situation within

531

LibRaw.

532

</p>

533

534

<h2>Data Output to Files: Emulation of dcraw Behavior</h2>

535

<p>In spite of the abundance of libraries for file output in any formats, LibRaw includes calls that emulate

536

the file output provided by dcraw. This is done primarily for easier verification of library work: the resultant

537

files must be binary identical.

538

</p>

539

540

541

<h3>int LibRaw::dcraw_ppm_tiff_writer(const char *outfile)</h3>

542

<p>

543

The function outputs the postprocessing results to a file in the PPM/PGM or TIFF format (the format is set via

544

imgdata.params.output_tiff). The results are binary identical to those provided by dcraw.

545

</p>

546

<p>The function returns an integer number in accordance with the <a href=API-notes-eng.html#errors>error

547

code convention</a>: positive if any system call has returned an error, negative (from the

548

<a href=API-datastruct-eng.html#LibRaw_errors>LibRaw error list</a>) if there has been an error situation within

549

LibRaw.

550

</p>

551

552

<h3>int LibRaw::dcraw_thumb_writer(const char *thumbfile)</h3>

553

<p>Writes the thumbnail to a file in the PPM format for bitmap thumbnails and in the JPEG format for JPEG thumbnails, i.e.,

554

in the format completely identical to the results provided by dcraw.

555

</p>

556

<p>The function returns an integer number in accordance with the <a href=API-notes-eng.html#errors>error

557

code convention</a>: positive if any system call has returned an error, negative (from the

558

<a href=API-datastruct-eng.html#LibRaw_errors>LibRaw error list</a>) if there has been an error situation within

559

LibRaw.

560

</p>

561

562

<h2>Copying unpacked data into memory buffer</h2>

563

<p>

564

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

565

<ul>

566

<li><b>dcraw_make_mem_image</b> - store processed image data into allocated buffer;

567

</li>

568

<li><b>dcraw_make_mem_thumb</b> - store extracted thumbnail into buffer as JPEG-file image (for most cameras)

569

or as RGB-bitmap.

570

</li>

571

</ul>

572

For usage primer see samples/mem_image.c sample.

573

</p>

574

575

<h3>libraw_processed_image_t *dcraw_make_mem_image(int *errorcode=NULL) - store unpacked and processed image into

576

memory buffer as RGB-bitmap</h3>

577

<p>

578

This function allocates memory buffer and stores unpacked-preprocessed image into this buffer. Function returns

579

allocated structure <a href="API-datastruct-eng.html#libraw_processed_image_t">libraw_processed_image_t</a> with

580

filled fields. Always returns data as RGB bitmap (i.e. <b>type</b> field is equal to LIBRAW_IMAGE_BITMAP).

581

</p>

582

<p>

583

584

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

585

</p>

586

<p>

587

Returns NULL in case of an error. If caller has passed not-NULL value as errorcode parameter, than *errorcode

588

will be set to error code according to <a href="API-notes-eng.html#errors">error code convention</a>.

589

</p>

590

<p><b>NOTE!</b> Memory, allocated for return value will not be fried at destructor or <b>LibRaw::recycle</b>

591

calls. Caller of dcraw_make_mem_image should free this memory by call to free().

592

</p>

593

594

595

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

596

<p>

597

This function allocates memory buffer and stores thumbnail data in it. Function returns allocated

598

structure <a href="API-datastruct-eng.html#libraw_processed_image_t">libraw_processed_image_t</a> with

599

filled fields. For most RAW images allocated structure will contains JPEG image (i.e. <b>type</b>

600

field is equal to LIBRAW_IMAGE_JPEG). For some cameras with RGB-bitmap thumbnail (Kodak SLRs)

601

returned structure contains RGB bitmap (<b>type</b> field is equal to LIBRAW_IMAGE_JPEG, see structure

602

description for details).

603

</p>

604

<p>

605

unpack_thumb() should be called before dcraw_make_mem_thumb();

606

</p>

607

<p>

608

Returns NULL in case of an error. If caller has passed not-NULL value as errorcode parameter, than *errorcode

609

will be set to error code according to � <a href=API-notes-eng.html#errors>error code convention</a>.

610

</p>

611

<p><b>NOTE!</b> Memory, allocated for return value will not be fried at destructor or <b>LibRaw::recycle</b>

612

calls. Caller of dcraw_make_mem_image should free this memory by call to free().

613

</p>

614

615

616

<h2>Input layer abstraction</h2>

617

618

<h3>class LibRaw_abstract_datastream - abstract RAW read interface</h3>

619

<p>

620

LibRaw reads RAW-data by calling (virtual) methods of C++ object derived from

621

<b>LibRaw_abstract_datastream</b>. This C++ class does not implement any read, but defines interface to be

622

called. Call to base class methods always results in error.

623

</p>

624

625

<h4>LibRaw_abstract_datastream class methods</h4>

626

627

<h5>Object verification</h5>

628

<dl>

629

<dt><b> virtual int valid()</b></dt>

630

<dd>Checks input datastream validity. Returns 1 on valid stream and 0 if datastream was created on non-valid

631

input parameters (wrong filename for file stream and so on).

632

</dd>

633

634

<h5>Stream read and positioning</h5>

635

<p>This group of methods implements file object (FILE*) semantics.</p>

636

<dl>

637

<dt><b>virtual int read(void * ptr,size_t size, size_t nmemb)</b></dt>

638

<dd>

639

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

640

</dd>

641

<dt><b>virtual int seek(off_t o, int whence)</b></dt>

642

<dd>

643

Similar to fseek(file,o,whence).

644

</dd>

645

<dt><b>virtual int tell(</b></dt>

646

<dd>

647

Similar to ftell(file).

648

</dd>

649

<dt><b>virtual int get_char()</b></dt>

650

<dd>

651

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

652

</dd>

653

<dt><b>virtual char* gets(char *s, int n)</b></dt>

654

<dd>

655

Similar to fgets(s,n,file).

656

</dd>

657

<dt><b>virtual int eof()</b></dt>

658

<dd>

659

Similar to feof(file).

660

</dd>

661

<dt><b>virtual int scanf_one(const char *fmt, void *val)</b></dt>

662

<dd>

663

Simplified variant of fscanf(file,fmt,val): format string is always contains one argument to read. So,

664

variable args call is not needed and only one pointer to data passed.

665

</dd>

666

</dl>

667

668

<h5>Other methods</h5>

669

<p>This group of methods includes several supplementary calls. These calls are used to temporary switch to another

670

data stream (file and/or memory buffer).

671

</p>

672

<dl>

673

<dt><b>virtual const char* fname()</b></dt>

674

<dd>

675

Returns name of opened file if datastream object knows it (for example,

676

<b>LibRaw_file_datastream</b> used). Filename used in:

677

<ul>

678

<li>error notofocation callbacks;</li>

679

<li>generation of filename of JPEG-file with metadata when needed (i.e. cameras with 'Diag RAW hack').

680

</ul>

681

</dd>

682

<dt><b>virtual int subfile_open(const char *fn)</b></dt>

683

<dd>

684

This call temporary switches input to file <b>fn</b>. Returns 0 on success and error code on error.<br/>

685

The function used to read metadata from external JPEG file (on cameras with "Diag RAW hack").

686

<br/>

687

This call is not implemented for <a href="#buffer_datastream">LibRaw_buffer_datastream</a>, so

688

external JPEG processing is not possible when buffer datastream used.

689

<br/>

690

This functon should be implemented in real input class, base class call always return error.

691

<br/>

692

Working implementation sample can be found in

693

<a href="#file_datastream">LibRaw_file_datastream</a> implementation in <b>libraw/libraw_datastream.h</b> file.

694

</dd>

695

<dt><b> virtual void subfile_close()</b></dt>

696

<dd>

697

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

698

</dd>

699

<dt><b> virtual int tempbuffer_open(void *buf, size_t size)</b></dt>

700

<dd>

701

This call temporary switches input to <a href="#buffer_datastream">LibRaw_buffer_datastream</a> object,

702

created from <b>buf</b>.<br/>

703

This method is needed for Sony encrypted metadata parser.

704

<p>

705

This call implemented in base class (<b>LibRaw_abstract_datastream</b>), there is no need to

706

reimplement in in derived classes.<br/>

707

Possible activity of temporary datastream requires very accurate programming when implementing

708

datastreams derived from base <b>LibRaw_abstract_datastream</b>. See <a href="#substream">below</a>

709

for more details.

710

</dd>

711

<dt><b> virtual void tempbuffer_close()</b></dt>

712

<dd>

713

This call switch input back from temporary datastream to main stream. This call implemented

714

in base <b>LibRaw_abstract_datastream</b> class.

715

</dd>

716

</dl>

717

718

719

<h3>Derived input classes included in LibRaw</h3>

720

<p>

721

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

722

</p>

723

<ul>

724

<li><a href="#file_datastream">LibRaw_file_datastream</a> implements input from file (in filesystem).</li>

725

<li><a href="#buffer_datastream">LibRaw_buffer_datastream</a> implements input from memory buffer.</li>

726

</ul>

727

<p>

728

LibRaw C++ interface users can implement their own input classes and use them via

729

<a href="#open_datastream">LibRaw::open_datastream</a> call. Requirements and implementation specifics are

730

described below.

731

</p>

732

733

<h4>class LibRaw_file_datastream - file input interface</h4>

734

<p>

735

This class implements input from file.

736

</p>

737

<p><b>Class methods:</b></p>

738

<dl>

739

<dt><b> LibRaw_file_datastream(const char *fname) </b></dt>

740

<dd>

741

This constructor creates <b>LibRaw_file_datastream</b> object from file <b>fname</b>.<br/>

742

Unfortunately, C++ constructor cannot return an error. So if bad filename passed (e.g. nonexistent file)

743

object is created as non-valid (valid() call returns zero).

744

</dd>

745

</dl>

746

<p>

747

All other class methods are <a href="#datastream_methods">described above</a>.<br/>

748

This class implements all possble methods, including fname() and subfile_open().

749

</p>

750

751

<h4>class LibRaw_buffer_datastream - memory buffer input interface</h4>

752

<p>

753

This class implements input from memory buffer.

754

</p>

755

<p><b>Class methods:</b></p>

756

<dl>

757

<dt><b> LibRaw_buffer_datastream(void *buffer, size_t bsize)</b></dt>

758

<dd>

759

This constructor creates datastream object from <b>buffer</b> with size <b>bsize</b>.<br/>

760

It is not possibly to verify the pointer passed, so buffer address is checked against 0 and -1 only.

761

</dd>

762

</dl>

763

<p>

764

All other class methods are <a href="#datastream_methods">described above</a>.<br/>

765

This class does not implement fname() and subfile_open() calls, so external JPEG metadata parsing

766

is not possible.

767

</p>

768

769

<h3>Own datastream derived classes</h3>

770

<p>

771

To create own read interface LibRaw user should implement C++ class derived from

772

<b>LibRaw_abstract_datastream</b> with all read methods.<br/>

773

LibRaw standard implementations may be used as reference. See <b>libraw/libraw_datastream.h</b> file for details

774

(all standard LibRaw input classes are implemented using inline functions only).

775

</p>

776

777

<h4>substream field: secondary input stream</h4>

778

<p>

779

<b>substream</b> field, defined in base LibRaw_abstract_datastream class requires some additional notes.

780

This field is used when input switched to temporary buffer (used for Sony metadata processing). Unfortunately,

781

there is now ideal C++ way to hide this functionality into base class internals. So, any read call in

782

derived class should include 1-line statement like this:<br/>

783

<b>int method(...args...){ if(substream) return substream->method(...args...)</b>. For example:

784

<pre>

785

virtual int eof()

786

{

787

if(substream) return substream->eof();

788

....

789

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

790

{

791

if(substream) return substream->scanf_one(fmt,val);

792

</pre>

793

794

795

796

<a href=index-eng.html>[back to Index]</a>

797

<hr>

798

<address><a href="mailto:info@libraw.org">LibRaw Team</a></address>

799

800

801

Last modified: Fri Apr 9 11:34:30 MSD 2010

802

803

</body>

804

</html>