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
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
|
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!-- The babl webpage is partially autogenerated
-->
<html>
<head>
<title>babl-@BABL_VERSION@</title>
<link rel="icon" href="graphics/babl-16x16.png" type="image/png" />
<link rel="shortcut icon" href="graphics/babl-16x16.png" type="image/png" />
<style type='text/css'>
@import url(babl.css);
</style>
<script type='text/javascript'>
function hide(id)
{
(document.getElementById(id)).style.display = "none";
}
function show(id)
{
(document.getElementById(id)).style.display = "block";
}
function get_visible (id)
{
var element = document.getElementById(id);
if (element &&
element.style.display &&
element.style.display != "none")
return true;
return false;
}
function set_visible (id, visible)
{
var element = document.getElementById(id);
if (element)
{
if (visible)
element.style.display = "block";
else
element.style.display = "none";
}
}
function toggle_visible (id)
{
if (get_visible(id))
set_visible(id, false);
else
set_visible(id,true);
}
</script>
</head>
<body>
<div class='print'>
<div class='print_title'>
<h1>Babl-@BABL_VERSION@</h1>
</div>
</div>
<div class='toc'>
<div class='print'>
<h3>Contents</h3>
</div>
<ul>
<li><a href='#Babl'>Babl</a></li>
<li><a href='#Features'> Features</a></li>
<li><a href='#Download'>Download</a></li>
<!--<li><a href='#Background'>Background</a></li>-->
<li><a href='#Documentation'>Documentation</a></li>
<li><a href='#Usage'> Usage</a></li>
<li><a href='#Vocabulary'> Vocabulary</a></li>
<!--<li><a href='#Data-types'> Data types</a></li>
<li><a href='#Color-models'> Color models</a></li>
<li><a href='#Pixel-formats'> Pixel formats</a></li>-->
<li><a href='#Shortcut_coverage'> Shortcut Coverage</a></li>
<li><a href='#Environment'> Environment</a></li>
<li><a href='#Extending'> Extending</a></li>
<li><a href='#DirectoryOverview'> Directory Overview</a></li>
<!--<li><a href='#ColorManagement'>Color Management</a></li>-->
<li><a href='#TODO'>Todo</a></li>
<li><a href='#Copyright'>Copyright</a></li>
<li><a href='#Authors'> Authors</a></li>
</ul>
</div>
<div><a name='Babl'></a></div>
<div class='paper'>
<div class='content'>
<!--<h1>Babl</h1>-->
<p>
<br/> <!-- FIXME: should be in CSS -->
<strong>babl is a dynamic, any to any, pixel format translation library</strong>.
<br/>
</p>
<p>It allows converting between different methods of storing <a href='http://en.wikipedia.org/wiki/Pixel'>pixels</a> known as <em>pixel formats</em> that have
with different bitdepths and other data representations, color models and
component permutations.</p>
<p> A vocabulary to formulate new <em>pixel formats</em> from existing
primitives is provided as well as the framework to add new color models and
data types.
</p>
<!--<a name='Background'></a>
<h2>Background</h2>
<p> When creating various libraries and small tools that deal with
computer graphics I have often created functions for converting
raster images between different representations.
</p>
<p>Libraries to help with such conversions already do exist, but no
extendable candidates have surfaced in my searches.
</p>
<p>The vocabulary developed in babl will most likely be part of
<a href='http://www.gegl.org/'>GEGL</a>'s vocabulary to describe image
buffers.
</p>-->
<a name='Features'></a>
<h2>Features</h2>
<ul>
<li>Fast.</li>
<li>Accurate.</li>
<li>Stable, small API.</li>
<li>Self profiling and optimizing.</li>
<li>ANSI C, works on win32, linux and mac, 32bit and 64bit systems.</li>
<li>Extendable with new formats, color models, components
and datatypes.</li>
<li>Reference 64bit floating point conversions for datatypes and color models.</li>
</ul>
<p><a href='http://www.gegl.org/'>GEGL</a> through <a
href='http://www.gegl.org/api.html#GeglBuffer'>GeglBuffer</a> provides
tiled buffers with on disk storage as well as linear buffers with accessor
functions for efficient data access transparently using babl fishes for
translation to the desired pixel formats.</p>
<a name='Download'></a>
<h2>Download</h2>
<p>The latest versioned development version of babl can be found in
<a href='ftp://ftp.gtk.org/pub/babl/'>ftp://ftp.gtk.org/pub/babl/</a>.
</p>
<p>Babl uses git. The main repository is hosted by GNOME.
It can be <a href='http://git.gnome.org/cgit/babl'>browsed online</a> and cloned with:
</p>
<pre>git clone git://git.gnome.org/babl</pre>
<p>The following is a list of the major changes that have gone into
each babl release. If there are significant improvements to babl when
a GEGL release is done a babl release is most often put out just prior
to the GEGL release.</p>
<!--NEWS-->
For more news see git log.
<a name='Documentation'></a>
<h2>Documentation</h2>
<p>When using BablFishes to do your conversions, you request a fish to
convert between two formats, and an optimal fish to babls capability is
provided that you can use to do your conversions. Babl also provides
the capability to describe new formats based on a vocabulary of user
registered color models and data types.
</p>
<p>Babl provides a base vocabulary in BablBase and some extensions
that are thought to be generally useful.</p>
<p>When performing further extensions to the vocabulary of babl, the
internal consistency is governed by reference conversions that operate
on <em>double</em> (64 bit floating point values). The only color model
created during BablCore bootstrap is <em>RGBA</em> (linear light RGB,
0.0 - 1.0, with a linear 0.0 - 1.0 opacity channel) backed by the
<em>double</em> datatype. Defined similarily to <a
href='http://en.wikipedia.org/wiki/ScRGB_color_space'>scRGB</a> using
64bit floating point.
</p>
<p>If babls conversion isn't fast enough, you can provide
your own conversion shortcut between two formats. The registered
shortcut might also be used by babl as an intermediate conversion when
constructing BablFishes for other conversions.
</p>
<p>Babl extensions are shared objects. If you have already developed
some fast conversion functions, wrapping them as babl extensions should
not take much time and will speed up babl for other users as well.
</p>
<a name='Usage'></a>
<h3>Usage</h3>
<pre
><span class='function'>babl_process</span> <span class='paren'>(</span><span class='function'>babl_fish</span> <span class='paren'>(</span>source_format, destination_format<span class='paren'>)</span>,
source_buffer, destination_buffer,
pixel_count<span class='paren'>);</span></pre>
<p>The processing operation that babl performs is copying including
conversions if needed between linear buffers containing the same count
of pixels, with different pixel formats.
</p>
<pre>
int width = 123, height = 581, pixel_count = width * height;
const Babl *srgb = <span class='function'>babl_format</span> <span class='paren'>(</span><span class='string'>"R'G'B' u8"</span><span class='paren'>)</span>;
const Babl *lab = <span class='function'>babl_format</span> <span class='paren'>(</span><span class='string'>"CIE Lab float"</span><span class='paren'>)</span>;
Babl *rgb_to_lab_fish = <span class='function'>babl_fish</span> <span class='paren'>(</span>srgb, lab);
float *lab_buffer;
unsigned char *srgb_buffer;
babl_init <span class='paren'>()</span>;
srgb_buffer = malloc (pixel_count * babl_format_get_bytes_per_pixel (srgb));
lab_buffer = malloc (pixel_count * 3 * sizeof (float));
...... load data into srgb_buffer .......
<span class='function'>babl_process</span> <span class='paren'>(</span>rgb_to_lab_fish, srgb_buffer, lab_buffer, pixel_count<span class='paren'>);</span>
...... do operation in lab space ........
<span class='function'>babl_process</span> <span class='paren'>(</span><span class='function'>babl_fish</span><span class='paren'>(</span>lab, srgb<span class='paren'>)</span>,
lab_buffer, srgb_buffer, pixel_count<span class='paren'>);</span>
/* the data has now been transformed back to srgb data */</pre>
<p>If the existing pixel formats are not sufficient for your conversion
needs, new ones can be created on the fly. The constructor
will provide the prior created one if duplicates are registered. </p>
<pre
>const Babl *format = <span class='function'>babl_format_new</span> <span class='paren'>(</span><span class='function'>babl_model</span> <span class='paren'>(</span><span class='string'>"R'G'B'"</span><span class='paren'>)</span>,
<span class='function'>babl_type</span> <span class='paren'>(</span><span class='string'>"u16"</span><span class='paren'>)</span>,
<span class='function'>babl_component</span> <span class='paren'>(</span><span class='string'>"B'"</span><span class='paren'>)</span>,
<span class='function'>babl_component</span> <span class='paren'>(</span><span class='string'>"G'"</span><span class='paren'>)</span>,
<span class='function'>babl_component</span> <span class='paren'>(</span><span class='string'>"R'"</span><span class='paren'>)</span>,
<span class='NULL'>NULL</span><span class='paren'>);</span></pre>
<!--
<p>Instead of a linear buffer you can an image descriptor which desribes the start of the memory segment, the pitch in bytes between samples, and the rowstride (not used yet,
use 0 to indicate unlimited for compatibility with future API.)
</p>
<pre
><span class='function'>babl_process</span> <span class='paren'>(</span><span class='function'>babl_fish</span> <span class='paren'>(</span><span class='string'>"srgb"</span>, <span class='string'>"Y'CbCr u8"</span><span class='paren'>)</span>,
srgb_buffer,
<span class='function'>babl_image</span> <span class='paren'>(</span><span class='function'><span class='string'>"Y'"</span>, luma_buffer, 1, 0,
<span class='string'>"Cb"</span>, cb_buffer, 1, 0,
<span class='string'>"Cr"</span>, cr_buffer, 1, 0,
<span class='NULL'>NULL</span><span class='paren'>)</span>,
pixel_count<span class='paren'>);</span>
</pre>
-->
<a name='Vocabulary'></a>
<h3 style='margin-bottom:0em;'>Vocabulary</h3>
<!--BablBase-->
<!--
<a name='Extensions'></a>
<h3>Extensions</h3>
<p>
At compile, load, and runtime; babl is extendable with:
</p>
<ul>
<li>data types.</li>
<li>color models.</li>
<li>pixel formats.</li>
<li>optimized conversion functions:
<dl>
<dt>SIMD instructions</dt>
<dd>MMX, SSE, Altivec ...</dd>
<dt>External libraries</dd>
<dd>liboil, hermes, libavcodec, lcms, ...</li>
</dl>
</li>
</ul>-->
<a name='Shortcut_coverage'></a>
<h3>Shortcut Coverage</h3>
<p>The diagram shown below visualizes the coverage of current shortcut
conversions. Dots indicate a direct conversion is provided for, the height
of the bar indicates the number of conversions steps needed in a chain of
conversions.
A <a href='BablFishPath.html'>DHTML version</a> is also available.
</p>
<pre style='font-size:50%;height:30em;overflow:scroll'>
<!--BablFishPath-->
</pre>
<a name='Environment'></a>
<h2>Environment</h2>
<p>If the environment variable <tt>BABL_STATS</tt> is set containting
a html pixel format conversion usage matrix will be written to
<tt>/tmp/babl-stats.html</tt>. This allows figuring out which
conversions is taking up time during processing, and what shortcuts <a
href='#Extending'>extensions</a> might be created or improved to
make babl do it's job faster.
</p>
<p>Through the environment variable <tt>BABL_TOLERANCE</tt> you can control
a speed/performance trade off that by default is set very low (0.000001)
values in the range 0.01-0.1 can provide reasonable preview performance
by allowing lower numerical accuracy</p>.
<a name='Extending'></a>
<h2>Extending</h2>
<p>For samples of how the current internal API specification of
data types, color models, and conversions look in the <tt><a href='http://git.gnome.org/cgit/babl/tree/extensions'>extensions/</a></tt>
directory. The tables in this HTML file is directly generated
based on the data registered by BablCore (double and RGBA), BablBase
(core datatypes, and RGB models), extensions (CIE Lab, naive CMYK,
various shortcut conversions).<!--The API's used are very
similar in style to the API's described under the <a href='#Usage'>Usage section</a>.-->
</p>
<a name='DirectoryOverview'></a>
<h2>Directory Overview</h2>
<pre><tt>babl-dist-root
│
├──babl the babl core
│ └──base reference implementations for RGB and Grayscale Color Models,
│ 8bit 16bit, and 32bit and 64bit floating point.
├──extensions CIE-Lab color model as well as a naive-CMYK color model.
│ also contains a random cribbage of old conversion optimized
│ code from gggl. Finding more exsisting conversions in third
│ part libraries (hermes, lcms?, liboil?) could improve the
│ speed of babl.
├──tests tests used to keep babl sane during development.
└──docs Documentation/webpage for babl (the document you are reading
originated there.</tt></pre>
<!--
<div class='screen'>
<p>You can also <a href='source-local.html'>browse the source</a> for
the version this website was built. </p>
</div>
-->
<!--
<a name='ColorManagement'></a>
<h2>Color Management</h2>
<p> Babl is not a color management system, since it doesn't deal with
ICC profiles. Babl is designed primarily for internal use when the
color space is already known (sRGB, CIE Lab, Luminance or similar).</p>
<p>
It is also possible to register new color models that are managed by a
color management system like <em>lcms</em>, take a look at the <em>lcms-lab</em>
extensions for an example.</p>
-->
<a name='TODO'></a>
<!--TODO-->
<a name='Copyright'></a>
<h2>Copyright</h2>
<p> Babl is free software; you can redistribute it and/or modify it
under the terms of the <a href='COPYING.LESSER'>GNU Lesser General Public
License</a> as published by the Free Software Foundation; either
version 3 of the License, or (at your option) any later version. </p>
<a name='Authors'></a>
<h3>Authors</h3>
<!--AUTHORS-->
<a href='graphics/index.html'><img class='BablFish' alt='/babl-@BABL_VERSION@' title='babl-@BABL_VERSION@' src='graphics/babl-48x48.png'/></a>
</div>
</div>
<div class='graphic'>
<div class='print'>
<img src='graphics/babl-a4poster.png' alt=' '/>
</div>
</div>
</body>
</html>
|
