[babl] docs: add section about symmetric alpha transforms
- From: Øyvind "pippin" Kolås <ok src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [babl] docs: add section about symmetric alpha transforms
- Date: Wed, 19 Jun 2019 12:08:53 +0000 (UTC)
commit 3ebf0dfb3eff341f3471cffecbdd7e087d5b8893
Author: Øyvind Kolås <pippin gimp org>
Date: Wed Jun 19 14:04:26 2019 +0200
docs: add section about symmetric alpha transforms
docs/index-static.html.in | 233 +++++++++++++++++++++++-----------------------
1 file changed, 114 insertions(+), 119 deletions(-)
---
diff --git a/docs/index-static.html.in b/docs/index-static.html.in
index 207a620..17c33a0 100644
--- a/docs/index-static.html.in
+++ b/docs/index-static.html.in
@@ -69,14 +69,12 @@
<h3>Contents</h3>
</div>
<ul>
- <li><a href='#Babl'>Babl</a></li>
+ <li><a href='#Download'> Download</a></li>
<li><a href='#Features'> Features</a></li>
+ <li><a href='#ColorManagement'> Color Management</a></li>
<li><a href='#Symmetric-Alpha'> Symmetric-Alpha</a></li>
<li><a href='#CMYK'> CMYK</a></li>
- <li><a href='#ColorManagement'> Color Management</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>
@@ -87,8 +85,9 @@
<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='#TODO'> Todo</a></li>
+
+ <li><a href='#Copyright'> Copyright</a></li>
<li><a href='#Authors'> Authors</a></li>
</ul>
</div>
@@ -119,19 +118,15 @@
<li>ANSI C without external dependencies, works on win32, linux and mac,
32bit and 64bit systems.</li>
<li>Stable, small API, with singleton objects returned.</li>
- <li>Extendable with new formats, color models, components
- and datatypes.</li>
+ <li>Extendable with new formats, color models, components and datatypes.</li>
<li>Can load <a href='#ColorManagement'> Color
-Spaces</a></li> rom ICC v2 and v4 profiles containing RGB matrix + TRC, or <a
+Spaces</a></li> from ICC v2 and v4 profiles containing RGB matrix + TRC, or <a
href='#CMYK'>CMYK</a> profiles.</li>
<li><a href='#Symmetric-Alpha'>Symmetric-Alpha</a> no loss of color fidelity due to asymptotic
behavior near alpha 0.0 in floating point.</li>
<li>Reference 64bit floating point conversions for datatypes and color
models, with 32bit floating point reference speed-ups in some places.
</li>
- <li>Self profiling/validating and optimizing, optimizing accuracy and
-performance at runtime when the best performing single or multi-step conversion
-path is chosen. This permits additional SIMD optimiations paths to be added and
-to ones supported are competing with each other.</li>
+ <li>Runtime profiling/validating and code-path optimizing with persistence of profiling data across
runs, with caching of results.</li>
</ul>
<p><a href='http://www.gegl.org/'>GEGL</a> through <a
@@ -163,8 +158,112 @@ to ones supported are competing with each other.</li>
<!--NEWS-->
For more news see git log.
- <a name='Documentation'></a>
- <h2>Documentation</h2>
+
+ <a name='ColorManagement'></a>
+ <h2>Color Management</h2>
+
+ <p>All pixel formats in babl have a specified color space, if NULL is passed
+as a space constants for (unbounded) linear sRGB data is assumed, data being
+sRGB defines the conversion to and from gray-scale as well as the gamma
+ - or Transfer Response Curve, TRC, used for converting between linear and
+ non-linear variants of the data.</p>
+
+ <p>babl has API for creating a format for a specific space:
+<tt>babl_format_with_space("R'G'B' u16", babl_space ("Rec2020"))</tt> creates a
+16 bit integer format for the Rec2020 color space. Babl knows internally about
+"sRGB", "Rec2020", "Adobe", "Apple", "ProPhoto", "ACEScg" and "ACES2065-1"
+spaces, as they are defined with constants on their wikipedia pages or similar upstream references.</p>
+
+ <p>Additional spaces can be loaded from monitor-class matrix+TRC ICC v2 and
+ v4 profiles. Using babl_icc_make_space (see babl.h for details). The space of
+ a babl format can also be queried with babl_format_get_space.
+ </p>
+
+ <a name='Symmetric-Alpha'></a>
+ <h2>Symmetric transformations for floating point alpha</h2>
+
+
+ <p> babl clamps the alpha used when going from separate alpha to associated
+alpha or from associated alpha to separate alpha to BABL_ALPHA_FLOOR. This
+replaces asymptotic behavior and direct precision loss of color precision when
+multiplying or dividing by alphas near 0.0 with a consistent symmetric
+transformation.</p>
+
+<p>Original intent of data as well as non-asymptotic precision loss is thus
+maintained when the processing chain might temporarily use the other alpha
+representation.</p>
+
+<pre>
+ #define BABL_ALPHA_FLOOR (1.0/65536.0)
+ #define BABL_ALPHA_FLOOR_F (1.0f/65536.0f)
+</pre>
+
+<p>The deviation from not clamping near 0.0 is within the quantization margin
+of 16bit integer alpha, thus no adaptations for any SIMD or and similar 8bit
+and 16bit extensions of pixel format conversions are needed.
+ </p>
+
+ <p>This is the clamping function in use:</p>
+<pre>
+static inline float
+babl_epsilon_for_zero_float (float value)
+{
+ if (value <= BABL_ALPHA_FLOOR_F)
+ {
+ /* for performance one could directly retun BABL_ALPHA_FLOOR_F here
+ and dropping handling negative values consistently. */
+ if (value >= 0.0f)
+ return BABL_ALPHA_FLOOR_F;
+ else if (value >= -BABL_ALPHA_FLOOR_F)
+ return -BABL_ALPHA_FLOOR_F;
+ }
+ return value; /* most common case, return input value */
+}
+</pre>
+<p>And an example use of this clamping function that is consistent with babls behavior:</p>
+<pre>
+static inline void
+associated_to_separate_rgba (const float *associated_rgba,
+ float *separate_rgba)
+{
+ float alpha = associated_rgba[3];
+ float clamped_alpha = babl_epsilon_for_zero_float (alpha);
+ float reciprocal_alpha = 1.0f / clamped_alpha;
+
+ separate_rgba[0] = associated_rgba[0] * reciprocal_alpha;
+ separate_rgba[1] = associated_rgba[1] * reciprocal_alpha;
+ separate_rgba[2] = associated_rgba[2] * reciprocal_alpha;
+ separate_rgba[3] = alpha;
+}
+</pre>
+
+
+<p>For more detils see <a
href='https://gitlab.gnome.org/GNOME/babl/commit/a4d607843d3cab18745d547fc8a46dec51dcea5e'>the commit message
of the most recent refinement</a> as well as <a
href='https://www.patreon.com/posts/premultiplied-in-21014115'>blog post with further background</a>.</p>
+
+
+ <a name='CMYK'></a>
+ <h2>CMYK</h2>
+
+ <p>CMYK handling is done using babl-spaces created with ICC profiles
+containing CMYK profiles. BablSpaces for these ICC profiles handle color conversions using lcms2 - or if
compiled without lcms2 support a naive profile independent fallback.</p>
+ <p>When a babl space derived from a CMYK ICC profile is used to instantiate
+RGB formats, the resulting formats are using the default/NULL space for
+primaries and TRCs.</p>
+
+ <p>The CMYK formats that use lcms2 for color interchange with the rest of
+babl are the following, which are available for all data types, u8, u16, half
+and float:</p>
+ <dl>
+ <dt>CMYK</dt><dd>Cyan Magenta Yellow Key, with 0 being white and 1.0 full ink coverage.</dd>
+ <dt>CMYKA</dt><dd>as previous, with separate alpha channel</dd>
+ <dt>CaMaYaKaA</dt><dd>as previous but associated alpha</dd>
+ <dt>cmyk</dt><dd>inverted CMYK, where 0.0 is full ink coverage and 1.0 is none</dd>
+ <dt>cmykA</dt><dd>as previous, with separate alpha channel</dd>
+ <dt>camayakaA</dt><dd>as previous but associated alpha</dd>
+ </dl>
+
+ <a name='Usage'></a>
+ <h2>Usage</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
@@ -195,9 +294,6 @@ conversion when constructing BablFishes for other conversions.
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,
@@ -261,107 +357,6 @@ lab_buffer = malloc (pixel_count * 3 * sizeof (float));
</pre>
-->
- <a name='ColorManagement'></a>
- <h2>Color Management</h2>
-
- <p>All pixel formats in babl have a specified color space, if NULL is passed
-as a space constants for (unbounded) linear sRGB data is assumed, data being
-sRGB defines the conversion to and from gray-scale as well as the gamma
- - or Transfer Response Curve, TRC, used for converting between linear and
- non-linear variants of the data.</p>
-
- <p>babl has API for creating a format for a specific space:
-<tt>babl_format_with_space("R'G'B' u16", babl_space ("Rec2020"))</tt> creates a
-16 bit integer format for the Rec2020 color space. Babl knows internally about
-"sRGB", "Rec2020", "Adobe", "Apple", "ProPhoto", "ACEScg" and "ACES2065-1"
-spaces, as they are defined with constants on their wikipedia pages or similar upstream references.</p>
-
- <p>Additional spaces can be loaded from monitor-class matrix+TRC ICC v2 and
- v4 profiles. Using babl_icc_make_space (see babl.h for details). The space of
- a babl format can also be queried with babl_format_get_space.
- </p>
-
- <a name='Symmetric-Alpha'></a>
- <h2>Symmetric transformations for floating point alpha</h2>
-
-
- <p>
- babl clamps the alpha used when going from separate alpha to associated alpha
-or from associated alpha to separate alpha to BABL_ALPHA_FLOOR. This avoids
-asymptotic behavior and direct precision loss of color precision when multiplying or dividing by alphas near
0.0.</p>
-
-<p>Original intent of data as well as non-asymptotic precision loss is thus
-maintained when the processing chain might temporarily use the other alpha
-representation.</p>
-
-<pre>
- #define BABL_ALPHA_FLOOR (1.0/65536.0)
- #define BABL_ALPHA_FLOOR_F (1.0f/65536.0f)
-</pre>
-
-<p>The deviation from not clamping near 0.0 is within the quantization margin
-of 16bit integer alpha, thus no adaptations of are introduced for the 8bit and 16bit versions of pixel
format conversions were needed.
- </p>
-
- <p>This is the clamping function:</p>
-<pre>
-
- static inline float
- babl_epsilon_for_zero_float (float value)
- {
- if (value <= BABL_ALPHA_FLOOR_F)
- {
- /* for performance one could directly retun BABL_ALPHA_FLOOR_F here
- and dropping handling negative values consistently. */
- if (value >= 0.0f)
- return BABL_ALPHA_FLOOR_F;
- else if (value >= -BABL_ALPHA_FLOOR_F)
- return -BABL_ALPHA_FLOOR_F;
- }
- return value; /* most common case, return input value */
- }
-</pre>
-<p>And an example use of this clamping function that is consistent with babls behavior:</p>
-<pre>
- static inline void
- associated_to_separate_rgba (const float *associated_rgba,
- float *separate_rgba)
- {
- float alpha = associated_rgba[3];
- float clamped_alpha = babl_epsilon_for_zero_float (alpha);
- float reciprocal_alpha = 1.0f / clamped_alpha;
-
- separate_rgba[0] = associated_rgba[0] * reciprocal_alpha;
- separate_rgba[1] = associated_rgba[1] * reciprocal_alpha;
- separate_rgba[2] = associated_rgba[2] * reciprocal_alpha;
- separate_rgba[3] = alpha;
- }
-</pre>
-
-
-<p>For more detils see <a
href='https://gitlab.gnome.org/GNOME/babl/commit/a4d607843d3cab18745d547fc8a46dec51dcea5e'>the commit message
of the most recent refinement</a> as well as <a
href='https://www.patreon.com/posts/premultiplied-in-21014115'>blog post with further background</a>.</p>
-
-
- <a name='CMYK'></a>
- <h2>CMYK</h2>
-
- <p>CMYK handling is done using babl-spaces created with ICC profiles
-containing CMYK profiles. BablSpaces for these ICC profiles handle color conversions using lcms2 - or if
compiled without lcms2 support a naive profile independent fallback.</p>
- <p>When a babl space derived from a CMYK ICC profile is used to instantiate
-RGB formats, the resulting formats are using the default/NULL space for
-primaries and TRCs.</p>
-
- <p>The CMYK formats that use lcms2 for color interchange with the rest of
-babl are the following, which are available for all data types, u8, u16, half
-and float:</p>
- <dl>
- <dt>CMYK</dt><dd>Cyan Magenta Yellow Key, with 0 being white and 1.0 full ink coverage.</dd>
- <dt>CMYKA</dt><dd>as previous, with non-associated alpha channel</dd>
- <dt>CaMaYaKaA</dt><dd>as previous but premultiplied/associated alpha</dd>
- <dt>cmyk</dt><dd>inverted CMYK, where 0.0 is full ink coverage and 1.0 is none</dd>
- <dt>cmykA</dt><dd>as previous, with non-associated alpha channel</dd>
- <dt>camayakaA</dt><dd>as previous but premultiplied/associated alpha</dd>
- </dl>
<a name='Vocabulary'></a>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
