<?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</title>
    <meta http-equiv="content-type" content="text/html;charset=utf-8" />

    <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>
  </head>
  <body>

    <div class='print'>
      <div class='print_title'>
        <h1>Babl</h1>
      </div>
    </div>
<!--TOC-->


<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 pixel encoding and color space conversion engine in C</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, color spaces 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,
   spaces and data types.  </p>

    <a name='Features'></a>
    <h2>Features</h2>

    <ul>
      <li>Dynamically extendable with new formats, color models, components and datatypes, and SIMD code paths.</li>
      <li>Reference 64bit floating point conversions for datatypes and color
          models, with 32bit floating point reference speed-ups in some places.
      </li>
      <li>Runtime profiling/validating and code-path optimizing with persistence of profiling data across runs, with caching of results.</li>
        <li>Can load <a href='ColorManagement.html'>Color Spaces</a> from ICC v2 and v4 profiles containing RGB matrix + TRC and with lcms2 dependency also <a
href='CMYK.html'>CMYK</a> profiles.</li>
      <li>Uses <a href='UnifiedAlpha.html'>Unified Alpha</a> conversions for conversions between separate and associate alpha, avoiding loss of color fidelity due to asymptotic behavior when dividing by 0.0 in floating point.</li>
      <li>Portable self contained C code working on win32, linux, bsds and mac
on 32bit and 64bit systems.</li>
      <li>Stable, small API, with singleton objects returned.</li>
    </ul>

    <p>The pixel data storage in <a href='https://www.gimp.org/'>GIMP</a> uses
<a href='http://www.gegl.org/'>GEGL</a>'s GeglBuffer which internally stores
tiles and provides an API for retrieving and storing pixel data with implicit
conversions using babl formats.
    </p>

    <a name='Download'></a>
    <h2>Download</h2>

    <p>The latest versioned development version of babl can be found in
    <a href='https://download.gimp.org/pub/babl/'>https://download.gimp.org/pub/babl/</a>.
    </p>

    <p>Babl uses git. The main repository is hosted by GNOME.
    It can be <a href='https://gitlab.gnome.org/GNOME/babl/'>browsed online</a> and cloned with:
    </p>
    <pre>git clone https://gitlab.gnome.org/GNOME/babl.git/</pre>

    <a name='News'></a>
    <h2>News</h2>

    <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-->
    
    <p>For more detailed changes see git log.</p>


    <a name='Usage'></a>
    <h2>Usage</h2>
    <p>Most users of babl do not know they are using babl and it is GIMP itself
    which uses babl, this is documentation for such uses - and others that might
    want to use babl for pixel format or color space conversion in other software.
</p>

    <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). Color Spaces can
    be created from chromaticity coordinates or ICC profiles. The reference
    color space - to maintain fast and bit-accurate conversions on with
    sRGB is similar to <a
    href='http://en.wikipedia.org/wiki/ScRGB_color_space'>scRGB</a> using
    64bit floating point.
    </p>

    <p>To speed up operations, fast path conversions are used.
    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>

        <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>;
const Babl *srgb_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>srgb_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
        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='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='Environment'></a>
    <h2>Environment</h2>

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

    <p><tt>BABL_PATH</tt> contains the path of the directory, containing the .so extensions to babl.
    </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='https://gitlab.gnome.org/GNOME/babl/tree/master/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.
 ├──tools      various commandline tools used for verifying accuracy of extensions.
 ├──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='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>
  <h2>Authors</h2>

<!--AUTHORS-->          
     
        <a href='graphics/index.html'><img class='BablFish' alt='babl' title='babl' src='graphics/babl-48x48.png'/></a>
      </div>
    </div>
    <div class='graphic'>
      <div class='print'>
        <img src='graphics/babl-a4poster.png' alt=' '/>
      </div>
    </div>

  </body>
