1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>LibRaw: общие комментарии к API</title>
</head>
<body>
<a href=index-rus.html>[вернуться к оглавлению]</a>
<h1>LibRaw: общие комментарии к API</h1>
<h2>Содержание</h2>
<ol>
<li><a href="#versions">Варианты LibRaw</a></li>
<li><a href="#errors">Соглашения о кодах ошибок и действиях при ошибках</a></li>
<li><a href="#warnings">Нештатные ситуации, не являющиеся ошибкой</a></li>
<li><a href="#io">Абстракция ввода данных</a></li>
<li><a href="threads">Thread safety</a></li>
<li><a href="#CXX">Использование C++</a></li>
<li><a href="#imgdata_params">Параметры структуры LibRaw::imgdata.params, влияющие на поведение
open_file/unpack/unpack_thumb</a></li>
<li><a href="#memory">Использование памяти</a>
<ol>
<li><a href="#stack">Использование стека</a></li>
<li><a href="#memmgr">Управление динамической памятью</a></li>
<li><a href="#memuse">Использование динамической памяти</a>
<ol>
<li><a href="#memraw">Память для хранения RAW-данных</a></li>
<li><a href="#memimage">Память для раскодированного изображения</a></li>
<li><a href="#memthumb">Память для раскодированного thumbnail</a></li>
<li><a href="#memprofile">Память для раскодированного ICC-profile</a></li>
<li><a href="#rawmem">Память для распаковки RAW</a></li>
<li><a href="#mempostproces">Память для постобработки</a></li>
<li><a href="#memwrite">Память для записи файла</a></li>
<li><a href="#memunpack">Память для распаковки в буфер в памяти</a></li>
</ol>
</li>
</ol>
</li>
<li><a href="#incompat">Несовместимости с dcraw</a>
<ol>
<li><a href="#incompat_kodak">Обработка Thumbnails от камер Kodak</a></li>
</ol>
</li>
</ol>
<a name=versions></a>
<h2>Варианты LibRaw</h2>
<p>Начиная с версии 0.9, библиотека LibRaw существует в единственном варианте. Более старые версии
существовали в трех редакциях (основная, облегченная и коммерческая).
</p>
<a name=errors></a>
<h2>Соглашения о кодах ошибок и действиях при ошибках</h2>
<p>
Приняты следующие соглашения о возвращаемых ошибках
</p>
<ol>
<li>Все функции, которые могут вернуть код ошибки имеют целый тип возвращаемых данных.</li>
<li>При отсутствии ошибки возвращается 0 (LIBRAW_SUCCESS).</li>
<li>Если случилась ошибка в системном вызове, то возвращается значение errno (это положительное число), которое
может быть проанализировано с помощью strerror() или подобных средств.</li>
<li>Все собственные коды ошибок LibRaw - отрицательные, при этом ошибки делятся на два типа:
<dl>
<dt><b>Нефатальные ошибки</b></dt>
<dd>
Нефатальные ошибки не запрещают исполнение других функций в последовательности обработки (например,
<a href="API-CXX-rus.html#unpack_thumb">unpack_thumb()</a> вполне может вернуть код, означающий "preview
отсутствует" и это не мешает затем вызвать <a href="API-CXX-rus.html#unpack">unpack()</a>).
</dd>
<dt><b>Фатальные ошибки</b></dt>
<dd>
В случае возникновения фатальной ошибки (нехватка памяти, ошибка во входных данных, невозможность
распаковки данных) текущая стадия обработки завершается, все аллоцированные ресурсы освобождаются.<br/>
В случае попытки продолжения обработки - все последущие вызовы API вернут ошибку
LIBRAW_OUT_OF_ORDER_CALL.<br/>
Вместе с тем, экземпляр LibRaw, в котором возникла фатальная ошибка, может
обрабатывать следущие RAW-файлы обычным образом (вызов
<a href="API-CXX-rus.html#open_file">open_file()</a> (либо
<a href="API-CXX-rus.html#open_datastream">open_datastream()</a>,
<a href="API-CXX-rus.html#open_buffer">open_buffer()</a>)
затем <a href="API-CXX-rus.html#unpack">unpack()</a> и так далее).
</dd>
</dl>
<li>Проверка фатальности ошибки осуществляется макросом LIBAW_FATAL_ERROR(код ошибки)</li>
<li>Коды ошибок <a href="API-datastruct-rus.html#errors">перечислены и расшифрованы здесь</a>.</li>
</ol>
<a name=warnings></a>
<h2>Нештатные ситуации, не являющиеся ошибкой</h2>
<p>В случае возникновения нештатной ситуации, не мешающей получить из файла какие-то данные, о ней будет
просигнализировано путем взведения соответствующего бита в <a
href="API-datastruct-rus.html#libraw_data_t">imgdata.process_warnings</a>. Возможные типы предупреждений <a
href=href="API-datastruct-rus.html#warnings>перечислены и расшифрованы здесь</a>.
</p>
<a name="io"></a>
<h2>Абстракция ввода данных</h2>
<p>
LibRaw использует для чтения файла объект, производный от класса
<a href="API-CXX-rus.html#datastream">LibRaw_abstract_datastream</a>.
Cемантика этого класса схожа с семантикой объектов типа "файл с произвольным позиционированием", объект
реализующий ввод должен поддерживать операции позиционирования и чтения.
</p>
<p>
Для работы с некоторыми форматами, содержащими зашифрованые куски TIFF-каталогов, требуется временное
переключение ввода на временный поток, привязанный к созданному LibRaw буферу в памяти. Эта функциональность
реализуется в базовом классе <a href="API-CXX-rus.html#datastream">LibRaw_abstract_datastream</a> через
имеющеется там поле <b>substream</b>, которое является указателем на объект класса
<a href="API-CXX-rus.html#buffer_datastream">LibRaw_buffer_datastream</a>.
<br/>
При использовании собственных реализаций потоков данных, необходимо в методах чтения и позиционирования
проверять инициализированность этого поля и если оно не нулевое - передавать управление туда. Подробнее
см. реализацию класса
<a href="API-CXX-rus.html#file_datastream">LibRaw_file_datastream</a> в заголовочном файле
<b>libraw/libraw_datastream.h</b>.
</p>
<p>
Если поток данных знает имя обрабатываемого файла в файловой системе, он должен уметь сообщить его всем, кто в
нем нуждается вызовом <b>fname()</b>. Это имя будет использовано при вызове
<a href="API-CXX-rus.html#callbacks">callbacks</a> (уведомителях об ошибках) и может быть использовано для
генерации имени файла с метаданными, если это нужно для распаковываемого формата.
</p>
<p>
Для некоторых форматов данных метаданные (экспозиционные параметры, баланс белого) не хранятся в RAW-файле, но
могут быть считаны из JPEG-версии того же снимка. Если реализация надстройки над
<a href="API-CXX-rus.html#datastream">LibRaw_abstract_datastream</a> умеет вернуть имя обрабатываемого файла при
вызове <b>fname()</b>, то предполагается, что для такой реализации возможно временное переключение потока ввода
на другой файл. Чтобы это было действительно так,
<a href="API-CXX-rus.html#own_datastreams">реализация потока данных</a> должна реализовать методы
<b>subfile_open()/subfile_close()</b>. Стандартные реализации, унаследованные от базового класса, просто
возврашают код ошибки.
<br/>
Пример реализации методов открытия дополнительного потока данных можно подсмотреть в реализации класса
<a href="API-CXX-rus.html#file_datastream">LibRaw_file_datastream</a> в заголовочном файле
<b>libraw/libraw_datastream.h</b>.
</p>
<a name="threads"></a>
<h2>Thread safety</h2>
<p>
Thread safety обеспечивается, если объект LibRaw создается и иcпользуется внутри одного thread. При этом
количество threads (каждая со своим объектом LibRaw) ничем не ограничено (кроме потребностей в памяти).
</p>
<p>
В случае создания объекта LibRaw в одном потоке исполнения, а использования в другом - необходима внешняя
синхронизация, не дающая произвести одновременный доступ к одному объекту.
</p>
<p>
В Unix (Linux/FreeBSD/MacOS) собираются две версии библиотеки: thread-safe версия libraw_r.a и более быстрая
не thread-safe libraw.a.
</p>
<p>
Thread-safe версия использует для хранения локальных данных поля в классе LibRaw, что позволяет иметь несколько
экземпляров класса LibRaw, работающих одновременно.
</p>
<p>
Не thread-safe версия хранит промежуточные данные в глобальных переменных, что несколько быстрее. Не thread-safe
версия может использоваться и в multithreaded-приложениях, но только если экземпляр класса LibRaw гарантированно
один.
</p>
<p>
Под Windows собирается только thread-safe версия.
</p>
<a name="CXX"></a>
<h2>Использование C++</h2>
<p>
При обработке исключительных ситуаций внутри LibRaw используется механизм C++ exceptions. Все исключения
перехватываются внутри функций библиотеки и проникать наружу не должны.
</p>
<p>
Для аллокации/освобождения памяти используются функции malloc(calloc)/free, а не new/delete.
</p>
<p>Какие-либо специфические библиотеки (STL, Boost, smart pointers) - не используются. </p>
<p>При использовании С API ссылки на C++-вызовы new/delete остаются, поэтому линковаться надо с
libstdc++(Unix)/....(Windows).
</p>
<a name="imgdata_params"></a>
<h2>Параметры структуры LibRaw::imgdata.params, влияющие на поведение open_file/unpack/unpack_thumb</h2>
<p>
Большинство полей данных структуры LibRaw::imgdata.params влияют только на <a
href="API-CXX-rus.html#dcrawemu">постобработку данных</a>, но есть ряд исключений, унаследованных текущей
версией LibRaw от особенностей исходных текстов dcraw (постепенно эти зависимости будут удаляться).
<dl>
<dt><b>imgdata.params.use_camera_matrix и imgdata.params.use_camera_wb</b></dt>
<dd>
Влияют на загрузку RAW-данных для камер у которых есть colormatrix.<br/>
<b>Внимание!</b> Если параметр <b>imgdata.params.use_camera_matrix</b> не установлен пользователем, то он
копируется из <b>imgdata.params.use_camera_wb</b> на этапе открытия файла.
</dd>
<dt><b>imgdata.params.user_flip</b></dt>
<dd>
Если этот параметр больше или равен нулю, то на этапе открытия файла
(<a href="API-CXX-rus.html#open_file">open_file()</a> и остальные подобные вызовы)
производится присваивание <code>imgdata.sizes.flip = imgdata.params.user_flip</code>.
</dd>
<dt><b>imgdata.params.shot_select</b></dt>
<dd>
Позволяет выбрать номер извлекаемого изображения для тех форматов данных, где возможно хранение нескольких
RAW-изображений в одном файле данных.
</dd>
<dt><b>imgdata.params.half_size</b></dt>
<dd>
Влияет на загрузку RAW-данных для задников Phase One и Sinar. Кроме того, если установлен этот параметр, то
считывание данных будет производиться в битмэп половинного размера в котором будут заполняться 4 компонента.
</dd>
<dt><b>imgdata.params.threshold, imgdata.params.aber</b></dt>
<dd>
Использование этих параметров (т.е. указание, что будет использоваться, соответственно, wavelet denoising и
исправление аберраций) то чтение данных будет производиться в битмэп половинного размера, у каждого пиксела
будут заполнены вcе 4 компонента (для байеровских матриц).
</dd>
<dt><b>imgdata.params.use_camera_wb</b></dt>
<dd>
Влияет на загрузку матрицы баланса белого для задников Leaf.
</dd>
<dt><b>imgdata.params.document_mode</b></dt>
<dd>
<b>В текущей версии LibRaw не влияет на чтение данных</b>. В dcraw - влияет на данные thumbnails для
некоторых камер Kodak.
</dd>
</dl>
<a name="memory"></a>
<h2>Использование памяти</h2>
<a name="stack"></a>
<h3>Использование стека</h3>
<p>
Экземпляр класса LibRaw имеет собственный размер <b>около 100 килобайт</b>, при использовании конструкций вида
<code>LibRaw imageProcessor;</code> эта память аллоцируется на стеке.
</p>
<p>
Методы класса LibRaw (и вызовы С API) при работе могут аллоцировать до 130-140 килобайт данных на стеке под
автоматические переменные.
</p>
<p>Таким образом, для работы одного экземпляра LibRaw может требоваться около 250 килобайт стека. В большинстве
современных архитектур это не является проблемой, но при использовании LibRaw в multi-threaded-окружении
необходимо не забывать аллоцировать достаточно памяти для стека thread.
</p>
<p>При динамической аллокации (<code>LibRaw *iProcessor = new LibRaw;</code>) требования к памяти на стеке
снижаются (на 100 килобайт - размер экземпляра класса). При использовании <a href="API-C-rus.html">C API</a>
экземпляр LibRaw аллоцируется динамически.
</p>
<a name="memmgr"></a>
<h3>Управление динамической памятью</h3>
<p>LibRaw ведет учет всех блоков аллоцированной динамической памяти, при возникновении исключительной ситуации
(фатальной ошибки) все они освобождаются. Код учета довольно примитивный и не расчитан на аллокацию большого
числа блоков (в обычной ситуации при обработке файла аллокация происходи 2-6 раз), при расширении LibRaw
собственными методами это надлежит учитывать.
</p>
<a name="memuse"></a>
<h3>Использование динамической памяти</h3>
<p>LibRaw использует динамическую память:</p>
<ul>
<li>для извлеченных из файла RAW-данных;</li>
<li>для постобработки изображения;</li>
<li>для раскодированного thumbnail;</li>
<li>для извлеченного из RAW-файла ICC-профиля (если он там есть);</li>
<li>для временных данных на этапе распаковки RAW-файла;</li>
<li>для временных данных на этапе постобработки и записи результата;</li>
<li>для чтения исходного RAW-файла (только на Win32)</li>
</ul>
<a name="memraw"></a>
<h4>Память для хранения RAW-данных</h4>
<p>
Извлеченные из файла RAW-данные хранятся в формате:
</p>
<ul>
<li>16-битное целое на пиксель для "байеровских" (1 цвет на пиксель) камер. Если у RAW-изображения есть черная
рамка, она хранится вместе с изображением.
</li>
<li>4 16-битных целых для полноцветных изображений (Foveon, Linear DNG, Canon sRAW и т.п.). Полноцветные
изображения бывают как 3, так и 4-цветные, все они хранятся в виде 4 компонента на пиксел, для трехцветных
изображений четвертый компонент будет нулевым.
</li>
</ul>
<p>Буфер для раскодированного изображения аллоцируется при вызове <a
href="API-CXX-rus.html#unpack">unpack()</a> и
освобождается при <a href="API-CXX-rus.html#recycle">recycle()</a>.
</p>
<a name="memimage"></a>
<h4>Память для постобработки изображения</h4>
<p>
<b>Для каждого пикселя при постобработке отводится 4 16-битных компонента</b>
<b>Таким образом, размер памяти под буфер изображения в 6-10 раз превышает размер исходного RAW-файла (с учетом
сжатия RAW-данных).</b><br/>
</p>
<p>Буфер для раскодированного изображения аллоцируется при вызове
<a href="API-CXX-rus.html#dcraw_process">dcraw_process()</a>,
<a href="API-CXX-rus.html#dcraw_document_mode_processing">dcraw_document_mode_processing()</a>,
или <a href="API-CXX-rus.html#raw2image">raw2image()</a> и
освобождается при <a href="API-CXX-rus.html#recycle">recycle()</a> или
<a href="API-CXX-rus.html#free_image">free_image()</a>
</p>
<a name="memthumb"></a>
<h4>Память для раскодированного thumbnail</h4>
<p>
Память для thumbnail аллоцируется при вызове <a href="API-CXX-rus.html#unpack_thumb">unpack_thumb()</a> и
освобождается при <a href="API-CXX-rus.html#recycle">recycle()</a>. Аллоцируется буфер размером ровно под
thumbnail т.е. до нескольких мегабайт.
</p>
<a name="memprofile"></a>
<h4>Память для раскодированного ICC-profile</h4>
<p>
Память для ICC-профиля аллоцируется при вызове <a href="API-CXX-rus.html#unpack_profile">unpack_profile()</a> и
освобождается при <a href="API-CXX-rus.html#recycle">recycle()</a>. Аллоцируется буфер размером ровно под
размер ICC-профиля т.е. до нескольких сотен килобайт.
</p>
<a name="rawmem"></a>
<h4>Память для распаковки RAW</h4>
<p>
Память для временных буферов, нужных при распаковке RAW-данных может быт аллоцирована во время работы <a
href="API-CXX-rus.html#unpack">unpack()</a> и освобождается до завершения этой функции. Размеры аллоцированных
буферов невелики, в пределах нескольких десятков килобайт.
</p>
<a name="mempostproces"></a>
<h4>Память для постобработки</h4>
<p>При постобработке изображений (унаследованной от dcraw) выделяется память под гистограмму (128 килобайт). Эта
память выделяется при вызове <a
href="API-CXX-rus.html#dcraw_document_mode_processing">dcraw_document_mode_processing()</a> и
<a href="API-CXX-rus.html#dcraw_process">dcraw_process()</a>, а освобождается при вызове
<a href="API-CXX-rus.html#recycle">recycle()</a>.
</a>
<p>
Помимо этого, при работе <a href="API-CXX-rus.html#dcraw_process">dcraw_process()</a> и использовании ряда
имеющихся возможностей:
</p>
<ul>
<li>ротации изображений с камер FUJI;</li>
<li>коррекции хроматических аберраций;</li>
<li>изменении размеров изображения (включая случаи коррекции неквадратного пиксела);</li>
<li>highlight recovery;</li>
</ul>
<p>
будет аллоцирован временный буфер, размер которого равен размеру результирующего изображения (из расчета 6-8
байт на пиксел для разных стадий обработки). При завершении промежуточной подстадии обработки, буфер с
предыдущей копией изображения будет освобожден.<br/>
Если постобработка не используется, то временные буферы не аллоцируются.
</p>
<a name="memwrite"></a>
<h4>Память для записи файла</h4>
<p>
Вызов <a href="API-CXX-rus.html#dcraw_ppm_tiff_writer">dcraw_ppm_tiff_writer()</a> аллоцирует память под одну
строку выходного изображения. Аллоцированная память освобождается перед выходом из вызова.
</p>
<a name="memunpack"></a>
<h4>Память для распаковки в буфер в памяти</h4>
<p>
Вызовы <a href="API-CXX-rus.html#dcraw_make_mem_image">dcraw_make_mem_image()</a> и
<a href="API-CXX-rus.html#make_mem_thumb">dcraw_make_mem_thumb()</a> (и их аналоги в C-API)
аллоцируют дополнительную память в объеме, необходимом для хранения выводимых данных (изображения
и thumbnail, соответственно).<b>Освобождение этой памяти - задача вызывающей функции</b>.
</p>
<a name="incompat"></a>
<h2>Несовместимости с dcraw</h2>
<a name="incompat_kodak"></a>
<h3>Обработка Thumbnails от камер Kodak</h3>
<p>В ряде камер Kodak preview (thumbnail) хранится в виде нескорректированного изображения. При извлечении его с
помощью <b>dcraw -e</b> используются те же настройки баланса белого, коррекции цветов и так далее, что и для
извлечения основных RAW-данных (включая удаление дефектов и вычитание dark frame, что ошибочно т.к. размер
изображения другой).
<br/>
В вызове LibRaw::unpack_thumb() всегда используется баланс белого, взятый из камеры (as shot), какие-либо
настроки из imgdata.params не используются.
</p>
<p>
Для Всех остальных камер thumbnails извлекаются as-is, без каких-либо цветовых
преобразований, как в dcraw, так и в LibRaw.
</p>
<a href=index-rus.html>[вернуться к оглавлению]</a>
<hr>
<address><a href="mailto:info@libraw.org">LibRaw Team</a></address>
<!-- Created: Sun Mar 16 10:05:08 MSK 2008 -->
<!-- hhmts start -->
Last modified: Mon Jul 11 13:40:10 MSD 2011
<!-- hhmts end -->
</body>
</html>
|
